@prisma-next/family-mongo 0.7.0 → 0.8.0-dev.1

package/src/core/ir/mongo-contract-serializer-base.ts

@@ -0,0 +1,124 @@
+import { validateContractDomain } from '@prisma-next/contract/validate-domain';
+import type { ContractSerializer } from '@prisma-next/framework-components/control';
+import {
+  MongoCollection,
+  type MongoCollectionInput,
+  type MongoContract,
+  MongoContractSchema,
+  validateMongoStorage,
+} from '@prisma-next/mongo-contract';
+import type { JsonObject } from '@prisma-next/utils/json';
+import { type as arktypeType } from 'arktype';
+
+/**
+ * Mongo family `ContractSerializer` abstract base. Owns the family-shared
+ * deserialization pipeline:
+ *
+ * 1. Structural validation against the Mongo contract arktype schema
+ *    (`MongoContractSchema`).
+ * 2. Framework-shared domain validation (`validateContractDomain`).
+ * 3. Family-shared storage validation (`validateMongoStorage`).
+ *
+ * The validated value is handed to the target via the
+ * `constructTargetContract` hook, which wraps the plain-JSON shape in
+ * the family-layer `MongoStorage` class instance (carrying the
+ * target-supplied `namespaces` map). Targets that need to add
+ * structural checks beyond the family default can override
+ * `parseMongoContractStructure`.
+ *
+ * Default `serializeContract` is identity over the contract — Mongo
+ * target classes carry JSON-clean fields by construction, so the value
+ * can be `JSON.stringify`'d directly. Targets that need on-the-way-out
+ * canonicalization override `serializeContract`.
+ */
+export abstract class MongoContractSerializerBase<TContract>
+  implements ContractSerializer<TContract>
+{
+  deserializeContract(json: unknown): TContract {
+    const validated = this.parseMongoContractStructure(json);
+    return this.constructTargetContract(validated);
+  }
+
+  serializeContract(contract: TContract): JsonObject {
+    // Mongo contract class fields are JSON-clean by construction; the
+    // cast asserts that. Targets that need to canonicalize on the way
+    // out override this method.
+    return contract as unknown as JsonObject;
+  }
+
+  /**
+   * Family-shared structural validation: parse against the Mongo
+   * contract arktype schema, then run framework-shared domain + Mongo
+   * family storage checks, then hydrate the validated tree into Mongo
+   * Contract IR class instances. Targets can override to add
+   * target-specific structural checks; most targets accept the family
+   * default.
+   *
+   * The returned `MongoContract` carries class instances under
+   * `storage.collections` (each value is a `MongoCollection`, with
+   * nested `MongoIndex` / `MongoValidator` / `MongoCollectionOptions`
+   * constructed by the `MongoCollection` constructor). The rest of the
+   * contract envelope (models, valueObjects, capabilities, …) remains
+   * in plain-JSON form; those IR layers are handled by sibling
+   * subsystems and don't sit behind this SPI.
+   */
+  protected parseMongoContractStructure(json: unknown): MongoContract {
+    const parsed = MongoContractSchema(json);
+    if (parsed instanceof arktypeType.errors) {
+      throw new Error(`Contract structural validation failed: ${parsed.summary}`);
+    }
+
+    // arktype's `infer`d type for `MongoContractSchema` is structurally
+    // equivalent to `MongoContract` (both describe the same on-disk JSON
+    // envelope) but not nominally so: the arktype DSL produces a type whose
+    // optional/readonly profile, narrowed string-literal positions, and
+    // utility-type wrappings (`Type.infer`, `Out`, …) differ from the
+    // hand-authored `MongoContract<S, M>` generic surface. The schema and
+    // the type are kept in lockstep by the round-trip fixtures under
+    // `test/validate.test.ts`. The hydration walk below additionally
+    // re-shapes `storage.collections` from plain data into IR-class
+    // instances, so the `MongoContract` returned here carries class
+    // identity under `storage.collections.*` (and transitively under
+    // `indexes` / `validator` / `options`).
+    const validatedShape = parsed as unknown as MongoContract;
+
+    const hydratedContract = this.hydrateMongoContract(validatedShape);
+
+    validateContractDomain(hydratedContract);
+    validateMongoStorage(hydratedContract);
+
+    return hydratedContract;
+  }
+
+  /**
+   * Walk a structurally-validated Mongo contract and convert
+   * `storage.collections` entries from plain data into
+   * `MongoCollection` IR-class instances. Idempotent: already-class
+   * instances pass through unchanged.
+   */
+  protected hydrateMongoContract(contract: MongoContract): MongoContract {
+    const rawCollections = contract.storage.collections;
+    const hydrated: Record<string, MongoCollection> = {};
+    for (const [name, raw] of Object.entries(rawCollections)) {
+      hydrated[name] =
+        raw instanceof MongoCollection ? raw : new MongoCollection(raw as MongoCollectionInput);
+    }
+    return {
+      ...contract,
+      storage: {
+        ...contract.storage,
+        collections: hydrated,
+      },
+    };
+  }
+
+  /**
+   * Target-specific class construction from the validated structural
+   * data. The target wraps the contract envelope in the family-layer
+   * `MongoStorage` class instance, supplying the `namespaces` map
+   * (target concretions like `MongoTargetUnspecifiedDatabase`). The
+   * leaf collection / index shapes are already family-layer IR-class
+   * instances after the hydration walk above.
+   */
+  protected abstract constructTargetContract(validated: MongoContract): TContract;
+}

