pyric 0.0.1 → 0.1.0-alpha.7

package/dist/database/modular.d.ts

@@ -0,0 +1,604 @@
+/**
+ * `@pyric/rtdb` modular SDK surface — Phase 3 implementation.
+ *
+ * Mirrors `firebase/database`'s tree-shakable free-function shape:
+ * `getDatabase`, `ref`, `child`, `get`, `set`, `update`, `remove`,
+ * `push`, `onValue`, `serverTimestamp`, `connectDatabaseEmulator`.
+ *
+ * Three backends picked by what's passed to `getDatabase`:
+ *
+ *   - **Sandbox target** — wraps `RtdbBackend` (in-memory JSON tree
+ *     plus the existing `@pyric/rtdb` rule simulator). Identity is the
+ *     `SandboxContext`'s frozen `auth`.
+ *   - **Sandbox-live target** — same backend, but identity is read
+ *     per-op from `sandbox.currentUser` so a `pyric/auth`-driven
+ *     sign-in flips the next op's `request.auth` without re-binding.
+ *   - **Prod target** — wraps `firebase/database` against a real
+ *     Firebase project.
+ *
+ * Dispatch machinery mirrors `pyric/firestore`:
+ *   - {@link TARGET_SYMBOL} brand on every {@link Database} handle.
+ *   - {@link refToTarget} WeakMap from refs to their owning target so
+ *     chained calls (`child(ref, 'sub')`, `get(ref)`) recover routing.
+ *
+ * Every public function has a `target.kind` switch with explicit
+ * branches — structure is parallel and grep-friendly.
+ *
+ * **Critical contract — error shape (locked by oracle observation
+ * `scripts/oracle/observations/rtdb-rules-denied-error-code.json`):**
+ *
+ *   - Throws a **plain `Error`** (NOT a `FirebaseError`).
+ *   - `.code === 'PERMISSION_DENIED'` (uppercase snake-case — distinct
+ *     from Firestore's `'permission-denied'`).
+ *   - `.message === 'PERMISSION_DENIED: Permission denied'`.
+ *
+ * The sandbox backend matches this shape exactly. Tests assert against
+ * `.constructor.name === 'Error'` to catch any future "improvement" to
+ * a custom subclass.
+ */
+import type { FirebaseApp } from 'firebase/app';
+import * as fb from 'firebase/database';
+import type { AuthState, Sandbox, SandboxContext } from 'pyric/sandbox';
+import { type PyricApp } from 'pyric/app';
+import { RtdbBackend } from './sandbox/backend.js';
+import { type ServerTimestampSentinel, type IncrementSentinel } from './sandbox/sentinels.js';
+import { type JsonValue } from './sandbox/data-tree.js';
+import { type Constraint, type QuerySpec } from './sandbox/query.js';
+/** Hidden brand on every {@link Database} handle. */
+export declare const TARGET_SYMBOL: unique symbol;
+type SandboxTarget = {
+    kind: 'sandbox';
+    backend: RtdbBackend;
+    auth: AuthState;
+    admin?: boolean;
+};
+type SandboxLiveTarget = {
+    kind: 'sandbox-live';
+    backend: RtdbBackend;
+    sandbox: Sandbox;
+    admin?: boolean;
+};
+type ProdTarget = {
+    kind: 'prod';
+    db: fb.Database;
+};
+type Target = SandboxTarget | SandboxLiveTarget | ProdTarget;
+/** Opaque RTDB handle. Routes via {@link TARGET_SYMBOL}. */
+export interface Database {
+    readonly [TARGET_SYMBOL]: Target;
+}
+/**
+ * RTDB-shaped reference. Backend-opaque to consumers; mirrors
+ * `firebase/database`'s `DatabaseReference` for the subset of methods
+ * the modular SDK uses idiomatically as plain free-function args.
+ *
+ * `key` is the last path segment (matches `DatabaseReference.key`).
+ * `null` for the root ref. `parent` is the ref one segment up
+ * (`null` at root). `root` is always the root ref.
+ *
+ * `toString()` returns the absolute URL — for sandbox refs we
+ * stub a `sandbox://` URL; for prod refs `firebase/database`
+ * provides the real URL.
+ */
+export interface DatabaseReference {
+    readonly key: string | null;
+    readonly parent: DatabaseReference | null;
+    readonly root: DatabaseReference;
+    toString(): string;
+    /** Internal — the canonical path (`'/users/alice'`). */
+    readonly _path: string;
+}
+/**
+ * Lightweight `DataSnapshot` — matches the subset of
+ * `firebase/database`'s `DataSnapshot` we surface synchronously on a
+ * `get()`. Methods are the load-bearing ones (`val`, `exists`, `key`,
+ * `child`) plus a few utilities consumer code routinely reads.
+ */
+export interface DataSnapshot {
+    readonly key: string | null;
+    /**
+     * Number of child properties of this snapshot. A getter (NOT a
+     * `numChildren()` method — that was the legacy namespaced API). Locked
+     * by oracle `rtdb-modular-get-snapshot-shape.json`
+     * (`hasSize: true, hasNumChildren: false`) + upstream
+     * `api/Reference_impl.ts:331-333`.
+     */
+    readonly size: number;
+    /**
+     * The node's priority, or `null`. The sandbox does not model RTDB's
+     * priority (deny-listed — see COMPAT) so this is always `null`, matching
+     * the common case (no `.priority` set). Mirrors `api/Reference_impl.ts:312`.
+     */
+    readonly priority: string | number | null;
+    exists(): boolean;
+    val(): JsonValue;
+    child(path: string): DataSnapshot;
+    hasChild(path: string): boolean;
+    hasChildren(): boolean;
+    /**
+     * Like `val()` but includes priority info (for backups). With no
+     * priority modeled, this equals `val()`. Mirrors
+     * `api/Reference_impl.ts:374-376`.
+     */
+    exportVal(): JsonValue;
+    toJSON(): JsonValue;
+    /**
+     * Iterate the snapshot's immediate children. The callback is invoked
+     * with a child `DataSnapshot` for each child; return `true` to stop
+     * iteration early (matches the `firebase/database` contract).
+     *
+     * For a snapshot built from a {@link Query}, children are visited in
+     * the order the query's `orderBy*` constraint computed — the windowed
+     * + filtered + limited sequence. For a plain ref snapshot, children
+     * are visited in key-insertion order (V8 object iteration order; the
+     * RTDB SDK does NOT guarantee an order on plain refs either).
+     */
+    forEach(cb: (child: DataSnapshot) => boolean | void): boolean;
+    /** The ref the snap was taken from. */
+    readonly ref: DatabaseReference;
+}
+/**
+ * The return type of {@link push} — a regular {@link DatabaseReference}
+ * with `.then` / `.catch` attached so it can be `await`ed. Mirrors
+ * `firebase/database`'s `ThenableReference` (`api/Reference_impl.ts:569`).
+ *
+ * Critical (DB-B7): the ref + its `.key` are available SYNCHRONOUSLY —
+ * the key is minted client-side. The promise covers only the optional
+ * value write; a rules-denied write rejects the promise (it does NOT
+ * throw synchronously and lose the key). Oracle:
+ * `rtdb-push-autoid-format.json`.
+ */
+export interface ThenableReference extends DatabaseReference {
+    then<TResult1 = DatabaseReference, TResult2 = never>(onfulfilled?: ((value: DatabaseReference) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): Promise<DatabaseReference | TResult>;
+}
+export type Unsubscribe = () => void;
+/**
+ * Hidden brand on every {@link Query} (and on every QueryConstraint).
+ * Distinct from `TARGET_SYMBOL`; this brand is only used to dispatch
+ * `get` / `onValue` between plain refs and query-wrapped refs.
+ */
+export declare const QUERY_SYMBOL: unique symbol;
+/** Hidden brand on every {@link QueryConstraint}. */
+declare const CONSTRAINT_SYMBOL: unique symbol;
+/**
+ * RTDB-shaped Query — a ref + an immutable constraint chain. Mirrors
+ * `firebase/database`'s `Query` for the subset of methods the modular
+ * SDK uses idiomatically.
+ *
+ * Construct with {@link query}; pass to {@link get} or {@link onValue}.
+ */
+export interface Query {
+    /** The Query's location. Used by `query()` chaining + listener fan-out. */
+    readonly ref: DatabaseReference;
+    /** Resolves to the same URL the ref would. */
+    toString(): string;
+    /** Internal — the constraint chain that built this query (sandbox path). */
+    readonly _spec: QuerySpec;
+    /** Internal — the prod-side fb.Query (when this query routes to prod). */
+    readonly _fbQuery?: fb.Query;
+    readonly [QUERY_SYMBOL]: true;
+}
+/**
+ * Opaque constraint produced by `orderByChild` / `equalTo` / `limitToFirst`
+ * etc. Pass to {@link query}.
+ */
+export interface QueryConstraint {
+    /** The constraint's variant — surfaces as the SDK's
+     *  `QueryConstraintType` strings. */
+    readonly type: 'orderByChild' | 'orderByKey' | 'orderByValue' | 'startAt' | 'startAfter' | 'endAt' | 'endBefore' | 'equalTo' | 'limitToFirst' | 'limitToLast';
+    readonly [CONSTRAINT_SYMBOL]: Constraint;
+}
+/**
+ * Build a Database handle. Three overloads dispatch by input shape:
+ *
+ *   - `SandboxContext` → sandbox-backed, frozen identity.
+ *   - `Sandbox` → sandbox-backed, live identity (per-op `currentUser`).
+ *   - `FirebaseApp` → prod-backed (delegates to `firebase/database`).
+ *
+ * @example
+ * ```ts
+ * import { initializeSandbox } from 'pyric/sandbox';
+ * import { getDatabase, ref, set, get } from 'pyric/database';
+ *
+ * const sandbox = initializeSandbox();
+ * const db = getDatabase(sandbox.withAuth({ uid: 'alice' }));
+ * await set(ref(db, 'greetings/hello'), { text: 'hi' });
+ * const snap = await get(ref(db, 'greetings/hello'));
+ * console.log(snap.val()); // { text: 'hi' }
+ * ```
+ */
+export declare function getDatabase(ctx: SandboxContext): Database;
+export declare function getDatabase(sandbox: Sandbox): Database;
+export declare function getDatabase(app: FirebaseApp): Database;
+export declare function getDatabase(app: PyricApp): Database;
+/**
+ * Sandbox-only rules-bypass RTDB handle. Mirrors Firestore's
+ * `getAdminFirestore(sandbox)` for Studio/Playground data browsers and
+ * controlled admin tools. A prod-backed app has no client-side rules-bypass
+ * equivalent and is rejected loudly.
+ */
+export declare function getAdminDatabase(sandbox: Sandbox): Database;
+export declare function getAdminDatabase(ctx: SandboxContext): Database;
+export declare function getAdminDatabase(app: PyricApp): Database;
+/**
+ * Build a {@link DatabaseReference} at `path` (default root).
+ *
+ * Sandbox: returns a lightweight ref object owning its absolute path.
+ * Prod: delegates to `firebase/database`'s `ref(db, path)` and tags
+ * the returned ref so chained ops route correctly.
+ *
+ * Path normalisation: leading + trailing slashes are stripped;
+ * empty path / `'/'` becomes the root.
+ */
+export declare function ref(db: Database, path?: string): DatabaseReference;
+/**
+ * Sub-path constructor. `child(ref, 'sub/path')` returns a ref at
+ * `<ref>/sub/path`.
+ *
+ * Mirrors `firebase/database`'s `child(parent, path)` — leading +
+ * empty segments stripped; the result inherits the parent's target.
+ */
+export declare function child(parent: DatabaseReference, path: string): DatabaseReference;
+/**
+ * `get(ref)` — one-shot read at the ref's path. Resolves to a
+ * `DataSnapshot`-shaped object.
+ *
+ * Sandbox: runs through the rule engine; denial throws the plain-`Error`
+ * shape locked by the oracle. Prod: delegates to `firebase/database`'s
+ * `get(ref)` and wraps the returned snapshot in our minimal shape.
+ *
+ * Absent path → `snap.val() === null && snap.exists() === false`.
+ * Matches the SDK's `DataSnapshot.val()` contract.
+ */
+export declare function get(r: DatabaseReference | Query): Promise<DataSnapshot>;
+/**
+ * `set(ref, value)` — replace the value at `ref`'s path. `null`
+ * deletes (matches the RTDB invariant — locked by oracle observation
+ * `rtdb-remove-vs-set-null.json`).
+ *
+ * `serverTimestamp()` sentinels are resolved at write time on the
+ * sandbox side; the prod side relies on `firebase/database`'s wire
+ * encoder.
+ */
+export declare function set(r: DatabaseReference, value: unknown): Promise<void>;
+/**
+ * `update(ref, values)` — partial update.
+ *
+ *   - When `values` keys contain `/`, the call is a **multi-path atomic
+ *     update**: every listed path is written as one transaction (any
+ *     denial fails the whole batch).
+ *   - Otherwise it's a **shallow merge** at the ref's path: each
+ *     top-level key replaces the corresponding child. `null` values
+ *     delete.
+ *
+ * Both behaviors are sandbox-implemented per the RtdbBackend's
+ * `update` method (`rtdb-modular`-spec atomic claim, matrix row #23).
+ */
+export declare function update(r: DatabaseReference, values: Record<string, unknown>): Promise<void>;
+/**
+ * `remove(ref)` — delete the subtree at the ref's path.
+ *
+ * RTDB invariant (oracle: `rtdb-remove-vs-set-null.json`): equivalent
+ * to `set(ref, null)`. The sandbox backend dispatches `remove` through
+ * the same code path as `set(_, null)`.
+ */
+export declare function remove(r: DatabaseReference): Promise<void>;
+/**
+ * `push(ref, value?)` — mint an auto-id child key under `ref`'s path,
+ * optionally writing `value` at the new child.
+ *
+ * Returns a ref at the new child path. The ref's `key` is the minted
+ * id (locked by oracle observation `rtdb-push-autoid-format.json`:
+ * 20 chars, leading `-`, lex-sortable).
+ *
+ * Production note: the key is minted **client-side** (no server
+ * round-trip required); it's available synchronously on the returned
+ * ref even when the optional write is denied by rules. The oracle
+ * observation confirms this — the sandbox matches.
+ */
+export declare function push(r: DatabaseReference, value?: unknown): ThenableReference;
+/**
+ * Pre-mint a push key without writing. Used by callers that need the
+ * key for a multi-path update (`update(rootRef, { [\`/users/${key}\`]: ... })`).
+ * Sandbox-side: returns a freshly-minted key. Prod-side: same — the
+ * `push(ref).key` pattern is the documented way.
+ */
+export declare function pushKey(): string;
+/**
+ * `onValue(ref, cb)` — subscribe to value changes at the ref's path.
+ *
+ * Fires immediately on subscribe with the current value (or
+ * `null` + `exists: false` for an absent path), then on every
+ * subsequent write that touches the path or any descendant.
+ *
+ * Returns an unsubscribe function. The unsubscribe is idempotent;
+ * calling it twice is a no-op.
+ *
+ * `options.onlyOnce` (DB-B12): when `true`, the listener auto-unsubscribes
+ * after its first fire (mirrors `api/Reference_impl.ts:975-980`).
+ *
+ * Errors path: subscribing under rules that deny the read throws the
+ * plain-`Error` `PERMISSION_DENIED` shape synchronously (matching the
+ * production behavior where the subscribe path immediately errors).
+ */
+export declare function onValue(r: DatabaseReference | Query, cb: (snap: DataSnapshot) => void, options?: {
+    onlyOnce?: boolean;
+}): Unsubscribe;
+/**
+ * `onChildAdded(ref, cb)` — subscribe to child-added events at the
+ * ref's path.
+ *
+ * Semantics (locked by oracle observations under
+ * `scripts/oracle/observations/rtdb-modular-onchildadded-*.json`):
+ *
+ *   - On subscribe, replays every existing direct child of `ref`'s path
+ *     (one fire per existing key, in `orderByKey`-default order).
+ *   - After subscribe, fires exactly once per new direct child write.
+ *
+ * Also accepts a {@link Query} (a `query(ref, ...)` with `orderBy*` /
+ * `limitTo*` constraints): child events are then computed against the
+ * ordered, windowed result — a child ENTERING the window fires
+ * `child_added`; on subscribe the current window is replayed in window
+ * order.
+ *
+ * Returns an unsubscribe; calling it twice is a no-op.
+ */
+export declare function onChildAdded(r: DatabaseReference | Query, cb: (snap: DataSnapshot) => void): Unsubscribe;
+/**
+ * `onChildChanged(ref, cb)` — subscribe to child-changed events.
+ *
+ * Semantics (oracle: `rtdb-modular-onchildchanged-fires-on-update`):
+ *
+ *   - No initial replay.
+ *   - Fires when an existing direct child's value transitions to a
+ *     NEW non-null value. Snapshot carries the NEW value.
+ *   - Does NOT fire for added or removed children.
+ *
+ * Also accepts a {@link Query}: fires when a child that is IN the query
+ * window changes value (an in-window update).
+ */
+export declare function onChildChanged(r: DatabaseReference | Query, cb: (snap: DataSnapshot) => void): Unsubscribe;
+/**
+ * `onChildRemoved(ref, cb)` — subscribe to child-removed events.
+ *
+ * Semantics (oracle: `rtdb-modular-onchildremoved-fires-on-delete`):
+ *
+ *   - No initial replay.
+ *   - Fires when a direct child is deleted (via `remove(child)` or
+ *     `set(child, null)`).
+ *   - Snapshot carries the PRIOR (now-removed) value — the listener
+ *     sees what was there before deletion.
+ *
+ * Also accepts a {@link Query}: a child LEAVING the query window (e.g.
+ * displaced past a `limitTo*` boundary or filtered out) fires
+ * `child_removed` carrying its prior value.
+ */
+export declare function onChildRemoved(r: DatabaseReference | Query, cb: (snap: DataSnapshot) => void): Unsubscribe;
+/**
+ * `onChildMoved(ref, cb)` — subscribe to child-moved events.
+ *
+ * Semantics (oracle: `rtdb-modular-onchildmoved-with-orderby`):
+ *
+ *   - Only fires under an ordered query (`query(ref, orderByChild(...))`).
+ *   - Under a plain ref, this listener is effectively a no-op — the
+ *     upstream SDK accepts the subscription but never fires it
+ *     (matches RTDB docs).
+ *
+ * Accepts a {@link Query} WITHOUT throwing, but the sandbox deliberately
+ * does NOT fire `child_moved` on reorder yet: prod fires here (matrix row
+ * `rtdb-modular#137`) while the sandbox holds — the reorder /
+ * `previousChildName` ordering semantics are pending two new oracle
+ * captures. This is a documented, pinned divergence (both sides asserted
+ * in `test/database/modular/sandbox-child-events.test.ts`).
+ */
+export declare function onChildMoved(r: DatabaseReference | Query, cb: (snap: DataSnapshot) => void): Unsubscribe;
+type ChildEvent = 'child_added' | 'child_changed' | 'child_removed' | 'child_moved';
+/**
+ * `off(ref, eventType?, callback?)` — unsubscribe variant.
+ *
+ * Semantics (locked by oracle observation
+ * `scripts/oracle/observations/rtdb-modular-off-stops-child-fires.json`):
+ *
+ *   - `off(ref)` (no eventType) removes ALL listeners at that ref —
+ *     value + every child event variety.
+ *   - `off(ref, 'value')` removes only `value` listeners.
+ *   - `off(ref, 'child_added')` (or any child event type) removes only
+ *     that variety.
+ *   - `off(ref, eventType, cb)` removes only the matching callback.
+ *
+ * The returned-unsubscribe pattern from `onValue` / `onChild*` is
+ * functionally equivalent to `off(ref, eventType, cb)` for a specific
+ * registration — both are supported.
+ */
+export declare function off(r: DatabaseReference, eventType?: 'value' | ChildEvent, callback?: (snap: DataSnapshot) => void): void;
+/**
+ * `query(ref, ...constraints)` — wrap a ref in an immutable
+ * constraint chain. The resulting {@link Query} routes through
+ * {@link get}/{@link onValue} and applies the ordering + filtering +
+ * limit pipeline on the sandbox backend; on prod it delegates to
+ * `firebase/database`'s `query()`.
+ *
+ * Chaining is supported — `query(query(ref, orderByChild('x')),
+ * limitToFirst(2))` folds both constraints into one spec.
+ *
+ * Locked semantics (oracle):
+ *   - `orderByChild('p') + startAt(v) + endAt(w)` is BOTH-inclusive
+ *     (`rtdb-modular-orderbychild-window.json`).
+ *   - `orderByKey() + startAt('b') + endAt('d')` matches `[b, c, d]`
+ *     (`rtdb-modular-orderbykey-window.json`).
+ *   - `orderByValue() + limitToFirst(3)` returns the 3 smallest by
+ *     value (`rtdb-modular-orderbyvalue-numeric.json` — note: prod
+ *     requires `.indexOn: ".value"`; sandbox does not enforce indexes).
+ *   - `orderByChild('group') + equalTo('b')` returns ALL matching
+ *     children (`rtdb-modular-equalTo-filter.json`).
+ *   - `limitToFirst(N)` / `limitToLast(N)` take from the start / end of
+ *     the ordered window (`rtdb-modular-limittofirst-vs-limittolast.json`).
+ *   - `startAfter` / `endBefore` are EXCLUSIVE
+ *     (`rtdb-modular-startafter-endbefore-exclusive.json`).
+ */
+export declare function query(refOrQuery: DatabaseReference | Query, ...constraints: QueryConstraint[]): Query;
+/** `orderByChild('path')` — order children by the value at the nested
+ *  child path. Locked by oracle observation
+ *  `rtdb-modular-orderbychild-window.json`. */
+export declare function orderByChild(path: string): QueryConstraint;
+/** `orderByKey()` — order children lexicographically by key string.
+ *  Locked by oracle observation `rtdb-modular-orderbykey-window.json`. */
+export declare function orderByKey(): QueryConstraint;
+/** `orderByValue()` — order children by primitive value. Prod requires
+ *  `.indexOn: ".value"` (oracle: `rtdb-modular-orderbyvalue-numeric.json`
+ *  threw `Index not defined` against blockingfun); sandbox does NOT
+ *  enforce indexes (the rules engine here checks read-allow only, not
+ *  query-index conformance). */
+export declare function orderByValue(): QueryConstraint;
+/** `startAt(value, key?)` — INCLUSIVE lower bound under the active
+ *  ordering. Optional `key` is the tie-breaker when ordering by
+ *  child/value and multiple children share the bound's value. */
+export declare function startAt(value: JsonValue, key?: string): QueryConstraint;
+/** `startAfter(value, key?)` — EXCLUSIVE lower bound. Locked by
+ *  `rtdb-modular-startafter-endbefore-exclusive.json`. */
+export declare function startAfter(value: JsonValue, key?: string): QueryConstraint;
+/** `endAt(value, key?)` — INCLUSIVE upper bound. Adjacent to startAt;
+ *  same key tie-breaker semantics. */
+export declare function endAt(value: JsonValue, key?: string): QueryConstraint;
+/** `endBefore(value, key?)` — EXCLUSIVE upper bound. Locked by
+ *  `rtdb-modular-startafter-endbefore-exclusive.json`. */
+export declare function endBefore(value: JsonValue, key?: string): QueryConstraint;
+/** `equalTo(value, key?)` — sugar for `startAt(value, key) +
+ *  endAt(value, key)`. Returns ALL matching children (no uniqueness).
+ *  Locked by oracle observation `rtdb-modular-equalTo-filter.json`. */
+export declare function equalTo(value: JsonValue, key?: string): QueryConstraint;
+/** `limitToFirst(n)` — keep the first N children of the ordered window.
+ *  Locked by oracle observation `rtdb-modular-limittofirst-vs-limittolast.json`. */
+export declare function limitToFirst(n: number): QueryConstraint;
+/** `limitToLast(n)` — keep the last N children of the ordered window.
+ *  Locked by oracle observation `rtdb-modular-limittofirst-vs-limittolast.json`. */
+export declare function limitToLast(n: number): QueryConstraint;
+/**
+ * Result of {@link runTransaction}. Matches `firebase/database`'s
+ * `TransactionResult` for the fields agent / playground code reads
+ * idiomatically.
+ *
+ * `committed === false` when the update fn aborted by returning
+ * `undefined`. The snapshot still resolves — it reflects the **pre-
+ * transaction** value (oracle:
+ * `rtdb-modular-runtransaction-abort-undefined.json` →
+ * `afterValOnServer: 100` preserved).
+ *
+ * On rule denial the promise rejects with a plain `Error` whose
+ * `message === 'permission_denied'` (lowercase, no `.code`); see
+ * `rtdb-modular-runtransaction-on-rules-denied-path.json`.
+ */
+export interface TransactionResult {
+    readonly committed: boolean;
+    readonly snapshot: DataSnapshot;
+}
+/**
+ * `runTransaction(ref, transactionUpdate, options?)` — atomic
+ * read-modify-write.
+ *
+ * Contract (oracle-locked):
+ *
+ *   1. `transactionUpdate` is called with the CURRENT value at `ref`'s
+ *      path. For an absent path the arg is `null` (NOT `undefined`);
+ *      oracle:
+ *      `rtdb-modular-runtransaction-current-value-arg.json` →
+ *      `missingFirstWasNull: true`.
+ *   2. Returning `undefined` from the update fn ABORTS the transaction:
+ *      resolves `{ committed: false, snapshot }` where the snapshot is
+ *      the pre-transaction value; oracle:
+ *      `rtdb-modular-runtransaction-abort-undefined.json` → `committed:
+ *      false, snapVal: null`.
+ *   3. Returning any defined value WRITES that value (rules-checked);
+ *      resolves `{ committed: true, snapshot }` where `snapshot.val()`
+ *      is the committed value; oracle:
+ *      `rtdb-modular-runtransaction-success.json` → `committedNewValue:
+ *      true` and
+ *      `rtdb-modular-runtransaction-returns-committed-snapshot.json`.
+ *   4. If rules deny the write, the promise REJECTS with a plain
+ *      `Error` whose `message === 'permission_denied'` and NO `.code`
+ *      field (distinct from `set`/`get`'s `'PERMISSION_DENIED:
+ *      Permission denied'`); oracle:
+ *      `rtdb-modular-runtransaction-on-rules-denied-path.json`.
+ *
+ * `options.applyLocally` (default `true`): when `false`, the
+ * intermediate optimistic value is NOT fanned out to listeners — they
+ * see only the committed value. In a single-client harness this is
+ * usually invisible; we honor the flag for prod-parity. Oracle
+ * observation `rtdb-modular-runtransaction-options-applylocally.json`
+ * confirms both branches commit and end at the same value; the
+ * intermediate-fire difference isn't observable from a single client.
+ *
+ * Single-client sandbox doesn't model concurrency conflicts; the
+ * documented "retry on conflict" path is degenerate (no other writer
+ * exists to conflict with). The fn is invoked once.
+ */
+export declare function runTransaction<T>(r: DatabaseReference, transactionUpdate: (current: T | null) => T | undefined, options?: {
+    applyLocally?: boolean;
+}): Promise<TransactionResult>;
+/**
+ * `serverTimestamp()` — returns the `{ ".sv": "timestamp" }` sentinel
+ * the wire encoder recognises. Resolves to `Date.now()` (epoch ms) on
+ * write — locked by the prod SDK's resolved-as-number contract
+ * (oracle: `rtdb-servertimestamp-resolves.json`).
+ *
+ * Same shape across targets: the sandbox backend recognises the
+ * marker; the prod backend's wire encoder does too. Agent code that
+ * imports `serverTimestamp` from `@pyric/rtdb` works identically on
+ * either target.
+ */
+export declare function serverTimestamp(): ServerTimestampSentinel;
+/**
+ * `increment(delta)` — returns the `{ ".sv": { increment: delta } }`
+ * sentinel that atomically adds `delta` to the current value at the
+ * write's field. Starts from `0` when the field is absent or
+ * non-numeric (oracle: `rtdb-modular-increment-from-missing.json`).
+ *
+ * Same shape across targets: the sandbox backend resolves it against the
+ * field's prior value at write time; the prod backend's wire encoder
+ * recognises the marker. Mirrors `firebase/database`'s `increment`
+ * (`api/ServerValue.ts:38-44`).
+ */
+export declare function increment(delta: number): IncrementSentinel;
+/**
+ * `connectDatabaseEmulator(db, host, port)` — point a prod handle at
+ * a Firebase emulator. No-op on sandbox handles (the sandbox IS a
+ * local emulator); the call is still accepted so consumer code that
+ * does the wiring unconditionally compiles against both targets.
+ */
+export declare function connectDatabaseEmulator(db: Database, host: string, port: number, options?: {
+    mockUserToken?: string | fb.EmulatorMockTokenOptions;
+}): void;
+export declare const sandbox: {
+    /**
+     * Replace deployed rules. Pass `null` to clear (sandbox returns to
+     * default-allow). Rules are evaluated through the existing
+     * `@pyric/rtdb` simulator — same engine as `simulate()` /
+     * `rtdb_simulate_access`.
+     *
+     * @example
+     * ```ts
+     * sandbox.setRules(db, {
+     *   rules: {
+     *     '.read': 'auth != null',
+     *     '.write': 'auth != null',
+     *   },
+     * });
+     * ```
+     */
+    setRules(db: Database, rulesJson: {
+        rules: Record<string, unknown>;
+    } | null): void;
+    /**
+     * Bulk-load data bypassing rules. The supplied map's keys are
+     * absolute paths (`'/users/alice'`) and the values land at those
+     * paths. Convenient for test fixtures.
+     */
+    setData(db: Database, data: Record<string, unknown>): void;
+    /** Snapshot the full sandbox tree (rule-bypass read). Usually a keyed
+     *  object; may be a primitive when the root holds one (DB-B13). */
+    snapshotState(db: Database): JsonValue;
+};
+export type { Sandbox, SandboxContext, AuthState, FirebaseApp };
+export type { JsonValue };
+//# sourceMappingURL=modular.d.ts.map

package/dist/database/modular.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modular.d.ts","sourceRoot":"","sources":["../../src/database/modular.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,mBAAmB,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAKxE,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEtD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EAGL,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAA0B,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,EAGL,KAAK,UAAU,EAEf,KAAK,SAAS,EACf,MAAM,oBAAoB,CAAC;AAI5B,qDAAqD;AACrD,eAAO,MAAM,aAAa,EAAE,OAAO,MAAqC,CAAC;AAEzE,KAAK,aAAa,GAAG;IACnB,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,WAAW,CAAC;IACrB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AACF,KAAK,iBAAiB,GAAG;IACvB,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,WAAW,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AACF,KAAK,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAA;CAAE,CAAC;AACpD,KAAK,MAAM,GAAG,aAAa,GAAG,iBAAiB,GAAG,UAAU,CAAC;AA+E7D,4DAA4D;AAC5D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,IAAI,MAAM,CAAC;IACnB,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC1C,MAAM,IAAI,OAAO,CAAC;IAClB,GAAG,IAAI,SAAS,CAAC;IACjB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,WAAW,IAAI,OAAO,CAAC;IACvB;;;;OAIG;IACH,SAAS,IAAI,SAAS,CAAC;IACvB,MAAM,IAAI,SAAS,CAAC;IACpB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC;IAC9D,uCAAuC;IACvC,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC;CACjC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,IAAI,CAAC,QAAQ,GAAG,iBAAiB,EAAE,QAAQ,GAAG,KAAK,EACjD,WAAW,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,iBAAiB,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,EACrF,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,GAC1E,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAAC;IAChC,KAAK,CAAC,OAAO,GAAG,KAAK,EACnB,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,GACxE,OAAO,CAAC,iBAAiB,GAAG,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,OAAO,MAAoC,CAAC;AAEvE,qDAAqD;AACrD,QAAA,MAAM,iBAAiB,EAAE,OAAO,MAA+C,CAAC;AAEhF;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC;IAChC,8CAA8C;IAC9C,QAAQ,IAAI,MAAM,CAAC;IACnB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC;IAC7B,QAAQ,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;yCACqC;IACrC,QAAQ,CAAC,IAAI,EACT,cAAc,GACd,YAAY,GACZ,cAAc,GACd,SAAS,GACT,YAAY,GACZ,OAAO,GACP,WAAW,GACX,SAAS,GACT,cAAc,GACd,aAAa,CAAC;IAClB,QAAQ,CAAC,CAAC,iBAAiB,CAAC,EAAE,UAAU,CAAC;CAC1C;AA4DD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,QAAQ,CAAC;AAC3D,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CAAC;AACxD,wBAAgB,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,QAAQ,CAAC;AACxD,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,QAAQ,CAAC;AA2BrD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CAAC;AAC7D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,QAAQ,CAAC;AAChE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,GAAG,QAAQ,CAAC;AAsD1D;;;;;;;;;GASG;AACH,wBAAgB,GAAG,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAUlE;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAShF;AAkCD;;;;;;;;;;GAUG;AACH,wBAAsB,GAAG,CAAC,CAAC,EAAE,iBAAiB,GAAG,KAAK,GAAG,OAAO,CAAC,YAAY,CAAC,CA0B7E;AAED;;;;;;;;GAQG;AACH,wBAAsB,GAAG,CAAC,CAAC,EAAE,iBAAiB,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAW7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,MAAM,CAC1B,CAAC,EAAE,iBAAiB,EACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,iBAAiB,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,iBAAiB,CA0B7E;AAkBD;;;;;GAKG;AACH,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CACrB,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,EAChC,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/B,WAAW,CA+Eb;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,GAC/B,WAAW,CAEb;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,GAC/B,WAAW,CAEb;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,GAC/B,WAAW,CAEb;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,GAC/B,WAAW,CAEb;AAED,KAAK,UAAU,GAAG,aAAa,GAAG,eAAe,GAAG,eAAe,GAAG,aAAa,CAAC;AAoIpF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,GAAG,CACjB,CAAC,EAAE,iBAAiB,EACpB,SAAS,CAAC,EAAE,OAAO,GAAG,UAAU,EAChC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,GACtC,IAAI,CAuBN;AAID;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,KAAK,CACnB,UAAU,EAAE,iBAAiB,GAAG,KAAK,EACrC,GAAG,WAAW,EAAE,eAAe,EAAE,GAChC,KAAK,CAuCP;AAED;;+CAE+C;AAC/C,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAK1D;AAED;0EAC0E;AAC1E,wBAAgB,UAAU,IAAI,eAAe,CAK5C;AAED;;;;gCAIgC;AAChC,wBAAgB,YAAY,IAAI,eAAe,CAK9C;AAED;;iEAEiE;AACjE,wBAAgB,OAAO,CACrB,KAAK,EAAE,SAAS,EAChB,GAAG,CAAC,EAAE,MAAM,GACX,eAAe,CAKjB;AAED;0DAC0D;AAC1D,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,EAChB,GAAG,CAAC,EAAE,MAAM,GACX,eAAe,CAKjB;AAED;sCACsC;AACtC,wBAAgB,KAAK,CACnB,KAAK,EAAE,SAAS,EAChB,GAAG,CAAC,EAAE,MAAM,GACX,eAAe,CAKjB;AAED;0DAC0D;AAC1D,wBAAgB,SAAS,CACvB,KAAK,EAAE,SAAS,EAChB,GAAG,CAAC,EAAE,MAAM,GACX,eAAe,CAKjB;AAED;;uEAEuE;AACvE,wBAAgB,OAAO,CACrB,KAAK,EAAE,SAAS,EAChB,GAAG,CAAC,EAAE,MAAM,GACX,eAAe,CAKjB;AAED;oFACoF;AACpF,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,eAAe,CAMvD;AAED;oFACoF;AACpF,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,eAAe,CAMtD;AAID;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,CAAC,EAAE,iBAAiB,EACpB,iBAAiB,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,GAAG,SAAS,EACvD,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GACnC,OAAO,CAAC,iBAAiB,CAAC,CAqB5B;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,uBAAuB,CAEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAE1D;AAID;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAGZ,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,GAAG,EAAE,CAAC,wBAAwB,CAAA;CAAE,GACjE,IAAI,CAIN;AAQD,eAAO,MAAM,OAAO;IAClB;;;;;;;;;;;;;;;OAeG;iBACU,QAAQ,aAAa;QAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,GAAG,IAAI;IAQlF;;;;OAIG;gBACS,QAAQ,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAQ1D;uEACmE;sBACjD,QAAQ,GAAG,SAAS;CAOvC,CAAC;AAmKF,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;AAChE,YAAY,EAAE,SAAS,EAAE,CAAC"}