@querykitjs/mongodb 0.0.0-stage → 1.0.1

package/dist/repository-CPlf87mC.d.cts

@@ -0,0 +1,184 @@
+import { ObjectId, Document, Collection } from 'mongodb';
+import { z } from 'zod';
+import * as Core from '@querykitjs/core';
+import { AllRows, MutationCount, MutationRows } from '@querykitjs/core';
+
+/**
+ * `@querykitjs/mongodb` — public types. The DSL, filter and meta types come from `@querykitjs/core`
+ * (REQUIREMENTS R7); they are specialized here over a document type (`TDoc`), with the raw
+ * escape hatch bound to a native Mongo filter object (branded by core `raw()`, R19).
+ * The surface mirrors the other adapters, so one frontend request contract fits every backend.
+ */
+
+/** Plain (lean) document type — what reads return. */
+type Row<TDoc> = TDoc;
+/**
+ * Insertable shape — the document minus auto-managed fields (`_id`, timestamps),
+ * with the rest optional (the zod schema owns `required` and defaults; that
+ * metadata isn't in the doc type, so unlike drizzle-pg we can't mark it here).
+ */
+type Insert<TDoc> = Partial<Omit<TDoc, "_id" | "createdAt" | "updatedAt">>;
+/** Value accepted anywhere an id is expected. */
+type Id = string | number | ObjectId;
+/**
+ * Raw Mongo predicate fragment — the filter escape hatch (`TRaw`), a plain Mongo query
+ * object. Accepted only when server code brands it with core `raw()` (R19).
+ */
+type RawFilter<_TDoc = unknown> = Record<string, unknown>;
+/** Union of a document's field keys. */
+type FieldKey<TDoc> = keyof TDoc & string;
+/**
+ * A field key that also accepts any `string`. Filter/sort keys arrive from the
+ * wire as plain strings and the adapter skips the ones it cannot resolve, so a
+ * validated payload can go straight into a repository call with no `as` cast.
+ * Autocomplete still suggests the document's real fields.
+ */
+type LooseFieldKey<TDoc> = Core.LooseKey<FieldKey<TDoc>>;
+type FilterOperator = Core.FilterOperator;
+type FilterScalar = Core.FilterScalar;
+type FilterValue = Core.FilterValue;
+type FieldCondition<TDoc = Record<string, unknown>> = Core.FieldCondition<LooseFieldKey<TDoc>>;
+type AndGroup<TDoc = Record<string, unknown>> = Core.AndGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type OrGroup<TDoc = Record<string, unknown>> = Core.OrGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type NotGroup<TDoc = Record<string, unknown>> = Core.NotGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type FilterNode<TDoc = Record<string, unknown>> = Core.FilterNode<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type Filter<TDoc = Record<string, unknown>> = Core.Filter<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type SortDirection = Core.SortDirection;
+/** One sort field by typed field key (`{ key, direction }`) — autocomplete. */
+type SortItem<TDoc = Record<string, unknown>> = Core.SortItem<LooseFieldKey<TDoc>>;
+/**
+ * Sort — **always an array** of `{ key, direction }` (multi-field). This is the
+ * exact shape the querykit frontend sends (`@querykitjs/web` decodes its
+ * `sortType=-createdAt,id` URL string into it).
+ */
+type Sort<TDoc = Record<string, unknown>> = SortItem<TDoc>[];
+type ColumnSelection<TDoc = Record<string, unknown>> = Partial<Record<FieldKey<TDoc>, boolean>>;
+/** Relations (`with`): refused in this version unless the repository lists `relations` — no `$lookup` yet (task 017 L3). */
+type WithRelations = Record<string, unknown>;
+interface QueryParams<TDoc = Record<string, unknown>> {
+    filter?: Filter<TDoc>;
+    sort?: Sort<TDoc>;
+    columns?: ColumnSelection<TDoc>;
+    with?: WithRelations;
+    /** Include soft-deleted docs (schemas with a `deletedAt` path). */
+    withDeleted?: boolean;
+}
+/** Equality scope applied to every operation of a scoped repository. */
+type Scope<TDoc = Record<string, unknown>> = Core.Scope<FieldKey<TDoc>>;
+interface ByIdParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc> {
+    /** Field to match against the id. Defaults to `"id"` (→ `_id`). */
+    idKey?: LooseFieldKey<TDoc>;
+}
+/** Options for {@link Repository.upsert} / {@link Repository.upsertMany}. */
+type UpsertOptions<TDoc = Record<string, unknown>> = Core.UpsertOptions<FieldKey<TDoc>, Insert<TDoc>>;
+/** Aggregate query specification (`count`/`sum`/`avg`/`min`/`max` + `groupBy`). */
+type AggregateSpec<TDoc = Record<string, unknown>> = Core.AggregateSpec<FieldKey<TDoc>, Filter<TDoc>>;
+/** One aggregated result row (group fields + aggregate values). */
+type AggregateRow = Record<string, unknown>;
+
+interface OffsetParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc> {
+    page?: number;
+    perPage?: number;
+    /** `false` — no count query: `perPage + 1` rows are read, `total_items` / `total_pages` are `null` (task 013). Default `true`. */
+    withTotal?: boolean;
+}
+type OffsetMeta = Core.OffsetMeta;
+interface OffsetResult<T> {
+    data: T[];
+    meta: OffsetMeta;
+}
+interface InfiniteParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc> {
+    limit?: number;
+    offset?: number;
+}
+type InfiniteMeta = Core.InfiniteMeta;
+interface InfiniteResult<T> {
+    data: T[];
+    meta: InfiniteMeta;
+}
+interface CursorParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc> {
+    limit?: number;
+    cursor?: string | null;
+    /** Field the cursor walks over. Defaults to `"id"` (→ `_id`). */
+    cursorKey?: LooseFieldKey<TDoc>;
+    order?: SortDirection;
+    direction?: "forward" | "backward";
+}
+type CursorMeta = Core.CursorMeta;
+interface CursorResult<T> {
+    data: T[];
+    meta: CursorMeta;
+}
+
+/**
+ * Per-repository options — the same names as the other adapters (REQUIREMENTS R11), plus the
+ * zod `schema` the driver does not have: field types for casting, unknown keys, the default
+ * `filterable` (equality on the schema's fields, R12).
+ */
+interface RepositoryOptions<TDoc = Document> {
+    /** The document's zod object schema — the one source of field types (task 017 Locked 2). */
+    schema: z.ZodObject;
+    /** Fields stored as `ObjectId` (cast from 24-hex strings). Default `["_id"]`. */
+    objectId?: readonly (FieldKey<TDoc> | "_id")[];
+    /** Applied to every read and write (RBAC / tenancy); a value may be `{ in: [...] }`. */
+    scope?: Scope<TDoc>;
+    /** The response always has exactly these fields; the client's `columns` is ignored. */
+    forcedColumns?: ColumnSelection<TDoc>;
+    /** The client's `columns` is intersected with this list. */
+    allowedColumns?: readonly FieldKey<TDoc>[];
+    /** Field → allowed operators (`"*"` all). Absent: equality (`=`, `in`) on the schema's fields. */
+    filterable?: Core.Filterable<FieldKey<TDoc> | "_id">;
+    /** Sortable fields. Absent: `_id` and the createdAt field. */
+    sortable?: readonly (FieldKey<TDoc> | "_id")[];
+    limits?: Partial<Core.QueryLimits>;
+    /** Server time limit per read, in ms (default: the registry's, 2000). */
+    maxTimeMS?: number;
+}
+type TrueKeys<T> = {
+    [K in keyof T]: T[K] extends true ? K : never;
+}[keyof T];
+/** `columns` narrows the row via `Pick`. */
+type Result<TDoc, TColumns> = TColumns extends ColumnSelection<TDoc> ? ([TrueKeys<TColumns>] extends [never] ? TDoc : Pick<TDoc, TrueKeys<TColumns> & keyof TDoc>) : TDoc;
+type Params<TBase, TColumns> = Omit<TBase, "columns"> & {
+    columns?: TColumns;
+};
+interface Repository<TDoc extends Document = Document> {
+    readonly collection: Collection<TDoc>;
+    findAll<const TColumns extends ColumnSelection<TDoc> | undefined = undefined>(params?: Params<QueryParams<TDoc>, TColumns>): Promise<Result<TDoc, TColumns>[]>;
+    findOne<const TColumns extends ColumnSelection<TDoc> | undefined = undefined>(params?: Params<QueryParams<TDoc>, TColumns>): Promise<Result<TDoc, TColumns> | undefined>;
+    findById<const TColumns extends ColumnSelection<TDoc> | undefined = undefined>(id: Id, params?: Params<ByIdParams<TDoc>, TColumns>): Promise<Result<TDoc, TColumns> | undefined>;
+    findList<const TColumns extends ColumnSelection<TDoc> | undefined = undefined>(params?: Params<OffsetParams<TDoc>, TColumns>): Promise<OffsetResult<Result<TDoc, TColumns>>>;
+    findInfinite<const TColumns extends ColumnSelection<TDoc> | undefined = undefined>(params?: Params<InfiniteParams<TDoc>, TColumns>): Promise<InfiniteResult<Result<TDoc, TColumns>>>;
+    findCursor<const TColumns extends ColumnSelection<TDoc> | undefined = undefined>(params?: Params<CursorParams<TDoc>, TColumns>): Promise<CursorResult<Result<TDoc, TColumns>>>;
+    count(filter?: Filter<TDoc>): Promise<number>;
+    exists(filter?: Filter<TDoc>): Promise<boolean>;
+    create(values: Insert<TDoc>): Promise<Row<TDoc>>;
+    createMany(values: Insert<TDoc>[]): Promise<Row<TDoc>[]>;
+    upsert(values: Insert<TDoc>, options: UpsertOptions<TDoc>): Promise<Row<TDoc>>;
+    upsertMany(values: Insert<TDoc>[], options: UpsertOptions<TDoc>): Promise<Row<TDoc>[]>;
+    updateById(id: Id, patch: Partial<Insert<TDoc>>, idKey?: FieldKey<TDoc>): Promise<Row<TDoc> | undefined>;
+    /** One `updateMany`; an empty filter is refused (`empty-filter`) unless it is `{ all: true }`. */
+    updateWhere(filter: Filter<TDoc> | AllRows, patch: Partial<Insert<TDoc>>, options?: {
+        returning?: false;
+    }): Promise<MutationCount>;
+    updateWhere(filter: Filter<TDoc> | AllRows, patch: Partial<Insert<TDoc>>, options: {
+        returning: {
+            limit: number;
+        };
+    }): Promise<MutationRows<Row<TDoc>>>;
+    deleteById(id: Id, idKey?: FieldKey<TDoc>): Promise<Row<TDoc> | undefined>;
+    deleteWhere(filter: Filter<TDoc> | AllRows, options?: {
+        returning?: false;
+    }): Promise<MutationCount>;
+    deleteWhere(filter: Filter<TDoc> | AllRows, options: {
+        returning: {
+            limit: number;
+        };
+    }): Promise<MutationRows<Row<TDoc>>>;
+    softDelete(id: Id, idKey?: FieldKey<TDoc>): Promise<Row<TDoc> | undefined>;
+    restore(id: Id, idKey?: FieldKey<TDoc>): Promise<Row<TDoc> | undefined>;
+    aggregate(spec: AggregateSpec<TDoc>): Promise<AggregateRow[]>;
+    scoped(scope: Scope<TDoc>): Repository<TDoc>;
+}
+
+export type { AggregateRow as A, ByIdParams as B, ColumnSelection as C, FieldKey as F, Id as I, LooseFieldKey as L, NotGroup as N, OffsetMeta as O, QueryParams as Q, RepositoryOptions as R, Scope as S, UpsertOptions as U, WithRelations as W, Repository as a, RawFilter as b, AggregateSpec as c, AndGroup as d, CursorMeta as e, CursorParams as f, CursorResult as g, FieldCondition as h, Filter as i, FilterNode as j, FilterOperator as k, FilterScalar as l, FilterValue as m, InfiniteMeta as n, InfiniteParams as o, InfiniteResult as p, Insert as q, OffsetParams as r, OffsetResult as s, OrGroup as t, Result as u, Row as v, Sort as w, SortDirection as x, SortItem as y };