package/src/core/ir/mongo-contract-serializer.ts

@@ -0,0 +1,18 @@
+import type { MongoContract } from '@prisma-next/mongo-contract';
+import { MongoContractSerializerBase } from './mongo-contract-serializer-base';
+
+/**
+ * Default Mongo family `ContractSerializer` concretion. Inherits the
+ * Mongo-shared deserialization pipeline (structural validation +
+ * collection-level hydration) and falls through `constructTargetContract`
+ * with the validated `MongoContract` shape. Family-level call sites
+ * (family-instance methods, family-layer tests that don't reach into
+ * a target descriptor) instantiate this directly; targets with their
+ * own storage concretion (`target-mongo`'s `MongoTargetContractSerializer`)
+ * override `constructTargetContract` to wrap the storage shape.
+ */
+export class MongoContractSerializer extends MongoContractSerializerBase<MongoContract> {
+  protected constructTargetContract(validated: MongoContract): MongoContract {
+    return validated;
+  }
+}

package/src/core/ir/mongo-schema-verifier-base.ts

@@ -0,0 +1,87 @@
+import type {
+  SchemaIssue,
+  SchemaVerifier,
+  SchemaVerifyOptions,
+  SchemaVerifyResult,
+} from '@prisma-next/framework-components/control';
+import type { Namespace } from '@prisma-next/framework-components/ir';
+import type { MongoStorage } from '@prisma-next/mongo-contract';
+
+/**
+ * Mongo family `SchemaVerifier` abstract base. Commits the Mongo family
+ * to namespace-keyed verification: the family-shared walk iterates
+ * `storage.namespaces` in sorted order and dispatches per-namespace
+ * through the protected `verifyNamespace` hook, then aggregates
+ * target-extension issues from `verifyTargetExtensions`.
+ *
+ * Per-element diff work (collection / index / validator comparisons)
+ * lives on the target inside `verifyNamespace`. The family's structural
+ * commitment is "verification is namespaced"; the target's commitment is
+ * "verification of a given namespace's collections is the existing
+ * diff/canonicalize pipeline". The split keeps target-mongo's
+ * introspection-side helpers (`contractToMongoSchemaIR`,
+ * `canonicalizeSchemasForVerification`, `diffMongoSchemas`) in the target
+ * layer where they belong, while the family base owns the iteration
+ * scaffolding that makes namespaces a first-class verifier concept.
+ *
+ * Target-specific issue kinds (Atlas-only, future RLS-equivalents)
+ * surface through `verifyTargetExtensions`; that hook returns the empty
+ * list when no extensions exist over the Mongo family alphabet.
+ */
+export abstract class MongoSchemaVerifierBase<
+  TContract extends { readonly storage: MongoStorage },
+  TSchema,
+> implements SchemaVerifier<TContract, TSchema>
+{
+  verifySchema(options: SchemaVerifyOptions<TContract, TSchema>): SchemaVerifyResult {
+    const issues: SchemaIssue[] = [];
+    issues.push(...this.verifyCommonMongoSchema(options));
+    issues.push(...this.verifyTargetExtensions(options));
+    return { ok: issues.length === 0, issues };
+  }
+
+  protected verifyCommonMongoSchema(
+    options: SchemaVerifyOptions<TContract, TSchema>,
+  ): readonly SchemaIssue[] {
+    const issues: SchemaIssue[] = [];
+    const { namespaces } = options.contract.storage;
+    const namespaceIds = Object.keys(namespaces).sort();
+    for (const namespaceId of namespaceIds) {
+      const namespace = namespaces[namespaceId];
+      if (!namespace) continue;
+      issues.push(
+        ...this.verifyNamespace({
+          contract: options.contract,
+          schema: options.schema,
+          namespaceId,
+          namespace,
+        }),
+      );
+    }
+    return issues;
+  }
+
+  /**
+   * Per-namespace verification hook. Receives the namespace metadata plus
+   * the full contract + schema pair; the target's implementation owns the
+   * per-collection diff using its existing introspection-side helpers.
+   * Slice the schema by namespace at the call site (or compute the full
+   * diff once and dispatch per namespace) — the family base does not
+   * prescribe the per-namespace shape.
+   */
+  protected abstract verifyNamespace(options: {
+    readonly contract: TContract;
+    readonly schema: TSchema;
+    readonly namespaceId: string;
+    readonly namespace: Namespace;
+  }): readonly SchemaIssue[];
+
+  /**
+   * Target-specific extensions — Atlas-only kinds, target-only
+   * namespace-mismatch issues that don't fit the family-shared walk.
+   * Returns the empty list when the target ships no extensions.
+   */
+  protected abstract verifyTargetExtensions(
+    options: SchemaVerifyOptions<TContract, TSchema>,
+  ): readonly SchemaIssue[];
+}

