mongo-query-normalizer 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+# Mongo Query Normalizer
+
+**English** | [中文](README.zh-CN.md)
+
+An **observable, level-based** normalizer for MongoDB query objects. It stabilizes query **shape** at the conservative default, offers **preview** higher levels for analysis and experiments, and returns **predictable** output plus **metadata**—not a MongoDB planner optimizer.
+
+> **v0.1.0 — production scope:** For **general production** traffic, use **`shape` only**—it is the **sole** level we recommend for that role in this release. **`predicate`**, **`logical`**, and **`experimental`** are **preview / experimental** surfaces; they fit **offline analysis**, **replay testing**, **semantic validation**, and **targeted experiments** better than a blanket default for all online requests.
+
+---
+
+## Why it exists
+
+- Query **shape** diverges across builders and hand-written filters.
+- Outputs can be **hard to compare**, log, or diff without a stable pass.
+- You need a **low-risk normalization layer** that defaults to conservative behavior.
+
+This library does **not** promise to make queries faster or to pick optimal indexes.
+
+---
+
+## Features
+
+- **Level-based** normalization (`shape` → `predicate` → `logical` → `experimental`)
+- **Conservative default**: `shape` only out of the box (the **only** level we recommend for general production in v0.1.0)
+- **Observable** `meta`: changed flags, applied/skipped rules, warnings, hashes, optional stats
+- **Stable / idempotent** output when rules apply (same options)
+- **Opaque fallback** for unsupported operators (passthrough, not semantically rewritten)
+
+---
+
+## Install
+
+```bash
+npm install mongo-query-normalizer
+```
+
+---
+
+## Quick start
+
+```ts
+import { normalizeQuery } from "mongo-query-normalizer";
+
+const result = normalizeQuery({
+    $and: [{ status: "open" }, { $and: [{ priority: { $gte: 1 } }] }],
+});
+
+console.log(result.query);
+console.log(result.meta);
+```
+
+---
+
+## Default behavior
+
+- **Default `level` is `"shape"`** (see `resolveNormalizeOptions()`).
+- By default there is **no** aggressive predicate merge or logical hoisting.
+- The goal is **stability and observability**, not “smart optimization.”
+
+---
+
+## Production guidance (v0.1.0)
+
+- Use **`shape`** for **general production** traffic. It is the **only** level recommended for that purpose in v0.1.0.
+- Levels above `shape` (`predicate`, `logical`, `experimental`) are **preview / unstable** surfaces. Use them for **offline analysis**, **replay testing**, and **targeted experiments** when you explicitly accept preview semantics—not as a default for all online requests.
+- If you opt into a non-`shape` level, **`meta.warnings` includes a boundary notice** for that call. In **non-production** runs (`NODE_ENV !== "production"`), the library also prints a **matching `console.warn` once per level per process** so local development surfaces the same guidance without spamming repeated logs.
+
+---
+
+## Levels
+
+### `shape` (default)
+
+**Recommended for production hot paths** (the only v0.1.0 level recommended for general production). Safe structural normalization only, for example:
+
+- flatten logical nodes  
+- remove empty logical nodes  
+- collapse single-child logical nodes  
+- dedupe logical children  
+- canonical ordering  
+
+### `predicate`
+
+**Preview / not recommended for general production** in v0.1.0. On top of `shape`, conservative **predicate** cleanup:
+
+- dedupe same-field predicates  
+- merge comparable predicates where modeled  
+- collapse clear contradictions to an unsatisfiable filter  
+- merge **direct** `$and` children that share the same field name before further predicate work (so contradictions like `{ $and: [{ a: 1 }, { a: 2 }] }` can be detected)
+
+### `logical`
+
+**Preview / not recommended for general production** in v0.1.0. On top of `predicate`:
+
+- **detect** common predicates inside `$or` (detection / metadata; **no** default hoisting)
+
+### `experimental`
+
+**Preview / not recommended for general production** in v0.1.0. May **hoist** common predicates from `$or` when the corresponding rule is enabled—**not** for blanket production rollout.
+
+---
+
+## `meta` fields
+
+| Field | Meaning |
+|--------|---------|
+| `changed` | Structural/predicate output differs from input (hash-based) |
+| `level` | Resolved normalization level |
+| `appliedRules` / `skippedRules` | Rule tracing |
+| `warnings` | Non-fatal issues when observation is enabled, plus a **v0.1.0 boundary warning** whenever the resolved level is not `shape` (always present for that case, independent of `observe.collectWarnings`) |
+| `bailedOut` | Safety stop; output reverts to pre-pass parse for that call |
+| `bailoutReason` | Why bailout happened, if any |
+| `beforeHash` / `afterHash` | Stable hashes for diffing |
+| `stats` | Optional before/after tree metrics (`observe.collectMetrics`) |
+
+---
+
+## Unsupported / opaque behavior
+
+Structures such as **`$nor`**, **`$regex`**, **`$not`**, **`$elemMatch`**, **`$expr`**, geo/text queries, and **unknown** operators are generally treated as **opaque**: they pass through or are preserved without full semantic rewriting. They are **not** guaranteed to participate in merge or contradiction logic.
+
+---
+
+## Stability policy
+
+The **public contract** is:
+
+- `normalizeQuery`
+- `resolveNormalizeOptions`
+- the exported **types** listed in the package entry
+
+**Not** part of the public contract: internal AST, `parseQuery`, `compileQuery`, individual rules/passes, or utilities. They may change between versions.
+
+---
+
+## Principles (explicit)
+
+1. Default level is **`shape`**.  
+2. At the default **`shape`** level, the API is **intended for general production use** in v0.1.0.  
+3. **`predicate`** and above may change structure while aiming for **semantic equivalence** on modeled operators.  
+4. **`experimental`** is for experiments or offline replay—**not** default online traffic.  
+5. **Opaque** nodes are not rewritten semantically.  
+6. Output should be **idempotent** under the same options when no bailout occurs.  
+7. This library is **not** the MongoDB query planner or an optimizer.
+
+---
+
+## Example scenarios
+
+**Online main path** — use default (`shape`); this is the supported production default in v0.1.0:
+
+```ts
+normalizeQuery(query);
+```
+
+**Offline analysis / replay / experiments** — opt into higher levels only when you accept preview semantics and non-`shape` boundary warnings (and optional dev console hints):
+
+```ts
+normalizeQuery(query, { level: "predicate" });
+```
+
+---
+
+## Public API
+
+```ts
+normalizeQuery(query, options?) => { query, meta }
+resolveNormalizeOptions(options?) => ResolvedNormalizeOptions
+```
+
+Types: `NormalizeLevel`, `NormalizeOptions`, `NormalizeRules`, `NormalizeSafety`, `NormalizeObserve`, `ResolvedNormalizeOptions`, `NormalizeResult`, `NormalizeStats`.
+
+---
+
+## Semantic tests (property-based)
+
+Randomized tests use **`mongodb-memory-server`** + **`fast-check`** to compare **real** `find` results (same `sort` / `skip` / `limit`, projection `{ _id: 1 }`) before and after `normalizeQuery` on a **fixed document schema** and a **restricted operator set** (see `test/helpers/arbitraries.js`). They assert matching **`_id` order**, **idempotency** of the returned `query`, and (for opaque operators) **non-crash / stable second pass** only. **`FC_SEED` / `FC_RUNS` defaults are centralized in `test/helpers/fc-config.js`** (also re-exported from `arbitraries.js`).
+
+- **`npm run test:unit`** — unit tests (excludes `test/semantic/**`, `test/regression/**`, `test/property/**`; includes `test/contracts/**`, `test/invariants/**`, `test/performance/**`).
+- **`npm run test:semantic`** — semantic + regression + property folders (defaults when env unset: see `fc-config.js`).
+- **`npm run test:semantic:quick`** — lower **`FC_RUNS`** (script sets `45`) + **`FC_SEED=42`**, still runs `test/regression/**` and `test/property/**`.
+- **`npm run test:semantic:ci`** — CI-oriented env (`FC_RUNS=200`, `FC_SEED=42` in script).
+
+Override property-test parameters: **`FC_SEED`**, **`FC_RUNS`**, optional **`FC_QUICK=1`** (see `fc-config.js`). How to reproduce failures and when to add a fixed regression case: **`test/REGRESSION.md`**.
+
+Full-text, geo, heavy **`$expr`**, **`$where`**, aggregation, collation, etc. stay **out** of the main semantic equivalence generator; opaque contracts live in **`test/contracts/opaque-operators.test.js`**.
+
+---
+
+## Contributor notes
+
+- [SPEC.md](SPEC.md) — behavior-oriented specification.  
+- [docs/CANONICAL_FORM.md](docs/CANONICAL_FORM.md) — idempotency and canonical shape notes.

