Skip to content

Commit 52d76f1

Browse files
claudeclaude
committed
feat(codegen-ts): reverse navigation via explicit FK finders (ADR-0038)
Implement the TS reference for ADR-0038 / ADR-0036 Wave 4: generate reverse 1:N navigation as explicit, typed FK query methods instead of lazy Drizzle relations() collections, and fix the same-pair reverse-nav collision bug. For each FK an entity E holds (identity.reference), E's queries module now gains a finder pair, named by the FK FIELD (PascalCased, trailing `Id` dropped) so it is unique within E by construction: find<EPlural>By<FkField>(value) → SELECT … WHERE fk = ? (single, indexed) find<EPlural>By<FkField>In(values) → SELECT … WHERE fk IN (…) (batched, anti-N+1) The same-pair case (GameSession with 3 FKs to Scene) yields 3 distinct finders — findGameSessionsByCurrentScene / …ByLastOpeningNarrativeScene / …ByTransitioningFromScene — no collision. Both finders are plain, framework-free, single-query reads returning E[]. Collision fix: the lazy reverse many() entries in relation-resolver (named from the SOURCE entity, so two FKs same source→target silently overwrote) are REMOVED — the explicit finders are the primitive per ADR-0038. Forward one() relations and M:N many(junction) navigation are unchanged. - naming.ts: reverseFinderFnName / reverseFinderInFnName / reverseFinderFkSegment (the cross-port naming SSOT). - queries.ts: reverseFksFor + renderReverseFinderFns; wired into queries-file. - reference/queries.ts (ADR-0034 scaffold-and-own copy) kept byte-identical. - New fixtures/conformance/reverse-finders-same-pair (3 FKs to Scene + a string-PK FK to Player) gates the metadata cross-port; reverse-finders.test.ts asserts the generated finder names incl. the same-pair case. - Regenerated golden + package-layout snapshots (additive finders; reverse many() blocks dropped). Registry-conformance unaffected (no new vocab). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GF9xLEQZaPus5Y6opk398n
1 parent 42852a7 commit 52d76f1

39 files changed

Lines changed: 935 additions & 109 deletions

‎fixtures/conformance/reverse-finders-same-pair/expected.json‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
{
2+
"metadata.root": {
3+
"package": "game",
4+
"children": [
5+
{
6+
"object.entity": {
7+
"name": "Scene",
8+
"children": [
9+
{
10+
"source.rdb": {
11+
"@table": "scenes"
12+
}
13+
},
14+
{
15+
"field.long": {
16+
"name": "id"
17+
}
18+
},
19+
{
20+
"field.string": {
21+
"name": "title"
22+
}
23+
},
24+
{
25+
"identity.primary": {
26+
"name": "id",
27+
"@fields": [
28+
"id"
29+
],
30+
"@generation": "increment"
31+
}
32+
}
33+
]
34+
}
35+
},
36+
{
37+
"object.entity": {
38+
"name": "Player",
39+
"children": [
40+
{
41+
"source.rdb": {
42+
"@table": "players"
43+
}
44+
},
45+
{
46+
"field.string": {
47+
"name": "id"
48+
}
49+
},
50+
{
51+
"field.string": {
52+
"name": "name"
53+
}
54+
},
55+
{
56+
"identity.primary": {
57+
"name": "id",
58+
"@fields": [
59+
"id"
60+
],
61+
"@generation": "assigned"
62+
}
63+
}
64+
]
65+
}
66+
},
67+
{
68+
"object.entity": {
69+
"name": "GameSession",
70+
"children": [
71+
{
72+
"source.rdb": {
73+
"@table": "game_sessions"
74+
}
75+
},
76+
{
77+
"field.long": {
78+
"name": "id"
79+
}
80+
},
81+
{
82+
"field.long": {
83+
"name": "currentSceneId"
84+
}
85+
},
86+
{
87+
"field.long": {
88+
"name": "lastOpeningNarrativeSceneId"
89+
}
90+
},
91+
{
92+
"field.long": {
93+
"name": "transitioningFromSceneId"
94+
}
95+
},
96+
{
97+
"field.string": {
98+
"name": "playerId"
99+
}
100+
},
101+
{
102+
"relationship.association": {
103+
"name": "currentScene",
104+
"@cardinality": "one",
105+
"@objectRef": "Scene"
106+
}
107+
},
108+
{
109+
"relationship.association": {
110+
"name": "player",
111+
"@cardinality": "one",
112+
"@objectRef": "Player"
113+
}
114+
},
115+
{
116+
"identity.primary": {
117+
"name": "id",
118+
"@fields": [
119+
"id"
120+
],
121+
"@generation": "increment"
122+
}
123+
},
124+
{
125+
"identity.reference": {
126+
"name": "fkCurrentScene",
127+
"@fields": [
128+
"currentSceneId"
129+
],
130+
"@references": "Scene"
131+
}
132+
},
133+
{
134+
"identity.reference": {
135+
"name": "fkLastOpeningNarrativeScene",
136+
"@fields": [
137+
"lastOpeningNarrativeSceneId"
138+
],
139+
"@references": "Scene"
140+
}
141+
},
142+
{
143+
"identity.reference": {
144+
"name": "fkTransitioningFromScene",
145+
"@fields": [
146+
"transitioningFromSceneId"
147+
],
148+
"@references": "Scene"
149+
}
150+
},
151+
{
152+
"identity.reference": {
153+
"name": "fkPlayer",
154+
"@fields": [
155+
"playerId"
156+
],
157+
"@references": "Player"
158+
}
159+
}
160+
]
161+
}
162+
}
163+
]
164+
}
165+
}
166+

