@prisma-next/sql-contract-ts 0.3.0-dev.16 → 0.3.0-dev.162

package/schemas/data-contract-sql-v1.json

@@ -24,10 +24,10 @@
       "enum": ["sql"],
       "description": "Target family classification"
     },
-    "coreHash": {
+    "storageHash": {
       "type": "string",
       "pattern": "^sha256:[a-f0-9]{64}$",
-      "description": "SHA-256 hash of the core schema structure (models, fields, relations, storage layout)"
+      "description": "SHA-256 hash of the storage section (DB-satisfied expectations)"
     },
     "profileHash": {
       "type": "string",
@@ -44,7 +44,7 @@
         }
       }
     },
-    "extensions": {
+    "extensionPacks": {
       "type": "object",
       "description": "Extension packs and their configuration",
       "additionalProperties": true
@@ -61,6 +61,13 @@
         "$ref": "#/$defs/Source"
       }
     },
+    "roots": {
+      "type": "object",
+      "description": "Mapping of root model names to their identifiers",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
     "models": {
       "type": "object",
       "description": "Model definitions mapping application-level models to storage tables",
@@ -79,12 +86,51 @@
           "additionalProperties": {
             "$ref": "#/$defs/StorageTable"
           }
+        },
+        "types": {
+          "type": "object",
+          "description": "Named type instances for parameterized/custom types (e.g., vectors, enums)",
+          "additionalProperties": {
+            "$ref": "#/$defs/StorageTypeInstance"
+          }
         }
       },
       "required": ["tables"]
+    },
+    "execution": {
+      "type": "object",
+      "description": "Execution-only behavior not satisfied by the database",
+      "additionalProperties": false,
+      "properties": {
+        "executionHash": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$",
+          "description": "SHA-256 hash of the execution section (client-side behavior)"
+        },
+        "mutations": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "defaults": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/ExecutionMutationDefault" }
+            }
+          },
+          "required": ["defaults"]
+        }
+      },
+      "required": ["executionHash", "mutations"]
     }
   },
-  "required": ["schemaVersion", "target", "targetFamily", "coreHash", "models", "storage"],
+  "required": [
+    "schemaVersion",
+    "target",
+    "targetFamily",
+    "storageHash",
+    "models",
+    "storage",
+    "roots"
+  ],
   "$defs": {
     "StorageTable": {
       "type": "object",
@@ -126,21 +172,142 @@
       },
       "required": ["columns"]
     },
+    "ColumnDefault": {
+      "description": "Column default value. Can be a literal value or a database function expression.",
+      "oneOf": [
+        {
+          "type": "object",
+          "description": "Static literal value",
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": ["literal"]
+            },
+            "value": {
+              "description": "JSON literal value (or tagged bigint) for the default value",
+              "oneOf": [
+                { "type": "string" },
+                { "type": "number" },
+                { "type": "boolean" },
+                { "type": "null" },
+                { "type": "array" },
+                { "type": "object" }
+              ]
+            }
+          },
+          "required": ["kind", "value"]
+        },
+        {
+          "type": "object",
+          "description": "Database function expression (e.g., 'autoincrement()', 'now()', 'gen_random_uuid()')",
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": ["function"]
+            },
+            "expression": {
+              "type": "string",
+              "description": "The function expression (e.g., 'autoincrement()', 'now()', 'gen_random_uuid()')"
+            }
+          },
+          "required": ["kind", "expression"]
+        }
+      ]
+    },
+    "ExecutionMutationDefaultValue": {
+      "type": "object",
+      "description": "Execution-time default value applied before a write",
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["generator"]
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$"
+        },
+        "params": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      },
+      "required": ["kind", "id"]
+    },
+    "ExecutionMutationDefault": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "ref": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "table": { "type": "string" },
+            "column": { "type": "string" }
+          },
+          "required": ["table", "column"]
+        },
+        "onCreate": { "$ref": "#/$defs/ExecutionMutationDefaultValue" },
+        "onUpdate": { "$ref": "#/$defs/ExecutionMutationDefaultValue" }
+      },
+      "required": ["ref"]
+    },
     "StorageColumn": {
       "type": "object",
-      "description": "Column definition with type and nullability",
+      "description": "Column definition with type, nullability, and optional parameterized type info",
       "additionalProperties": false,
       "properties": {
-        "type": {
+        "nativeType": {
+          "type": "string",
+          "description": "Database-native type (e.g., 'text', 'int4', 'timestamptz', 'vector(1536)')"
+        },
+        "codecId": {
           "type": "string",
-          "description": "Column type (e.g., 'text', 'int4', 'timestamptz', 'bool')"
+          "description": "Codec identifier for encoding/decoding (e.g., 'pg/text@1', 'pg/vector@1')"
         },
         "nullable": {
           "type": "boolean",
           "default": false,
           "description": "Whether the column allows NULL values"
+        },
+        "typeParams": {
+          "type": "object",
+          "description": "Opaque, codec-owned JS/type parameters (e.g., { length: 1536 } for vectors)",
+          "additionalProperties": true
+        },
+        "typeRef": {
+          "type": "string",
+          "description": "Reference to a named type instance in storage.types"
+        },
+        "default": {
+          "$ref": "#/$defs/ColumnDefault",
+          "description": "Default value for the column"
         }
-      }
+      },
+      "required": ["nativeType", "codecId", "nullable"]
+    },
+    "StorageTypeInstance": {
+      "type": "object",
+      "description": "Named, parameterized type instance for reuse across columns",
+      "additionalProperties": false,
+      "properties": {
+        "codecId": {
+          "type": "string",
+          "description": "Codec identifier for encoding/decoding"
+        },
+        "nativeType": {
+          "type": "string",
+          "description": "Database-native type"
+        },
+        "typeParams": {
+          "type": "object",
+          "description": "Codec-owned type parameters",
+          "additionalProperties": true
+        }
+      },
+      "required": ["codecId", "nativeType", "typeParams"]
     },
     "PrimaryKey": {
       "type": "object",
@@ -234,9 +401,17 @@
         "name": {
           "type": "string",
           "description": "Foreign key constraint name"
+        },
+        "constraint": {
+          "type": "boolean",
+          "description": "Whether to emit FK constraint DDL (ALTER TABLE … ADD CONSTRAINT … FOREIGN KEY)"
+        },
+        "index": {
+          "type": "boolean",
+          "description": "Whether to emit a backing index for the FK columns"
         }
       },