package/README.zh-CN.md

@@ -0,0 +1,194 @@
+# Mongo Query Normalizer
+
+[English](README.md) | **中文**
+
+一个面向 **MongoDB 查询对象** 的**分层规范化**工具：强调**稳定、可控、可观测**，而不是激进改写或执行计划优化。
+
+> **v0.1.0 版本边界：** 面向**一般生产流量**，请**只使用 `shape`**——在本版本中，它是我们**唯一**作此用途推荐的 level。其上的 **`predicate`、`logical`、`experimental`** 属于**预览 / 实验向**能力，更适合**离线分析、回放测试、语义校验与定向实验**，不宜无差别地作为全量在线请求的默认策略。
+
+---
+
+## 为什么需要它
+
+- 查询 **结构** 在不同写法下容易发散。  
+- 没有稳定层时，**对比、日志、回放** 成本高。  
+- 需要一层 **低风险** 的 query normalization，默认行为要保守。
+
+本库**不以**「自动让查询更快」或「替代 planner」作为卖点。
+
+---
+
+## 核心特性
+
+- **按 level 分层**：`shape` → `predicate` → `logical` → `experimental`  
+- **默认保守**：开箱仅 `shape`；在 **v0.1.0** 中，这也是**唯一**建议用于**一般生产环境**的 level  
+- **可观测的 `meta`**：变更、规则、告警、哈希、可选统计  
+- **稳定 / 幂等**（相同 options、未熔断时）  
+- **不透明（opaque）回退**：不支持的算子以透传为主，不做完整语义改写  
+
+---
+
+## 安装
+
+```bash
+npm install mongo-query-normalizer
+```
+
+---
+
+## 快速开始
+
+```ts
+import { normalizeQuery } from "mongo-query-normalizer";
+
+const result = normalizeQuery({
+    $and: [{ status: "open" }, { $and: [{ priority: { $gte: 1 } }] }],
+});
+
+console.log(result.query);
+console.log(result.meta);
+```
+
+---
+
+## 默认行为说明
+
+- **默认 `level` 为 `shape`**（见 `resolveNormalizeOptions()`）。  
+- 默认**不会**做激进的谓词合并或逻辑上提。  
+- 默认目标是 **稳定与可观测**，不是「智能优化」。  
+
+---
+
+## 生产环境建议（v0.1.0）
+
+- **一般生产流量**请使用 **`shape`**；在 **v0.1.0** 中，这是**唯一**建议用于该场景的 level。  
+- `shape` 之上的 **`predicate`、`logical`、`experimental`** 属于**预览 / 不稳定**能力面，宜在**明确接受预览语义**的前提下，用于**离线分析**、**回放测试**、**语义验证**与**定向实验**，不宜作为全量在线请求的默认策略。  
+- 若启用**非 `shape`** 的 level，每次调用都会在 **`meta.warnings`** 中写入一条 **v0.1.0 版本边界说明**。在**非生产**环境（`NODE_ENV !== "production"`）下，还会在进程内对**同一 level 至多输出一次**与之对应的 **`console.warn`**，便于本地开发看到同样提示，又避免重复刷屏。  
+
+---
+
+## Level 说明
+
+### `shape`（默认）
+
+**推荐用于线上主路径**；在 **v0.1.0** 中，亦是**唯一**建议用于**一般生产环境**的层级。只做安全结构规范化，例如：
+
+- flatten logical  
+- remove empty logical  
+- collapse single-child logical  
+- dedupe logical children  
+- canonical ordering  
+
+### `predicate`
+
+**预览能力**：在 **v0.1.0** 中**不建议**作为一般生产环境的默认选择。在 `shape` 之上增加**保守**谓词整理：
+
+- 同字段谓词去重  
+- 可建模的比较类谓词合并  
+- 明确矛盾收敛为不可满足过滤器  
+- 在 `normalizePredicate` 中，**`$and` 下同名 field 的直接子 `FieldNode` 会先合并**，以便检出诸如 `{ $and: [{ a: 1 }, { a: 2 }] }` 的矛盾  
+
+### `logical`
+
+**预览能力**：在 **v0.1.0** 中**不建议**作为一般生产环境的默认选择。在 `predicate` 之上：
+
+- **检测** `$or` 中的公共谓词（默认**只检测**，默认**不上提**）  
+
+### `experimental`
+
+**实验 / 预览层**：在 **v0.1.0** 中**不建议**作为一般生产环境的默认选择。
+
+- 可在规则开启时对 `$or` 做 **hoist** 等实验性变换；**禁止**作为线上全量默认  
+
+---
+
+## `meta` 说明
+
+| 字段 | 含义 |
+|------|------|
+| `changed` | 输出相对输入是否变化（基于哈希） |
+| `level` | 实际使用的规范化层级 |
+| `appliedRules` / `skippedRules` | 规则应用轨迹 |
+| `warnings` | 观察选项开启时的非致命告警；此外，只要解析后的 level **不是** `shape`，就会**始终**附带一条 **v0.1.0 边界说明**（**不**受 `observe.collectWarnings` 影响） |
+| `bailedOut` | 是否触发安全熔断 |
+| `bailoutReason` | 熔断原因 |
+| `beforeHash` / `afterHash` | 前后稳定哈希 |
+| `stats` | 可选的前后树统计（`observe.collectMetrics`） |
+
+---
+
+## 不支持 / opaque 行为
+
+以下结构通常**只透传或不参与完整语义改写**，例如：
+
+`$nor`、`$regex`、`$not`、`$elemMatch`、`$expr`、geo / text、未知算子等。
+
+---
+
+## 稳定性策略
+
+**对外承诺**仅包括：
+
+- `normalizeQuery`  
+- `resolveNormalizeOptions`  
+- 入口导出的 **类型**  
+
+**不属于**对外契约：内部 AST、`parseQuery`、`compileQuery`、各 pass/rule、工具函数等，版本间可能变化。
+
+---
+
+## 必须明确的原则
+
+1. 默认是 **`shape`**。  
+2. 在默认 **`shape`** 路径上，API 面向 **v0.1.0** 的**一般生产用途**而设计；更高 level 不在此承诺范围内。  
+3. **`predicate` 及以上**可能改变查询结构，但在已建模算子上追求 **语义等价**。  
+4. **`experimental`** 仅用于实验或离线回放验证。  
+5. **opaque** 节点不会被语义重写。  
+6. 在未熔断时，输出应对相同 options 保持 **幂等**。  
+7. 本库 **不是** MongoDB 的 planner optimizer。  
+
+---
+
+## 示例场景
+
+- **线上主路径**：`normalizeQuery(query)`（默认 `shape`；**v0.1.0** 约定的生产侧默认路径）  
+- **离线分析 / 回放测试 / 语义验证 / 定向实验**：仅在可接受预览语义，以及非 `shape` 时的 `meta.warnings` 边界说明（与非生产环境下按 level 一次性的 `console.warn`）时，再启用更高 level，例如：  
+
+```ts
+normalizeQuery(query, { level: "predicate" });
+```  
+
+---
+
+## 对外 API
+
+```ts
+normalizeQuery(query, options?) => { query, meta }
+resolveNormalizeOptions(options?) => ResolvedNormalizeOptions
+```
+
+类型：`NormalizeLevel`、`NormalizeOptions`、`NormalizeRules`、`NormalizeSafety`、`NormalizeObserve`、`ResolvedNormalizeOptions`、`NormalizeResult`、`NormalizeStats`。
+
+---
+
+## 语义测试（基于属性的随机测试）
+
+使用 `mongodb-memory-server` 与 `fast-check`，在固定文档 schema 与受限算子集合下对比 normalize 前后真实 `find` 结果（相同 `sort` / `skip` / `limit`，投影 `{ _id: 1 }`），并校验返回 `query` 的幂等。生成器见 `test/helpers/arbitraries.js`，**fast-check 的 seed / runs 统一由 `test/helpers/fc-config.js` 读取**（勿在单测里硬编码默认值）。
+
+- `npm run test:unit`：单元测试（含 `test/contracts`、`test/invariants`、`test/performance`）  
+- `npm run test:semantic`：语义 + 全量回归 + property（默认 `FC_RUNS=200`，见 `fc-config.js`）  
+- `npm run test:semantic:quick`：本地快速跑：**降低 `FC_RUNS`（当前脚本为 45）**，仍包含 `test/regression/**` 与 `test/property/**`  
+- `npm run test:semantic:ci`：CI 较完整配置（脚本内 `FC_RUNS=200`、`FC_SEED=42`）
+
+环境变量：`FC_SEED`、`FC_RUNS`；可选 `FC_QUICK=1` 在未设 `FC_RUNS` 时将默认 runs 降为 50（见 `fc-config.js`）。
+
+**property 失败如何复现、何时沉淀成固定用例、命名与分类**：见 [`test/REGRESSION.md`](test/REGRESSION.md)。
+
+主随机语义等价**不包含**全文、地理、复杂 `$expr`、`$where`、聚合、collation 等；opaque 算子契约见 `test/contracts/opaque-operators.test.js`。
+
+---
+
+## 延伸阅读
+
+- [SPEC.zh-CN.md](SPEC.zh-CN.md)  
+- [docs/CANONICAL_FORM.md](docs/CANONICAL_FORM.md)  

