anchordb 0.2.0

package/dist/esm/query/aggregation/source.js

@@ -0,0 +1,77 @@
+import { extractConstraints, isFullyExtractable, matchesFilter } from "../filter.js";
+import { compareValues, getPath } from "../path.js";
+import { hydrateDoc } from "../../model/model.js";
+/**
+ * Connects the pipeline to real storage.
+ *
+ * The pushdown contract is the same one the query builder uses, and for the same reason:
+ * `extractConstraints` silently drops what it cannot express, so the JS matcher always runs, and
+ * skip/limit only reach the storage engine when the filter is provably lossless. Pushing pagination
+ * over a not-yet-filtered row set would page the wrong rows.
+ */
+export class StorageAggregationSource {
+    constructor(opts) {
+        this.lastScan = {
+            stage: "COLLSCAN",
+            indexUsed: null,
+        };
+        this.adapter = opts.adapter;
+        this.collection = opts.collection;
+        this.schema = opts.schema;
+        this.resolveCollection = opts.resolveCollection;
+    }
+    async *stream(pushdown) {
+        const filter = pushdown.filter ?? {};
+        const lossless = isFullyExtractable(filter);
+        const canPage = lossless;
+        const result = await this.adapter.find({
+            collection: this.collection,
+            constraints: extractConstraints(filter),
+            ...(pushdown.sort ? { sort: pushdown.sort } : {}),
+            ...(canPage && pushdown.skip !== undefined ? { skip: pushdown.skip } : {}),
+            ...(canPage && pushdown.limit !== undefined ? { limit: pushdown.limit } : {}),
+        });
+        this.lastScan = {
+            stage: result.indexUsed ? "IXSCAN" : "COLLSCAN",
+            indexUsed: result.indexUsed ?? null,
+        };
+        let docs = result.rows.map((row) => hydrateDoc(row, this.schema));
+        docs = docs.filter((d) => matchesFilter(d, filter));
+        if (pushdown.sort && !result.applied.sort) {
+            docs.sort((a, b) => {
+                for (const [path, dir] of pushdown.sort) {
+                    const c = compareValues(getPath(a, path), getPath(b, path));
+                    if (c !== 0)
+                        return dir === 1 ? c : -c;
+                }
+                return 0;
+            });
+        }
+        if (pushdown.skip !== undefined && !(canPage && result.applied.skip))
+            docs = docs.slice(pushdown.skip);
+        if (pushdown.limit !== undefined && !(canPage && result.applied.limit)) {
+            docs = docs.slice(0, pushdown.limit);
+        }
+        for (const doc of docs)
+            yield doc;
+    }
+    /** One query per foreign collection, never one per document. */
+    async lookup(collection, localValues, foreignField) {
+        const target = this.resolveCollection(collection);
+        const name = target?.collection ?? collection;
+        const schema = target?.schema ?? this.schema;
+        if (localValues.length === 0)
+            return [];
+        const values = localValues.map((v) => (v === null || v === undefined ? v : String(v)));
+        const result = await this.adapter.find({
+            collection: name,
+            constraints: [{ path: foreignField, op: "in", value: values }],
+        });
+        const filter = { [foreignField]: { $in: localValues } };
+        return result.rows.map((row) => hydrateDoc(row, schema)).filter((d) => matchesFilter(d, filter));
+    }
+    explainLast() {
+        return this.lastScan;
+    }
+}
+//# sourceMappingURL=source.js.map

package/dist/esm/query/aggregation/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../../../src/query/aggregation/source.ts"],"names":[],"mappings":"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"}

package/dist/esm/query/builder/query.d.ts

