@prisma-next/mongo-query-builder 0.12.0-dev.50 → 0.12.0-dev.51

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@prisma-next/mongo-query-builder",
-  "version": "0.12.0-dev.50",
+  "version": "0.12.0-dev.51",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "Type-safe MongoDB query builder (reads, writes, find-and-modify, pipeline-terminal writes) with document shape tracking",
   "dependencies": {
-    "@prisma-next/contract": "0.12.0-dev.50",
-    "@prisma-next/mongo-contract": "0.12.0-dev.50",
-    "@prisma-next/mongo-query-ast": "0.12.0-dev.50",
-    "@prisma-next/mongo-value": "0.12.0-dev.50",
-    "@prisma-next/utils": "0.12.0-dev.50"
+    "@prisma-next/contract": "0.12.0-dev.51",
+    "@prisma-next/mongo-contract": "0.12.0-dev.51",
+    "@prisma-next/mongo-query-ast": "0.12.0-dev.51",
+    "@prisma-next/mongo-value": "0.12.0-dev.51",
+    "@prisma-next/utils": "0.12.0-dev.51"
   },
   "devDependencies": {
-    "@prisma-next/tsconfig": "0.12.0-dev.50",
-    "@prisma-next/tsdown": "0.12.0-dev.50",
+    "@prisma-next/tsconfig": "0.12.0-dev.51",
+    "@prisma-next/tsdown": "0.12.0-dev.51",
     "tsdown": "0.22.0",
     "typescript": "5.9.3",
     "vitest": "4.1.6"
@@ -34,6 +34,7 @@
   "types": "./dist/index.d.mts",
   "exports": {
     ".": "./dist/index.mjs",
+    "./contract-free": "./dist/exports/contract-free.mjs",
     "./package.json": "./package.json"
   },
   "engines": {

package/src/contract-free/collection.ts

@@ -0,0 +1,178 @@
+import {
+  AggregateCommand,
+  FindOneAndUpdateCommand,
+  InsertOneCommand,
+  MongoAndExpr,
+  type MongoFilterExpr,
+  MongoLimitStage,
+  MongoMatchStage,
+  type MongoPipelineStage,
+  MongoSortStage,
+  type MongoUpdatePipelineStage,
+} from '@prisma-next/mongo-query-ast/execution';
+import type { MongoValue } from '@prisma-next/mongo-value';
+import { createFieldAccessor, type FieldAccessor } from '../field-accessor';
+import type { DocShape } from '../types';
+import { resolveUpdaterResult, type UpdaterResult } from '../update-ops';
+
+/**
+ * Fold an array of filter expressions into a single `MongoFilterExpr`. Length-1
+ * short-circuits to avoid a redundant `$and` wrapper; the call site never writes
+ * `MongoAndExpr.of([...])` directly.
+ */
+function foldFilters(filters: ReadonlyArray<MongoFilterExpr>): MongoFilterExpr {
+  const first = filters[0];
+  if (first === undefined) {
+    throw new Error('foldFilters: invariant violated — empty filter list');
+  }
+  return filters.length === 1 ? first : MongoAndExpr.of(filters);
+}
+
+/**
+ * Fluent aggregate chain. Accumulates `$match` / `$sort` / `$limit` stages and
+ * produces an `AggregateCommand` via `.build()`.
+ *
+ * Instances are immutable — each stage method returns a new chain.
+ */
+export class AggregateChain<Shape extends DocShape> {
+  readonly #collection: string;
+  readonly #stages: ReadonlyArray<MongoPipelineStage>;
+
+  constructor(collection: string, stages: ReadonlyArray<MongoPipelineStage>) {
+    this.#collection = collection;
+    this.#stages = stages;
+  }
+
+  match(filterFn: (fields: FieldAccessor<Shape>) => MongoFilterExpr): AggregateChain<Shape> {
+    const f = createFieldAccessor<Shape>();
+    const filter = filterFn(f);
+    return new AggregateChain<Shape>(this.#collection, [
+      ...this.#stages,
+      new MongoMatchStage(filter),
+    ]);
+  }
+
+  sort(spec: Record<string, 1 | -1>): AggregateChain<Shape> {
+    return new AggregateChain<Shape>(this.#collection, [...this.#stages, new MongoSortStage(spec)]);
+  }
+
+  limit(n: number): AggregateChain<Shape> {
+    return new AggregateChain<Shape>(this.#collection, [...this.#stages, new MongoLimitStage(n)]);
+  }
+
+  build(): AggregateCommand {
+    return new AggregateCommand(this.#collection, this.#stages);
+  }
+}
+
+/**
+ * Fluent find-and-modify chain. Holds an accumulated list of filter expressions
+ * (AND-folded into the wire command's `filter` slot) and exposes
+ * `.findOneAndUpdate(...)` as the only terminal.
+ *
+ * Multiple `.match()` calls AND-fold internally — `MongoAndExpr.of` never
+ * appears at the call site.
+ *
+ * Instances are immutable — `.match()` returns a new `FilteredBuilder`.
+ */
+export class FilteredBuilder<Shape extends DocShape> {
+  readonly #collection: string;
+  readonly #filters: ReadonlyArray<MongoFilterExpr>;
+
+  constructor(collection: string, filters: ReadonlyArray<MongoFilterExpr>) {
+    if (filters.length === 0) {
+      throw new Error('FilteredBuilder requires at least one filter');
+    }
+    this.#collection = collection;
+    this.#filters = filters;
+  }
+
+  match(filterFn: (fields: FieldAccessor<Shape>) => MongoFilterExpr): FilteredBuilder<Shape> {
+    const f = createFieldAccessor<Shape>();
+    const filter = filterFn(f);
+    return new FilteredBuilder<Shape>(this.#collection, [...this.#filters, filter]);
+  }
+
+  findOneAndUpdate(
+    updaterFn: (fields: FieldAccessor<Shape>) => UpdaterResult,
+    opts: { readonly upsert?: boolean; readonly returnDocument?: 'before' | 'after' } = {},
+  ): FindOneAndUpdateCommand {
+    const filter = foldFilters(this.#filters);
+    const f = createFieldAccessor<Shape>();
+    const items = updaterFn(f);
+    const update = resolveUpdaterResult(items);
+    return new FindOneAndUpdateCommand(
+      this.#collection,
+      filter,
+      update,
+      opts.upsert ?? false,
+      undefined,
+      opts.returnDocument ?? 'after',
+    );
+  }
+}
+
+/**
+ * Contract-free fluent Mongo collection builder. Produces the canonical
+ * `AggregateCommand` / `InsertOneCommand` / `FindOneAndUpdateCommand` command
+ * nodes without any contract coupling — parameterised by an explicit `DocShape`
+ * instead of a `MongoContract`.
+ *
+ * Mirrors SQL's `table(source, schema)` → `TableHandle` in spirit: a top-level
+ * entry point that exposes fluent query chains from which call sites never write
+ * `new MongoMatchStage(...)`, `MongoAndExpr.of([...])`, or `new AggregateCommand(...)`.
+ *
+ * ```ts
+ * const markerLedger = collection<MarkerLedgerDocShape>('_prisma_migrations');
+ *
+ * // aggregate
+ * markerLedger.aggregate().match(f => f._id.eq(space)).limit(1).build();
+ *
+ * // insertOne
+ * markerLedger.insertOne({ _id: space, space, storageHash });
+ *
+ * // findOneAndUpdate (CAS)
+ * markerLedger.match(f => f._id.eq(space)).match(f => f.storageHash.eq(expectedFrom))
+ *   .findOneAndUpdate(f => [f.stage.set({ storageHash: newHash })], { upsert: false });
+ * ```
+ */
+export interface CollectionBuilder<Shape extends DocShape> {
+  aggregate(): AggregateChain<Shape>;
+  insertOne(document: Record<string, MongoValue>): InsertOneCommand;
+  match(filterFn: (fields: FieldAccessor<Shape>) => MongoFilterExpr): FilteredBuilder<Shape>;
+}
+
+class CollectionBuilderImpl<Shape extends DocShape> implements CollectionBuilder<Shape> {
+  readonly #name: string;
+
+  constructor(name: string) {
+    this.#name = name;
+  }
+
+  aggregate(): AggregateChain<Shape> {
+    return new AggregateChain<Shape>(this.#name, []);
+  }
+
+  insertOne(document: Record<string, MongoValue>): InsertOneCommand {
+    return new InsertOneCommand(this.#name, document);
+  }
+
+  match(filterFn: (fields: FieldAccessor<Shape>) => MongoFilterExpr): FilteredBuilder<Shape> {
+    const f = createFieldAccessor<Shape>();
+    const filter = filterFn(f);
+    return new FilteredBuilder<Shape>(this.#name, [filter]);
+  }
+}
+
+/**
+ * Declare a contract-free collection builder parameterised by a `DocShape`.
+ * The collection name is bound once; field access reuses `createFieldAccessor`
+ * so the shape is typed at every call site without a contract.
+ *
+ * @param name The MongoDB collection name (e.g. `'_prisma_migrations'`)
+ */
+export function collection<Shape extends DocShape>(name: string): CollectionBuilder<Shape> {
+  return new CollectionBuilderImpl<Shape>(name);
+}
+
+export type { MongoUpdatePipelineStage };

package/src/exports/contract-free.ts

@@ -0,0 +1,6 @@
+export {
+  AggregateChain,
+  type CollectionBuilder,
+  collection,
+  FilteredBuilder,
+} from '../contract-free/collection';

package/src/exports/index.ts

@@ -13,7 +13,7 @@ export type {
   LeafExpression,
   ObjectExpression,
 } from '../field-accessor';
-export { createFieldAccessor } from '../field-accessor';
+export { createFieldAccessor, expr } from '../field-accessor';
 export type {
   LookupBuilder,
   LookupBuilderWithKey,

package/src/field-accessor.ts

@@ -7,6 +7,7 @@ import {
   MongoAddFieldsStage,
   MongoAggFieldRef,
   MongoExistsExpr,
+  MongoExprFilter,
   MongoFieldFilter,
   MongoProjectStage,
   MongoReplaceRootStage,
@@ -58,6 +59,14 @@ export interface LeafExpression<F extends DocField> extends TypedAggExpr<F> {
   nin(values: ReadonlyArray<MongoValue>): MongoFilterExpr;
   exists(flag?: boolean): MongoFilterExpr;
 
+  /**
+   * `$type` filter: `{ field: { $type: bsonType } }`. Rides
+   * `MongoFieldFilter`'s generic `op` string — no dedicated AST node. The
+   * BSON type is expressed as Mongo's alias string (e.g. `'string'`) or
+   * numeric type code; an array selects any of several types.
+   */
+  type(bsonType: MongoValue): MongoFilterExpr;
+
   // Update operators ($set family)
   set(value: MongoValue): TypedUpdateOp;
   unset(): TypedUpdateOp;
@@ -203,6 +212,17 @@ export type FieldAccessor<S extends DocShape, N extends NestedDocShape = Record<
     rawPath<F extends DocField = DocField>(path: string): LeafExpression<F>;
   };
 
+/**
+ * Wrap a boolean aggregation expression as an `$expr` filter
+ * (`MongoExprFilter`). Lets a `$match` express an aggregation-expression
+ * predicate — e.g. comparing two field references via `fn.eq(a, b)` — in
+ * the typed AST rather than via a raw escape hatch. Pairs with `.type()`
+ * to express filters like `{ _id: { $type: 'string' }, $expr: { $eq: ['$_id', '$space'] } }`.
+ */
+export function expr(predicate: TypedAggExpr<DocField>): MongoFilterExpr {
+  return MongoExprFilter.of(predicate.node);
+}
+
 function buildExpression<F extends DocField>(path: string): Expression<F> {
   // The runtime object carries the full operator surface unconditionally;
   // `ObjectExpression` is a strict subset of `LeafExpression`, so a single
@@ -223,6 +243,7 @@ function buildExpression<F extends DocField>(path: string): Expression<F> {
     nin: (values: ReadonlyArray<MongoValue>) => MongoFieldFilter.nin(path, values),
     exists: (flag?: boolean) =>
       flag === false ? MongoExistsExpr.notExists(path) : MongoExistsExpr.exists(path),
+    type: (bsonType: MongoValue) => MongoFieldFilter.of(path, '$type', bsonType),
 
     set: (value: MongoValue) => setOp(path, value),
     unset: () => unsetOp(path),