package/dist/ast/builders.d.ts

@@ -0,0 +1,8 @@
+import type { FalseNode, FieldNode, FieldPredicate, LogicalNode, OpaqueNode, QueryNode, TrueNode } from "./types";
+export declare function trueNode(): TrueNode;
+export declare function falseNode(): FalseNode;
+export declare function opaqueNode(raw: unknown, reason?: string): OpaqueNode;
+export declare function andNode(children: QueryNode[]): LogicalNode;
+export declare function orNode(children: QueryNode[]): LogicalNode;
+export declare function fieldNode(field: string, predicates: FieldPredicate[]): FieldNode;
+//# sourceMappingURL=builders.d.ts.map

package/dist/ast/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/ast/builders.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAElH,wBAAgB,QAAQ,IAAI,QAAQ,CAEnC;AAED,wBAAgB,SAAS,IAAI,SAAS,CAErC;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CAEpE;AAED,wBAAgB,OAAO,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,WAAW,CAE1D;AAED,wBAAgB,MAAM,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,WAAW,CAEzD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,GAAG,SAAS,CAEhF"}

package/dist/ast/builders.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trueNode = trueNode;
+exports.falseNode = falseNode;
+exports.opaqueNode = opaqueNode;
+exports.andNode = andNode;
+exports.orNode = orNode;
+exports.fieldNode = fieldNode;
+function trueNode() {
+    return { type: "true" };
+}
+function falseNode() {
+    return { type: "false" };
+}
+function opaqueNode(raw, reason) {
+    return { type: "opaque", raw, reason };
+}
+function andNode(children) {
+    return { type: "logical", op: "$and", children };
+}
+function orNode(children) {
+    return { type: "logical", op: "$or", children };
+}
+function fieldNode(field, predicates) {
+    return { type: "field", field, predicates };
+}
+//# sourceMappingURL=builders.js.map