package/src/core/operation-preview.ts

@@ -0,0 +1,131 @@
+import type {
+  MigrationPlanOperation,
+  OperationPreview,
+} from '@prisma-next/framework-components/control';
+import type {
+  CollModCommand,
+  CreateCollectionCommand,
+  CreateIndexCommand,
+  DropCollectionCommand,
+  DropIndexCommand,
+  MongoDdlCommandVisitor,
+  MongoIndexKey,
+} from '@prisma-next/mongo-query-ast/control';
+
+function formatKeySpec(keys: ReadonlyArray<MongoIndexKey>): string {
+  const entries = keys.map((k) => `${JSON.stringify(k.field)}: ${JSON.stringify(k.direction)}`);
+  return `{ ${entries.join(', ')} }`;
+}
+
+function formatOptions(cmd: CreateIndexCommand): string | undefined {
+  const parts: string[] = [];
+  if (cmd.unique) parts.push('unique: true');
+  if (cmd.sparse) parts.push('sparse: true');
+  if (cmd.expireAfterSeconds !== undefined)
+    parts.push(`expireAfterSeconds: ${cmd.expireAfterSeconds}`);
+  if (cmd.name) parts.push(`name: ${JSON.stringify(cmd.name)}`);
+  if (cmd.collation) parts.push(`collation: ${JSON.stringify(cmd.collation)}`);
+  if (cmd.weights) parts.push(`weights: ${JSON.stringify(cmd.weights)}`);
+  if (cmd.default_language) parts.push(`default_language: ${JSON.stringify(cmd.default_language)}`);
+  if (cmd.language_override)
+    parts.push(`language_override: ${JSON.stringify(cmd.language_override)}`);
+  if (cmd.wildcardProjection)
+    parts.push(`wildcardProjection: ${JSON.stringify(cmd.wildcardProjection)}`);
+  if (cmd.partialFilterExpression)
+    parts.push(`partialFilterExpression: ${JSON.stringify(cmd.partialFilterExpression)}`);
+  if (parts.length === 0) return undefined;
+  return `{ ${parts.join(', ')} }`;
+}
+
+function formatCreateCollectionOptions(cmd: CreateCollectionCommand): string | undefined {
+  const parts: string[] = [];
+  if (cmd.capped) parts.push('capped: true');
+  if (cmd.size !== undefined) parts.push(`size: ${cmd.size}`);
+  if (cmd.max !== undefined) parts.push(`max: ${cmd.max}`);
+  if (cmd.timeseries) parts.push(`timeseries: ${JSON.stringify(cmd.timeseries)}`);
+  if (cmd.collation) parts.push(`collation: ${JSON.stringify(cmd.collation)}`);
+  if (cmd.clusteredIndex) parts.push(`clusteredIndex: ${JSON.stringify(cmd.clusteredIndex)}`);
+  if (cmd.validator) parts.push(`validator: ${JSON.stringify(cmd.validator)}`);
+  if (cmd.validationLevel) parts.push(`validationLevel: ${JSON.stringify(cmd.validationLevel)}`);
+  if (cmd.validationAction) parts.push(`validationAction: ${JSON.stringify(cmd.validationAction)}`);
+  if (cmd.changeStreamPreAndPostImages)
+    parts.push(`changeStreamPreAndPostImages: ${JSON.stringify(cmd.changeStreamPreAndPostImages)}`);
+  if (parts.length === 0) return undefined;
+  return `{ ${parts.join(', ')} }`;
+}
+
+class MongoDdlCommandFormatter implements MongoDdlCommandVisitor<string> {
+  createIndex(cmd: CreateIndexCommand): string {
+    const keySpec = formatKeySpec(cmd.keys);
+    const opts = formatOptions(cmd);
+    return opts
+      ? `db.${cmd.collection}.createIndex(${keySpec}, ${opts})`
+      : `db.${cmd.collection}.createIndex(${keySpec})`;
+  }
+
+  dropIndex(cmd: DropIndexCommand): string {
+    return `db.${cmd.collection}.dropIndex(${JSON.stringify(cmd.name)})`;
+  }
+
+  createCollection(cmd: CreateCollectionCommand): string {
+    const opts = formatCreateCollectionOptions(cmd);
+    return opts
+      ? `db.createCollection(${JSON.stringify(cmd.collection)}, ${opts})`
+      : `db.createCollection(${JSON.stringify(cmd.collection)})`;
+  }
+
+  dropCollection(cmd: DropCollectionCommand): string {
+    return `db.${cmd.collection}.drop()`;
+  }
+
+  collMod(cmd: CollModCommand): string {
+    const parts: string[] = [`collMod: ${JSON.stringify(cmd.collection)}`];
+    if (cmd.validator) parts.push(`validator: ${JSON.stringify(cmd.validator)}`);
+    if (cmd.validationLevel) parts.push(`validationLevel: ${JSON.stringify(cmd.validationLevel)}`);
+    if (cmd.validationAction)
+      parts.push(`validationAction: ${JSON.stringify(cmd.validationAction)}`);
+    if (cmd.changeStreamPreAndPostImages)
+      parts.push(
+        `changeStreamPreAndPostImages: ${JSON.stringify(cmd.changeStreamPreAndPostImages)}`,
+      );
+    return `db.runCommand({ ${parts.join(', ')} })`;
+  }
+}
+
+const formatter = new MongoDdlCommandFormatter();
+
+interface MongoExecuteStep {
+  readonly command: { readonly accept: <R>(visitor: MongoDdlCommandVisitor<R>) => R };
+}
+
+export function formatMongoOperations(operations: readonly MigrationPlanOperation[]): string[] {
+  const statements: string[] = [];
+  for (const operation of operations) {
+    const candidate = operation as unknown as Record<string, unknown>;
+    if (!('execute' in candidate) || !Array.isArray(candidate['execute'])) {
+      continue;
+    }
+    for (const step of candidate['execute'] as MongoExecuteStep[]) {
+      if (step.command && typeof step.command.accept === 'function') {
+        statements.push(step.command.accept(formatter));
+      }
+    }
+  }
+  return statements;
+}
+
+/**
+ * Wraps `formatMongoOperations` into the family-agnostic
+ * `OperationPreview` shape. Each statement carries
+ * `language: 'mongodb-shell'`. Mirrors `sqlOperationsToPreview`.
+ */
+export function mongoOperationsToPreview(
+  operations: readonly MigrationPlanOperation[],
+): OperationPreview {
+  return {
+    statements: formatMongoOperations(operations).map((text) => ({
+      text,
+      language: 'mongodb-shell',
+    })),
+  };
+}