@prisma-next/mongo-core 0.0.1

package/src/commands.ts

@@ -0,0 +1,93 @@
+import type { MongoExpr, MongoUpdateDocument, MongoValue, RawPipeline } from './values';
+
+abstract class MongoCommand {
+  abstract readonly kind: string;
+  readonly collection: string;
+
+  protected constructor(collection: string) {
+    this.collection = collection;
+  }
+
+  protected freeze(): void {
+    Object.freeze(this);
+  }
+}
+
+export interface FindOptions {
+  readonly projection?: Record<string, 1 | 0>;
+  readonly sort?: Record<string, 1 | -1>;
+  readonly limit?: number;
+  readonly skip?: number;
+}
+
+export class FindCommand extends MongoCommand {
+  readonly kind = 'find' as const;
+  readonly filter: MongoExpr | undefined;
+  readonly projection: Record<string, 1 | 0> | undefined;
+  readonly sort: Record<string, 1 | -1> | undefined;
+  readonly limit: number | undefined;
+  readonly skip: number | undefined;
+
+  constructor(collection: string, filter?: MongoExpr, options?: FindOptions) {
+    super(collection);
+    this.filter = filter;
+    this.projection = options?.projection;
+    this.sort = options?.sort;
+    this.limit = options?.limit;
+    this.skip = options?.skip;
+    this.freeze();
+  }
+}
+
+export class InsertOneCommand extends MongoCommand {
+  readonly kind = 'insertOne' as const;
+  readonly document: Record<string, MongoValue>;
+
+  constructor(collection: string, document: Record<string, MongoValue>) {
+    super(collection);
+    this.document = document;
+    this.freeze();
+  }
+}
+
+export class UpdateOneCommand extends MongoCommand {
+  readonly kind = 'updateOne' as const;
+  readonly filter: MongoExpr;
+  readonly update: MongoUpdateDocument;
+
+  constructor(collection: string, filter: MongoExpr, update: MongoUpdateDocument) {
+    super(collection);
+    this.filter = filter;
+    this.update = update;
+    this.freeze();
+  }
+}
+
+export class DeleteOneCommand extends MongoCommand {
+  readonly kind = 'deleteOne' as const;
+  readonly filter: MongoExpr;
+
+  constructor(collection: string, filter: MongoExpr) {
+    super(collection);
+    this.filter = filter;
+    this.freeze();
+  }
+}
+
+export class AggregateCommand extends MongoCommand {
+  readonly kind = 'aggregate' as const;
+  readonly pipeline: RawPipeline;
+
+  constructor(collection: string, pipeline: RawPipeline) {
+    super(collection);
+    this.pipeline = pipeline;
+    this.freeze();
+  }
+}
+
+export type AnyMongoCommand =
+  | FindCommand
+  | InsertOneCommand
+  | UpdateOneCommand
+  | DeleteOneCommand
+  | AggregateCommand;

package/src/contract-schema.ts

