@prisma-next/target-mongo 0.3.0 → 0.4.0-dev.2

package/src/core/mongo-runner.ts

@@ -0,0 +1,275 @@
+import type { ContractMarkerRecord } from '@prisma-next/contract/types';
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import type {
+  MigrationOperationPolicy,
+  MigrationPlan,
+  MigrationPlanOperation,
+  MigrationRunnerExecutionChecks,
+  MigrationRunnerFailure,
+  MigrationRunnerResult,
+} from '@prisma-next/framework-components/control';
+import type {
+  MongoDdlCommandVisitor,
+  MongoInspectionCommandVisitor,
+  MongoMigrationCheck,
+  MongoMigrationPlanOperation,
+} from '@prisma-next/mongo-query-ast/control';
+import { notOk, ok } from '@prisma-next/utils/result';
+import { FilterEvaluator } from './filter-evaluator';
+import { deserializeMongoOps } from './mongo-ops-serializer';
+
+export interface MarkerOperations {
+  readMarker(): Promise<ContractMarkerRecord | null>;
+  initMarker(destination: {
+    readonly storageHash: string;
+    readonly profileHash: string;
+  }): Promise<void>;
+  updateMarker(
+    expectedFrom: string,
+    destination: { readonly storageHash: string; readonly profileHash: string },
+  ): Promise<boolean>;
+  writeLedgerEntry(entry: {
+    readonly edgeId: string;
+    readonly from: string;
+    readonly to: string;
+  }): Promise<void>;
+}
+
+export interface MongoRunnerDependencies {
+  readonly commandExecutor: MongoDdlCommandVisitor<Promise<void>>;
+  readonly inspectionExecutor: MongoInspectionCommandVisitor<Promise<Record<string, unknown>[]>>;
+  readonly markerOps: MarkerOperations;
+}
+
+function runnerFailure(
+  code: string,
+  summary: string,
+  opts?: { why?: string; meta?: Record<string, unknown> },
+): MigrationRunnerResult {
+  return notOk<MigrationRunnerFailure>({
+    code,
+    summary,
+    ...opts,
+  });
+}
+
+export class MongoMigrationRunner {
+  constructor(private readonly deps: MongoRunnerDependencies) {}
+
+  async execute(options: {
+    readonly plan: MigrationPlan;
+    readonly destinationContract: unknown;
+    readonly policy: MigrationOperationPolicy;
+    readonly callbacks?: {
+      onOperationStart?(op: MigrationPlanOperation): void;
+      onOperationComplete?(op: MigrationPlanOperation): void;
+    };
+    readonly executionChecks?: MigrationRunnerExecutionChecks;
+    readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'mongo', 'mongo'>>;
+  }): Promise<MigrationRunnerResult> {
+    const { commandExecutor, inspectionExecutor, markerOps } = this.deps;
+    const operations = deserializeMongoOps(options.plan.operations as readonly unknown[]);
+
+    const policyCheck = this.enforcePolicyCompatibility(options.policy, operations);
+    if (policyCheck) return policyCheck;
+
+    const existingMarker = await markerOps.readMarker();
+
+    const markerCheck = this.ensureMarkerCompatibility(existingMarker, options.plan);
+    if (markerCheck) return markerCheck;
+
+    const checks = options.executionChecks;
+    const runPrechecks = checks?.prechecks !== false;
+    const runPostchecks = checks?.postchecks !== false;
+    const runIdempotency = checks?.idempotencyChecks !== false;
+
+    const filterEvaluator = new FilterEvaluator();
+
+    let operationsExecuted = 0;
+
+    for (const operation of operations) {
+      options.callbacks?.onOperationStart?.(operation);
+      try {
+        if (runPostchecks && runIdempotency) {
+          const allSatisfied = await this.allChecksSatisfied(
+            operation.postcheck,
+            inspectionExecutor,
+            filterEvaluator,
+          );
+          if (allSatisfied) continue;
+        }
+
+        if (runPrechecks) {
+          const precheckResult = await this.evaluateChecks(
+            operation.precheck,
+            inspectionExecutor,
+            filterEvaluator,
+          );
+          if (!precheckResult) {
+            return runnerFailure(
+              'PRECHECK_FAILED',
+              `Operation ${operation.id} failed during precheck`,
+              { meta: { operationId: operation.id } },
+            );
+          }
+        }
+
+        for (const step of operation.execute) {
+          await step.command.accept(commandExecutor);
+        }
+
+        if (runPostchecks) {
+          const postcheckResult = await this.evaluateChecks(
+            operation.postcheck,
+            inspectionExecutor,
+            filterEvaluator,
+          );
+          if (!postcheckResult) {
+            return runnerFailure(
+              'POSTCHECK_FAILED',
+              `Operation ${operation.id} failed during postcheck`,
+              { meta: { operationId: operation.id } },
+            );
+          }
+        }
+
+        operationsExecuted += 1;
+      } finally {
+        options.callbacks?.onOperationComplete?.(operation);
+      }
+    }
+
+    const destination = options.plan.destination;
+    const contract = options.destinationContract as { profileHash?: string };
+    const profileHash = contract.profileHash ?? destination.storageHash;
+
+    if (
+      operationsExecuted === 0 &&
+      existingMarker?.storageHash === destination.storageHash &&
+      existingMarker.profileHash === profileHash
+    ) {
+      return ok({ operationsPlanned: operations.length, operationsExecuted });
+    }
+
+    if (existingMarker) {
+      const updated = await markerOps.updateMarker(existingMarker.storageHash, {
+        storageHash: destination.storageHash,
+        profileHash,
+      });
+      if (!updated) {
+        return runnerFailure(
+          'MARKER_CAS_FAILURE',
+          'Marker was modified by another process during migration execution.',
+          {
+            meta: {
+              expectedStorageHash: existingMarker.storageHash,
+              destinationStorageHash: destination.storageHash,
+            },
+          },
+        );
+      }
+    } else {
+      await markerOps.initMarker({
+        storageHash: destination.storageHash,
+        profileHash,
+      });
+    }
+
+    const originHash = existingMarker?.storageHash ?? '';
+    await markerOps.writeLedgerEntry({
+      edgeId: `${originHash}->${destination.storageHash}`,
+      from: originHash,
+      to: destination.storageHash,
+    });
+
+    return ok({ operationsPlanned: operations.length, operationsExecuted });
+  }
+
+  private async evaluateChecks(
+    checks: readonly MongoMigrationCheck[],
+    inspectionExecutor: MongoInspectionCommandVisitor<Promise<Record<string, unknown>[]>>,
+    filterEvaluator: FilterEvaluator,
+  ): Promise<boolean> {
+    for (const check of checks) {
+      const documents = await check.source.accept(inspectionExecutor);
+      const matchFound = documents.some((doc) =>
+        filterEvaluator.evaluate(check.filter, doc as Record<string, unknown>),
+      );
+      const passed = check.expect === 'exists' ? matchFound : !matchFound;
+      if (!passed) return false;
+    }
+    return true;
+  }
+
+  private async allChecksSatisfied(
+    checks: readonly MongoMigrationCheck[],
+    inspectionExecutor: MongoInspectionCommandVisitor<Promise<Record<string, unknown>[]>>,
+    filterEvaluator: FilterEvaluator,
+  ): Promise<boolean> {
+    if (checks.length === 0) return false;
+    return this.evaluateChecks(checks, inspectionExecutor, filterEvaluator);
+  }
+
+  private enforcePolicyCompatibility(
+    policy: MigrationOperationPolicy,
+    operations: readonly MongoMigrationPlanOperation[],
+  ): MigrationRunnerResult | undefined {
+    const allowedClasses = new Set(policy.allowedOperationClasses);
+    for (const operation of operations) {
+      if (!allowedClasses.has(operation.operationClass)) {
+        return runnerFailure(
+          'POLICY_VIOLATION',
+          `Operation ${operation.id} has class "${operation.operationClass}" which is not allowed by policy.`,
+          {
+            why: `Policy only allows: ${[...allowedClasses].join(', ')}.`,
+            meta: {
+              operationId: operation.id,
+              operationClass: operation.operationClass,
+            },
+          },
+        );
+      }
+    }
+    return undefined;
+  }
+
+  private ensureMarkerCompatibility(
+    marker: ContractMarkerRecord | null,
+    plan: MigrationPlan,
+  ): MigrationRunnerResult | undefined {
+    const origin = plan.origin ?? null;
+    if (!origin) {
+      if (marker) {
+        return runnerFailure(
+          'MARKER_ORIGIN_MISMATCH',
+          'Database already has a contract marker but the plan has no origin. This would silently overwrite the existing marker.',
+          { meta: { markerStorageHash: marker.storageHash } },
+        );
+      }
+      return undefined;
+    }
+
+    if (!marker) {
+      return runnerFailure(
+        'MARKER_ORIGIN_MISMATCH',
+        `Missing contract marker: expected origin storage hash ${origin.storageHash}.`,
+        { meta: { expectedOriginStorageHash: origin.storageHash } },
+      );
+    }
+
+    if (marker.storageHash !== origin.storageHash) {
+      return runnerFailure(
+        'MARKER_ORIGIN_MISMATCH',
+        `Existing contract marker (${marker.storageHash}) does not match plan origin (${origin.storageHash}).`,
+        {
+          meta: {
+            markerStorageHash: marker.storageHash,
+            expectedOriginStorageHash: origin.storageHash,
+          },
+        },
+      );
+    }
+
+    return undefined;
+  }
+}

