@prisma-next/contract 0.3.0-dev.33 → 0.3.0-dev.35

package/src/types.ts

@@ -1,17 +1,76 @@
 import type { OperationRegistry } from '@prisma-next/operations';
-import type { RenderTypeContext } from './framework-components';
 import type { ContractIR } from './ir';
 
-export interface ContractBase {
+/**
+ * Unique symbol used as the key for branding types.
+ */
+export const $: unique symbol = Symbol('__prisma_next_brand__');
+
+/**
+ * A helper type to brand a given type with a unique identifier.
+ *
+ * @template TKey Text used as the brand key.
+ * @template TValue Optional value associated with the brand key. Defaults to `true`.
+ */
+export type Brand<TKey extends string | number | symbol, TValue = true> = {
+  [$]: {
+    [K in TKey]: TValue;
+  };
+};
+
+/**
+ * Context passed to type renderers during contract.d.ts generation.
+ */
+export interface RenderTypeContext {
+  /** The name of the CodecTypes type alias (typically 'CodecTypes') */
+  readonly codecTypesName: string;
+}
+
+/**
+ * Base type for storage contract hashes.
+ * Emitted contract.d.ts files use this with the hash value as a type parameter:
+ * `type StorageHash = StorageHashBase<'sha256:abc123...'>`
+ */
+export type StorageHashBase<THash extends string> = THash & Brand<'StorageHash'>;
+
+/**
+ * Base type for execution contract hashes.
+ * Emitted contract.d.ts files use this with the hash value as a type parameter:
+ * `type ExecutionHash = ExecutionHashBase<'sha256:def456...'>`
+ */
+export type ExecutionHashBase<THash extends string> = THash & Brand<'ExecutionHash'>;
+
+export function coreHash<const T extends string>(value: T): StorageHashBase<T> {
+  return value as StorageHashBase<T>;
+}
+
+/**
+ * Base type for profile contract hashes.
+ * Emitted contract.d.ts files use this with the hash value as a type parameter:
+ * `type ProfileHash = ProfileHashBase<'sha256:def456...'>`
+ */
+export type ProfileHashBase<THash extends string> = THash & Brand<'ProfileHash'>;
+
+export function profileHash<const T extends string>(value: T): ProfileHashBase<T> {
+  return value as ProfileHashBase<T>;
+}
+
+export interface ContractBase<
+  TStorageHash extends StorageHashBase<string> = StorageHashBase<string>,
+  TExecutionHash extends ExecutionHashBase<string> = ExecutionHashBase<string>,
+  TProfileHash extends ProfileHashBase<string> = ProfileHashBase<string>,
+> {
   readonly schemaVersion: string;
   readonly target: string;
   readonly targetFamily: string;
-  readonly coreHash: string;
-  readonly profileHash?: string;
+  readonly storageHash: TStorageHash;
+  readonly executionHash?: TExecutionHash | undefined;
+  readonly profileHash?: TProfileHash | undefined;
   readonly capabilities: Record<string, Record<string, boolean>>;
   readonly extensionPacks: Record<string, unknown>;
   readonly meta: Record<string, unknown>;
   readonly sources: Record<string, Source>;
+  readonly execution?: ExecutionSection;
 }
 
 export interface FieldType {
@@ -21,6 +80,36 @@ export interface FieldType {
   readonly properties?: Record<string, FieldType>;
 }
 
+export type GeneratedValueSpec = {
+  readonly id: 'ulid' | 'nanoid' | 'uuidv7' | 'uuidv4' | 'cuid2' | 'ksuid';
+  readonly params?: Record<string, unknown>;
+};
+
+export type ColumnDefault =
+  | {
+      readonly kind: 'literal';
+      readonly expression: string;
+    }
+  | { readonly kind: 'function'; readonly expression: string };
+
+export type ExecutionMutationDefaultValue = {
+  readonly kind: 'generator';
+  readonly id: GeneratedValueSpec['id'];
+  readonly params?: Record<string, unknown>;
+};
+
+export type ExecutionMutationDefault = {
+  readonly ref: { readonly table: string; readonly column: string };
+  readonly onCreate?: ExecutionMutationDefaultValue;
+  readonly onUpdate?: ExecutionMutationDefaultValue;
+};
+
+export type ExecutionSection = {
+  readonly mutations: {
+    readonly defaults: ReadonlyArray<ExecutionMutationDefault>;
+  };
+};
+
 export interface Source {
   readonly readOnly: boolean;
   readonly projection: Record<string, FieldType>;
@@ -43,7 +132,7 @@ export type Expr =
 export interface DocCollection {
   readonly name: string;
   readonly id?: {
-    readonly strategy: 'auto' | 'client' | 'uuid' | 'cuid' | 'objectId';
+    readonly strategy: 'auto' | 'client' | 'uuid' | 'objectId';
   };
   readonly fields: Record<string, FieldType>;
   readonly indexes?: ReadonlyArray<DocIndex>;
@@ -56,7 +145,11 @@ export interface DocumentStorage {
   };
 }
 
-export interface DocumentContract extends ContractBase {
+export interface DocumentContract<
+  TStorageHash extends StorageHashBase<string> = StorageHashBase<string>,
+  TExecutionHash extends ExecutionHashBase<string> = ExecutionHashBase<string>,
+  TProfileHash extends ProfileHashBase<string> = ProfileHashBase<string>,
+> extends ContractBase<TStorageHash, TExecutionHash, TProfileHash> {
   // Accept string to work with JSON imports; runtime validation ensures 'document'
   readonly targetFamily: string;
   readonly storage: DocumentStorage;
@@ -86,7 +179,7 @@ export interface PlanRefs {
 export interface PlanMeta {
   readonly target: string;
   readonly targetFamily?: string;
-  readonly coreHash: string;
+  readonly storageHash: string;
   readonly profileHash?: string;
   readonly lane: string;
   readonly annotations?: {
@@ -152,7 +245,7 @@ export function isDocumentContract(contract: unknown): contract is DocumentContr
  * Represents the current contract identity for a database.
  */
 export interface ContractMarkerRecord {
-  readonly coreHash: string;
+  readonly storageHash: string;
   readonly profileHash: string;
   readonly contractJson: unknown | null;
   readonly canonicalVersion: number | null;
@@ -247,6 +340,7 @@ export interface TargetFamilyHook {
    * @param ir - Contract IR
    * @param codecTypeImports - Array of codec type import specs
    * @param operationTypeImports - Array of operation type import specs
+   * @param hashes - Contract hash values (storageHash, executionHash, profileHash)
    * @param options - Additional options including parameterized type renderers
    * @returns Generated TypeScript type definitions as string
    */
@@ -254,35 +348,15 @@ export interface TargetFamilyHook {
     ir: ContractIR,
     codecTypeImports: ReadonlyArray<TypesImportSpec>,
     operationTypeImports: ReadonlyArray<TypesImportSpec>,
+    hashes: {
+      readonly storageHash: string;
+      readonly executionHash?: string;
+      readonly profileHash: string;
+    },
     options?: GenerateContractTypesOptions,
   ): string;
 }
 
-// Extension pack manifest types - moved from @prisma-next/core-control-plane to shared location
-export type ArgSpecManifest =
-  | { readonly kind: 'typeId'; readonly type: string }
-  | { readonly kind: 'param' }
-  | { readonly kind: 'literal' };
-
-export type ReturnSpecManifest =
-  | { readonly kind: 'typeId'; readonly type: string }
-  | { readonly kind: 'builtin'; readonly type: 'number' | 'boolean' | 'string' };
-
-export interface LoweringSpecManifest {
-  readonly targetFamily: 'sql';
-  readonly strategy: 'infix' | 'function';
-  readonly template: string;
-}
-
-export interface OperationManifest {
-  readonly for: string;
-  readonly method: string;
-  readonly args: ReadonlyArray<ArgSpecManifest>;
-  readonly returns: ReturnSpecManifest;
-  readonly lowering: LoweringSpecManifest;
-  readonly capabilities?: ReadonlyArray<string>;
-}
-
 // ============================================================================
 // Parameterized Codec Descriptor Types
 // ============================================================================
@@ -293,9 +367,6 @@ export interface OperationManifest {
 //
 // ============================================================================
 
-// Re-export RenderTypeContext so it's available alongside TypeRenderer
-export type { RenderTypeContext };
-
 /**
  * Declarative type renderer that produces a TypeScript type expression.
  *