@noy-db/hub 0.3.0-pre.9 → 0.3.0

package/dist/kernel/query/join.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Query DSL `.join()` — eager, single-FK, intra-vault joins.
+ *
+ * resolves a ref()-declared foreign key into an attached
+ * right-side record under an alias, using one of two planner paths
+ * selected automatically:
+ *
+ *   - **nested-loop** — right-side source exposes `lookupById`, so
+ *     each left row costs O(1). This is the common path for joins
+ *     against a Collection, which backs `lookupById` with a Map
+ *     lookup.
+ *   - **hash** — right-side has only `snapshot()`. Build a
+ *     `Map<id, record>` once, probe per left row. Same asymptotic
+ *     cost for our collections, but the path exists as a fallback
+ *     for custom QuerySource implementations and as an explicit
+ *     test-only override via `{ strategy: 'hash' }`.
+ *
+ * Scope:
+ *
+ *   - Equi-joins on declared `ref()` fields only. Joins on
+ *     undeclared fields throw at plan time with an actionable error
+ *     naming the field and collection.
+ *   - Same-vault only. Cross-vault correlation goes
+ *     through `queryAcross`; this is an architectural
+ *     invariant, not a limitation we plan to lift.
+ *   - Hard row ceiling via `JoinTooLargeError` — default 50k per
+ *     side, override via `{ maxRows }`. Warns at 80% of the ceiling
+ *     on the existing warn channel.
+ *   - Three ref-mode behaviors on dangling refs:
+ *     strict → `DanglingReferenceError`,
+ *     warn → attach `null` with a one-shot warning,
+ *     cascade → attach `null` silently (cascade is a delete-time
+ *     mode; any dangling refs still present at read time are
+ *     mid-flight cascades or orphans from earlier, not a DSL error).
+ *
+ * Partition-awareness seam:
+ *
+ * Every `JoinLeg` carries a `partitionScope` field that is always
+ * `'all'` in. The executor never reads this field.
+ * partition-aware joins will start populating it from `where()`
+ * predicates on the partition key without changing the planner's
+ * external shape — this is the whole reason it exists now.
+ *
+ * Joins stay OUT of the ledger: reads don't touch `_ledger/`,
+ * including joined reads.
+ */
+import type { RefDescriptor, RefMode } from '../refs.js';
+/** Planner strategy for a single join leg. Auto-selected unless overridden. */
+export type JoinStrategy = 'hash' | 'nested';
+/** Default per-side row ceiling before `.join()` throws `JoinTooLargeError`. */
+export declare const DEFAULT_JOIN_MAX_ROWS = 50000;
+/**
+ * Internal representation of a single join leg in the query plan.
+ *
+ * This is the primary place where  constraint #1 is honored:
+ * every leg carries a `partitionScope` field that is always `'all'`
+ * in and is never read by the executor. partition-aware
+ * joins will start populating it from `where()` predicates on the
+ * partition key without changing the planner's external shape.
+ */
+export interface JoinLeg {
+    /** Field on the left-side record holding the foreign key value. */
+    readonly field: string;
+    /** Alias key under which the joined right-side record attaches. */
+    readonly as: string;
+    /** Target collection name, resolved from the `ref()` declaration. */
+    readonly target: string;
+    /** Ref mode controlling behavior on dangling refs at read time. */
+    readonly mode: RefMode;
+    /** Manual planner strategy override. `undefined` → auto-select. */
+    readonly strategy: JoinStrategy | undefined;
+    /** Per-side row ceiling override. `undefined` → DEFAULT_JOIN_MAX_ROWS. */
+    readonly maxRows: number | undefined;
+    /**
+     * Partition scope for future partition-aware joins. Always `'all'`
+     * today — the executor never reads this field. Future versions will
+     * populate it from `where()` predicates without breaking the
+     * planner's external shape. Do not remove even though it looks
+     * unused today — that's the whole point of having it.
+     */
+    readonly partitionScope: 'all' | readonly string[];
+    /**
+     * When `true`, this is a dictionary join. The executor
+     * resolves the left-field value against the dict snapshot and
+     * attaches `{ ...labels, key }` rather than a right-side record.
+     * `target` holds the dictionary name (not a collection name).
+     */
+    readonly isDictJoin?: true;
+}
+/**
+ * Minimal shape of a joinable right-side record source.
+ *
+ * Collections implement this structurally via their `QuerySource`;
+ * sources without `lookupById` force the hash-join fallback. Kept as
+ * a thin interface so tests can wire up plain-object sources without
+ * pulling in the full Collection class.
+ *
+ * The optional `subscribe` is used by `Query.live()` to merge
+ * right-side change streams into the live re-run trigger. Sources
+ * that omit `subscribe` still work for live joins — they just
+ * don't drive re-fires when their right side mutates. Collection
+ * implements `subscribe` by hooking into the existing per-
+ * vault event emitter.
+ */
+export interface JoinableSource {
+    snapshot(): readonly unknown[];
+    lookupById?(id: string): unknown;
+    /**
+     * Default locale a label-resolving query falls back to when the query
+     * itself is locale-less. Set by a `staticDict()`-backed source from its
+     * `displayLocale` so `{ by: 'label' }` resolves under a locale-less read.
+     * Plain `_dict_*`-backed sources omit it.
+     */
+    readonly displayLocale?: string;
+    /**
+     * Sync present-for-join dressing (#626 retirement, #650 Task 6) — when
+     * present and the query carries a locale, each joined right-side record
+     * is passed through this hook (built by the right-side `Collection` from
+     * its own i18n-text + lookup-label bindings) BEFORE it is attached under
+     * the leg's alias — so a joined `i18nText` field resolves to a string
+     * (not a raw `{ locale }` map) and a joined lookup field gains its
+     * `<field>Label`. Locale-less queries leave joined fields raw
+     * (consistent with a locale-less read). Replaces the old `i18nFields`
+     * data field — the join executor no longer resolves i18n locale itself,
+     * it just calls this hook.
+     */
+    readonly presentForJoin?: (record: unknown, locale: string) => unknown;
+    /**
+     * Subscribe to mutations on this source. The callback fires
+     * AFTER the underlying record set has been updated. Returns an
+     * unsubscribe function. Optional — sources without this method
+     * cannot trigger live-join re-fires from their side.
+     */
+    subscribe?(cb: () => void): () => void;
+}
+/**
+ * Join resolution context attached to a `Query` when it's constructed
+ * from a `Collection`. Holds everything the `.join()` method needs to
+ * translate a field name into a target collection + ref mode, and
+ * everything the executor needs to read the right side.
+ *
+ * Kept as a structural interface so `Vault` can implement it
+ * without `Query` needing to import `Vault` (circular-import
+ * avoid). The Collection wires this up in its `query()` method using
+ * the `joinResolver` back-reference the Vault passes in.
+ */
+export interface JoinContext {
+    /** Name of the left-side (owning) collection. */
+    readonly leftCollection: string;
+    /**
+     * The owning collection's default locale. Used to resolve joined
+     * i18n fields at the `join` layer when a terminal call doesn't pass an
+     * explicit locale — so `openVault({ locale })` flows to joins like it does
+     * to `get`/`list`. A per-call `toArray({ locale })` overrides it.
+     */
+    readonly defaultLocale?: string;
+    /** Look up a `RefDescriptor` by field name on the left collection. */
+    resolveRef(field: string): RefDescriptor | null;
+    /** Resolve a right-side source by target collection name. */
+    resolveSource(collectionName: string): JoinableSource | null;
+    /**
+     * Resolve a dictKey join source. Returns a `JoinableSource`
+     * whose snapshot exposes `{ key, ...labels }` records, keyed by the
+     * stable dictionary key. `null` when the field is not a dictKey.
+     *
+     * The source is built from the compartment's in-memory dictionary
+     * snapshot — same data as `DictionaryHandle.list()`, O(1) per lookup.
+     */
+    resolveDictSource?(field: string): JoinableSource | null;
+}
+/**
+ * Apply every join leg in the plan against a base set of left-side
+ * rows. Called by the query executor after `where` / `orderBy` /
+ * `offset` / `limit` have narrowed the left set.
+ *
+ * Each leg attaches a `leg.as` field to every row. Returns a new
+ * array of plain objects — the original left rows are not mutated
+ * (structural sharing is fine for the inner fields, but the
+ * top-level object is a fresh clone so consumers can further mutate
+ * safely).
+ *
+ * **Ordering:** joins run AFTER orderBy / limit / offset in v1.
+ * This keeps the planner simple and means queries like "top 10
+ * invoices with client" sort and paginate the left side first, then
+ * join. Sorting *by* a joined field is out of scope for  — users
+ * can post-sort the result array in userland or wait for
+ * (multi-FK chaining) which can be layered on top.
+ *
+ * **Multi-FK chaining:** each leg's `maxRows` is enforced
+ * against the current left-row count independently. Because
+ * joins are equi-joins on the target's primary key (one-to-one or
+ * one-to-null), the left row count is constant across legs — no
+ * cartesian blowup. The per-leg left-side check is still necessary
+ * so that a later leg with a tighter ceiling correctly fires on a
+ * query like `.join('a', { maxRows: 100_000 }).join('b', { maxRows: 50 })`,
+ * which should throw on the second leg if the left set exceeds 50.
+ */
+export declare function applyJoins(rows: readonly unknown[], joins: readonly JoinLeg[], context: JoinContext, locale?: string): unknown[];
+/**
+ * Test-only: reset the join warning deduplication state between
+ * tests. Production code never calls this — the dedup state is
+ * intentionally process-scoped so a noisy query doesn't spam the
+ * console once per component render.
+ */
+export declare function resetJoinWarnings(): void;