-      "required": ["columns", "references"]
+      "required": ["columns", "references", "constraint", "index"]
     },
     "FieldType": {
       "type": "object",
@@ -310,13 +485,20 @@
             "table": {
               "type": "string",
               "description": "Table name in storage.tables"
+            },
+            "fields": {
+              "type": "object",
+              "description": "Per-field storage mappings",
+              "additionalProperties": {
+                "$ref": "#/$defs/ModelStorageField"
+              }
             }
           },
           "required": ["table"]
         },
         "fields": {
           "type": "object",
-          "description": "Field definitions mapping model fields to storage columns",
+          "description": "Domain field metadata (codecId, nullable)",
           "additionalProperties": {
             "$ref": "#/$defs/ModelField"
           }
@@ -327,26 +509,53 @@
           "additionalProperties": {
             "$ref": "#/$defs/ModelRelation"
           }
+        },
+        "owner": {
+          "type": "string",
+          "description": "Owner model name — declares this model belongs to another model's aggregate (per ADR 177)"
         }
       },
       "required": ["storage", "fields"]
     },
     "ModelField": {
       "type": "object",
-      "description": "Model field definition mapping to storage column",
+      "description": "Domain field definition (codec and nullability; column mapping lives in model.storage.fields)",
+      "additionalProperties": false,
+      "properties": {
+        "codecId": {
+          "type": "string",
+          "description": "Codec identifier for the field"
+        },
+        "nullable": {
+          "type": "boolean",
+          "description": "Whether the field allows NULL values"
+        }
+      },
+      "required": ["codecId", "nullable"]
+    },
+    "ModelStorageField": {
+      "type": "object",
+      "description": "Per-field storage mapping",
       "additionalProperties": false,
       "properties": {
         "column": {
           "type": "string",
           "description": "Column name in the model's backing table"
+        },
+        "codecId": {
+          "type": "string",
+          "description": "Codec identifier for the field (derived from storage column)"
+        },
+        "nullable": {
+          "type": "boolean",
+          "description": "Whether the field allows NULL values (derived from storage column)"
         }
       },
       "required": ["column"]
     },
     "ModelRelation": {
       "type": "object",
-      "description": "Model relation definition",
-      "additionalProperties": false,
+      "description": "Model relation definition (domain format with localFields/targetFields)",
       "properties": {
         "to": {
           "type": "string",
@@ -357,30 +566,29 @@
           "enum": ["1:1", "1:N", "N:1", "N:M"],
           "description": "Relation cardinality"
         },
+        "strategy": {
+          "type": "string",
+          "enum": ["reference", "embed"],
+          "description": "Relation strategy"
+        },
         "on": {
           "type": "object",
           "description": "Relation field mappings",
-          "additionalProperties": false,
           "properties": {
-            "parentCols": {
+            "localFields": {
               "type": "array",
-              "description": "Parent table columns",
-              "items": {
-                "type": "string"
-              }
+              "description": "Local model fields",
+              "items": { "type": "string" }
             },
-            "childCols": {
+            "targetFields": {
               "type": "array",
-              "description": "Child table columns",
-              "items": {
-                "type": "string"
-              }
+              "description": "Target model fields",
+              "items": { "type": "string" }
             }
-          },
-          "required": ["parentCols", "childCols"]
+          }
         }
       },
-      "required": ["to", "cardinality", "on"]
+      "required": ["to", "cardinality"]
     }
   }
 }

