mongo-query-normalizer 0.1.0

package/dist/core/simplify.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.simplify = simplify;
+const builders_1 = require("../ast/builders");
+const guards_1 = require("../ast/guards");
+const constraint_propagation_1 = require("./constraint-propagation");
+/**
+ * simplify（AST → AST）编排：
+ *
+ * 1. **约束传播**（`constraint-propagation`）：`$and` 内 sibling context、父级与子级 FieldNode 的
+ *    冲突剪枝与 tighten；tighten 仅作用于 `conditions.ts` 中声明的支持操作符，其余条件原样保留，
+ *    不改变 Mongo 语义。
+ * 2. **逻辑化简**：true/false 传播、AND 吸收 true、OR 吸收 false、AND flatten、$nor 结构化简。
+ */
+function simplify(ast) {
+    const context = new Map();
+    return simplifyNode(ast, context);
+}
+function simplifyNode(node, context) {
+    if ((0, guards_1.isTrueNode)(node) || (0, guards_1.isFalseNode)(node)) {
+        return node;
+    }
+    if ((0, guards_1.isFieldNode)(node)) {
+        return (0, constraint_propagation_1.simplifyFieldAgainstContext)(node, context);
+    }
+    if ((0, guards_1.isLogicalNode)(node)) {
+        switch (node.op) {
+            case "$and":
+                return simplifyAnd(node, context);
+            case "$or":
+                return simplifyOr(node, context);
+            case "$nor":
+                return simplifyNor(node, context);
+        }
+    }
+    return node;
+}
+function simplifyAnd(node, context) {
+    const layerAll = (0, constraint_propagation_1.collectAndLayerFieldConditions)(node);
+    const resultChildren = [];
+    for (const child of node.children) {
+        const childContext = (0, guards_1.isFieldNode)(child)
+            ? (0, constraint_propagation_1.buildSiblingContext)(context, layerAll, child)
+            : (0, constraint_propagation_1.buildLayerContext)(context, layerAll);
+        const simplified = simplifyNode(child, childContext);
+        if ((0, guards_1.isFalseNode)(simplified)) {
+            return builders_1.ASTNodeBuilder.falseNode();
+        }
+        if ((0, guards_1.isTrueNode)(simplified)) {
+            continue;
+        }
+        if ((0, guards_1.isFieldNode)(simplified)) {
+            resultChildren.push(simplified);
+            continue;
+        }
+        if ((0, guards_1.isLogicalNode)(simplified) && simplified.op === "$and") {
+            resultChildren.push(...simplified.children);
+            continue;
+        }
+        resultChildren.push(simplified);
+    }
+    if (resultChildren.length === 0) {
+        return builders_1.ASTNodeBuilder.trueNode();
+    }
+    if (resultChildren.length === 1) {
+        return resultChildren[0];
+    }
+    return builders_1.ASTNodeBuilder.logical("$and", resultChildren);
+}
+function simplifyOr(node, context) {
+    const resultChildren = [];
+    for (const child of node.children) {
+        const simplified = simplifyNode(child, context);
+        if ((0, guards_1.isTrueNode)(simplified)) {
+            return builders_1.ASTNodeBuilder.trueNode();
+        }
+        if ((0, guards_1.isFalseNode)(simplified)) {
+            continue;
+        }
+        resultChildren.push(simplified);
+    }
+    if (resultChildren.length === 0) {
+        return builders_1.ASTNodeBuilder.falseNode();
+    }
+    if (resultChildren.length === 1) {
+        return resultChildren[0];
+    }
+    return builders_1.ASTNodeBuilder.logical("$or", resultChildren);
+}
+/**
+ * $nor 子句：空 context 做结构化简，父 context 判断是否可剪枝；恒 true 子句使 NOR 为 false。
+ */
+function simplifyNorChildrenWithContext(children, context) {
+    const kept = [];
+    const emptyContext = new Map();
+    for (const child of children) {
+        const childNoCtx = simplifyNode(child, emptyContext);
+        if ((0, guards_1.isFalseNode)(childNoCtx)) {
+            continue;
+        }
+        const childWithCtx = simplifyNode(child, context);
+        if ((0, guards_1.isFalseNode)(childWithCtx)) {
+            continue;
+        }
+        // 子句在外层 $and 上下文中可化简（如与 sibling 字段矛盾）时必须保留化简结果，不能推入
+        // childNoCtx；否则首轮输出仍含冗余支，再 parse 后 sibling 顺序/合并变化会导致二轮多剪一枝，破坏幂等。
+        if ((0, guards_1.isTrueNode)(childNoCtx) || (0, guards_1.isTrueNode)(childWithCtx)) {
+            return { kept: [], hasAlwaysTrue: true };
+        }
+        kept.push(childWithCtx);
+    }
+    return { kept, hasAlwaysTrue: false };
+}
+function simplifyNor(node, context) {
+    const { kept, hasAlwaysTrue } = simplifyNorChildrenWithContext(node.children, context);
+    if (hasAlwaysTrue) {
+        return builders_1.ASTNodeBuilder.falseNode();
+    }
+    if (kept.length === 0) {
+        return builders_1.ASTNodeBuilder.trueNode();
+    }
+    if (kept.length === 1) {
+        return builders_1.ASTNodeBuilder.logical("$nor", [kept[0]]);
+    }
+    // 扁平 $nor 子句列表（与 $nor:[{$or:[...]}] 语义等价）；标准形采用扁平形以利于一步幂等
+    return builders_1.ASTNodeBuilder.logical("$nor", kept);
+}
+//# sourceMappingURL=simplify.js.map

