@routier/core 0.3.0 → 0.5.0

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

@@ -6,8 +6,21 @@ export type QueryCollectionItem<T, K extends QueryOptionName> = {
 export declare class QueryOptionsCollection<T> {
     private options;
     private nextExecutionTarget;
+    private nextExecutionReason;
     private nextIndex;
     private enumeratedItems;
+    /** 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>;

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

@@ -0,0 +1,82 @@
+import { MemoryExecutionReason, QueryOptionExecutionTarget, QueryOptionName } from "./types";
+import { QueryOptionsCollection } from "./QueryOptionsCollection";
+/**
+ * One sentence per reason code, written for someone meeting pushdown for the first time.
+ *
+ * Beside the codes rather than in the formatter, so console output, a failing test and the
+ * docs all say the same thing.
+ */
+export declare const MEMORY_EXECUTION_EXPLANATIONS: Record<MemoryExecutionReason, string>;
+/**
+ * One thing a backend actually executed, in the backend's own language.
+ *
+ * A plugin pushes these onto `DbPluginQueryEvent.executedQueries` as it runs them, so a join —
+ * which reads twice — reports both, in execution order. `text` is not required to be SQL: a
+ * key-value store describes what it did in whatever terms it has.
+ */
+export type ExecutedQuery = {
+    text: string;
+    parameters?: unknown[];
+};
+export type ExplainedOption = {
+    index: number;
+    name: QueryOptionName;
+    detail?: Record<string, unknown>;
+};
+export declare const EXECUTED_QUERIES_UNSUPPORTED = "This plugin did not report what it executed. It may not support explain.";
+export type ExecutionStep = {
+    step: number;
+    of: number;
+    executedIn: QueryOptionExecutionTarget;
+    description: string;
+    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. */
+    executedQueriesUnsupported?: string;
+    /** Set on memory steps only. */
+    reason?: MemoryExecutionReason;
+    explanation?: string;
+};
+export type QueryExplanationSummary = {
+    database: number;
+    memory: number;
+    /** Deduped, in first-seen order. Empty when the whole query pushed down. */
+    reasons: MemoryExecutionReason[];
+    explanation: string;
+};
+export type QueryExplanation = {
+    collection: string;
+    database: string;
+    summary: QueryExplanationSummary;
+    executionSteps: ExecutionStep[];
+    plugin: {
+        kind: string;
+    };
+};
+export type ExplainContext = {
+    collection: string;
+    database: string;
+    pluginKind: string;
+};
+/**
+ * Builds the explanation from the resolved options, with no plugin involvement.
+ *
+ * Takes the collection BEFORE `split()`, and throws otherwise. Splitting re-adds each half
+ * into a fresh collection, which re-derives targets without the options that caused them — a
+ * post-join filter alone in the memory half derives back to `"database"`, and the document
+ * would report memory work as having run in the database.
+ */
+export declare const explainQuery: (options: QueryOptionsCollection<any>, context: ExplainContext) => QueryExplanation;
+/**
+ * Attaches what the backend reported to the step that was sent to it.
+ *
+ * Reporting is optional for a plugin, so an empty report is not an error: the step is marked
+ * `executedQueriesUnsupported` instead, and the rest of the explanation stands — the pushdown
+ * analysis comes from the options and is correct with or without the plugin's statements.
+ *
+ * Copies the steps rather than writing into them, so the explanation a caller already holds
+ * does not gain statements after the fact. Options and their details are shared with the
+ * original — nothing mutates them, and copying deeper would only look safer than it is.
+ */
+export declare const withExecutedQueries: (explanation: QueryExplanation, executedQueries: ExecutedQuery[]) => QueryExplanation;

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

@@ -0,0 +1,9 @@
+import { QueryExplanation } from "./explain";
+/**
+ * Renders an explanation for a terminal.
+ *
+ * The STEP headers carry the whole lesson: a reader who has never heard of pushdown still sees
+ * that the statement in step 1 is not the entire query. Nobody should have to notice a missing
+ * ORDER BY to work that out.
+ */
+export declare const formatExplanation: (explanation: QueryExplanation) => string;

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

@@ -1,3 +1,5 @@
+export * from './explain';
+export * from './formatExplanation';
 export * from './join';
 export * from './Query';
 export * from './QueryOptionsCollection';

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

@@ -19,10 +19,21 @@ export type QueryField = {
 };
 export type QueryOptionExecutionTarget = "database" | "memory";
 export type QueryOptionName = keyof QueryOptionValueMap<unknown>;
+/**
+ * Why an option runs in memory rather than in the database.
+ *
+ * A code rather than a sentence, so a test can assert on it — the sentences live in
+ * `MEMORY_EXECUTION_EXPLANATIONS`. Every cause is a ratchet, because `nextExecutionTarget`
+ * 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";
 export type QueryOption<T, K extends QueryOptionName> = {
     name: QueryOptionName;
     value: QueryOptionValueMap<T>[K];
     target: QueryOptionExecutionTarget;
+    /** Set only when `target` is `"memory"`. */
+    reason?: MemoryExecutionReason;
 };
 export type QueryOptionValueMap<T extends {}> = {
     skip: number;

package/dist/plugins/types.d.ts

@@ -1,4 +1,5 @@
 import { PluginEventCallbackPartialResult, PluginEventCallbackResult } from "../results";
+import { ExecutedQuery } from "./query/explain";
 import { QueryOptionsCollection } from "./query/QueryOptionsCollection";
 import { CompiledSchema, InferType } from '../schema';
 import { BulkPersistChanges, BulkPersistResult, SchemaCollection } from "../collections";
@@ -50,7 +51,48 @@ export interface IDbPlugin {
 /**
  * Event for a query operation, including schema, parent, and the query operation.
  */
-export type DbPluginQueryEvent<TRoot extends {}, TShape> = DbPluginOperationEvent<IQuery<TRoot, TShape>>;
+export type DbPluginQueryEvent<TRoot extends {}, TShape> = DbPluginOperationEvent<IQuery<TRoot, TShape>> & {
+    /**
+     * Whether the caller asked for an explanation. Required, never optional: a query is
+     * either explained or it is not, and "unset" is not a third state.
+     *
+     * A plugin is free to ignore it. One that reports unconditionally is correct; one that
+     * checks the flag to skip building report strings is also correct. What a plugin must
+     * NOT do is treat `true` as an instruction it has to obey — a plugin that cannot report
+     * simply doesn't, and the datastore marks the step as not reported.
+     */
+    explain: boolean;
+    /**
+     * Where a plugin reports what it executed. Pushing to it is how a plugin supports
+     * `.explain()` — a plugin that never pushes still answers queries, and its explanations
+     * mark the database step as not reported (`executedQueriesUnsupported`) instead of
+     * showing statements.
+     *
+     * The datastore decides whether anyone sees it: with `explain` on it reads the array and
+     * an empty one means "not supported"; with `explain` off it takes no action either way.
+     *
+     * An array the DATASTORE creates and the plugin pushes into, rather than a value the plugin
+     * returns. The result envelope is rebuilt in at least six places between a plugin and the
+     * caller — the memory half re-translates, joins build fresh tuple values, the cache
+     * reconstructs from stored entries — so anything carried on it is discarded before arrival.
+     * The event is not rebuilt, and an array survives the shallow spread in `ConcurrencyDbPlugin`
+     * because both sides then hold the same array. Assigning a new one would not.
+     *
+     * Push once per query actually executed, in execution order, so a join reports both reads.
+     * `text` is whatever the backend runs — SQL for a SQL engine, a description of the access
+     * path for a store that has no statement. A plugin that answered without touching its
+     * backend pushes a description of that instead — `CacheDbPlugin` pushes "cache hit" —
+     * because pushing nothing reads as "this plugin does not report".
+     *
+     * Push AFTER the query runs, not before. `RetryDbPlugin` re-invokes with the same event, so
+     * a plugin that pushes first reports an entry per failed attempt.
+     *
+     * The array accumulates for as long as the event lives. That is why `.explain()` is not
+     * offered on a subscribed queryable: `subscribeQuery` builds its event once and re-issues it
+     * on every change notification, which would grow this without bound.
+     */
+    executedQueries: ExecutedQuery[];
+};
 /**
  * Event for bulk operations, including schema, parent, and the entity changes.
  */

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

@@ -1,5 +1,6 @@
 import { SerializedExpression } from "../../expressions";
 import { JoinKind } from "../query/join";
+import { ExecutedQuery } from "../query/explain";
 import { QueryOrdering } from "../query/types";
 /**
  * The wire format for a whole Routier operation.
@@ -75,6 +76,12 @@ export type SerializedQueryRequest = {
     kind: "query";
     collectionName: string;
     options: SerializedQueryOption[];
+    /**
+     * Whether the caller wants the response to say what the server ran. Required — a query is
+     * either explained or it is not. A server whose plugin does not report answers `true` the
+     * same as `false`, and the caller's explanation marks the remote step as not reported.
+     */
+    explain: boolean;
 };
 /** One entity update, as `EntityUpdateInfo` minus nothing — every field of it is already JSON. */
 export type SerializedUpdate = {
@@ -101,10 +108,19 @@ export type SerializedDestroyRequest = {
 };
 export type SerializedRequest = SerializedQueryRequest | SerializedPersistRequest | SerializedDestroyRequest;
 /** What a receiver sends back. Errors are a value, not a transport status. */
-export type SerializedResponse = {
+export type SerializedResponse = 
+/**
+ * `executedQueries` carries what the SERVER's plugin ran, so `.explain()` on a client sees
+ * through the wire rather than reporting a blank. Optional on the response, unlike on a
+ * local event: a plugin that does not report has nothing to send, and the client's
+ * explanation then marks the remote step as not reported. There is no flag on either end —
+ * the wire forwards whatever the plugin pushed, or nothing.
+ */
+{
     ok: true;
     kind: "query";
     value: unknown;
+    executedQueries?: ExecutedQuery[];
 } | {
     ok: true;
     kind: "persist";

package/dist/utilities/index.cjs

@@ -150,8 +150,26 @@ __webpack_require__.d(__webpack_exports__, {
 class QueryOptionsCollection {
     options = new Map();
     nextExecutionTarget = "database";
+    nextExecutionReason = null;
     nextIndex = 0;
     enumeratedItems = [];
+    /** Cuts over to memory execution, keeping the first cause. See `MemoryExecutionReason`. */ cutOverToMemory(reason) {
+        this.nextExecutionTarget = "memory";
+        if (this.nextExecutionReason == null) {
+            this.nextExecutionReason = reason;
+        }
+    }
+    /**
+     * 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`.
+     */ derived = false;
+    get isDerived() {
+        return this.derived;
+    }
     get items() {
         return this.options;
     }
@@ -172,7 +190,7 @@ class QueryOptionsCollection {
             if (mapValue.fields.some((x)=>x.isRename === true) || mapValue.fields.some((x)=>x.property?.isUnmapped === true)) {
                 // Cut over to memory execution since we are renaming a property with .map
                 // We do not want to figure out how the new name flows through the entire query
-                this.nextExecutionTarget = "memory";
+                this.cutOverToMemory("map-rename");
             }
         }
         if (name === "filter") {
@@ -184,13 +202,13 @@ class QueryOptionsCollection {
                 return;
             }
             if (filterValue.expression.type === "not-parsable") {
-                this.nextExecutionTarget = "memory";
+                this.cutOverToMemory("not-parsable");
             } else {
                 (0,_expressions_utils__rspack_import_0/* .forEach */.j)(filterValue.expression, (expression)=>{
                     if ((0,_assertions__rspack_import_1.isPropertyExpression)(expression) && expression.property.isUnmapped) {
                         // Cut over to memory execution, unmapped properties are not in the database and
                         // cannot be queried
-                        this.nextExecutionTarget = "memory";
+                        this.cutOverToMemory("unmapped-property");
                         return false;
                     }
                     if ((0,_assertions__rspack_import_1.isPropertyExpression)(expression) && expression.property.hasRenamedSegments) {
@@ -198,7 +216,7 @@ class QueryOptionsCollection {
                         // `from` (storage) names, but filter selectors reference the
                         // in-memory names.  Memory execution runs after deserialization,
                         // where the in-memory names exist
-                        this.nextExecutionTarget = "memory";
+                        this.cutOverToMemory("renamed-property");
                         return false;
                     }
                     return true;
@@ -209,8 +227,10 @@ class QueryOptionsCollection {
             const sortValue = value;
             // Same rule as filters: sort selectors reference in-memory names, which
             // only exist after deserialization when the property is renamed or unmapped
-            if (sortValue.property != null && (sortValue.property.isUnmapped || sortValue.property.hasRenamedSegments)) {
-                this.nextExecutionTarget = "memory";
+            if (sortValue.property != null && sortValue.property.isUnmapped) {
+                this.cutOverToMemory("unmapped-property");
+            } else if (sortValue.property != null && sortValue.property.hasRenamedSegments) {
+                this.cutOverToMemory("renamed-property");
             }
         }
         if (name === "nearest") {
@@ -221,8 +241,10 @@ class QueryOptionsCollection {
             //
             // This is also what lets every translator's in-memory fallback read the column by
             // its resolved name — anything whose storage name differs never reaches them.
-            if (nearestValue.property != null && (nearestValue.property.isUnmapped || nearestValue.property.hasRenamedSegments)) {
-                this.nextExecutionTarget = "memory";
+            if (nearestValue.property != null && nearestValue.property.isUnmapped) {
+                this.cutOverToMemory("unmapped-property");
+            } else if (nearestValue.property != null && nearestValue.property.hasRenamedSegments) {
+                this.cutOverToMemory("renamed-property");
             }
         }
         if (name === "join") {
@@ -234,7 +256,7 @@ class QueryOptionsCollection {
             // Set BEFORE the item is created, unlike `nearest`'s ratchet below, because this
             // moves the join option itself rather than everything after it.
             if (joinValue.crossPlugin === true) {
-                this.nextExecutionTarget = "memory";
+                this.cutOverToMemory("cross-plugin-join");
             }
         }
         const item = {
@@ -242,7 +264,10 @@ class QueryOptionsCollection {
             option: {
                 name,
                 target: this.nextExecutionTarget,
-                value
+                value,
+                ...this.nextExecutionReason == null ? {} : {
+                    reason: this.nextExecutionReason
+                }
             }
         };
         this.nextIndex++;
@@ -265,7 +290,7 @@ class QueryOptionsCollection {
             //
             // A plugin that DID push the search down loses nothing but the chance to also
             // push down what follows it, which is a limit over ten rows.
-            this.nextExecutionTarget = "memory";
+            this.cutOverToMemory("after-nearest");
         }
         if (name === "join") {
             // Everything AFTER a join runs in memory, for the same reason as `nearest`: this
@@ -276,7 +301,7 @@ class QueryOptionsCollection {
             // OUTER rows read, not the pairs produced — a plausible-looking result with the
             // wrong number of rows in it. Conjuncts that can safely run earlier are split off
             // by the query builder BEFORE dispatch, which is the only exception.
-            this.nextExecutionTarget = "memory";
+            this.cutOverToMemory("after-join");
         }
     }
     /**
@@ -290,6 +315,8 @@ class QueryOptionsCollection {
         const sortedItems = this.enumeratedItems.toSorted((a, b)=>a.index - b.index);
         const before = new QueryOptionsCollection();
         const after = new QueryOptionsCollection();
+        before.derived = true;
+        after.derived = true;
         let at = null;
         for(let i = 0, length = sortedItems.length; i < length; i++){
             const { option } = sortedItems[i];
@@ -323,10 +350,12 @@ class QueryOptionsCollection {
                 ]
             ]));
         const nextExecutionTarget = this.nextExecutionTarget;
+        const nextExecutionReason = this.nextExecutionReason;
         const nextIndex = this.nextIndex;
         return ()=>{
             this.options = new Map(options);
             this.nextExecutionTarget = nextExecutionTarget;
+            this.nextExecutionReason = nextExecutionReason;
             this.nextIndex = nextIndex;
             this.enumeratedItems = [];
         };
@@ -336,6 +365,8 @@ class QueryOptionsCollection {
         const sortedItems = this.enumeratedItems.toSorted((a, b)=>a.index - b.index);
         const memoryQueryOptionsCollection = new QueryOptionsCollection();
         const databaseQueryOptionsCollection = new QueryOptionsCollection();
+        memoryQueryOptionsCollection.derived = true;
+        databaseQueryOptionsCollection.derived = true;
         for(let i = 0, length = sortedItems.length; i < length; i++){
             const sortedItem = sortedItems[i];
             if (sortedItem.option.target === "database") {