@prisma-next/mongo-schema-ir 0.0.1

package/README.md

@@ -0,0 +1,58 @@
+# @prisma-next/mongo-schema-ir
+
+MongoDB Schema Intermediate Representation (IR) for migration diffing.
+
+## Overview
+
+This package defines the in-memory representation of MongoDB collection schemas used by the migration planner to diff desired vs. actual state. It provides an immutable AST of collections, indexes, validators, and collection options, plus comparison utilities for index equivalence.
+
+## Responsibilities
+
+- **Schema AST nodes**: `MongoSchemaIR` (root), `MongoSchemaCollection`, `MongoSchemaIndex`, `MongoSchemaValidator`, `MongoSchemaCollectionOptions` — frozen, visitable AST nodes representing MongoDB schema elements. `MongoSchemaIR` is the root node holding collections as sorted children with name-based lookup via `collection(name)`.
+- **Index equivalence**: `indexesEquivalent()` compares two `MongoSchemaIndex` nodes field-by-field (keys, direction, unique, sparse, TTL, partial filter, wildcardProjection, collation, weights, default_language, language_override). Used by the planner to decide create/drop operations.
+- **Deep equality**: `deepEqual()` provides key-order-sensitive structural comparison for MongoDB values. For key-order-independent comparison, use `canonicalize()`.
+- **Canonical serialization**: `canonicalize()` produces a key-order-independent string representation of values. Used by the planner for index lookup keys.
+- **Visitor pattern**: `MongoSchemaVisitor<R>` enables extensible traversal without modifying AST nodes.
+
+## Dependencies
+
+- **`@prisma-next/mongo-contract`**: `MongoIndexKey` type for index key definitions.
+
+**Dependents:**
+
+- `@prisma-next/adapter-mongo` — uses the schema IR via `contractToMongoSchemaIR()` for contract-to-schema conversion, migration planning, and filter evaluation.
+
+## Usage
+
+```typescript
+import {
+  MongoSchemaIR,
+  MongoSchemaCollection,
+  MongoSchemaIndex,
+  indexesEquivalent,
+} from '@prisma-next/mongo-schema-ir';
+
+const index = new MongoSchemaIndex({
+  keys: [{ field: 'email', direction: 1 }],
+  unique: true,
+});
+
+const collection = new MongoSchemaCollection({
+  name: 'users',
+  indexes: [index],
+});
+
+const ir = new MongoSchemaIR([collection]);
+
+ir.collection('users');     // MongoSchemaCollection
+ir.collectionNames;         // ['users']
+ir.collections;             // sorted ReadonlyArray<MongoSchemaCollection>
+
+indexesEquivalent(index, index); // true
+```
+
+## Architecture
+
+- **Domain**: `mongo`
+- **Layer**: `tooling`
+- **Plane**: `shared` (migration-plane)

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@prisma-next/mongo-schema-ir",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "description": "MongoDB schema IR AST for migration diffing",
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
+  },
+  "dependencies": {
+    "@prisma-next/mongo-contract": "workspace:*"
+  },
+  "devDependencies": {
+    "@prisma-next/test-utils": "workspace:*",
+    "@prisma-next/tsconfig": "workspace:*",
+    "@prisma-next/tsdown": "workspace:*",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/exports/index.d.mts",
+      "import": "./dist/exports/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/2-mongo-family/3-tooling/mongo-schema-ir"
+  }
+}

package/src/canonicalize.ts

@@ -0,0 +1,10 @@
+export function canonicalize(obj: unknown): string {
+  if (obj === null) return 'null';
+  if (obj === undefined) return 'undefined';
+  if (typeof obj !== 'object') return JSON.stringify(obj);
+  if (Array.isArray(obj)) return `[${obj.map(canonicalize).join(',')}]`;
+  const record = obj as Record<string, unknown>;
+  const sorted = Object.keys(record).sort();
+  const entries = sorted.map((k) => `${JSON.stringify(k)}:${canonicalize(record[k])}`);
+  return `{${entries.join(',')}}`;
+}

package/src/exports/index.ts

