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
| Parameter | Type |
|---|---|
name | string |
Returns
Overrides
Error.constructor
Interfaces
Checkpoint
One checkpoint: the whole sandbox at an instant, with the counts over it.
Properties
| Property | Type | Description |
|---|---|---|
at | number | When the checkpoint was taken, in milliseconds since the epoch. |
counts | CheckpointCounts | How much each service held. Read by a listing so it needs no state. |
format | "pyric-checkpoint-v1" | - |
state | FullSandboxState | The 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
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
| Parameter | Type |
|---|---|
name | string |
Returns
Promise<Checkpoint>
remove()
remove(name: string): Promise<boolean>;
Remove one checkpoint. Reports whether there was one to remove.
Parameters
| Parameter | Type |
|---|---|
name | string |
Returns
Promise<boolean>
write()
write(name: string, checkpoint: Checkpoint): Promise<void>;
Write one checkpoint under name, replacing whatever that name held.
Parameters
| Parameter | Type |
|---|---|
name | string |
checkpoint | Checkpoint |
Returns
Promise<void>
CheckpointCounts
How much each service held when the checkpoint was taken.
Properties
| Property | Type | Description |
|---|---|---|
auth | number | Auth accounts. |
database | number | Top-level keys of the Realtime Database tree. |
firestore | number | Firestore documents. |
storage | number | Storage objects. |
CheckpointListing
One entry of a checkpoint listing: the name plus what a caller reads without loading state.
Properties
| Property | Type |
|---|---|
at | number |
counts | CheckpointCounts |
name | string |
SavedCheckpoint
What a save reports: the checkpoint written, and whether it replaced one.
Properties
| Property | Type |
|---|---|
checkpoint | Checkpoint |
name | string |
overwrote | boolean |
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
| Parameter | Type |
|---|---|
name | string |
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
| Parameter | Type |
|---|---|
sandbox | LocalSandbox |
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
| Parameter | Type |
|---|---|
backend | CheckpointBackend |
Returns
Promise<string[]>
countsOf()
function countsOf(state: FullSandboxState): CheckpointCounts;
How much each service holds in one state.
Parameters
| Parameter | Type |
|---|---|
state | FullSandboxState |
Returns
isCheckpointEnvelope()
function isCheckpointEnvelope(value: unknown): value is Checkpoint;
Recognize the envelope; restore validates each service before resetting state.
Parameters
| Parameter | Type |
|---|---|
value | unknown |
Returns
value is Checkpoint
listCheckpoints()
function listCheckpoints(backend: CheckpointBackend): Promise<CheckpointListing[]>;
Every checkpoint the backend holds, ordered by name.
Parameters
| Parameter | Type |
|---|---|
backend | CheckpointBackend |
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
| Parameter | Type |
|---|---|
backend | CheckpointBackend |
name | string |
Returns
Promise<Checkpoint>
recordCheckpointBackend()
function recordCheckpointBackend(store: PersistenceBackend): CheckpointBackend;
Keep checkpoints as records in store.
Parameters
| Parameter | Type | Description |
|---|---|---|
store | PersistenceBackend | The record store the host already persists into, which in the served worker is the page’s own IndexedDB. |
Returns
removeCheckpoint()
function removeCheckpoint(backend: CheckpointBackend, name: string): Promise<boolean>;
Remove one checkpoint. Reports whether there was one to remove.
Parameters
| Parameter | Type |
|---|---|
backend | CheckpointBackend |
name | string |
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
| Parameter | Type |
|---|---|
sandbox | LocalSandbox |
checkpoint | Checkpoint |
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
| Parameter | Type |
|---|---|
backend | CheckpointBackend |
name | string |
sandbox | LocalSandbox |
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
| Parameter | Type |
|---|---|
backend | CheckpointBackend |
name | string |
sandbox | LocalSandbox |
Returns
Promise<SavedCheckpoint>