@routier/core 0.6.0 → 0.8.0

package/dist/plugins/query/QueryOptionsCollection.d.ts

@@ -9,18 +9,11 @@ export declare class QueryOptionsCollection<T> {
     private nextExecutionReason;
     private nextIndex;
     private enumeratedItems;
+    private dirty;
+    /** The collection a `splitAt`/`split` half came from. A capability report belongs to it. */
+    private origin;
     /** Cuts over to memory execution, keeping the first cause. See `MemoryExecutionReason`. */
     private cutOverToMemory;
-    /**
-     * True when `split()` or `splitAt()` produced this collection.
-     *
-     * Those rebuild each half by re-adding its options, which re-derives execution targets
-     * without the options that caused them — a post-join filter alone in the memory half
-     * derives back to `"database"`. Anything reading `target` as a report of where work runs
-     * has to reject a derived collection; see `explainQuery`.
-     */
-    private derived;
-    get isDerived(): boolean;
     get items(): Map<keyof QueryOptionValueMap<unknown>, QueryCollectionItem<any, any>[]>;
     get isEmpty(): boolean;
     static EMPTY<R>(): QueryOptionsCollection<R>;
@@ -45,8 +38,53 @@ export declare class QueryOptionsCollection<T> {
      * the shared collection before executing. Without restoring, a re-executed terminal —
      * the whole point of a subscribed queryable — stacks its option a second time and
      * runs it over the first execution's scalar result.
+     *
+     * The item objects are shared with the snapshot. Nothing reports on them, because every
+     * dispatch sends a `forDispatch` copy, so a restore brings back no reports.
      */
     snapshot(): () => void;
+    /** Takes an item as it stands — same object, same index, same target and reason. */
+    private adopt;
+    /**
+     * A plugin reporting that its engine cannot express one option.
+     *
+     * Core marks the rest of the database phase `not-reached`, because the database has to stop
+     * there — a window applied in front of a filter that was not applied returns the wrong rows.
+     * Passing the cascade through core is what makes it impossible for a plugin to mark a
+     * non-contiguous cut.
+     *
+     * A report names a culprit and never un-names one, so reports commute.
+     *
+     * The option is not moved to the memory arm. It stays where it was planned, which is what keeps
+     * a redirect distinguishable from something core sent to memory in the first place.
+     */
+    reportMissingCapability(item: QueryCollectionItem<any, any>): void;
+    /**
+     * A plugin reporting that its engine would answer one option differently from JavaScript.
+     *
+     * Same cascade as `reportMissingCapability`, and a separate reason because the caller can act on
+     * one and not the other. See `DatabaseExecutionReason`.
+     */
+    reportEngineDivergence(item: QueryCollectionItem<any, any>): void;
+    private report;
+    /**
+     * A copy of the collection for one dispatch to a plugin, with nothing reported on it.
+     *
+     * Capability is answered per dispatch, so a report is only an answer for the execution that
+     * produced it. Reports are written onto items, and the items of a queryable's collection
+     * outlive any one execution: a snapshot shares them, and a subscription dispatches the same
+     * query on every change. A report left on them replays options the plugin did run on the
+     * next execution, such as a `skip` applied twice over rows already windowed, or hands a
+     * renamed filter to memory that the engine could have run.
+     *
+     * Each item keeps its index, name, value and target. A half from `split`/`splitAt` is copied
+     * with a copy of its origin, and its items are that copy's items, so a report on the half still
+     * cascades over the whole dispatch without reaching the collection it was copied from.
+     */
+    forDispatch(): QueryOptionsCollection<T>;
+    private copyForDispatch;
+    /** The options the database did not run, in the order they were written. */
+    notExecuted(): QueryCollectionItem<any, any>[];
     split(): {
         memory: QueryOptionsCollection<T>;
         database: QueryOptionsCollection<T>;

package/dist/plugins/query/describeFilter.d.ts

@@ -0,0 +1,83 @@
+import type { Expression } from "../../expressions";
+/**
+ * Saying what a backend was asked to do, with the values pulled out.
+ *
+ * `explain` already carries `{ text, parameters }` per executed query, and the SQL plugins fill
+ * both in — a statement with `?` and the values bound to it. Every other backend reported a
+ * placeholder: Dexie said `filter(<predicate>)`, which names nothing, and a key-value store said
+ * only that it scanned. The predicate was the one thing a reader wanted and the one thing missing.
+ *
+ * Two renderings live here, and neither knows about a specific engine:
+ *
+ * - `describeFilterAsJs` — the predicate as JavaScript, for a backend with no query language of
+ *   its own. It reads like what the caller wrote, which is what they are looking for.
+ * - `parameteriseDocument` — for a backend whose query IS a document. Values become `?` and are
+ *   collected in order, so a Mango selector and an MQL filter both come out in their own shape
+ *   with the values listed beside them.
+ *
+ * Pulling values out is not decoration. It is what makes two runs of one query comparable, and
+ * what keeps a value out of the text when that text is logged.
+ */
+export type ParameterisedQuery = {
+    /** The query in its own language, with each value replaced by `?`. */
+    text: string;
+    /** The values, in the order their placeholders appear. */
+    parameters: unknown[];
+};
+/**
+ * The predicate as JavaScript, with every value replaced by `?`.
+ *
+ * Rendered from the parsed tree rather than from the function's source. The tree is what the
+ * backend was actually given, so this cannot drift from what ran; and a value reaching the tree
+ * as a literal is indistinguishable from one arriving through a params object, which is what
+ * makes both come out as `?` the way SQL treats them.
+ */
+export declare const describeFilterAsJs: (expression: Expression) => ParameterisedQuery;
+/**
+ * Marks a value inside a query document so it is replaced by `?` rather than printed.
+ *
+ * A document language carries its values inline, so there is nothing in the shape itself to say
+ * which parts are operators and which are data. A dialect wraps the data as it builds the
+ * document, and `parameteriseDocument` reads the wrapper.
+ */
+declare const PARAMETER: unique symbol;
+export type ParameterHolder = {
+    readonly [PARAMETER]: unknown;
+};
+export declare const parameter: (value: unknown) => ParameterHolder;
+/**
+ * Renders a query DOCUMENT with its values replaced by `?`.
+ *
+ * Language-agnostic on purpose: an MQL filter and a Mango selector are both plain objects, and so
+ * is whatever a future document store wants reported. The dialect decides the shape; this only
+ * decides how it is written down.
+ *
+ * A value not wrapped by `parameter` is structural — an operator name, a field path, a nesting
+ * level — and is printed as it is. That is the whole distinction, and it has to be made where the
+ * document is built, because by the time it is an object the two are the same kind of thing.
+ */
+export declare const parameteriseDocument: (document: unknown) => ParameterisedQuery;
+/**
+ * Every filter on a query, as one description.
+ *
+ * Filters accumulate — `.where(a).where(b)` is `a && b` — so they are reported as one predicate
+ * rather than several, which is how the caller thinks of them and how a SQL plugin renders them
+ * into one `WHERE`. Parameters run left to right across the whole thing, matching the text.
+ *
+ * A filter that could not be parsed falls back to its source. Mixing the two is deliberate: one
+ * unparsable filter does not make the others unreadable, and seeing which one it was is the
+ * point.
+ */
+export declare const describeFilters: (filters: readonly {
+    expression: Expression;
+    filter?: unknown;
+}[]) => ParameterisedQuery;
+/**
+ * A predicate core could not parse, shown as the caller wrote it.
+ *
+ * This is the case where the source matters most: an unparsable filter is why the query did not
+ * push down, and the reason codes say that it happened without showing what it was. There are no
+ * parameters — nothing was extracted, because nothing was understood.
+ */
+export declare const describeUnparsableFilter: (filter: unknown, reason?: string) => ParameterisedQuery;
+export {};

package/dist/plugins/query/explain.d.ts

@@ -1,4 +1,4 @@
-import { MemoryExecutionReason, QueryOptionExecutionTarget, QueryOptionName } from "./types";
+import { DatabaseExecutionReason, MemoryExecutionReason, QueryOptionName } from "./types";
 import { QueryOptionsCollection } from "./QueryOptionsCollection";
 /**
  * One sentence per reason code, written for someone meeting pushdown for the first time.
@@ -24,25 +24,68 @@ export type ExplainedOption = {
     detail?: Record<string, unknown>;
 };
 export declare const EXECUTED_QUERIES_UNSUPPORTED = "This plugin did not report what it executed. It may not support explain.";
+/**
+ * Why an option planned for the database did not run there. `executed` has no sentence: it needs no
+ * explaining, and a step made of executed options is a database step like any other.
+ */
+export declare const DATABASE_EXECUTION_EXPLANATIONS: Record<Exclude<DatabaseExecutionReason, "executed">, string>;
+/**
+ * Where a step ran.
+ *
+ * A database step names WHICH database, because a cross-plugin join reads from more than one — and a
+ * name alone does not say whether the second was PostgreSQL or PouchDB, which is the difference
+ * between a statement a reader recognises and one they cannot place.
+ */
+export type ExecutedIn = {
+    kind: "database";
+    database: string;
+    plugin: string;
+} | {
+    kind: "memory";
+};
+/** Why a step is not in the database. `executed` never appears: those steps ARE in the database. */
+export type StepReason = MemoryExecutionReason | Exclude<DatabaseExecutionReason, "executed">;
+/**
+ * One run of options in one place.
+ *
+ * A union, so a memory step cannot carry statements it could not have run and a database step cannot
+ * carry a reason for not being in the database.
+ */
 export type ExecutionStep = {
     step: number;
     of: number;
-    executedIn: QueryOptionExecutionTarget;
-    description: string;
+    executedIn: Extract<ExecutedIn, {
+        kind: "database";
+    }>;
     options: ExplainedOption[];
-    /** Set on database steps once the plugin has reported. */
-    executedQueries?: ExecutedQuery[];
-    /** Set on the first database step instead, when the plugin reported nothing. */
+    /** What the plugin reported running. Empty when it reported nothing. */
+    executedQueries: ExecutedQuery[];
+    /** Set instead, when this plugin does not report what it executed. */
     executedQueriesUnsupported?: string;
-    /** Set on memory steps only. */
-    reason?: MemoryExecutionReason;
+} | {
+    step: number;
+    of: number;
+    executedIn: Extract<ExecutedIn, {
+        kind: "memory";
+    }>;
+    options: ExplainedOption[];
+    reason?: StepReason;
     explanation?: string;
 };
+export type DatabaseStep = Extract<ExecutionStep, {
+    executedQueries: ExecutedQuery[];
+}>;
+export type MemoryStep = Exclude<ExecutionStep, DatabaseStep>;
+/**
+ * TypeScript does not narrow a union from a discriminant nested inside a property, so the two kinds
+ * of step need a guard rather than an inline check.
+ */
+export declare const isDatabaseStep: (step: ExecutionStep) => step is DatabaseStep;
 export type QueryExplanationSummary = {
     database: number;
     memory: number;
     /** Deduped, in first-seen order. Empty when the whole query pushed down. */
-    reasons: MemoryExecutionReason[];
+    reasons: StepReason[];
     explanation: string;
 };
 export type QueryExplanation = {
@@ -80,3 +123,22 @@ export declare const explainQuery: (options: QueryOptionsCollection<any>, contex
  * original — nothing mutates them, and copying deeper would only look safer than it is.
  */
 export declare const withExecutedQueries: (explanation: QueryExplanation, executedQueries: ExecutedQuery[]) => QueryExplanation;
+/**
+ * Adds the step for a cross-plugin join's inner side.
+ *
+ * Appended by the executor rather than derived from the options, because the inner side's options
+ * live on the join, in its own collection, and were never part of this query's chain. It goes before
+ * the memory steps that consume it — the join cannot run until both sides are read.
+ */
+/**
+ * Every statement the query ran, across every database it touched, in execution order.
+ *
+ * A step is a place, so the statements live on the steps — this is for a caller that wants them all
+ * without caring which plugin ran which.
+ */
+export declare const executedQueriesOf: (explanation: QueryExplanation) => ExecutedQuery[];
+export declare const withInnerSide: (explanation: QueryExplanation, innerSide: {
+    database: string;
+    plugin: string;
+    executedQueries: ExecutedQuery[];
+}) => QueryExplanation;

package/dist/plugins/query/index.d.ts

@@ -1,7 +1,9 @@
+export * from './describeFilter';
 export * from './explain';
 export * from './formatExplanation';
 export * from './join';
 export * from './Query';
 export * from './QueryOptionsCollection';
+export * from './renames';
 export * from './types';
 export * from './similarity';

package/dist/plugins/query/join.d.ts

@@ -5,6 +5,7 @@ import type { DbPluginQueryEvent } from "../types";
 import type { ITranslatedValue } from "../translators/types";
 import { QueryOptionsCollection } from "./QueryOptionsCollection";
 import { QueryOptionValueMap } from "./types";
+import { ExecutedQuery } from "./explain";
 export type JoinKind = "inner" | "left";
 /**
  * One side's join key, as a property path plus the resolved property.
@@ -165,7 +166,9 @@ export declare const loadJoinInnerSide: <TRoot extends {}, TShape>(event: DbPlug
  * before anything else — so it is optional, and its absence costs a wider inner read rather
  * than a wrong one.
  */
-outerKeys?: ReadonlySet<unknown> | null) => void;
+outerKeys?: ReadonlySet<unknown> | null, 
+/** Where the inner read reports what it executed. Defaults to the outer read's own list. */
+innerExecutedQueries?: ExecutedQuery[]) => void;
 /**
  * Interprets a join by running TWO ordinary queries through the plugin's own read path.
  *

package/dist/plugins/query/renames.d.ts

@@ -0,0 +1,27 @@
+import { QueryOptionsCollection } from "./QueryOptionsCollection";
+/**
+ * The options that name a property by what the caller wrote, and so can name a renamed one.
+ *
+ * `sum`, `min`, `max` and `distinct` are not among them: they carry no property, and read what the
+ * `map` in front of them projected. A report on that `map` ends the database phase, so they run in
+ * memory behind it.
+ */
+export type PropertyReadingOption = "filter" | "sort" | "nearest" | "map" | "group";
+/**
+ * Hands back every option over a property stored under a `.from()` name, for the datastore to run
+ * in memory.
+ *
+ * Core keeps such an option with the database, because only the plugin knows whether its backend
+ * reads storage names. One that translates the option — SQL renders the column from
+ * `getResolvedName()` — needs nothing from here. One that runs the caller's lambda over rows as it
+ * stores them reads a key the row does not have, and answers wrongly without an error: that plugin
+ * calls this before it reads anything, and the datastore finishes the query after deserialization,
+ * where the in-memory names exist.
+ *
+ * Reported as `missing-capability`: the backend cannot express the option as written, and like
+ * every capability, that is only knowable by the plugin.
+ *
+ * @param names Which options to check, for a plugin that resolves some of them itself — Mongo renders
+ * filters and sorts through the stored path, and runs `nearest`, `map` and `group` in JavaScript.
+ */
+export declare const reportRenamedProperties: (options: QueryOptionsCollection<any>, names?: readonly PropertyReadingOption[]) => void;

package/dist/plugins/query/types.d.ts

@@ -14,7 +14,16 @@ export type QueryField = {
     sourceName: string;
     destinationName: string;
     isRename: boolean;
+    /** The property the field's value is read from, when it reads exactly one. */
     property?: PropertyInfo<unknown>;
+    /** Every property the field's value is read from. Absent when the selector could not be parsed. */
+    reads?: PropertyInfo<unknown>[];
+    /**
+     * `false` when the value is computed from `property` rather than being it, as in `x.createdDate.getTime()`,
+     * or when the selector could not be parsed. Absent on a field built from a property rather than a
+     * selector, which is that property.
+     */
+    isDirectProperty?: boolean;
     getter: <T>(data: Record<string, unknown>) => T;
 };
 export type QueryOptionExecutionTarget = "database" | "memory";
@@ -27,22 +36,57 @@ export type QueryOptionName = keyof QueryOptionValueMap<unknown>;
  * never returns to `"database"`, so the code recorded is the FIRST cause and it stays on every
  * option after it. Reporting a later one would name a symptom of this one.
  */
-export type MemoryExecutionReason = "not-parsable" | "unmapped-property" | "renamed-property" | "map-rename" | "after-nearest" | "after-join" | "cross-plugin-join";
+/** Why core planned an option for memory, decided when the option is added. */
+export type MemoryExecutionReason = "not-parsable" | "unmapped-property" | "map-rename" | "after-nearest" | "after-join" | "cross-plugin-join" | "predicate-error" | "after-window";
+/**
+ * What became of an option planned for the database.
+ *
+ * `missing-capability` and `engine-divergence` are the only values a plugin writes, and the only
+ * ones core cannot derive: an engine's capabilities are not knowable from here. SQLite's `REGEXP`
+ * exists if the host registered the function and not otherwise, so two instances in one process can
+ * differ.
+ *
+ * They are separate because a developer can act on one and not the other: no way to say it at all,
+ * versus an engine that would answer, and answer differently from JavaScript.
+ *
+ * `not-reached` is the rest of the database phase after either. The database stops there rather than
+ * carrying on: a window applied in front of a filter that was not applied returns the wrong rows.
+ * Core writes it, so a plugin cannot mark a cascade it does not own.
+ */
+export type DatabaseExecutionReason = "executed" | "missing-capability" | "engine-divergence" | "not-reached";
+/**
+ * One option, and where it runs.
+ *
+ * `target` narrows what `reason` can say, so an option cannot carry a reason that does not belong to
+ * the half it was planned for. An option is never moved between arms — the database arm records what
+ * became of it, which is what makes a redirect readable:
+ *
+ * ```ts
+ * option.target === "database" && option.reason === "missing-capability"
+ * ```
+ */
 export type QueryOption<T, K extends QueryOptionName> = {
     name: QueryOptionName;
     value: QueryOptionValueMap<T>[K];
-    target: QueryOptionExecutionTarget;
-    /** Set only when `target` is `"memory"`. */
-    reason?: MemoryExecutionReason;
+    target: "database";
+    reason: DatabaseExecutionReason;
+} | {
+    name: QueryOptionName;
+    value: QueryOptionValueMap<T>[K];
+    target: "memory";
+    reason: MemoryExecutionReason;
 };
 export type QueryOptionValueMap<T extends {}> = {
     skip: number;
     take: number;
+    /** `property`, `reads` and `isDirectProperty` mean what they do on a {@link QueryField}. */
     sort: {
         selector: GenericFunction<T, T[keyof T]>;
         direction: QueryOrdering;
         propertyName: string;
         property?: PropertyInfo<T> | null;
+        reads?: PropertyInfo<T>[];
+        isDirectProperty?: boolean;
     };
     map: {
         selector: GenericFunction<T, any>;
@@ -69,6 +113,8 @@ export type QueryOptionValueMap<T extends {}> = {
         selector: GenericFunction<T, T[keyof T]>;
         propertyName: string;
         property?: PropertyInfo<T> | null;
+        reads?: PropertyInfo<T>[];
+        isDirectProperty?: boolean;
         vector: number[];
         count: number;
     };

package/dist/plugins/translators/SqlTranslator.d.ts

@@ -1,6 +1,7 @@
 import { QueryOption } from "../query/types";
 import { IQuery } from "../types";
 import { DataTranslator } from "./DataTranslator";
+import { ITranslatedValue } from "./types";
 /**
  * What the statement that produced these rows actually did.
  *
@@ -16,6 +17,20 @@ export type SqlPushdown = {
 export declare class SqlTranslator<TRoot extends {}, TShape> extends DataTranslator<TRoot, TShape> {
     protected readonly pushedDown: SqlPushdown;
     constructor(query: IQuery<TRoot, TShape>, pushedDown?: SqlPushdown);
+    /**
+     * Dates back as Dates, before the caller's selectors run over the rows.
+     *
+     * A `group` key and a `map` are the caller's lambdas, run here over rows as the engine returned them.
+     * SQLite, D1 and libSQL hand a date back as the TEXT it was stored as, which has no `getFullYear()`
+     * and groups apart from the Date the entity holds. Revived at storage paths and in place, which the
+     * datastore's deserialization still reads, and after `decodeJsonColumns`, so a date inside a JSON
+     * column is revived too. Only a string is converted, so an engine that returns a Date (PostgreSQL,
+     * PGlite, MySQL) is left alone, and so is a row already revived.
+     *
+     * Not a joined statement's rows, which are tuples, each half already deserialized. Nor rows whose
+     * `group` or `map` was handed back, which the datastore runs after deserializing them.
+     */
+    translate(data: unknown): ITranslatedValue<TShape>;
     count<TResult extends number>(data: unknown, _: QueryOption<TShape, "count">): TResult;
     min<TResult extends string | number | Date>(data: unknown, _: QueryOption<TShape, "min">): TResult;
     max<TResult extends string | number | Date>(data: unknown, _: QueryOption<TShape, "max">): TResult;

package/dist/schema/PropertyInfo.d.ts

@@ -89,7 +89,6 @@ export declare class PropertyInfo<T extends {}> {
      */
     get level(): number;
     get isRenamed(): boolean;
-    get supportsDeserialization(): boolean;
     private _getPropertyChain;
     private _needsOptionalChaining;
     private _resolvePathArray;

package/dist/schema/SchemaDefinition.d.ts

@@ -36,6 +36,14 @@ export declare class SchemaDefinition<T extends {}> extends SchemaBase<T, any> {
      */
     get '~standard'(): StandardJSONSchemaV1.Props<InferCreateType<T>, InferType<T>>;
     private createReturnFunction;
+    /**
+     * Compiles `builder` into a function taking `fnArgs`.
+     *
+     * A builder with bindings is compiled one level out: an outer function whose parameters are
+     * the bindings, called once here with their values, returns the function that is kept. The
+     * bound values become closure variables of that function, so the per-call cost is a context
+     * read rather than anything resolved by name.
+     */
     private createFunction;
     modify<R>(builder: (d: {
         function: <UU, I = never>(fn: (entity: InferType<CompiledSchema<T>>, collectionName: CollectionName, injected: I) => UU, injected?: I) => SchemaFunction<UU, I, "unmapped">;

package/dist/schema/changeTracker.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Builds the proxy factory that change-tracks an entity.
+ *
+ * Generated schema code receives the result as a bound value — a parameter of the generated
+ * factory — and never refers to this module by name. Name references do not survive a minifier,
+ * which renames the declaration but cannot see inside generated source text (#40, #46). The
+ * returned function holds no per-entity state, so one per compiled schema is shared by every
+ * entity it tracks.
+ */
+export declare function createChangeTracker(): <TEntity extends {}>(entity: TEntity, path?: string, parent?: TEntity) => TEntity;