@@ -0,0 +1,119 @@
+import { type } from 'arktype';
+
+const MongoModelFieldSchema = type({
+  '+': 'reject',
+  codecId: 'string',
+  nullable: 'boolean',
+});
+
+const MongoModelStorageSchema = type({
+  '+': 'reject',
+  'collection?': 'string',
+});
+
+const MongoDiscriminatorSchema = type({
+  '+': 'reject',
+  field: 'string',
+});
+
+const MongoVariantEntrySchema = type({
+  '+': 'reject',
+  value: 'string',
+});
+
+const MongoReferenceRelationOnSchema = type({
+  '+': 'reject',
+  localFields: 'string[]',
+  targetFields: 'string[]',
+});
+
+const MongoReferenceRelationSchema = type({
+  '+': 'reject',
+  to: 'string',
+  cardinality: "'1:1' | '1:N' | 'N:1'",
+  strategy: "'reference'",
+  on: MongoReferenceRelationOnSchema,
+});
+
+const MongoEmbedRelationSchema = type({
+  '+': 'reject',
+  to: 'string',
+  cardinality: "'1:1' | '1:N'",
+  strategy: "'embed'",
+  field: 'string',
+});
+
+const MongoRelationSchema = MongoReferenceRelationSchema.or(MongoEmbedRelationSchema);
+
+const MongoModelDefinitionSchema = type({
+  '+': 'reject',
+  fields: type('Record<string, unknown>').pipe((fields) => {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(fields)) {
+      const parsed = MongoModelFieldSchema(value);
+      if (parsed instanceof type.errors) {
+        throw new Error(`Invalid field "${key}": ${parsed.summary}`);
+      }
+      result[key] = parsed;
+    }
+    return result;
+  }),
+  storage: MongoModelStorageSchema,
+  relations: type('Record<string, unknown>').pipe((relations) => {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(relations)) {
+      const parsed = MongoRelationSchema(value);
+      if (parsed instanceof type.errors) {
+        throw new Error(`Invalid relation "${key}": ${parsed.summary}`);
+      }
+      result[key] = parsed;
+    }
+    return result;
+  }),
+  'discriminator?': MongoDiscriminatorSchema,
+  'variants?': type('Record<string, unknown>').pipe((variants) => {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(variants)) {
+      const parsed = MongoVariantEntrySchema(value);
+      if (parsed instanceof type.errors) {
+        throw new Error(`Invalid variant "${key}": ${parsed.summary}`);
+      }
+      result[key] = parsed;
+    }
+    return result;
+  }),
+  'base?': 'string',
+});
+
+const MongoStorageCollectionSchema = type({ '+': 'reject' });
+
+export const MongoContractSchema = type({
+  '+': 'reject',
+  targetFamily: "'mongo'",
+  roots: 'Record<string, string>',
+  storage: type({
+    '+': 'reject',
+    collections: type('Record<string, unknown>').pipe((collections) => {
+      const result: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(collections)) {
+        const parsed = MongoStorageCollectionSchema(value);
+        if (parsed instanceof type.errors) {
+          throw new Error(`Invalid collection "${key}": ${parsed.summary}`);
+        }
+        result[key] = parsed;
+      }
+      return result;
+    }),
+  }),
+  models: type('Record<string, unknown>').pipe((models) => {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(models)) {
+      const parsed = MongoModelDefinitionSchema(value);
+      if (parsed instanceof type.errors) {
+        throw new Error(`Invalid model "${key}": ${parsed.summary}`);
+      }
+      result[key] = parsed;
+    }
+    return result;
+  }),
+});

package/src/contract-types.ts

@@ -0,0 +1,120 @@
+// --- Storage layer: collection-level metadata ---
+
+export type MongoStorageCollection = Record<string, never>;
+
+export type MongoStorage = {
+  readonly collections: Record<string, MongoStorageCollection>;
+};
+
+// --- Model field (domain level) ---
+
+export type MongoModelField = {
+  readonly codecId: string;
+  readonly nullable: boolean;
+};
+
+// --- Model storage (family-specific bridge) ---
+
+export type MongoModelStorage = {
+  readonly collection?: string;
+};
+
+// --- Polymorphism ---
+
+export type MongoDiscriminator = {
+  readonly field: string;
+};
+
+export type MongoVariantEntry = {
+  readonly value: string;
+};
+
+// --- Relations ---
+
+export type MongoReferenceRelationOn = {
+  readonly localFields: readonly string[];
+  readonly targetFields: readonly string[];
+};
+
+export type MongoReferenceRelation = {
+  readonly to: string;
+  readonly cardinality: '1:1' | '1:N' | 'N:1';
+  readonly strategy: 'reference';
+  readonly on: MongoReferenceRelationOn;
+};
+
+export type MongoEmbedRelation = {
+  readonly to: string;
+  readonly cardinality: '1:1' | '1:N';
+  readonly strategy: 'embed';
+  readonly field: string;
+};
+
+export type MongoRelation = MongoReferenceRelation | MongoEmbedRelation;
+
+// --- Model definition ---
+
+export type MongoModelDefinition = {
+  readonly fields: Record<string, MongoModelField>;
+  readonly storage: MongoModelStorage;
+  readonly relations: Record<string, MongoRelation>;
+  readonly discriminator?: MongoDiscriminator;
+  readonly variants?: Record<string, MongoVariantEntry>;
+  readonly base?: string;
+};
+
+// --- Contract ---
+
+export type MongoContract<
+  Roots extends Record<string, string> = Record<string, string>,
+  S extends MongoStorage = MongoStorage,
+  M extends Record<string, MongoModelDefinition> = Record<string, MongoModelDefinition>,
+> = {
+  readonly targetFamily: string;
+  readonly roots: Roots;
+  readonly storage: S;
+  readonly models: M;
+};
+
+// --- TypeMaps: phantom type attachment ---
+
+export type MongoTypeMaps<
+  TCodecTypes extends Record<string, { output: unknown }> = Record<string, { output: unknown }>,
+> = {
+  readonly codecTypes: TCodecTypes;
+};
+
+export type MongoTypeMapsPhantomKey = '__@prisma-next/mongo-core/typeMaps@__';
+
+export type MongoContractWithTypeMaps<TContract, TTypeMaps> = TContract & {
+  readonly [K in MongoTypeMapsPhantomKey]?: TTypeMaps;
+};
+
+// --- Type extraction helpers ---
+
+export type ExtractMongoTypeMaps<T> = MongoTypeMapsPhantomKey extends keyof T
+  ? NonNullable<T[MongoTypeMapsPhantomKey & keyof T]>
+  : never;
+
+export type ExtractMongoCodecTypes<T> =
+  ExtractMongoTypeMaps<T> extends { codecTypes: infer C }
+    ? C extends Record<string, { output: unknown }>
+      ? C
+      : Record<string, never>
+    : Record<string, never>;
+
+// --- Row inference ---
+
+export type InferModelRow<
+  TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>,
+  ModelName extends string & keyof TContract['models'],
+  TFields extends Record<
+    string,
+    { codecId: string; nullable: boolean }
+  > = TContract['models'][ModelName]['fields'],
+  TCodecTypes extends Record<string, { output: unknown }> = ExtractMongoCodecTypes<TContract>,
+> = {
+  -readonly [FieldName in keyof TFields]: TFields[FieldName]['nullable'] extends true
+    ? TCodecTypes[TFields[FieldName]['codecId']]['output'] | null
+    : TCodecTypes[TFields[FieldName]['codecId']]['output'];
+};

