@pyric/cli 0.1.0-alpha.14 → 0.1.0-alpha.16

package/dist/serve/{docs-ui → site-ui}/docs/pyric-database-reference-api.md

@@ -1,21 +1,446 @@
 <!-- Generated from published package declarations via TypeDoc. Rendered by the api-reference content loader. -->
 
-## Interfaces
+## Classes
+
+<a id="database"></a>
+
+### Database
+
+Opaque RTDB handle. Routes via [TARGET\_SYMBOL](#target_symbol-1).
+
+#### Constructors
+
+<a id="constructor"></a>
+
+##### Constructor
+
+```ts
+new Database(target?: Target, app?: FirebaseApp): Database;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `target?` | `Target` |
+| `app?` | [`FirebaseApp`](pyric-app-reference-api.md#firebaseapp) |
+
+###### Returns
+
+[`Database`](#database)
+
+#### Properties
+
+| Property | Modifier | Type | Default value |
+| :------ | :------ | :------ | :------ |
+| <a id="target_symbol"></a> `[TARGET_SYMBOL]` | `readonly` | `Target` | `undefined` |
+| <a id="app"></a> `app` | `readonly` | [`FirebaseApp`](pyric-app-reference-api.md#firebaseapp) | `undefined` |
+| <a id="type"></a> `type` | `readonly` | `"database"` | `"database"` |
+
+***
+
+<a id="datasnapshot"></a>
+
+### DataSnapshot
+
+Firebase-shaped RTDB snapshot runtime value.
+
+#### Extended by
+
+- [`IteratedDataSnapshot`](#iterateddatasnapshot)
+
+#### Constructors
+
+<a id="constructor-1"></a>
+
+##### Constructor
+
+```ts
+new DataSnapshot(implementation?: DataSnapshotImplementation): DataSnapshot;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `implementation?` | [`DataSnapshotImplementation`](#datasnapshotimplementation) |
+
+###### Returns
+
+[`DataSnapshot`](#datasnapshot)
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="ref"></a> `ref` | `readonly` | [`DatabaseReference`](#databasereference) |
+
+#### Accessors
+
+<a id="key"></a>
+
+##### key
+
+###### Get Signature
+
+```ts
+get key(): string;
+```
+
+###### Returns
+
+`string`
+
+<a id="priority"></a>
+
+##### priority
+
+###### Get Signature
+
+```ts
+get priority(): string | number;
+```
+
+###### Returns
+
+`string` \| `number`
+
+<a id="size"></a>
+
+##### size
+
+###### Get Signature
+
+```ts
+get size(): number;
+```
+
+###### Returns
+
+`number`
+
+#### Methods
+
+<a id="child"></a>
+
+##### child()
+
+```ts
+child(path: string): DataSnapshot;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `path` | `string` |
+
+###### Returns
+
+[`DataSnapshot`](#datasnapshot)
+
+<a id="exists"></a>
+
+##### exists()
+
+```ts
+exists(): boolean;
+```
+
+###### Returns
+
+`boolean`
+
+<a id="exportval"></a>
+
+##### exportVal()
+
+```ts
+exportVal(): JsonValue;
+```
+
+###### Returns
+
+[`JsonValue`](#jsonvalue)
+
+<a id="foreach"></a>
+
+##### forEach()
+
+```ts
+forEach(cb: (child: DataSnapshot) => boolean | void): boolean;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `cb` | (`child`: [`DataSnapshot`](#datasnapshot)) => `boolean` \| `void` |
+
+###### Returns
+
+`boolean`
+
+<a id="haschild"></a>
+
+##### hasChild()
+
+```ts
+hasChild(path: string): boolean;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `path` | `string` |
+
+###### Returns
+
+`boolean`
+
+<a id="haschildren"></a>
+
+##### hasChildren()
+
+```ts
+hasChildren(): boolean;
+```
+
+###### Returns
+
+`boolean`
+
+<a id="tojson"></a>
+
+##### toJSON()
+
+```ts
+toJSON(): JsonValue;
+```
+
+###### Returns
+
+[`JsonValue`](#jsonvalue)
+
+<a id="val"></a>
+
+##### val()
+
+```ts
+val(): JsonValue;
+```
+
+###### Returns
+
+[`JsonValue`](#jsonvalue)
+
+***
+
+<a id="ondisconnect"></a>
+
+### OnDisconnect
+
+#### Methods
+
+<a id="cancel"></a>
+
+##### cancel()
+
+```ts
+cancel(): Promise<void>;
+```
+
+###### Returns
+
+`Promise`\<`void`\>
+
+<a id="remove"></a>
+
+##### remove()
+
+```ts
+remove(): Promise<void>;
+```
+
+###### Returns
+
+`Promise`\<`void`\>
+
+<a id="set"></a>
+
+##### set()
+
+```ts
+set(value: unknown): Promise<void>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `value` | `unknown` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+<a id="setwithpriority"></a>
+
+##### setWithPriority()
+
+```ts
+setWithPriority(value: unknown, priority: string | number): Promise<void>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `value` | `unknown` |
+| `priority` | `string` \| `number` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+<a id="update"></a>
+
+##### update()
+
+```ts
+update(values: Record<string, unknown>): Promise<void>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `values` | `Record`\<`string`, `unknown`\> |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+***
+
+<a id="queryconstraint"></a>
+
+### QueryConstraint
+
+Opaque constraint produced by the order/filter/limit query functions.
+
+#### Constructors
+
+<a id="constructor-2"></a>
+
+##### Constructor
+
+```ts
+new QueryConstraint(type?: QueryConstraintType, internal?: Constraint): QueryConstraint;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `type?` | [`QueryConstraintType`](#queryconstrainttype-1) |
+| `internal?` | `Constraint` |
+
+###### Returns
+
+[`QueryConstraint`](#queryconstraint)
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="constraint_symbol"></a> `[CONSTRAINT_SYMBOL]` | `readonly` | `Constraint` |
+| <a id="type-1"></a> `type` | `readonly` | [`QueryConstraintType`](#queryconstrainttype-1) |
 
-<a id="database"></a>
+***
 
-### Database
+<a id="transactionresult"></a>
 
-Opaque RTDB handle. Routes via [TARGET\_SYMBOL](#target_symbol-1).
+### TransactionResult
+
+Result of [runTransaction](#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`.
+
+#### Constructors
+
+<a id="constructor-3"></a>
+
+##### Constructor
+
+```ts
+new TransactionResult(committed?: boolean, snapshot?: DataSnapshot): TransactionResult;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `committed?` | `boolean` |
+| `snapshot?` | [`DataSnapshot`](#datasnapshot) |
+
+###### Returns
+
+[`TransactionResult`](#transactionresult)
 
 #### Properties
 
 | Property | Modifier | Type |
 | :------ | :------ | :------ |
-| <a id="target_symbol"></a> `[TARGET_SYMBOL]` | `readonly` | `Target` |
-| <a id="app"></a> `app?` | `readonly` | [`FirebaseApp`](pyric-app-reference-api.md#firebaseapp) |
+| <a id="committed"></a> `committed` | `readonly` | `boolean` |
+| <a id="snapshot"></a> `snapshot` | `readonly` | [`DataSnapshot`](#datasnapshot) |
 
-***
+#### Methods
+
+<a id="tojson-2"></a>
+
+##### toJSON()
+
+```ts
+toJSON(): {
+  committed: boolean;
+  snapshot: JsonValue;
+};
+```
+
+###### Returns
+
+```ts
+{
+  committed: boolean;
+  snapshot: JsonValue;
+}
+```
+
+###### committed
+
+```ts
+committed: boolean;
+```
+
+###### snapshot
+
+```ts
+snapshot: JsonValue;
+```
+
+## Interfaces
 
 <a id="databasereference"></a>
 
@@ -31,6 +456,10 @@ the modular SDK uses idiomatically as plain free-function args.
 
 `toString()` returns a stable `sandbox://` URL.
 
+#### Extends
+
+- [`Query`](#query)
+
 #### Extended by
 
 - [`ThenableReference`](#thenablereference)
@@ -39,12 +468,52 @@ the modular SDK uses idiomatically as plain free-function args.
 
 | Property | Modifier | Type |
 | :------ | :------ | :------ |
-| <a id="key"></a> `key` | `readonly` | `string` |
+| <a id="query_symbol"></a> `[QUERY_SYMBOL]` | `readonly` | `true` |
+| <a id="key-1"></a> `key` | `readonly` | `string` |
 | <a id="parent"></a> `parent` | `readonly` | [`DatabaseReference`](#databasereference) |
+| <a id="ref-1"></a> `ref` | `readonly` | [`DatabaseReference`](#databasereference) |
 | <a id="root"></a> `root` | `readonly` | [`DatabaseReference`](#databasereference) |
 
 #### Methods
 
+<a id="isequal"></a>
+
+##### isEqual()
+
+```ts
+isEqual(other: Query): boolean;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `other` | [`Query`](#query) |
+
+###### Returns
+
+`boolean`
+
+###### Inherited from
+
+[`Query`](#query).[`isEqual`](#isequal-2)
+
+<a id="tojson-4"></a>
+
+##### toJSON()
+
+```ts
+toJSON(): string;
+```
+
+###### Returns
+
+`string`
+
+###### Inherited from
+
+[`Query`](#query).[`toJSON`](#tojson-10)
+
 <a id="tostring"></a>
 
 ##### toString()
@@ -57,29 +526,201 @@ toString(): string;
 
 `string`
 
+###### Inherited from
+
+[`Query`](#query).[`toString`](#tostring-2)
+
 ***
 
-<a id="datasnapshot"></a>
+<a id="datasnapshotimplementation"></a>
 
-### DataSnapshot
+### DataSnapshotImplementation
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="key-2"></a> `key` | `readonly` | `string` |
+| <a id="priority-1"></a> `priority` | `readonly` | `string` \| `number` |
+| <a id="ref-2"></a> `ref` | `readonly` | [`DatabaseReference`](#databasereference) |
+| <a id="size-1"></a> `size` | `readonly` | `number` |
+
+#### Methods
+
+<a id="child-2"></a>
+
+##### child()
+
+```ts
+child(path: string): DataSnapshot;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `path` | `string` |
+
+###### Returns
+
+[`DataSnapshot`](#datasnapshot)
+
+<a id="exists-2"></a>
+
+##### exists()
 
-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.
+```ts
+exists(): boolean;
+```
+
+###### Returns
+
+`boolean`
+
+<a id="exportval-2"></a>
+
+##### exportVal()
+
+```ts
+exportVal(): JsonValue;
+```
+
+###### Returns
+
+[`JsonValue`](#jsonvalue)
+
+<a id="foreach-2"></a>
+
+##### forEach()
+
+```ts
+forEach(cb: (child: DataSnapshot) => boolean | void): boolean;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `cb` | (`child`: [`DataSnapshot`](#datasnapshot)) => `boolean` \| `void` |
+
+###### Returns
+
+`boolean`
+
+<a id="haschild-2"></a>
+
+##### hasChild()
+
+```ts
+hasChild(path: string): boolean;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `path` | `string` |
+
+###### Returns
+
+`boolean`
+
+<a id="haschildren-2"></a>
+
+##### hasChildren()
+
+```ts
+hasChildren(): boolean;
+```
+
+###### Returns
+
+`boolean`
+
+<a id="tojson-6"></a>
+
+##### toJSON()
+
+```ts
+toJSON(): JsonValue;
+```
+
+###### Returns
+
+[`JsonValue`](#jsonvalue)
+
+<a id="val-2"></a>
+
+##### val()
+
+```ts
+val(): JsonValue;
+```
+
+###### Returns
+
+[`JsonValue`](#jsonvalue)
+
+***
+
+<a id="iterateddatasnapshot"></a>
+
+### IteratedDataSnapshot
+
+Child snapshot supplied during ordered iteration; its key is never null.
+
+#### Extends
+
+- [`DataSnapshot`](#datasnapshot)
 
 #### Properties
 
-| Property | Modifier | Type | Description |
+| Property | Modifier | Type | Overrides |
 | :------ | :------ | :------ | :------ |
-| <a id="key-1"></a> `key` | `readonly` | `string` | - |
-| <a id="priority"></a> `priority` | `readonly` | `string` \| `number` | The node's priority, or `null`. The sandbox does not model RTDB's priority values, so this is always `null`, matching the common case (no `.priority` set). Mirrors `api/Reference_impl.ts:312`. |
-| <a id="ref"></a> `ref` | `readonly` | [`DatabaseReference`](#databasereference) | The ref the snap was taken from. |
-| <a id="size"></a> `size` | `readonly` | `number` | 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`. |
+| <a id="key-3"></a> `key` | `readonly` | `string` | [`DataSnapshot`](#datasnapshot).[`key`](#key) |
+| <a id="ref-3"></a> `ref` | `readonly` | [`DatabaseReference`](#databasereference) | - |
+
+#### Accessors
+
+<a id="priority-2"></a>
+
+##### priority
+
+###### Get Signature
+
+```ts
+get priority(): string | number;
+```
+
+###### Returns
+
+`string` \| `number`
+
+###### Inherited from
+
+[`DataSnapshot`](#datasnapshot).[`priority`](#priority)
+
+<a id="size-2"></a>
+
+##### size
+
+###### Get Signature
+
+```ts
+get size(): number;
+```
+
+###### Returns
+
+`number`
+
+###### Inherited from
+
+[`DataSnapshot`](#datasnapshot).[`size`](#size)
 
 #### Methods
 
-<a id="child"></a>
+<a id="child-4"></a>
 
 ##### child()
 
@@ -97,7 +738,11 @@ child(path: string): DataSnapshot;
 
 [`DataSnapshot`](#datasnapshot)
 
-<a id="exists"></a>
+###### Inherited from
+
+[`DataSnapshot`](#datasnapshot).[`child`](#child)
+
+<a id="exists-4"></a>
 
 ##### exists()
 
@@ -109,7 +754,11 @@ exists(): boolean;
 
 `boolean`
 
-<a id="exportval"></a>
+###### Inherited from
+
+[`DataSnapshot`](#datasnapshot).[`exists`](#exists)
+
+<a id="exportval-4"></a>
 
 ##### exportVal()
 
@@ -117,15 +766,15 @@ exists(): boolean;
 exportVal(): JsonValue;
 ```
 
-Like `val()` but includes priority info (for backups). With no
-priority modeled, this equals `val()`. Mirrors
-`api/Reference_impl.ts:374-376`.
-
 ###### Returns
 
 [`JsonValue`](#jsonvalue)
 
-<a id="foreach"></a>
+###### Inherited from
+
+[`DataSnapshot`](#datasnapshot).[`exportVal`](#exportval)
+
+<a id="foreach-4"></a>
 
 ##### forEach()
 
@@ -133,16 +782,6 @@ priority modeled, this equals `val()`. Mirrors
 forEach(cb: (child: DataSnapshot) => boolean | void): boolean;
 ```
 
-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 [Query](#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).
-
 ###### Parameters
 
 | Parameter | Type |
@@ -153,7 +792,11 @@ RTDB SDK does NOT guarantee an order on plain refs either).
 
 `boolean`
 
-<a id="haschild"></a>
+###### Inherited from
+
+[`DataSnapshot`](#datasnapshot).[`forEach`](#foreach)
+
+<a id="haschild-4"></a>
 
 ##### hasChild()
 
@@ -171,7 +814,11 @@ hasChild(path: string): boolean;
 
 `boolean`
 
-<a id="haschildren"></a>
+###### Inherited from
+
+[`DataSnapshot`](#datasnapshot).[`hasChild`](#haschild)
+
+<a id="haschildren-4"></a>
 
 ##### hasChildren()
 
@@ -183,7 +830,11 @@ hasChildren(): boolean;
 
 `boolean`
 
-<a id="tojson"></a>
+###### Inherited from
+
+[`DataSnapshot`](#datasnapshot).[`hasChildren`](#haschildren)
+
+<a id="tojson-8"></a>
 
 ##### toJSON()
 
@@ -195,7 +846,11 @@ toJSON(): JsonValue;
 
 [`JsonValue`](#jsonvalue)
 
-<a id="val"></a>
+###### Inherited from
+
+[`DataSnapshot`](#datasnapshot).[`toJSON`](#tojson)
+
+<a id="val-4"></a>
 
 ##### val()
 
@@ -207,56 +862,92 @@ val(): JsonValue;
 
 [`JsonValue`](#jsonvalue)
 
+###### Inherited from
+
+[`DataSnapshot`](#datasnapshot).[`val`](#val)
+
+***
+
+<a id="listenoptions"></a>
+
+### ListenOptions
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="onlyonce"></a> `onlyOnce?` | `readonly` | `boolean` |
+
 ***
 
 <a id="query"></a>
 
 ### Query
 
-RTDB-shaped Query — a ref + an immutable constraint chain. Mirrors
-`firebase/database`'s `Query` for the subset of methods the modular
-SDK uses idiomatically.
+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 a stable `sandbox://` URL.
+
+#### Extended by
 
-Construct with [query](#query-1); pass to [get](#get) or [onValue](#onvalue).
+- [`DatabaseReference`](#databasereference)
 
 #### Properties
 
-| Property | Modifier | Type | Description |
-| :------ | :------ | :------ | :------ |
-| <a id="query_symbol"></a> `[QUERY_SYMBOL]` | `readonly` | `true` | - |
-| <a id="ref-1"></a> `ref` | `readonly` | [`DatabaseReference`](#databasereference) | The Query's location. Used by `query()` chaining + listener fan-out. |
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="query_symbol-1"></a> `[QUERY_SYMBOL]` | `readonly` | `true` |
+| <a id="ref-4"></a> `ref` | `readonly` | [`DatabaseReference`](#databasereference) |
 
 #### Methods
 
-<a id="tostring-2"></a>
+<a id="isequal-2"></a>
 
-##### toString()
+##### isEqual()
 
 ```ts
-toString(): string;
+isEqual(other: Query): boolean;
 ```
 
-Resolves to the same URL the ref would.
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `other` | [`Query`](#query) |
 
 ###### Returns
 
-`string`
+`boolean`
 
-***
+<a id="tojson-10"></a>
 
-<a id="queryconstraint"></a>
+##### toJSON()
 
-### QueryConstraint
+```ts
+toJSON(): string;
+```
 
-Opaque constraint produced by `orderByChild` / `equalTo` / `limitToFirst`
-etc. Pass to [query](#query-1).
+###### Returns
 
-#### Properties
+`string`
 
-| Property | Modifier | Type | Description |
-| :------ | :------ | :------ | :------ |
-| <a id="constraint_symbol"></a> `[CONSTRAINT_SYMBOL]` | `readonly` | `Constraint` | - |
-| <a id="type"></a> `type` | `readonly` | \| `"orderByChild"` \| `"orderByKey"` \| `"orderByValue"` \| `"startAt"` \| `"startAfter"` \| `"endAt"` \| `"endBefore"` \| `"equalTo"` \| `"limitToFirst"` \| `"limitToLast"` | The constraint's variant — surfaces as the SDK's `QueryConstraintType` strings. |
+<a id="tostring-2"></a>
+
+##### toString()
+
+```ts
+toString(): string;
+```
+
+###### Returns
+
+`string`
 
 ***
 
@@ -282,8 +973,10 @@ throw synchronously and lose the key). Oracle:
 
 | Property | Modifier | Type |
 | :------ | :------ | :------ |
-| <a id="key-2"></a> `key` | `readonly` | `string` |
+| <a id="query_symbol-2"></a> `[QUERY_SYMBOL]` | `readonly` | `true` |
+| <a id="key-4"></a> `key` | `readonly` | `string` |
 | <a id="parent-1"></a> `parent` | `readonly` | [`DatabaseReference`](#databasereference) |
+| <a id="ref-5"></a> `ref` | `readonly` | [`DatabaseReference`](#databasereference) |
 | <a id="root-1"></a> `root` | `readonly` | [`DatabaseReference`](#databasereference) |
 
 #### Methods
@@ -312,6 +1005,28 @@ catch<TResult>(onrejected?: (reason: unknown) => TResult | PromiseLike<TResult>)
 
 `Promise`\<[`DatabaseReference`](#databasereference) \| `TResult`\>
 
+<a id="isequal-4"></a>
+
+##### isEqual()
+
+```ts
+isEqual(other: Query): boolean;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `other` | [`Query`](#query) |
+
+###### Returns
+
+`boolean`
+
+###### Inherited from
+
+[`DatabaseReference`](#databasereference).[`isEqual`](#isequal)
+
 <a id="then"></a>
 
 ##### then()
@@ -338,6 +1053,22 @@ then<TResult1, TResult2>(onfulfilled?: (value: DatabaseReference) => TResult1 |
 
 `Promise`\<`TResult1` \| `TResult2`\>
 
+<a id="tojson-12"></a>
+
+##### toJSON()
+
+```ts
+toJSON(): string;
+```
+
+###### Returns
+
+`string`
+
+###### Inherited from
+
+[`DatabaseReference`](#databasereference).[`toJSON`](#tojson-4)
+
 <a id="tostring-4"></a>
 
 ##### toString()
@@ -356,30 +1087,15 @@ toString(): string;
 
 ***
 
-<a id="transactionresult"></a>
-
-### TransactionResult
-
-Result of [runTransaction](#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).
+<a id="transactionoptions"></a>
 
-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`.
+### TransactionOptions
 
 #### Properties
 
 | Property | Modifier | Type |
 | :------ | :------ | :------ |
-| <a id="committed"></a> `committed` | `readonly` | `boolean` |
-| <a id="snapshot"></a> `snapshot` | `readonly` | [`DataSnapshot`](#datasnapshot) |
+| <a id="applylocally"></a> `applyLocally?` | `readonly` | `boolean` |
 
 ## Type Aliases
 
@@ -405,6 +1121,37 @@ readonly app: FirebaseApp;
 
 ***
 
+<a id="emulatormocktokenoptions"></a>
+
+### EmulatorMockTokenOptions
+
+```ts
+type EmulatorMockTokenOptions =
+  | {
+  user_id: string;
+}
+  | {
+  sub: string;
+} & Partial<FirebaseIdTokenShape>;
+```
+
+***
+
+<a id="eventtype"></a>
+
+### EventType
+
+```ts
+type EventType =
+  | "value"
+  | "child_added"
+  | "child_changed"
+  | "child_moved"
+  | "child_removed";
+```
+
+***
+
 <a id="jsonvalue"></a>
 
 ### JsonValue
@@ -449,6 +1196,27 @@ This module is identity-agnostic — rules evaluation happens in
 
 ***
 
+<a id="queryconstrainttype-1"></a>
+
+### QueryConstraintType
+
+```ts
+type QueryConstraintType =
+  | "orderByChild"
+  | "orderByKey"
+  | "orderByPriority"
+  | "orderByValue"
+  | "startAt"
+  | "startAfter"
+  | "endAt"
+  | "endBefore"
+  | "equalTo"
+  | "limitToFirst"
+  | "limitToLast";
+```
+
+***
+
 <a id="unsubscribe"></a>
 
 ### Unsubscribe()
@@ -463,7 +1231,19 @@ type Unsubscribe = () => void;
 
 ## Variables
 
-<a id="query_symbol-1"></a>
+<a id="constraint_symbol-1"></a>
+
+### CONSTRAINT\_SYMBOL
+
+```ts
+const CONSTRAINT_SYMBOL: unique symbol;
+```
+
+Hidden brand on every QueryConstraint.
+
+***
+
+<a id="query_symbol-3"></a>
 
 ### QUERY\_SYMBOL
 
@@ -471,9 +1251,7 @@ type Unsubscribe = () => void;
 const QUERY_SYMBOL: unique symbol;
 ```
 
-Hidden brand on every [Query](#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.
+Hidden brand on every Query.
 
 ***
 
@@ -586,7 +1364,32 @@ Hidden brand on every [Database](#database) handle.
 
 ## Functions
 
-<a id="child-2"></a>
+<a id="buildsandboxref"></a>
+
+### buildSandboxRef()
+
+```ts
+function buildSandboxRef(target: SandboxTarget | SandboxLiveTarget, path: string): DatabaseReference;
+```
+
+Build a sandbox-backed `DatabaseReference`. Cached parent / root
+pointers are computed lazily so a long chain doesn't materialise
+every intermediate ref upfront.
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `target` | `SandboxTarget` \| `SandboxLiveTarget` |
+| `path` | `string` |
+
+#### Returns
+
+[`DatabaseReference`](#databasereference)
+
+***
+
+<a id="child-6"></a>
 
 ### child()
 
@@ -623,7 +1426,7 @@ function connectDatabaseEmulator(
    _host: string,
    _port: number,
    _options?: {
-  mockUserToken?: string | Record<string, unknown>;
+  mockUserToken?: string | EmulatorMockTokenOptions;
 }): void;
 ```
 
@@ -637,8 +1440,8 @@ selected backend already is the local sandbox.
 | `_db` | [`Database`](#database) |
 | `_host` | `string` |
 | `_port` | `number` |
-| `_options?` | \{ `mockUserToken?`: `string` \| `Record`\<`string`, `unknown`\>; \} |
-| `_options.mockUserToken?` | `string` \| `Record`\<`string`, `unknown`\> |
+| `_options?` | \{ `mockUserToken?`: `string` \| [`EmulatorMockTokenOptions`](#emulatormocktokenoptions); \} |
+| `_options.mockUserToken?` | `string` \| [`EmulatorMockTokenOptions`](#emulatormocktokenoptions) |
 
 #### Returns
 
@@ -793,7 +1596,7 @@ sandbox (see [forceLongPolling](#forcelongpolling)).
 ### get()
 
 ```ts
-function get(r: DatabaseReference | Query): Promise<DataSnapshot>;
+function get(r: Query | DatabaseReference): Promise<DataSnapshot>;
 ```
 
 `get(ref)` — one-shot read at the ref's path. Resolves to a
@@ -809,7 +1612,7 @@ Matches the SDK's `DataSnapshot.val()` contract.
 
 | Parameter | Type |
 | :------ | :------ |
-| `r` | [`DatabaseReference`](#databasereference) \| [`Query`](#query) |
+| `r` | [`Query`](#query) \| [`DatabaseReference`](#databasereference) |
 
 #### Returns
 
@@ -1024,21 +1827,19 @@ console.log(snap.val()); // { text: 'hi' }
 ### goOffline()
 
 ```ts
-function goOffline(_db: Database): void;
+function goOffline(db: Database): void;
 ```
 
 `goOffline(db)` — disconnect the client from the RTDB backend.
 
-No-op on sandbox handles: there is NO network connection in the local
-sandbox to toggle, so honest behavior is to accept the call and do
-nothing (we deliberately do NOT simulate a disconnect — pending
-writes, listeners, and `get()` all keep working exactly as before).
+Drains this client's one-shot onDisconnect queue. The shared data backend
+remains available to other Database clients and listeners.
 
 #### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `_db` | [`Database`](#database) |
+| `db` | [`Database`](#database) |
 
 #### Returns
 
@@ -1051,19 +1852,19 @@ writes, listeners, and `get()` all keep working exactly as before).
 ### goOnline()
 
 ```ts
-function goOnline(_db: Database): void;
+function goOnline(db: Database): void;
 ```
 
 `goOnline(db)` — reconnect the client to the RTDB backend.
 
-No-op on sandbox handles (there is no connection to reopen — see
-[goOffline](#gooffline)).
+Reconnects the logical client. Executed disconnect operations are not
+resurrected; reads and writes remain synchronous in the local sandbox.
 
 #### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `_db` | [`Database`](#database) |
+| `db` | [`Database`](#database) |
 
 #### Returns
 
@@ -1151,7 +1952,7 @@ function limitToLast(n: number): QueryConstraint;
 
 ```ts
 function off(
-   r: DatabaseReference,
+   r: Query | DatabaseReference,
    eventType?: "value" | ChildEvent,
    callback?: (snap: DataSnapshot) => void): void;
 ```
@@ -1176,7 +1977,7 @@ registration — both are supported.
 
 | Parameter | Type |
 | :------ | :------ |
-| `r` | [`DatabaseReference`](#databasereference) |
+| `r` | [`Query`](#query) \| [`DatabaseReference`](#databasereference) |
 | `eventType?` | `"value"` \| `ChildEvent` |
 | `callback?` | (`snap`: [`DataSnapshot`](#datasnapshot)) => `void` |
 
@@ -1191,7 +1992,11 @@ registration — both are supported.
 ### onChildAdded()
 
 ```ts
-function onChildAdded(r: DatabaseReference | Query, cb: (snap: DataSnapshot) => void): Unsubscribe;
+function onChildAdded(
+   r: Query | DatabaseReference,
+   cb: (snap: DataSnapshot, previousChildName: string) => void,
+   cancelCallbackOrOptions?: ListenOptions | (error: Error) => void,
+   options?: ListenOptions): Unsubscribe;
 ```
 
 `onChildAdded(ref, cb)` — subscribe to child-added events at the
@@ -1201,7 +2006,7 @@ Semantics (locked by oracle observations under
 `packages/conformance/observations/rtdb-modular/rtdb-modular-onchildadded-*.json`):
 
   - On subscribe, replays every existing direct child of `ref`'s path
-    (one fire per existing key, in `orderByKey`-default order).
+    (one fire per existing key, in default priority/key order).
   - After subscribe, fires exactly once per new direct child write.
 
 Also accepts a [Query](#query) (a `query(ref, ...)` with `orderBy*` /
@@ -1216,8 +2021,10 @@ Returns an unsubscribe; calling it twice is a no-op.
 
 | Parameter | Type |
 | :------ | :------ |
-| `r` | [`DatabaseReference`](#databasereference) \| [`Query`](#query) |
-| `cb` | (`snap`: [`DataSnapshot`](#datasnapshot)) => `void` |
+| `r` | [`Query`](#query) \| [`DatabaseReference`](#databasereference) |
+| `cb` | (`snap`: [`DataSnapshot`](#datasnapshot), `previousChildName`: `string`) => `void` |
+| `cancelCallbackOrOptions?` | [`ListenOptions`](#listenoptions) \| (`error`: `Error`) => `void` |
+| `options?` | [`ListenOptions`](#listenoptions) |
 
 #### Returns
 
@@ -1230,7 +2037,11 @@ Returns an unsubscribe; calling it twice is a no-op.
 ### onChildChanged()
 
 ```ts
-function onChildChanged(r: DatabaseReference | Query, cb: (snap: DataSnapshot) => void): Unsubscribe;
+function onChildChanged(
+   r: Query | DatabaseReference,
+   cb: (snap: DataSnapshot, previousChildName: string) => void,
+   cancelCallbackOrOptions?: ListenOptions | (error: Error) => void,
+   options?: ListenOptions): Unsubscribe;
 ```
 
 `onChildChanged(ref, cb)` — subscribe to child-changed events.
@@ -1249,8 +2060,10 @@ window changes value (an in-window update).
 
 | Parameter | Type |
 | :------ | :------ |
-| `r` | [`DatabaseReference`](#databasereference) \| [`Query`](#query) |
-| `cb` | (`snap`: [`DataSnapshot`](#datasnapshot)) => `void` |
+| `r` | [`Query`](#query) \| [`DatabaseReference`](#databasereference) |
+| `cb` | (`snap`: [`DataSnapshot`](#datasnapshot), `previousChildName`: `string`) => `void` |
+| `cancelCallbackOrOptions?` | [`ListenOptions`](#listenoptions) \| (`error`: `Error`) => `void` |
+| `options?` | [`ListenOptions`](#listenoptions) |
 
 #### Returns
 
@@ -1263,31 +2076,32 @@ window changes value (an in-window update).
 ### onChildMoved()
 
 ```ts
-function onChildMoved(r: DatabaseReference | Query, cb: (snap: DataSnapshot) => void): Unsubscribe;
+function onChildMoved(
+   r: Query | DatabaseReference,
+   cb: (snap: DataSnapshot, previousChildName: string) => void,
+   cancelCallbackOrOptions?: ListenOptions | (error: Error) => void,
+   options?: ListenOptions): 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).
+  - Explicit queries use their active `orderBy*` index.
+  - Plain refs use Firebase's default priority index, so changing a
+    child's priority can move it while an ordinary value-only write does not.
 
-Accepts a [Query](#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`).
+Accepts a [Query](#query) and fires when the active ordered value changes,
+including the Firebase `previousChildName` second callback argument.
 
 #### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `r` | [`DatabaseReference`](#databasereference) \| [`Query`](#query) |
-| `cb` | (`snap`: [`DataSnapshot`](#datasnapshot)) => `void` |
+| `r` | [`Query`](#query) \| [`DatabaseReference`](#databasereference) |
+| `cb` | (`snap`: [`DataSnapshot`](#datasnapshot), `previousChildName`: `string`) => `void` |
+| `cancelCallbackOrOptions?` | [`ListenOptions`](#listenoptions) \| (`error`: `Error`) => `void` |
+| `options?` | [`ListenOptions`](#listenoptions) |
 
 #### Returns
 
@@ -1300,7 +2114,11 @@ in `test/database/modular/sandbox-child-events.test.ts`).
 ### onChildRemoved()
 
 ```ts
-function onChildRemoved(r: DatabaseReference | Query, cb: (snap: DataSnapshot) => void): Unsubscribe;
+function onChildRemoved(
+   r: Query | DatabaseReference,
+   cb: (snap: DataSnapshot, previousChildName: string) => void,
+   cancelCallbackOrOptions?: ListenOptions | (error: Error) => void,
+   options?: ListenOptions): Unsubscribe;
 ```
 
 `onChildRemoved(ref, cb)` — subscribe to child-removed events.
@@ -1321,8 +2139,10 @@ displaced past a `limitTo*` boundary or filtered out) fires
 
 | Parameter | Type |
 | :------ | :------ |
-| `r` | [`DatabaseReference`](#databasereference) \| [`Query`](#query) |
-| `cb` | (`snap`: [`DataSnapshot`](#datasnapshot)) => `void` |
+| `r` | [`Query`](#query) \| [`DatabaseReference`](#databasereference) |
+| `cb` | (`snap`: [`DataSnapshot`](#datasnapshot), `previousChildName`: `string`) => `void` |
+| `cancelCallbackOrOptions?` | [`ListenOptions`](#listenoptions) \| (`error`: `Error`) => `void` |
+| `options?` | [`ListenOptions`](#listenoptions) |
 
 #### Returns
 
@@ -1330,17 +2150,39 @@ displaced past a `limitTo*` boundary or filtered out) fires
 
 ***
 
+<a id="ondisconnect-1"></a>
+
+### onDisconnect()
+
+```ts
+function onDisconnect(r: DatabaseReference): OnDisconnect;
+```
+
+Register a one-shot write for this Database client's next disconnect.
+Registration checks rules immediately; execution checks them again.
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `r` | [`DatabaseReference`](#databasereference) |
+
+#### Returns
+
+[`OnDisconnect`](#ondisconnect)
+
+***
+
 <a id="onvalue"></a>
 
 ### onValue()
 
 ```ts
 function onValue(
-   r: DatabaseReference | Query,
+   r: Query | DatabaseReference,
    cb: (snap: DataSnapshot) => void,
-   options?: {
-  onlyOnce?: boolean;
-}): Unsubscribe;
+   cancelCallbackOrOptions?: ListenOptions | (error: Error) => void,
+   options?: ListenOptions): Unsubscribe;
 ```
 
 `onValue(ref, cb)` — subscribe to value changes at the ref's path.
@@ -1355,18 +2197,18 @@ 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).
+With a cancellation callback, an initially denied listen returns normally
+and reports the Firebase `PERMISSION_DENIED` error asynchronously. Without
+one, the sandbox preserves its legacy synchronous throw.
 
 #### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `r` | [`DatabaseReference`](#databasereference) \| [`Query`](#query) |
+| `r` | [`Query`](#query) \| [`DatabaseReference`](#databasereference) |
 | `cb` | (`snap`: [`DataSnapshot`](#datasnapshot)) => `void` |
-| `options?` | \{ `onlyOnce?`: `boolean`; \} |
-| `options.onlyOnce?` | `boolean` |
+| `cancelCallbackOrOptions?` | [`ListenOptions`](#listenoptions) \| (`error`: `Error`) => `void` |
+| `options?` | [`ListenOptions`](#listenoptions) |
 
 #### Returns
 
@@ -1415,6 +2257,23 @@ function orderByKey(): QueryConstraint;
 
 ***
 
+<a id="orderbypriority"></a>
+
+### orderByPriority()
+
+```ts
+function orderByPriority(): QueryConstraint;
+```
+
+`orderByPriority()` — order children by their RTDB priority metadata,
+with Firebase's key ordering as the tie-breaker.
+
+#### Returns
+
+[`QueryConstraint`](#queryconstraint)
+
+***
+
 <a id="orderbyvalue"></a>
 
 ### orderByValue()
@@ -1491,7 +2350,7 @@ Returns a freshly-minted key.
 ### query()
 
 ```ts
-function query(refOrQuery: DatabaseReference | Query, ...constraints: QueryConstraint[]): Query;
+function query(refOrQuery: Query | DatabaseReference, ...constraints: QueryConstraint[]): Query;
 ```
 
 `query(ref, ...constraints)` — wrap a ref in an immutable
@@ -1521,7 +2380,7 @@ Locked semantics (oracle):
 
 | Parameter | Type |
 | :------ | :------ |
-| `refOrQuery` | [`DatabaseReference`](#databasereference) \| [`Query`](#query) |
+| `refOrQuery` | [`Query`](#query) \| [`DatabaseReference`](#databasereference) |
 | ...`constraints` | [`QueryConstraint`](#queryconstraint)[] |
 
 #### Returns
@@ -1530,7 +2389,7 @@ Locked semantics (oracle):
 
 ***
 
-<a id="ref-2"></a>
+<a id="ref-6"></a>
 
 ### ref()
 
@@ -1567,12 +2426,8 @@ function refFromURL(db: Database, url: string): DatabaseReference;
 `refFromURL(db, url)` — build a [DatabaseReference](#databasereference) from an
 absolute database URL (`https://<namespace>.firebaseio.com/path`).
 
-Real alias with real behavior: parses the path out of the URL and
-delegates to [ref](#ref-2), so the returned ref resolves + reads exactly
-like `ref(db, path)`. The sandbox is single-database and has no host /
-namespace, so the URL's HOST is not validated against the handle (the
-real SDK throws if the host doesn't match the db's namespace); only
-the path component is honored.
+The sandbox is single-database, so only the URL path is honored; unlike the
+production SDK, the host is not checked against the database namespace.
 
 #### Parameters
 
@@ -1587,7 +2442,7 @@ the path component is honored.
 
 ***
 
-<a id="remove"></a>
+<a id="remove-2"></a>
 
 ### remove()
 
@@ -1621,9 +2476,7 @@ the same code path as `set(_, null)`.
 function runTransaction<T>(
    r: DatabaseReference,
    transactionUpdate: (current: T) => T,
-   options?: {
-  applyLocally?: boolean;
-}): Promise<TransactionResult>;
+options?: TransactionOptions): Promise<TransactionResult>;
 ```
 
 `runTransaction(ref, transactionUpdate, options?)` — atomic
@@ -1661,9 +2514,8 @@ 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.
+A synchronous overlapping write during the update callback invalidates the
+read and retries the callback. Writes to unrelated paths do not conflict.
 
 #### Type Parameters
 
@@ -1677,8 +2529,7 @@ exists to conflict with). The fn is invoked once.
 | :------ | :------ |
 | `r` | [`DatabaseReference`](#databasereference) |
 | `transactionUpdate` | (`current`: `T`) => `T` |
-| `options?` | \{ `applyLocally?`: `boolean`; \} |
-| `options.applyLocally?` | `boolean` |
+| `options?` | [`TransactionOptions`](#transactionoptions) |
 
 #### Returns
 
@@ -1707,7 +2558,7 @@ The sandbox backend recognises the marker.
 
 ***
 
-<a id="set"></a>
+<a id="set-2"></a>
 
 ### set()
 
@@ -1734,6 +2585,52 @@ deletes (matches the RTDB invariant — locked by oracle observation
 
 ***
 
+<a id="setpriority"></a>
+
+### setPriority()
+
+```ts
+function setPriority(r: DatabaseReference, priority: string | number): Promise<void>;
+```
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `r` | [`DatabaseReference`](#databasereference) |
+| `priority` | `string` \| `number` |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+<a id="setwithpriority-2"></a>
+
+### setWithPriority()
+
+```ts
+function setWithPriority(
+   r: DatabaseReference,
+   value: unknown,
+priority: string | number): Promise<void>;
+```
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `r` | [`DatabaseReference`](#databasereference) |
+| `value` | `unknown` |
+| `priority` | `string` \| `number` |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
 <a id="startafter"></a>
 
 ### startAfter()
@@ -1783,7 +2680,7 @@ function startAt(value: JsonValue, key?: string): QueryConstraint;
 
 ***
 
-<a id="update"></a>
+<a id="update-2"></a>
 
 ### update()