package/dist/ast/builders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.js","sourceRoot":"","sources":["../../src/ast/builders.ts"],"names":[],"mappings":";;AAEA,4BAEC;AAED,8BAEC;AAED,gCAEC;AAED,0BAEC;AAED,wBAEC;AAED,8BAEC;AAtBD,SAAgB,QAAQ;IACpB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC5B,CAAC;AAED,SAAgB,SAAS;IACrB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC;AAED,SAAgB,UAAU,CAAC,GAAY,EAAE,MAAe;IACpD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;AAC3C,CAAC;AAED,SAAgB,OAAO,CAAC,QAAqB;IACzC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AACrD,CAAC;AAED,SAAgB,MAAM,CAAC,QAAqB;IACxC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AACpD,CAAC;AAED,SAAgB,SAAS,CAAC,KAAa,EAAE,UAA4B;IACjE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AAChD,CAAC"}

package/dist/ast/contains-opaque.d.ts

@@ -0,0 +1,3 @@
+import type { QueryNode } from "./types";
+export declare function containsOpaqueNode(node: QueryNode): boolean;
+//# sourceMappingURL=contains-opaque.d.ts.map

package/dist/ast/contains-opaque.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contains-opaque.d.ts","sourceRoot":"","sources":["../../src/ast/contains-opaque.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAQ3D"}