package/src/driver-types.ts

@@ -0,0 +1,6 @@
+import type { AnyMongoWireCommand } from './wire-commands';
+
+export interface MongoDriver {
+  execute<Row>(wireCommand: AnyMongoWireCommand): AsyncIterable<Row>;
+  close(): Promise<void>;
+}

package/src/exports/index.ts

@@ -0,0 +1,64 @@
+export type { MongoAdapter, MongoLoweringContext } from '../adapter-types';
+export type { MongoCodecRegistry } from '../codec-registry';
+export { createMongoCodecRegistry } from '../codec-registry';
+export type { MongoCodec, MongoCodecJsType } from '../codecs';
+export { mongoCodec } from '../codecs';
+export type { AnyMongoCommand, FindOptions } from '../commands';
+export {
+  AggregateCommand,
+  DeleteOneCommand,
+  FindCommand,
+  InsertOneCommand,
+  UpdateOneCommand,
+} from '../commands';
+export type {
+  ExtractMongoCodecTypes,
+  ExtractMongoTypeMaps,
+  InferModelRow,
+  MongoContract,
+  MongoContractWithTypeMaps,
+  MongoDiscriminator,
+  MongoEmbedRelation,
+  MongoModelDefinition,
+  MongoModelField,
+  MongoModelStorage,
+  MongoReferenceRelation,
+  MongoReferenceRelationOn,
+  MongoRelation,
+  MongoStorage,
+  MongoStorageCollection,
+  MongoTypeMaps,
+  MongoTypeMapsPhantomKey,
+  MongoVariantEntry,
+} from '../contract-types';
+export type { MongoDriver } from '../driver-types';
+export { MongoParamRef } from '../param-ref';
+export type { MongoExecutionPlan, MongoQueryPlan } from '../plan';
+export type { DeleteOneResult, InsertOneResult, UpdateOneResult } from '../results';
+export type {
+  DomainContractShape,
+  DomainModelShape,
+  DomainValidationResult,
+} from '../validate-domain';
+export { validateContractDomain } from '../validate-domain';
+export type { MongoContractIndices, ValidatedMongoContract } from '../validate-mongo-contract';
+export { validateMongoContract } from '../validate-mongo-contract';
+export { validateMongoStorage } from '../validate-storage';
+export type {
+  Document,
+  LiteralValue,
+  MongoArray,
+  MongoDocument,
+  MongoExpr,
+  MongoUpdateDocument,
+  MongoValue,
+  RawPipeline,
+} from '../values';
+export type { AnyMongoWireCommand } from '../wire-commands';
+export {
+  AggregateWireCommand,
+  DeleteOneWireCommand,
+  FindWireCommand,
+  InsertOneWireCommand,
+  UpdateOneWireCommand,
+} from '../wire-commands';

package/src/param-ref.ts

