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

package/dist/with-formula/overlay-views/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Read-shadow overlay primitive. Binds an MV's read-only base output
+ * to a separate user-writable overlay collection; reads merge via a
+ * single shadow predicate, writes route to the overlay.
+ *
+ * v2 ships the read-shadow variant only — arbitrary `mergePolicy`
+ * callbacks are deferred to v3.
+ */
+export interface OverlayedViewStrategy {
+    /**
+     * Virtual collection name. `vault.collection(name)` returns a
+     * proxy that merges `base` and `overlay` per the shadow rule.
+     * Writes to the proxy route to the `overlay` collection. The name
+     * must be unique within the vault — collisions with MV outputs or
+     * concrete source collections throw `OverlayNameCollisionError` at
+     * vault open.
+     */
+    name: string;
+    /**
+     * The collection providing the default rows. Typically an MV's
+     * output collection. Must be a CONCRETE collection (a real source
+     * or an MV output) — not itself another overlay's virtual name.
+     * Multi-overlay stacking is a v3 non-goal; the constraint is
+     * enforced at vault open via `OverlayBaseIsVirtualError`.
+     */
+    base: string;
+    /**
+     * User-writable collection that carries overrides. Must be a real,
+     * vault-known collection that is NOT an MV-output collection. The
+     * overlay's `withGuard` / `withDerivation` registrations apply to
+     * direct writes; the virtual layer's `put(record)` also flows
+     * through the overlay's normal write pipeline.
+     */
+    overlay: string;
+    /**
+     * Single-field shadow predicate. When `overlay[shadowField] ===
+     * shadowValue` for a given id, virtual-collection reads of that id
+     * return the overlay row; otherwise reads return the base row.
+     *
+     * Niwat's canonical example: `dataStatus === 'override'` flips a
+     * row into operator-controlled mode.
+     *
+     * No callback merge, no priority lattice, no field-level merge —
+     * v2 stays explicitly narrow.
+     */
+    shadowField: string;
+    shadowValue: unknown;
+    /**
+     * Optional field-level merge mode. When present, a
+     * row whose `shadowField` does NOT equal `shadowValue` is no longer
+     * forced all-base: the rules below let an intermediate status pull a
+     * declared subset of fields from the overlay while every other field
+     * still comes from the base row.
+     *
+     * Absent `mergeMode` preserves the original binary behaviour
+     * exactly — overlay wins entirely iff `shadowField === shadowValue`,
+     * otherwise base wins.
+     */
+    mergeMode?: OverlayFieldMergeMode;
+}
+/**
+ * One field-level merge rule. When the overlay row's `shadowField`
+ * equals `whenStatus`, the merged row takes `overlayFields` from the
+ * overlay and every other field from the base row.
+ *
+ * Always include `shadowField` in `overlayFields` so the status value
+ * itself propagates to the merged read (otherwise the merged row would
+ * carry the base's status, which is usually `undefined`).
+ */
+export interface OverlayFieldMergeRule {
+    /** The `overlay[shadowField]` value this rule matches. */
+    readonly whenStatus: unknown;
+    /**
+     * Field names pulled from the overlay row when this rule matches.
+     * Fields absent on the overlay row are skipped (base value kept).
+     */
+    readonly overlayFields: readonly string[];
+}
+/**
+ * Field-level merge configuration. `rules` are evaluated in
+ * declaration order and the FIRST rule whose `whenStatus` matches the
+ * overlay's `shadowField` wins; later rules are not consulted.
+ *
+ * The binary shadow check (`shadowField === shadowValue` → overlay
+ * wins entirely) is always the implicit, highest-priority rule applied
+ * BEFORE any `rules` entry, so adding `mergeMode` never changes the
+ * full-override path.
+ */
+export interface OverlayFieldMergeMode {
+    readonly kind: 'field-merge';
+    readonly rules: readonly OverlayFieldMergeRule[];
+}
+/** Returned by `withOverlayedView()` and consumed by `createNoydb`. */
+export interface OverlayedViewStrategyHandle {
+    readonly __noydb_strategy: 'overlayed-view';
+    readonly spec: OverlayedViewStrategy;
+}

package/dist/with-formula/overlay-views/virtual-collection.d.ts