package/dist/ast/contains-opaque.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.containsOpaqueNode = containsOpaqueNode;
+const guards_1 = require("./guards");
+function containsOpaqueNode(node) {
+    if ((0, guards_1.isOpaqueNode)(node)) {
+        return true;
+    }
+    if ((0, guards_1.isLogicalNode)(node)) {
+        return node.children.some(containsOpaqueNode);
+    }
+    return false;
+}
+//# sourceMappingURL=contains-opaque.js.map

package/dist/ast/contains-opaque.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contains-opaque.js","sourceRoot":"","sources":["../../src/ast/contains-opaque.ts"],"names":[],"mappings":";;AAGA,gDAQC;AAXD,qCAAuD;AAGvD,SAAgB,kBAAkB,CAAC,IAAe;IAC9C,IAAI,IAAA,qBAAY,EAAC,IAAI,CAAC,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,IAAI,IAAA,sBAAa,EAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC"}

package/dist/ast/guards.d.ts

@@ -0,0 +1,7 @@
+import type { FalseNode, FieldNode, LogicalNode, OpaqueNode, QueryNode, TrueNode } from "./types";
+export declare function isLogicalNode(node: QueryNode): node is LogicalNode;
+export declare function isFieldNode(node: QueryNode): node is FieldNode;
+export declare function isTrueNode(node: QueryNode): node is TrueNode;
+export declare function isFalseNode(node: QueryNode): node is FalseNode;
+export declare function isOpaqueNode(node: QueryNode): node is OpaqueNode;
+//# sourceMappingURL=guards.d.ts.map

