Storage

The two tiers an environment keeps state in: the session it holds while it is open, and the interaction store that outlives the visit.

@internote/canvas-sdk21 exports

#Functions

createCanvasStorage
packages/canvas-sdk/src/storage/index.ts:74
Assemble an environment's storage surface from its definition's declaration and the host's backends.
<S = unknown>(
    declaration: CanvasStorageDeclaration | undefined,
    session: EnvironmentSessionState<S>,
    db?: KeyValueStorage,
): CanvasStorage<S>
createTransientCollection
packages/canvas-sdk/src/storage/transient.ts:123
A channel carrying one reading per MARK per environment — a legend row for each heatmap, a key for each choropleth.
<T>(equal?: TransientEqual<T>): TransientCollection<T>

The snapshot is rebuilt on write and shared between reads, which is not a detail: useSyncExternalStore compares the snapshot by identity and spins forever on a getter that builds a new array each time.

createTransientValue
packages/canvas-sdk/src/storage/transient.ts:79
A channel carrying one reading per environment.
<T>(equal?: TransientEqual<T>): TransientValue<T>

Declared at module scope beside the surface that publishes it, exactly as the five private stores were: the channel is the contract between an environment's surface and its own footer, and nothing outside that pair should be reading it.

environmentKey
packages/canvas-sdk/src/storage/session.ts:38
The session-store key for an environment: its three ids joined by spaces.
(identity: EnvironmentIdentity): string
keyValueFromInteractionStore
packages/canvas-sdk/src/storage/interaction.ts:88
Adapt an InteractionStore into a KeyValueStorage scoped to a single element hash.
(store: InteractionStore, elementHash: string): KeyValueStorage

#Classes

SessionStore
packages/canvas-sdk/src/storage/session.ts:63
The session store one canvas host owns.
typeof SessionStore

#Constants

noopInteractionStore
packages/canvas-sdk/src/storage/interaction.ts:53
An InteractionStore that keeps nothing: reads return null and saves resolve without storing.
InteractionStore
noopKeyValueStorage
packages/canvas-sdk/src/storage/interaction.ts:76
A KeyValueStorage that keeps nothing: get resolves to null and writes resolve without storing.
KeyValueStorage

#Interfaces

CanvasStorage
packages/canvas-sdk/src/storage/index.ts:49
The storage surface an environment sees, assembled by the host per declaration.
dbRequired
Database tier — present only for tiers: 'session+db' types; a no-op store elsewhere so type code can be written unconditionally.
KeyValueStorage
sessionRequired
The environment's reading-session state: survives scroll-away and rides continue:, never persisted.
EnvironmentSessionState<S>
CanvasStorageDeclaration
packages/canvas-sdk/src/storage/index.ts:39
The storage an environment asks for, in its definition's storage field.
initState
Initial session state for a freshly mounted environment.
() => unknown
serializeForContinue
Shape the state handed to a continue: successor. Defaults to identity.
(state: unknown) => unknown
tiersRequired
Whether the environment gets the database tier as well as the session tier.
sessionsession+db
EnvironmentIdentity
packages/canvas-sdk/src/storage/session.ts:28
Where one canvas environment sits: the internote, the scene and the environment within it.

Session state is keyed by all three, so an environment keeps its state across scroll-away and a continue: successor can find its source.

environmentIdRequired
The environment within the scene.
string
internoteIdRequired
The internote the environment belongs to.
string
sceneIdRequired
The scene within the internote.
string
EnvironmentSessionState
packages/canvas-sdk/src/storage/session.ts:43
An environment-scoped view over the session store.
clearRequired
Deletes the state and notifies subscribers.
void
getRequired
The environment's current state, or undefined before anything was written.
S | undefined
setRequired
Replaces the state and notifies subscribers.
void
subscribeRequired
Notified after every write to this environment's state (set/update/clear/handoff).
() => void
updateRequired
Replace via updater — convenience for instrument reducers.
void
InteractionStore
packages/canvas-sdk/src/storage/interaction.ts:45
Where elements keep a reader's interaction state, one value per element, keyed by the element's content hash.

Keying by content means the same authored element finds its state again after a reload. The host supplies the implementation.

getInteractionRequired
Reads what an element stored, or null when it stored nothing.
GetInteraction
saveInteractionRequired
Replaces what an element stored.
SaveInteraction
KeyValueStorage
packages/canvas-sdk/src/storage/interaction.ts:66
An element's own key/value store, handed to its render function as api.storage.

Every element gets a separate namespace, so keys never collide between elements. It is the storage surface plugins get.

deleteRequired
Removes a key and its value.
Promise<void>
getRequired
Resolves to the value stored under a key, or null when there is none.
Promise<T | null>
setRequired
Stores a value under a key, replacing any before it.
Promise<void>
TransientCollection
packages/canvas-sdk/src/storage/transient.ts:106
Several readings per environment, one per publishing mark.
setRequired
Publish under memberKey, or null to take that member's entry away.
void
snapshotRequired
Every member's reading, in insertion order — a stable array between changes.
readonly T[]
subscribeRequired
Notified after every real change to THIS environment's collection.
() => void
TransientValue
packages/canvas-sdk/src/storage/transient.ts:62
One reading per environment: a cursor position, a scale bar, a focused mark.
getRequired
The current reading, or null.
T | null
setRequired
Publish, or null to withdraw. Subscribers wake only on a real change.
void
subscribeRequired
Notified after every real change to THIS environment's reading.
() => void

#Types

Addressed
packages/canvas-sdk/src/storage/transient.ts:51
How a publisher says which environment it is speaking for: an EnvironmentContext, the identity itself, or the store key.
string | EnvironmentIdentity | { identity: EnvironmentIdentity }

The bare key is there for the marks. A heatmap or a choropleth sits deep inside a surface's tree and is handed its environment's key as a prop — threading the whole identity down to it would be ceremony for a value that is already the thing this store is keyed by.

GetInteraction
packages/canvas-sdk/src/storage/interaction.ts:35
What one element stored, or null when it stored nothing.
(elementHash: string) => unknown
SaveInteraction
packages/canvas-sdk/src/storage/interaction.ts:37
Stores what one element wants kept, replacing whatever it stored before; resolves once saved.
(elementHash: string, content: unknown) => Promise<void>
StorageTiers
packages/canvas-sdk/src/storage/index.ts:36
Which storage an environment asks for: 'session' for state that lasts while the page is open, or 'session+db' to also save each reader's answers.
sessionsession+db
TransientEqual
packages/canvas-sdk/src/storage/transient.ts:59
Whether a new reading says anything the old one did not.
(previous: T, next: T) => boolean

Last updated