package/dist/core/simplify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"simplify.js","sourceRoot":"","sources":["../../src/core/simplify.ts"],"names":[],"mappings":"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"}

package/dist/core/stable-structural-key.d.ts

@@ -0,0 +1,7 @@
+import type { SelectorAST } from "../ast/types";
+/**
+ * 为 canonical form 下的子节点排序生成稳定、无语义含义的字符串键（仅用于 $or / $nor 子句重排）。
+ * 不用于语义比较；同一 AST 结构应产生同一键。
+ */
+export declare function stableStructuralSortKey(node: SelectorAST): string;
+//# sourceMappingURL=stable-structural-key.d.ts.map

package/dist/core/stable-structural-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-structural-key.d.ts","sourceRoot":"","sources":["../../src/core/stable-structural-key.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhE;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAejE"}

package/dist/core/stable-structural-key.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stableStructuralSortKey = stableStructuralSortKey;
+/**
+ * 为 canonical form 下的子节点排序生成稳定、无语义含义的字符串键（仅用于 $or / $nor 子句重排）。
+ * 不用于语义比较；同一 AST 结构应产生同一键。
+ */
+function stableStructuralSortKey(node) {
+    switch (node.type) {
+        case "true":
+            return "0:true";
+        case "false":
+            return "1:false";
+        case "field":
+            return `2:field:${node.field}:${stableFieldConditionsKey(node.conditions)}`;
+        case "logical": {
+            const childKeys = node.children.map(stableStructuralSortKey).sort();
+            return `3:log:${node.op}(${childKeys.join("\u001f")})`;
+        }
+        default:
+            return "9:unknown";
+    }
+}
+function stableFieldConditionsKey(conditions) {
+    const parts = conditions.map((c) => {
+        const v = serializeValueForSort(c.value);
+        return `${c.op}\u0000${v}`;
+    });
+    parts.sort();
+    return parts.join("\u001f");
+}
+function serializeValueForSort(value) {
+    if (value === undefined) {
+        return "u";
+    }
+    if (value === null) {
+        return "n:null";
+    }
+    if (typeof value === "number") {
+        if (Object.is(value, -0)) {
+            return "num:-0";
+        }
+        if (!Number.isFinite(value)) {
+            return `num:${String(value)}`;
+        }
+        return `num:${value}`;
+    }
+    if (typeof value === "boolean") {
+        return `bool:${value}`;
+    }
+    if (typeof value === "string") {
+        return `str:${JSON.stringify(value)}`;
+    }
+    if (value instanceof Date) {
+        return `date:${value.toISOString()}`;
+    }
+    if (value instanceof RegExp) {
+        return `re:${value.source}\u0000${value.flags}`;
+    }
+    if (Array.isArray(value)) {
+        return `arr:[${value.map(serializeValueForSort).join("\u001f")}]`;
+    }
+    if (typeof value === "object") {
+        const o = value;
+        const keys = Object.keys(o).sort();
+        const inner = keys.map((k) => `${JSON.stringify(k)}:${serializeValueForSort(o[k])}`).join("\u001f");
+        return `obj:{${inner}}`;
+    }
+    return `x:${String(value)}`;
+}
+//# sourceMappingURL=stable-structural-key.js.map

