flowquery 1.0.86 → 1.0.87

package/dist/graph/source_provider.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Backend-neutral source provider contract (version 1).
+ *
+ * A source provider exposes the rows of a virtual node label or
+ * relationship type to FlowQuery and declares, through explicit
+ * capabilities, which logical operations it can execute natively
+ * (lookup by id, adjacency expansion, predicate filtering, paging).
+ * FlowQuery plans against these declared operations only; it never
+ * inspects what kind of backend sits behind a provider.
+ *
+ * Rows always describe the *virtual definition*: node rows carry an `id`
+ * plus properties, relationship rows carry `left_id`, `right_id` plus
+ * properties, exactly as a `CREATE VIRTUAL` definition would return them.
+ * Ids are scoped to their label (or relationship type); they do not need
+ * to be globally unique.
+ *
+ * Correctness rule: a provider may return a *superset* of the rows that
+ * satisfy a request — FlowQuery always re-applies every constraint
+ * locally — but it must never drop a row that satisfies the request.
+ */
+export declare const SOURCE_CONTRACT_VERSION = 1;
+export type SourceRow = Record<string, any>;
+/** Comparison operators that can appear in a {@link SourcePredicate}. */
+export type PredicateOperator = "eq" | "gt" | "gte" | "lt" | "lte" | "in";
+export declare const PREDICATE_OPERATORS: readonly PredicateOperator[];
+/**
+ * Structured, versioned predicate over the columns of the virtual
+ * definition.  Semantics (identical in the TypeScript and Python
+ * implementations):
+ *
+ * - `eq`: the property is present and equal to `value` (host-language
+ *   equality on primitives).  `value` is never `null`.
+ * - `gt`/`gte`/`lt`/`lte`: a row may only be excluded when its property
+ *   value is a non-null primitive of the same type as `value` (number or
+ *   string) that fails the comparison.  Rows whose value is missing,
+ *   `null`, or of another type must be returned.  String bounds are only
+ *   sent to sources declaring `stringOrdering: "binary"`.
+ * - `in`: the property is present and equal to one of `values`.  `values`
+ *   is de-duplicated, contains only primitives and never contains `null`;
+ *   it may be empty (no row matches).
+ * - `and`: every term holds.  FlowQuery never sends `or` or negation.
+ */
+export type SourcePredicate = {
+    op: "and";
+    terms: SourcePredicate[];
+} | {
+    op: "eq" | "gt" | "gte" | "lt" | "lte";
+    property: string;
+    value: any;
+} | {
+    op: "in";
+    property: string;
+    values: any[];
+};
+export interface PredicateCapabilities {
+    /** Operators the source can evaluate.  `and` is always implied. */
+    operators: PredicateOperator[];
+    /** Restrict push-down to these definition columns.  Omit for any column. */
+    properties?: string[];
+    /**
+     * String ordering used for range operators.  Only `"binary"`
+     * (code-unit order) matches FlowQuery and enables string range
+     * push-down; numeric ranges are always eligible.
+     */
+    stringOrdering?: "binary";
+}
+interface BaseSourceCapabilities {
+    /** Contract version; must be {@link SOURCE_CONTRACT_VERSION}. */
+    version: number;
+    /** Predicate push-down support.  Omit when the source ignores predicates. */
+    predicates?: PredicateCapabilities;
+    /**
+     * Results are produced incrementally as pages (async iterables).  For
+     * statement-backed definitions this also enables streaming execution
+     * of eligible inner queries.
+     */
+    streaming?: boolean;
+    /** Repeated identical reads within one query return the same rows and may be cached. */
+    cacheable?: boolean;
+    /** Maximum number of ids per lookup/expand request (default: unlimited). */
+    maxBatchSize?: number;
+}
+export interface NodeSourceCapabilities extends BaseSourceCapabilities {
+    /** The source implements {@link NodeSourceProvider.lookup} (batched lookup by id). */
+    lookup?: boolean;
+}
+export interface RelationshipSourceCapabilities extends BaseSourceCapabilities {
+    /**
+     * Adjacency expansion support.  `left: true` means relationships can be
+     * fetched by `left_id`, `right: true` by `right_id`.
+     */
+    expand?: {
+        left?: boolean;
+        right?: boolean;
+    };
+}
+interface BaseSourceRequest {
+    version: number;
+    /** Pushed-down predicate over definition columns, or `null`. */
+    predicate: SourcePredicate | null;
+    /**
+     * The legacy `$args` equality map built from the pattern's own
+     * property constraints (unchanged shape), or `null`.  Never contains
+     * correlation ids.
+     */
+    args: Record<string, any> | null;
+    /** Preferred page size.  Sources may return smaller or larger pages. */
+    pageSize: number;
+}
+export interface NodeScanRequest extends BaseSourceRequest {
+    operation: "scan";
+    label: string;
+}
+export interface NodeLookupRequest extends BaseSourceRequest {
+    operation: "lookup";
+    label: string;
+    /** Distinct ids to fetch; at most `maxBatchSize` entries. */
+    ids: any[];
+}
+export interface RelationshipScanRequest extends BaseSourceRequest {
+    operation: "scan";
+    type: string;
+    sourceLabel: string | null;
+    targetLabel: string | null;
+}
+export interface RelationshipExpandRequest extends BaseSourceRequest {
+    operation: "expand";
+    type: string;
+    sourceLabel: string | null;
+    targetLabel: string | null;
+    /** Which stored endpoint the anchor ids constrain (`left` → `left_id`). */
+    side: "left" | "right";
+    /** Distinct anchor ids; at most `maxBatchSize` entries. */
+    ids: any[];
+}
+export type NodeSourceRequest = NodeScanRequest | NodeLookupRequest;
+export type RelationshipSourceRequest = RelationshipScanRequest | RelationshipExpandRequest;
+/**
+ * Per-query read context passed to every provider call.
+ */
+export interface SourceReadContext {
+    /** Aborted when the query completes, fails, is cancelled or abandons the read. */
+    signal: AbortSignal;
+    /** Value returned by the provider's `openReadContext`, or `undefined`. */
+    snapshot: unknown;
+}
+/**
+ * Result of a provider call: a single page (array or promise of array),
+ * or a sync/async iterable of pages.  Empty pages are allowed and do not
+ * signal completion; completion is the end of the iteration.
+ */
+export type SourceResult = SourceRow[] | Promise<SourceRow[]> | AsyncIterable<SourceRow[]> | Iterable<SourceRow[]>;
+interface BaseSourceProvider {
+    /**
+     * Optional query-scoped read context (e.g. a snapshot or transaction).
+     * Opened lazily on first use and closed when the query ends.
+     */
+    openReadContext?(): unknown | Promise<unknown>;
+    closeReadContext?(snapshot: unknown): void | Promise<void>;
+}
+export interface NodeSourceProvider extends BaseSourceProvider {
+    readonly capabilities: NodeSourceCapabilities;
+    /** Required: return all rows (optionally filtered by `request.predicate`). */
+    scan(request: NodeScanRequest, context: SourceReadContext): SourceResult;
+    /** Return rows whose `id` is in `request.ids`.  Required when `capabilities.lookup`. */
+    lookup?(request: NodeLookupRequest, context: SourceReadContext): SourceResult;
+    /** Optional cardinality estimate used to rank start points (lower is better). */
+    estimate?(request: NodeScanRequest): number | undefined;
+}
+export interface RelationshipSourceProvider extends BaseSourceProvider {
+    readonly capabilities: RelationshipSourceCapabilities;
+    /** Required: return all rows (optionally filtered by `request.predicate`). */
+    scan(request: RelationshipScanRequest, context: SourceReadContext): SourceResult;
+    /** Return rows whose `side` endpoint is in `request.ids`.  Required when `capabilities.expand`. */
+    expand?(request: RelationshipExpandRequest, context: SourceReadContext): SourceResult;
+}
+/** Base class of all source-related errors. */
+export declare class SourceError extends Error {
+    readonly source: string;
+    readonly operation: string;
+    readonly cause?: unknown;
+    constructor(message: string, source?: string, operation?: string, cause?: unknown);
+}
+/** Invalid capability declaration or provider registration. */
+export declare class SourceCapabilityError extends SourceError {
+    constructor(message: string, source?: string);
+}
+/** Malformed provider response (non-array page, missing ids, invalid cursor...). */
+export declare class SourceResponseError extends SourceError {
+    constructor(message: string, source?: string, operation?: string);
+}
+/**
+ * Thrown by a provider to decline an optional operation at runtime.
+ * FlowQuery then uses its documented fallback (a scan).  Any other
+ * error propagates to the caller of the query.
+ */
+export declare class SourceUnsupportedError extends SourceError {
+    constructor(message?: string, source?: string, operation?: string);
+}
+/** Raised when a query is cancelled through `Runner.cancel()`. */
+export declare class QueryCancelledError extends Error {
+    constructor(message?: string);
+}
+/** Validate a node provider; throws {@link SourceCapabilityError} with an actionable message. */
+export declare function validateNodeProvider(provider: NodeSourceProvider, name: string): void;
+/** Validate a relationship provider; throws {@link SourceCapabilityError} with an actionable message. */
+export declare function validateRelationshipProvider(provider: RelationshipSourceProvider, name: string): void;
+/**
+ * Turn a continuation-token API into a page iterator.  Tokens stay opaque
+ * to FlowQuery; a token repeated twice in a row is reported as an invalid
+ * cursor instead of looping forever.
+ *
+ * @example
+ * ```typescript
+ * scan(req, ctx) {
+ *     return cursorPages((cursor) => backend.query(req, cursor, req.pageSize));
+ * }
+ * ```
+ */
+export declare function cursorPages(fetchPage: (cursor: string | null) => Promise<{
+    rows: SourceRow[];
+    cursor?: string | null;
+}>): AsyncGenerator<SourceRow[], void, unknown>;
+/**
+ * Reference implementation of {@link SourcePredicate} semantics for
+ * in-memory providers and tests.  Returns `true` when the row must be
+ * returned by a source receiving this predicate.
+ */
+export declare function matchesPredicate(predicate: SourcePredicate | null, row: SourceRow): boolean;
+/** Options for {@link inMemoryNodeSource} and {@link inMemoryRelationshipSource}. */
+export interface InMemorySourceOptions {
+    /** Declare the source cacheable (default `true`). */
+    cacheable?: boolean;
+    /** Maximum ids per lookup/expand request (default: unlimited). */
+    maxBatchSize?: number;
+}
+/**
+ * A ready-made node source over an in-memory array of rows (each with an
+ * `id`).  It supports lookup, every predicate operator and paging, which
+ * makes it handy for tests, examples and small reference data sets.  The
+ * array is read on every request, so later mutations are visible.
+ *
+ * @example
+ * ```typescript
+ * FlowQuery.registerNodeSource("Person", inMemoryNodeSource([{ id: 1, name: "Ada" }]));
+ * ```
+ */
+export declare function inMemoryNodeSource(rows: SourceRow[], options?: InMemorySourceOptions): NodeSourceProvider;
+/**
+ * A ready-made relationship source over an in-memory array of rows (each
+ * with `left_id` and `right_id`), supporting expansion from both sides.
+ *
+ * @example
+ * ```typescript
+ * FlowQuery.registerRelationshipSource(
+ *     "KNOWS", "Person", "Person",
+ *     inMemoryRelationshipSource([{ left_id: 1, right_id: 2, since: 2020 }])
+ * );
+ * ```
+ */
+export declare function inMemoryRelationshipSource(rows: SourceRow[], options?: InMemorySourceOptions): RelationshipSourceProvider;
+export {};
+//# sourceMappingURL=source_provider.d.ts.map