package/dist/repository-CPlf87mC.d.ts

@@ -0,0 +1,184 @@
+import { ObjectId, Document, Collection } from 'mongodb';
+import { z } from 'zod';
+import * as Core from '@querykitjs/core';
+import { AllRows, MutationCount, MutationRows } from '@querykitjs/core';
+
+/**
+ * `@querykitjs/mongodb` — public types. The DSL, filter and meta types come from `@querykitjs/core`
+ * (REQUIREMENTS R7); they are specialized here over a document type (`TDoc`), with the raw
+ * escape hatch bound to a native Mongo filter object (branded by core `raw()`, R19).
+ * The surface mirrors the other adapters, so one frontend request contract fits every backend.
+ */
+
+/** Plain (lean) document type — what reads return. */
+type Row<TDoc> = TDoc;
+/**
+ * Insertable shape — the document minus auto-managed fields (`_id`, timestamps),
+ * with the rest optional (the zod schema owns `required` and defaults; that
+ * metadata isn't in the doc type, so unlike drizzle-pg we can't mark it here).
+ */
+type Insert<TDoc> = Partial<Omit<TDoc, "_id" | "createdAt" | "updatedAt">>;
+/** Value accepted anywhere an id is expected. */
+type Id = string | number | ObjectId;
+/**
+ * Raw Mongo predicate fragment — the filter escape hatch (`TRaw`), a plain Mongo query
+ * object. Accepted only when server code brands it with core `raw()` (R19).
+ */
+type RawFilter<_TDoc = unknown> = Record<string, unknown>;
+/** Union of a document's field keys. */
+type FieldKey<TDoc> = keyof TDoc & string;
+/**
+ * A field key that also accepts any `string`. Filter/sort keys arrive from the
+ * wire as plain strings and the adapter skips the ones it cannot resolve, so a
+ * validated payload can go straight into a repository call with no `as` cast.
+ * Autocomplete still suggests the document's real fields.
+ */
+type LooseFieldKey<TDoc> = Core.LooseKey<FieldKey<TDoc>>;
+type FilterOperator = Core.FilterOperator;
+type FilterScalar = Core.FilterScalar;
+type FilterValue = Core.FilterValue;
+type FieldCondition<TDoc = Record<string, unknown>> = Core.FieldCondition<LooseFieldKey<TDoc>>;
+type AndGroup<TDoc = Record<string, unknown>> = Core.AndGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type OrGroup<TDoc = Record<string, unknown>> = Core.OrGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type NotGroup<TDoc = Record<string, unknown>> = Core.NotGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type FilterNode<TDoc = Record<string, unknown>> = Core.FilterNode<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type Filter<TDoc = Record<string, unknown>> = Core.Filter<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type SortDirection = Core.SortDirection;
+/** One sort field by typed field key (`{ key, direction }`) — autocomplete. */
+type SortItem<TDoc = Record<string, unknown>> = Core.SortItem<LooseFieldKey<TDoc>>;
+/**
+ * Sort — **always an array** of `{ key, direction }` (multi-field). This is the
+ * exact shape the querykit frontend sends (`@querykitjs/web` decodes its
+ * `sortType=-createdAt,id` URL string into it).
+ */
+type Sort<TDoc = Record<string, unknown>> = SortItem<TDoc>[];
+type ColumnSelection<TDoc = Record<string, unknown>> = Partial<Record<FieldKey<TDoc>, boolean>>;
+/** Relations (`with`): refused in this version unless the repository lists `relations` — no `$lookup` yet (task 017 L3). */
+type WithRelations = Record<string, unknown>;
+interface QueryParams<TDoc = Record<string, unknown>> {
+    filter?: Filter<TDoc>;
+    sort?: Sort<TDoc>;
+    columns?: ColumnSelection<TDoc>;
+    with?: WithRelations;
+    /** Include soft-deleted docs (schemas with a `deletedAt` path). */
+    withDeleted?: boolean;
+}
+/** Equality scope applied to every operation of a scoped repository. */
+type Scope<TDoc = Record<string, unknown>> = Core.Scope<FieldKey<TDoc>>;
+interface ByIdParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc> {
+    /** Field to match against the id. Defaults to `"id"` (→ `_id`). */
+    idKey?: LooseFieldKey<TDoc>;
+}
+/** Options for {@link Repository.upsert} / {@link Repository.upsertMany}. */
+type UpsertOptions<TDoc = Record<string, unknown>> = Core.UpsertOptions<FieldKey<TDoc>, Insert<TDoc>>;
+/** Aggregate query specification (`count`/`sum`/`avg`/`min`/`max` + `groupBy`). */
+type AggregateSpec<TDoc = Record<string, unknown>> = Core.AggregateSpec<FieldKey<TDoc>, Filter<TDoc>>;
+/** One aggregated result row (group fields + aggregate values). */
+type AggregateRow = Record<string, unknown>;
+
+interface OffsetParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc> {
+    page?: number;
+    perPage?: number;
+    /** `false` — no count query: `perPage + 1` rows are read, `total_items` / `total_pages` are `null` (task 013). Default `true`. */
+    withTotal?: boolean;
+}
+type OffsetMeta = Core.OffsetMeta;
+interface OffsetResult<T> {
+    data: T[];
+    meta: OffsetMeta;
+}
+interface InfiniteParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc> {
+    limit?: number;
+    offset?: number;
+}
+type InfiniteMeta = Core.InfiniteMeta;
+interface InfiniteResult<T> {
+    data: T[];
+    meta: InfiniteMeta;
+}
+interface CursorParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc> {
+    limit?: number;
+    cursor?: string | null;
+    /** Field the cursor walks over. Defaults to `"id"` (→ `_id`). */
+    cursorKey?: LooseFieldKey<TDoc>;
+    order?: SortDirection;
+    direction?: "forward" | "backward";
+}
+type CursorMeta = Core.CursorMeta;
+interface CursorResult<T> {
+    data: T[];
+    meta: CursorMeta;
+}
+
+/**
+ * Per-repository options — the same names as the other adapters (REQUIREMENTS R11), plus the
+ * zod `schema` the driver does not have: field types for casting, unknown keys, the default
+ * `filterable` (equality on the schema's fields, R12).
+ */
+interface RepositoryOptions<TDoc = Document> {
+    /** The document's zod object schema — the one source of field types (task 017 Locked 2). */
+    schema: z.ZodObject;
+    /** Fields stored as `ObjectId` (cast from 24-hex strings). Default `["_id"]`. */
+    objectId?: readonly (FieldKey<TDoc> | "_id")[];
+    /** Applied to every read and write (RBAC / tenancy); a value may be `{ in: [...] }`. */
+    scope?: Scope<TDoc>;
+    /** The response always has exactly these fields; the client's `columns` is ignored. */
+    forcedColumns?: ColumnSelection<TDoc>;
+    /** The client's `columns` is intersected with this list. */
+    allowedColumns?: readonly FieldKey<TDoc>[];
+    /** Field → allowed operators (`"*"` all). Absent: equality (`=`, `in`) on the schema's fields. */
+    filterable?: Core.Filterable<FieldKey<TDoc> | "_id">;
+    /** Sortable fields. Absent: `_id` and the createdAt field. */
+    sortable?: readonly (FieldKey<TDoc> | "_id")[];
+    limits?: Partial<Core.QueryLimits>;
+    /** Server time limit per read, in ms (default: the registry's, 2000). */
+    maxTimeMS?: number;
+}
+type TrueKeys<T> = {
+    [K in keyof T]: T[K] extends true ? K : never;
+}[keyof T];
+/** `columns` narrows the row via `Pick`. */
+type Result<TDoc, TColumns> = TColumns extends ColumnSelection<TDoc> ? ([TrueKeys<TColumns>] extends [never] ? TDoc : Pick<TDoc, TrueKeys<TColumns> & keyof TDoc>) : TDoc;
+type Params<TBase, TColumns> = Omit<TBase, "columns"> & {
+    columns?: TColumns;
+};
+interface Repository<TDoc extends Document = Document> {
+    readonly collection: Collection<TDoc>;
+    findAll<const TColumns extends ColumnSelection<TDoc> | undefined = undefined>(params?: Params<QueryParams<TDoc>, TColumns>): Promise<Result<TDoc, TColumns>[]>;
+    findOne<const TColumns extends ColumnSelection<TDoc> | undefined = undefined>(params?: Params<QueryParams<TDoc>, TColumns>): Promise<Result<TDoc, TColumns> | undefined>;
+    findById<const TColumns extends ColumnSelection<TDoc> | undefined = undefined>(id: Id, params?: Params<ByIdParams<TDoc>, TColumns>): Promise<Result<TDoc, TColumns> | undefined>;
+    findList<const TColumns extends ColumnSelection<TDoc> | undefined = undefined>(params?: Params<OffsetParams<TDoc>, TColumns>): Promise<OffsetResult<Result<TDoc, TColumns>>>;
+    findInfinite<const TColumns extends ColumnSelection<TDoc> | undefined = undefined>(params?: Params<InfiniteParams<TDoc>, TColumns>): Promise<InfiniteResult<Result<TDoc, TColumns>>>;
+    findCursor<const TColumns extends ColumnSelection<TDoc> | undefined = undefined>(params?: Params<CursorParams<TDoc>, TColumns>): Promise<CursorResult<Result<TDoc, TColumns>>>;
+    count(filter?: Filter<TDoc>): Promise<number>;
+    exists(filter?: Filter<TDoc>): Promise<boolean>;
+    create(values: Insert<TDoc>): Promise<Row<TDoc>>;
+    createMany(values: Insert<TDoc>[]): Promise<Row<TDoc>[]>;
+    upsert(values: Insert<TDoc>, options: UpsertOptions<TDoc>): Promise<Row<TDoc>>;
+    upsertMany(values: Insert<TDoc>[], options: UpsertOptions<TDoc>): Promise<Row<TDoc>[]>;
+    updateById(id: Id, patch: Partial<Insert<TDoc>>, idKey?: FieldKey<TDoc>): Promise<Row<TDoc> | undefined>;
+    /** One `updateMany`; an empty filter is refused (`empty-filter`) unless it is `{ all: true }`. */
+    updateWhere(filter: Filter<TDoc> | AllRows, patch: Partial<Insert<TDoc>>, options?: {
+        returning?: false;
+    }): Promise<MutationCount>;
+    updateWhere(filter: Filter<TDoc> | AllRows, patch: Partial<Insert<TDoc>>, options: {
+        returning: {
+            limit: number;
+        };
+    }): Promise<MutationRows<Row<TDoc>>>;
+    deleteById(id: Id, idKey?: FieldKey<TDoc>): Promise<Row<TDoc> | undefined>;
+    deleteWhere(filter: Filter<TDoc> | AllRows, options?: {
+        returning?: false;
+    }): Promise<MutationCount>;
+    deleteWhere(filter: Filter<TDoc> | AllRows, options: {
+        returning: {
+            limit: number;
+        };
+    }): Promise<MutationRows<Row<TDoc>>>;
+    softDelete(id: Id, idKey?: FieldKey<TDoc>): Promise<Row<TDoc> | undefined>;
+    restore(id: Id, idKey?: FieldKey<TDoc>): Promise<Row<TDoc> | undefined>;
+    aggregate(spec: AggregateSpec<TDoc>): Promise<AggregateRow[]>;
+    scoped(scope: Scope<TDoc>): Repository<TDoc>;
+}
+
+export type { AggregateRow as A, ByIdParams as B, ColumnSelection as C, FieldKey as F, Id as I, LooseFieldKey as L, NotGroup as N, OffsetMeta as O, QueryParams as Q, RepositoryOptions as R, Scope as S, UpsertOptions as U, WithRelations as W, Repository as a, RawFilter as b, AggregateSpec as c, AndGroup as d, CursorMeta as e, CursorParams as f, CursorResult as g, FieldCondition as h, Filter as i, FilterNode as j, FilterOperator as k, FilterScalar as l, FilterValue as m, InfiniteMeta as n, InfiniteParams as o, InfiniteResult as p, Insert as q, OffsetParams as r, OffsetResult as s, OrGroup as t, Result as u, Row as v, Sort as w, SortDirection as x, SortItem as y };