package/dist/ast/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/ast/guards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,SAAS,EACT,SAAS,EACT,WAAW,EACX,UAAU,EACV,SAAS,EACT,QAAQ,EACX,MAAM,SAAS,CAAC;AAEjB,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,IAAI,WAAW,CAElE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,IAAI,SAAS,CAE9D;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,IAAI,QAAQ,CAE5D;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,IAAI,SAAS,CAE9D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,IAAI,UAAU,CAEhE"}

package/dist/ast/guards.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLogicalNode = isLogicalNode;
+exports.isFieldNode = isFieldNode;
+exports.isTrueNode = isTrueNode;
+exports.isFalseNode = isFalseNode;
+exports.isOpaqueNode = isOpaqueNode;
+function isLogicalNode(node) {
+    return node.type === "logical";
+}
+function isFieldNode(node) {
+    return node.type === "field";
+}
+function isTrueNode(node) {
+    return node.type === "true";
+}
+function isFalseNode(node) {
+    return node.type === "false";
+}
+function isOpaqueNode(node) {
+    return node.type === "opaque";
+}
+//# sourceMappingURL=guards.js.map

package/dist/ast/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/ast/guards.ts"],"names":[],"mappings":";;AASA,sCAEC;AAED,kCAEC;AAED,gCAEC;AAED,kCAEC;AAED,oCAEC;AAlBD,SAAgB,aAAa,CAAC,IAAe;IACzC,OAAO,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC;AACnC,CAAC;AAED,SAAgB,WAAW,CAAC,IAAe;IACvC,OAAO,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC;AACjC,CAAC;AAED,SAAgB,UAAU,CAAC,IAAe;IACtC,OAAO,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC;AAChC,CAAC;AAED,SAAgB,WAAW,CAAC,IAAe;IACvC,OAAO,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC;AACjC,CAAC;AAED,SAAgB,YAAY,CAAC,IAAe;IACxC,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;AAClC,CAAC"}

