@routier/core 0.5.0 → 0.7.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>;
@@ -47,6 +40,41 @@ export declare class QueryOptionsCollection<T> {
      * runs it over the first execution's scalar result.
      */
     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;
+    /**
+     * Forgets what any previous dispatch reported.
+     *
+     * Capability is answered per dispatch, so a report is only an answer for the execution that
+     * produced it. The items are shared with any snapshot, so a report mutated in place otherwise
+     * survives a restore and a second terminal on the same queryable replays options the plugin
+     * did run — a `skip` applied twice, over rows already windowed.
+     */
+    forgetReports(): void;
+    /** 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,3 +1,4 @@
+export * from './describeFilter';
 export * from './explain';
 export * from './formatExplanation';
 export * from './join';

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/types.d.ts

@@ -27,13 +27,45 @@ 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" | "renamed-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;

package/dist/plugins/resultShape.d.ts

@@ -0,0 +1,35 @@
+import type { PropertyInfo } from '../schema/PropertyInfo';
+import type { QueryField } from './query/types';
+/**
+ * What a statement or command RETURNS, described before it runs.
+ *
+ * A plugin's builder knows this and nothing else knows it: the shape of a result comes from the
+ * projection, the join aliases, or the `RETURNING` list, none of which survive into the SQL as
+ * anything a reader could recover. So the builder states it, once, beside the statement it built.
+ *
+ * Deliberately says nothing about what anyone does with the result. It is a description, not an
+ * instruction — the same description serves a driver that transfers rows across a worker
+ * boundary, one that hands them straight back, and one that only wants to know the column order.
+ * A consumer that needs more turns this into whatever it needs: `buildTransferPlan` in
+ * `@routier/core/transfer` is one such consumer, and it is not privileged.
+ */
+export type ResultColumn = {
+    /** Exact name the engine will return, including any projection or join alias. */
+    readonly name: string;
+    /**
+     * The schema property behind the column, or `null`.
+     *
+     * `null` for an expression — a computed value, an aggregate, anything with no declared type
+     * to reason from. A consumer that wants to treat the value specially needs the property; one
+     * that only wants names does not.
+     */
+    readonly property: PropertyInfo<any> | null;
+};
+/**
+ * The columns a `map` projection selects.
+ *
+ * Named by `sourceName`, which is what the statement actually emits; the rename to
+ * `destinationName` happens in the translator, after the rows come back. A field with no
+ * `property` is an expression.
+ */
+export declare const mappedResultColumns: (fields: readonly QueryField[]) => ResultColumn[];

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/index.cjs

@@ -618,12 +618,14 @@ const isLogLevel = (value)=>typeof value === 'string' && LOG_LEVELS.includes(val
         const debug = process.env.DEBUG;
         if (debug === 'routier' || debug === '*') return 'debug';
         const env = "production"?.toLowerCase();
-        // `test` is deliberately absent. It used to be here, which meant no test suite anywhere
-        // could run Routier quietly. Opt in with DEBUG=routier or ROUTIER_LOG_LEVEL when a test
-        // needs the output.
         if (env === 'dev' || env === 'development') return 'debug';
     }
-    return 'silent';
+    // Warnings are on unless something turns them off.
+    //
+    // Routier warns when a query returns correct rows a slower way than it could, or when a filter
+    // compares types that can never match. Both are the caller's to act on, and a default of
+    // `silent` meant the only people who ever saw them were the ones who already knew to look.
+    return 'warn';
 };
 let level = resolveLevel();
 let rank = RANK[level];
@@ -1779,12 +1781,6 @@ class SchemaComputed extends SchemaBase {
 ;// CONCATENATED MODULE: ./src/schema/PropertyInfo.ts
 
 
-const SUPPORTED_DESERIALIZATION_TYPES = new Set([
-    types/* .SchemaTypes.Boolean */.L.Boolean,
-    types/* .SchemaTypes.Date */.L.Date,
-    types/* .SchemaTypes.Number */.L.Number,
-    types/* .SchemaTypes.String */.L.String
-]);
 /**
  * Represents metadata and utilities for a property in a schema, including its type, name, parent, children, and serialization details.
  */ class PropertyInfo {
@@ -1904,9 +1900,6 @@ const SUPPORTED_DESERIALIZATION_TYPES = new Set([
     get isRenamed() {
         return !!this.from;
     }
-    get supportsDeserialization() {
-        return this.valueDeserializer != null || SUPPORTED_DESERIALIZATION_TYPES.has(this.type);
-    }
     _getPropertyChain() {
         if (this._propertyChainCache) {
             return this._propertyChainCache;
@@ -2159,7 +2152,7 @@ const SUPPORTED_DESERIALIZATION_TYPES = new Set([
         if (this.type === types/* .SchemaTypes.Boolean */.L.Boolean) {
             return Boolean(value);
         }
-        throw new Error(`Unsupported deserialization for type.  Type: ${this.type}`);
+        return value;
     }
 }