@routier/core 0.6.0 → 0.8.0

package/dist/utilities/index.cjs

@@ -3,7 +3,9 @@
 var __webpack_modules__ = ({
 126(__unused_rspack_module, __webpack_exports__, __webpack_require__) {
 __webpack_require__.d(__webpack_exports__, {
-  isPropertyExpression: () => (isPropertyExpression)
+  isComparatorExpression: () => (isComparatorExpression),
+  isPropertyExpression: () => (isPropertyExpression),
+  isValueExpression: () => (isValueExpression)
 });
 
 
@@ -75,6 +77,11 @@ function isObjectWithType(value) {
  */ function isValueExpression(value) {
     return isObjectWithType(value) && value.type === "value";
 }
+/**
+ * Type guard: narrows `value` to `CallExpression` when it is an object with `type === "call"`.
+ */ function isCallExpression(value) {
+    return isObjectWithType(value) && value.type === "call";
+}
 /**
  * Type guard: narrows `value` to `EmptyExpression` when it is an object with `type === "empty"`.
  */ function isEmptyExpression(value) {
@@ -90,8 +97,42 @@ function isObjectWithType(value) {
 },
 63(__unused_rspack_module, __webpack_exports__, __webpack_require__) {
 __webpack_require__.d(__webpack_exports__, {
-  j: () => (forEach)
+  jJ: () => (forEach)
 });
+/**
+ * Separates an operand from the calls applied to it.
+ *
+ * `null` when there is no operand beneath the calls. Every consumer needs this to decide whether a
+ * comparator side is a property or a value, so it lives here rather than in each translator.
+ */ function peelCalls(expression) {
+    const calls = [];
+    let current = expression;
+    while(current != null && current.type === "call"){
+        calls.unshift(current);
+        current = current.expression;
+    }
+    return current == null ? null : {
+        operand: current,
+        calls
+    };
+}
+function childrenOf(expression) {
+    if (expression.type === "call") {
+        const call = expression;
+        return [
+            call.expression,
+            ...call.arguments ?? []
+        ].filter((child)=>child != null);
+    }
+    const children = [];
+    if (expression.left != null) {
+        children.push(expression.left);
+    }
+    if (expression.right != null) {
+        children.push(expression.right);
+    }
+    return children;
+}
 /**
  * Extracts all properties referenced in an expression
  * @param expression The expression to analyze
@@ -103,12 +144,8 @@ __webpack_require__.d(__webpack_exports__, {
         if (expr.type === "property") {
             properties.push(expr.property);
         }
-        // Traverse left and right expressions if they exist
-        if (expr.left) {
-            traverse(expr.left);
-        }
-        if (expr.right) {
-            traverse(expr.right);
+        for (const child of childrenOf(expr)){
+            traverse(child);
         }
     }
     traverse(expression);
@@ -121,14 +158,8 @@ function forEach(expression, callback) {
         if (!callback(expr)) {
             return false;
         }
-        // Traverse left and right expressions if they exist
-        if (expr.left) {
-            if (!traverse(expr.left)) {
-                return false;
-            }
-        }
-        if (expr.right) {
-            if (!traverse(expr.right)) {
+        for (const child of childrenOf(expr)){
+            if (!traverse(child)) {
                 return false;
             }
         }
@@ -144,32 +175,86 @@ __webpack_require__.d(__webpack_exports__, {
   H: () => (QueryOptionsCollection)
 });
 /* import */ var _assertions__rspack_import_1 = __webpack_require__(126);
-/* import */ var _expressions_utils__rspack_import_0 = __webpack_require__(63);
+/* import */ var _expressions_utils__rspack_import_2 = __webpack_require__(63);
+/* import */ var _schema_types__rspack_import_0 = __webpack_require__(537);
+/* import */ var _utilities__rspack_import_3 = __webpack_require__(581);
+
+
 
 
+/** What a schema type is called in JavaScript, where one exists. A value of any other type cannot equal it. */ const JAVASCRIPT_TYPE_OF = {
+    [_schema_types__rspack_import_0/* .SchemaTypes.Number */.L.Number]: "number",
+    [_schema_types__rspack_import_0/* .SchemaTypes.String */.L.String]: "string",
+    [_schema_types__rspack_import_0/* .SchemaTypes.Boolean */.L.Boolean]: "boolean",
+    [_schema_types__rspack_import_0/* .SchemaTypes.Date */.L.Date]: "object"
+};
+const mismatchedSide = (property, value)=>{
+    if (property == null || value == null || !(0,_assertions__rspack_import_1.isPropertyExpression)(property) || !(0,_assertions__rspack_import_1.isValueExpression)(value)) {
+        return null;
+    }
+    const expected = JAVASCRIPT_TYPE_OF[property.property.type];
+    if (expected == null || value.value == null || typeof value.value === expected) {
+        return null;
+    }
+    return {
+        property,
+        value,
+        expected
+    };
+};
+/** A strict comparison whose answer is the same for every row, because the types cannot be equal. */ const comparesTypesThatCannotMatch = (expression)=>{
+    if (!(0,_assertions__rspack_import_1.isComparatorExpression)(expression) || expression.strict !== true) {
+        return false;
+    }
+    if (expression.comparator !== "equals") {
+        return false;
+    }
+    return mismatchedSide(expression.left, expression.right) != null || mismatchedSide(expression.right, expression.left) != null;
+};
+/** `JSON.stringify` throws on a BigInt, and this runs inside the guard that exists to catch one. */ const describeLiteral = (value)=>typeof value === "string" ? `"${value}"` : String(value);
+const mismatchWarning = (expression)=>{
+    const side = mismatchedSide(expression.left, expression.right) ?? mismatchedSide(expression.right, expression.left);
+    const outcome = expression.negated ? "every row matches" : "no row matches";
+    return `Routier: '${side.property.property.getAssignmentPath()}' is a ${side.expected}, and this filter ` + `compares it against ${describeLiteral(side.value.value)}, which is a ${typeof side.value.value}. ` + `A strict comparison between them is the same answer for every row, so ${outcome} and the filter ` + `runs in memory. https://routier.dev/guides/strict-comparison-types`;
+};
+/**
+ * An item as one dispatch receives it: a new object, so a report written on it stays with that dispatch.
+ *
+ * A database option starts `executed` again, because a report is only an answer from the plugin that
+ * made it. A memory option keeps the reason core planned it with. A join's inner options are copied the
+ * same way, since a plugin can report on them too.
+ */ const toDispatchItem = (item)=>{
+    const option = item.option;
+    const value = option.name === "join" ? {
+        ...option.value,
+        innerOptions: option.value.innerOptions.forDispatch()
+    } : option.value;
+    return {
+        index: item.index,
+        option: option.target === "database" ? {
+            ...option,
+            value,
+            reason: "executed"
+        } : {
+            ...option,
+            value
+        }
+    };
+};
 class QueryOptionsCollection {
     options = new Map();
     nextExecutionTarget = "database";
     nextExecutionReason = null;
     nextIndex = 0;
     enumeratedItems = [];
+    dirty = true;
+    /** The collection a `splitAt`/`split` half came from. A capability report belongs to it. */ origin = null;
     /** 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;
     }
@@ -194,7 +279,7 @@ class QueryOptionsCollection {
             }
         }
         if (name === "filter") {
-            // Need to check for unmapped and renamed properties
+            // Need to check for unmapped properties
             const filterValue = value;
             // A tautology (`x => true`) filters nothing — skip it entirely so
             // plugins never see it
@@ -204,19 +289,20 @@ class QueryOptionsCollection {
             if (filterValue.expression.type === "not-parsable") {
                 this.cutOverToMemory("not-parsable");
             } else {
-                (0,_expressions_utils__rspack_import_0/* .forEach */.j)(filterValue.expression, (expression)=>{
+                (0,_expressions_utils__rspack_import_2/* .forEach */.jJ)(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.cutOverToMemory("unmapped-property");
                         return false;
                     }
-                    if ((0,_assertions__rspack_import_1.isPropertyExpression)(expression) && expression.property.hasRenamedSegments) {
-                        // Cut over to memory execution: the plugin stores data under the
-                        // `from` (storage) names, but filter selectors reference the
-                        // in-memory names.  Memory execution runs after deserialization,
-                        // where the in-memory names exist
-                        this.cutOverToMemory("renamed-property");
+                    // A renamed property stays with the database. Whether the backend can read a
+                    // `from` name is the plugin's to know, not this collection's: the property
+                    // travels with the option, and a plugin that cannot resolve it reports it
+                    // back — see `reportRenamedProperties`
+                    if (comparesTypesThatCannotMatch(expression)) {
+                        _utilities__rspack_import_3/* .logger.warn */.vF.warn(mismatchWarning(expression));
+                        this.cutOverToMemory("predicate-error");
                         return false;
                     }
                     return true;
@@ -225,28 +311,26 @@ class QueryOptionsCollection {
         }
         if (name === "sort") {
             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
+            // Same rule as filters: an unmapped property only exists after deserialization. A
+            // renamed one stays with the database, for the plugin to resolve or report
             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") {
             const nearestValue = value;
-            // Same rule as sort, and for the same reason: the plugin stores the vector under
-            // the `from` name, and an unmapped property is not stored at all. Both are only
-            // readable after deserialization, which is where memory execution runs.
-            //
-            // 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.
+            // Same rule as sort, and for the same reason: an unmapped property is not stored at
+            // all, so it is only readable after deserialization, which is where memory execution
+            // runs. A vector stored under a `from` name is the plugin's to resolve or report.
             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 === "filter" || name === "sort") && (this.options.has("skip") || this.options.has("take"))) {
+            // SQL emits WHERE before LIMIT and Mongo's find() filters before skipping, so an option
+            // written after a window can only see the windowed rows if it runs after it.
+            this.cutOverToMemory("after-window");
+        }
         if (name === "join") {
             const joinValue = value;
             // A join whose two sides live on different plugins cannot be sent to EITHER of
@@ -259,18 +343,24 @@ class QueryOptionsCollection {
                 this.cutOverToMemory("cross-plugin-join");
             }
         }
+        // `executed` is the plan, not a record: nothing has run when an option is added. Every
+        // consumer reads it after the plugin returned, so the optimistic window is never observed.
         const item = {
             index: this.nextIndex,
-            option: {
+            option: this.nextExecutionTarget === "database" ? {
                 name,
-                target: this.nextExecutionTarget,
                 value,
-                ...this.nextExecutionReason == null ? {} : {
-                    reason: this.nextExecutionReason
-                }
+                target: "database",
+                reason: "executed"
+            } : {
+                name,
+                value,
+                target: "memory",
+                reason: this.nextExecutionReason ?? "not-parsable"
             }
         };
         this.nextIndex++;
+        this.dirty = true;
         const found = this.options.get(name);
         this.options.set(name, [
             ...found ?? [],
@@ -315,8 +405,6 @@ 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];
@@ -325,8 +413,10 @@ class QueryOptionsCollection {
                 continue;
             }
             const destination = at == null ? before : after;
-            destination.add(option.name, option.value);
+            destination.adopt(sortedItems[i]);
         }
+        before.origin = this.origin ?? this;
+        after.origin = this.origin ?? this;
         return {
             before,
             at,
@@ -340,6 +430,9 @@ class QueryOptionsCollection {
      * 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() {
         const options = new Map([
             ...this.options.entries()
@@ -358,23 +451,128 @@ class QueryOptionsCollection {
             this.nextExecutionReason = nextExecutionReason;
             this.nextIndex = nextIndex;
             this.enumeratedItems = [];
+            // Clearing the list is not enough now that staleness is a flag rather than a count:
+            // without this, `resolveEnumeration` believes the empty list is current and every read
+            // of the collection sees no options at all.
+            this.dirty = true;
+        };
+    }
+    /** Takes an item as it stands — same object, same index, same target and reason. */ adopt(item) {
+        const found = this.options.get(item.option.name);
+        this.options.set(item.option.name, [
+            ...found ?? [],
+            item
+        ]);
+        this.nextIndex = Math.max(this.nextIndex, item.index + 1);
+        this.dirty = true;
+    }
+    /**
+     * 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) {
+        this.report(item, "missing-capability");
+    }
+    /**
+     * 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) {
+        this.report(item, "engine-divergence");
+    }
+    report(item, reason) {
+        // A half can only see its own slice, and the database has to stop for the whole dispatch.
+        if (this.origin != null) {
+            this.origin.report(item, reason);
+            return;
+        }
+        this.resolveEnumeration();
+        for (const candidate of this.enumeratedItems){
+            if (candidate.option.target !== "database" || candidate.index < item.index) {
+                continue;
+            }
+            if (candidate.index === item.index) {
+                candidate.option.reason = reason;
+                continue;
+            }
+            if (candidate.option.reason === "executed") {
+                candidate.option.reason = "not-reached";
+            }
+        }
+    }
+    /**
+     * 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() {
+        if (this.origin == null) {
+            return this.copyForDispatch().copy;
+        }
+        const { copy: root, copies } = this.origin.copyForDispatch();
+        const half = new QueryOptionsCollection();
+        this.resolveEnumeration();
+        for (const item of this.enumeratedItems){
+            // An item added to the half after it was split has no counterpart in the origin
+            half.adopt(copies.get(item) ?? toDispatchItem(item));
+        }
+        half.origin = root;
+        return half;
+    }
+    copyForDispatch() {
+        const copy = new QueryOptionsCollection();
+        const copies = new Map();
+        this.resolveEnumeration();
+        for (const item of this.enumeratedItems){
+            const copied = toDispatchItem(item);
+            copies.set(item, copied);
+            copy.adopt(copied);
+        }
+        copy.nextExecutionTarget = this.nextExecutionTarget;
+        copy.nextExecutionReason = this.nextExecutionReason;
+        copy.nextIndex = this.nextIndex;
+        return {
+            copy,
+            copies
         };
     }
+    /** The options the database did not run, in the order they were written. */ notExecuted() {
+        this.resolveEnumeration();
+        return this.enumeratedItems.filter((item)=>item.option.target === "database" && item.option.reason !== "executed").toSorted((a, b)=>a.index - b.index);
+    }
     split() {
         this.resolveEnumeration();
         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") {
-                databaseQueryOptionsCollection.add(sortedItem.option.name, sortedItem.option.value);
-                continue;
-            }
-            memoryQueryOptionsCollection.add(sortedItem.option.name, sortedItem.option.value);
+            const half = sortedItem.option.target === "database" ? databaseQueryOptionsCollection : memoryQueryOptionsCollection;
+            // The ITEM, not its name and value. Re-adding would re-derive target and reason from a
+            // fresh cascade, and a memory option re-added alone comes back out as `database` with no
+            // reason at all. Sharing it also means a plugin's report on the database half is the
+            // same object the explanation reads.
+            half.adopt(sortedItem);
         }
+        memoryQueryOptionsCollection.origin = this.origin ?? this;
+        databaseQueryOptionsCollection.origin = this.origin ?? this;
         return {
             memory: memoryQueryOptionsCollection,
             database: databaseQueryOptionsCollection
@@ -420,8 +618,11 @@ class QueryOptionsCollection {
         ].flat().toSorted((a, b)=>a.index - b.index);
     }
     resolveEnumeration() {
-        if (this.enumeratedItems.length != this.nextIndex) {
+        // A flag, not a count: adopting leaves gaps in the indexes, so `length !== nextIndex` is
+        // true forever on a half and the enumeration rebuilds on every read.
+        if (this.dirty === true) {
             this.enumeratedItems = this.getEnumeration();
+            this.dirty = false;
         }
     }
     forEach(iterator) {
@@ -433,6 +634,41 @@ class QueryOptionsCollection {
 }
 
 
+},
+537(__unused_rspack_module, __webpack_exports__, __webpack_require__) {
+__webpack_require__.d(__webpack_exports__, {
+  L: () => (SchemaTypes)
+});
+var SchemaTypes = /*#__PURE__*/ function(SchemaTypes) {
+    SchemaTypes["Array"] = "Array";
+    SchemaTypes["Boolean"] = "Boolean";
+    SchemaTypes["Date"] = "Date";
+    SchemaTypes["Number"] = "Number";
+    SchemaTypes["Object"] = "Object";
+    SchemaTypes["String"] = "String";
+    SchemaTypes["Definition"] = "Definition";
+    SchemaTypes["Function"] = "Function";
+    SchemaTypes["Computed"] = "Computed";
+    /**
+     * Content in, reference out. The only type whose write shape differs from its stored
+     * shape, and a leaf on purpose — see `SchemaFile`.
+     */ SchemaTypes["File"] = "File";
+    /**
+     * A fixed-length list of numbers, carrying its dimension count — see `SchemaVector`.
+     *
+     * Value-shaped exactly like `s.array(s.number())`, which is why every array codegen
+     * handler accepts it. It is a distinct type only so a backend can recognise it and store
+     * it natively; nothing else needs to tell the two apart.
+     */ SchemaTypes["Vector"] = "Vector";
+    return SchemaTypes;
+}({});
+var HashType = /*#__PURE__*/ (/* unused pure expression or super */ null && (function(HashType) {
+    HashType["Ids"] = "Ids";
+    HashType["Object"] = "Object";
+    return HashType;
+}({})));
+
+
 },
 76(__unused_rspack_module, __webpack_exports__, __webpack_require__) {
 __webpack_require__.d(__webpack_exports__, {
@@ -529,12 +765,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];