@uniqu/core 0.1.7 → 0.1.8

package/README.md

@@ -35,7 +35,7 @@ const query: Uniquery = {
 
 ### Filter Expressions
 
-A `FilterExpr` is either a **comparison node** (leaf) or a **logical node** (branch):
+A `FilterExpr` is a **comparison node** (leaf), a **logical node** (branch), or a mix of both in one object (see [below](#mixing-comparison-fields-with-logical-operators)):
 
 ```ts
 // Comparison — one or more field conditions
@@ -54,6 +54,27 @@ A `FilterExpr` is either a **comparison node** (leaf) or a **logical node** (bra
 { $not: { status: 'DELETED' } }
 ```
 
+#### Mixing comparison fields with logical operators
+
+Comparison fields and logical operators may appear in the **same** object. All
+members of an object are combined with an implicit **AND**, in key order
+(MongoDB semantics):
+
+```ts
+// Both the field conditions and the $or branch apply
+{ id: 101, nextRefreshAt: { $lte: now }, $or: [{ status: 'a' }, { status: 'b' }] }
+
+// …is equivalent to
+{ $and: [
+  { id: 101, nextRefreshAt: { $lte: now } },
+  { $or: [{ status: 'a' }, { status: 'b' }] },
+]}
+```
+
+The same holds for `$and` and `$not` members, and for several logical keys in
+one object — each is simply another AND member: `{ a: 1, $and: [...], $or: [...] }`
+means `a = 1` AND the `$and` branch AND the `$or` branch.
+
 ### Comparison Operators
 
 | Operator | Description | Value Type |
@@ -290,11 +311,13 @@ interface FilterVisitor<R> {
 
 ### Walker Behavior
 
+- Every member of a node is ANDed, in key order — comparison fields and logical keys alike. A field with several operators (`{ age: { $gte: 18, $lte: 30 } }`) contributes one `comparison` call per operator
 - Bare primitive values (`{ name: 'John' }`) are normalized to `comparison(field, '$eq', value)` calls
-- Multi-field comparison nodes (`{ age: ..., status: ... }`) are expanded into individual `comparison` calls wrapped in `visitor.and(...)`
-- `$and` / `$or` nodes recurse into children and call the corresponding visitor method
-- `$not` nodes recurse into the single child and call `visitor.not(...)`
-- Empty nodes call `visitor.and([])`
+- A single-member node returns its result unwrapped: `and()` is not called for `{ a: 1 }` or a lone `{ $or: [...] }`, but it is called with one child for `{ $and: [x] }`
+- `$and` / `$or` recurse into their children and call `and(...)` / `or(...)`; `$not` recurses into its single child and calls `not(...)`
+- Children are visited before their parent (depth-first, post-order)
+- A logical key whose value is `undefined` is skipped
+- An empty node calls `and([])`
 
 ## Lazy Insights
 
@@ -370,7 +393,7 @@ const insights = getInsights(query)
 | `FieldValue` | `Primitive \| FieldOps` |
 | `FilterExpr<T>` | `ComparisonNode<T> \| LogicalNode<T>` |
 | `ComparisonNode<T>` | Leaf node — keys constrained to `keyof T` when typed |
-| `LogicalNode<T>` | `{ $and: ... } \| { $or: ... } \| { $not: ... }` — variants are mutually exclusive via `never` |
+| `LogicalNode<T>` | `{ $and: ... } \| { $or: ... } \| { $not: ... }` — at most one logical key per object at the type level (the others are `never`); comparison fields may sit alongside it, and the runtime ANDs several logical keys |
 | `AggregateFn` | `'sum' \| 'count' \| 'avg' \| 'min' \| 'max'` |
 | `AggregateExpr<Fn, Field, Alias>` | `{ $fn, $field, $as? }` — aggregate function call in `$select`. Generic params preserve literal types for result inference |
 | `SelectExpr<T>` | `((keyof T & string) \| AggregateExpr)[] \| Record<keyof T & string, 0 \| 1>` |

package/dist/index.cjs

@@ -6,36 +6,30 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 * Returns the fully assembled result from the visitor.
 *
 * - Bare primitive values are normalized to `comparison(field, '$eq', value)`.
-* - Multi-field ComparisonNodes are combined via `visitor.and(...)`.
+* - Every member of an object is combined with implicit AND, in key insertion
+*   order — comparison fields and logical operators may be mixed freely
+*   (Mongo semantics): `{ id: 101, $or: [...] }` is equivalent to
+*   `{ $and: [{ id: 101 }, { $or: [...] }] }`. A field with several operators
+*   contributes one `comparison` per operator.
+* - A node that yields a single result returns it unwrapped (no surrounding
+*   `and`); an empty node yields `visitor.and([])`.
 */ function walkFilter(expr, visitor) {
 	if (!expr) return void 0;
-	if ("$and" in expr && expr.$and !== void 0) {
-		const andArr = expr.$and;
-		const children = [];
-		for (const child of andArr) children.push(walkFilter(child, visitor));
-		return visitor.and(children);
-	}
-	if ("$or" in expr && expr.$or !== void 0) {
-		const orArr = expr.$or;
-		const children = [];
-		for (const child of orArr) children.push(walkFilter(child, visitor));
-		return visitor.or(children);
-	}
-	if ("$not" in expr && expr.$not !== void 0) {
-		const child = walkFilter(expr.$not, visitor);
-		return visitor.not(child);
-	}
-	const node = expr;
-	const entries = Object.entries(node);
-	if (entries.length === 0) return visitor.and([]);
 	const results = [];
-	for (const [field, value] of entries) if (isPrimitive(value)) results.push(visitor.comparison(field, "$eq", value));
-	else {
-		const ops = value;
-		for (const [op, opValue] of Object.entries(ops)) results.push(visitor.comparison(field, op, opValue));
-	}
+	for (const [key, value] of Object.entries(expr)) if (isLogicalKey(key)) {
+		if (value !== void 0) results.push(walkLogical(key, value, visitor));
+	} else if (isPrimitive(value)) results.push(visitor.comparison(key, "$eq", value));
+	else for (const [op, opValue] of Object.entries(value)) results.push(visitor.comparison(key, op, opValue));
 	return results.length === 1 ? results[0] : visitor.and(results);
 }
+function walkLogical(key, value, visitor) {
+	if (key === "$not") return visitor.not(walkFilter(value, visitor));
+	const children = value.map((child) => walkFilter(child, visitor));
+	return key === "$and" ? visitor.and(children) : visitor.or(children);
+}
+/** Type guard for the logical keys a filter node may carry. */ function isLogicalKey(key) {
+	return key === "$and" || key === "$or" || key === "$not";
+}
 function isPrimitive(x) {
 	if (x === null || typeof x !== "object") return true;
 	if (x instanceof RegExp || x instanceof Date) return true;
@@ -112,5 +106,6 @@ function isPrimitive(x) {
 //#endregion
 exports.computeInsights = computeInsights;
 exports.getInsights = getInsights;
+exports.isLogicalKey = isLogicalKey;
 exports.isPrimitive = isPrimitive;
 exports.walkFilter = walkFilter;

package/dist/index.d.ts

@@ -49,8 +49,10 @@ type ComparisonNode<T = Record<string, unknown>> = {
 };
 /**
  * Branch node: logical combination of child expressions.
- * Each variant forbids the other logical keys via `never` to prevent
- * mixing comparison fields with logical operators at the type level.
+ * The `never` members allow at most one logical key per object at the type
+ * level (`{ $and, $or }` is rejected); comparison fields may still sit
+ * alongside it (`{ id: 1, $or: [...] }`). At runtime every member of a node
+ * is ANDed, so several logical keys in one object are accepted and combined.
  */
 type LogicalNode<T = Record<string, unknown>> = {
     $and: FilterExpr<T>[];
@@ -209,9 +211,17 @@ interface FilterVisitor<R> {
  * Returns the fully assembled result from the visitor.
  *
  * - Bare primitive values are normalized to `comparison(field, '$eq', value)`.
- * - Multi-field ComparisonNodes are combined via `visitor.and(...)`.
+ * - Every member of an object is combined with implicit AND, in key insertion
+ *   order — comparison fields and logical operators may be mixed freely
+ *   (Mongo semantics): `{ id: 101, $or: [...] }` is equivalent to
+ *   `{ $and: [{ id: 101 }, { $or: [...] }] }`. A field with several operators
+ *   contributes one `comparison` per operator.
+ * - A node that yields a single result returns it unwrapped (no surrounding
+ *   `and`); an empty node yields `visitor.and([])`.
  */
 declare function walkFilter<R>(expr: FilterExpr | undefined, visitor: FilterVisitor<R>): R | undefined;
+/** Type guard for the logical keys a filter node may carry. */
+declare function isLogicalKey(key: string): key is '$and' | '$or' | '$not';
 declare function isPrimitive(x: unknown): x is Primitive;
 
 /**
@@ -226,5 +236,5 @@ declare function computeInsights(filter?: FilterExpr, controls?: UniqueryControl
  */
 declare function getInsights(query: Uniquery): UniqueryInsights;
 
-export { computeInsights, getInsights, isPrimitive, walkFilter };
+export { computeInsights, getInsights, isLogicalKey, isPrimitive, walkFilter };
 export type { AggregateControls, AggregateExpr, AggregateFn, AggregateQuery, AggregateResult, ComparisonNode, ComparisonOp, FieldOps, FieldOpsFor, FieldValue, FilterExpr, FilterVisitor, InsightOp, LogicalNode, NavTarget, Primitive, ResolveAlias, SelectExpr, TypedWithRelation, Uniquery, UniqueryControls, UniqueryInsights, WithRelation };

package/dist/index.mjs

@@ -4,36 +4,30 @@
 * Returns the fully assembled result from the visitor.
 *
 * - Bare primitive values are normalized to `comparison(field, '$eq', value)`.
-* - Multi-field ComparisonNodes are combined via `visitor.and(...)`.
+* - Every member of an object is combined with implicit AND, in key insertion
+*   order — comparison fields and logical operators may be mixed freely
+*   (Mongo semantics): `{ id: 101, $or: [...] }` is equivalent to
+*   `{ $and: [{ id: 101 }, { $or: [...] }] }`. A field with several operators
+*   contributes one `comparison` per operator.
+* - A node that yields a single result returns it unwrapped (no surrounding
+*   `and`); an empty node yields `visitor.and([])`.
 */ function walkFilter(expr, visitor) {
 	if (!expr) return void 0;
-	if ("$and" in expr && expr.$and !== void 0) {
-		const andArr = expr.$and;
-		const children = [];
-		for (const child of andArr) children.push(walkFilter(child, visitor));
-		return visitor.and(children);
-	}
-	if ("$or" in expr && expr.$or !== void 0) {
-		const orArr = expr.$or;
-		const children = [];
-		for (const child of orArr) children.push(walkFilter(child, visitor));
-		return visitor.or(children);
-	}
-	if ("$not" in expr && expr.$not !== void 0) {
-		const child = walkFilter(expr.$not, visitor);
-		return visitor.not(child);
-	}
-	const node = expr;
-	const entries = Object.entries(node);
-	if (entries.length === 0) return visitor.and([]);
 	const results = [];
-	for (const [field, value] of entries) if (isPrimitive(value)) results.push(visitor.comparison(field, "$eq", value));
-	else {
-		const ops = value;
-		for (const [op, opValue] of Object.entries(ops)) results.push(visitor.comparison(field, op, opValue));
-	}
+	for (const [key, value] of Object.entries(expr)) if (isLogicalKey(key)) {
+		if (value !== void 0) results.push(walkLogical(key, value, visitor));
+	} else if (isPrimitive(value)) results.push(visitor.comparison(key, "$eq", value));
+	else for (const [op, opValue] of Object.entries(value)) results.push(visitor.comparison(key, op, opValue));
 	return results.length === 1 ? results[0] : visitor.and(results);
 }
+function walkLogical(key, value, visitor) {
+	if (key === "$not") return visitor.not(walkFilter(value, visitor));
+	const children = value.map((child) => walkFilter(child, visitor));
+	return key === "$and" ? visitor.and(children) : visitor.or(children);
+}
+/** Type guard for the logical keys a filter node may carry. */ function isLogicalKey(key) {
+	return key === "$and" || key === "$or" || key === "$not";
+}
 function isPrimitive(x) {
 	if (x === null || typeof x !== "object") return true;
 	if (x instanceof RegExp || x instanceof Date) return true;
@@ -108,4 +102,4 @@ function isPrimitive(x) {
 }
 
 //#endregion
-export { computeInsights, getInsights, isPrimitive, walkFilter };
+export { computeInsights, getInsights, isLogicalKey, isPrimitive, walkFilter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqu/core",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Canonical query format types, tree walker, and utilities for Uniqu",
   "license": "MIT",
   "author": "Artem Maltsev",