package/dist/graph/source_provider.d.ts.map

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

package/dist/graph/source_provider.js

@@ -0,0 +1,306 @@
+"use strict";
+/**
+ * Backend-neutral source provider contract (version 1).
+ *
+ * A source provider exposes the rows of a virtual node label or
+ * relationship type to FlowQuery and declares, through explicit
+ * capabilities, which logical operations it can execute natively
+ * (lookup by id, adjacency expansion, predicate filtering, paging).
+ * FlowQuery plans against these declared operations only; it never
+ * inspects what kind of backend sits behind a provider.
+ *
+ * Rows always describe the *virtual definition*: node rows carry an `id`
+ * plus properties, relationship rows carry `left_id`, `right_id` plus
+ * properties, exactly as a `CREATE VIRTUAL` definition would return them.
+ * Ids are scoped to their label (or relationship type); they do not need
+ * to be globally unique.
+ *
+ * Correctness rule: a provider may return a *superset* of the rows that
+ * satisfy a request — FlowQuery always re-applies every constraint
+ * locally — but it must never drop a row that satisfies the request.
+ */
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryCancelledError = exports.SourceUnsupportedError = exports.SourceResponseError = exports.SourceCapabilityError = exports.SourceError = exports.PREDICATE_OPERATORS = exports.SOURCE_CONTRACT_VERSION = void 0;
+exports.validateNodeProvider = validateNodeProvider;
+exports.validateRelationshipProvider = validateRelationshipProvider;
+exports.cursorPages = cursorPages;
+exports.matchesPredicate = matchesPredicate;
+exports.inMemoryNodeSource = inMemoryNodeSource;
+exports.inMemoryRelationshipSource = inMemoryRelationshipSource;
+exports.SOURCE_CONTRACT_VERSION = 1;
+exports.PREDICATE_OPERATORS = [
+    "eq",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "in",
+];
+/** Base class of all source-related errors. */
+class SourceError extends Error {
+    constructor(message, source = "", operation = "", cause) {
+        super(message);
+        this.name = "SourceError";
+        this.source = source;
+        this.operation = operation;
+        this.cause = cause;
+    }
+}
+exports.SourceError = SourceError;
+/** Invalid capability declaration or provider registration. */
+class SourceCapabilityError extends SourceError {
+    constructor(message, source = "") {
+        super(message, source, "register");
+        this.name = "SourceCapabilityError";
+    }
+}
+exports.SourceCapabilityError = SourceCapabilityError;
+/** Malformed provider response (non-array page, missing ids, invalid cursor...). */
+class SourceResponseError extends SourceError {
+    constructor(message, source = "", operation = "") {
+        super(message, source, operation);
+        this.name = "SourceResponseError";
+    }
+}
+exports.SourceResponseError = SourceResponseError;
+/**
+ * Thrown by a provider to decline an optional operation at runtime.
+ * FlowQuery then uses its documented fallback (a scan).  Any other
+ * error propagates to the caller of the query.
+ */
+class SourceUnsupportedError extends SourceError {
+    constructor(message = "Operation not supported", source = "", operation = "") {
+        super(message, source, operation);
+        this.name = "SourceUnsupportedError";
+    }
+}
+exports.SourceUnsupportedError = SourceUnsupportedError;
+/** Raised when a query is cancelled through `Runner.cancel()`. */
+class QueryCancelledError extends Error {
+    constructor(message = "Query cancelled") {
+        super(message);
+        this.name = "QueryCancelledError";
+    }
+}
+exports.QueryCancelledError = QueryCancelledError;
+function validateBase(caps, name) {
+    if (caps === null || typeof caps !== "object") {
+        throw new SourceCapabilityError(`Source ${name}: capabilities object is required`, name);
+    }
+    if (caps.version !== exports.SOURCE_CONTRACT_VERSION) {
+        throw new SourceCapabilityError(`Source ${name}: unsupported capability version ${JSON.stringify(caps.version)}; expected ${exports.SOURCE_CONTRACT_VERSION}`, name);
+    }
+    if (caps.maxBatchSize !== undefined &&
+        (!Number.isInteger(caps.maxBatchSize) || caps.maxBatchSize < 1)) {
+        throw new SourceCapabilityError(`Source ${name}: maxBatchSize must be a positive integer`, name);
+    }
+    if (caps.predicates !== undefined) {
+        const p = caps.predicates;
+        if (p === null || typeof p !== "object" || !Array.isArray(p.operators)) {
+            throw new SourceCapabilityError(`Source ${name}: predicates.operators must be an array`, name);
+        }
+        for (const op of p.operators) {
+            if (!exports.PREDICATE_OPERATORS.includes(op)) {
+                throw new SourceCapabilityError(`Source ${name}: unknown predicate operator ${JSON.stringify(op)}; supported: ${exports.PREDICATE_OPERATORS.join(", ")}`, name);
+            }
+        }
+        if (p.properties !== undefined && !Array.isArray(p.properties)) {
+            throw new SourceCapabilityError(`Source ${name}: predicates.properties must be an array of column names`, name);
+        }
+        if (p.stringOrdering !== undefined && p.stringOrdering !== "binary") {
+            throw new SourceCapabilityError(`Source ${name}: predicates.stringOrdering must be "binary" when set`, name);
+        }
+    }
+}
+/** Validate a node provider; throws {@link SourceCapabilityError} with an actionable message. */
+function validateNodeProvider(provider, name) {
+    if (provider === null || typeof provider !== "object") {
+        throw new SourceCapabilityError(`Source ${name}: provider object is required`, name);
+    }
+    validateBase(provider.capabilities, name);
+    if (typeof provider.scan !== "function") {
+        throw new SourceCapabilityError(`Source ${name}: provider must implement scan()`, name);
+    }
+    if (provider.capabilities.lookup && typeof provider.lookup !== "function") {
+        throw new SourceCapabilityError(`Source ${name}: capabilities.lookup is true but lookup() is not implemented`, name);
+    }
+}
+/** Validate a relationship provider; throws {@link SourceCapabilityError} with an actionable message. */
+function validateRelationshipProvider(provider, name) {
+    if (provider === null || typeof provider !== "object") {
+        throw new SourceCapabilityError(`Source ${name}: provider object is required`, name);
+    }
+    validateBase(provider.capabilities, name);
+    if (typeof provider.scan !== "function") {
+        throw new SourceCapabilityError(`Source ${name}: provider must implement scan()`, name);
+    }
+    const expand = provider.capabilities.expand;
+    if (expand !== undefined) {
+        if (expand === null || typeof expand !== "object") {
+            throw new SourceCapabilityError(`Source ${name}: capabilities.expand must be an object like { left: true, right: true }`, name);
+        }
+        if ((expand.left || expand.right) && typeof provider.expand !== "function") {
+            throw new SourceCapabilityError(`Source ${name}: capabilities.expand is declared but expand() is not implemented`, name);
+        }
+    }
+}
+/**
+ * Turn a continuation-token API into a page iterator.  Tokens stay opaque
+ * to FlowQuery; a token repeated twice in a row is reported as an invalid
+ * cursor instead of looping forever.
+ *
+ * @example
+ * ```typescript
+ * scan(req, ctx) {
+ *     return cursorPages((cursor) => backend.query(req, cursor, req.pageSize));
+ * }
+ * ```
+ */
+function cursorPages(fetchPage) {
+    return __asyncGenerator(this, arguments, function* cursorPages_1() {
+        var _a;
+        let cursor = null;
+        while (true) {
+            const page = yield __await(fetchPage(cursor));
+            if (page === null || typeof page !== "object" || !Array.isArray(page.rows)) {
+                throw new SourceResponseError("Cursor page must be an object with a rows array");
+            }
+            yield yield __await(page.rows);
+            const next = (_a = page.cursor) !== null && _a !== void 0 ? _a : null;
+            if (next === null) {
+                return yield __await(void 0);
+            }
+            if (next === cursor) {
+                throw new SourceResponseError(`Invalid continuation token: ${String(next)} repeated`);
+            }
+            cursor = next;
+        }
+    });
+}
+function isRangeComparable(value, bound) {
+    return (value !== null &&
+        value !== undefined &&
+        (typeof bound === "number" || typeof bound === "string") &&
+        typeof value === typeof bound);
+}
+/**
+ * A source may only drop a row for an equality/IN term when the property
+ * is absent or holds a number/string that differs from every value;
+ * other values (booleans, lists, maps...) must be returned and are
+ * re-checked by FlowQuery.
+ */
+function matchesEquality(row, property, values) {
+    if (!(property in row))
+        return false;
+    const value = row[property];
+    if (typeof value !== "number" && typeof value !== "string")
+        return true;
+    return values.includes(value);
+}
+/**
+ * Reference implementation of {@link SourcePredicate} semantics for
+ * in-memory providers and tests.  Returns `true` when the row must be
+ * returned by a source receiving this predicate.
+ */
+function matchesPredicate(predicate, row) {
+    if (predicate === null)
+        return true;
+    switch (predicate.op) {
+        case "and":
+            return predicate.terms.every((t) => matchesPredicate(t, row));
+        case "eq":
+            return matchesEquality(row, predicate.property, [predicate.value]);
+        case "in":
+            return matchesEquality(row, predicate.property, predicate.values);
+        default: {
+            const value = row[predicate.property];
+            if (!isRangeComparable(value, predicate.value))
+                return true;
+            switch (predicate.op) {
+                case "gt":
+                    return value > predicate.value;
+                case "gte":
+                    return value >= predicate.value;
+                case "lt":
+                    return value < predicate.value;
+                case "lte":
+                    return value <= predicate.value;
+            }
+        }
+    }
+    return true;
+}
+function* pagesOf(rows, pageSize) {
+    const size = Number.isInteger(pageSize) && pageSize > 0 ? pageSize : rows.length || 1;
+    for (let i = 0; i < rows.length; i += size) {
+        yield rows.slice(i, i + size);
+    }
+}
+function filterRows(rows, predicate, field, ids) {
+    const wanted = ids === null ? null : new Set(ids);
+    return rows.filter((row) => (wanted === null || (field !== null && wanted.has(row[field]))) &&
+        matchesPredicate(predicate, row));
+}
+function inMemoryCapabilities(options) {
+    var _a;
+    const caps = {
+        version: exports.SOURCE_CONTRACT_VERSION,
+        cacheable: (_a = options.cacheable) !== null && _a !== void 0 ? _a : true,
+        streaming: true,
+        predicates: { operators: [...exports.PREDICATE_OPERATORS], stringOrdering: "binary" },
+    };
+    if (options.maxBatchSize !== undefined)
+        caps.maxBatchSize = options.maxBatchSize;
+    return caps;
+}
+/**
+ * A ready-made node source over an in-memory array of rows (each with an
+ * `id`).  It supports lookup, every predicate operator and paging, which
+ * makes it handy for tests, examples and small reference data sets.  The
+ * array is read on every request, so later mutations are visible.
+ *
+ * @example
+ * ```typescript
+ * FlowQuery.registerNodeSource("Person", inMemoryNodeSource([{ id: 1, name: "Ada" }]));
+ * ```
+ */
+function inMemoryNodeSource(rows, options = {}) {
+    return {
+        capabilities: Object.assign(Object.assign({}, inMemoryCapabilities(options)), { lookup: true }),
+        scan: (req) => pagesOf(filterRows(rows, req.predicate, null, null), req.pageSize),
+        lookup: (req) => pagesOf(filterRows(rows, req.predicate, "id", req.ids), req.pageSize),
+    };
+}
+/**
+ * A ready-made relationship source over an in-memory array of rows (each
+ * with `left_id` and `right_id`), supporting expansion from both sides.
+ *
+ * @example
+ * ```typescript
+ * FlowQuery.registerRelationshipSource(
+ *     "KNOWS", "Person", "Person",
+ *     inMemoryRelationshipSource([{ left_id: 1, right_id: 2, since: 2020 }])
+ * );
+ * ```
+ */
+function inMemoryRelationshipSource(rows, options = {}) {
+    return {
+        capabilities: Object.assign(Object.assign({}, inMemoryCapabilities(options)), { expand: { left: true, right: true } }),
+        scan: (req) => pagesOf(filterRows(rows, req.predicate, null, null), req.pageSize),
+        expand: (req) => pagesOf(filterRows(rows, req.predicate, req.side === "left" ? "left_id" : "right_id", req.ids), req.pageSize),
+    };
+}
+//# sourceMappingURL=source_provider.js.map