package/src/core/op-factory-call.ts

@@ -0,0 +1,196 @@
+import type { MigrationOperationClass } from '@prisma-next/framework-components/control';
+import type {
+  CollModOptions,
+  CreateCollectionOptions,
+  CreateIndexOptions,
+  MongoIndexKey,
+} from '@prisma-next/mongo-query-ast/control';
+import type {
+  MongoSchemaCollection,
+  MongoSchemaCollectionOptions,
+  MongoSchemaIndex,
+  MongoSchemaValidator,
+} from '@prisma-next/mongo-schema-ir';
+
+export interface CollModMeta {
+  readonly id?: string;
+  readonly label?: string;
+  readonly operationClass?: MigrationOperationClass;
+}
+
+export interface OpFactoryCallVisitor<R> {
+  createIndex(call: CreateIndexCall): R;
+  dropIndex(call: DropIndexCall): R;
+  createCollection(call: CreateCollectionCall): R;
+  dropCollection(call: DropCollectionCall): R;
+  collMod(call: CollModCall): R;
+}
+
+abstract class OpFactoryCallNode {
+  abstract readonly factory: string;
+  abstract readonly operationClass: MigrationOperationClass;
+  abstract readonly label: string;
+  abstract accept<R>(visitor: OpFactoryCallVisitor<R>): R;
+
+  protected freeze(): void {
+    Object.freeze(this);
+  }
+}
+
+function formatKeys(keys: ReadonlyArray<MongoIndexKey>): string {
+  return keys.map((k) => `${k.field}:${k.direction}`).join(', ');
+}
+
+export class CreateIndexCall extends OpFactoryCallNode {
+  readonly factory = 'createIndex' as const;
+  readonly operationClass = 'additive' as const;
+  readonly collection: string;
+  readonly keys: ReadonlyArray<MongoIndexKey>;
+  readonly options: CreateIndexOptions | undefined;
+  readonly label: string;
+
+  constructor(
+    collection: string,
+    keys: ReadonlyArray<MongoIndexKey>,
+    options?: CreateIndexOptions,
+  ) {
+    super();
+    this.collection = collection;
+    this.keys = keys;
+    this.options = options;
+    this.label = `Create index on ${collection} (${formatKeys(keys)})`;
+    this.freeze();
+  }
+
+  accept<R>(visitor: OpFactoryCallVisitor<R>): R {
+    return visitor.createIndex(this);
+  }
+}
+
+export class DropIndexCall extends OpFactoryCallNode {
+  readonly factory = 'dropIndex' as const;
+  readonly operationClass = 'destructive' as const;
+  readonly collection: string;
+  readonly keys: ReadonlyArray<MongoIndexKey>;
+  readonly label: string;
+
+  constructor(collection: string, keys: ReadonlyArray<MongoIndexKey>) {
+    super();
+    this.collection = collection;
+    this.keys = keys;
+    this.label = `Drop index on ${collection} (${formatKeys(keys)})`;
+    this.freeze();
+  }
+
+  accept<R>(visitor: OpFactoryCallVisitor<R>): R {
+    return visitor.dropIndex(this);
+  }
+}
+
+export class CreateCollectionCall extends OpFactoryCallNode {
+  readonly factory = 'createCollection' as const;
+  readonly operationClass = 'additive' as const;
+  readonly collection: string;
+  readonly options: CreateCollectionOptions | undefined;
+  readonly label: string;
+
+  constructor(collection: string, options?: CreateCollectionOptions) {
+    super();
+    this.collection = collection;
+    this.options = options;
+    this.label = `Create collection ${collection}`;
+    this.freeze();
+  }
+
+  accept<R>(visitor: OpFactoryCallVisitor<R>): R {
+    return visitor.createCollection(this);
+  }
+}
+
+export class DropCollectionCall extends OpFactoryCallNode {
+  readonly factory = 'dropCollection' as const;
+  readonly operationClass = 'destructive' as const;
+  readonly collection: string;
+  readonly label: string;
+
+  constructor(collection: string) {
+    super();
+    this.collection = collection;
+    this.label = `Drop collection ${collection}`;
+    this.freeze();
+  }
+
+  accept<R>(visitor: OpFactoryCallVisitor<R>): R {
+    return visitor.dropCollection(this);
+  }
+}
+
+export class CollModCall extends OpFactoryCallNode {
+  readonly factory = 'collMod' as const;
+  readonly collection: string;
+  readonly options: CollModOptions;
+  readonly meta: CollModMeta | undefined;
+  readonly operationClass: MigrationOperationClass;
+  readonly label: string;
+
+  constructor(collection: string, options: CollModOptions, meta?: CollModMeta) {
+    super();
+    this.collection = collection;
+    this.options = options;
+    this.meta = meta;
+    this.operationClass = meta?.operationClass ?? 'destructive';
+    this.label = meta?.label ?? `Modify collection ${collection}`;
+    this.freeze();
+  }
+
+  accept<R>(visitor: OpFactoryCallVisitor<R>): R {
+    return visitor.collMod(this);
+  }
+}
+
+export type OpFactoryCall =
+  | CreateIndexCall
+  | DropIndexCall
+  | CreateCollectionCall
+  | DropCollectionCall
+  | CollModCall;
+
+export function schemaIndexToCreateIndexOptions(index: MongoSchemaIndex): CreateIndexOptions {
+  return {
+    unique: index.unique || undefined,
+    sparse: index.sparse,
+    expireAfterSeconds: index.expireAfterSeconds,
+    partialFilterExpression: index.partialFilterExpression,
+    wildcardProjection: index.wildcardProjection,
+    collation: index.collation,
+    weights: index.weights,
+    default_language: index.default_language,
+    language_override: index.language_override,
+  };
+}
+
+export function schemaCollectionToCreateCollectionOptions(
+  coll: MongoSchemaCollection,
+): CreateCollectionOptions | undefined {
+  const opts: MongoSchemaCollectionOptions | undefined = coll.options;
+  const validator: MongoSchemaValidator | undefined = coll.validator;
+  if (!opts && !validator) return undefined;
+  return {
+    capped: opts?.capped ? true : undefined,
+    size: opts?.capped?.size,
+    max: opts?.capped?.max,
+    timeseries: opts?.timeseries,
+    collation: opts?.collation,
+    clusteredIndex: opts?.clusteredIndex
+      ? {
+          key: { _id: 1 } as Record<string, number>,
+          unique: true as boolean,
+          ...(opts.clusteredIndex.name != null ? { name: opts.clusteredIndex.name } : {}),
+        }
+      : undefined,
+    validator: validator ? { $jsonSchema: validator.jsonSchema } : undefined,
+    validationLevel: validator?.validationLevel,
+    validationAction: validator?.validationAction,
+    changeStreamPreAndPostImages: opts?.changeStreamPreAndPostImages,
+  };
+}