@@ -0,0 +1,90 @@
+import type { Collection } from '../../kernel/collection.js';
+import type { OverlayedViewStrategy } from './types.js';
+/**
+ * Virtual-collection proxy returned by `vault.collection(overlayName)`
+ * when `overlayName` is a registered `withOverlayedView`.
+ *
+ * Implements the core `Collection<T>`-shaped read/write surface with
+ * merge-on-read semantics:
+ *   - `get(id)`: overlay row wins iff `overlay[shadowField] === shadowValue`;
+ *     when `spec.mergeMode` is set, an intermediate status may instead pull
+ *     a declared subset of fields from the overlay over the base
+ *   - `list()` / `.query()`: union of ids, per-id merge applied
+ *   - `put(record)` / `put(id, record)`: routes to overlay; id derived
+ *     via the base MV's `rowKey` (validated on the two-arg form)
+ *   - `delete(id)`: removes the overlay row only; base stays
+ *
+ * Reactive APIs (`live`, `subscribe`, `query().live()`) are out of
+ * scope for this release and surface as "not yet implemented" — wired in a
+ * future sub-issue.
+ */
+export declare class OverlayedCollection<T extends Record<string, unknown> = any> {
+    private readonly spec;
+    private readonly baseCollection;
+    private readonly overlayCollection;
+    private readonly baseRowKey;
+    constructor(spec: OverlayedViewStrategy, baseCollection: Collection<T>, overlayCollection: Collection<T>, baseRowKey: ((row: Record<string, unknown>) => string) | undefined);
+    /**
+     * Convenience accessors for advanced callers that need to bypass the
+     * virtual layer (bulk imports, direct overlay queries). Mirrors the
+     * spec's "direct writes to the underlying overlay collection skip
+     * the validation" escape hatch.
+     */
+    readonly overlay: {
+        rowKey: (row: Record<string, unknown>) => string;
+    };
+    /** Get the merged row by id. */
+    get(id: string): Promise<T | null>;
+    /** List union of base + overlay ids, applying the merge per row. */
+    list(): Promise<T[]>;
+    /**
+     * Write to the overlay. Two forms:
+     * - `put(record)`: id is derived via the base MV's `rowKey(record)`.
+     *   Throws if the base isn't an MV.
+     * - `put(id, record)`: validates `id === rowKey(record)`; throws
+     *   `OverlayIdMismatchError` on mismatch.
+     */
+    put(idOrRecord: string | T, maybeRecord?: T): Promise<void>;
+    /**
+     * Remove the overlay row only. Idempotent (no-op on absent).
+     * The base row is untouched — if a base row exists for `id`,
+     * subsequent reads return it.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Merge a single id's overlay + base rows into the visible row.
+     *
+     * Priority (first match wins):
+     *  1. Binary shadow win — overlay present AND
+     *     `overlay[shadowField] === shadowValue` → return the overlay row
+     *     entirely. This stays FIRST so the original binary behaviour is
+     *     unchanged whether or not `mergeMode` is configured.
+     *  2. Field-level merge — overlay present, `mergeMode` configured,
+     *     and a rule whose `whenStatus` equals `overlay[shadowField]`.
+     *     The matched rule pulls its `overlayFields` (those present on
+     *     the overlay row) on top of the base row. With no base row, the
+     *     overlay row is returned as-is.
+     *  3. Fallback — return the base row (possibly `null`). An
+     *     overlay-only row that qualifies under neither (1) nor (2) and
+     *     has no base is therefore NOT surfaced.
+     */
+    private mergeRows;
+    /** @throws — chainable Query<T> over a virtual collection is deferred. */
+    query(): never;
+    /** @throws — change-stream subscription over a virtual collection is deferred. */
+    subscribe(): never;
+    /** @throws — live query over a virtual collection is deferred. */
+    live(): never;
+    /** @throws — async iteration over a virtual collection is deferred. */
+    scan(): never;
+    /** @throws — lazy-mode query is not applicable to virtual collections. */
+    lazyQuery(): never;
+    /** @throws — bulk-atomic put is deferred to a future MV sub-issue. */
+    putManyAtomic(): never;
+    /** @throws — bulk delete is deferred to a future MV sub-issue. */
+    deleteMany(): never;
+    /** @throws — `.first()` over a virtual collection is deferred. */
+    first(): never;
+    /** @throws — `.count()` over a virtual collection is deferred. */
+    count(): never;
+}

package/dist/with-formula/overlay-views/with-overlayed-view.d.ts

@@ -0,0 +1,9 @@
+import type { OverlayedViewStrategy, OverlayedViewStrategyHandle } from './types.js';
+/**
+ * Register a read-shadow overlay: bind an MV-owned base collection to
+ * a user-writable overlay so consumers can express operator-editable
+ * lifecycles as one declarative block.
+ *
+ * See docs/superpowers/specs/2026-05-20-dim14-mv-v2-design.md.
+ */
+export declare function withOverlayedView(spec: OverlayedViewStrategy): OverlayedViewStrategyHandle;