package/dist/testing.cjs

@@ -0,0 +1,2 @@
+'use strict';var e=Symbol.for("querykit.mongodb.explain");function m(r,n={}){let o=r[e];if(!o)throw new TypeError("explainFind: not a @querykitjs/mongodb repository");return o(n)}exports.explainFind=m;//# sourceMappingURL=testing.cjs.map
+//# sourceMappingURL=testing.cjs.map

package/dist/testing.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/explain-key.ts","../src/testing.ts"],"names":["EXPLAIN","explainFind","repository","params","explain"],"mappings":"aAKO,IAAMA,CAAAA,CAAU,MAAA,CAAO,GAAA,CAAI,0BAA0B,CAAA,CCiBrD,SAASC,CAAAA,CAAmCC,CAAAA,CAA8BC,CAAAA,CAA4B,EAAC,CAAsB,CAClI,IAAMC,CAAAA,CAAWF,CAAAA,CAAsCF,CAAO,CAAA,CAC9D,GAAI,CAACI,CAAAA,CAAS,MAAM,IAAI,SAAA,CAAU,mDAAmD,CAAA,CACrF,OAAOA,CAAAA,CAAQD,CAAqB,CACtC","file":"testing.cjs","sourcesContent":["/**\n * The key of a repository's hidden `explain` method — shared by the repository (main entry)\n * and `@querykitjs/mongodb/testing`, which imports only this key, not the repository code.\n * `Symbol.for`, so the two entries' bundles agree on it.\n */\nexport const EXPLAIN = Symbol.for(\"querykit.mongodb.explain\");\n","/**\n * `@querykitjs/mongodb/testing` — test helpers, kept out of the main entry (REQUIREMENTS R14).\n *\n * @example\n * ```ts\n * import { explainFind } from \"@querykitjs/mongodb/testing\";\n *\n * const plan = await explainFind(users, { filter: [{ key: \"email\", operation: \"%_\", value: \"ali\" }] });\n * expect(JSON.stringify(plan)).toContain(\"IXSCAN\"); // the prefix search uses the index\n * ```\n */\nimport type { Document } from \"mongodb\";\n\nimport { EXPLAIN } from \"./internal/explain-key\";\nimport type { QueryParams, Repository } from \"./types\";\n\ntype Explainable = { [EXPLAIN]?: (params: QueryParams) => Promise<Document> };\n\n/**\n * The MongoDB query plan (`explain(\"queryPlanner\")`) of `repository.findAll(params)` — the same\n * policy checks and compiled filter, so a test can assert that a request uses an index.\n */\nexport function explainFind<TDoc extends Document>(repository: Repository<TDoc>, params: QueryParams<TDoc> = {}): Promise<Document> {\n  const explain = (repository as unknown as Explainable)[EXPLAIN];\n  if (!explain) throw new TypeError(\"explainFind: not a @querykitjs/mongodb repository\");\n  return explain(params as QueryParams);\n}\n"]}