@@ -0,0 +1,16 @@
+export class MongoParamRef {
+  readonly value: unknown;
+  readonly name: string | undefined;
+  readonly codecId: string | undefined;
+
+  constructor(value: unknown, options?: { name?: string; codecId?: string }) {
+    this.value = value;
+    this.name = options?.name;
+    this.codecId = options?.codecId;
+    Object.freeze(this);
+  }
+
+  static of(value: unknown, options?: { name?: string; codecId?: string }): MongoParamRef {
+    return new MongoParamRef(value, options);
+  }
+}

package/src/plan.ts

@@ -0,0 +1,16 @@
+import type { PlanMeta } from '@prisma-next/contract/types';
+import type { AnyMongoCommand } from './commands';
+import type { AnyMongoWireCommand } from './wire-commands';
+
+export interface MongoQueryPlan<Row = unknown> {
+  readonly command: AnyMongoCommand;
+  readonly meta: PlanMeta;
+  readonly _row?: Row;
+}
+
+export interface MongoExecutionPlan<Row = unknown> {
+  readonly wireCommand: AnyMongoWireCommand;
+  readonly command: AnyMongoCommand;
+  readonly meta: PlanMeta;
+  readonly _row?: Row;
+}

package/src/results.ts

@@ -0,0 +1,12 @@
+export interface InsertOneResult {
+  readonly insertedId: unknown;
+}
+
+export interface UpdateOneResult {
+  readonly matchedCount: number;
+  readonly modifiedCount: number;
+}
+
+export interface DeleteOneResult {
+  readonly deletedCount: number;
+}

package/src/validate-domain.ts

@@ -0,0 +1,174 @@
+export interface DomainModelShape {
+  readonly fields: Record<string, unknown>;
+  readonly relations: Record<string, { readonly to: string }>;
+  readonly discriminator?: { readonly field: string };
+  readonly variants?: Record<string, unknown>;
+  readonly base?: string;
+}
+
+export interface DomainContractShape {
+  readonly roots: Record<string, string>;
+  readonly models: Record<string, DomainModelShape>;
+}
+
+export interface DomainValidationResult {
+  readonly warnings: string[];
+}
+
+export function validateContractDomain(contract: DomainContractShape): DomainValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const modelNames = new Set(Object.keys(contract.models));
+
+  validateRoots(contract, modelNames, errors);
+  validateVariantsAndBases(contract, modelNames, errors);
+  validateRelationTargets(contract, modelNames, errors);
+  validateDiscriminators(contract, errors);
+  detectOrphanedModels(contract, modelNames, warnings);
+
+  if (errors.length > 0) {
+    throw new Error(`Contract domain validation failed:\n- ${errors.join('\n- ')}`);
+  }
+
+  return { warnings };
+}
+
+function validateRoots(
+  contract: DomainContractShape,
+  modelNames: Set<string>,
+  errors: string[],
+): void {
+  const seenValues = new Set<string>();
+  for (const [rootKey, modelName] of Object.entries(contract.roots)) {
+    if (seenValues.has(modelName)) {
+      errors.push(`Duplicate root value: "${modelName}" is mapped by multiple root keys`);
+    }
+    seenValues.add(modelName);
+
+    if (!modelNames.has(modelName)) {
+      errors.push(
+        `Root "${rootKey}" references model "${modelName}" which does not exist in models`,
+      );
+    }
+  }
+}
+
+function validateVariantsAndBases(
+  contract: DomainContractShape,
+  modelNames: Set<string>,
+  errors: string[],
+): void {
+  for (const [modelName, model] of Object.entries(contract.models)) {
+    if (model.variants) {
+      for (const variantName of Object.keys(model.variants)) {
+        if (!modelNames.has(variantName)) {
+          errors.push(
+            `Model "${modelName}" lists variant "${variantName}" which does not exist in models`,
+          );
+          continue;
+        }
+        const variantModel = contract.models[variantName];
+        if (!variantModel) continue;
+        if (variantModel.base !== modelName) {
+          errors.push(
+            `Variant "${variantName}" has base "${variantModel.base ?? '(none)'}" but expected "${modelName}"`,
+          );
+        }
+      }
+    }
+
+    if (model.base) {
+      if (!modelNames.has(model.base)) {
+        errors.push(`Model "${modelName}" has base "${model.base}" which does not exist in models`);
+        continue;
+      }
+      const baseModel = contract.models[model.base];
+      if (!baseModel) continue;
+      if (!baseModel.variants || !(modelName in baseModel.variants)) {
+        errors.push(
+          `Model "${modelName}" has base "${model.base}" which does not list it as a variant`,
+        );
+      }
+    }
+  }
+}
+
+function validateRelationTargets(
+  contract: DomainContractShape,
+  modelNames: Set<string>,
+  errors: string[],
+): void {
+  for (const [modelName, model] of Object.entries(contract.models)) {
+    for (const [relName, relation] of Object.entries(model.relations)) {
+      if (!modelNames.has(relation.to)) {
+        errors.push(
+          `Relation "${relName}" on model "${modelName}" targets "${relation.to}" which does not exist in models`,
+        );
+      }
+    }
+  }
+}
+
+function validateDiscriminators(contract: DomainContractShape, errors: string[]): void {
+  for (const [modelName, model] of Object.entries(contract.models)) {
+    if (model.discriminator) {
+      if (!model.variants || Object.keys(model.variants).length === 0) {
+        errors.push(`Model "${modelName}" has discriminator but no variants`);
+      }
+      if (!(model.discriminator.field in model.fields)) {
+        errors.push(
+          `Discriminator field "${model.discriminator.field}" is not a field on model "${modelName}"`,
+        );
+      }
+    }
+
+    if (model.variants && Object.keys(model.variants).length > 0 && !model.discriminator) {
+      errors.push(`Model "${modelName}" has variants but no discriminator`);
+    }
+
+    // Single-level polymorphism only: a variant (model with `base`) cannot itself
+    // declare discriminator/variants. Multi-level polymorphism is out of scope per ADR 2.
+    if (model.base) {
+      if (model.discriminator) {
+        errors.push(`Model "${modelName}" has base and must not have discriminator`);
+      }
+      if (model.variants && Object.keys(model.variants).length > 0) {
+        errors.push(`Model "${modelName}" has base and must not have variants`);
+      }
+    }
+  }
+}
+
+function detectOrphanedModels(
+  contract: DomainContractShape,
+  modelNames: Set<string>,
+  warnings: string[],
+): void {
+  const referenced = new Set<string>();
+
+  for (const modelName of Object.values(contract.roots)) {
+    referenced.add(modelName);
+  }
+
+  for (const model of Object.values(contract.models)) {
+    for (const relation of Object.values(model.relations)) {
+      referenced.add(relation.to);
+    }
+    if (model.variants) {
+      for (const variantName of Object.keys(model.variants)) {
+        referenced.add(variantName);
+      }
+    }
+    if (model.base) {
+      referenced.add(model.base);
+    }
+  }
+
+  for (const modelName of modelNames) {
+    if (!referenced.has(modelName)) {
+      warnings.push(
+        `Orphaned model: "${modelName}" is not referenced by any root, relation, or variant`,
+      );
+    }
+  }
+}

