@uniqu/core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 moostjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# @uniqu/core
+
+<p align="center">
+  <img src="../../logo.svg" alt="uniqu" height="80">
+</p>
+
+Canonical query format types and transport-agnostic utilities for the Uniqu query representation.
+
+## Install
+
+```bash
+pnpm add @uniqu/core
+```
+
+## Query Format
+
+A `Uniquery` consists of a **filter** (recursive expression tree) and **controls** (pagination, projection, sorting):
+
+```ts
+import type { Uniquery, FilterExpr } from '@uniqu/core'
+
+const query: Uniquery = {
+  filter: {
+    age: { $gte: 18, $lte: 30 },
+    status: { $ne: 'DELETED' },
+    role: { $in: ['Admin', 'Editor'] },
+  },
+  controls: {
+    $sort: { createdAt: -1 },
+    $limit: 20,
+    $select: ['name', 'email'],
+  },
+}
+```
+
+### Filter Expressions
+
+A `FilterExpr` is either a **comparison node** (leaf) or a **logical node** (branch):
+
+```ts
+// Comparison — one or more field conditions
+{ age: { $gte: 18 }, status: 'active' }
+
+// Bare primitive is implicit $eq
+{ name: 'John' }  // equivalent to { name: { $eq: 'John' } }
+
+// Logical — $and / $or wrapping child expressions
+{ $or: [
+  { age: { $gt: 25 } },
+  { status: 'VIP' },
+]}
+
+// Negation — $not wrapping a single child
+{ $not: { status: 'DELETED' } }
+```
+
+### Comparison Operators
+
+| Operator | Description | Value Type |
+|----------|-------------|------------|
+| `$eq` | Equal (implicit when bare value) | `Primitive` |
+| `$ne` | Not equal | `Primitive` |
+| `$gt` | Greater than | `Primitive` |
+| `$gte` | Greater than or equal | `Primitive` |
+| `$lt` | Less than | `Primitive` |
+| `$lte` | Less than or equal | `Primitive` |
+| `$in` | In list | `Primitive[]` |
+| `$nin` | Not in list | `Primitive[]` |
+| `$regex` | Regular expression match | `RegExp \| string` |
+| `$exists` | Field existence check | `boolean` |
+
+`Primitive` = `string | number | boolean | null | RegExp | Date`
+
+> **Note on `Date`:** `Date` is included for direct code usage (e.g. `{ createdAt: { $gt: new Date() } }`). The URL parser produces ISO strings, not `Date` instances. Adapters are responsible for converting `Date` to their native format (`.toISOString()` for SQL, native `Date` for MongoDB).
+
+### Controls
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `$sort` | `Record<string, 1 \| -1>` | Sort fields (1 = asc, -1 = desc) |
+| `$skip` | `number` | Skip N results |
+| `$limit` | `number` | Limit to N results |
+| `$count` | `boolean` | Request total count |
+| `$select` | `string[] \| Record<string, 0 \| 1>` | Field projection — array for inclusion, object for exclusion/mixed |
+| `$<custom>` | `unknown` | Arbitrary pass-through keywords |
+
+## Type-Safe Filters
+
+`FilterExpr<T>` accepts a generic entity type for compile-time field and value checking. Dot-notation paths are always allowed for nested access:
+
+```ts
+interface User {
+  name: string
+  age: number
+  active: boolean
+}
+
+const filter: FilterExpr<User> = {
+  name: 'John',              // string — ok
+  age: { $gte: 18 },         // number — ok
+  active: true,              // boolean — ok
+  'address.city': 'NYC',     // dot-notation — always allowed
+  // age: { $gte: 'old' },   // type error: string not assignable to number
+}
+```
+
+Without a generic argument, `FilterExpr` accepts any string keys with any values (untyped mode).
+
+### Type-Safe Controls
+
+`UniqueryControls<T>` constrains `$select` and `$sort` field names when a type parameter is provided:
+
+```ts
+const query: Uniquery<User> = {
+  filter: { name: 'John' },
+  controls: {
+    $select: ['name', 'email'],     // ✅ autocomplete, catches typos
+    $sort: { name: 1 },             // ✅ only known fields
+    // $select: ['foo'],            // type error: 'foo' is not keyof User
+  },
+}
+```
+
+## Tree Walker
+
+`walkFilter` traverses a filter tree and calls a visitor at each node. The generic return type `R` is controlled by the visitor — `string` for SQL rendering, `boolean` for validation, `void` for side-effect traversals:
+
+```ts
+import { walkFilter, type FilterVisitor } from '@uniqu/core'
+
+// Example: render to a SQL WHERE clause
+const sqlVisitor: FilterVisitor<string> = {
+  comparison(field, op, value) {
+    const ops: Record<string, string> = {
+      $eq: '=', $ne: '!=', $gt: '>', $gte: '>=', $lt: '<', $lte: '<=',
+    }
+    if (ops[op]) return `${field} ${ops[op]} ${JSON.stringify(value)}`
+    if (op === '$in') return `${field} IN (${(value as unknown[]).map(v => JSON.stringify(v)).join(', ')})`
+    if (op === '$regex') return `${field} ~ ${value}`
+    if (op === '$exists') return value ? `${field} IS NOT NULL` : `${field} IS NULL`
+    return `${field} ${op} ${JSON.stringify(value)}`
+  },
+  and: (children) => children.join(' AND '),
+  or: (children) => `(${children.join(' OR ')})`,
+  not: (child) => `NOT (${child})`,
+}
+
+const where = walkFilter(query.filter, sqlVisitor)
+// "age >= 18 AND age <= 30 AND status != \"DELETED\" AND role IN (\"Admin\", \"Editor\")"
+```
+
+### Visitor Interface
+
+```ts
+interface FilterVisitor<R> {
+  /** Called for each field comparison (bare values normalized to $eq). */
+  comparison(field: string, op: ComparisonOp, value: Primitive | Primitive[]): R
+
+  /** Combine children with AND logic. */
+  and(children: R[]): R
+
+  /** Combine children with OR logic. */
+  or(children: R[]): R
+
+  /** Negate a child expression. */
+  not(child: R): R
+}
+```
+
+### Walker Behavior
+
+- 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([])`
+
+## Lazy Insights
+
+`computeInsights` walks an already-built query to produce a map of field names to the set of operators used on each field. This is the lazy counterpart to the eager insights computed during URL parsing:
+
+```ts
+import { computeInsights } from '@uniqu/core'
+
+const insights = computeInsights(query.filter, query.controls)
+// Map {
+//   'age'       => Set { '$gte', '$lte' },
+//   'status'    => Set { '$ne' },
+//   'role'      => Set { '$in' },
+//   'createdAt' => Set { '$order' },
+//   'name'      => Set { '$select' },
+//   'email'     => Set { '$select' },
+// }
+```
+
+Use cases: field whitelisting, operator auditing, index planning.
+
+### `getInsights`
+
+`getInsights` returns pre-computed insights when present on the query, or computes them lazily:
+
+```ts
+import { getInsights } from '@uniqu/core'
+
+const insights = getInsights(query)
+// Uses query.insights if present (e.g. from parseUrl), otherwise calls computeInsights
+```
+
+## API Reference
+
+### Types
+
+| Export | Description |
+|--------|-------------|
+| `Primitive` | `string \| number \| boolean \| null \| RegExp \| Date` |
+| `ComparisonOp` | Union of all `$`-prefixed operator names |
+| `FieldOpsFor<V>` | Per-field typed operator map |
+| `FieldOps` | Untyped operator map (`FieldOpsFor<Primitive>`) |
+| `FieldValue` | `Primitive \| FieldOps` |
+| `FilterExpr<T>` | `ComparisonNode<T> \| LogicalNode<T>` |
+| `ComparisonNode<T>` | Leaf node with typed field comparisons |
+| `LogicalNode<T>` | `{ $and: ... } \| { $or: ... } \| { $not: ... }` — variants are mutually exclusive via `never` |
+| `UniqueryControls<T>` | Pagination, sorting, projection — `$select`/`$sort` constrained to `keyof T` when typed |
+| `Uniquery<T>` | `{ filter: FilterExpr<T>, controls: UniqueryControls<T>, insights?: UniqueryInsights }` |
+| `InsightOp` | `ComparisonOp \| '$select' \| '$order'` |
+| `UniqueryInsights` | `Map<string, Set<InsightOp>>` |
+
+### Functions
+
+| Export | Signature | Description |
+|--------|-----------|-------------|
+| `walkFilter` | `<R>(expr: FilterExpr, visitor: FilterVisitor<R>) => R` | Traverse filter tree with visitor callbacks |
+| `computeInsights` | `(filter: FilterExpr, controls?: UniqueryControls) => UniqueryInsights` | Lazily compute field/operator usage map |
+| `getInsights` | `(query: Uniquery) => UniqueryInsights` | Return pre-computed or lazily computed insights |
+| `isPrimitive` | `(x: unknown) => x is Primitive` | Type guard for primitive values |
+
+## License
+
+[MIT](../../LICENSE)

package/dist/index.cjs

@@ -0,0 +1,78 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region packages/core/src/walk.ts
+/**
+* Walk a filter expression tree, calling visitor callbacks at each node.
+* 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(...)`.
+*/ function walkFilter(expr, visitor) {
+	if ("$and" in expr && expr.$and !== void 0) {
+		const children = expr.$and.map((child) => walkFilter(child, visitor));
+		return visitor.and(children);
+	}
+	if ("$or" in expr && expr.$or !== void 0) {
+		const children = expr.$or.map((child) => 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));
+	}
+	return results.length === 1 ? results[0] : visitor.and(results);
+}
+function isPrimitive(x) {
+	return x === null || typeof x === "string" || typeof x === "number" || typeof x === "boolean" || x instanceof RegExp || x instanceof Date;
+}
+
+//#endregion
+//#region packages/core/src/insights.ts
+/**
+* Compute insights (field → operators map) from an already-built query.
+* This is the lazy counterpart to the eager insight capture done during
+* URL parsing.
+*/ function computeInsights(filter, controls) {
+	const insights = /* @__PURE__ */ new Map();
+	function capture(field, op) {
+		let set = insights.get(field);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			insights.set(field, set);
+		}
+		set.add(op);
+	}
+	walkFilter(filter, {
+		comparison(field, op) {
+			capture(field, op);
+		},
+		and() {},
+		or() {},
+		not() {}
+	});
+	if (controls?.$select) if (Array.isArray(controls.$select)) for (const field of controls.$select) capture(field, "$select");
+	else for (const field of Object.keys(controls.$select)) capture(field, "$select");
+	if (controls?.$sort) for (const field of Object.keys(controls.$sort)) capture(field, "$order");
+	return insights;
+}
+/**
+* Return insights for a query — uses pre-computed insights when present,
+* computes lazily otherwise.
+*/ function getInsights(query) {
+	return query.insights ?? computeInsights(query.filter, query.controls);
+}
+
+//#endregion
+exports.computeInsights = computeInsights;
+exports.getInsights = getInsights;
+exports.isPrimitive = isPrimitive;
+exports.walkFilter = walkFilter;

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Scalar value types supported in filter expressions.
+ *
+ * `Date` is included for direct code usage (e.g. `{ createdAt: { $gt: new Date() } }`).
+ * The URL parser produces ISO strings, not `Date` instances.
+ * Adapters are responsible for handling both: convert `Date` to their native format
+ * (e.g. `.toISOString()` for SQL params, native `Date` for MongoDB).
+ */
+type Primitive = string | number | boolean | null | RegExp | Date;
+/** All comparison operators supported by the filter format. */
+type ComparisonOp = '$eq' | '$ne' | '$gt' | '$gte' | '$lt' | '$lte' | '$in' | '$nin' | '$regex' | '$exists';
+/**
+ * Per-field typed operator map. When `V` is the field's value type, operators
+ * are constrained accordingly:
+ * - `$regex` is only available when `V` extends `string`
+ * - `$gt/$gte/$lt/$lte` are only available when `V` extends `number | string | Date`
+ */
+type FieldOpsFor<V> = {
+    $eq?: V;
+    $ne?: V;
+    $in?: V[];
+    $nin?: V[];
+    $exists?: boolean;
+} & (V extends string ? {
+    $regex?: RegExp | string;
+} : {}) & (V extends number | string | Date ? {
+    $gt?: V;
+    $gte?: V;
+    $lt?: V;
+    $lte?: V;
+} : {});
+/** Untyped operator map. */
+type FieldOps = FieldOpsFor<Primitive>;
+/** A field can hold a bare primitive (implicit $eq) or an explicit operator map. */
+type FieldValue = Primitive | FieldOps;
+/**
+ * A filter expression is either a comparison leaf or a logical branch.
+ * `T` is the entity shape — provides type-safe field names and value types.
+ * Defaults to `Record<string, unknown>` (untyped).
+ */
+type FilterExpr<T = Record<string, unknown>> = ComparisonNode<T> | LogicalNode<T>;
+/**
+ * Leaf node: one or more field comparisons.
+ * Known keys from `T` get typed values; arbitrary string keys
+ * (e.g. dot-notation paths like `"client.age"`) are always allowed.
+ */
+type ComparisonNode<T = Record<string, unknown>> = {
+    [K in keyof T & string]?: T[K] | FieldOpsFor<T[K]>;
+} & 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.
+ */
+type LogicalNode<T = Record<string, unknown>> = {
+    $and: FilterExpr<T>[];
+    $or?: never;
+    $not?: never;
+} | {
+    $or: FilterExpr<T>[];
+    $and?: never;
+    $not?: never;
+} | {
+    $not: FilterExpr<T>;
+    $and?: never;
+    $or?: never;
+};
+/** Query controls (pagination, projection, sorting). Generic `T` constrains field names in `$select` and `$sort`. */
+interface UniqueryControls<T = Record<string, unknown>> {
+    $sort?: Partial<Record<keyof T & string, 1 | -1>>;
+    $skip?: number;
+    $limit?: number;
+    $count?: boolean;
+    $select?: (keyof T & string)[] | Partial<Record<keyof T & string, 0 | 1>>;
+    /** Pass-through for unknown $-prefixed keywords. */
+    [key: `$${string}`]: unknown;
+}
+/** Top-level query: filter tree + controls. */
+interface Uniquery<T = Record<string, unknown>> {
+    filter: FilterExpr<T>;
+    controls: UniqueryControls<T>;
+    /** Pre-computed insights. When present, consumers should use `getInsights()` which trusts these instead of recomputing. */
+    insights?: UniqueryInsights;
+}
+/** Insight operator includes comparison ops plus control-derived ops. */
+type InsightOp = ComparisonOp | '$select' | '$order';
+/** Map of field names to the set of operators used on that field. */
+type UniqueryInsights = Map<string, Set<InsightOp>>;
+
+/**
+ * Visitor callbacks for controlling how filter nodes are processed.
+ * Generic parameter `R` is the return type — `string` for SQL rendering,
+ * `boolean` for validation, `FilterExpr` for AST transforms, `void` for
+ * side-effect-only traversals (e.g. insight collection).
+ */
+interface FilterVisitor<R> {
+    /** Called for each field comparison. */
+    comparison(field: string, op: ComparisonOp, value: Primitive | Primitive[]): R;
+    /** Combine children with AND logic. */
+    and(children: R[]): R;
+    /** Combine children with OR logic. */
+    or(children: R[]): R;
+    /** Negate a child expression. */
+    not(child: R): R;
+}
+/**
+ * Walk a filter expression tree, calling visitor callbacks at each node.
+ * 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(...)`.
+ */
+declare function walkFilter<R>(expr: FilterExpr, visitor: FilterVisitor<R>): R;
+declare function isPrimitive(x: unknown): x is Primitive;
+
+/**
+ * Compute insights (field → operators map) from an already-built query.
+ * This is the lazy counterpart to the eager insight capture done during
+ * URL parsing.
+ */
+declare function computeInsights(filter: FilterExpr, controls?: UniqueryControls): UniqueryInsights;
+/**
+ * Return insights for a query — uses pre-computed insights when present,
+ * computes lazily otherwise.
+ */
+declare function getInsights(query: Uniquery): UniqueryInsights;
+
+export { computeInsights, getInsights, isPrimitive, walkFilter };
+export type { ComparisonNode, ComparisonOp, FieldOps, FieldOpsFor, FieldValue, FilterExpr, FilterVisitor, InsightOp, LogicalNode, Primitive, Uniquery, UniqueryControls, UniqueryInsights };