package/dist/testing.d.cts

@@ -0,0 +1,24 @@
+import { Document } from 'mongodb';
+import { Repository, QueryParams } from './index.cjs';
+import 'zod';
+import '@querykitjs/core';
+
+/**
+ * `@querykitjs/mongodb/testing` — test helpers, kept out of the main entry (REQUIREMENTS R14).
+ *
+ * @example
+ * ```ts
+ * import { explainFind } from "@querykitjs/mongodb/testing";
+ *
+ * const plan = await explainFind(users, { filter: [{ key: "email", operation: "%_", value: "ali" }] });
+ * expect(JSON.stringify(plan)).toContain("IXSCAN"); // the prefix search uses the index
+ * ```
+ */
+
+/**
+ * The MongoDB query plan (`explain("queryPlanner")`) of `repository.findAll(params)` — the same
+ * policy checks and compiled filter, so a test can assert that a request uses an index.
+ */
+declare function explainFind<TDoc extends Document>(repository: Repository<TDoc>, params?: QueryParams<TDoc>): Promise<Document>;
+
+export { explainFind };

package/dist/testing.d.ts

@@ -0,0 +1,24 @@
+import { Document } from 'mongodb';
+import { Repository, QueryParams } from './index.js';
+import 'zod';
+import '@querykitjs/core';
+
+/**
+ * `@querykitjs/mongodb/testing` — test helpers, kept out of the main entry (REQUIREMENTS R14).
+ *
+ * @example
+ * ```ts
+ * import { explainFind } from "@querykitjs/mongodb/testing";
+ *
+ * const plan = await explainFind(users, { filter: [{ key: "email", operation: "%_", value: "ali" }] });
+ * expect(JSON.stringify(plan)).toContain("IXSCAN"); // the prefix search uses the index
+ * ```
+ */
+
+/**
+ * The MongoDB query plan (`explain("queryPlanner")`) of `repository.findAll(params)` — the same
+ * policy checks and compiled filter, so a test can assert that a request uses an index.
+ */
+declare function explainFind<TDoc extends Document>(repository: Repository<TDoc>, params?: QueryParams<TDoc>): Promise<Document>;
+
+export { explainFind };