@@ -0,0 +1,14 @@
+export { canonicalize } from '../canonicalize';
+export { deepEqual, indexesEquivalent } from '../index-equivalence';
+export type { MongoSchemaCollectionCtorOptions } from '../schema-collection';
+export { MongoSchemaCollection } from '../schema-collection';
+export type { MongoSchemaCollectionOptionsInput } from '../schema-collection-options';
+export { MongoSchemaCollectionOptions } from '../schema-collection-options';
+export type { MongoSchemaIndexOptions } from '../schema-index';
+export { MongoSchemaIndex } from '../schema-index';
+export { MongoSchemaIR } from '../schema-ir';
+export { MongoSchemaNode } from '../schema-node';
+export type { MongoSchemaValidatorOptions } from '../schema-validator';
+export { MongoSchemaValidator } from '../schema-validator';
+export type { AnyMongoSchemaNode } from '../types';
+export type { MongoSchemaVisitor } from '../visitor';

package/src/index-equivalence.ts

@@ -0,0 +1,60 @@
+import { canonicalize } from './canonicalize';
+import type { MongoSchemaIndex } from './schema-index';
+
+/**
+ * Key-order-sensitive structural comparison. For key-order-independent
+ * comparison (e.g. lookup key construction), use {@link canonicalize}.
+ */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (a === undefined || b === undefined) return false;
+  if (typeof a !== typeof b) return false;
+
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b)) return false;
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+
+  if (typeof a === 'object' && typeof b === 'object') {
+    const aObj = a as Record<string, unknown>;
+    const bObj = b as Record<string, unknown>;
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
+    if (aKeys.length !== bKeys.length) return false;
+    for (let i = 0; i < aKeys.length; i++) {
+      if (aKeys[i] !== bKeys[i]) return false;
+      const key = aKeys[i] as string;
+      if (!deepEqual(aObj[key], bObj[key])) return false;
+    }
+    return true;
+  }
+
+  return false;
+}
+
+export function indexesEquivalent(a: MongoSchemaIndex, b: MongoSchemaIndex): boolean {
+  if (a.keys.length !== b.keys.length) return false;
+  for (let i = 0; i < a.keys.length; i++) {
+    const aKey = a.keys[i];
+    const bKey = b.keys[i];
+    if (!aKey || !bKey) return false;
+    if (aKey.field !== bKey.field) return false;
+    if (aKey.direction !== bKey.direction) return false;
+  }
+  if (a.unique !== b.unique) return false;
+  if (a.sparse !== b.sparse) return false;
+  if (a.expireAfterSeconds !== b.expireAfterSeconds) return false;
+  if (canonicalize(a.partialFilterExpression) !== canonicalize(b.partialFilterExpression))
+    return false;
+  if (canonicalize(a.wildcardProjection) !== canonicalize(b.wildcardProjection)) return false;
+  if (canonicalize(a.collation) !== canonicalize(b.collation)) return false;
+  if (canonicalize(a.weights) !== canonicalize(b.weights)) return false;
+  if (a.default_language !== b.default_language) return false;
+  if (a.language_override !== b.language_override) return false;
+  return true;
+}

package/src/schema-collection-options.ts

@@ -0,0 +1,39 @@
+import { MongoSchemaNode } from './schema-node';
+import type { MongoSchemaVisitor } from './visitor';
+
+export interface MongoSchemaCollectionOptionsInput {
+  readonly capped?: { size: number; max?: number };
+  readonly timeseries?: {
+    timeField: string;
+    metaField?: string;
+    granularity?: 'seconds' | 'minutes' | 'hours';
+  };
+  readonly collation?: Record<string, unknown>;
+  readonly changeStreamPreAndPostImages?: { enabled: boolean };
+  readonly clusteredIndex?: { name?: string };
+}
+
+export class MongoSchemaCollectionOptions extends MongoSchemaNode {
+  readonly kind = 'collectionOptions' as const;
+  readonly capped?: { size: number; max?: number } | undefined;
+  readonly timeseries?:
+    | { timeField: string; metaField?: string; granularity?: 'seconds' | 'minutes' | 'hours' }
+    | undefined;
+  readonly collation?: Record<string, unknown> | undefined;
+  readonly changeStreamPreAndPostImages?: { enabled: boolean } | undefined;
+  readonly clusteredIndex?: { name?: string } | undefined;
+
+  constructor(options: MongoSchemaCollectionOptionsInput) {
+    super();
+    this.capped = options.capped;
+    this.timeseries = options.timeseries;
+    this.collation = options.collation;
+    this.changeStreamPreAndPostImages = options.changeStreamPreAndPostImages;
+    this.clusteredIndex = options.clusteredIndex;
+    this.freeze();
+  }
+
+  accept<R>(visitor: MongoSchemaVisitor<R>): R {
+    return visitor.collectionOptions(this);
+  }
+}

