@prisma-next/sql-contract-ts 0.3.0-dev.134 → 0.3.0-dev.135

package/src/authoring-helper-runtime.ts

@@ -0,0 +1,139 @@
+import type {
+  AuthoringFieldNamespace,
+  AuthoringFieldPresetDescriptor,
+  AuthoringTypeNamespace,
+} from '@prisma-next/contract/framework-components';
+import {
+  instantiateAuthoringTypeConstructor,
+  isAuthoringFieldPresetDescriptor,
+  isAuthoringTypeConstructorDescriptor,
+  validateAuthoringHelperArguments,
+} from '@prisma-next/contract/framework-components';
+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/contract/framework-components';
+import type { ScalarFieldBuilder, ScalarFieldState } from './staged-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;
+};

package/src/composed-authoring-helpers.ts

@@ -0,0 +1,254 @@
+import type {
+  AuthoringArgumentDescriptor,
+  AuthoringFieldNamespace,
+  AuthoringTypeConstructorDescriptor,
+  AuthoringTypeNamespace,
+  ExtensionPackRef,
+  FamilyPackRef,
+  TargetPackRef,
+} from '@prisma-next/contract/framework-components';
+import {
+  isAuthoringFieldPresetDescriptor,
+  isAuthoringTypeConstructorDescriptor,
+} from '@prisma-next/contract/framework-components';
+import {
+  createFieldHelpersFromNamespace,
+  createFieldPresetHelper,
+  createTypeHelpersFromNamespace,
+} from './authoring-helper-runtime';
+import type {
+  FieldHelpersFromNamespace,
+  ResolveTemplateValue,
+  TupleFromArgumentDescriptors,
+  UnionToIntersection,
+} from './authoring-type-utils';
+import { buildFieldPreset, field, model, rel } from './staged-contract-dsl';
+
+type ExtractTypeNamespaceFromPack<Pack> = Pack extends {
+  readonly authoring?: { readonly type?: infer Namespace extends AuthoringTypeNamespace };
+}
+  ? Namespace
+  : Record<never, never>;
+
+type ExtractFieldNamespaceFromPack<Pack> = Pack extends {
+  readonly authoring?: { readonly field?: infer Namespace extends AuthoringFieldNamespace };
+}
+  ? Namespace
+  : Record<never, never>;
+
+type MergeExtensionTypeNamespaces<ExtensionPacks> =
+  ExtensionPacks extends Record<string, unknown>
+    ? keyof ExtensionPacks extends never
+      ? Record<never, never>
+      : UnionToIntersection<
+          {
+            [K in keyof ExtensionPacks]: ExtractTypeNamespaceFromPack<ExtensionPacks[K]>;
+          }[keyof ExtensionPacks]
+        >
+    : Record<never, never>;
+
+type MergeExtensionFieldNamespaces<ExtensionPacks> =
+  ExtensionPacks extends Record<string, unknown>
+    ? keyof ExtensionPacks extends never
+      ? Record<never, never>
+      : UnionToIntersection<
+          {
+            [K in keyof ExtensionPacks]: ExtractFieldNamespaceFromPack<ExtensionPacks[K]>;
+          }[keyof ExtensionPacks]
+        >
+    : Record<never, never>;
+
+type StorageTypeFromDescriptor<
+  Descriptor extends AuthoringTypeConstructorDescriptor,
+  Args extends readonly unknown[],
+> = {
+  readonly codecId: ResolveTemplateValue<Descriptor['output']['codecId'], Args>;
+  readonly nativeType: ResolveTemplateValue<Descriptor['output']['nativeType'], Args>;
+} & (Descriptor['output'] extends {
+  readonly typeParams: infer TypeParams extends Record<string, unknown>;
+}
+  ? {
+      readonly typeParams: ResolveTemplateValue<TypeParams, Args>;
+    }
+  : Record<never, never>);
+
+type TypeHelperFunction<Descriptor extends AuthoringTypeConstructorDescriptor> =
+  Descriptor extends { readonly args: infer Args extends readonly AuthoringArgumentDescriptor[] }
+    ? <const Params extends TupleFromArgumentDescriptors<Args>>(
+        ...args: Params
+      ) => StorageTypeFromDescriptor<Descriptor, Params>
+    : () => StorageTypeFromDescriptor<Descriptor, readonly []>;
+
+type TypeHelpersFromNamespace<Namespace> = {
+  readonly [K in keyof Namespace]: Namespace[K] extends AuthoringTypeConstructorDescriptor
+    ? TypeHelperFunction<Namespace[K]>
+    : Namespace[K] extends Record<string, unknown>
+      ? TypeHelpersFromNamespace<Namespace[K]>
+      : never;
+};
+
+type CoreFieldHelpers = Pick<typeof field, 'column' | 'generated' | 'namedType'>;
+
+export type ComposedAuthoringHelpers<
+  Family extends FamilyPackRef<string>,
+  Target extends TargetPackRef<'sql', string>,
+  ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined,
+> = {
+  readonly field: CoreFieldHelpers &
+    FieldHelpersFromNamespace<
+      ExtractFieldNamespaceFromPack<Family> &
+        ExtractFieldNamespaceFromPack<Target> &
+        MergeExtensionFieldNamespaces<ExtensionPacks>
+    >;
+  readonly model: typeof model;
+  readonly rel: typeof rel;
+  readonly type: TypeHelpersFromNamespace<
+    ExtractTypeNamespaceFromPack<Family> &
+      ExtractTypeNamespaceFromPack<Target> &
+      MergeExtensionTypeNamespaces<ExtensionPacks>
+  >;
+};
+
+function extractTypeNamespace<Pack>(pack: Pack): ExtractTypeNamespaceFromPack<Pack> {
+  return ((pack as { readonly authoring?: { readonly type?: unknown } }).authoring?.type ??
+    {}) as ExtractTypeNamespaceFromPack<Pack>;
+}
+
+function extractFieldNamespace<Pack>(pack: Pack): ExtractFieldNamespaceFromPack<Pack> {
+  return ((pack as { readonly authoring?: { readonly field?: unknown } }).authoring?.field ??
+    {}) as ExtractFieldNamespaceFromPack<Pack>;
+}
+
+function mergeHelperNamespaces(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>,
+  path: readonly string[],
+  leafGuard: (value: unknown) => boolean,
+  label: string,
+): void {
+  const assertSafePath = (currentPath: readonly string[]) => {
+    const blockedSegment = currentPath.find(
+      (segment) => segment === '__proto__' || segment === 'constructor' || segment === 'prototype',
+    );
+    if (blockedSegment) {
+      throw new Error(
+        `Invalid authoring ${label} helper "${currentPath.join('.')}". Helper path segments must not use "${blockedSegment}".`,
+      );
+    }
+  };
+
+  for (const [key, sourceValue] of Object.entries(source)) {
+    const currentPath = [...path, key];
+    assertSafePath(currentPath);
+    const hasExistingValue = Object.hasOwn(target, key);
+    const existingValue = hasExistingValue ? target[key] : undefined;
+
+    if (!hasExistingValue) {
+      target[key] = sourceValue;
+      continue;
+    }
+
+    const existingIsLeaf = leafGuard(existingValue);
+    const sourceIsLeaf = leafGuard(sourceValue);
+
+    if (existingIsLeaf || sourceIsLeaf) {
+      throw new Error(
+        `Duplicate authoring ${label} helper "${currentPath.join('.')}". Helper names must be unique across composed packs.`,
+      );
+    }
+
+    mergeHelperNamespaces(
+      existingValue as Record<string, unknown>,
+      sourceValue as Record<string, unknown>,
+      currentPath,
+      leafGuard,
+      label,
+    );
+  }
+}
+
+type AuthoringComponent = {
+  readonly authoring?: { readonly type?: unknown; readonly field?: unknown };
+};
+
+function composeTypeNamespace(components: readonly AuthoringComponent[]): AuthoringTypeNamespace {
+  const merged: Record<string, unknown> = {};
+  for (const component of components) {
+    const ns = extractTypeNamespace(component);
+    if (Object.keys(ns).length > 0) {
+      mergeHelperNamespaces(merged, ns, [], isAuthoringTypeConstructorDescriptor, 'type');
+    }
+  }
+  return merged as AuthoringTypeNamespace;
+}
+
+function composeFieldNamespace(components: readonly AuthoringComponent[]): AuthoringFieldNamespace {
+  const merged: Record<string, unknown> = {};
+  for (const component of components) {
+    const ns = extractFieldNamespace(component);
+    if (Object.keys(ns).length > 0) {
+      mergeHelperNamespaces(merged, ns, [], isAuthoringFieldPresetDescriptor, 'field');
+    }
+  }
+  return merged as AuthoringFieldNamespace;
+}
+
+function createComposedFieldHelpers(
+  components: readonly AuthoringComponent[],
+): CoreFieldHelpers & Record<string, unknown> {
+  const helperNamespace = createFieldHelpersFromNamespace(
+    composeFieldNamespace(components),
+    ({ helperPath, descriptor }) =>
+      createFieldPresetHelper({
+        helperPath,
+        descriptor,
+        build: ({ args, namedConstraintOptions }) =>
+          buildFieldPreset(descriptor, args, namedConstraintOptions),
+      }),
+  );
+  const coreFieldHelpers = {
+    column: field.column,
+    generated: field.generated,
+    namedType: field.namedType,
+  } satisfies CoreFieldHelpers;
+
+  const coreHelperNames = new Set(Object.keys(coreFieldHelpers));
+  for (const helperName of Object.keys(helperNamespace)) {
+    if (coreHelperNames.has(helperName)) {
+      throw new Error(
+        `Duplicate authoring field helper "${helperName}". Core field helpers reserve that name.`,
+      );
+    }
+  }
+
+  return {
+    ...coreFieldHelpers,
+    ...helperNamespace,
+  };
+}
+
+export function createComposedAuthoringHelpers<
+  Family extends FamilyPackRef<string>,
+  Target extends TargetPackRef<'sql', string>,
+  ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined,
+>(options: {
+  readonly family: Family;
+  readonly target: Target;
+  readonly extensionPacks?: ExtensionPacks;
+}): ComposedAuthoringHelpers<Family, Target, ExtensionPacks> {
+  const extensionValues: readonly ExtensionPackRef<'sql', string>[] = Object.values(
+    (options.extensionPacks ?? {}) as Record<string, ExtensionPackRef<'sql', string>>,
+  );
+  const components: readonly AuthoringComponent[] = [
+    options.family,
+    options.target,
+    ...extensionValues,
+  ];
+
+  return {
+    field: createComposedFieldHelpers(components),
+    model,
+    rel,
+    type: createTypeHelpersFromNamespace(composeTypeNamespace(components)),
+  } as ComposedAuthoringHelpers<Family, Target, ExtensionPacks>;
+}