package/dist/with-lookup/aggregate/active.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Active aggregate strategy factory. Calling `withAggregate()` returns
+ * an `AggregateStrategy` whose methods construct real `Aggregation` /
+ * `GroupedQuery` instances and run the streaming reducer protocol.
+ *
+ * This module is only reachable through the `@noy-db/hub/aggregate`
+ * subpath — a consumer that never imports the subpath ships none of
+ * this (ESM tree-shaking + hub's `"sideEffects": false`).
+ */
+import type { AggregateStrategy } from './strategy.js';
+/**
+ * Build the default aggregate strategy. Pass into
+ * `createNoydb({ aggregateStrategy: withAggregate() })` to light up
+ * `.aggregate()` and `.groupBy()` on `Query` and `ScanBuilder`.
+ *
+ * @example
+ * ```ts
+ * import { createNoydb } from '@noy-db/hub'
+ * import { withAggregate, sum, count } from '@noy-db/hub/aggregate'
+ *
+ * const db = await createNoydb({
+ *   store, user, secret,
+ *   aggregateStrategy: withAggregate(),
+ * })
+ *
+ * const totals = invoices.query()
+ *   .where('status', '==', 'paid')
+ *   .groupBy('clientId')
+ *   .aggregate({ amount: sum('amount'), n: count() })
+ *   .run()
+ * ```
+ */
+export declare function withAggregate(): AggregateStrategy;

package/dist/with-lookup/aggregate/aggregation.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Aggregate execution — the runtime behind `Query.aggregate()`.
+ *
+ * takes an `AggregateSpec` (a record of named reducers
+ * built from `reducers.ts`) and runs every reducer over the records
+ * produced by the underlying query. Two terminal surfaces:
+ *
+ *   - `.run(): R` — synchronous one-shot reduction. Matches the
+ *     existing `Query.toArray()` / `.first()` / `.count()` style.
+ *   - `.live(): LiveAggregation<R>` — reactive primitive that
+ *     re-runs the reduction whenever the query's source notifies of
+ *     a change. uses naive full re-run; incremental delta
+ *     maintenance is admitted by the reducer protocol (`remove()`)
+ *     but not wired to the executor yet — a follow-up optimization
+ *     can switch from full re-run to delta-based without breaking
+ *     the public API. Consumers get correct, reactive values today.
+ *
+ * The `Aggregation<R>` wrapper is deliberately tiny — it exists so
+ * `.aggregate(spec)` can be chained with either `.run()` or `.live()`
+ * without the builder needing two separate terminal methods. It
+ * holds the closure over the query execution (produces the current
+ * matching record set) and the spec, and stitches them together in
+ * either mode.
+ *
+ * This file depends ONLY on `reducers.ts` — it has no knowledge of
+ * the `Query` class. Tests can therefore exercise the reduction
+ * surface with plain record arrays, without spinning up a Collection.
+ */
+import type { Reducer } from './reducers.js';
+/**
+ * A named set of reducers, keyed by output field name. Each key
+ * becomes a field on the aggregated result.
+ *
+ * ```ts
+ * const spec = {
+ *   total: sum('amount'),
+ *   n:     count(),
+ *   avgAmount: avg('amount'),
+ * }
+ * ```
+ */
+export type AggregateSpec = Readonly<Record<string, Reducer<unknown, unknown>>>;
+/**
+ * Map an `AggregateSpec` to its reduced result shape — each key
+ * carries the finalized result type from its reducer. A spec built
+ * from `{ total: sum('amount'), n: count() }` yields a result of
+ * `{ total: number, n: number }`.
+ *
+ * This uses a mapped type with a conditional to extract `R` from
+ * each `Reducer<R, _>`. The `infer` captures the user-visible result
+ * type, discarding the internal state type `S`.
+ */
+export type AggregateResult<Spec extends AggregateSpec> = {
+    [K in keyof Spec]: Spec[K] extends Reducer<infer R, unknown> ? R : never;
+};
+/**
+ * Pure reduction over a record array. Runs every reducer's
+ * `init → step* → finalize` pipeline exactly once over the records.
+ *
+ * Called by `Aggregation.run()` and by the live-mode refresh path.
+ * Exported for tests and for future `scan().aggregate()` reuse
+ * — the streaming path will call the same reducer protocol with a
+ * per-page loop instead of a single array.
+ */
+export declare function reduceRecords<Spec extends AggregateSpec>(records: readonly unknown[], spec: Spec): AggregateResult<Spec>;
+/**
+ * A minimal reactive primitive for aggregation results.
+ *
+ * Same spirit as the `LiveQuery` in : frame-agnostic, a plain
+ * object with `value` / `error` fields and a `subscribe(cb)`
+ * notification channel that Vue / React / Solid adapters wrap in
+ * their own primitive. Intentionally NOT a Promise — aggregations
+ * have a well-defined "current value" at every instant, and the
+ * reactive consumer wants to read that value synchronously.
+ *
+ * Error semantics mirror `LiveQuery`: if a re-run throws, the
+ * previous successful `value` is preserved and the error is stored
+ * in `error` so consumers can render an error state without losing
+ * the last-known-good result. The throw does NOT propagate out of
+ * the source's change handler (which would tear down the upstream
+ * emitter).
+ *
+ * `stop()` tears down the upstream subscription. It is idempotent —
+ * calling it multiple times is safe — and subscribe calls after
+ * stop are no-ops (they immediately return a no-op unsubscribe).
+ * Always call `stop()` when done; Vue's `onUnmounted` is the
+ * canonical place. Raw consumers must do it themselves.
+ */
+export interface LiveAggregation<R> {
+    /** Current reduced value. Undefined only if the first compute threw. */
+    readonly value: R | undefined;
+    /** Last execution error, if any. Cleared on the next successful run. */
+    readonly error: unknown;
+    /** Notify on every recomputation (success or error). Returns unsubscribe. */
+    subscribe(cb: () => void): () => void;
+    /** Tear down the upstream subscription. Idempotent. */
+    stop(): void;
+}
+/**
+ * Upstream change-notification hook for live aggregation.
+ *
+ * Matches the shape that `QuerySource.subscribe` already uses — a
+ * single method that accepts a callback and returns an unsubscribe
+ * function. The `Aggregation` wrapper collects upstreams from the
+ * query's source and wires them into a single re-run trigger.
+ */
+export interface AggregationUpstream {
+    subscribe(cb: () => void): () => void;
+}
+/**
+ * Chainable wrapper returned by `Query.aggregate(spec)`. Holds the
+ * execute-records closure and the spec; terminal methods (`run`,
+ * `live`) stitch them together in either mode.
+ *
+ * Why a wrapper instead of two terminal methods on `Query` directly?
+ *
+ * The `.aggregate(spec)` call is where the spec is bound — both
+ * `.run()` and `.live()` need the same spec, and the consumer's
+ * fluent style is `query.where(...).aggregate(spec).run()` or
+ * `.aggregate(spec).live()`. Wrapping lets the spec be named once
+ * and reused for either terminal, and keeps the `Query` class
+ * from growing a pair of near-duplicate method overloads
+ * (`aggregateRun` / `aggregateLive`) that would be harder to
+ * discover.
+ */
+export declare class Aggregation<R> {
+    private readonly executeRecords;
+    private readonly spec;
+    private readonly upstreams;
+    constructor(executeRecords: () => readonly unknown[], spec: AggregateSpec, upstreams: readonly AggregationUpstream[]);
+    /**
+     * Execute the query and reduce the results synchronously.
+     * Returns the reduced shape matching the spec — e.g. a spec of
+     * `{ total: sum('amount'), n: count() }` returns
+     * `{ total: number, n: number }`.
+     */
+    run(): R;
+    /**
+     * Build a reactive `LiveAggregation<R>` that re-runs the reduction
+     * whenever any upstream source notifies of a change. The initial
+     * value is computed eagerly in the constructor, so consumers can
+     * read `live.value` immediately after calling `.live()`.
+     *
+     * Always call `live.stop()` when finished — it tears down the
+     * upstream subscriptions. Vue's `onUnmounted` is the canonical
+     * place.
+     *
+     * **Implementation note:** every upstream change triggers a full
+     * re-reduction. Incremental maintenance (O(1) per delta for
+     * sum/count/avg via the reducer protocol's `remove()` method) is a
+     * planned follow-up optimization — the protocol already supports
+     * it, but the executor doesn't drive it yet. Consumers get
+     * correct, reactive values today; future PRs can switch to
+     * delta-based maintenance without changing this API.
+     */
+    live(): LiveAggregation<R>;
+}
+/**
+ * Build a `LiveAggregation<V>` from a recompute closure and a list
+ * of upstreams. Exposed so sibling files in the query DSL
+ * (currently `groupby.ts`) can reuse the reactive primitive
+ * without reaching into `LiveAggregationImpl` directly. This keeps
+ * the implementation class private while still allowing planned
+ * composition with `.groupBy().aggregate().live()`.
+ */
+export declare function buildLiveAggregation<V>(recompute: () => V, upstreams: readonly AggregationUpstream[]): LiveAggregation<V>;

package/dist/with-lookup/aggregate/canonical-key.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Canonicalise a group-key tuple to a stable string for dedup hashing.
+ *
+ * Sorts field names lexicographically before serialising, so that
+ * `.groupBy('a', 'b')` and `.groupBy('b', 'a')` produce identical
+ * keys for the same logical group. Values are JSON-stringified;
+ * `undefined` and `null` are distinguished (matching the Map-key
+ * semantics in `groupAndReduce`).
+ *
+ * NOT part of the public API. Used by:
+ *   - `groupAndReduce` for the dedup Map's key
+ *   - `materialized-views/query-hash` for UNION MV cross-arm row-key dedup (PR 2)
+ *
+ * Pure: same input → same output, no side effects.
+ */
+export declare function canonicalGroupKey(fields: readonly string[], row: Record<string, unknown>): string;