package/src/schema-collection.ts

@@ -0,0 +1,33 @@
+import type { MongoSchemaCollectionOptions } from './schema-collection-options';
+import type { MongoSchemaIndex } from './schema-index';
+import { MongoSchemaNode } from './schema-node';
+import type { MongoSchemaValidator } from './schema-validator';
+import type { MongoSchemaVisitor } from './visitor';
+
+export interface MongoSchemaCollectionCtorOptions {
+  readonly name: string;
+  readonly indexes?: ReadonlyArray<MongoSchemaIndex>;
+  readonly validator?: MongoSchemaValidator;
+  readonly options?: MongoSchemaCollectionOptions;
+}
+
+export class MongoSchemaCollection extends MongoSchemaNode {
+  readonly kind = 'collection' as const;
+  readonly name: string;
+  readonly indexes: ReadonlyArray<MongoSchemaIndex>;
+  readonly validator?: MongoSchemaValidator | undefined;
+  readonly options?: MongoSchemaCollectionOptions | undefined;
+
+  constructor(options: MongoSchemaCollectionCtorOptions) {
+    super();
+    this.name = options.name;
+    this.indexes = options.indexes ?? [];
+    this.validator = options.validator;
+    this.options = options.options;
+    this.freeze();
+  }
+
+  accept<R>(visitor: MongoSchemaVisitor<R>): R {
+    return visitor.collection(this);
+  }
+}

package/src/schema-index.ts

@@ -0,0 +1,49 @@
+import type { MongoIndexKey } from '@prisma-next/mongo-contract';
+import { MongoSchemaNode } from './schema-node';
+import type { MongoSchemaVisitor } from './visitor';
+
+export interface MongoSchemaIndexOptions {
+  readonly keys: ReadonlyArray<MongoIndexKey>;
+  readonly unique?: boolean | undefined;
+  readonly sparse?: boolean | undefined;
+  readonly expireAfterSeconds?: number | undefined;
+  readonly partialFilterExpression?: Record<string, unknown> | undefined;
+  readonly wildcardProjection?: Record<string, 0 | 1> | undefined;
+  readonly collation?: Record<string, unknown> | undefined;
+  readonly weights?: Record<string, number> | undefined;
+  readonly default_language?: string | undefined;
+  readonly language_override?: string | undefined;
+}
+
+export class MongoSchemaIndex extends MongoSchemaNode {
+  readonly kind = 'index' as const;
+  readonly keys: ReadonlyArray<MongoIndexKey>;
+  readonly unique: boolean;
+  readonly sparse?: boolean | undefined;
+  readonly expireAfterSeconds?: number | undefined;
+  readonly partialFilterExpression?: Record<string, unknown> | undefined;
+  readonly wildcardProjection?: Record<string, 0 | 1> | undefined;
+  readonly collation?: Record<string, unknown> | undefined;
+  readonly weights?: Record<string, number> | undefined;
+  readonly default_language?: string | undefined;
+  readonly language_override?: string | undefined;
+
+  constructor(options: MongoSchemaIndexOptions) {
+    super();
+    this.keys = options.keys;
+    this.unique = options.unique ?? false;
+    this.sparse = options.sparse;
+    this.expireAfterSeconds = options.expireAfterSeconds;
+    this.partialFilterExpression = options.partialFilterExpression;
+    this.wildcardProjection = options.wildcardProjection;
+    this.collation = options.collation;
+    this.weights = options.weights;
+    this.default_language = options.default_language;
+    this.language_override = options.language_override;
+    this.freeze();
+  }
+
+  accept<R>(visitor: MongoSchemaVisitor<R>): R {
+    return visitor.index(this);
+  }
+}