package/src/core/render-ops.ts

@@ -0,0 +1,39 @@
+import type { MongoMigrationPlanOperation } from '@prisma-next/mongo-query-ast/control';
+import {
+  collMod,
+  createCollection,
+  createIndex,
+  dropCollection,
+  dropIndex,
+} from './migration-factories';
+import type {
+  CollModCall,
+  CreateCollectionCall,
+  CreateIndexCall,
+  DropCollectionCall,
+  DropIndexCall,
+  OpFactoryCall,
+  OpFactoryCallVisitor,
+} from './op-factory-call';
+
+const renderVisitor: OpFactoryCallVisitor<MongoMigrationPlanOperation> = {
+  createIndex(call: CreateIndexCall) {
+    return createIndex(call.collection, call.keys, call.options);
+  },
+  dropIndex(call: DropIndexCall) {
+    return dropIndex(call.collection, call.keys);
+  },
+  createCollection(call: CreateCollectionCall) {
+    return createCollection(call.collection, call.options);
+  },
+  dropCollection(call: DropCollectionCall) {
+    return dropCollection(call.collection);
+  },
+  collMod(call: CollModCall) {
+    return collMod(call.collection, call.options, call.meta);
+  },
+};
+
+export function renderOps(calls: ReadonlyArray<OpFactoryCall>): MongoMigrationPlanOperation[] {
+  return calls.map((call) => call.accept(renderVisitor));
+}