package/dist/index.mjs

@@ -0,0 +1,73 @@
+//#region packages/core/src/walk.ts
+/**
+* Walk a filter expression tree, calling visitor callbacks at each node.
+* 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(...)`.
+*/ function walkFilter(expr, visitor) {
+	if ("$and" in expr && expr.$and !== void 0) {
+		const children = expr.$and.map((child) => walkFilter(child, visitor));
+		return visitor.and(children);
+	}
+	if ("$or" in expr && expr.$or !== void 0) {
+		const children = expr.$or.map((child) => 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));
+	}
+	return results.length === 1 ? results[0] : visitor.and(results);
+}
+function isPrimitive(x) {
+	return x === null || typeof x === "string" || typeof x === "number" || typeof x === "boolean" || x instanceof RegExp || x instanceof Date;
+}
+
+//#endregion
+//#region packages/core/src/insights.ts
+/**
+* Compute insights (field → operators map) from an already-built query.
+* This is the lazy counterpart to the eager insight capture done during
+* URL parsing.
+*/ function computeInsights(filter, controls) {
+	const insights = /* @__PURE__ */ new Map();
+	function capture(field, op) {
+		let set = insights.get(field);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			insights.set(field, set);
+		}
+		set.add(op);
+	}
+	walkFilter(filter, {
+		comparison(field, op) {
+			capture(field, op);
+		},
+		and() {},
+		or() {},
+		not() {}
+	});
+	if (controls?.$select) if (Array.isArray(controls.$select)) for (const field of controls.$select) capture(field, "$select");
+	else for (const field of Object.keys(controls.$select)) capture(field, "$select");
+	if (controls?.$sort) for (const field of Object.keys(controls.$sort)) capture(field, "$order");
+	return insights;
+}
+/**
+* Return insights for a query — uses pre-computed insights when present,
+* computes lazily otherwise.
+*/ function getInsights(query) {
+	return query.insights ?? computeInsights(query.filter, query.controls);
+}
+
+//#endregion
+export { computeInsights, getInsights, isPrimitive, walkFilter };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@uniqu/core",
+  "version": "0.0.1",
+  "description": "Canonical query format types, tree walker, and utilities for Uniqu",
+  "license": "MIT",
+  "author": "Artem Maltsev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moostjs/uniqu.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/moostjs/uniqu/issues"
+  },
+  "homepage": "https://github.com/moostjs/uniqu/tree/main/packages/core#readme",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "pub": "pnpm publish --access public",
+    "test": "vitest"
+  }
+}