package/dist/graph/source_provider.js.map

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

package/dist/graph/statement_source.d.ts

@@ -0,0 +1,27 @@
+import SourceContext from "./source_context";
+import { NodeSourceCapabilities, RelationshipSourceCapabilities, SourceReadContext, SourceRow } from "./source_provider";
+import type VirtualStatement from "./virtual_statement";
+/**
+ * Adapts a `CREATE VIRTUAL` definition to the source provider contract.
+ *
+ * The definition is opted in with explicit capabilities; every request
+ * runs the inner statement with `$request` bound to the request envelope
+ * (`operation`, `label`/`type`, `ids`, `side`, `predicate`, `pageSize`)
+ * while `$args` keeps its legacy meaning.  Statements that ignore part
+ * of the request remain correct because FlowQuery re-checks every row.
+ */
+export declare class StatementSourceProvider {
+    private readonly _virtual;
+    readonly capabilities: NodeSourceCapabilities & RelationshipSourceCapabilities;
+    constructor(_virtual: VirtualStatement, capabilities: NodeSourceCapabilities & RelationshipSourceCapabilities);
+    private _run;
+    scan(request: any, context: SourceReadContext): any;
+    lookup(request: any, context: SourceReadContext): any;
+    expand(request: any, context: SourceReadContext): any;
+}
+/**
+ * Fully read a provider's scan (legacy eager paths: schema
+ * introspection, pattern expressions and mixed legacy/provider patterns).
+ */
+export declare function materializeScan(provider: any, kind: "node" | "relationship", name: string, base: Record<string, any>, args: Record<string, any> | null, ctx: SourceContext | null): Promise<SourceRow[]>;
+//# sourceMappingURL=statement_source.d.ts.map