package/dist/core/stable-structural-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-structural-key.js","sourceRoot":"","sources":["../../src/core/stable-structural-key.ts"],"names":[],"mappings":"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"}

package/dist/core/utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 深度比较两个值是否相等（含 Date、ObjectId-like、数组、对象），用于去重与交集等。
+ *
+ * @param left - 任意值
+ * @param right - 任意值
+ * @returns 是否相等
+ */
+export declare function areValuesEqual(left: unknown, right: unknown): boolean;
+/**
+ * 数组去重（使用 areValuesEqual 比较）。
+ *
+ * @param items - 待去重数组
+ * @returns 去重后的新数组
+ */
+export declare function deduplicateByValue<T>(items: T[]): T[];
+//# sourceMappingURL=utils.d.ts.map

package/dist/core/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/core/utils.ts"],"names":[],"mappings":"AAwCA;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CA2DrE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAQrD"}

package/dist/core/utils.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.areValuesEqual = areValuesEqual;
+exports.deduplicateByValue = deduplicateByValue;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isObjectIdLike(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const obj = value;
+    return obj._bsontype === "ObjectId" || typeof obj.toHexString === "function" || typeof obj.equals === "function";
+}
+function isEjsonObjectId(value) {
+    if (!isPlainObject(value)) {
+        return false;
+    }
+    return Object.keys(value).length === 1 && typeof value["$oid"] === "string";
+}
+function objectIdHex(value) {
+    if (isEjsonObjectId(value)) {
+        return value.$oid.toLowerCase();
+    }
+    if (isObjectIdLike(value) && typeof value.toHexString === "function") {
+        return value.toHexString().toLowerCase();
+    }
+    if (typeof value === "string" && /^[0-9a-f]{24}$/i.test(value)) {
+        return value.toLowerCase();
+    }
+    return undefined;
+}
+/**
+ * 深度比较两个值是否相等（含 Date、ObjectId-like、数组、对象），用于去重与交集等。
+ *
+ * @param left - 任意值
+ * @param right - 任意值
+ * @returns 是否相等
+ */
+function areValuesEqual(left, right) {
+    if (left === right) {
+        return true;
+    }
+    if (left instanceof Date && right instanceof Date) {
+        return left.getTime() === right.getTime();
+    }
+    const leftHex = objectIdHex(left);
+    const rightHex = objectIdHex(right);
+    if (leftHex !== undefined && rightHex !== undefined) {
+        return leftHex === rightHex;
+    }
+    if (isObjectIdLike(left) && isObjectIdLike(right)) {
+        if (typeof left.equals === "function") {
+            return left.equals(right);
+        }
+        if (typeof right.equals === "function") {
+            return right.equals(left);
+        }
+        if (typeof left.toHexString === "function" && typeof right.toHexString === "function") {
+            return left.toHexString() === right.toHexString();
+        }
+        return false;
+    }
+    if (Array.isArray(left) && Array.isArray(right)) {
+        if (left.length !== right.length) {
+            return false;
+        }
+        for (let i = 0; i < left.length; i += 1) {
+            if (!areValuesEqual(left[i], right[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    if (typeof left === "object" && left !== null && typeof right === "object" && right !== null) {
+        const leftKeys = Object.keys(left).sort();
+        const rightKeys = Object.keys(right).sort();
+        if (leftKeys.length !== rightKeys.length) {
+            return false;
+        }
+        for (let i = 0; i < leftKeys.length; i += 1) {
+            if (leftKeys[i] !== rightKeys[i]) {
+                return false;
+            }
+            const key = leftKeys[i];
+            if (!areValuesEqual(left[key], right[key])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    return false;
+}
+/**
+ * 数组去重（使用 areValuesEqual 比较）。
+ *
+ * @param items - 待去重数组
+ * @returns 去重后的新数组
+ */
+function deduplicateByValue(items) {
+    const result = [];
+    for (const item of items) {
+        if (!result.some((x) => areValuesEqual(x, item))) {
+            result.push(item);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=utils.js.map

package/dist/core/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/core/utils.ts"],"names":[],"mappings":"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"}

package/dist/flatten/flatten.d.ts

@@ -0,0 +1,43 @@
+import type { Selector, IndexSpec } from "../common/types.js";
+/**
+ * 阶段二：打平嵌套层级（结合律），并可选按集合索引排列条件以提升索引利用率。
+ *
+ * @param selector - 已修减的选择器（通常为 simplifySelector 的输出）
+ * @param indexSpecs - 可选，当前集合的索引列表；传入时会对 $and 等按索引键顺序排序
+ * @returns 打平后的选择器，语义不变
+ */
+export declare function normalizeSelector(selector: Selector, indexSpecs?: IndexSpec[]): Selector;
+/**
+ * 对 $and 子句数组应用结合律：展平嵌套的 $and，单子节点时提升为根。
+ * 不改变语义，仅简化结构。
+ *
+ * @param andClauses - $and 子句数组（每项已递归展平）
+ * @param siblingFields - 与 $and 同层的其它字段条件（非逻辑运算符部分）
+ * @returns 合并后的选择器
+ */
+export declare function flattenAndClauses(andClauses: Selector[], siblingFields: Record<string, unknown>): Selector;
+/**
+ * 对 $or 子句数组应用结合律：展平嵌套的 $or，单子节点时提升为根。
+ *
+ * @param orClauses - $or 子句数组（每项已递归展平）
+ * @param siblingFields - 与 $or 同层的其它字段条件
+ * @returns 合并后的选择器
+ */
+export declare function flattenOrClauses(orClauses: Selector[], siblingFields: Record<string, unknown>): Selector;
+/**
+ * 对 $nor 子句数组应用结合律：展平嵌套的 $nor。不做「单子节点提升」以免丢失否定语义。
+ *
+ * @param norClauses - $nor 子句数组（每项已递归展平）
+ * @param siblingFields - 与 $nor 同层的其它字段条件
+ * @returns 合并后的选择器
+ */
+export declare function flattenNorClauses(norClauses: Selector[], siblingFields: Record<string, unknown>): Selector;
+/**
+ * 按给定索引的键顺序排列条件（如 $and 中的字段顺序），使生成的选择器更贴近索引，利于 planner 选择。
+ *
+ * @param conditions - 扁平条件列表（如 AtomicCondition[] 或字段名列表）
+ * @param indexSpec - 可选，用于排序的索引；未传则保持原序
+ * @returns 按索引键顺序排列后的条件
+ */
+export declare function sortConditionsByIndexKeys<T>(conditions: T[], indexSpec?: IndexSpec): T[];
+//# sourceMappingURL=flatten.d.ts.map

package/dist/flatten/flatten.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../../src/flatten/flatten.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,EAClB,UAAU,CAAC,EAAE,SAAS,EAAE,GACvB,QAAQ,CAIV;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,QAAQ,EAAE,EACtB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,QAAQ,CAIV;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,QAAQ,EAAE,EACrB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,QAAQ,CAIV;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,QAAQ,EAAE,EACtB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,QAAQ,CAIV;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EACzC,UAAU,EAAE,CAAC,EAAE,EACf,SAAS,CAAC,EAAE,SAAS,GACpB,CAAC,EAAE,CAGL"}

package/dist/flatten/flatten.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeSelector = normalizeSelector;
+exports.flattenAndClauses = flattenAndClauses;
+exports.flattenOrClauses = flattenOrClauses;
+exports.flattenNorClauses = flattenNorClauses;
+exports.sortConditionsByIndexKeys = sortConditionsByIndexKeys;
+/**
+ * 阶段二：打平嵌套层级（结合律），并可选按集合索引排列条件以提升索引利用率。
+ *
+ * @param selector - 已修减的选择器（通常为 simplifySelector 的输出）
+ * @param indexSpecs - 可选，当前集合的索引列表；传入时会对 $and 等按索引键顺序排序
+ * @returns 打平后的选择器，语义不变
+ */
+function normalizeSelector(selector, indexSpecs) {
+    void indexSpecs;
+    // TODO: 递归应用 flattenAndClauses / flattenOrClauses / flattenNorClauses，再按 indexSpecs 排序
+    return selector;
+}
+/**
+ * 对 $and 子句数组应用结合律：展平嵌套的 $and，单子节点时提升为根。
+ * 不改变语义，仅简化结构。
+ *
+ * @param andClauses - $and 子句数组（每项已递归展平）
+ * @param siblingFields - 与 $and 同层的其它字段条件（非逻辑运算符部分）
+ * @returns 合并后的选择器
+ */
+function flattenAndClauses(andClauses, siblingFields) {
+    void andClauses;
+    void siblingFields;
+    return {};
+}
+/**
+ * 对 $or 子句数组应用结合律：展平嵌套的 $or，单子节点时提升为根。
+ *
+ * @param orClauses - $or 子句数组（每项已递归展平）
+ * @param siblingFields - 与 $or 同层的其它字段条件
+ * @returns 合并后的选择器
+ */
+function flattenOrClauses(orClauses, siblingFields) {
+    void orClauses;
+    void siblingFields;
+    return {};
+}
+/**
+ * 对 $nor 子句数组应用结合律：展平嵌套的 $nor。不做「单子节点提升」以免丢失否定语义。
+ *
+ * @param norClauses - $nor 子句数组（每项已递归展平）
+ * @param siblingFields - 与 $nor 同层的其它字段条件
+ * @returns 合并后的选择器
+ */
+function flattenNorClauses(norClauses, siblingFields) {
+    void norClauses;
+    void siblingFields;
+    return {};
+}
+/**
+ * 按给定索引的键顺序排列条件（如 $and 中的字段顺序），使生成的选择器更贴近索引，利于 planner 选择。
+ *
+ * @param conditions - 扁平条件列表（如 AtomicCondition[] 或字段名列表）
+ * @param indexSpec - 可选，用于排序的索引；未传则保持原序
+ * @returns 按索引键顺序排列后的条件
+ */
+function sortConditionsByIndexKeys(conditions, indexSpec) {
+    void indexSpec;
+    return conditions;
+}
+//# sourceMappingURL=flatten.js.map

package/dist/flatten/flatten.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flatten.js","sourceRoot":"","sources":["../../src/flatten/flatten.ts"],"names":[],"mappings":";;AASA,8CAOC;AAUD,8CAOC;AASD,4CAOC;AASD,8CAOC;AASD,8DAMC;AA9ED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAC/B,QAAkB,EAClB,UAAwB;IAExB,KAAK,UAAU,CAAC;IAChB,uFAAuF;IACvF,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,iBAAiB,CAC/B,UAAsB,EACtB,aAAsC;IAEtC,KAAK,UAAU,CAAC;IAChB,KAAK,aAAa,CAAC;IACnB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAC9B,SAAqB,EACrB,aAAsC;IAEtC,KAAK,SAAS,CAAC;IACf,KAAK,aAAa,CAAC;IACnB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAC/B,UAAsB,EACtB,aAAsC;IAEtC,KAAK,UAAU,CAAC;IAChB,KAAK,aAAa,CAAC;IACnB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,yBAAyB,CACvC,UAAe,EACf,SAAqB;IAErB,KAAK,SAAS,CAAC;IACf,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/flatten/index.d.ts

@@ -0,0 +1,2 @@
+export { normalizeSelector, flattenAndClauses, flattenOrClauses, flattenNorClauses, sortConditionsByIndexKeys, } from "./flatten.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/flatten/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/flatten/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,cAAc,CAAC"}

package/dist/flatten/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sortConditionsByIndexKeys = exports.flattenNorClauses = exports.flattenOrClauses = exports.flattenAndClauses = exports.normalizeSelector = void 0;
+var flatten_js_1 = require("./flatten.js");
+Object.defineProperty(exports, "normalizeSelector", { enumerable: true, get: function () { return flatten_js_1.normalizeSelector; } });
+Object.defineProperty(exports, "flattenAndClauses", { enumerable: true, get: function () { return flatten_js_1.flattenAndClauses; } });
+Object.defineProperty(exports, "flattenOrClauses", { enumerable: true, get: function () { return flatten_js_1.flattenOrClauses; } });
+Object.defineProperty(exports, "flattenNorClauses", { enumerable: true, get: function () { return flatten_js_1.flattenNorClauses; } });
+Object.defineProperty(exports, "sortConditionsByIndexKeys", { enumerable: true, get: function () { return flatten_js_1.sortConditionsByIndexKeys; } });
+//# sourceMappingURL=index.js.map

package/dist/flatten/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/flatten/index.ts"],"names":[],"mappings":";;;AAAA,2CAMsB;AALpB,+GAAA,iBAAiB,OAAA;AACjB,+GAAA,iBAAiB,OAAA;AACjB,8GAAA,gBAAgB,OAAA;AAChB,+GAAA,iBAAiB,OAAA;AACjB,uHAAA,yBAAyB,OAAA"}

package/dist/flatten.d.ts

@@ -0,0 +1,43 @@
+import type { FilterQuery, IndexSpec } from "./types";
+/**
+ * 阶段二：打平嵌套层级（结合律），并可选按集合索引排列条件以提升索引利用率。
+ *
+ * @param query - 已修减的查询（通常为 pruneSelector 的输出）
+ * @param indexSpecs - 可选，当前集合的索引列表；传入时会对 $and 等按索引键顺序排序
+ * @returns 打平后的查询，语义不变
+ */
+export declare function flattenSelector(query: FilterQuery, indexSpecs?: IndexSpec[]): FilterQuery;
+/**
+ * 对 $and 数组应用结合律：展平嵌套的 $and，单子节点时提升为根。
+ * 不改变语义，仅简化结构。
+ *
+ * @param andClauses - $and 子句数组（每项已递归 flatten）
+ * @param baseSelector - 与 $and 同层的其它字段条件
+ * @returns 合并后的 selector
+ */
+export declare function reduceAnd(andClauses: FilterQuery[], baseSelector: Record<string, unknown>): FilterQuery;
+/**
+ * 对 $or 数组应用结合律：展平嵌套的 $or，单子节点时提升为根。
+ *
+ * @param orClauses - $or 子句数组（每项已递归 flatten）
+ * @param baseSelector - 与 $or 同层的其它字段条件
+ * @returns 合并后的 selector
+ */
+export declare function reduceOr(orClauses: FilterQuery[], baseSelector: Record<string, unknown>): FilterQuery;
+/**
+ * 对 $nor 数组应用结合律：展平嵌套的 $nor。不做「单子节点提升」以免丢失否定语义。
+ *
+ * @param norClauses - $nor 子句数组（每项已递归 flatten）
+ * @param baseSelector - 与 $nor 同层的其它字段条件
+ * @returns 合并后的 selector
+ */
+export declare function reduceNor(norClauses: FilterQuery[], baseSelector: Record<string, unknown>): FilterQuery;
+/**
+ * 按给定索引的键顺序排列条件（如 $and 中的字段顺序），使生成的 selector 更贴近索引，利于 planner 选择。
+ *
+ * @param conditions - 扁平条件列表（如 ParsedOp[] 或字段名列表）
+ * @param indexSpec - 可选，用于排序的索引；未传则保持原序
+ * @returns 按索引键顺序排列后的条件
+ */
+export declare function orderConditionsByIndex<T>(conditions: T[], indexSpec?: IndexSpec): T[];
+//# sourceMappingURL=flatten.d.ts.map

package/dist/flatten.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../src/flatten.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEtD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,WAAW,EAClB,UAAU,CAAC,EAAE,SAAS,EAAE,GACvB,WAAW,CAIb;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,UAAU,EAAE,WAAW,EAAE,EACzB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,WAAW,CAIb;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,SAAS,EAAE,WAAW,EAAE,EACxB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,WAAW,CAIb;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,UAAU,EAAE,WAAW,EAAE,EACzB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,WAAW,CAIb;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,UAAU,EAAE,CAAC,EAAE,EACf,SAAS,CAAC,EAAE,SAAS,GACpB,CAAC,EAAE,CAGL"}

package/dist/flatten.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flattenSelector = flattenSelector;
+exports.reduceAnd = reduceAnd;
+exports.reduceOr = reduceOr;
+exports.reduceNor = reduceNor;
+exports.orderConditionsByIndex = orderConditionsByIndex;
+/**
+ * 阶段二：打平嵌套层级（结合律），并可选按集合索引排列条件以提升索引利用率。
+ *
+ * @param query - 已修减的查询（通常为 pruneSelector 的输出）
+ * @param indexSpecs - 可选，当前集合的索引列表；传入时会对 $and 等按索引键顺序排序
+ * @returns 打平后的查询，语义不变
+ */
+function flattenSelector(query, indexSpecs) {
+    void indexSpecs;
+    // TODO: 递归应用 reduceAnd / reduceOr / reduceNor，再按 indexSpecs 排序
+    return query;
+}
+/**
+ * 对 $and 数组应用结合律：展平嵌套的 $and，单子节点时提升为根。
+ * 不改变语义，仅简化结构。
+ *
+ * @param andClauses - $and 子句数组（每项已递归 flatten）
+ * @param baseSelector - 与 $and 同层的其它字段条件
+ * @returns 合并后的 selector
+ */
+function reduceAnd(andClauses, baseSelector) {
+    void andClauses;
+    void baseSelector;
+    return {};
+}
+/**
+ * 对 $or 数组应用结合律：展平嵌套的 $or，单子节点时提升为根。
+ *
+ * @param orClauses - $or 子句数组（每项已递归 flatten）
+ * @param baseSelector - 与 $or 同层的其它字段条件
+ * @returns 合并后的 selector
+ */
+function reduceOr(orClauses, baseSelector) {
+    void orClauses;
+    void baseSelector;
+    return {};
+}
+/**
+ * 对 $nor 数组应用结合律：展平嵌套的 $nor。不做「单子节点提升」以免丢失否定语义。
+ *
+ * @param norClauses - $nor 子句数组（每项已递归 flatten）
+ * @param baseSelector - 与 $nor 同层的其它字段条件
+ * @returns 合并后的 selector
+ */
+function reduceNor(norClauses, baseSelector) {
+    void norClauses;
+    void baseSelector;
+    return {};
+}
+/**
+ * 按给定索引的键顺序排列条件（如 $and 中的字段顺序），使生成的 selector 更贴近索引，利于 planner 选择。
+ *
+ * @param conditions - 扁平条件列表（如 ParsedOp[] 或字段名列表）
+ * @param indexSpec - 可选，用于排序的索引；未传则保持原序
+ * @returns 按索引键顺序排列后的条件
+ */
+function orderConditionsByIndex(conditions, indexSpec) {
+    void indexSpec;
+    return conditions;
+}
+//# sourceMappingURL=flatten.js.map

package/dist/flatten.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flatten.js","sourceRoot":"","sources":["../src/flatten.ts"],"names":[],"mappings":";;AASA,0CAOC;AAUD,8BAOC;AASD,4BAOC;AASD,8BAOC;AASD,wDAMC;AA9ED;;;;;;GAMG;AACH,SAAgB,eAAe,CAC7B,KAAkB,EAClB,UAAwB;IAExB,KAAK,UAAU,CAAC;IAChB,+DAA+D;IAC/D,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,SAAS,CACvB,UAAyB,EACzB,YAAqC;IAErC,KAAK,UAAU,CAAC;IAChB,KAAK,YAAY,CAAC;IAClB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,QAAQ,CACtB,SAAwB,EACxB,YAAqC;IAErC,KAAK,SAAS,CAAC;IACf,KAAK,YAAY,CAAC;IAClB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,SAAS,CACvB,UAAyB,EACzB,YAAqC;IAErC,KAAK,UAAU,CAAC;IAChB,KAAK,YAAY,CAAC;IAClB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,sBAAsB,CACpC,UAAe,EACf,SAAqB;IAErB,KAAK,SAAS,CAAC;IACf,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { normalizeQuery } from "./normalize";
+export { resolveNormalizeOptions } from "./options/resolve";
+export type { NormalizeLevel, NormalizeObserve, NormalizeOptions, NormalizeResult, NormalizeRules, NormalizeSafety, NormalizeStats, ResolvedNormalizeOptions, } from "./options/types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,YAAY,EACR,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,eAAe,EACf,cAAc,EACd,wBAAwB,GAC3B,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveNormalizeOptions = exports.normalizeQuery = void 0;
+var normalize_1 = require("./normalize");
+Object.defineProperty(exports, "normalizeQuery", { enumerable: true, get: function () { return normalize_1.normalizeQuery; } });
+var resolve_1 = require("./options/resolve");
+Object.defineProperty(exports, "resolveNormalizeOptions", { enumerable: true, get: function () { return resolve_1.resolveNormalizeOptions; } });
+//# sourceMappingURL=index.js.map