@noy-db/hub 0.7.0 → 0.8.0-pre.0

package/dist/kernel/query/civil-date.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Civil-date recognition for `dateTrunc()` (#1410).
+ *
+ * ## Why this module exists
+ *
+ * `dateTrunc()` buckets a value by resolving it to an instant and reading the
+ * civil calendar date that instant falls on in the declared `timeZone`. That is
+ * exactly right for a *timestamp*. It is a **category error** for a value that
+ * names no instant.
+ *
+ * `'2026-01-01'` — the shape `z.string().date()` produces — is a calendar date.
+ * ECMA-262 nonetheless resolves the ISO date-only form to **UTC midnight**, and
+ * converting that instant into any zone west of UTC moves it back a day. So
+ * `dateTrunc(..., 'month', { timeZone: 'America/New_York' })` silently bucketed
+ * `'2026-01-01'` into `2025-12` — a wrong year, no error, no warning. Correct at
+ * `+07` and UTC purely by accident of sign, which is what made it latent.
+ *
+ * ## The rule
+ *
+ * **A string carrying no timezone designator denotes CIVIL time and is used as
+ * written. Everything else is an instant and is converted through the zone.**
+ *
+ * That covers three shapes, all of which are zoneless:
+ *
+ * | input | denotes | why |
+ * |---|---|---|
+ * | `'2026-01-01'`, `'2026-01'`, `'2026'` | civil | ISO calendar forms; no time, no zone |
+ * | `'2026-01-01T08:30'`, `'2026-01-01 08:30:00.5'` | civil | offsetless date-time |
+ * | `'2026-01-01T00:00:00Z'`, `'…+07:00'`, `Date`, epoch ms | instant | carries, or *is*, a fixed point in time |
+ *
+ * The offsetless date-time is the subtle one and it is included **deliberately**.
+ * ECMA-262 parses it as *host-local*, which is the same defect one layer down:
+ * the bucket would depend on the machine the query ran on, and this module's
+ * whole premise (see `date-trunc.ts`) is that a host-local guess is never
+ * acceptable. Reading it as civil makes the result host-independent. The
+ * time-of-day is then simply discarded — every `dateTrunc` unit is a day or
+ * coarser, so no unit can observe it.
+ *
+ * ⚠️ **Loose, non-ISO strings are NOT recognised here** — `'01/01/2026'`,
+ * RFC-2822, and anything else `Date.parse` accepts by implementation extension
+ * stay on the instant path. Their parsing is implementation-defined, so there
+ * is no shape this module could claim to recognise correctly; a consumer who
+ * wants civil treatment should pass an ISO calendar date.
+ *
+ * ⚠️ **An out-of-range field is REFUSED, not rolled over.** V8's `Date.parse`
+ * accepts `'2026-02-30'` and yields 2 March; bucketing a typo under a
+ * wrong-but-plausible key is the failure mode this whole module exists to
+ * prevent, so a recognised-shape-but-impossible date throws instead.
+ */
+/** A calendar date with no instant and no zone. `m` is 1-12. */
+export interface CivilDate {
+    readonly y: number;
+    readonly m: number;
+    readonly d: number;
+}
+/**
+ * What a value denotes:
+ *   - a {@link CivilDate} — a zoneless calendar shape, use it as written;
+ *   - `'invalid'` — a recognised calendar shape naming no real day (see the
+ *     out-of-range note above); the caller refuses it with its own context;
+ *   - `undefined` — an instant, or an unrecognised shape: convert through the
+ *     declared zone exactly as before.
+ */
+export declare function civilDateOf(value: unknown): CivilDate | 'invalid' | undefined;

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

@@ -0,0 +1,40 @@
+/**
+ * Keyset cursors for `Query.page()` / `Query.after()` (#1346).
+ *
+ * A cursor names a POSITION — the `(sortKey, id)` of the last row a page
+ * served — not an offset. That is the whole point: a record inserted or
+ * deleted before the position cannot shift the next window, where
+ * `offset(n)` would re-serve or skip a row.
+ *
+ * The encoding is deliberately OPAQUE: consumers must treat the string as a
+ * token and pass it back verbatim, so the shape stays free to change. It is
+ * an encoding, NOT a signature — a cursor carries no secret and travels only
+ * as far as the caller sends it. The `shape` token is an integrity check
+ * against consumer mistakes (a cursor replayed against another sort order or
+ * another collection), not against an adversary.
+ *
+ * Portability: hub/src must run in a browser/Worker/Deno/Bun, so the base64
+ * step uses `btoa`/`atob` over a `TextEncoder` byte string — never `Buffer`.
+ */
+import type { OrderBy } from './builder.js';
+/** The decoded keyset a cursor names. */
+export interface KeysetCursor {
+    /** The sort spec + source identity this cursor was minted for. */
+    readonly shape: string;
+    /** The row's sort-key values, one per `orderBy` entry. */
+    readonly values: readonly unknown[];
+    /** The row's record id — the tiebreak that makes the keyset a total order. */
+    readonly id: string;
+}
+/**
+ * The token a cursor is bound to. Two queries may resume each other's cursors
+ * only when this matches: same source, same ordered sort spec.
+ */
+export declare function keysetShape(identity: string | undefined, orderBy: readonly OrderBy[]): string;
+export declare function encodeCursor(cursor: KeysetCursor): string;
+/**
+ * Decode a cursor and REFUSE it unless it was minted for `expectedShape`.
+ * Silently returning a nonsense window for a mismatched cursor is the
+ * failure mode this exists to prevent.
+ */
+export declare function decodeCursor(raw: string, expectedShape: string): KeysetCursor;

package/dist/kernel/query/distinct-key.d.ts

@@ -0,0 +1,98 @@
+/**
+ * ⚠️ #1458 — this file is SHARED, not Reduce's.
+ *
+ * It moved into `query/reduce/` with `distinct()` and moved straight back: the
+ * eager index layer (`with-lookup/indexing/eager-indexes.ts`) canonicalises its
+ * bucket keys through `stringifyBucketKey` / `isProbeableBucketKey`, so
+ * `@noy-db/hub/query` reaches it at runtime through the index fast path and the
+ * query-tiers closure check said so. Two callers with different lifetimes —
+ * `distinctKeyOf` for Reduce, the bucket-key pair for Find's indexes — and the
+ * canonicalisation must be ONE definition or a probe and a bucket disagree.
+ */
+/**
+ * The ONE definition of "are these two field values the same value?" (#1347).
+ *
+ * `distinct()`, `countDistinct()` and the eager hash index all have to answer
+ * that question, and they have to answer it IDENTICALLY — an index-backed
+ * `distinct()` reads bucket keys, a scanned one recomputes them, and the two
+ * are only allowed to be different code paths because they are not different
+ * definitions. So `stringifyBucketKey` lives here and `eager-indexes.ts`
+ * imports it rather than keeping a private twin; a change to one is a change
+ * to both by construction.
+ *
+ * ⚠️ THE KEY IS COMPUTED FROM THE **STORED** VALUE, never the decoded one.
+ * That is what makes a Via-covered field behave: money stores a scaled
+ * integer, and a legacy row written before the field was declared can hold a
+ * non-canonical spelling of it (`'0100'` where a canonical write produces
+ * `'100'`). Both denote 1.00, and `ViaPipeline.canonicalizeIndexKey` folds
+ * them onto one key. Dedup on the raw string reports two values; dedup on the
+ * FORMATTED string is worse still, because it makes distinctness depend on a
+ * locale the query layer does not have.
+ */
+/**
+ * Stringify a value into a stable bucket key.
+ *
+ * `null`/`undefined` produce a sentinel that records will never match (so we
+ * never index nullish values — `where('x', '==', null)` falls back to a
+ * linear scan). Numbers, booleans, strings, and Date objects are coerced via
+ * `String()`. Objects produce a sentinel that no real record will match —
+ * querying with object values is a code smell.
+ */
+export declare function stringifyBucketKey(value: unknown): string;
+/**
+ * Is this OPERAND one a hash bucket can answer for? (#1402)
+ *
+ * ⛔ Two of {@link stringifyBucketKey}'s outputs are not addresses, and a
+ * probe that treats them as one returns wrong rows SILENTLY — the #1402
+ * failure mode, and measured on `main` for ordinary non-Via fields:
+ *
+ *  - `'\0OBJECT\0'` is a COLLISION BUCKET, not a sentinel. Every non-Date
+ *    object-valued record in the collection sits in it, so
+ *    `where('obj', '==', { k: 1 })` matched `[a, b]` from the index against
+ *    `[]` from the scan (the scan compares by reference and matches
+ *    neither). The doc above says *"objects produce a sentinel that no real
+ *    record will match"*; that was true of the OPERAND and false of the
+ *    stored values, which is exactly the half that decides the answer.
+ *  - `'\0NULL\0'` is an empty bucket, because nullish values are never
+ *    inserted. Probing it returns `EMPTY_SET`, which reads as "no matches"
+ *    rather than "I cannot answer" — so `where('tag', '==', undefined)`
+ *    returned `[]` from the index against the records that genuinely have
+ *    no `tag` from the scan. The doc above already claims this case *"falls
+ *    back to a linear scan"*; it did not.
+ *
+ * Both are fixed at the PROBE, never at the bucketing: a caller that gets
+ * `false` here must return `null` (= "no index answer, scan it"), not an
+ * empty set. Bucketing is untouched, so no stored data or persisted sidecar
+ * moves.
+ *
+ * ⚠️ EAGER MODE ONLY, deliberately. `PersistedCollectionIndex` (lazy) has
+ * no scan to fall back TO — refusing there converts wrong rows into an
+ * `IndexRequiredError`, which is a behaviour decision of its own and is
+ * left open rather than smuggled in here.
+ */
+export declare function isProbeableBucketKey(value: unknown): boolean;
+/**
+ * The narrow slice of `ViaPipeline` a distinct key needs. Declared
+ * structurally so this module — kernel spine — does not have to reach into a
+ * `with-*` service, and so a caller holding only a money binder can satisfy it.
+ */
+export interface BucketKeyCanonicalizer {
+    canonicalizeIndexKey(field: string, rawValue: unknown): string | undefined;
+}
+/**
+ * The distinct key for one stored field value, or `undefined` when the value
+ * is NULLISH and therefore not a distinct value at all.
+ *
+ * ⭐ NULLISH IS EXCLUDED, DELIBERATELY. Three reasons, and the first is the
+ * one that decides it: the hash index does not hold nullish values, so an
+ * index-backed `distinct()` *cannot* report them, and a scan that did would
+ * make the two paths disagree — a correctness bug that only appears on the
+ * collections large enough to have an index. Second, it matches
+ * `COUNT(DISTINCT x)` and Dexie's `uniqueKeys()`, so nobody is surprised.
+ * Third, a caller who wants the nullish bucket can ask for it directly with
+ * `.where(field, '==', null)`, which is cheap and says what it means.
+ * (`groupBy()` goes the OTHER way and buckets nullish — that is not an
+ * inconsistency: a group key is a partition of the rows, a distinct value is
+ * a member of the field's value set.)
+ */
+export declare function distinctKeyOf(field: string, storedValue: unknown, via?: BucketKeyCanonicalizer): string | undefined;

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

@@ -0,0 +1,76 @@
+/**
+ * #1414 — the cold-collection gate.
+ *
+ * An eager collection that has never been read asynchronously holds an EMPTY
+ * cache. Before this module every synchronous query terminal answered out of
+ * that cache, so a cold collection reported `[]` / `0` / `false` with total
+ * confidence, forever, until some `list()`/`get()` hydrated it. Guards inherit
+ * the same source through `ReadOnlyVaultFacade`, and both failure directions
+ * were measured on shipped stable: a valid write refused because the guard's
+ * lookup came back empty, and — worse — a write that a warm instance REFUSES
+ * committing on a cold one, because the guard's `await …toArray()` saw nothing.
+ *
+ * **Empty and unable-to-answer are different facts.** Same posture as #1402
+ * ("an index that cannot answer must say so, not return nothing") and #1410.
+ *
+ * The fix has to serve two callers at once, and that is what shapes this
+ * module:
+ *
+ *  - the AWAITED caller (`await q.toArray()`, and therefore every guard, since
+ *    `GuardSpec.check` is async) must transparently hydrate and get the rows.
+ *    This is the half that closes the bypass.
+ *  - the SYNCHRONOUS caller must be told, loudly, that the answer it is about
+ *    to trust is not an answer.
+ *
+ * A terminal cannot both throw and be awaitable, so a cold terminal returns a
+ * **pending result**: a thenable that hydrates and re-runs the terminal when
+ * awaited, and throws {@link CollectionNotHydratedError} on every use that
+ * READS it — indexing, `.length`, iteration, spread, `.map()`, `JSON.stringify`,
+ * `String()`, `in`, `Object.keys`, arithmetic, any property read.
+ *
+ * ⛔ **THE EXACT BOUNDARY, enumerated — because "any other use" is what this
+ * doc used to say, and it was not true (#1462).** Two operations answer
+ * without reaching a proxy trap, and NEITHER CAN BE MADE TO THROW:
+ *
+ * | use | result | why it cannot throw |
+ * |---|---|---|
+ * | `typeof rows` | `'object'` | answered from the value's type, no trap |
+ * | `if (rows)` / `Boolean(rows)` — truthiness | `true` | `ToBoolean` never calls a trap |
+ *
+ * Do not try to close either with a `valueOf` returning `false` — that would
+ * resurrect the confident-wrong-answer this whole module exists to abolish, in
+ * the one shape nobody would ever check.
+ *
+ * ⭐ **`Array.isArray` used to be a third row, and it was the dangerous one.**
+ * `toArray()` is declared `T[]`, so `Array.isArray(rows) ? rows : []` is the
+ * ORDINARY defensive shape for the declared type — and it returned `[]` on a
+ * cold collection, restoring the silent empty read this module abolishes,
+ * behind code that looks like it handles the edge case. It is closed: the
+ * proxy's target is `[]`, and `IsArray` unwraps a proxy to its target, so the
+ * check answers `true` and the guard falls through to the throwing path. That
+ * cost one character of target and no change to the design — the report that
+ * found it assumed it needed a real array exotic object.
+ *
+ * ⚠️ **So the rule for anyone extending this: a use that reaches a trap must
+ * throw, and a use that cannot reach one must be IN THE TABLE ABOVE.** The
+ * table is pinned by `__tests__/1462-pending-result-surface.test.ts`, which
+ * also asserts this comment no longer claims a total guarantee — a probe
+ * written against "any other use" passes vacuously, because the phrase names
+ * no specific use for anything to contradict.
+ */
+export interface HydrationGate {
+    /** `<vault>/<collection>` — names the collection in the error. */
+    readonly label: string;
+    /** Collection name alone, for the error's structured field. */
+    readonly collection: string;
+    /** False only while the eager cache has never been bulk-loaded. */
+    isHydrated(): boolean;
+    /** Bulk-load the collection. Idempotent. */
+    hydrate(): Promise<void>;
+}
+/**
+ * Terminal wrapper. Returns `compute()` unchanged whenever the source is
+ * hydrated (or carries no gate at all — a plain-object source, a join source,
+ * a lazy collection), so the hot path is one property read and a boolean.
+ */
+export declare function gateTerminal<V>(gate: HydrationGate | undefined, terminal: string, compute: () => V): V;

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

@@ -1,25 +1,41 @@
 /**
- * Query DSL — barrel export.
+ * `@noy-db/hub/query` — **Find**, the always-on group of the query DSL (#1458).
  *
- * Public API:
- *   - `Query<T>` — chainable, immutable builder
- *   - `QuerySource<T>` — interface for record sources (Collection implements it)
- *   - `Operator` — comparison operators accepted by `where()`
- *   - `QueryPlan<T>` — serializable plan object
+ * ```ts
+ * import { Query } from '@noy-db/hub/query'
+ * invoices.query().where('status', '==', 'paid').orderBy('date', 'desc').limit(20).toArray()
+ * ```
  *
- * Tree-shakeable: importing this barrel without calling `query()` does not
- * pull in the executor's runtime, since `Query` is the only entry point.
+ * Predicate → sort → slice → hydrate, over one source: `where` (ten
+ * operators), `or`, `and`, `filter`, `wherePredicate`, `orderBy`, `limit`,
+ * `offset`, `page`, `after`, `first`, `toArray`, `count`, `exists`, `ids`,
+ * `toPlan`. Nothing here reaches a second collection, folds a result set, or
+ * re-runs on change.
+ *
+ * ⭐ **The other three groups are subpaths, and each is one import:**
+ *
+ * | group | import | brings |
+ * |---|---|---|
+ * | Live | `@noy-db/hub/query/live` | `subscribe`, `live` |
+ * | Reduce | `@noy-db/hub/query/reduce` | `aggregate`, `groupBy`, `window`, `distinct`, `dateTrunc` |
+ * | Relate | `@noy-db/hub/query/relate` | the joins, `traverse`, `explain` |
+ *
+ * The import is a SIDE EFFECT — it patches the methods onto `Query.prototype`
+ * and merges their types into `Query`, so one line at your app's entry serves
+ * the whole program. Calling a method whose group is not imported does not
+ * compile; if it reaches runtime through a cast, it throws
+ * {@link QueryExtensionMissingError} naming the subpath.
+ *
+ * ⚠️ **`@noy-db/hub` (the root barrel) imports all three**, so a consumer on
+ * the root barrel needs none of this and sees no change. The saving is for
+ * consumers who import this subpath directly.
  */
-export { Query, executePlan, DEFAULT_CROSS_JOIN_MAX_ROWS } from './builder.js';
+export { Query, executePlan } from './builder.js';
 export type { QueryPlan, QuerySource, OrderBy } from './builder.js';
 export type { Operator, Clause, FieldClause, FilterClause, GroupClause, CrossJoinClause } from './predicate.js';
 export { evaluateClause, evaluateFieldClause, readPath } from './predicate.js';
 export { CollectionIndexes } from '../../with-lookup/indexing/eager-indexes.js';
 export type { IndexDef, HashIndex } from '../../with-lookup/indexing/eager-indexes.js';
-export { applyJoins, DEFAULT_JOIN_MAX_ROWS, resetJoinWarnings } from './join.js';
-export type { JoinLeg, JoinContext, JoinableSource, JoinStrategy } from './join.js';
-export { buildLiveQuery } from './live.js';
-export type { LiveQuery, LiveUpstream } from './live.js';
 export { ScanBuilder } from './scan-builder.js';
-export type { ScanPageProvider } from './scan-builder.js';
-export { GroupCardinalityError, IndexRequiredError, IndexWriteFailureError, JoinTooLargeError, DanglingReferenceError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, FieldNotQueryableError, } from '../errors.js';
+export type { ScanPageProvider, MultiReduceResult } from './scan-builder.js';
+export { IndexRequiredError, IndexWriteFailureError, FieldNotQueryableError, UnsafePatternError, QueryExtensionMissingError, } from '../errors.js';

package/dist/kernel/query/internal/core.d.ts

@@ -0,0 +1,30 @@
+/**
+ * #1458 — how an extension group's methods reach `Query.prototype`.
+ *
+ * Each group defines its half of the builder as a MIXIN CLASS whose method
+ * bodies moved out of `builder.ts` unchanged — `this.plan`, `this.source`,
+ * `this.joinContext` and the rest still resolve, because TypeScript's
+ * `private` is a compile-time construct and a method installed on the
+ * prototype reads them like any other property. The mixin declares those
+ * fields with `declare`, which emits nothing.
+ *
+ * ⭐ **Why a mixin CLASS rather than a file of `Query.prototype.x = function`
+ * assignments.** The bodies are the point: several are 100+ lines carrying
+ * prose that explains a decision, and a mechanical rewrite into assignment
+ * form would have touched every one of them. As class methods they moved
+ * byte-for-byte, so the diff shows a relocation rather than a rewrite — and an
+ * overload set (`join`, `joinOn`, `aggregate`, `groupBy` all have them)
+ * survives, which an assignment form cannot express.
+ */
+/**
+ * Copy a mixin's prototype methods onto a target prototype, replacing the Find
+ * stubs.
+ *
+ * `getOwnPropertyNames` rather than `Object.assign`: class methods are
+ * non-enumerable prototype properties, so `assign` copies nothing at all —
+ * silently, leaving every stub in place. Descriptors are copied whole so a
+ * getter stays a getter.
+ */
+export declare function installMethods(target: object, mixin: {
+    prototype: object;
+}): void;

package/dist/kernel/query/internal/hooks.d.ts

@@ -0,0 +1,22 @@
+import type { Clause, CrossJoinClause } from '../predicate.js';
+import type { JoinableSource, JoinContext, JoinLeg } from '../relate/join.js';
+import type { OrderBy } from '../builder.js';
+/** The Relate entry points Find's executor calls. Every one is join-conditional. */
+export interface RelateHooks {
+    applyJoins(rows: readonly unknown[], joins: readonly JoinLeg[], ctx: JoinContext, locale?: string): unknown[];
+    splitAroundJoins(clauses: readonly Clause[], joins: readonly JoinLeg[]): {
+        preJoin: readonly Clause[];
+        postJoin: readonly Clause[];
+    };
+    orderReferencesJoinAlias(orderBy: readonly OrderBy[], joins: readonly JoinLeg[]): boolean;
+    joinsDropLeftRows(joins: readonly JoinLeg[]): boolean;
+    applyCrossJoin(leftRel: unknown[], clause: CrossJoinClause, rightSource: JoinableSource): unknown[];
+}
+/** Called once by `@noy-db/hub/query/relate` on load. */
+export declare function installRelateHooks(hooks: RelateHooks): void;
+/**
+ * The Relate hooks, or the actionable error. Read only from a guarded branch —
+ * see this module's header for why that makes the throw unreachable for a
+ * consumer who never built a join.
+ */
+export declare function relateHooks(): RelateHooks;

package/dist/kernel/query/internal/maintenance.d.ts

@@ -0,0 +1,43 @@
+import type { DeclaredPredicate, InternalSource, QueryPlan } from '../builder.js';
+import type { JoinContext } from '../relate/join.js';
+import type { ReduceStrategy } from '../../../with-lookup/reduce/strategy.js';
+/** @internal — copied onto `Query.prototype` by both Live and Reduce. */
+export declare class MaintenanceMethods {
+    protected readonly source: InternalSource;
+    protected readonly plan: QueryPlan;
+    protected readonly joinContext: JoinContext | undefined;
+    protected readonly reduceStrategy: ReduceStrategy;
+    protected readonly predicates: ReadonlyMap<string, DeclaredPredicate> | undefined;
+    protected decodeVia: (records: readonly unknown[], locale?: string) => unknown[];
+    /**
+     * Build the #1341 delta maintainer for this plan, or `undefined` when the
+     * plan shape or the source cannot support one (the query then re-runs in
+     * full, exactly as it did before #1341).
+     *
+     * Everything the maintainer needs is taken from THIS query so the two paths
+     * cannot diverge: `matches` is the same `filterRecords` call the eager
+     * pipeline makes, `compare` is the same comparator `sortRecords` sorts with,
+     * and `decode` is the same Via result decode `toArray()` applies after
+     * slicing.
+     */
+    private incrementalMaintainer;
+    /**
+     * Build the #1341 grouped-maintenance seam for this plan, or `undefined`
+     * when the plan shape or the source cannot support one (a grouped live
+     * reduction then re-runs in full, exactly as it did before).
+     *
+     * Same whitelist and the same three inputs `incrementalMaintainer('records')`
+     * uses, for the same reason: `.groupBy()`'s record pipeline IS
+     * `.aggregate()`'s — `candidateRecords` + `filterRecords`, with no sort, no
+     * window and no Via result decode — so `orderBy`/`limit` are stripped before
+     * the whitelist is asked. `matches` is the same `filterRecords` call the
+     * eager pipeline makes, which is what stops the two paths from drifting.
+     *
+     * The one addition is `project`: `.groupBy(dateTrunc(...))` (#1350) stamps a
+     * derived key onto each row AFTER filtering and before bucketing, and the
+     * maintainer has to stamp it too or it would bucket on a field that is not
+     * there. It is a pure per-record map, which is the only kind of projection
+     * this hook may carry.
+     */
+    private groupMaintenance;
+}