package/src/core/render-typescript.ts

@@ -0,0 +1,137 @@
+import type {
+  CollModCall,
+  CreateCollectionCall,
+  CreateIndexCall,
+  DropCollectionCall,
+  DropIndexCall,
+  OpFactoryCall,
+  OpFactoryCallVisitor,
+} from './op-factory-call';
+
+export interface RenderMigrationMeta {
+  readonly from: string;
+  readonly to: string;
+  readonly kind?: string;
+  readonly labels?: readonly string[];
+}
+
+export function renderTypeScript(
+  calls: ReadonlyArray<OpFactoryCall>,
+  meta?: RenderMigrationMeta,
+): string {
+  const factoryNames = collectFactoryNames(calls);
+  const imports = buildImports(factoryNames);
+  const planBody = calls.map((c) => c.accept(renderCallVisitor)).join(',\n');
+  const describeMethod = meta ? buildDescribeMethod(meta) : '';
+
+  return [
+    imports,
+    '',
+    'class M extends Migration {',
+    describeMethod,
+    '  override plan() {',
+    '    return [',
+    indent(planBody, 6),
+    '    ];',
+    '  }',
+    '}',
+    '',
+    'export default M;',
+    'Migration.run(import.meta.url, M);',
+    '',
+  ].join('\n');
+}
+
+function collectFactoryNames(calls: ReadonlyArray<OpFactoryCall>): string[] {
+  const names = new Set<string>();
+  for (const call of calls) {
+    names.add(call.factory);
+  }
+  return [...names].sort();
+}
+
+function buildImports(factoryNames: string[]): string {
+  const lines = ["import { Migration } from '@prisma-next/family-mongo/migration';"];
+  if (factoryNames.length > 0) {
+    lines.push(`import { ${factoryNames.join(', ')} } from '@prisma-next/target-mongo/migration';`);
+  }
+  return lines.join('\n');
+}
+
+function buildDescribeMethod(meta: RenderMigrationMeta): string {
+  const lines: string[] = [];
+  lines.push('  override describe() {');
+  lines.push('    return {');
+  lines.push(`      from: ${JSON.stringify(meta.from)},`);
+  lines.push(`      to: ${JSON.stringify(meta.to)},`);
+  if (meta.kind) {
+    lines.push(`      kind: ${JSON.stringify(meta.kind)},`);
+  }
+  if (meta.labels && meta.labels.length > 0) {
+    lines.push(`      labels: ${renderLiteral(meta.labels)},`);
+  }
+  lines.push('    };');
+  lines.push('  }');
+  lines.push('');
+  return lines.join('\n');
+}
+
+const renderCallVisitor: OpFactoryCallVisitor<string> = {
+  createIndex(call: CreateIndexCall) {
+    return call.options
+      ? `createIndex(${renderLiteral(call.collection)}, ${renderLiteral(call.keys)}, ${renderLiteral(call.options)})`
+      : `createIndex(${renderLiteral(call.collection)}, ${renderLiteral(call.keys)})`;
+  },
+  dropIndex(call: DropIndexCall) {
+    return `dropIndex(${renderLiteral(call.collection)}, ${renderLiteral(call.keys)})`;
+  },
+  createCollection(call: CreateCollectionCall) {
+    return call.options
+      ? `createCollection(${renderLiteral(call.collection)}, ${renderLiteral(call.options)})`
+      : `createCollection(${renderLiteral(call.collection)})`;
+  },
+  dropCollection(call: DropCollectionCall) {
+    return `dropCollection(${renderLiteral(call.collection)})`;
+  },
+  collMod(call: CollModCall) {
+    return call.meta
+      ? `collMod(${renderLiteral(call.collection)}, ${renderLiteral(call.options)}, ${renderLiteral(call.meta)})`
+      : `collMod(${renderLiteral(call.collection)}, ${renderLiteral(call.options)})`;
+  },
+};
+
+function renderLiteral(value: unknown): string {
+  if (value === undefined) return 'undefined';
+  if (value === null) return 'null';
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    const items = value.map((v) => renderLiteral(v));
+    const singleLine = `[${items.join(', ')}]`;
+    if (singleLine.length <= 80) return singleLine;
+    return `[\n${items.map((i) => `  ${i}`).join(',\n')},\n]`;
+  }
+  if (typeof value === 'object') {
+    const entries = Object.entries(value).filter(([, v]) => v !== undefined);
+    if (entries.length === 0) return '{}';
+    const items = entries.map(([k, v]) => `${renderKey(k)}: ${renderLiteral(v)}`);
+    const singleLine = `{ ${items.join(', ')} }`;
+    if (singleLine.length <= 80) return singleLine;
+    return `{\n${items.map((i) => `  ${i}`).join(',\n')},\n}`;
+  }
+  return String(value);
+}
+
+function renderKey(key: string): string {
+  if (key === '__proto__') return JSON.stringify(key);
+  return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+}
+
+function indent(text: string, spaces: number): string {
+  const pad = ' '.repeat(spaces);
+  return text
+    .split('\n')
+    .map((line) => (line.trim() ? `${pad}${line}` : line))
+    .join('\n');
+}