@@ -0,0 +1,113 @@
+import type { Filter } from "../filter.js";
+import type { SortSpec } from "../../storage/types.js";
+/**
+ * The lazy, chainable query — Mongoose's `Query`.
+ *
+ * Nothing runs until `exec()`, `await`, or iteration. That laziness is not sugar: it is what lets
+ * the whole chain compile into ONE storage plan, so `.skip(20).limit(10)` fetches ten rows instead
+ * of fetching the collection and slicing it in JS, and `populate` batches only the page that was
+ * actually selected.
+ */
+export interface PopulateSpec {
+    path: string;
+    select?: string | Record<string, 0 | 1>;
+    match?: Filter;
+    model?: string;
+    options?: {
+        sort?: SortSpec | string | Record<string, 1 | -1>;
+        limit?: number;
+        skip?: number;
+    };
+    populate?: PopulateSpec[];
+}
+export interface QueryState {
+    op: "find" | "findOne" | "count" | "distinct" | "deleteOne" | "deleteMany" | "updateOne" | "updateMany";
+    filter: Filter;
+    projection?: Record<string, 0 | 1>;
+    sort?: SortSpec;
+    skip?: number;
+    limit?: number;
+    populate: PopulateSpec[];
+    lean: boolean;
+    hint?: string;
+    explain: boolean;
+    distinctField?: string;
+    update?: Record<string, unknown>;
+    options: Record<string, unknown>;
+}
+export interface QueryExecutor<T> {
+    run(state: QueryState): Promise<unknown>;
+}
+export type SortArg = string | Record<string, 1 | -1 | "asc" | "desc"> | SortSpec;
+/** `Query` is thenable, so `await Model.find()` works exactly as in Mongoose. */
+export declare class Query<TResult, TDoc = TResult> implements PromiseLike<TResult> {
+    private state;
+    private readonly executor;
+    private currentPath;
+    constructor(executor: QueryExecutor<TDoc>, state: Partial<QueryState> & Pick<QueryState, "op">);
+    where(path: string): this;
+    where(filter: Filter): this;
+    /** Applies to the path most recently named by `.where()`. */
+    private condition;
+    equals(value: unknown): this;
+    gt(value: unknown): this;
+    gte(value: unknown): this;
+    lt(value: unknown): this;
+    lte(value: unknown): this;
+    ne(value: unknown): this;
+    in(values: unknown[]): this;
+    nin(values: unknown[]): this;
+    regex(value: RegExp | string): this;
+    exists(value?: boolean): this;
+    sort(arg: SortArg): this;
+    skip(n: number): this;
+    limit(n: number): this;
+    select(arg: string | Record<string, 0 | 1>): this;
+    populate(arg: string | PopulateSpec | Array<string | PopulateSpec>): this;
+    lean(value?: boolean): this;
+    hint(indexName: string): this;
+    setOptions(options: Record<string, unknown>): this;
+    getFilter(): Filter;
+    getOptions(): Record<string, unknown>;
+    exec(): Promise<TResult>;
+    /** Makes `await query` work without `.exec()`, exactly like Mongoose. */
+    then<TResult1 = TResult, TResult2 = never>(onfulfilled?: ((value: TResult) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    catch<TCatch = never>(onrejected?: ((reason: unknown) => TCatch | PromiseLike<TCatch>) | null): Promise<TResult | TCatch>;
+    finally(onfinally?: (() => void) | null): Promise<TResult>;
+    /** Row count without materialising documents. */
+    count(): Promise<number>;
+    countDocuments(): Promise<number>;
+    distinct(field: string): Promise<unknown[]>;
+    /** Reports which index was chosen and what was pushed down, in Mongo's vocabulary. */
+    explain(): Promise<ExplainResult>;
+    /** Throw instead of resolving null — Mongoose's `orFail()`. */
+    orFail(makeError?: () => Error): Promise<NonNullable<TResult>>;
+    /**
+     * Streams results in batches so a large collection never lands in memory at once.
+     * `for await (const doc of Model.find())`.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<TDoc>;
+    /** Mongoose's `.cursor()`. */
+    cursor(): AsyncIterable<TDoc>;
+}
+export interface ExplainResult {
+    op: string;
+    filter: Filter;
+    /** "IXSCAN" when an index was used, "COLLSCAN" otherwise — Mongo's vocabulary. */
+    stage: "IXSCAN" | "COLLSCAN";
+    indexUsed: string | null;
+    /** Which parts of the plan the storage engine handled, vs. re-done in JS. */
+    pushedDown: {
+        constraints: boolean;
+        sort: boolean;
+        skip: boolean;
+        limit: boolean;
+    };
+    documentsExamined: number;
+    documentsReturned: number;
+    sort?: SortSpec;
+    populatedPaths: string[];
+}
+export declare function normaliseSort(arg: SortArg): SortSpec;
+export declare function normaliseProjection(arg: string | Record<string, 0 | 1>): Record<string, 0 | 1>;
+//# sourceMappingURL=query.d.ts.map

package/dist/esm/query/builder/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../../src/query/builder/query.ts"],"names":[],"mappings":"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"}

package/dist/esm/query/builder/query.js

@@ -0,0 +1,209 @@
+/** `Query` is thenable, so `await Model.find()` works exactly as in Mongoose. */
+export class Query {
+    constructor(executor, state) {
+        this.currentPath = null;
+        this.executor = executor;
+        this.state = {
+            filter: {},
+            populate: [],
+            lean: false,
+            explain: false,
+            options: {},
+            ...state,
+        };
+    }
+    where(arg) {
+        if (typeof arg === "string") {
+            this.currentPath = arg;
+        }
+        else {
+            Object.assign(this.state.filter, arg);
+        }
+        return this;
+    }
+    /** Applies to the path most recently named by `.where()`. */
+    condition(op, value) {
+        if (!this.currentPath) {
+            throw new Error(`Call .where("path") before .${op.replace("$", "")}().`);
+        }
+        const existing = this.state.filter[this.currentPath];
+        const merged = existing !== null && typeof existing === "object" && !Array.isArray(existing) && !(existing instanceof Date)
+            ? { ...existing }
+            : {};
+        merged[op] = value;
+        this.state.filter[this.currentPath] = merged;
+        return this;
+    }
+    equals(value) {
+        if (!this.currentPath)
+            throw new Error('Call .where("path") before .equals().');
+        this.state.filter[this.currentPath] = value;
+        return this;
+    }
+    gt(value) {
+        return this.condition("$gt", value);
+    }
+    gte(value) {
+        return this.condition("$gte", value);
+    }
+    lt(value) {
+        return this.condition("$lt", value);
+    }
+    lte(value) {
+        return this.condition("$lte", value);
+    }
+    ne(value) {
+        return this.condition("$ne", value);
+    }
+    in(values) {
+        return this.condition("$in", values);
+    }
+    nin(values) {
+        return this.condition("$nin", values);
+    }
+    regex(value) {
+        return this.condition("$regex", value);
+    }
+    exists(value = true) {
+        return this.condition("$exists", value);
+    }
+    sort(arg) {
+        this.state.sort = normaliseSort(arg);
+        return this;
+    }
+    skip(n) {
+        this.state.skip = n;
+        return this;
+    }
+    limit(n) {
+        this.state.limit = n;
+        return this;
+    }
+    select(arg) {
+        this.state.projection = normaliseProjection(arg);
+        return this;
+    }
+    populate(arg) {
+        const list = Array.isArray(arg) ? arg : [arg];
+        for (const entry of list) {
+            this.state.populate.push(typeof entry === "string" ? { path: entry } : entry);
+        }
+        return this;
+    }
+    lean(value = true) {
+        this.state.lean = value;
+        return this;
+    }
+    hint(indexName) {
+        this.state.hint = indexName;
+        return this;
+    }
+    setOptions(options) {
+        Object.assign(this.state.options, options);
+        return this;
+    }
+    getFilter() {
+        return this.state.filter;
+    }
+    getOptions() {
+        return this.state.options;
+    }
+    // ---- terminal operations -------------------------------------------------
+    async exec() {
+        return (await this.executor.run({ ...this.state }));
+    }
+    /** Makes `await query` work without `.exec()`, exactly like Mongoose. */
+    then(onfulfilled, onrejected) {
+        return this.exec().then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.exec().catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.exec().finally(onfinally);
+    }
+    /** Row count without materialising documents. */
+    async count() {
+        return (await this.executor.run({ ...this.state, op: "count" }));
+    }
+    async countDocuments() {
+        return this.count();
+    }
+    async distinct(field) {
+        return (await this.executor.run({ ...this.state, op: "distinct", distinctField: field }));
+    }
+    /** Reports which index was chosen and what was pushed down, in Mongo's vocabulary. */
+    async explain() {
+        return (await this.executor.run({ ...this.state, explain: true }));
+    }
+    /** Throw instead of resolving null — Mongoose's `orFail()`. */
+    async orFail(makeError) {
+        const result = await this.exec();
+        if (result === null || result === undefined || (Array.isArray(result) && result.length === 0)) {
+            throw makeError ? makeError() : new Error("No document found for query");
+        }
+        return result;
+    }
+    /**
+     * Streams results in batches so a large collection never lands in memory at once.
+     * `for await (const doc of Model.find())`.
+     */
+    async *[Symbol.asyncIterator]() {
+        const batchSize = this.state.options.batchSize ?? 200;
+        let skip = this.state.skip ?? 0;
+        const hardLimit = this.state.limit;
+        let yielded = 0;
+        for (;;) {
+            const remaining = hardLimit === undefined ? batchSize : Math.min(batchSize, hardLimit - yielded);
+            if (remaining <= 0)
+                return;
+            const batch = (await this.executor.run({
+                ...this.state,
+                op: "find",
+                skip,
+                limit: remaining,
+            }));
+            if (batch.length === 0)
+                return;
+            for (const doc of batch) {
+                yield doc;
+                yielded++;
+            }
+            if (batch.length < remaining)
+                return;
+            skip += batch.length;
+        }
+    }
+    /** Mongoose's `.cursor()`. */
+    cursor() {
+        return this;
+    }
+}
+export function normaliseSort(arg) {
+    if (typeof arg === "string") {
+        // "-createdAt name" — Mongoose's string form
+        return arg
+            .split(/\s+/)
+            .filter(Boolean)
+            .map((token) => token.startsWith("-") ? [token.slice(1), -1] : [token, 1]);
+    }
+    if (Array.isArray(arg))
+        return arg;
+    return Object.entries(arg).map(([path, dir]) => [
+        path,
+        dir === 1 || dir === "asc" ? 1 : -1,
+    ]);
+}
+export function normaliseProjection(arg) {
+    if (typeof arg !== "string")
+        return arg;
+    const out = {};
+    for (const token of arg.split(/\s+/).filter(Boolean)) {
+        if (token.startsWith("-"))
+            out[token.slice(1)] = 0;
+        else
+            out[token] = 1;
+    }
+    return out;
+}
+//# sourceMappingURL=query.js.map

package/dist/esm/query/builder/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../../../src/query/builder/query.ts"],"names":[],"mappings":"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"}

package/dist/esm/query/filter.d.ts

@@ -0,0 +1,50 @@
+import type { PlanConstraint } from "../storage/types.js";
+/**
+ * MongoDB filter evaluation.
+ *
+ * Operators live in a registry rather than a hard-coded switch, so a new one can be added without
+ * touching the matcher — the extensibility the brief asks for, and what lets Lens reuse the exact
+ * same query language instead of inventing its own.
+ */
+export type Filter = Record<string, unknown>;
+export interface OperatorContext {
+    /** Value at the path, already extracted. */
+    value: unknown;
+    /** The operand written in the filter. */
+    operand: unknown;
+    /** Whole document, for operators that need siblings. */
+    doc: unknown;
+    path: string;
+    /** True when the path is genuinely present, distinguishing missing from null. */
+    present: boolean;
+}
+export type OperatorFn = (ctx: OperatorContext) => boolean;
+/** Extension point: `registerQueryOperator("$near", fn)`. */
+export declare function registerQueryOperator(name: string, fn: OperatorFn): void;
+export declare function listQueryOperators(): string[];
+/** Does a document satisfy a filter? */
+export declare function matchesFilter(doc: Record<string, unknown>, filter: Filter): boolean;
+/**
+ * Extract the constraints a storage adapter might push into an index.
+ *
+ * Only the unambiguous, non-array-sensitive leaves are extracted. Anything inside `$or`/`$nor`, or
+ * needing array semantics, is left out — the adapter reports it did not apply them and the JS
+ * matcher runs anyway, so a missed pushdown costs speed, never correctness.
+ */
+export declare function extractConstraints(filter: Filter): PlanConstraint[];
+/** Paths a filter constrains — used for index selection. */
+export declare function filterPaths(filter: Filter): string[];
+/**
+ * Can `extractConstraints` represent this filter *completely*?
+ *
+ * This matters for correctness, not speed. `extractConstraints` silently drops anything it cannot
+ * express (a `$regex`, an `$or`, an `$elemMatch`), so an adapter that reports "I applied all the
+ * constraints you gave me" has told the truth about the constraints — but not about the filter.
+ * Acting on that would skip the dropped conditions entirely and return rows that do not match.
+ *
+ * So: the JS matcher always runs, and this predicate decides only whether it is safe to let the
+ * storage engine apply `skip`/`limit`. Pushing pagination down while conditions remain unapplied
+ * would page over the wrong row set.
+ */
+export declare function isFullyExtractable(filter: Filter): boolean;
+//# sourceMappingURL=filter.d.ts.map

package/dist/esm/query/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../src/query/filter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;GAMG;AAEH,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE7C,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,KAAK,EAAE,OAAO,CAAC;IACf,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,wDAAwD;IACxD,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC;AAI3D,6DAA6D;AAC7D,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,GAAG,IAAI,CAExE;AAED,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAE7C;AAuJD,wCAAwC;AACxC,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CA0BnF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE,CAgDnE;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAEpD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CA0B1D"}