package/dist/testing.js

@@ -0,0 +1,2 @@
+var e=Symbol.for("querykit.mongodb.explain");function m(r,n={}){let o=r[e];if(!o)throw new TypeError("explainFind: not a @querykitjs/mongodb repository");return o(n)}export{m as explainFind};//# sourceMappingURL=testing.js.map
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/explain-key.ts","../src/testing.ts"],"names":["EXPLAIN","explainFind","repository","params","explain"],"mappings":"AAKO,IAAMA,CAAAA,CAAU,MAAA,CAAO,GAAA,CAAI,0BAA0B,CAAA,CCiBrD,SAASC,CAAAA,CAAmCC,CAAAA,CAA8BC,CAAAA,CAA4B,EAAC,CAAsB,CAClI,IAAMC,CAAAA,CAAWF,CAAAA,CAAsCF,CAAO,CAAA,CAC9D,GAAI,CAACI,CAAAA,CAAS,MAAM,IAAI,SAAA,CAAU,mDAAmD,CAAA,CACrF,OAAOA,CAAAA,CAAQD,CAAqB,CACtC","file":"testing.js","sourcesContent":["/**\n * The key of a repository's hidden `explain` method — shared by the repository (main entry)\n * and `@querykitjs/mongodb/testing`, which imports only this key, not the repository code.\n * `Symbol.for`, so the two entries' bundles agree on it.\n */\nexport const EXPLAIN = Symbol.for(\"querykit.mongodb.explain\");\n","/**\n * `@querykitjs/mongodb/testing` — test helpers, kept out of the main entry (REQUIREMENTS R14).\n *\n * @example\n * ```ts\n * import { explainFind } from \"@querykitjs/mongodb/testing\";\n *\n * const plan = await explainFind(users, { filter: [{ key: \"email\", operation: \"%_\", value: \"ali\" }] });\n * expect(JSON.stringify(plan)).toContain(\"IXSCAN\"); // the prefix search uses the index\n * ```\n */\nimport type { Document } from \"mongodb\";\n\nimport { EXPLAIN } from \"./internal/explain-key\";\nimport type { QueryParams, Repository } from \"./types\";\n\ntype Explainable = { [EXPLAIN]?: (params: QueryParams) => Promise<Document> };\n\n/**\n * The MongoDB query plan (`explain(\"queryPlanner\")`) of `repository.findAll(params)` — the same\n * policy checks and compiled filter, so a test can assert that a request uses an index.\n */\nexport function explainFind<TDoc extends Document>(repository: Repository<TDoc>, params: QueryParams<TDoc> = {}): Promise<Document> {\n  const explain = (repository as unknown as Explainable)[EXPLAIN];\n  if (!explain) throw new TypeError(\"explainFind: not a @querykitjs/mongodb repository\");\n  return explain(params as QueryParams);\n}\n"]}

