Navigate

API reference

pyric/sandbox/checkpoints

20 published symbols from pyric

Generated from the TypeScript declarations shipped at this import path.

Classes

CheckpointNameError

A checkpoint name a backend refuses. Thrown rather than returned: it is a caller mistake.

Extends

  • Error

Constructors

Constructor
new CheckpointNameError(name: string): CheckpointNameError;
Parameters
ParameterType
namestring
Returns

CheckpointNameError

Overrides
Error.constructor

Interfaces

Checkpoint

One checkpoint: the whole sandbox at an instant, with the counts over it.

Properties

PropertyTypeDescription
atnumberWhen the checkpoint was taken, in milliseconds since the epoch.
countsCheckpointCountsHow much each service held. Read by a listing so it needs no state.
format"pyric-checkpoint-v1"-
stateFullSandboxStateThe whole sandbox, as one plain JSON value.

CheckpointBackend

Where checkpoints are kept.

A backend stores and returns whole Checkpoint values and decides nothing about them. It rejects a name that does not match CHECKPOINT_NAME_PATTERN by throwing CheckpointNameError, because a name that could reach outside its keeping place is a caller mistake rather than a missing checkpoint.

Properties

PropertyModifierTypeDescription
storage?readonly"reference" | "inline"How checkpoints kept here record Storage bytes. reference names each object by hash and suits a backend that keeps those bytes itself, so a checkpoint copies none of them. Absent means inline.

Methods

list()
list(): Promise<CheckpointListing[]>;

Every checkpoint the backend holds, ordered by name.

Returns

Promise<CheckpointListing[]>

read()
read(name: string): Promise<Checkpoint>;

The checkpoint stored under name, or null when the backend holds none.

Parameters
ParameterType
namestring
Returns

Promise<Checkpoint>

remove()
remove(name: string): Promise<boolean>;

Remove one checkpoint. Reports whether there was one to remove.

Parameters
ParameterType
namestring
Returns

Promise<boolean>

write()
write(name: string, checkpoint: Checkpoint): Promise<void>;

Write one checkpoint under name, replacing whatever that name held.

Parameters
ParameterType
namestring
checkpointCheckpoint
Returns

Promise<void>


CheckpointCounts

How much each service held when the checkpoint was taken.

Properties

PropertyTypeDescription
authnumberAuth accounts.
databasenumberTop-level keys of the Realtime Database tree.
firestorenumberFirestore documents.
storagenumberStorage objects.

CheckpointListing

One entry of a checkpoint listing: the name plus what a caller reads without loading state.

Properties

PropertyType
atnumber
countsCheckpointCounts
namestring

SavedCheckpoint

What a save reports: the checkpoint written, and whether it replaced one.

Properties

PropertyType
checkpointCheckpoint
namestring
overwroteboolean

Variables

CHECKPOINT_FORMAT

const CHECKPOINT_FORMAT: "pyric-checkpoint-v1" = "pyric-checkpoint-v1";

The tag every checkpoint carries, so an unrelated record is not read as one.


CHECKPOINT_NAME_PATTERN

const CHECKPOINT_NAME_PATTERN: RegExp;

The names a checkpoint may take. One filename segment and one record id, so a name can never reach outside the place its backend keeps checkpoints.

Functions

assertCheckpointName()

function assertCheckpointName(name: string): void;

Reject a name that is not one segment of a backend’s keyspace.

Parameters

ParameterType
namestring

Returns

void


captureCheckpoint()

function captureCheckpoint(sandbox: LocalSandbox, options?: FullStateCaptureOptions): Promise<Checkpoint>;

Read the whole sandbox into a checkpoint.

A pure read: nothing in the sandbox changes, and two captures with no intervening write are the same value apart from at.

Parameters

ParameterType
sandboxLocalSandbox
options?FullStateCaptureOptions

Returns

Promise<Checkpoint>


checkpointNames()

function checkpointNames(backend: CheckpointBackend): Promise<string[]>;

The names the backend holds, ordered, for a refusal that has to name them.

Parameters

ParameterType
backendCheckpointBackend

Returns

Promise<string[]>


countsOf()

function countsOf(state: FullSandboxState): CheckpointCounts;

How much each service holds in one state.

Parameters

ParameterType
stateFullSandboxState

Returns

CheckpointCounts


isCheckpointEnvelope()

function isCheckpointEnvelope(value: unknown): value is Checkpoint;

Recognize the envelope; restore validates each service before resetting state.

Parameters

ParameterType
valueunknown

Returns

value is Checkpoint


listCheckpoints()

function listCheckpoints(backend: CheckpointBackend): Promise<CheckpointListing[]>;

Every checkpoint the backend holds, ordered by name.

Parameters

ParameterType
backendCheckpointBackend

Returns

Promise<CheckpointListing[]>


readCheckpoint()

function readCheckpoint(backend: CheckpointBackend, name: string): Promise<Checkpoint>;

The checkpoint kept under name, or null when the backend holds none.

Parameters

ParameterType
backendCheckpointBackend
namestring

Returns

Promise<Checkpoint>


recordCheckpointBackend()

function recordCheckpointBackend(store: PersistenceBackend): CheckpointBackend;

Keep checkpoints as records in store.

Parameters

ParameterTypeDescription
storePersistenceBackendThe record store the host already persists into, which in the served worker is the page’s own IndexedDB.

Returns

CheckpointBackend


removeCheckpoint()

function removeCheckpoint(backend: CheckpointBackend, name: string): Promise<boolean>;

Remove one checkpoint. Reports whether there was one to remove.

Parameters

ParameterType
backendCheckpointBackend
namestring

Returns

Promise<boolean>


restoreCheckpoint()

function restoreCheckpoint(sandbox: LocalSandbox, checkpoint: Checkpoint): Promise<void>;

Replace the whole sandbox with what a checkpoint holds.

A total replace, not a merge: state the sandbox holds that the checkpoint does not is gone when this returns.

The operation log is reset first, and this is the difference between restoring a checkpoint and promoting a branch. Both write a full state, but a promotion continues the sandbox’s history and a restore declares that the history since the checkpoint did not happen. A cursor a reader holds from before the restore names an event in a log that is gone, and the reset is what lets the log say so rather than reading like a continuation.

Parameters

ParameterType
sandboxLocalSandbox
checkpointCheckpoint

Returns

Promise<void>


restoreNamedCheckpoint()

function restoreNamedCheckpoint(
   backend: CheckpointBackend,
   name: string,
sandbox: LocalSandbox): Promise<Checkpoint>;

Put the sandbox back to the checkpoint kept under name, and report which one was restored. Resolves null when the backend holds no such checkpoint, and the sandbox is left exactly as it was.

Parameters

ParameterType
backendCheckpointBackend
namestring
sandboxLocalSandbox

Returns

Promise<Checkpoint>


saveCheckpoint()

function saveCheckpoint(
   backend: CheckpointBackend,
   name: string,
sandbox: LocalSandbox): Promise<SavedCheckpoint>;

Capture the sandbox and keep it under name, replacing whatever that name held.

Parameters

ParameterType
backendCheckpointBackend
namestring
sandboxLocalSandbox

Returns

Promise<SavedCheckpoint>