Documentation / @etherfold/browser / streamSubtree

Function: streamSubtree()

streamSubtree(name, digest): object

Defined in: packages/browser/src/storage/stream/OnIndexedDB.ts:54

One stream's address, BY DIGEST: a HIERARCHICAL array key.

['stream', <indexer-name>, <streamDigest>, <ordinal>]   a segment
['stream', <indexer-name>, <streamDigest>, 'cursor']    the cursor record

An earlier design packed these components into one delimited STRING and then needed an anchored regex, a cross-chain corruption hazard (stream_tag_1 is a prefix of stream_tag_10_0), a temp-name rule and an extra keeper operation. All of that was a consequence of the flat namespace: comparing key ELEMENTS cannot confuse chain 1 with chain 10, so the hazard is gone rather than withLegacyBlobProbe. There is no string-prefix matching anywhere below.

The DIGEST level is @etherfold/core's streamDigestOf: what the stream CONTAINS -- its fetch filter and its stream config -- and nothing about who indexed it. chainId is not a level of its own because that digest already covers it (its block-0 skeleton entry hashes chainId and genesisHash), and <indexer-name> is the caller-supplied discriminator, untouched here. This level held a chain-<chainId> PLACEHOLDER while the digest was being built; subtrees written under it are simply unreachable now, and disposing of them belongs to the sweep in the generation registry, which is the only place that can know which digests are registered.

It is addressed BY THE DIGEST rather than by a {source, config} because that sweep reaches subtrees it cannot resolve a source for: an orphan is a digest and nothing else. streamAddress below is the same subtree for a caller that has the source in hand.

Parameters

name

string

digest

string

Returns

cursor

cursor: IDBValidKey

prefix

prefix: IDBValidKey[]

segment

segment: (ordinal) => IDBValidKey

Parameters

ordinal

number

Returns

IDBValidKey

segments

segments: IDBKeyRange

The two ranges, which are NOT the same and using the wrong one is a real bug.

IndexedDB orders number < string < array. So the SUBTREE range, whose upper bound is an empty ARRAY, spans the 'cursor' record along with the ordinals -- which is what clear wants and what keeps the cursor from being orphaned by a scoped delete. A SEGMENTS-ONLY read has to exclude the string bound, or a full ordered scan would come back with the cursor record sitting in it as though it were a segment.

The subtree's LOWER bound is the prefix itself (exclusive) rather than ordinal 0, so it spans every key below this digest whatever its last element is. That matters to the registry's sweep, which drops subtrees written by code that is GONE: what a dead digest rule put down there is not this module's to assume.

subtree

subtree: IDBKeyRange