‎fixtures/conformance/reverse-finders-same-pair/input/meta.game.json‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
{
2+
"metadata.root": {
3+
"package": "game",
4+
"children": [
5+
{
6+
"object.entity": {
7+
"name": "Scene",
8+
"children": [
9+
{ "source.rdb": { "@table": "scenes" } },
10+
{ "field.long": { "name": "id" } },
11+
{ "field.string": { "name": "title" } },
12+
{ "identity.primary": { "name": "id", "@fields": "id", "@generation": "increment" } }
13+
]
14+
}
15+
},
16+
{
17+
"object.entity": {
18+
"name": "Player",
19+
"children": [
20+
{ "source.rdb": { "@table": "players" } },
21+
{ "field.string": { "name": "id" } },
22+
{ "field.string": { "name": "name" } },
23+
{ "identity.primary": { "name": "id", "@fields": "id", "@generation": "assigned" } }
24+
]
25+
}
26+
},
27+
{
28+
"object.entity": {
29+
"name": "GameSession",
30+
"children": [
31+
{ "source.rdb": { "@table": "game_sessions" } },
32+
{ "field.long": { "name": "id" } },
33+
{ "field.long": { "name": "currentSceneId" } },
34+
{ "field.long": { "name": "lastOpeningNarrativeSceneId" } },
35+
{ "field.long": { "name": "transitioningFromSceneId" } },
36+
{ "field.string": { "name": "playerId" } },
37+
{ "relationship.association": { "name": "currentScene", "@cardinality": "one", "@objectRef": "Scene" } },
38+
{ "relationship.association": { "name": "player", "@cardinality": "one", "@objectRef": "Player" } },
39+
{ "identity.primary": { "name": "id", "@fields": "id", "@generation": "increment" } },
40+
{ "identity.reference": { "name": "fkCurrentScene", "@fields": "currentSceneId", "@references": "Scene" } },
41+
{ "identity.reference": { "name": "fkLastOpeningNarrativeScene", "@fields": "lastOpeningNarrativeSceneId", "@references": "Scene" } },
42+
{ "identity.reference": { "name": "fkTransitioningFromScene", "@fields": "transitioningFromSceneId", "@references": "Scene" } },
43+
{ "identity.reference": { "name": "fkPlayer", "@fields": "playerId", "@references": "Player" } }
44+
]
45+
}
46+
}
47+
]
48+
}
49+
}

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,8 @@ export {
108108
renderCreateFn,
109109
renderUpdateFn,
110110
renderDeleteByIdFn,
111+
renderReverseFinderFns,
112+
reverseFksFor,
111113
getPkInfo,
112114
} from "./templates/queries.js";
113115

‎server/typescript/packages/codegen-ts/src/naming.ts‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,57 @@ export function deleteByIdFnName(entityName: string): string {
121121
return `delete${entityName}ById`;
122122
}
123123

