@prisma-next/sql-contract 0.14.0-dev.80 → 0.14.0-dev.82

package/dist/entity-handle-lowering-hook.d.mts

@@ -0,0 +1,91 @@
+//#region src/entity-handle-lowering-hook.d.ts
+/**
+ * SQL-family extension to the pack authoring contributions: a pack whose
+ * `entityTypes` registers entity kinds may implement a batch lowering hook
+ * that turns author-declared pack-entity handles (the generic `entities`
+ * list on the TS contract input) into `entries` rows.
+ *
+ * The generic contract build (`contract-ts`) owns the kind-agnostic walk: it
+ * groups handles by the pack that registered each `entityKind`, resolves
+ * each handle's declared model refs to storage table coordinates using the
+ * same model→table maps the relation lowering uses, and calls the owning
+ * pack's hook once with all of its claimed handles — batch, so the hook's
+ * diagnostics can see sibling handles. Neither the walk nor these types name
+ * any specific entity kind.
+ *
+ * SQL-family concept — the resolved-ref shape is a table coordinate, so the
+ * hook lives here beside {@link ../value-set-derivation-hook} instead of on
+ * the framework contributions type.
+ */
+/**
+ * An authored pack-entity handle: branded by the `entityKind` its owning
+ * pack registered, optionally declaring model refs under `refs` (actual
+ * model-handle objects, resolved by the generic walk before lowering).
+ */
+interface PackEntityHandle {
+  readonly entityKind: string;
+  readonly refs?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A declared model ref after the generic walk resolved it: a storage table
+ * coordinate for a model of this contract, the coordinate plus `spaceId` for
+ * a cross-space (extensionModel) handle, or `unresolved` when the handle
+ * does not correspond to any model in the contract. `modelName` is carried
+ * for diagnostics where the handle declares one.
+ */
+type ResolvedEntityHandleRef = {
+  readonly kind: 'resolved';
+  readonly namespaceId: string;
+  readonly tableName: string;
+  readonly modelName?: string;
+} | {
+  readonly kind: 'cross-space';
+  readonly spaceId: string;
+  readonly namespaceId: string;
+  readonly tableName: string;
+  readonly modelName?: string;
+} | {
+  readonly kind: 'unresolved';
+  readonly modelName?: string;
+};
+/** One claimed handle paired with its resolved declared refs. */
+interface ResolvedPackEntityHandle {
+  readonly handle: PackEntityHandle;
+  readonly refs: Readonly<Record<string, ResolvedEntityHandleRef>>;
+}
+interface EntityHandleLoweringInput {
+  /** Every handle in the `entities` list whose `entityKind` this pack registered, in authored order. */
+  readonly handles: readonly ResolvedPackEntityHandle[];
+  readonly defaultNamespaceId: string;
+}
+/** One lowered entity row: filed into `storage.namespaces[namespaceId].entries[entityKind][key]`. */
+interface LoweredPackEntity {
+  readonly namespaceId: string;
+  readonly entityKind: string;
+  readonly key: string;
+  readonly entity: unknown;
+}
+interface SqlEntityHandleLoweringContribution {
+  /**
+   * Method syntax keeps the declaration bivariant, so a pack's concretely
+   * typed implementation stays structurally compatible (the same convention
+   * as `SqlValueSetDerivingEntityTypeOutput.deriveValueSet`).
+   */
+  lowerEntityHandles(input: EntityHandleLoweringInput): readonly LoweredPackEntity[];
+}
+/** Structural check for {@link SqlEntityHandleLoweringContribution}: no casts. */
+declare function providesEntityHandleLowering(authoring: unknown): authoring is SqlEntityHandleLoweringContribution;
+/**
+ * PSL-side twin of {@link ResolvedEntityHandleRef}: the family interpreter
+ * resolves an extension block's descriptor-declared model ref parameters
+ * (`{ kind: 'ref', refKind: 'model' }`) to storage table names and annotates
+ * the block with this map (keyed by parameter name) before invoking the
+ * entity factory. An unresolved required ref is the interpreter's
+ * diagnostic; a factory never sees one.
+ */
+type ResolvedPslModelRefs = Readonly<Record<string, {
+  readonly tableName: string;
+}>>;
+//#endregion
+export { type EntityHandleLoweringInput, type LoweredPackEntity, type PackEntityHandle, type ResolvedEntityHandleRef, type ResolvedPackEntityHandle, type ResolvedPslModelRefs, type SqlEntityHandleLoweringContribution, providesEntityHandleLowering };
+//# sourceMappingURL=entity-handle-lowering-hook.d.mts.map

package/dist/entity-handle-lowering-hook.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-handle-lowering-hook.d.mts","names":[],"sources":["../src/entity-handle-lowering-hook.ts"],"mappings":";;AAwBA;;;;;;;;;AAEiC;AAUjC;;;;;;;;;;;;UAZiB,gBAAA;EAAA,SACN,UAAA;EAAA,SACA,IAAA,GAAO,QAAQ,CAAC,MAAA;AAAA;AA0BH;AAIxB;;;;;;AAJwB,KAhBZ,uBAAA;EAAA,SAEG,IAAA;EAAA,SACA,WAAA;EAAA,SACA,SAAA;EAAA,SACA,SAAA;AAAA;EAAA,SAGA,IAAA;EAAA,SACA,OAAA;EAAA,SACA,WAAA;EAAA,SACA,SAAA;EAAA,SACA,SAAA;AAAA;EAAA,SAGA,IAAA;EAAA,SACA,SAAA;AAAA;;UAIE,wBAAA;EAAA,SACN,MAAA,EAAQ,gBAAA;EAAA,SACR,IAAA,EAAM,QAAA,CAAS,MAAA,SAAe,uBAAA;AAAA;AAAA,UAGxB,yBAAA;EAOiB;EAAA,SALvB,OAAA,WAAkB,wBAAwB;EAAA,SAC1C,kBAAA;AAAA;;UAIM,iBAAA;EAAA,SACN,WAAA;EAAA,SACA,UAAA;EAAA,SACA,GAAA;EAAA,SACA,MAAA;AAAA;AAAA,UAGM,mCAAA;EAMiE;;;;;EAAhF,kBAAA,CAAmB,KAAA,EAAO,yBAAA,YAAqC,iBAAiB;AAAA;AAIlF;AAAA,iBAAgB,4BAAA,CACd,SAAA,YACC,SAAA,IAAa,mCAAmC;;;;;;;AAAA;AAgBnD;KAAY,oBAAA,GAAuB,QAAQ,CAAC,MAAA;EAAA,SAA0B,SAAA;AAAA"}

package/dist/entity-handle-lowering-hook.mjs

@@ -0,0 +1,11 @@
+//#region src/entity-handle-lowering-hook.ts
+/** Structural check for {@link SqlEntityHandleLoweringContribution}: no casts. */
+function providesEntityHandleLowering(authoring) {
+	if (typeof authoring !== "object" || authoring === null || !("lowerEntityHandles" in authoring)) return false;
+	const { lowerEntityHandles } = authoring;
+	return typeof lowerEntityHandles === "function";
+}
+//#endregion
+export { providesEntityHandleLowering };
+
+//# sourceMappingURL=entity-handle-lowering-hook.mjs.map

package/dist/entity-handle-lowering-hook.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-handle-lowering-hook.mjs","names":[],"sources":["../src/entity-handle-lowering-hook.ts"],"sourcesContent":["/**\n * SQL-family extension to the pack authoring contributions: a pack whose\n * `entityTypes` registers entity kinds may implement a batch lowering hook\n * that turns author-declared pack-entity handles (the generic `entities`\n * list on the TS contract input) into `entries` rows.\n *\n * The generic contract build (`contract-ts`) owns the kind-agnostic walk: it\n * groups handles by the pack that registered each `entityKind`, resolves\n * each handle's declared model refs to storage table coordinates using the\n * same model→table maps the relation lowering uses, and calls the owning\n * pack's hook once with all of its claimed handles — batch, so the hook's\n * diagnostics can see sibling handles. Neither the walk nor these types name\n * any specific entity kind.\n *\n * SQL-family concept — the resolved-ref shape is a table coordinate, so the\n * hook lives here beside {@link ../value-set-derivation-hook} instead of on\n * the framework contributions type.\n */\n\n/**\n * An authored pack-entity handle: branded by the `entityKind` its owning\n * pack registered, optionally declaring model refs under `refs` (actual\n * model-handle objects, resolved by the generic walk before lowering).\n */\nexport interface PackEntityHandle {\n  readonly entityKind: string;\n  readonly refs?: Readonly<Record<string, unknown>>;\n}\n\n/**\n * A declared model ref after the generic walk resolved it: a storage table\n * coordinate for a model of this contract, the coordinate plus `spaceId` for\n * a cross-space (extensionModel) handle, or `unresolved` when the handle\n * does not correspond to any model in the contract. `modelName` is carried\n * for diagnostics where the handle declares one.\n */\nexport type ResolvedEntityHandleRef =\n  | {\n      readonly kind: 'resolved';\n      readonly namespaceId: string;\n      readonly tableName: string;\n      readonly modelName?: string;\n    }\n  | {\n      readonly kind: 'cross-space';\n      readonly spaceId: string;\n      readonly namespaceId: string;\n      readonly tableName: string;\n      readonly modelName?: string;\n    }\n  | {\n      readonly kind: 'unresolved';\n      readonly modelName?: string;\n    };\n\n/** One claimed handle paired with its resolved declared refs. */\nexport interface ResolvedPackEntityHandle {\n  readonly handle: PackEntityHandle;\n  readonly refs: Readonly<Record<string, ResolvedEntityHandleRef>>;\n}\n\nexport interface EntityHandleLoweringInput {\n  /** Every handle in the `entities` list whose `entityKind` this pack registered, in authored order. */\n  readonly handles: readonly ResolvedPackEntityHandle[];\n  readonly defaultNamespaceId: string;\n}\n\n/** One lowered entity row: filed into `storage.namespaces[namespaceId].entries[entityKind][key]`. */\nexport interface LoweredPackEntity {\n  readonly namespaceId: string;\n  readonly entityKind: string;\n  readonly key: string;\n  readonly entity: unknown;\n}\n\nexport interface SqlEntityHandleLoweringContribution {\n  /**\n   * Method syntax keeps the declaration bivariant, so a pack's concretely\n   * typed implementation stays structurally compatible (the same convention\n   * as `SqlValueSetDerivingEntityTypeOutput.deriveValueSet`).\n   */\n  lowerEntityHandles(input: EntityHandleLoweringInput): readonly LoweredPackEntity[];\n}\n\n/** Structural check for {@link SqlEntityHandleLoweringContribution}: no casts. */\nexport function providesEntityHandleLowering(\n  authoring: unknown,\n): authoring is SqlEntityHandleLoweringContribution {\n  if (typeof authoring !== 'object' || authoring === null || !('lowerEntityHandles' in authoring)) {\n    return false;\n  }\n  const { lowerEntityHandles } = authoring;\n  return typeof lowerEntityHandles === 'function';\n}\n\n/**\n * PSL-side twin of {@link ResolvedEntityHandleRef}: the family interpreter\n * resolves an extension block's descriptor-declared model ref parameters\n * (`{ kind: 'ref', refKind: 'model' }`) to storage table names and annotates\n * the block with this map (keyed by parameter name) before invoking the\n * entity factory. An unresolved required ref is the interpreter's\n * diagnostic; a factory never sees one.\n */\nexport type ResolvedPslModelRefs = Readonly<Record<string, { readonly tableName: string }>>;\n"],"mappings":";;AAqFA,SAAgB,6BACd,WACkD;CAClD,IAAI,OAAO,cAAc,YAAY,cAAc,QAAQ,EAAE,wBAAwB,YACnF,OAAO;CAET,MAAM,EAAE,uBAAuB;CAC/B,OAAO,OAAO,uBAAuB;AACvC"}

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@prisma-next/sql-contract",
-  "version": "0.14.0-dev.80",
+  "version": "0.14.0-dev.82",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "SQL contract types, validators, and IR factories for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.14.0-dev.80",
-    "@prisma-next/framework-components": "0.14.0-dev.80",
-    "@prisma-next/utils": "0.14.0-dev.80",
+    "@prisma-next/contract": "0.14.0-dev.82",
+    "@prisma-next/framework-components": "0.14.0-dev.82",
+    "@prisma-next/utils": "0.14.0-dev.82",
     "arktype": "^2.2.2"
   },
   "devDependencies": {
-    "@prisma-next/test-utils": "0.14.0-dev.80",
-    "@prisma-next/tsconfig": "0.14.0-dev.80",
-    "@prisma-next/tsdown": "0.14.0-dev.80",
+    "@prisma-next/test-utils": "0.14.0-dev.82",
+    "@prisma-next/tsconfig": "0.14.0-dev.82",
+    "@prisma-next/tsdown": "0.14.0-dev.82",
     "tsdown": "0.22.3",
     "typescript": "5.9.3",
     "vitest": "4.1.10"
@@ -34,6 +34,7 @@
   "exports": {
     "./canonicalization-hooks": "./dist/canonicalization-hooks.mjs",
     "./contract-view": "./dist/contract-view.mjs",
+    "./entity-handle-lowering-hook": "./dist/entity-handle-lowering-hook.mjs",
     "./entity-kinds": "./dist/entity-kinds.mjs",
     "./factories": "./dist/factories.mjs",
     "./index-type-validation": "./dist/index-type-validation.mjs",

package/src/entity-handle-lowering-hook.ts

@@ -0,0 +1,104 @@
+/**
+ * SQL-family extension to the pack authoring contributions: a pack whose
+ * `entityTypes` registers entity kinds may implement a batch lowering hook
+ * that turns author-declared pack-entity handles (the generic `entities`
+ * list on the TS contract input) into `entries` rows.
+ *
+ * The generic contract build (`contract-ts`) owns the kind-agnostic walk: it
+ * groups handles by the pack that registered each `entityKind`, resolves
+ * each handle's declared model refs to storage table coordinates using the
+ * same model→table maps the relation lowering uses, and calls the owning
+ * pack's hook once with all of its claimed handles — batch, so the hook's
+ * diagnostics can see sibling handles. Neither the walk nor these types name
+ * any specific entity kind.
+ *
+ * SQL-family concept — the resolved-ref shape is a table coordinate, so the
+ * hook lives here beside {@link ../value-set-derivation-hook} instead of on
+ * the framework contributions type.
+ */
+
+/**
+ * An authored pack-entity handle: branded by the `entityKind` its owning
+ * pack registered, optionally declaring model refs under `refs` (actual
+ * model-handle objects, resolved by the generic walk before lowering).
+ */
+export interface PackEntityHandle {
+  readonly entityKind: string;
+  readonly refs?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * A declared model ref after the generic walk resolved it: a storage table
+ * coordinate for a model of this contract, the coordinate plus `spaceId` for
+ * a cross-space (extensionModel) handle, or `unresolved` when the handle
+ * does not correspond to any model in the contract. `modelName` is carried
+ * for diagnostics where the handle declares one.
+ */
+export type ResolvedEntityHandleRef =
+  | {
+      readonly kind: 'resolved';
+      readonly namespaceId: string;
+      readonly tableName: string;
+      readonly modelName?: string;
+    }
+  | {
+      readonly kind: 'cross-space';
+      readonly spaceId: string;
+      readonly namespaceId: string;
+      readonly tableName: string;
+      readonly modelName?: string;
+    }
+  | {
+      readonly kind: 'unresolved';
+      readonly modelName?: string;
+    };
+
+/** One claimed handle paired with its resolved declared refs. */
+export interface ResolvedPackEntityHandle {
+  readonly handle: PackEntityHandle;
+  readonly refs: Readonly<Record<string, ResolvedEntityHandleRef>>;
+}
+
+export interface EntityHandleLoweringInput {
+  /** Every handle in the `entities` list whose `entityKind` this pack registered, in authored order. */
+  readonly handles: readonly ResolvedPackEntityHandle[];
+  readonly defaultNamespaceId: string;
+}
+
+/** One lowered entity row: filed into `storage.namespaces[namespaceId].entries[entityKind][key]`. */
+export interface LoweredPackEntity {
+  readonly namespaceId: string;
+  readonly entityKind: string;
+  readonly key: string;
+  readonly entity: unknown;
+}
+
+export interface SqlEntityHandleLoweringContribution {
+  /**
+   * Method syntax keeps the declaration bivariant, so a pack's concretely
+   * typed implementation stays structurally compatible (the same convention
+   * as `SqlValueSetDerivingEntityTypeOutput.deriveValueSet`).
+   */
+  lowerEntityHandles(input: EntityHandleLoweringInput): readonly LoweredPackEntity[];
+}
+
+/** Structural check for {@link SqlEntityHandleLoweringContribution}: no casts. */
+export function providesEntityHandleLowering(
+  authoring: unknown,
+): authoring is SqlEntityHandleLoweringContribution {
+  if (typeof authoring !== 'object' || authoring === null || !('lowerEntityHandles' in authoring)) {
+    return false;
+  }
+  const { lowerEntityHandles } = authoring;
+  return typeof lowerEntityHandles === 'function';
+}
+
+/**
+ * PSL-side twin of {@link ResolvedEntityHandleRef}: the family interpreter
+ * resolves an extension block's descriptor-declared model ref parameters
+ * (`{ kind: 'ref', refKind: 'model' }`) to storage table names and annotates
+ * the block with this map (keyed by parameter name) before invoking the
+ * entity factory. An unresolved required ref is the interpreter's
+ * diagnostic; a factory never sees one.
+ */
+export type ResolvedPslModelRefs = Readonly<Record<string, { readonly tableName: string }>>;

package/src/exports/entity-handle-lowering-hook.ts

@@ -0,0 +1,10 @@
+export {
+  type EntityHandleLoweringInput,
+  type LoweredPackEntity,
+  type PackEntityHandle,
+  providesEntityHandleLowering,
+  type ResolvedEntityHandleRef,
+  type ResolvedPackEntityHandle,
+  type ResolvedPslModelRefs,
+  type SqlEntityHandleLoweringContribution,
+} from '../entity-handle-lowering-hook';