@routier/core 0.5.0 → 0.7.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,62 @@ __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`;
+};
 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;
     }
@@ -204,7 +265,7 @@ 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
@@ -219,6 +280,11 @@ class QueryOptionsCollection {
                         this.cutOverToMemory("renamed-property");
                         return false;
                     }
+                    if (comparesTypesThatCannotMatch(expression)) {
+                        _utilities__rspack_import_3/* .logger.warn */.vF.warn(mismatchWarning(expression));
+                        this.cutOverToMemory("predicate-error");
+                        return false;
+                    }
                     return true;
                 });
             }
@@ -247,6 +313,11 @@ class QueryOptionsCollection {
                 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 +330,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,
+                value,
+                target: "database",
+                reason: "executed"
+            } : {
                 name,
-                target: this.nextExecutionTarget,
                 value,
-                ...this.nextExecutionReason == null ? {} : {
-                    reason: this.nextExecutionReason
-                }
+                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 +392,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 +400,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,
@@ -358,23 +435,99 @@ 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";
+            }
+        }
+    }
+    /**
+     * 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() {
+        this.resolveEnumeration();
+        for (const item of this.enumeratedItems){
+            if (item.option.target === "database") {
+                item.option.reason = "executed";
+            }
+        }
+    }
+    /** 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 +573,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 +589,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 +720,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];