package/dist/ast/hash.d.ts

@@ -0,0 +1,4 @@
+import type { FieldPredicate, QueryNode } from "./types";
+export declare function hashPredicate(p: FieldPredicate): string;
+export declare function hashNode(node: QueryNode): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/ast/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/ast/hash.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzD,wBAAgB,aAAa,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAEvD;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAmBhD"}

package/dist/ast/hash.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashPredicate = hashPredicate;
+exports.hashNode = hashNode;
+function hashPredicate(p) {
+    return `op:${p.op}|opaque:${p.opaque ? 1 : 0}|v:${serializeValue(p.value)}`;
+}
+function hashNode(node) {
+    switch (node.type) {
+        case "true":
+            return "T";
+        case "false":
+            return "F";
+        case "opaque":
+            return `O:${node.reason ?? ""}:${serializeValue(node.raw)}`;
+        case "field": {
+            const parts = node.predicates.map(hashPredicate).sort();
+            return `F:${node.field}(${parts.join("\u001f")})`;
+        }
+        case "logical": {
+            const childKeys = node.children.map(hashNode).sort();
+            return `L:${node.op}(${childKeys.join("\u001f")})`;
+        }
+        default:
+            return "U";
+    }
+}
+function serializeValue(value) {
+    if (value === undefined) {
+        return "u";
+    }
+    if (value === null) {
+        return "n";
+    }
+    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 `b:${value}`;
+    }
+    if (typeof value === "string") {
+        return `s:${JSON.stringify(value)}`;
+    }
+    if (value instanceof Date) {
+        return `d:${value.toISOString()}`;
+    }
+    if (value instanceof RegExp) {
+        return `r:${value.source}\u0000${value.flags}`;
+    }
+    if (Array.isArray(value)) {
+        return `a:[${value.map(serializeValue).join("\u001f")}]`;
+    }
+    if (typeof value === "object") {
+        const o = value;
+        const keys = Object.keys(o).sort();
+        const inner = keys.map((k) => `${JSON.stringify(k)}:${serializeValue(o[k])}`).join("\u001f");
+        return `o:{${inner}}`;
+    }
+    return `x:${String(value)}`;
+}
+//# sourceMappingURL=hash.js.map

package/dist/ast/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/ast/hash.ts"],"names":[],"mappings":";;AAEA,sCAEC;AAED,4BAmBC;AAvBD,SAAgB,aAAa,CAAC,CAAiB;IAC3C,OAAO,MAAM,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;AAChF,CAAC;AAED,SAAgB,QAAQ,CAAC,IAAe;IACpC,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAChB,KAAK,MAAM;YACP,OAAO,GAAG,CAAC;QACf,KAAK,OAAO;YACR,OAAO,GAAG,CAAC;QACf,KAAK,QAAQ;YACT,OAAO,KAAK,IAAI,CAAC,MAAM,IAAI,EAAE,IAAI,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAChE,KAAK,OAAO,CAAC,CAAC,CAAC;YACX,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,EAAE,CAAC;YACxD,OAAO,KAAK,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QACtD,CAAC;QACD,KAAK,SAAS,CAAC,CAAC,CAAC;YACb,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;YACrD,OAAO,KAAK,IAAI,CAAC,EAAE,IAAI,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QACvD,CAAC;QACD;YACI,OAAO,GAAG,CAAC;IACnB,CAAC;AACL,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IAClC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,GAAG,CAAC;IACf,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACjB,OAAO,GAAG,CAAC;IACf,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5B,IAAI,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvB,OAAO,QAAQ,CAAC;QACpB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,OAAO,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAClC,CAAC;QACD,OAAO,OAAO,KAAK,EAAE,CAAC;IAC1B,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,KAAK,KAAK,EAAE,CAAC;IACxB,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;IACxC,CAAC;IACD,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;QACxB,OAAO,KAAK,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;IACtC,CAAC;IACD,IAAI,KAAK,YAAY,MAAM,EAAE,CAAC;QAC1B,OAAO,KAAK,KAAK,CAAC,MAAM,SAAS,KAAK,CAAC,KAAK,EAAE,CAAC;IACnD,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,MAAM,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;IAC7D,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,CAAC,GAAG,KAAgC,CAAC;QAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC7F,OAAO,MAAM,KAAK,GAAG,CAAC;IAC1B,CAAC;IACD,OAAO,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAChC,CAAC"}

