API reference: @pyric/ui/rtdb

Interfaces

RtdbApi

The RTDB backend seam the viewer drives — an EXPLICIT bundle, not a context default. Unlike Firestore/Auth/Storage there is no in-process handle typed into @pyric/ui, so the consumer constructs the bundle and passes it to the hook/components directly (Studio wires it to the SharedWorker client’s admin-lens ops; data views are always admin — PRINCIPLES M3).

Methods

remove()

remove(path: string): Promise<void>;

Delete the subtree at path.

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<void>

set()

set(path: string, value: unknown): Promise<void>;

Replace the value at path (null deletes, RTDB semantics).

Parameters

Parameter	Type
`path`	`string`
`value`	`unknown`

Returns

Promise<void>

subscribeValue()

subscribeValue(
   path: string,
   next: (value: unknown) => void,
   error?: (err: unknown) => void): () => void;

Live value subscription at path: next fires with the subtree’s plain JSON value (null when absent) on subscribe and after every change. Returns the unsubscribe.

Parameters

Parameter	Type
`path`	`string`
`next`	(`value`: `unknown`) => `void`
`error?`	(`err`: `unknown`) => `void`

Returns

(): void;

Returns

void

RtdbCrumb

Properties

Property	Type	Description
`label`	`string`	The path segment to display.
`path`	`string`	Absolute database path this crumb navigates to.

RtdbPathBarProps

Properties

Property	Type	Description
`className?`	`string`	-
`inputPrefix?`	`string`	Text shown before the input while editing (the non-editable URL part).
`onNavigate`	(`path`: `string`) => `void`	Fired with the parsed absolute path on crumb click or input submit.
`path`	`string`	Current absolute database path (`'/'` for root).
`rootLabel?`	`ReactNode`	Root crumb label — the database/instance identity (e.g. the sandbox slug). Default `'/'`.

RtdbTreeController

Everything a tree view needs: the reducer state plus path-addressed selectors and the expansion/paging commands. All paths are ABSOLUTE database paths.

Properties

Property	Type
`pageSize`	`number`
`state`	`RtdbTreeState`

Methods

childrenAt()

childrenAt(path: string): RtdbVisibleChildren;

Parameters

Parameter	Type
`path`	`string`

Returns

RtdbVisibleChildren

isExpanded()

isExpanded(path: string): boolean;

Parameters

Parameter	Type
`path`	`string`

Returns

boolean

showMore()

showMore(path: string): void;

Parameters

Parameter	Type
`path`	`string`

Returns

void

toggle()

toggle(path: string): void;

Parameters

Parameter	Type
`path`	`string`

Returns

void

updateAt()

updateAt(path: string): UpdateHighlight;

Parameters

Parameter	Type
`path`	`string`

Returns

UpdateHighlight

valueAt()

valueAt(path: string): unknown;

Parameters

Parameter	Type
`path`	`string`

Returns

unknown

RtdbTreeProps

Properties

Property	Type	Description
`api`	`RtdbApi`	Mutation backend (admin lens in Studio).
`className?`	`string`	-
`onNavigate?`	(`path`: `string`) => `void`	Key-click navigation: re-roots the viewer at the clicked node (wire to the same path state as the path bar).
`rootLabel?`	`ReactNode`	Label for the view-root row when the root is `'/'` — the database / instance identity. Default `'/'`.
`tree`	`RtdbTreeController`	The live tree controller from `useRtdbTree`.

RtdbTreeState

RTDB viewer tree state (pure reducer). The interaction form is the Firebase console / firebase-tools-ui data viewer: one view root (set by the path bar), expandable/collapsible descendants, and per-level paging for wide child lists.

DATA-LOADING STRATEGY (documented decision): the worker protocol exposes rtdb.get / value subscriptions per PATH but no shallow or depth-limited reads — a read at a path always ships that path’s WHOLE subtree over the MessagePort. A per-expand fetch would therefore re-ship data the view-root read already delivered. So the viewer holds ONE live value subscription at the view root (realtime by construction) and makes RENDERING lazy instead: nodes below the root start collapsed and mount nothing until expanded, and an expanded level renders at most pageSize children until “show more” (console-style paging at 50, chosen over virtualization for its simplicity — it bounds the mounted DOM the same way). Cost is bounded by navigating the view root deeper, which is the path bar’s job.

Properties