package/dist/graph/statement_source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statement_source.d.ts","sourceRoot":"","sources":["../../src/graph/statement_source.ts"],"names":[],"mappings":"AAAA,OAAO,aAA4B,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EACH,sBAAsB,EACtB,8BAA8B,EAC9B,iBAAiB,EACjB,SAAS,EACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,gBAAgB,MAAM,qBAAqB,CAAC;AAExD;;;;;;;;GAQG;AACH,qBAAa,uBAAuB;IAE5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;aACT,YAAY,EAAE,sBAAsB,GAAG,8BAA8B;gBADpE,QAAQ,EAAE,gBAAgB,EAC3B,YAAY,EAAE,sBAAsB,GAAG,8BAA8B;IAEzF,OAAO,CAAC,IAAI;IAOL,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,iBAAiB,GAAG,GAAG;IAGnD,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,iBAAiB,GAAG,GAAG;IAGrD,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,iBAAiB,GAAG,GAAG;CAG/D;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACjC,QAAQ,EAAE,GAAG,EACb,IAAI,EAAE,MAAM,GAAG,cAAc,EAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,EAChC,GAAG,EAAE,aAAa,GAAG,IAAI,GAC1B,OAAO,CAAC,SAAS,EAAE,CAAC,CAkBtB"}