package/dist/ast/index.d.ts

@@ -0,0 +1,6 @@
+export type { FieldNode, FieldPredicate, LogicalNode, OpaqueNode, QueryNode, TrueNode, FalseNode } from "./types";
+export { andNode, falseNode, fieldNode, opaqueNode, orNode, trueNode } from "./builders";
+export { isFalseNode, isFieldNode, isLogicalNode, isOpaqueNode, isTrueNode, } from "./guards";
+export { hashNode, hashPredicate } from "./hash";
+export { containsOpaqueNode } from "./contains-opaque";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ast/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAClH,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,EACH,WAAW,EACX,WAAW,EACX,aAAa,EACb,YAAY,EACZ,UAAU,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/ast/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.containsOpaqueNode = exports.hashPredicate = exports.hashNode = exports.isTrueNode = exports.isOpaqueNode = exports.isLogicalNode = exports.isFieldNode = exports.isFalseNode = exports.trueNode = exports.orNode = exports.opaqueNode = exports.fieldNode = exports.falseNode = exports.andNode = void 0;
+var builders_1 = require("./builders");
+Object.defineProperty(exports, "andNode", { enumerable: true, get: function () { return builders_1.andNode; } });
+Object.defineProperty(exports, "falseNode", { enumerable: true, get: function () { return builders_1.falseNode; } });
+Object.defineProperty(exports, "fieldNode", { enumerable: true, get: function () { return builders_1.fieldNode; } });
+Object.defineProperty(exports, "opaqueNode", { enumerable: true, get: function () { return builders_1.opaqueNode; } });
+Object.defineProperty(exports, "orNode", { enumerable: true, get: function () { return builders_1.orNode; } });
+Object.defineProperty(exports, "trueNode", { enumerable: true, get: function () { return builders_1.trueNode; } });
+var guards_1 = require("./guards");
+Object.defineProperty(exports, "isFalseNode", { enumerable: true, get: function () { return guards_1.isFalseNode; } });
+Object.defineProperty(exports, "isFieldNode", { enumerable: true, get: function () { return guards_1.isFieldNode; } });
+Object.defineProperty(exports, "isLogicalNode", { enumerable: true, get: function () { return guards_1.isLogicalNode; } });
+Object.defineProperty(exports, "isOpaqueNode", { enumerable: true, get: function () { return guards_1.isOpaqueNode; } });
+Object.defineProperty(exports, "isTrueNode", { enumerable: true, get: function () { return guards_1.isTrueNode; } });
+var hash_1 = require("./hash");
+Object.defineProperty(exports, "hashNode", { enumerable: true, get: function () { return hash_1.hashNode; } });
+Object.defineProperty(exports, "hashPredicate", { enumerable: true, get: function () { return hash_1.hashPredicate; } });
+var contains_opaque_1 = require("./contains-opaque");
+Object.defineProperty(exports, "containsOpaqueNode", { enumerable: true, get: function () { return contains_opaque_1.containsOpaqueNode; } });
+//# sourceMappingURL=index.js.map

package/dist/ast/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ast/index.ts"],"names":[],"mappings":";;;AACA,uCAAyF;AAAhF,mGAAA,OAAO,OAAA;AAAE,qGAAA,SAAS,OAAA;AAAE,qGAAA,SAAS,OAAA;AAAE,sGAAA,UAAU,OAAA;AAAE,kGAAA,MAAM,OAAA;AAAE,oGAAA,QAAQ,OAAA;AACpE,mCAMkB;AALd,qGAAA,WAAW,OAAA;AACX,qGAAA,WAAW,OAAA;AACX,uGAAA,aAAa,OAAA;AACb,sGAAA,YAAY,OAAA;AACZ,oGAAA,UAAU,OAAA;AAEd,+BAAiD;AAAxC,gGAAA,QAAQ,OAAA;AAAE,qGAAA,aAAa,OAAA;AAChC,qDAAuD;AAA9C,qHAAA,kBAAkB,OAAA"}