feat(codegen-ts-tanstack): FR-017 Tier 3 #1 — polymorphic + per-subtype TanStack hooks

A TPH discriminator base now emits one `.hooks.ts` carrying:
- A query-key factory with both polymorphic and per-subtype scopes (all keys
  rooted at <base>Keys.all(), so a per-subtype mutation invalidates both the
  per-subtype and the polymorphic lists).
- Polymorphic reads use<Base> / use<Plural> returning the discriminated union.
  No polymorphic create/update/delete (you can't instantiate an abstract base).
- Per concrete subtype: use<Plural> / use<Sub> (scoped to the value's REST
  sub-path /<base>/<value>) + useCreate/useUpdate/useDelete<Sub>. Create input
  is Omit<<Sub>, "<disc>"> (the discriminator is injected server-side, Tier 2);
  update is Partial of that. Mutations invalidate <base>Keys.all().

The tanstack-query generator filter skips TPH subtypes (their hooks live in the
base file). Exposed isTphDiscriminatorBase / tphConcreteSubtypes / isTphSubtype
from @metaobjectsdev/codegen-ts for the per-framework packages.

Tests: tph-hooks.test.ts (filter-skip + polymorphic + per-subtype content);
tanstack-query regression green. (Targeted suite 28/28; the full-suite reds
under the concurrent machine-load spike were all TimeoutError, none in TPH.)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

server/typescript/packages/codegen-ts-tanstack/src/tanstack-query.ts

@@ -1,5 +1,5 @@
 import type { MetaObject } from "@metaobjectsdev/metadata";
-import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, emitsInstanceArtifacts } from "@metaobjectsdev/codegen-ts";
+import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, emitsInstanceArtifacts, isTphSubtype } from "@metaobjectsdev/codegen-ts";
 import { renderHooksFile } from "./templates/hooks-file.js";
 
 export interface TanstackQueryOpts {
@@ -22,7 +22,9 @@ export const tanstackQuery = function tanstackQuery(opts?: TanstackQueryOpts): G
     // they contribute shape via inheritance only and have no instance to query),
     // the metadata opt-out, and the optional user filter. Projections still pass
     // here and get read-only hooks via renderHooksFile's isProjection branch.
-    filter: (e: MetaObject) => emitsInstanceArtifacts(e) && e.ownAttr("emitTanstack") !== false && userFilter(e),
+    // FR-017 Tier 3: TPH subtypes get no standalone hooks file — their per-subtype
+    // hooks live in the discriminator base's hooks file (polymorphic + per-subtype).
+    filter: (e: MetaObject) => emitsInstanceArtifacts(e) && e.ownAttr("emitTanstack") !== false && !isTphSubtype(e) && userFilter(e),
     generate: perEntity(async (entity, ctx) => {
       if (!ctx.renderContext) {
         throw new Error(

server/typescript/packages/codegen-ts-tanstack/src/templates/hooks-file.ts

@@ -1,7 +1,18 @@
 import { code, imp, joinCode, type Code } from "ts-poet";
-import type { MetaObject } from "@metaobjectsdev/metadata";
+import {
+  type MetaObject,
+  OBJECT_ATTR_DISCRIMINATOR,
+  OBJECT_ATTR_DISCRIMINATOR_VALUE,
+} from "@metaobjectsdev/metadata";
 import type { RenderContext } from "@metaobjectsdev/codegen-ts";
-import { GENERATED_HEADER, isProjection, pluralize, entityModuleSpecifier } from "@metaobjectsdev/codegen-ts";
+import {
+  GENERATED_HEADER,
+  isProjection,
+  pluralize,
+  entityModuleSpecifier,
+  isTphDiscriminatorBase,
+  tphConcreteSubtypes,
+} from "@metaobjectsdev/codegen-ts";
 
 /**
  * Render <Entity>.hooks.ts — query-key factory + 2 query hooks + (for non-projections) 3 mutation hooks.
@@ -29,6 +40,11 @@ export function renderHooksFile(entity: MetaObject, ctx: RenderContext): string
     entity.name,
     ctx.extStyle,
   );
+  // FR-017 Tier 3: a TPH discriminator base gets a polymorphic + per-subtype
+  // hooks file (the subtype entities are filtered out of this generator).
+  if (isTphDiscriminatorBase(entity, ctx.loadedRoot)) {
+    return renderTphHooksFile(entity, ctx, entityModule);
+  }
   if (isProjection(entity)) {
     return renderReadOnlyHooksFile(entity, entityModule);
   }
@@ -233,3 +249,177 @@ export function useDelete${entityName}(
     `// Source metadata: ${entityName} (${entity.fqn()})\n`;
   return header + entityImports.toString() + body.toString();
 }
+
+// ---------------------------------------------------------------------------
+// FR-017 Tier 3 — TPH discriminator base: polymorphic + per-subtype hooks.
+// ---------------------------------------------------------------------------
+
+function renderTphHooksFile(base: MetaObject, ctx: RenderContext, baseModule: string): string {
+  const baseName = base.name;
+  const lcBase = baseName.charAt(0).toLowerCase() + baseName.slice(1);
+  const keysVar = `${lcBase}Keys`;
+  const discField = base.ownAttr(OBJECT_ATTR_DISCRIMINATOR) as string;
+
+  const useQuerySym = imp("useQuery@@tanstack/react-query");
+  const useMutationSym = imp("useMutation@@tanstack/react-query");
+  const useQueryClientSym = imp("useQueryClient@@tanstack/react-query");
+  const useQueryOptionsSym = imp("t:UseQueryOptions@@tanstack/react-query");
+  const useMutationOptionsSym = imp("t:UseMutationOptions@@tanstack/react-query");
+  const useQueryResultSym = imp("t:UseQueryResult@@tanstack/react-query");
+  const useMutationResultSym = imp("t:UseMutationResult@@tanstack/react-query");
+  const useEntityFetcherSym = imp("useEntityFetcher@@metaobjectsdev/tanstack");
+  const buildFilterQsSym = imp("buildFilterQs@@metaobjectsdev/runtime-web");
+
+  const subtypes = tphConcreteSubtypes(base, ctx.loadedRoot);
+
+  // `${baseName}` imports BOTH the constants value (for $path/$apiPrefix) and the
+  // discriminated-union type (declaration merge). Each subtype contributes its
+  // interface type.
+  const subImportLines = subtypes
+    .map((s) => {
+      const m = entityModuleSpecifier(ctx.selfTarget, ctx.entityModuleTarget, s.package, s.name, ctx.extStyle);
+      return `import { type ${s.name} } from ${JSON.stringify(m)};`;
+    })
+    .join("\n");
+  const entityImports: Code = code`
+import { ${baseName}, type ${baseName}Filter } from ${JSON.stringify(baseModule)};
+${subImportLines}
+`;
+
+  const queryKeys: Code = code`
+export const ${keysVar} = {
+  all:           () => [${JSON.stringify(lcBase)}] as const,
+  lists:         () => [...${keysVar}.all(), "list"] as const,
+  list:          (filter?: ${baseName}Filter) => [...${keysVar}.lists(), filter ?? {}] as const,
+  details:       () => [...${keysVar}.all(), "detail"] as const,
+  detail:        (id: number) => [...${keysVar}.details(), id] as const,
+  subtypeLists:  (sub: string) => [...${keysVar}.all(), sub, "list"] as const,
+  subtypeList:   (sub: string, filter?: ${baseName}Filter) => [...${keysVar}.subtypeLists(sub), filter ?? {}] as const,
+  subtypeDetails:(sub: string) => [...${keysVar}.all(), sub, "detail"] as const,
+  subtypeDetail: (sub: string, id: number) => [...${keysVar}.subtypeDetails(sub), id] as const,
+};
+`;
+
+  // Polymorphic reads — return the discriminated union.
+  const polymorphic: Code = code`
+export function use${baseName}(
+  id: number,
+  opts?: Omit<${useQueryOptionsSym}<${baseName}>, "queryKey" | "queryFn">,
+): ${useQueryResultSym}<${baseName}> {
+  const fetcher = ${useEntityFetcherSym}();
+  return ${useQuerySym}<${baseName}>({
+    queryKey: ${keysVar}.detail(id),
+    queryFn: () => fetcher<${baseName}>(\`\${${baseName}.$apiPrefix}\${${baseName}.$path}/\${id}\`),
+    ...opts,
+  });
+}
+
+export function use${pluralize(baseName)}(
+  filter?: ${baseName}Filter,
+  opts?: Omit<${useQueryOptionsSym}<${baseName}[]>, "queryKey" | "queryFn">,
+): ${useQueryResultSym}<${baseName}[]> {
+  const fetcher = ${useEntityFetcherSym}();
+  const qs = filter ? "?" + ${buildFilterQsSym}(filter as Record<string, unknown>) : "";
+  return ${useQuerySym}<${baseName}[]>({
+    queryKey: ${keysVar}.list(filter),
+    queryFn: () => fetcher<${baseName}[]>(\`\${${baseName}.$apiPrefix}\${${baseName}.$path}\${qs}\`),
+    ...opts,
+  });
+}
+`;
+
+  // Per-subtype hooks — scoped to each discriminator value's REST sub-path.
+  const subtypeSections: Code[] = subtypes.map((sub) => {
+    const value = sub.ownAttr(OBJECT_ATTR_DISCRIMINATOR_VALUE) as string;
+    const seg = value.toLowerCase();
+    const valueLit = JSON.stringify(value);
+    const createInput = `Omit<${sub.name}, ${JSON.stringify(discField)}>`;
+    const updateInput = `Partial<${createInput}>`;
+    const subPath = `\`\${${baseName}.$apiPrefix}\${${baseName}.$path}/${seg}\``;
+    return code`
+export function use${pluralize(sub.name)}(
+  filter?: ${baseName}Filter,
+  opts?: Omit<${useQueryOptionsSym}<${sub.name}[]>, "queryKey" | "queryFn">,
+): ${useQueryResultSym}<${sub.name}[]> {
+  const fetcher = ${useEntityFetcherSym}();
+  const qs = filter ? "?" + ${buildFilterQsSym}(filter as Record<string, unknown>) : "";
+  return ${useQuerySym}<${sub.name}[]>({
+    queryKey: ${keysVar}.subtypeList(${valueLit}, filter),
+    queryFn: () => fetcher<${sub.name}[]>(\`\${${baseName}.$apiPrefix}\${${baseName}.$path}/${seg}\${qs}\`),
+    ...opts,
+  });
+}
+
+export function use${sub.name}(
+  id: number,
+  opts?: Omit<${useQueryOptionsSym}<${sub.name}>, "queryKey" | "queryFn">,
+): ${useQueryResultSym}<${sub.name}> {
+  const fetcher = ${useEntityFetcherSym}();
+  return ${useQuerySym}<${sub.name}>({
+    queryKey: ${keysVar}.subtypeDetail(${valueLit}, id),
+    queryFn: () => fetcher<${sub.name}>(\`\${${baseName}.$apiPrefix}\${${baseName}.$path}/${seg}/\${id}\`),
+    ...opts,
+  });
+}
+
+export function useCreate${sub.name}(
+  opts?: Omit<${useMutationOptionsSym}<${sub.name}, Error, ${createInput}>, "mutationFn">,
+): ${useMutationResultSym}<${sub.name}, Error, ${createInput}> {
+  const fetcher = ${useEntityFetcherSym}();
+  const qc = ${useQueryClientSym}();
+  return ${useMutationSym}<${sub.name}, Error, ${createInput}>({
+    mutationFn: (input) => fetcher<${sub.name}>(${subPath}, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+    }),
+    ...opts,
+    onSuccess: (...args) => {
+      qc.invalidateQueries({ queryKey: ${keysVar}.all() });
+      opts?.onSuccess?.(...args);
+    },
+  });
+}
+
+export function useUpdate${sub.name}(
+  opts?: Omit<${useMutationOptionsSym}<${sub.name}, Error, { id: number; input: ${updateInput} }>, "mutationFn">,
+): ${useMutationResultSym}<${sub.name}, Error, { id: number; input: ${updateInput} }> {
+  const fetcher = ${useEntityFetcherSym}();
+  const qc = ${useQueryClientSym}();
+  return ${useMutationSym}({
+    mutationFn: ({ id, input }) => fetcher<${sub.name}>(\`\${${baseName}.$apiPrefix}\${${baseName}.$path}/${seg}/\${id}\`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+    }),
+    ...opts,
+    onSuccess: (...args) => {
+      qc.invalidateQueries({ queryKey: ${keysVar}.all() });
+      opts?.onSuccess?.(...args);
+    },
+  });
+}
+
+export function useDelete${sub.name}(
+  opts?: Omit<${useMutationOptionsSym}<void, Error, number>, "mutationFn">,
+): ${useMutationResultSym}<void, Error, number> {
+  const fetcher = ${useEntityFetcherSym}();
+  const qc = ${useQueryClientSym}();
+  return ${useMutationSym}({
+    mutationFn: (id) => fetcher<void>(\`\${${baseName}.$apiPrefix}\${${baseName}.$path}/${seg}/\${id}\`, { method: "DELETE" }),
+    ...opts,
+    onSuccess: (...args) => {
+      qc.invalidateQueries({ queryKey: ${keysVar}.all() });
+      opts?.onSuccess?.(...args);
+    },
+  });
+}
+`;
+  });
+
+  const body: Code = joinCode([queryKeys, polymorphic, ...subtypeSections], { on: "\n" });
+  const header =
+    `// ${GENERATED_HEADER}-tanstack — DO NOT EDIT.\n` +
+    `// Source metadata: ${baseName} (${base.fqn()}) — TPH discriminator base\n`;
+  return header + entityImports.toString() + body.toString();
+}

server/typescript/packages/codegen-ts-tanstack/test/tph-hooks.test.ts

@@ -0,0 +1,118 @@
+// FR-017 Tier 3 — TanStack hooks for a TPH discriminator base.
+//
+// The base entity's hooks file carries polymorphic reads (useAuth / useAuths
+// returning the union) plus a full per-subtype hook set (list / get / create /
+// update / delete) targeting the per-subtype REST sub-paths. Subtype entities
+// get NO standalone hooks file.
+
+import { describe, test, expect } from "bun:test";
+import {
+  MetaDataLoader,
+  InMemoryStringSource,
+  type MetaObject,
+  type MetaRoot,
+} from "@metaobjectsdev/metadata";
+import { tanstackQuery } from "../src/tanstack-query.js";
+import { renderHooksFile } from "../src/templates/hooks-file.js";
+import { makeRenderContext, buildPkMap, buildRelationMap } from "@metaobjectsdev/codegen-ts";
+
+async function loadTph(): Promise<{ root: MetaRoot; base: MetaObject; bridge: MetaObject }> {
+  const loader = new MetaDataLoader();
+  const { root, errors } = await loader.load([
+    new InMemoryStringSource(
+      JSON.stringify({
+        "metadata.root": {
+          package: "demo",
+          children: [
+            {
+              "object.entity": {
+                name: "Auth",
+                "@discriminator": "type",
+                children: [
+                  { "source.rdb": { "@table": "auths" } },
+                  { "field.enum": { name: "type", "@values": ["Bridge", "Copay"] } },
+                  { "field.long": { name: "id" } },
+                  { "identity.primary": { "@fields": "id", "@generation": "increment" } },
+                ],
+              },
+            },
+            {
+              "object.entity": {
+                name: "BridgeAuth",
+                extends: "Auth",
+                "@discriminatorValue": "Bridge",
+                children: [{ "field.int": { name: "quantity" } }],
+              },
+            },
+            {
+              "object.entity": {
+                name: "CopayAuth",
+                extends: "Auth",
+                "@discriminatorValue": "Copay",
+                children: [
+                  { "field.decimal": { name: "copayAmount", "@precision": 10, "@scale": 2 } },
+                ],
+              },
+            },
+          ],
+        },
+      }),
+      { id: "auth.json" },
+    ),
+  ]);
+  if (errors.length > 0) throw new Error(errors.map((e) => e.message).join("; "));
+  const base = root.objects().find((o) => o.name === "Auth")! as MetaObject;
+  const bridge = root.objects().find((o) => o.name === "BridgeAuth")! as MetaObject;
+  return { root, base, bridge };
+}
+
+function ctxFor(root: MetaRoot) {
+  return makeRenderContext({
+    dialect: "postgres",
+    loadedRoot: root,
+    outDir: "/x",
+    dbImport: "../db",
+    extStyle: "none",
+    pkMap: buildPkMap(root),
+    relationMap: buildRelationMap(root),
+  });
+}
+
+describe("FR-017 Tier 3 — TPH TanStack hooks", () => {
+  test("generator filter skips TPH subtypes", async () => {
+    const { base, bridge } = await loadTph();
+    const gen = tanstackQuery();
+    expect(gen.filter!(bridge)).toBe(false);
+    expect(gen.filter!(base)).toBe(true);
+  });
+
+  test("base hooks file emits polymorphic reads returning the union, no base create", async () => {
+    const { root, base } = await loadTph();
+    const out = renderHooksFile(base, ctxFor(root));
+    expect(out).toContain("export const authKeys");
+    expect(out).toContain("export function useAuth(");
+    expect(out).toContain("export function useAuths(");
+    // Polymorphic reads return the Auth union.
+    expect(out).toContain("UseQueryResult<Auth>");
+    expect(out).toContain("UseQueryResult<Auth[]>");
+    // No polymorphic create/update/delete on the abstract-shaped base.
+    expect(out).not.toContain("export function useCreateAuth(");
+  });
+
+  test("base hooks file carries per-subtype hooks against the sub-paths", async () => {
+    const { root, base } = await loadTph();
+    const out = renderHooksFile(base, ctxFor(root));
+    expect(out).toContain("export function useBridgeAuths(");
+    expect(out).toContain("export function useBridgeAuth(");
+    expect(out).toContain("export function useCreateBridgeAuth(");
+    expect(out).toContain("export function useUpdateBridgeAuth(");
+    expect(out).toContain("export function useDeleteBridgeAuth(");
+    // Per-subtype CopayAuth too.
+    expect(out).toContain("export function useCreateCopayAuth(");
+    // Sub-path derived from the lowercased discriminator value.
+    expect(out).toContain("/bridge");
+    expect(out).toContain("/copay");
+    // Create input omits the discriminator.
+    expect(out).toContain('Omit<BridgeAuth, "type">');
+  });
+});

server/typescript/packages/codegen-ts/src/index.ts

@@ -61,6 +61,10 @@ export type { DocPageNode, DocPagePlacement } from "./docs-paths.js";
 
 export { isProjection, isWriteThrough } from "./projection/projection-detector.js";
 export { isAbstract, emitsInstanceArtifacts, emitsWriteArtifacts } from "./instance-artifacts.js";
+// FR-017 TPH helpers — used by the per-framework codegen packages (tanstack,
+// react) to dispatch polymorphic/per-subtype emission and skip subtype files.
+export { isTphDiscriminatorBase, tphConcreteSubtypes, collectTphSubtypeFields } from "./templates/tph-discriminator.js";
+export { isTphSubtype } from "./templates/zod-validators.js";
 export { extractViewSpec } from "./projection/extract-view-spec.js";
 export type { ExtractContext } from "./projection/extract-view-spec.js";
 export { emitViewDdl } from "./projection/view-ddl-emit.js";