Property	Type	Description
`error`	`string`	-
`expanded`	`Record`<`string`, `true`>	Expanded descendant paths (absolute). The view root itself is always expanded and is never in this set.
`pages`	`Record`<`string`, `number`>	Per-path shown-children override (absolute path → count). Absent means one page.
`path`	`string`	The view root — the absolute database path the path bar points at.
`status`	`"error"` \| `"live"` \| `"loading"`	`loading` until the first snapshot after a navigate; then `live`.
`value`	`unknown`	The subtree value AT `path` (plain JSON; `null` = nothing there).

RtdbVisibleChildren

Properties

Property	Type	Description
`entries`	[`string`, `unknown`][]	The children to render, in key order, capped at the shown count.
`hiddenCount`	`number`	How many more “show more” would reveal (0 = all shown).
`total`	`number`	Total direct children at this path.

UseRtdbTreeOptions

Properties

Property	Type	Description
`pageSize?`	`number`	Children rendered per level before “show more”. Default 50.

Type Aliases

RtdbEditorResult

type RtdbEditorResult =
  | {
  ok: true;
  value: unknown;
}
  | {
  error: string;
  ok: false;
};

RtdbEditorType

type RtdbEditorType = "string" | "number" | "boolean" | "json";

Inline value-editor logic (pure): the type select + text input pair used by the tree’s click-to-edit and add-child rows. Four author-facing types cover every RTDB value: string / number / boolean scalars, and json for objects/arrays/null (or any hand-written literal).

RtdbTreeAction

type RtdbTreeAction =
  | {
  path: string;
  type: "navigate";
}
  | {
  path: string;
  type: "value";
  value: unknown;
}
  | {
  message: string;
  path: string;
  type: "error";
}
  | {
  path: string;
  type: "toggle";
}
  | {
  path: string;
  type: "expand";
}
  | {
  path: string;
  type: "collapse";
}
  | {
  pageSize: number;
  path: string;
  type: "show-more";
};

Type Declaration

{
  path: string;
  type: "navigate";
}

path

path: string;

type

type: "navigate";

Path bar navigation: reset to a new view root.

{
  path: string;
  type: "value";
  value: unknown;
}

path

path: string;

type

type: "value";

value

value: unknown;

A value snapshot arrived. path is the subscription’s view root — a snapshot from a superseded subscription (its path no longer the state’s) is ignored.

{
  message: string;
  path: string;
  type: "error";
}

message

message: string;

path

path: string;

type

type: "error";

The view-root subscription failed (same path guard as value).

{
  path: string;
  type: "toggle";
}

path

path: string;

type

type: "toggle";

{
  path: string;
  type: "expand";
}

path

path: string;

type

type: "expand";

{
  path: string;
  type: "collapse";
}

path

path: string;

type

type: "collapse";

{
  pageSize: number;
  path: string;
  type: "show-more";
}

pageSize

pageSize: number;

path

path: string;

type

type: "show-more";

Reveal one more page of children at path.

Variables

RTDB_DEFAULT_PAGE_SIZE

const RTDB_DEFAULT_PAGE_SIZE: 50 = 50;

Console-style child paging (Firebase console shows 50, then “show more”).

RTDB_EDITOR_TYPES

const RTDB_EDITOR_TYPES: readonly RtdbEditorType[];

Functions

coerceRtdbEditorValue()

function coerceRtdbEditorValue(type: RtdbEditorType, text: string): RtdbEditorResult;

Coerce the editor’s text under the selected type, or explain why not.

Parameters

Parameter	Type
`type`	`RtdbEditorType`
`text`	`string`

Returns

RtdbEditorResult

formatRtdbEditorValue()

function formatRtdbEditorValue(value: unknown, type: RtdbEditorType): string;

Seed the editor’s text field from the current value under a type.

Parameters

Parameter	Type
`value`	`unknown`
`type`	`RtdbEditorType`

Returns

string

formatRtdbJson()

function formatRtdbJson(value: unknown): string;

@pyric/ui/rtdb — the headless RTDB data viewer, in the Firebase console / firebase-tools-ui form: an editable path bar (crumbs + direct path entry) over an expandable tree with inline add/edit/delete affordances. Follows this package’s firestore/auth/storage split: pure logic + hooks + unstyled components on data-* styling contracts; the consumer (Studio) brings the CSS and the backend bundle (RtdbApi).

Parameters

Parameter	Type
`value`	`unknown`

Returns

string

formatRtdbValueLabel()

function formatRtdbValueLabel(value: unknown): string;