package/src/exports/control.ts

@@ -1 +1,26 @@
+export { contractToMongoSchemaIR } from '../core/contract-to-schema';
+export { formatMongoOperations } from '../core/ddl-formatter';
+export { FilterEvaluator } from '../core/filter-evaluator';
 export { initMarker, readMarker, updateMarker, writeLedgerEntry } from '../core/marker-ledger';
+export {
+  deserializeMongoOp,
+  deserializeMongoOps,
+  serializeMongoOps,
+} from '../core/mongo-ops-serializer';
+export type { PlanCallsResult } from '../core/mongo-planner';
+export { MongoMigrationPlanner } from '../core/mongo-planner';
+export type { MarkerOperations, MongoRunnerDependencies } from '../core/mongo-runner';
+export { MongoMigrationRunner } from '../core/mongo-runner';
+export type { CollModMeta, OpFactoryCall, OpFactoryCallVisitor } from '../core/op-factory-call';
+export {
+  CollModCall,
+  CreateCollectionCall,
+  CreateIndexCall,
+  DropCollectionCall,
+  DropIndexCall,
+  schemaCollectionToCreateCollectionOptions,
+  schemaIndexToCreateIndexOptions,
+} from '../core/op-factory-call';
+export { renderOps } from '../core/render-ops';
+export type { RenderMigrationMeta } from '../core/render-typescript';
+export { renderTypeScript } from '../core/render-typescript';

package/src/exports/migration.ts

@@ -0,0 +1,9 @@
+export {
+  collMod,
+  createCollection,
+  createIndex,
+  dropCollection,
+  dropIndex,
+  setValidation,
+  validatedCollection,
+} from '../core/migration-factories';