package/src/validate-mongo-contract.ts

@@ -0,0 +1,50 @@
+import { type as arktypeType } from 'arktype';
+import { MongoContractSchema } from './contract-schema';
+import type { MongoContract } from './contract-types';
+import { validateContractDomain } from './validate-domain';
+import { validateMongoStorage } from './validate-storage';
+
+export interface MongoContractIndices {
+  readonly variantToBase: Record<string, string>;
+  readonly modelToVariants: Record<string, string[]>;
+}
+
+export interface ValidatedMongoContract<TContract extends MongoContract> {
+  readonly contract: TContract;
+  readonly indices: MongoContractIndices;
+  readonly warnings: string[];
+}
+
+export function validateMongoContract<TContract extends MongoContract>(
+  value: unknown,
+): ValidatedMongoContract<TContract> {
+  const parsed = MongoContractSchema(value);
+  if (parsed instanceof arktypeType.errors) {
+    throw new Error(`Contract structural validation failed: ${parsed.summary}`);
+  }
+
+  const contract = parsed as unknown as TContract;
+
+  const { warnings } = validateContractDomain(contract);
+  validateMongoStorage(contract);
+
+  const indices = buildIndices(contract);
+
+  return { contract, indices, warnings };
+}
+
+function buildIndices(contract: MongoContract): MongoContractIndices {
+  const variantToBase: Record<string, string> = {};
+  const modelToVariants: Record<string, string[]> = {};
+
+  for (const [modelName, model] of Object.entries(contract.models)) {
+    if (model.base) {
+      variantToBase[modelName] = model.base;
+    }
+    if (model.variants) {
+      modelToVariants[modelName] = Object.keys(model.variants);
+    }
+  }
+
+  return { variantToBase, modelToVariants };
+}