package/src/schema-ir.ts

@@ -0,0 +1,28 @@
+import type { MongoSchemaCollection } from './schema-collection';
+import { MongoSchemaNode } from './schema-node';
+import type { MongoSchemaVisitor } from './visitor';
+
+export class MongoSchemaIR extends MongoSchemaNode {
+  readonly kind = 'schema' as const;
+  readonly collections: ReadonlyArray<MongoSchemaCollection>;
+  readonly collectionNames: ReadonlyArray<string>;
+
+  private readonly _byName: Map<string, MongoSchemaCollection>;
+
+  constructor(collections: ReadonlyArray<MongoSchemaCollection>) {
+    super();
+    const sorted = [...collections].sort((a, b) => a.name.localeCompare(b.name));
+    this.collections = sorted;
+    this._byName = new Map(sorted.map((c) => [c.name, c]));
+    this.collectionNames = sorted.map((c) => c.name);
+    this.freeze();
+  }
+
+  accept<R>(visitor: MongoSchemaVisitor<R>): R {
+    return visitor.schema(this);
+  }
+
+  collection(name: string): MongoSchemaCollection | undefined {
+    return this._byName.get(name);
+  }
+}

package/src/schema-node.ts

@@ -0,0 +1,11 @@
+import type { MongoSchemaVisitor } from './visitor';
+
+export abstract class MongoSchemaNode {
+  abstract readonly kind: string;
+
+  abstract accept<R>(visitor: MongoSchemaVisitor<R>): R;
+
+  protected freeze(): void {
+    Object.freeze(this);
+  }
+}

package/src/schema-validator.ts

@@ -0,0 +1,27 @@
+import { MongoSchemaNode } from './schema-node';
+import type { MongoSchemaVisitor } from './visitor';
+
+export interface MongoSchemaValidatorOptions {
+  readonly jsonSchema: Record<string, unknown>;
+  readonly validationLevel: 'strict' | 'moderate';
+  readonly validationAction: 'error' | 'warn';
+}
+
+export class MongoSchemaValidator extends MongoSchemaNode {
+  readonly kind = 'validator' as const;
+  readonly jsonSchema: Record<string, unknown>;
+  readonly validationLevel: 'strict' | 'moderate';
+  readonly validationAction: 'error' | 'warn';
+
+  constructor(options: MongoSchemaValidatorOptions) {
+    super();
+    this.jsonSchema = options.jsonSchema;
+    this.validationLevel = options.validationLevel;
+    this.validationAction = options.validationAction;
+    this.freeze();
+  }
+
+  accept<R>(visitor: MongoSchemaVisitor<R>): R {
+    return visitor.validator(this);
+  }
+}

package/src/types.ts

@@ -0,0 +1,12 @@
+import type { MongoSchemaCollection } from './schema-collection';
+import type { MongoSchemaCollectionOptions } from './schema-collection-options';
+import type { MongoSchemaIndex } from './schema-index';
+import type { MongoSchemaIR } from './schema-ir';
+import type { MongoSchemaValidator } from './schema-validator';
+
+export type AnyMongoSchemaNode =
+  | MongoSchemaIR
+  | MongoSchemaCollection
+  | MongoSchemaCollectionOptions
+  | MongoSchemaIndex
+  | MongoSchemaValidator;

package/src/visitor.ts

@@ -0,0 +1,13 @@
+import type { MongoSchemaCollection } from './schema-collection';
+import type { MongoSchemaCollectionOptions } from './schema-collection-options';
+import type { MongoSchemaIndex } from './schema-index';
+import type { MongoSchemaIR } from './schema-ir';
+import type { MongoSchemaValidator } from './schema-validator';
+
+export interface MongoSchemaVisitor<R> {
+  schema(node: MongoSchemaIR): R;
+  collection(node: MongoSchemaCollection): R;
+  index(node: MongoSchemaIndex): R;
+  validator(node: MongoSchemaValidator): R;
+  collectionOptions(node: MongoSchemaCollectionOptions): R;
+}