@prisma-next/framework-components 0.13.0-dev.25 → 0.13.0-dev.27

package/dist/ir.d.mts

@@ -153,13 +153,20 @@ interface EntityCoordinate {
  * value, yielded as {@link EntityCoordinate} tuples with
  * `plane: 'storage'` (the parameter type binds the plane).
  *
- * Iterates each namespace's `entries` slot maps structurally. Skips
+ * Iterates each namespace's `entries` kind maps structurally. Skips
  * non-object `entries`; `id` and `kind` are not walked (`kind` is
  * non-enumerable on concretions). For every entity-kind key under
  * `entries` whose value is a non-null object, yields one coordinate per
- * entity name in that map. No family-specific slot vocabulary is required.
+ * entity name in that map. No family-specific kind vocabulary is required.
  */
 declare function elementCoordinates(storage: Pick<StorageBase, 'namespaces'>): Generator<EntityCoordinate>;
+/**
+ * Looks up a single entity in a `Storage`-shaped value by its full coordinate.
+ * Returns `undefined` if the namespace, entity kind, or entity name is absent.
+ * The type parameter is a caller assertion — the walk itself is structural
+ * and cannot verify the entity's shape.
+ */
+declare function entityAt<T = unknown>(storage: Pick<StorageBase, 'namespaces'>, coord: Pick<EntityCoordinate, 'namespaceId' | 'entityKind' | 'entityName'>): T | undefined;
 /**
  * Framework-level promise that every Contract IR / Schema IR carries a
  * collection of namespaces keyed by namespace id. Family storage
@@ -175,7 +182,7 @@ declare function elementCoordinates(storage: Pick<StorageBase, 'namespaces'>): G
  * is honest at every layer.
  *
  * Extends `IRNode` so the framework's IR-walking surfaces (verifiers,
- * serializers) can dispatch on `Storage`-typed slots through the same
+ * serializers) can dispatch on `Storage`-typed fields through the same
  * IR-node alphabet as every other node — the structural dual already
  * holds in code (every concrete storage class extends an IR-node base);
  * the interface promotion makes the typing honest.
@@ -232,5 +239,5 @@ interface StorageType extends IRNode {
   readonly kind: string;
 }
 //#endregion
-export { type EntityCoordinate, type IRNode, IRNodeBase, type Namespace, NamespaceBase, type Storage, type StorageType, UNBOUND_NAMESPACE_ID, domainElementCoordinates, elementCoordinates, freezeNode };
+export { type EntityCoordinate, type IRNode, IRNodeBase, type Namespace, NamespaceBase, type Storage, type StorageType, UNBOUND_NAMESPACE_ID, domainElementCoordinates, elementCoordinates, entityAt, freezeNode };
 //# sourceMappingURL=ir.d.mts.map

package/dist/ir.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"ir.d.mts","names":[],"sources":["../src/ir/ir-node.ts","../src/ir/namespace.ts","../src/ir/storage.ts","../src/ir/domain.ts","../src/ir/storage-type.ts"],"mappings":";;;;;;AAyCA;;;;AACe;AAGf;;;;AACwB;AAYxB;;;;;;;;;;;;;;AAAwD;;;;AChCxD;;;;AAA0D;AAkC1D;;;;UDnBiB,MAAA;EAAA,SACN,IAAI;AAAA;AAAA,uBAGO,UAAA,YAAsB,MAAM;EAAA,kBAC9B,IAAI;AAAA;;;;;;;;;;iBAYR,UAAA,WAAqB,MAAA,EAAQ,IAAA,EAAM,CAAA,GAAI,CAAA;;;;AAjBvD;;;;AACe;AAGf;;;;AACwB;AAYxB;;;;;;;;;;;;cChCa,oBAAA;;ADgC2C;;;;AChCxD;;;;AAA0D;AAkC1D;;;;;;;;;;;;;;;;;;;;AAE2D;AAG3D;UALiB,SAAA,SAAkB,MAAA,EAAQ,gBAAA;EAAA,SAChC,IAAA;EAAA,SACA,OAAA,EAAS,QAAA,CAAS,MAAA,SAAe,QAAA,CAAS,MAAA;AAAA;AAAA,uBAG/B,aAAA,SAAsB,UAAA,YAAsB,SAAA;EAAA,kBAC9C,EAAA;EAAA,kBACA,OAAA,EAAS,QAAA,CAAS,MAAA,SAAe,QAAA,CAAS,MAAA;EAAA,kBACjC,IAAA;AAAA;;;AD3B7B;;;;AACe;AAGf;;;;AACwB;AAYxB;;;;;;AAjBA,UErBiB,gBAAA;EAAA,SACN,KAAA;EAAA,SACA,WAAA;EAAA,SACA,UAAA;EAAA,SACA,UAAA;AAAA;;;AFkC6C;;;;AChCxD;;;;AAA0D;iBCYzC,kBAAA,CACf,OAAA,EAAS,IAAA,CAAK,WAAA,kBACb,SAAA,CAAU,gBAAA;;;;;;;;;;;;;;;;;;;;ADsB8C;AAG3D;;;;;;;;;;;;;;;UCuBiB,OAAA,SAAgB,MAAA;EAAA,SACtB,UAAA,EAAY,QAAA,CAAS,MAAA,SAAe,SAAA;AAAA;;;;AFhD/C;;;;AACe;AAGf;iBGnCiB,wBAAA,CACf,MAAA,EAAQ,IAAA,CAAK,iBAAA,kBACZ,SAAA,CAAU,gBAAA;;;;;AH6Bb;;;;AACe;AAGf;;;;AACwB;AAYxB;;;;;;UItCiB,WAAA,SAAoB,MAAM;EAAA,SAChC,IAAI;AAAA"}
+{"version":3,"file":"ir.d.mts","names":[],"sources":["../src/ir/ir-node.ts","../src/ir/namespace.ts","../src/ir/storage.ts","../src/ir/domain.ts","../src/ir/storage-type.ts"],"mappings":";;;;;;AAyCA;;;;AACe;AAGf;;;;AACwB;AAYxB;;;;;;;;;;;;;;AAAwD;;;;AChCxD;;;;AAA0D;AAkC1D;;;;UDnBiB,MAAA;EAAA,SACN,IAAI;AAAA;AAAA,uBAGO,UAAA,YAAsB,MAAM;EAAA,kBAC9B,IAAI;AAAA;;;;;;;;;;iBAYR,UAAA,WAAqB,MAAA,EAAQ,IAAA,EAAM,CAAA,GAAI,CAAA;;;;AAjBvD;;;;AACe;AAGf;;;;AACwB;AAYxB;;;;;;;;;;;;cChCa,oBAAA;;ADgC2C;;;;AChCxD;;;;AAA0D;AAkC1D;;;;;;;;;;;;;;;;;;;;AAE2D;AAG3D;UALiB,SAAA,SAAkB,MAAA,EAAQ,gBAAA;EAAA,SAChC,IAAA;EAAA,SACA,OAAA,EAAS,QAAA,CAAS,MAAA,SAAe,QAAA,CAAS,MAAA;AAAA;AAAA,uBAG/B,aAAA,SAAsB,UAAA,YAAsB,SAAA;EAAA,kBAC9C,EAAA;EAAA,kBACA,OAAA,EAAS,QAAA,CAAS,MAAA,SAAe,QAAA,CAAS,MAAA;EAAA,kBACjC,IAAA;AAAA;;;AD3B7B;;;;AACe;AAGf;;;;AACwB;AAYxB;;;;;;AAjBA,UEpBiB,gBAAA;EAAA,SACN,KAAA;EAAA,SACA,WAAA;EAAA,SACA,UAAA;EAAA,SACA,UAAA;AAAA;;;AFiC6C;;;;AChCxD;;;;AAA0D;iBCazC,kBAAA,CACf,OAAA,EAAS,IAAA,CAAK,WAAA,kBACb,SAAA,CAAU,gBAAA;;;;;;;iBAuBG,QAAA,cACd,OAAA,EAAS,IAAA,CAAK,WAAA,iBACd,KAAA,EAAO,IAAA,CAAK,gBAAA,iDACX,CAAA;;;;;;;;;;;;;ADLwD;AAG3D;;;;;;;;;;;;;;;;;;;;;AAGiC;UC+ChB,OAAA,SAAgB,MAAA;EAAA,SACtB,UAAA,EAAY,QAAA,CAAS,MAAA,SAAe,SAAA;AAAA;;;;AF3E/C;;;;AACe;AAGf;iBGnCiB,wBAAA,CACf,MAAA,EAAQ,IAAA,CAAK,iBAAA,kBACZ,SAAA,CAAU,gBAAA;;;;;AH6Bb;;;;AACe;AAGf;;;;AACwB;AAYxB;;;;;;UItCiB,WAAA,SAAoB,MAAM;EAAA,SAChC,IAAI;AAAA"}

package/dist/ir.mjs

@@ -1,3 +1,4 @@
+import { blindCast } from "@prisma-next/utils/casts";
 //#region src/ir/domain.ts
 /**
 * Lazy walk over every named domain entity in a {@link ApplicationDomain},
@@ -68,19 +69,19 @@ var NamespaceBase = class extends IRNodeBase {};
 * value, yielded as {@link EntityCoordinate} tuples with
 * `plane: 'storage'` (the parameter type binds the plane).
 *
-* Iterates each namespace's `entries` slot maps structurally. Skips
+* Iterates each namespace's `entries` kind maps structurally. Skips
 * non-object `entries`; `id` and `kind` are not walked (`kind` is
 * non-enumerable on concretions). For every entity-kind key under
 * `entries` whose value is a non-null object, yields one coordinate per
-* entity name in that map. No family-specific slot vocabulary is required.
+* entity name in that map. No family-specific kind vocabulary is required.
 */
 function* elementCoordinates(storage) {
 	for (const [namespaceId, ns] of Object.entries(storage.namespaces)) {
 		const entries = ns.entries;
 		if (entries === null || typeof entries !== "object") continue;
-		for (const [entityKind, slot] of Object.entries(entries)) {
-			if (slot === null || typeof slot !== "object") continue;
-			for (const entityName of Object.keys(slot)) yield {
+		for (const [entityKind, kindMap] of Object.entries(entries)) {
+			if (kindMap === null || typeof kindMap !== "object") continue;
+			for (const entityName of Object.keys(kindMap)) yield {
 				plane: "storage",
 				namespaceId,
 				entityKind,
@@ -89,7 +90,26 @@ function* elementCoordinates(storage) {
 		}
 	}
 }
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* Looks up a single entity in a `Storage`-shaped value by its full coordinate.
+* Returns `undefined` if the namespace, entity kind, or entity name is absent.
+* The type parameter is a caller assertion — the walk itself is structural
+* and cannot verify the entity's shape.
+*/
+function entityAt(storage, coord) {
+	const ns = storage.namespaces[coord.namespaceId];
+	if (ns === void 0) return void 0;
+	const entries = ns.entries;
+	if (!isRecord(entries)) return void 0;
+	const kindMap = entries[coord.entityKind];
+	if (!isRecord(kindMap)) return void 0;
+	if (!Object.hasOwn(kindMap, coord.entityName)) return void 0;
+	return blindCast(kindMap[coord.entityName]);
+}
 //#endregion
-export { IRNodeBase, NamespaceBase, UNBOUND_NAMESPACE_ID, domainElementCoordinates, elementCoordinates, freezeNode };
+export { IRNodeBase, NamespaceBase, UNBOUND_NAMESPACE_ID, domainElementCoordinates, elementCoordinates, entityAt, freezeNode };
 
 //# sourceMappingURL=ir.mjs.map

package/dist/ir.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ir.mjs","names":[],"sources":["../src/ir/domain.ts","../src/ir/ir-node.ts","../src/ir/namespace.ts","../src/ir/storage.ts"],"sourcesContent":["import type { ApplicationDomain } from '@prisma-next/contract/types';\nimport type { EntityCoordinate } from './storage';\n\n/**\n * Lazy walk over every named domain entity in a {@link ApplicationDomain},\n * yielded as {@link EntityCoordinate} tuples with `plane: 'domain'`.\n *\n * Same structural rules as {@link elementCoordinates} over storage: skip\n * scalar `id`; each other object-valued property is an entity-kind slot.\n */\nexport function* domainElementCoordinates(\n  domain: Pick<ApplicationDomain, 'namespaces'>,\n): Generator<EntityCoordinate> {\n  for (const [namespaceId, ns] of Object.entries(domain.namespaces)) {\n    for (const [entityKind, slot] of Object.entries(ns)) {\n      if (entityKind === 'id') continue;\n      if (slot === null || typeof slot !== 'object') continue;\n      for (const entityName of Object.keys(slot)) {\n        yield { plane: 'domain', namespaceId, entityKind, entityName };\n      }\n    }\n  }\n}\n","/**\n * Framework-level IR alphabet.\n *\n * The framework's contribution to Contract IR / Schema IR is a common\n * root for the IR class hierarchy and a freeze affordance. Family\n * abstract bases (e.g. `SqlNode`, `MongoSchemaIRNode`) refine the alphabet\n * for their family shape; targets ship the concrete classes.\n *\n * `kind` is an optional discriminator on the base. Families and leaves\n * that benefit from discriminated-union dispatch declare their own\n * literal `kind` at the level that earns it — Mongo leaves carry\n * per-class literals (`readonly kind = 'mongo-collection' as const`)\n * because Mongo IR has polymorphic walkers; SQL declares a single\n * family-level `kind = 'sql'` on `SqlNode` because SQL IR has no\n * polymorphic dispatch today. No framework consumer dispatches on\n * `IRNode.kind` at the BASE type — every dispatch site narrows\n * through a union of leaves where each leaf carries a literal kind, so\n * requiring `kind` at the base would be unearned. Future leaves that\n * earn polymorphic dispatch override with a required literal at that\n * leaf (e.g. `override readonly kind = 'pack-contributed-kind' as const`).\n *\n * `IRNodeBase` carries no methods: the freeze-and-assign affordance\n * lives in the free `freezeNode` helper below. Keeping `freezeNode` out\n * of the class type means an emitted contract literal type\n * (`{ readonly kind: 'mongo-collection', ... }` or an unkeyed literal\n * like `{ nativeType, codecId, nullable }`) is structurally assignable\n * to its class type — a `protected freeze()` instance method would\n * otherwise leak into the public type surface and require the literal\n * to carry it too.\n *\n * Subclasses construct fields then call `freezeNode(this)` to seal the\n * instance. Frozen instances + plain readonly fields keep IR nodes\n * JSON-clean by construction, so `JSON.stringify(node)` produces canonical\n * JSON without a `toJSON()` method. The `ContractSerializer` SPI handles\n * round-trip from canonical JSON back to typed class instances.\n *\n * The name (`IRNode` / `IRNodeBase`) reflects the dual-hierarchy reality:\n * this base is the common root for both Contract IR and Schema IR class\n * hierarchies, not a Schema-IR-specific alphabet.\n */\n\nexport interface IRNode {\n  readonly kind?: string;\n}\n\nexport abstract class IRNodeBase implements IRNode {\n  abstract readonly kind?: string;\n}\n\n/**\n * Seal an IR class instance after its constructor has assigned all\n * fields. The free-helper form (rather than a `protected freeze()`\n * instance method) keeps the class type structurally narrow so emitted\n * contract literal types remain assignable to their class types.\n *\n * The helper name stays `freezeNode` — it operates on IR nodes\n * regardless of root naming.\n */\nexport function freezeNode<T extends IRNode>(node: T): T {\n  Object.freeze(node);\n  return node;\n}\n","import type { StorageNamespace } from '@prisma-next/contract/types';\nimport { type IRNode, IRNodeBase } from './ir-node';\n\n/**\n * Reserved sentinel namespace id for the late-bound storage slot —\n * the slot whose binding the target resolves at connection time\n * rather than at authoring time. Postgres uses it for `search_path`\n * late binding; SQLite uses it for the trivial singleton; Mongo uses\n * it for the connection's `db` binding.\n *\n * Materialised target-side as a singleton subclass of the target's\n * `NamespaceBase` concretion that overrides the namespace's\n * qualifier-emission methods to elide the prefix entirely. Call sites\n * stay polymorphic and never branch on `id === UNBOUND_NAMESPACE_ID`\n * — the singleton's overrides drop the qualifier so emitted SQL / Mongo\n * commands look unqualified.\n *\n * The double-underscore decoration marks the id as a framework-reserved\n * coordinate when it appears in a JSON envelope (cold-read-as-reserved\n * — no realistic collision with user-declared namespace names).\n *\n * Encoded as an exported const (rather than scattered string literals)\n * so the sentinel-id invariant is single-sourced: any production-source\n * site that constructs an unbound-namespace singleton imports this\n * constant.\n */\nexport const UNBOUND_NAMESPACE_ID = '__unbound__' as const;\n\n/**\n * Framework-level building block for a \"namespace\" — the database-level\n * grouping under which storage objects (tables, collections, enums, …)\n * reside. Each target's namespace concretion maps the framework concept to\n * a target-native binding:\n *\n * - Postgres: a schema (`CREATE SCHEMA …`); rendered as `\"<schema>\"`.\n * - SQLite: the singleton `UNBOUND_NAMESPACE_ID`; emitted SQL has no qualifier.\n * - Mongo: the connection's `db` field; addressed as a database name.\n *\n * See `UNBOUND_NAMESPACE_ID` above for the sentinel id and the\n * singleton-subclass pattern that materialises it.\n *\n * The framework promises only the coordinate (`id`) — the named storage\n * entities a namespace contains are family-typed (SQL contributes\n * `table` / `type`, Mongo contributes `collection`, future families pick\n * their own native idiom under `entries`). Generic consumers walking \"all\n * named entries\" go through a family-typed namespace, not the framework\n * `Namespace`.\n *\n * Every namespace concretion (e.g. family-built SQL namespaces,\n * `MongoUnboundNamespace`, target-promoted namespaces like\n * `PostgresSchema`) carries exactly: `id` (enumerable string),\n * `entries` (frozen object holding entity-kind slot maps), and `kind`\n * (non-enumerable string discriminator set via `Object.defineProperty`).\n * Each slot map under `entries` uses a singular essence key (`table`,\n * `type`, `collection`, …) mapping entity names to IR classes. No other\n * own-enumerable data lives on a namespace; non-entity computed data lives\n * on the surrounding storage or contract IR. The framework's\n * `elementCoordinates(storage)` walk relies on this invariant to enumerate\n * entities structurally without family-specific knowledge.\n */\nexport interface Namespace extends IRNode, StorageNamespace {\n  readonly kind: string;\n  readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;\n}\n\nexport abstract class NamespaceBase extends IRNodeBase implements Namespace {\n  abstract readonly id: string;\n  abstract readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;\n  abstract override readonly kind: string;\n}\n","import type { StorageBase } from '@prisma-next/contract/types';\nimport type { IRNode } from './ir-node';\nimport type { Namespace } from './namespace';\n\n/**\n * Canonical address for a named entity in Contract IR / Schema IR.\n *\n * `plane` is `'domain' | 'storage'`: which top-level contract plane the\n * entity lives on. Domain-side walks yield `plane: 'domain'` via\n * {@link domainElementCoordinates}; {@link elementCoordinates} over storage\n * yields `plane: 'storage'`.\n *\n * Cross-plane references obey a directional invariant: domain → storage is\n * allowed; storage → domain is forbidden. That rule is enforced by a\n * separate validator, not by constraining this coordinate shape — the\n * coordinate carries the axis the validator checks.\n *\n * Iteration order over namespace properties follows `Object.entries` order;\n * consumers that depend on ordering must sort.\n */\nexport interface EntityCoordinate {\n  readonly plane: 'domain' | 'storage';\n  readonly namespaceId: string;\n  readonly entityKind: string;\n  readonly entityName: string;\n}\n\n/**\n * Lazy walk over every named storage entity in a `Storage`-shaped\n * value, yielded as {@link EntityCoordinate} tuples with\n * `plane: 'storage'` (the parameter type binds the plane).\n *\n * Iterates each namespace's `entries` slot maps structurally. Skips\n * non-object `entries`; `id` and `kind` are not walked (`kind` is\n * non-enumerable on concretions). For every entity-kind key under\n * `entries` whose value is a non-null object, yields one coordinate per\n * entity name in that map. No family-specific slot vocabulary is required.\n */\nexport function* elementCoordinates(\n  storage: Pick<StorageBase, 'namespaces'>,\n): Generator<EntityCoordinate> {\n  for (const [namespaceId, ns] of Object.entries(storage.namespaces)) {\n    const entries = ns.entries;\n    if (entries === null || typeof entries !== 'object') continue;\n    for (const [entityKind, slot] of Object.entries(entries)) {\n      if (slot === null || typeof slot !== 'object') continue;\n      for (const entityName of Object.keys(slot)) {\n        yield { plane: 'storage', namespaceId, entityKind, entityName };\n      }\n    }\n  }\n}\n\n/**\n * Framework-level promise that every Contract IR / Schema IR carries a\n * collection of namespaces keyed by namespace id. Family storage\n * concretions (`SqlStorage`, `MongoStorage`) refine the shape with\n * family-specific fields (tables, collections, enums, …); target\n * concretions add target fields where the family vocabulary doesn't\n * reach.\n *\n * Keeping `namespaces` at the framework layer enforces that every storage\n * object — across any target — is namespace-scoped. The framework can\n * therefore walk the namespace map without knowing the family alphabet, and\n * the `(namespace.id, name)` keying that the verifier and planner depend on\n * is honest at every layer.\n *\n * Extends `IRNode` so the framework's IR-walking surfaces (verifiers,\n * serializers) can dispatch on `Storage`-typed slots through the same\n * IR-node alphabet as every other node — the structural dual already\n * holds in code (every concrete storage class extends an IR-node base);\n * the interface promotion makes the typing honest.\n *\n * **Persisted envelope shape is target-owned, not framework-promised.**\n * Whether the `namespaces` map appears in the on-disk JSON envelope is\n * a per-target decision made by `ContractSerializer.serializeContract`.\n * Some targets emit a JSON-clean namespace shape that round-trips\n * through `JSON.stringify` cleanly (SQL today via the family-layer\n * identity serializer); others ship runtime-only fields on their\n * namespace concretions and override `serializeContract` to strip\n * them (Mongo). Future open (F16): extend the per-target\n * `ContractSerializer` integration-test surface with an explicit\n * envelope-shape assertion for each target, so the strip-vs-pass-through\n * choice is locked at test time rather than implied by the override\n * presence/absence. Earned by PR2's per-target namespace lift, when\n * `PostgresSchema` / `SqliteUnboundDatabase` start carrying\n * target-specific fields.\n */\nexport interface Storage extends IRNode {\n  readonly namespaces: Readonly<Record<string, Namespace>>;\n}\n"],"mappings":";;;;;;;;AAUA,UAAiB,yBACf,QAC6B;CAC7B,KAAK,MAAM,CAAC,aAAa,OAAO,OAAO,QAAQ,OAAO,UAAU,GAC9D,KAAK,MAAM,CAAC,YAAY,SAAS,OAAO,QAAQ,EAAE,GAAG;EACnD,IAAI,eAAe,MAAM;EACzB,IAAI,SAAS,QAAQ,OAAO,SAAS,UAAU;EAC/C,KAAK,MAAM,cAAc,OAAO,KAAK,IAAI,GACvC,MAAM;GAAE,OAAO;GAAU;GAAa;GAAY;EAAW;CAEjE;AAEJ;;;ACuBA,IAAsB,aAAtB,MAAmD,CAEnD;;;;;;;;;;AAWA,SAAgB,WAA6B,MAAY;CACvD,OAAO,OAAO,IAAI;CAClB,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;ACnCA,MAAa,uBAAuB;AAuCpC,IAAsB,gBAAtB,cAA4C,WAAgC,CAI5E;;;;;;;;;;;;;;AC/BA,UAAiB,mBACf,SAC6B;CAC7B,KAAK,MAAM,CAAC,aAAa,OAAO,OAAO,QAAQ,QAAQ,UAAU,GAAG;EAClE,MAAM,UAAU,GAAG;EACnB,IAAI,YAAY,QAAQ,OAAO,YAAY,UAAU;EACrD,KAAK,MAAM,CAAC,YAAY,SAAS,OAAO,QAAQ,OAAO,GAAG;GACxD,IAAI,SAAS,QAAQ,OAAO,SAAS,UAAU;GAC/C,KAAK,MAAM,cAAc,OAAO,KAAK,IAAI,GACvC,MAAM;IAAE,OAAO;IAAW;IAAa;IAAY;GAAW;EAElE;CACF;AACF"}
+{"version":3,"file":"ir.mjs","names":[],"sources":["../src/ir/domain.ts","../src/ir/ir-node.ts","../src/ir/namespace.ts","../src/ir/storage.ts"],"sourcesContent":["import type { ApplicationDomain } from '@prisma-next/contract/types';\nimport type { EntityCoordinate } from './storage';\n\n/**\n * Lazy walk over every named domain entity in a {@link ApplicationDomain},\n * yielded as {@link EntityCoordinate} tuples with `plane: 'domain'`.\n *\n * Same structural rules as {@link elementCoordinates} over storage: skip\n * scalar `id`; each other object-valued property is an entity-kind slot.\n */\nexport function* domainElementCoordinates(\n  domain: Pick<ApplicationDomain, 'namespaces'>,\n): Generator<EntityCoordinate> {\n  for (const [namespaceId, ns] of Object.entries(domain.namespaces)) {\n    for (const [entityKind, slot] of Object.entries(ns)) {\n      if (entityKind === 'id') continue;\n      if (slot === null || typeof slot !== 'object') continue;\n      for (const entityName of Object.keys(slot)) {\n        yield { plane: 'domain', namespaceId, entityKind, entityName };\n      }\n    }\n  }\n}\n","/**\n * Framework-level IR alphabet.\n *\n * The framework's contribution to Contract IR / Schema IR is a common\n * root for the IR class hierarchy and a freeze affordance. Family\n * abstract bases (e.g. `SqlNode`, `MongoSchemaIRNode`) refine the alphabet\n * for their family shape; targets ship the concrete classes.\n *\n * `kind` is an optional discriminator on the base. Families and leaves\n * that benefit from discriminated-union dispatch declare their own\n * literal `kind` at the level that earns it — Mongo leaves carry\n * per-class literals (`readonly kind = 'mongo-collection' as const`)\n * because Mongo IR has polymorphic walkers; SQL declares a single\n * family-level `kind = 'sql'` on `SqlNode` because SQL IR has no\n * polymorphic dispatch today. No framework consumer dispatches on\n * `IRNode.kind` at the BASE type — every dispatch site narrows\n * through a union of leaves where each leaf carries a literal kind, so\n * requiring `kind` at the base would be unearned. Future leaves that\n * earn polymorphic dispatch override with a required literal at that\n * leaf (e.g. `override readonly kind = 'pack-contributed-kind' as const`).\n *\n * `IRNodeBase` carries no methods: the freeze-and-assign affordance\n * lives in the free `freezeNode` helper below. Keeping `freezeNode` out\n * of the class type means an emitted contract literal type\n * (`{ readonly kind: 'mongo-collection', ... }` or an unkeyed literal\n * like `{ nativeType, codecId, nullable }`) is structurally assignable\n * to its class type — a `protected freeze()` instance method would\n * otherwise leak into the public type surface and require the literal\n * to carry it too.\n *\n * Subclasses construct fields then call `freezeNode(this)` to seal the\n * instance. Frozen instances + plain readonly fields keep IR nodes\n * JSON-clean by construction, so `JSON.stringify(node)` produces canonical\n * JSON without a `toJSON()` method. The `ContractSerializer` SPI handles\n * round-trip from canonical JSON back to typed class instances.\n *\n * The name (`IRNode` / `IRNodeBase`) reflects the dual-hierarchy reality:\n * this base is the common root for both Contract IR and Schema IR class\n * hierarchies, not a Schema-IR-specific alphabet.\n */\n\nexport interface IRNode {\n  readonly kind?: string;\n}\n\nexport abstract class IRNodeBase implements IRNode {\n  abstract readonly kind?: string;\n}\n\n/**\n * Seal an IR class instance after its constructor has assigned all\n * fields. The free-helper form (rather than a `protected freeze()`\n * instance method) keeps the class type structurally narrow so emitted\n * contract literal types remain assignable to their class types.\n *\n * The helper name stays `freezeNode` — it operates on IR nodes\n * regardless of root naming.\n */\nexport function freezeNode<T extends IRNode>(node: T): T {\n  Object.freeze(node);\n  return node;\n}\n","import type { StorageNamespace } from '@prisma-next/contract/types';\nimport { type IRNode, IRNodeBase } from './ir-node';\n\n/**\n * Reserved sentinel namespace id for the late-bound storage slot —\n * the slot whose binding the target resolves at connection time\n * rather than at authoring time. Postgres uses it for `search_path`\n * late binding; SQLite uses it for the trivial singleton; Mongo uses\n * it for the connection's `db` binding.\n *\n * Materialised target-side as a singleton subclass of the target's\n * `NamespaceBase` concretion that overrides the namespace's\n * qualifier-emission methods to elide the prefix entirely. Call sites\n * stay polymorphic and never branch on `id === UNBOUND_NAMESPACE_ID`\n * — the singleton's overrides drop the qualifier so emitted SQL / Mongo\n * commands look unqualified.\n *\n * The double-underscore decoration marks the id as a framework-reserved\n * coordinate when it appears in a JSON envelope (cold-read-as-reserved\n * — no realistic collision with user-declared namespace names).\n *\n * Encoded as an exported const (rather than scattered string literals)\n * so the sentinel-id invariant is single-sourced: any production-source\n * site that constructs an unbound-namespace singleton imports this\n * constant.\n */\nexport const UNBOUND_NAMESPACE_ID = '__unbound__' as const;\n\n/**\n * Framework-level building block for a \"namespace\" — the database-level\n * grouping under which storage objects (tables, collections, enums, …)\n * reside. Each target's namespace concretion maps the framework concept to\n * a target-native binding:\n *\n * - Postgres: a schema (`CREATE SCHEMA …`); rendered as `\"<schema>\"`.\n * - SQLite: the singleton `UNBOUND_NAMESPACE_ID`; emitted SQL has no qualifier.\n * - Mongo: the connection's `db` field; addressed as a database name.\n *\n * See `UNBOUND_NAMESPACE_ID` above for the sentinel id and the\n * singleton-subclass pattern that materialises it.\n *\n * The framework promises only the coordinate (`id`) — the named storage\n * entities a namespace contains are family-typed (SQL contributes\n * `table` / `type`, Mongo contributes `collection`, future families pick\n * their own native idiom under `entries`). Generic consumers walking \"all\n * named entries\" go through a family-typed namespace, not the framework\n * `Namespace`.\n *\n * Every namespace concretion (e.g. family-built SQL namespaces,\n * `MongoUnboundNamespace`, target-promoted namespaces like\n * `PostgresSchema`) carries exactly: `id` (enumerable string),\n * `entries` (frozen object holding entity-kind slot maps), and `kind`\n * (non-enumerable string discriminator set via `Object.defineProperty`).\n * Each slot map under `entries` uses a singular essence key (`table`,\n * `type`, `collection`, …) mapping entity names to IR classes. No other\n * own-enumerable data lives on a namespace; non-entity computed data lives\n * on the surrounding storage or contract IR. The framework's\n * `elementCoordinates(storage)` walk relies on this invariant to enumerate\n * entities structurally without family-specific knowledge.\n */\nexport interface Namespace extends IRNode, StorageNamespace {\n  readonly kind: string;\n  readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;\n}\n\nexport abstract class NamespaceBase extends IRNodeBase implements Namespace {\n  abstract readonly id: string;\n  abstract readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;\n  abstract override readonly kind: string;\n}\n","import type { StorageBase } from '@prisma-next/contract/types';\nimport { blindCast } from '@prisma-next/utils/casts';\nimport type { IRNode } from './ir-node';\nimport type { Namespace } from './namespace';\n\n/**\n * Canonical address for a named entity in Contract IR / Schema IR.\n *\n * `plane` is `'domain' | 'storage'`: which top-level contract plane the\n * entity lives on. Domain-side walks yield `plane: 'domain'` via\n * {@link domainElementCoordinates}; {@link elementCoordinates} over storage\n * yields `plane: 'storage'`.\n *\n * Cross-plane references obey a directional invariant: domain → storage is\n * allowed; storage → domain is forbidden. That rule is enforced by a\n * separate validator, not by constraining this coordinate shape — the\n * coordinate carries the axis the validator checks.\n *\n * Iteration order over namespace properties follows `Object.entries` order;\n * consumers that depend on ordering must sort.\n */\nexport interface EntityCoordinate {\n  readonly plane: 'domain' | 'storage';\n  readonly namespaceId: string;\n  readonly entityKind: string;\n  readonly entityName: string;\n}\n\n/**\n * Lazy walk over every named storage entity in a `Storage`-shaped\n * value, yielded as {@link EntityCoordinate} tuples with\n * `plane: 'storage'` (the parameter type binds the plane).\n *\n * Iterates each namespace's `entries` kind maps structurally. Skips\n * non-object `entries`; `id` and `kind` are not walked (`kind` is\n * non-enumerable on concretions). For every entity-kind key under\n * `entries` whose value is a non-null object, yields one coordinate per\n * entity name in that map. No family-specific kind vocabulary is required.\n */\nexport function* elementCoordinates(\n  storage: Pick<StorageBase, 'namespaces'>,\n): Generator<EntityCoordinate> {\n  for (const [namespaceId, ns] of Object.entries(storage.namespaces)) {\n    const entries = ns.entries;\n    if (entries === null || typeof entries !== 'object') continue;\n    for (const [entityKind, kindMap] of Object.entries(entries)) {\n      if (kindMap === null || typeof kindMap !== 'object') continue;\n      for (const entityName of Object.keys(kindMap)) {\n        yield { plane: 'storage', namespaceId, entityKind, entityName };\n      }\n    }\n  }\n}\n\nfunction isRecord(value: unknown): value is Readonly<Record<string, unknown>> {\n  return typeof value === 'object' && value !== null;\n}\n\n/**\n * Looks up a single entity in a `Storage`-shaped value by its full coordinate.\n * Returns `undefined` if the namespace, entity kind, or entity name is absent.\n * The type parameter is a caller assertion — the walk itself is structural\n * and cannot verify the entity's shape.\n */\nexport function entityAt<T = unknown>(\n  storage: Pick<StorageBase, 'namespaces'>,\n  coord: Pick<EntityCoordinate, 'namespaceId' | 'entityKind' | 'entityName'>,\n): T | undefined {\n  const ns = storage.namespaces[coord.namespaceId];\n  if (ns === undefined) return undefined;\n  const entries = ns.entries;\n  if (!isRecord(entries)) return undefined;\n  const kindMap = entries[coord.entityKind];\n  if (!isRecord(kindMap)) return undefined;\n  if (!Object.hasOwn(kindMap, coord.entityName)) return undefined;\n  return blindCast<T | undefined, 'caller asserts the entity type at this coordinate'>(\n    kindMap[coord.entityName],\n  );\n}\n\n/**\n * Framework-level promise that every Contract IR / Schema IR carries a\n * collection of namespaces keyed by namespace id. Family storage\n * concretions (`SqlStorage`, `MongoStorage`) refine the shape with\n * family-specific fields (tables, collections, enums, …); target\n * concretions add target fields where the family vocabulary doesn't\n * reach.\n *\n * Keeping `namespaces` at the framework layer enforces that every storage\n * object — across any target — is namespace-scoped. The framework can\n * therefore walk the namespace map without knowing the family alphabet, and\n * the `(namespace.id, name)` keying that the verifier and planner depend on\n * is honest at every layer.\n *\n * Extends `IRNode` so the framework's IR-walking surfaces (verifiers,\n * serializers) can dispatch on `Storage`-typed fields through the same\n * IR-node alphabet as every other node — the structural dual already\n * holds in code (every concrete storage class extends an IR-node base);\n * the interface promotion makes the typing honest.\n *\n * **Persisted envelope shape is target-owned, not framework-promised.**\n * Whether the `namespaces` map appears in the on-disk JSON envelope is\n * a per-target decision made by `ContractSerializer.serializeContract`.\n * Some targets emit a JSON-clean namespace shape that round-trips\n * through `JSON.stringify` cleanly (SQL today via the family-layer\n * identity serializer); others ship runtime-only fields on their\n * namespace concretions and override `serializeContract` to strip\n * them (Mongo). Future open (F16): extend the per-target\n * `ContractSerializer` integration-test surface with an explicit\n * envelope-shape assertion for each target, so the strip-vs-pass-through\n * choice is locked at test time rather than implied by the override\n * presence/absence. Earned by PR2's per-target namespace lift, when\n * `PostgresSchema` / `SqliteUnboundDatabase` start carrying\n * target-specific fields.\n */\nexport interface Storage extends IRNode {\n  readonly namespaces: Readonly<Record<string, Namespace>>;\n}\n"],"mappings":";;;;;;;;;AAUA,UAAiB,yBACf,QAC6B;CAC7B,KAAK,MAAM,CAAC,aAAa,OAAO,OAAO,QAAQ,OAAO,UAAU,GAC9D,KAAK,MAAM,CAAC,YAAY,SAAS,OAAO,QAAQ,EAAE,GAAG;EACnD,IAAI,eAAe,MAAM;EACzB,IAAI,SAAS,QAAQ,OAAO,SAAS,UAAU;EAC/C,KAAK,MAAM,cAAc,OAAO,KAAK,IAAI,GACvC,MAAM;GAAE,OAAO;GAAU;GAAa;GAAY;EAAW;CAEjE;AAEJ;;;ACuBA,IAAsB,aAAtB,MAAmD,CAEnD;;;;;;;;;;AAWA,SAAgB,WAA6B,MAAY;CACvD,OAAO,OAAO,IAAI;CAClB,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;ACnCA,MAAa,uBAAuB;AAuCpC,IAAsB,gBAAtB,cAA4C,WAAgC,CAI5E;;;;;;;;;;;;;;AC9BA,UAAiB,mBACf,SAC6B;CAC7B,KAAK,MAAM,CAAC,aAAa,OAAO,OAAO,QAAQ,QAAQ,UAAU,GAAG;EAClE,MAAM,UAAU,GAAG;EACnB,IAAI,YAAY,QAAQ,OAAO,YAAY,UAAU;EACrD,KAAK,MAAM,CAAC,YAAY,YAAY,OAAO,QAAQ,OAAO,GAAG;GAC3D,IAAI,YAAY,QAAQ,OAAO,YAAY,UAAU;GACrD,KAAK,MAAM,cAAc,OAAO,KAAK,OAAO,GAC1C,MAAM;IAAE,OAAO;IAAW;IAAa;IAAY;GAAW;EAElE;CACF;AACF;AAEA,SAAS,SAAS,OAA4D;CAC5E,OAAO,OAAO,UAAU,YAAY,UAAU;AAChD;;;;;;;AAQA,SAAgB,SACd,SACA,OACe;CACf,MAAM,KAAK,QAAQ,WAAW,MAAM;CACpC,IAAI,OAAO,KAAA,GAAW,OAAO,KAAA;CAC7B,MAAM,UAAU,GAAG;CACnB,IAAI,CAAC,SAAS,OAAO,GAAG,OAAO,KAAA;CAC/B,MAAM,UAAU,QAAQ,MAAM;CAC9B,IAAI,CAAC,SAAS,OAAO,GAAG,OAAO,KAAA;CAC/B,IAAI,CAAC,OAAO,OAAO,SAAS,MAAM,UAAU,GAAG,OAAO,KAAA;CACtD,OAAO,UACL,QAAQ,MAAM,WAChB;AACF"}

package/package.json

@@ -1,21 +1,21 @@
 {
   "name": "@prisma-next/framework-components",
-  "version": "0.13.0-dev.25",
+  "version": "0.13.0-dev.27",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "Framework component types, assembly logic, and stack creation for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.13.0-dev.25",
-    "@prisma-next/operations": "0.13.0-dev.25",
-    "@prisma-next/ts-render": "0.13.0-dev.25",
-    "@prisma-next/utils": "0.13.0-dev.25",
+    "@prisma-next/contract": "0.13.0-dev.27",
+    "@prisma-next/operations": "0.13.0-dev.27",
+    "@prisma-next/ts-render": "0.13.0-dev.27",
+    "@prisma-next/utils": "0.13.0-dev.27",
     "@standard-schema/spec": "^1.1.0",
     "arktype": "^2.2.0"
   },
   "devDependencies": {
-    "@prisma-next/tsconfig": "0.13.0-dev.25",
-    "@prisma-next/tsdown": "0.13.0-dev.25",
+    "@prisma-next/tsconfig": "0.13.0-dev.27",
+    "@prisma-next/tsdown": "0.13.0-dev.27",
     "tsdown": "0.22.1",
     "typescript": "5.9.3",
     "vitest": "4.1.8"

package/src/exports/ir.ts

@@ -4,5 +4,5 @@ export { freezeNode, IRNodeBase } from '../ir/ir-node';
 export type { Namespace } from '../ir/namespace';
 export { NamespaceBase, UNBOUND_NAMESPACE_ID } from '../ir/namespace';
 export type { EntityCoordinate, Storage } from '../ir/storage';
-export { elementCoordinates } from '../ir/storage';
+export { elementCoordinates, entityAt } from '../ir/storage';
 export type { StorageType } from '../ir/storage-type';

package/src/ir/storage.ts

@@ -1,4 +1,5 @@
 import type { StorageBase } from '@prisma-next/contract/types';
+import { blindCast } from '@prisma-next/utils/casts';
 import type { IRNode } from './ir-node';
 import type { Namespace } from './namespace';
 
@@ -30,11 +31,11 @@ export interface EntityCoordinate {
  * value, yielded as {@link EntityCoordinate} tuples with
  * `plane: 'storage'` (the parameter type binds the plane).
  *
- * Iterates each namespace's `entries` slot maps structurally. Skips
+ * Iterates each namespace's `entries` kind maps structurally. Skips
  * non-object `entries`; `id` and `kind` are not walked (`kind` is
  * non-enumerable on concretions). For every entity-kind key under
  * `entries` whose value is a non-null object, yields one coordinate per
- * entity name in that map. No family-specific slot vocabulary is required.
+ * entity name in that map. No family-specific kind vocabulary is required.
  */
 export function* elementCoordinates(
   storage: Pick<StorageBase, 'namespaces'>,
@@ -42,15 +43,41 @@ export function* elementCoordinates(
   for (const [namespaceId, ns] of Object.entries(storage.namespaces)) {
     const entries = ns.entries;
     if (entries === null || typeof entries !== 'object') continue;
-    for (const [entityKind, slot] of Object.entries(entries)) {
-      if (slot === null || typeof slot !== 'object') continue;
-      for (const entityName of Object.keys(slot)) {
+    for (const [entityKind, kindMap] of Object.entries(entries)) {
+      if (kindMap === null || typeof kindMap !== 'object') continue;
+      for (const entityName of Object.keys(kindMap)) {
         yield { plane: 'storage', namespaceId, entityKind, entityName };
       }
     }
   }
 }
 
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * Looks up a single entity in a `Storage`-shaped value by its full coordinate.
+ * Returns `undefined` if the namespace, entity kind, or entity name is absent.
+ * The type parameter is a caller assertion — the walk itself is structural
+ * and cannot verify the entity's shape.
+ */
+export function entityAt<T = unknown>(
+  storage: Pick<StorageBase, 'namespaces'>,
+  coord: Pick<EntityCoordinate, 'namespaceId' | 'entityKind' | 'entityName'>,
+): T | undefined {
+  const ns = storage.namespaces[coord.namespaceId];
+  if (ns === undefined) return undefined;
+  const entries = ns.entries;
+  if (!isRecord(entries)) return undefined;
+  const kindMap = entries[coord.entityKind];
+  if (!isRecord(kindMap)) return undefined;
+  if (!Object.hasOwn(kindMap, coord.entityName)) return undefined;
+  return blindCast<T | undefined, 'caller asserts the entity type at this coordinate'>(
+    kindMap[coord.entityName],
+  );
+}
+
 /**
  * Framework-level promise that every Contract IR / Schema IR carries a
  * collection of namespaces keyed by namespace id. Family storage
@@ -66,7 +93,7 @@ export function* elementCoordinates(
  * is honest at every layer.
  *
  * Extends `IRNode` so the framework's IR-walking surfaces (verifiers,
- * serializers) can dispatch on `Storage`-typed slots through the same
+ * serializers) can dispatch on `Storage`-typed fields through the same
  * IR-node alphabet as every other node — the structural dual already
  * holds in code (every concrete storage class extends an IR-node base);
  * the interface promotion makes the typing honest.