Leaf value text, console style: strings quoted, primitives literal. Defensive on objects: never String-coerce (that’s [object Object]) — fall back to JSON. Object values should have been normalized/expanded away before reaching a leaf label; this keeps the label honest if one slips in.

Parameters

Parameter	Type
`value`	`unknown`

Returns

string

hasRtdbChildren()

function hasRtdbChildren(value: unknown): boolean;

Does this value render as a PARENT node (has child keys)? RTDB has no true arrays — an array is an object with numeric keys, and renders as one.

Parameters

Parameter	Type
`value`	`unknown`

Returns

boolean

inferRtdbEditorType()

function inferRtdbEditorType(value: unknown): RtdbEditorType;

The editor type a value opens under when clicked.

Parameters

Parameter	Type
`value`	`unknown`

Returns

RtdbEditorType

initialRtdbTree()

function initialRtdbTree(path: string): RtdbTreeState;

Parameters

Parameter	Type
`path`	`string`

Returns

RtdbTreeState

isRtdbObjectValue()

function isRtdbObjectValue(value: unknown): value is Record<string, unknown>;

Parameters

Parameter	Type
`value`	`unknown`

Returns

value is Record<string, unknown>

isRtdbPathExpanded()

function isRtdbPathExpanded(state: RtdbTreeState, path: string): boolean;

Is this absolute path expanded? The view root always is.

Parameters

Parameter	Type
`state`	`RtdbTreeState`
`path`	`string`

Returns

boolean

joinRtdbPath()

function joinRtdbPath(base: string, child: string): string;

Parameters

Parameter	Type
`base`	`string`
`child`	`string`

Returns

string

normalizeRtdbPath()

function normalizeRtdbPath(path: string): string;

RTDB path + value helpers (pure). Paths are ALWAYS normalized to the '/'-rooted form ('/' for the root, '/a/b' otherwise) so every module in this package — the tree reducer, the path bar, the viewer components — agrees on what a path is.

Parameters

Parameter	Type
`path`	`string`

Returns

string

normalizeRtdbSnapshotValue()

function normalizeRtdbSnapshotValue(value: unknown): unknown;

Normalize a snapshot value to RTDB semantics before it enters tree state: an empty object IS null (RTDB has no empty containers — the server prunes them), so {} — and any object whose children all normalize away — becomes null. Without this, an empty database’s root value {} fails hasRtdbChildren and renders as a scalar leaf (String({}) → "[object Object]"). Reuses the input object when nothing changed.

Parameters

Parameter	Type
`value`	`unknown`

Returns

unknown

parentRtdbPath()

function parentRtdbPath(path: string): string;

Parameters

Parameter	Type
`path`	`string`

Returns

string

parseRtdbJson()

function parseRtdbJson(value: string): unknown;

Parameters

Parameter	Type
`value`	`string`

Returns

unknown

parseRtdbPathInput()

function parseRtdbPathInput(raw: string): string;

Normalize raw path-input text to a database path. Tolerant of what people paste into a database URL bar:

a plain path, with or without the leading slash (rooms/r1, /rooms)
a full URL (https://x.firebaseio.com/rooms/r1 → /rooms/r1)
repeated/trailing slashes, surrounding whitespace
a ?query / #hash tail (dropped) Empty input is the root.

Parameters

Parameter	Type
`raw`	`string`

Returns

string

previewRtdbValue()

function previewRtdbValue(value: unknown): string;

Parameters

Parameter	Type
`value`	`unknown`

Returns

string

relativeRtdbPath()

function relativeRtdbPath(base: string, target: string): string;

The path of target RELATIVE to base, or null when target is not base or one of its descendants. '/' means “target IS base”. Lets the tree address nodes by absolute database path while the loaded value sits at the view root.

Parameters

Parameter	Type
`base`	`string`
`target`	`string`

Returns

string

rtdbChildEntries()

function rtdbChildEntries(value: unknown): [string, unknown][];

Child entries sorted RTDB-console style: numeric-aware key order (2 before 10), then lexicographic.

Parameters

Parameter	Type
`value`	`unknown`

Returns

[string, unknown][]

rtdbCrumbs()

function rtdbCrumbs(path: string): RtdbCrumb[];

The non-root crumbs for a path, in order. '/' yields [] — the root crumb is the caller’s (it carries the database/instance label, not a segment).

Parameters

Parameter	Type
`path`	`string`

Returns

RtdbCrumb[]

rtdbKeyInputError()

function rtdbKeyInputError(key: string): string;

Why a typed child key is unusable, or null when it’s fine. RTDB forbids . $ # [ ] / in keys (a / would silently create a nested path).

Parameters

Parameter	Type
`key`	`string`

Returns

string

RtdbPathBar()

function RtdbPathBar(__namedParameters: RtdbPathBarProps): Element;

The editable path bar of the RTDB viewer — the interaction form of the Firebase console / firebase-tools-ui database URL bar (clean-room adaptation): in DISPLAY mode the path renders as clickable crumbs (root → … → current) plus an edit affordance; EDIT mode swaps in a text input seeded with the current path — Enter navigates, Escape or blur cancels. Pasted full URLs and missing leading slashes are tolerated (parseRtdbPathInput).

Headless. Consumers style via:

[data-pyric-ui="rtdb-path-bar"] — the root (data-rtdb-editing when editing)
[data-rtdb-crumb] / [data-rtdb-crumb-root] / [data-pyric-current]
[data-rtdb-crumb-separator]
[data-rtdb-path-edit] — the edit button
[data-rtdb-path-form], [data-rtdb-path-prefix], [data-rtdb-path-input]

Parameters

Parameter	Type
`__namedParameters`	`RtdbPathBarProps`

Returns

Element

rtdbPathSegments()

function rtdbPathSegments(path: string): string[];

Parameters

Parameter	Type
`path`	`string`

Returns

string[]

RtdbTree()

function RtdbTree(__namedParameters: RtdbTreeProps): Element;

The RTDB data tree — the interaction form of the Firebase console / firebase-tools-ui database viewer (clean-room adaptation of the NodeContainer/NodeParent/NodeLeaf split):

parents render a caret (expand/collapse), leaves a key: value row;
keys navigate (re-root the view), carets only toggle;
hover/focus reveals per-node actions: + add child, × delete — delete flips to an INLINE two-step confirm (no modal, C3);
leaf values are click-to-edit inline (type select: string / number / boolean / JSON);
wide levels page at tree.pageSize with a “show more” row (the console’s form — see reducers/tree.ts for why paging over virtualization).

Headless: consumers style [data-pyric-ui="rtdb-tree"] and the data-rtdb-* attributes (node, row, caret, key, sep, value, actions, action-add, action-delete, confirm, editor, children, show-more, error, loading). An empty root renders the console’s classic form — <root>: null — not an instructional empty state.

Parameters

Parameter	Type
`__namedParameters`	`RtdbTreeProps`

Returns

Element

rtdbTreeReducer()

function rtdbTreeReducer(state: RtdbTreeState, action: RtdbTreeAction): RtdbTreeState;

Parameters

Parameter	Type
`state`	`RtdbTreeState`
`action`	`RtdbTreeAction`

Returns

RtdbTreeState

rtdbTreeValueAt()

function rtdbTreeValueAt(state: RtdbTreeState, path: string): unknown;

The subtree value at an ABSOLUTE database path, resolved against the loaded view-root value. null outside the view root.

Parameters

Parameter	Type
`state`	`RtdbTreeState`
`path`	`string`

Returns

unknown

rtdbValueAt()

function rtdbValueAt(root: unknown, path: string): unknown;

Parameters

Parameter	Type
`root`	`unknown`
`path`	`string`

Returns

unknown

rtdbValueKind()

function rtdbValueKind(value: unknown): string;

Parameters

Parameter	Type
`value`	`unknown`

Returns

string

rtdbVisibleChildren()

function rtdbVisibleChildren(
   state: RtdbTreeState,
   path: string,
   pageSize: number): RtdbVisibleChildren;

The page-capped child list at an absolute path (console pages at 50).

Parameters

Parameter	Type
`state`	`RtdbTreeState`
`path`	`string`
`pageSize`	`number`

Returns

RtdbVisibleChildren

useRtdbTree()

function useRtdbTree(
   api: RtdbApi,
   path: string,
   options?: UseRtdbTreeOptions): RtdbTreeController;

Live tree state for the RTDB viewer: subscribes to the value at the view root path (realtime — every write re-delivers the subtree) and runs the expansion/paging reducer over it. See reducers/tree.ts for the one-subscription-per-view-root loading strategy and why expansion is a pure render toggle rather than a fetch.

Parameters

Parameter	Type
`api`	`RtdbApi`
`path`	`string`
`options?`	`UseRtdbTreeOptions`

Returns

RtdbTreeController