package/package.json

@@ -1,6 +1,98 @@
 {
   "name": "@querykitjs/mongodb",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Advanced filtering + flexible pagination repository layer for the official MongoDB driver.",
+  "type": "module",
+  "author": {
+    "name": "Suhrobbek Soatov",
+    "url": "https://soatov.uz",
+    "email": "svkhrobbeck@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/svkhrobbeck/querykit.git",
+    "directory": "packages/mongodb"
+  },
+  "homepage": "https://github.com/svkhrobbeck/querykit/tree/main/packages/mongodb#readme",
+  "bugs": {
+    "url": "https://github.com/svkhrobbeck/querykit/issues"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./testing": {
+      "import": {
+        "types": "./dist/testing.d.ts",
+        "default": "./dist/testing.js"
+      },
+      "require": {
+        "types": "./dist/testing.d.cts",
+        "default": "./dist/testing.cjs"
+      }
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "testing": [
+        "./dist/testing.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "README.en.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test:smoke": "bun --preload ./test/bun-v8-shim.ts test/smoke.ts",
+    "test:unit": "bun --preload ./test/bun-v8-shim.ts test/where.ts && bun --preload ./test/bun-v8-shim.ts test/policy.ts",
+    "test:types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@querykitjs/core": "^2.0.0"
+  },
+  "peerDependencies": {
+    "mongodb": "^6.21 || ^7.7",
+    "zod": "^4"
+  },
+  "devDependencies": {
+    "mongodb": "7.7.0",
+    "mongodb-memory-server": "11.3.0",
+    "zod": "4.6.7"
+  },
+  "keywords": [
+    "mongodb",
+    "repository",
+    "pagination",
+    "cursor",
+    "keyset",
+    "filter",
+    "query",
+    "zod",
+    "typescript"
+  ]
+}

package/skills/querykit-mongodb/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: querykit-mongodb
+description: Use when code builds or calls a querykit repository over the official MongoDB driver (@querykitjs/mongodb) - createRegistry(client), registry.repository(collection, { schema }), filterable / sortable / limits policy, findList / findInfinite / findCursor, updateWhere / deleteWhere, scope, transactions, or explainFind from @querykitjs/mongodb/testing.
+---
+
+## Safety rules
+
+- DO pass the document's zod object as `schema` and list ObjectId fields in `objectId` (default `["_id"]`); field types, unknown keys and casting come only from that schema.
+- DO list what a client may filter on in `filterable` (field → operators, `"*"` only on purpose). Without it a client gets equality (`=`, `in`) on the projection fields only; anything else is `QueryKitError` `forbidden-key` / `forbidden-operator` before the driver runs.
+- DO list sortable fields in `sortable`; the default is `_id` and the createdAt field.
+- DON'T pass a plain Mongo object as a filter node from request data. Server code brands one with `raw()` from `@querykitjs/core`; an unbranded node is `forbidden-key`, and `raw()` is not checked by `filterable`.
+- DON'T expect a client value to act as an operator: an object value (`{ "$where": … }`, `{ "$gt": "" }`) is `invalid-value` and never reaches MongoDB.
+- DON'T send `with`: relations are not built in this version (no `$lookup`); every `with` key is `forbidden-key`, `site: "with"`.
+- DO keep `maxTimeMS` (default `2000`, per registry or repository) and map `QueryKitTimeoutError` to 503/504.
+- DO keep the request limits (core `DEFAULT_QUERY_LIMITS`; LIKE patterns with more than `2` wildcards are `limit-exceeded`); raise one with `limits`, never turn it off.
+- DON'T call `updateWhere` / `deleteWhere` with an empty filter to mean "all rows" — it is `empty-filter`; pass `{ all: true }` on purpose.
+- DO set `cursorSecret` on the registry when cursor tokens leave the server; an unsigned token is then refused.
+- DO validate a write body with your zod schema first: writes store values as given.
+
+## When to use
+
+- A backend on the plain `mongodb` driver (no Mongoose) that serves querykit list requests from `@querykitjs/web`.
+- Tenant / RBAC scoping (`scope`, `repo.scoped(...)`), soft delete, bulk writes, aggregation over one collection.
+- Asserting in tests that a request uses an index (`explainFind`).
+
+With Mongoose models use `@querykitjs/mongoose`; the request contract is the same.
+
+## Setup
+
+```ts
+import type { MongoClient, ObjectId } from "mongodb";
+import { z } from "zod";
+import { createRegistry } from "@querykitjs/mongodb";
+
+declare const client: MongoClient;
+
+const UserSchema = z.object({ _id: z.string(), name: z.string(), status: z.enum(["active", "blocked"]), createdAt: z.date() });
+type User = { _id: ObjectId; name: string; status: "active" | "blocked"; createdAt: Date };
+
+const qk = createRegistry(client, { maxPerPage: 100 });
+export const users = qk.repository(client.db("app").collection<User>("users"), {
+  schema: UserSchema,
+  forcedColumns: { _id: true, name: true, status: true, createdAt: true },
+  filterable: { status: ["=", "in"], name: ["startsWith"] },
+  sortable: ["_id", "createdAt", "name"],
+});
+```
+
+## Common tasks
+
+### Serve a list request
+
+```ts
+import type { WireOffsetParams } from "@querykitjs/core";
+import type { Repository } from "@querykitjs/mongodb";
+
+declare const users: Repository<{ _id: unknown; name: string; status: string; createdAt: Date }>;
+
+export async function list(body: WireOffsetParams) {
+  return users.findList({ ...body, withTotal: false }); // meta.total_items is null, no count query
+}
+```
+
+### Scope every call to one tenant
+
+```ts
+import type { Repository } from "@querykitjs/mongodb";
+
+declare const orders: Repository<{ _id: unknown; shop_id: unknown; total: number }>;
+
+const shopOrders = orders.scoped({ shop_id: { in: ["65a1b2c3d4e5f60718293a4b"] } });
+await shopOrders.updateWhere([{ key: "total", operation: ">", value: 0 }], { total: 0 });
+```
+
+### Check an index in a test
+
+```ts
+import { explainFind } from "@querykitjs/mongodb/testing";
+import type { Repository } from "@querykitjs/mongodb";
+
+declare const users: Repository<{ _id: unknown; name: string }>;
+
+const plan = await explainFind(users, { filter: [{ key: "name", operation: "startsWith", value: "ali" }] });
+console.log(JSON.stringify(plan).includes("IXSCAN"));
+```
+
+## Request contract
+
+The same JSON shape as every querykit package (`@querykitjs/core`): conditions `{ key, operation?, value? }`, groups `{ and }` / `{ or }` / `{ not }` (a flat array = AND), `sort` always `[{ key, direction? }]`, offset `page` / `perPage` / `withTotal`, infinite `limit` / `offset`, cursor `limit` / `cursor` / `cursorKey` / `order` / `direction` (no `sort`), snake_case meta (`total_items`, `has_next`, `next_cursor`, …). `id` means `_id`. Refusals are `QueryKitError` with `{ source, site, key, operation?, reason }`.
+
+## Mistakes to avoid
+
+- Forgetting `objectId` for a reference field such as `shop_id` — a 24-hex string then never matches the stored `ObjectId`.
+- Expecting a numeric `id` to match: MongoDB ids are ObjectIds, so `{ key: "id", value: 2 }` is `invalid-value`.
+- Opening `contains` / `endsWith` on a large collection — they cannot use an index.
+- Running `registry.transaction` on a standalone `mongod` — transactions need a replica set.
+- Importing `explainFind` from `@querykitjs/mongodb` — it lives only in `@querykitjs/mongodb/testing`.