package/src/authoring-helper-runtime.ts

@@ -0,0 +1,139 @@
+import type {
+  AuthoringFieldNamespace,
+  AuthoringFieldPresetDescriptor,
+  AuthoringTypeNamespace,
+} from '@prisma-next/framework-components/authoring';
+import {
+  instantiateAuthoringTypeConstructor,
+  isAuthoringFieldPresetDescriptor,
+  isAuthoringTypeConstructorDescriptor,
+  validateAuthoringHelperArguments,
+} from '@prisma-next/framework-components/authoring';
+import type { StorageTypeInstance } from '@prisma-next/sql-contract/types';
+
+export type RuntimeNamedConstraintSpec = {
+  readonly name?: string;
+};
+
+export function isNamedConstraintOptionsLike(value: unknown): value is RuntimeNamedConstraintSpec {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false;
+  }
+
+  const keys = Object.keys(value as Record<string, unknown>);
+  if (keys.some((key) => key !== 'name')) {
+    return false;
+  }
+
+  const name = (value as { readonly name?: unknown }).name;
+  return name === undefined || typeof name === 'string';
+}
+
+const blockedSegments = new Set(['__proto__', 'constructor', 'prototype']);
+
+function assertSafeHelperKey(key: string, path: readonly string[]): void {
+  if (blockedSegments.has(key)) {
+    throw new Error(
+      `Invalid authoring helper "${[...path, key].join('.')}". Helper path segments must not use "${key}".`,
+    );
+  }
+}
+
+export function createTypeHelpersFromNamespace(
+  namespace: AuthoringTypeNamespace,
+  path: readonly string[] = [],
+): Record<string, unknown> {
+  const helpers: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(namespace)) {
+    assertSafeHelperKey(key, path);
+    const currentPath = [...path, key];
+
+    if (isAuthoringTypeConstructorDescriptor(value)) {
+      const helperPath = currentPath.join('.');
+      helpers[key] = (...args: readonly unknown[]) => {
+        validateAuthoringHelperArguments(helperPath, value.args, args);
+        return instantiateAuthoringTypeConstructor(value, args) as StorageTypeInstance;
+      };
+      continue;
+    }
+
+    helpers[key] = createTypeHelpersFromNamespace(value as AuthoringTypeNamespace, currentPath);
+  }
+
+  return helpers;
+}
+
+export function createFieldPresetHelper<Result>(options: {
+  readonly helperPath: string;
+  readonly descriptor: AuthoringFieldPresetDescriptor;
+  readonly build: (options: {
+    readonly args: readonly unknown[];
+    readonly namedConstraintOptions?: RuntimeNamedConstraintSpec;
+  }) => Result;
+}): (...rawArgs: readonly unknown[]) => Result {
+  return (...rawArgs: readonly unknown[]) => {
+    const acceptsNamedConstraintOptions =
+      options.descriptor.output.id === true || options.descriptor.output.unique === true;
+    const declaredArguments = options.descriptor.args ?? [];
+
+    if (acceptsNamedConstraintOptions && rawArgs.length > declaredArguments.length + 1) {
+      throw new Error(
+        `${options.helperPath} expects at most ${declaredArguments.length + 1} argument(s), received ${rawArgs.length}`,
+      );
+    }
+
+    let args = rawArgs;
+    let namedConstraintOptions: RuntimeNamedConstraintSpec | undefined;
+
+    if (acceptsNamedConstraintOptions && rawArgs.length === declaredArguments.length + 1) {
+      const maybeNamedConstraintOptions = rawArgs.at(-1);
+      if (!isNamedConstraintOptionsLike(maybeNamedConstraintOptions)) {
+        throw new Error(
+          `${options.helperPath} accepts an optional trailing { name?: string } constraint options object`,
+        );
+      }
+      namedConstraintOptions = maybeNamedConstraintOptions;
+      args = rawArgs.slice(0, -1);
+    }
+
+    validateAuthoringHelperArguments(options.helperPath, options.descriptor.args, args);
+
+    return options.build({
+      args,
+      ...(namedConstraintOptions ? { namedConstraintOptions } : {}),
+    });
+  };
+}
+
+export function createFieldHelpersFromNamespace(
+  namespace: AuthoringFieldNamespace,
+  createLeafHelper: (options: {
+    readonly helperPath: string;
+    readonly descriptor: AuthoringFieldPresetDescriptor;
+  }) => (...rawArgs: readonly unknown[]) => unknown,
+  path: readonly string[] = [],
+): Record<string, unknown> {
+  const helpers: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(namespace)) {
+    assertSafeHelperKey(key, path);
+    const currentPath = [...path, key];
+
+    if (isAuthoringFieldPresetDescriptor(value)) {
+      helpers[key] = createLeafHelper({
+        helperPath: currentPath.join('.'),
+        descriptor: value,
+      });
+      continue;
+    }
+
+    helpers[key] = createFieldHelpersFromNamespace(
+      value as AuthoringFieldNamespace,
+      createLeafHelper,
+      currentPath,
+    );
+  }
+
+  return helpers;
+}