124+
// ---------------------------------------------------------------------------
125+
// ADR-0038 — reverse-relationship navigation as explicit FK finders.
126+
//
127+
// For each FK relationship (entity `E` references entity `T` via an
128+
// `identity.reference` FK field), `E`'s query surface gains a finder returning
129+
// the `E` rows matching a given `T` id. Two variants: a single-value finder and
130+
// a batched (anti-N+1) `…In` finder.
131+
//
132+
// CANONICAL NAMING CONVENTION (the cross-port contract — every port replicates
133+
// this spelling exactly):
134+
//
135+
// find<EPlural>By<FkField>(value) → SELECT … FROM E WHERE <fkColumn> = ?
136+
// find<EPlural>By<FkField>In(values) → SELECT … FROM E WHERE <fkColumn> IN (…)
137+
//
138+
// where:
139+
// - <EPlural> is the source entity name pluralized, PascalCase
140+
// (`GameSession` → `GameSessions`) — the same spelling `list<Plural>` uses.
141+
// - <FkField> is the FK FIELD name (NOT the relationship/navigation name and
142+
// NOT the raw column), PascalCased, with a single trailing `Id` dropped if
143+
// present. The FK field name is unique within an entity, so the finder name
144+
// is unique by construction — this is what dissolves the same-pair collision
145+
// and removes any need for a naming attribute.
146+
//
147+
// SAME-PAIR EXAMPLE (GameSession has THREE FKs to Scene):
148+
// FK field `currentSceneId` → findGameSessionsByCurrentScene
149+
// FK field `lastOpeningNarrativeSceneId` → findGameSessionsByLastOpeningNarrativeScene
150+
// FK field `transitioningFromSceneId` → findGameSessionsByTransitioningFromScene
151+
// Three distinct finders — no collision.
152+
// ---------------------------------------------------------------------------
153+
154+
/**
155+
* Lower an FK field name to the `<FkField>` segment of a reverse finder name:
156+
* PascalCase the field, then drop a single trailing `Id` if present.
157+
* E.g. `currentSceneId` → `CurrentScene`, `authorId` → `Author`, `scene` → `Scene`.
158+
*/
159+
export function reverseFinderFkSegment(fkFieldName: string): string {
160+
const pascal = toPascalCase(toCamelCase(fkFieldName));
161+
// Drop a single trailing "Id" (but not a bare "Id" — that would yield "").
162+
return pascal.length > 2 && pascal.endsWith("Id") ? pascal.slice(0, -2) : pascal;
163+
}
164+
165+
/** Generated reverse single-value finder name: `find<EPlural>By<FkField>`. */
166+
export function reverseFinderFnName(sourceEntityName: string, fkFieldName: string): string {
167+
return `find${pluralize(sourceEntityName)}By${reverseFinderFkSegment(fkFieldName)}`;
168+
}
169+
170+
/** Generated reverse batched finder name: `find<EPlural>By<FkField>In`. */
171+
export function reverseFinderInFnName(sourceEntityName: string, fkFieldName: string): string {
172+
return `${reverseFinderFnName(sourceEntityName, fkFieldName)}In`;
173+
}
174+
124175
/**
125176
* Generated Fastify route-registrar name: camelCase `<entity>Routes`. The routes
126177
* generator (templates/routes-file.ts) emits a single exported

‎server/typescript/packages/codegen-ts/src/reference/queries.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@ import {
2727
renderCreateFn,
2828
renderUpdateFn,
2929
renderDeleteByIdFn,
30+
renderReverseFinderFns,
31+
reverseFksFor,
3032
isTphDiscriminatorBase,
3133
isProjection,
3234
isTphSubtype,
@@ -80,6 +82,13 @@ import { ${varName}, type ${entityName}, ${entityName}InsertSchema } from ${JSON
8082
renderDeleteByIdFn(obj, ctx),
8183
];
8284

85+
// ADR-0038 — reverse-relationship navigation as explicit FK finders. One
86+
// find<Plural>By<FkField> (+ batched …In) per FK this entity holds. OWNED:
87+
// drop this loop if you don't want reverse finders.
88+
for (const fk of reverseFksFor(obj)) {
89+
sections.push(renderReverseFinderFns(obj, fk, ctx));
90+
}
91+
8392
const body = joinCode(sections, { on: "\n" }).toString();
8493
const header =
8594
`// ${GENERATED_HEADER} — DO NOT EDIT.\n` +

‎server/typescript/packages/codegen-ts/src/relation-resolver.ts‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -104,11 +104,14 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
104104
fkField,
105105
targetPkField: "id",
106106
});
107-
ensure(targetEntity).push({
108-
name: variableNameFromEntity(obj.name),
109-
cardinality: "many",
110-
targetEntity: obj.name,
111-
});
107+
// ADR-0038: do NOT register a reverse lazy `many()` on the target. Those
108+
// entries were named after the SOURCE entity (`variableNameFromEntity(obj)`),
109+
// so two relationships from the same source to the same target produced
110+
// duplicate object-literal keys and silently overwrote each other (the
111+
// same-pair collision). Reverse 1:N navigation is now provided as explicit,
112+
// unique-by-FK-field finders in the source's queries module
113+
// (find<SourcePlural>By<FkField>), which are framework-free and non-N+1.
114+
// The forward one() relation above stays.
112115
}
113116
}
114117

‎server/typescript/packages/codegen-ts/src/templates/queries-file.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ import {
1515
renderCreateFn,
1616
renderUpdateFn,
1717
renderDeleteByIdFn,
18+
renderReverseFinderFns,
19+
reverseFksFor,
1820
getPkInfo,
1921
} from "./queries.js";
2022
import { pluralize, findByIdFnName, listFnName } from "../naming.js";
@@ -90,6 +92,16 @@ import { ${varName}, type ${entityName}, ${entityName}InsertSchema } from ${JSON
9092
renderDeleteByIdFn(obj, ctx),
9193
];
9294

95+
// ADR-0038 — reverse-relationship navigation via explicit FK finders. Each FK
96+
// this entity holds (`identity.reference`) gets `find<Plural>By<FkField>` +
97+
// its batched `…In` sibling, so the referenced entity can navigate back to its
98+
// referencing rows with a plain, single-query, framework-free read. FK field
99+
// names are unique within the entity, so the finder names never collide — the
100+
// same-pair case (3 FKs to one target) yields 3 distinct finders.
101+
for (const fk of reverseFksFor(obj)) {
102+
sections.push(renderReverseFinderFns(obj, fk, ctx));
103+
}
104+
93105
// Render ts-poet body first, then prepend the @generated header so it lands
94106
// at line 1 ahead of any imports.
95107
const body = joinCode(sections, { on: "\n" }).toString();

0 commit comments

Comments
 (0)