package/dist/kernel/query/live.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Reactive query primitive — `query.live()`.
+ *
+ * produces a `LiveQuery<T>` that re-runs the query and
+ * updates its `value` whenever any source feeding it (the left
+ * collection AND every right-side collection a join leg points at)
+ * mutates.
+ *
+ * Framework-agnostic by design. The Vue layer wraps a `LiveQuery`
+ * in a Vue `Ref<T[]>` by subscribing once and copying `value` into
+ * the ref on every notification. React/Solid/Svelte adapters do the
+ * same with their own primitives. Core never depends on a UI
+ * framework.
+ *
+ * **Error semantics.** A `.live()` query may throw at re-run time —
+ * a strict-mode `DanglingReferenceError` is the most common case
+ * (a right-side record was deleted out-of-band, leaving a left
+ * row's FK pointing at nothing). When the re-run throws, the
+ * `LiveQuery` catches the error and stores it in the `error`
+ * field; it does NOT propagate the throw out of the source's
+ * change handler, because doing so would tear down whatever
+ * upstream emitter is dispatching. Listeners check `error` after
+ * each notification and render an error state in the UI.
+ *
+ * **Dedup of right-side subscriptions.** A multi-FK chain that
+ * joins the same target twice (e.g.
+ * `.join('billingClientId').join('shippingClientId')`, both
+ * pointing at `clients`) only subscribes to that target once. We
+ * dedup by target collection name, on the assumption that
+ * `resolveSource(name)` returns a single subscribable source per
+ * vault + name. Vault's `resolveSource` reads from
+ * `collectionCache` so this assumption holds.
+ *
+ * **What .live() does NOT do in v1:**
+ *   - No granular delta updates — the whole query re-runs on every
+ *     change. Granular delta tracking is a v2 optimization once
+ *     the API is stable.
+ *   - No batching of bursty changes — one event in, one re-run
+ *     out. Batching with microtask coalescing is a v2 enhancement.
+ *   - No async notifications — every notification is synchronous
+ *     within the source's change handler.
+ *   - No re-planning under live mutations — the planner picks once
+ *     at subscription time and reuses the same plan for every
+ *     re-run.
+ */
+/**
+ * The reactive primitive returned by `Query.live()`.
+ *
+ * Listeners can read the current `value` snapshot at any time and
+ * subscribe to changes via `.subscribe(cb)`. The `error` field
+ * carries the most recent re-run error, if any — read it after
+ * each notification to render error state.
+ *
+ * Always call `stop()` when the live query is no longer needed.
+ * Without it, the upstream change-stream subscriptions stay live
+ * forever and the query keeps re-running on every mutation.
+ */
+export interface LiveQuery<T> {
+    /**
+     * Current snapshot of the query result. Updated in place on
+     * every upstream change. The reference returned is the same
+     * `readonly T[]` array — consumers that want change detection by
+     * reference should copy: `const arr = [...live.value]`.
+     */
+    readonly value: readonly T[];
+    /**
+     * Most recent re-run error, or `null` on success. Set when the
+     * executor throws (e.g. `DanglingReferenceError` in strict mode
+     * after a right-side delete). Cleared on the next successful
+     * re-run.
+     */
+    readonly error: Error | null;
+    /**
+     * Register a notification callback. Fires AFTER `value` and
+     * `error` have been updated for a given upstream change.
+     * Returns an unsubscribe function.
+     *
+     * The first call to `subscribe` does NOT fire the callback
+     * immediately — call sites that want the initial value should
+     * read `live.value` directly before subscribing.
+     */
+    subscribe(cb: () => void): () => void;
+    /**
+     * Tear down every upstream subscription and clear the listener
+     * set. Idempotent — calling twice is safe. After `stop()`, the
+     * query no longer re-runs and `subscribe()` becomes a no-op
+     * (the returned unsubscribe is still callable and is also a
+     * no-op).
+     */
+    stop(): void;
+}
+/**
+ * Internal subscription handle for an upstream source — left or
+ * right side. The contract is just `subscribe(cb): unsubscribe`,
+ * matching the existing `QuerySource.subscribe` and the new
+ * `JoinableSource.subscribe` (added in ).
+ */
+export interface LiveUpstream {
+    subscribe(cb: () => void): () => void;
+}
+/**
+ * Build a LiveQuery from a `recompute` callback (typically the
+ * Query's bound `toArray`) and a list of upstream sources to
+ * subscribe to.
+ *
+ * The recompute fires once synchronously to populate the initial
+ * value, then re-fires every time any upstream notifies. Errors
+ * thrown by recompute are caught and stored in `error` instead of
+ * propagating — see the file docstring for the rationale.
+ */
+export declare function buildLiveQuery<T>(recompute: () => T[], upstreams: readonly LiveUpstream[]): LiveQuery<T>;

package/dist/kernel/query/predicate.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Operator implementations for the query DSL.
+ *
+ * All predicates run client-side, AFTER decryption — they never see ciphertext.
+ * Field clauses over a Via-covered field (e.g. money) carry their own
+ * evaluator closure (see {@link FieldClause.via}), so this module has no
+ * dependency on any Via feature's implementation — still tree-shakeable.
+ */
+/** Comparison operators supported by the where() builder. */
+export type Operator = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'contains' | 'startsWith' | 'between';
+/**
+ * A single field comparison clause inside a query plan.
+ * Plans are JSON-serializable, so this type uses primitives only.
+ */
+export interface FieldClause {
+    readonly type: 'field';
+    readonly field: string;
+    readonly op: Operator;
+    readonly value: unknown;
+    /**
+     * Present when `field` is covered by a Via feature binding (e.g. a
+     * declared money field): the opaque payload built by the binding's
+     * `buildClause` at query BUILD time, plus a closure that evaluates it
+     * per record via the binding's `evaluateClause`. Attached by
+     * `Query.where()` / `ScanBuilder.where()` when `source.via` covers the
+     * field. The closure keeps this module free of any dependency on a
+     * Via feature's implementation — clauses are in-memory only, never
+     * serialized, so carrying a function here is safe.
+     */
+    readonly via?: {
+        readonly brand: string;
+        readonly payload: unknown;
+        readonly evaluate: (actual: unknown, op: string) => boolean;
+        /**
+         * The binding's `indexProbe` result for this clause's op/payload
+         * (#625) — the STORED-form operand `candidateRecords()` (`kernel/
+         * query/builder.ts`) can hand to `CollectionIndexes.lookupEqual`/
+         * `lookupIn` for a fast path. `undefined` (no `indexProbe` hook, or
+         * the binding declined to probe this op) means the field must fall
+         * back to a linear scan via `evaluate` above.
+         */
+        readonly indexValue?: unknown;
+    };
+}
+/**
+ * A user-supplied predicate function escape hatch. Not serializable.
+ *
+ * The predicate accepts `unknown` at the type level so the surrounding
+ * Clause type can stay non-parametric — this keeps Collection<T> covariant
+ * in T at the public API surface. Builder methods cast user predicates
+ * (typed `(record: T) => boolean`) into this shape on the way in.
+ */
+export interface FilterClause {
+    readonly type: 'filter';
+    readonly fn: (record: unknown) => boolean;
+}
+/**
+ * A declared deterministic predicate reference. The query
+ * builder produces this via `.wherePredicate(name, ctx?)` when a
+ * Query has been augmented with a predicates map (typically by the
+ * materialized-view registry).
+ *
+ * `predicateHash` is the consumer-supplied stable hash for the
+ * function body; `ctxHash` is the canonical-JSON SHA-256 of `ctx`.
+ * Both fold into the MV's `queryHash` so a function or ctx change
+ * forces refresh on next visit.
+ *
+ * `fn` is resolved at builder time from the predicates map and
+ * embedded directly — so `evaluateClause` can fire it without a
+ * runtime lookup.
+ */
+export interface WherePredicateClause {
+    readonly type: 'wherePredicate';
+    readonly name: string;
+    readonly ctx: unknown;
+    readonly predicateHash: string;
+    readonly ctxHash: string;
+    readonly fn: (record: unknown, ctx?: unknown) => boolean;
+}
+/** A logical group of clauses combined by AND or OR. */
+export interface GroupClause {
+    readonly type: 'group';
+    readonly op: 'and' | 'or';
+    readonly clauses: readonly Clause[];
+}
+/**
+ * Cartesian-product expansion clause. Appended to `QueryPlan.clauses`
+ * by `Query.crossJoin()`. Processed in declaration order by
+ * `executeClausePipeline` — NOT by `evaluateClause` (which is a
+ * per-record predicate and throws on this type).
+ */
+export interface CrossJoinClause {
+    readonly type: 'crossJoin';
+    /** Target collection name to cross-join against. */
+    readonly target: string;
+    /** Alias under which the right-side record is exposed on each result row. */
+    readonly as: string;
+    /**
+     * Lateral filter callback. `undefined` → full cartesian product.
+     * Two call shapes:
+     *   - Subset:    `(left) => TTarget[]`            — returns the right rows for this left row
+     *   - Predicate: `(left) => (right) => boolean`   — executor materializes then filters
+     */
+    readonly on?: (left: unknown) => unknown[] | ((right: unknown) => boolean);
+    /** When `on:` was supplied as `{ predicate: name }`, the name is stored here for queryHash. */
+    readonly onPredicateName?: string;
+    /** Per-clause row ceiling override. `undefined` → `DEFAULT_CROSS_JOIN_MAX_ROWS`. */
+    readonly maxRows?: number;
+}
+export type Clause = FieldClause | FilterClause | WherePredicateClause | GroupClause | CrossJoinClause;
+/**
+ * Read a possibly nested field path like "address.city" from a record.
+ * Returns undefined if any segment is missing.
+ */
+export declare function readPath(record: unknown, path: string): unknown;
+/**
+ * Evaluate a single field clause against a record.
+ * Returns false on type mismatches rather than throwing — query results
+ * exclude non-matching records by definition.
+ */
+export declare function evaluateFieldClause(record: unknown, clause: FieldClause): boolean;
+/**
+ * Evaluate any clause (field / filter / group) against a record.
+ * The recursion depth is bounded by the user's query expression — no risk of
+ * blowing the stack on a 50K-record collection.
+ *
+ * `fnRecord`, when provided, is the view handed to USER CALLBACK clauses
+ * (`filter` / `wherePredicate`) instead of `record` — the executor passes
+ * the money-decoded view there so user code never sees the stored
+ * scaled-int form, while field clauses keep evaluating against the raw
+ * record (their money operands are pre-quantized to that space).
+ */
+export declare function evaluateClause(record: unknown, clause: Clause, fnRecord?: unknown): boolean;
+/**
+ * Does the clause list contain any user-callback clause (filter /
+ * wherePredicate), at any group nesting depth? Used by executors to
+ * decide whether the per-record decoded view needs materializing.
+ */
+export declare function hasFnClause(clauses: readonly Clause[]): boolean;