package/src/authoring-type-utils.ts

@@ -0,0 +1,168 @@
+import type {
+  AuthoringArgumentDescriptor,
+  AuthoringFieldPresetDescriptor,
+} from '@prisma-next/framework-components/authoring';
+import type { ScalarFieldBuilder, ScalarFieldState } from './contract-dsl';
+
+export type UnionToIntersection<U> = (U extends unknown ? (value: U) => void : never) extends (
+  value: infer I,
+) => void
+  ? I
+  : never;
+
+export type NamedConstraintSpec<Name extends string | undefined = string | undefined> = {
+  readonly name?: Name;
+};
+
+export type NamedConstraintState<
+  Enabled extends boolean,
+  Name extends string | undefined = undefined,
+> = Enabled extends true ? NamedConstraintSpec<Name> : undefined;
+
+export type OptionalObjectArgumentKeys<
+  Properties extends Record<string, AuthoringArgumentDescriptor>,
+> = {
+  readonly [K in keyof Properties]: Properties[K] extends { readonly optional: true } ? K : never;
+}[keyof Properties];
+
+export type ObjectArgumentType<Properties extends Record<string, AuthoringArgumentDescriptor>> = {
+  readonly [K in Exclude<
+    keyof Properties,
+    OptionalObjectArgumentKeys<Properties>
+  >]: ArgTypeFromDescriptor<Properties[K]>;
+} & {
+  readonly [K in OptionalObjectArgumentKeys<Properties>]?: ArgTypeFromDescriptor<Properties[K]>;
+};
+
+export type ArgTypeFromDescriptor<Arg extends AuthoringArgumentDescriptor> = Arg extends {
+  readonly kind: 'string';
+}
+  ? string
+  : Arg extends { readonly kind: 'number' }
+    ? number
+    : Arg extends { readonly kind: 'stringArray' }
+      ? readonly string[]
+      : Arg extends {
+            readonly kind: 'object';
+            readonly properties: infer Properties extends Record<
+              string,
+              AuthoringArgumentDescriptor
+            >;
+          }
+        ? ObjectArgumentType<Properties>
+        : never;
+
+export type TupleFromArgumentDescriptors<Args extends readonly AuthoringArgumentDescriptor[]> = {
+  readonly [K in keyof Args]: Args[K] extends AuthoringArgumentDescriptor
+    ? ArgTypeFromDescriptor<Args[K]>
+    : never;
+};
+
+export type SupportsNamedConstraintOptions<Descriptor extends AuthoringFieldPresetDescriptor> =
+  Descriptor['output'] extends { readonly id: true }
+    ? true
+    : Descriptor['output'] extends { readonly unique: true }
+      ? true
+      : false;
+
+export type ResolveTemplateValue<Template, Args extends readonly unknown[]> = Template extends {
+  readonly kind: 'arg';
+  readonly index: infer Index extends number;
+  readonly path?: infer Path extends readonly string[] | undefined;
+  readonly default?: infer Default;
+}
+  ? ResolveTemplateArgValue<Args[Index], Path, Default, Args>
+  : Template extends readonly unknown[]
+    ? { readonly [K in keyof Template]: ResolveTemplateValue<Template[K], Args> }
+    : Template extends Record<string, unknown>
+      ? { readonly [K in keyof Template]: ResolveTemplateValue<Template[K], Args> }
+      : Template;
+
+type ResolveTemplatePathValue<
+  Value,
+  Path extends readonly string[] | undefined,
+> = Path extends readonly [infer Segment extends string, ...infer Rest extends readonly string[]]
+  ? Segment extends keyof NonNullable<Value>
+    ? ResolveTemplatePathValue<NonNullable<Value>[Segment], Rest>
+    : never
+  : Value;
+
+type ResolveTemplateDefaultValue<
+  Value,
+  Default,
+  Args extends readonly unknown[],
+> = Default extends undefined
+  ? Value
+  : [Value] extends [never]
+    ? ResolveTemplateValue<Default, Args>
+    : undefined extends Value
+      ? Exclude<Value, undefined> | ResolveTemplateValue<Default, Args>
+      : Value;
+
+type ResolveTemplateArgValue<
+  Value,
+  Path extends readonly string[] | undefined,
+  Default,
+  Args extends readonly unknown[],
+> = ResolveTemplateDefaultValue<ResolveTemplatePathValue<Value, Path>, Default, Args>;
+
+export type FieldBuilderFromPresetDescriptor<
+  Descriptor extends AuthoringFieldPresetDescriptor,
+  Args extends readonly unknown[] = readonly [],
+  ConstraintName extends string | undefined = undefined,
+> = ScalarFieldBuilder<
+  ScalarFieldState<
+    ResolveTemplateValue<Descriptor['output']['codecId'], Args> extends string
+      ? ResolveTemplateValue<Descriptor['output']['codecId'], Args>
+      : string,
+    undefined,
+    ResolveTemplateValue<Descriptor['output']['nullable'], Args> extends true ? true : false,
+    undefined,
+    NamedConstraintState<
+      ResolveTemplateValue<Descriptor['output']['id'], Args> extends true ? true : false,
+      ConstraintName
+    >,
+    NamedConstraintState<
+      ResolveTemplateValue<Descriptor['output']['unique'], Args> extends true ? true : false,
+      ConstraintName
+    >
+  >
+>;
+
+export type FieldHelperFunctionWithoutNamedConstraint<
+  Descriptor extends AuthoringFieldPresetDescriptor,
+> = Descriptor extends {
+  readonly args: infer Args extends readonly AuthoringArgumentDescriptor[];
+}
+  ? <const Params extends TupleFromArgumentDescriptors<Args>>(
+      ...args: Params
+    ) => FieldBuilderFromPresetDescriptor<Descriptor, Params>
+  : () => FieldBuilderFromPresetDescriptor<Descriptor, readonly []>;
+
+export type FieldHelperFunctionWithNamedConstraint<
+  Descriptor extends AuthoringFieldPresetDescriptor,
+> = Descriptor extends {
+  readonly args: infer Args extends readonly AuthoringArgumentDescriptor[];
+}
+  ? <
+      const Params extends TupleFromArgumentDescriptors<Args>,
+      const Name extends string | undefined = undefined,
+    >(
+      ...args: [...params: Params, options?: NamedConstraintSpec<Name>]
+    ) => FieldBuilderFromPresetDescriptor<Descriptor, Params, Name>
+  : <const Name extends string | undefined = undefined>(
+      options?: NamedConstraintSpec<Name>,
+    ) => FieldBuilderFromPresetDescriptor<Descriptor, readonly [], Name>;
+
+export type FieldHelperFunction<Descriptor extends AuthoringFieldPresetDescriptor> =
+  SupportsNamedConstraintOptions<Descriptor> extends true
+    ? FieldHelperFunctionWithNamedConstraint<Descriptor>
+    : FieldHelperFunctionWithoutNamedConstraint<Descriptor>;
+
+export type FieldHelpersFromNamespace<Namespace> = {
+  readonly [K in keyof Namespace]: Namespace[K] extends AuthoringFieldPresetDescriptor
+    ? FieldHelperFunction<Namespace[K]>
+    : Namespace[K] extends Record<string, unknown>
+      ? FieldHelpersFromNamespace<Namespace[K]>
+      : never;
+};