save family

Codecs, save schemas and migrations, save documents, byte storage, save slots and the settings store.

Most symbols on this page come from the package root, import { Name } from "gamekit";. The rest come from gamekit/src/save, as each entry shows.

26 symbols.

Symbol	Summary
canonicalizeValue	function. Recursively rebuilds objects with lexicographically sorted keys while preserving array order and scalar values.
Codec	class. Extensible bidirectional boundary between a runtime type and JSON-compatible save data.
CodecContext	class. Per-operation codec services and policy, including reference resolution and preserved unknown fields.
Codecs	class. Factory namespace for primitive and compositional save codecs.
FaultInjectingByteStorage	class. Test decorator that injects deterministic storage failures, partial writes, and corruption before delegating.
FsByteStorage	class. FsByteStorage implements byte-oriented persistence for save documents and slots.
IByteStorage	interface. Asynchronous text-blob storage boundary used by atomic save and settings workflows.
inspectSaveDocument	function. Parses only a save envelope's positive integer version and optional string schema ID.
MemoryByteStorage	class. Deterministic process-local IByteStorage for tests and ephemeral saves.
MigrationStep	class. One consecutive schema migration with optional validation on both sides of its version boundary.
RecordField	class. Declares one named field in a record codec, including decode presence and default rules.
ReferencePolicy	enum. Chooses whether an unresolved persisted reference fails decoding (STRICT) or decodes as null (ALLOW_NULL).
ReferenceResolver	class. Resolves persisted (kind, id) pairs to live objects from a local registry with an optional fallback.
SaveDocument	class. In-memory representation of a versioned save envelope and its encoded payload.
SaveDocumentHeader	class. Lightweight version and schema identity read without decoding a save payload.
SaveResult	class. Non-throwing outcome for expected persistence, compatibility, and data-quality failures.
SaveResultKind	enum. Distinguishes success, environmental unavailability, invalid data, version incompatibility, and unreadable serialization.
SaveSchema	class. Versioned codec pipeline that canonicalizes writes and validates every consecutive migration boundary on reads.
SaveSlotInfo	class. Listing result for one primary slot, including recoverability and metadata health.
SaveSlotManager	class. Coordinates named, game-defined save documents over caller-provided byte storage.
SaveSlotManagerOptions	class. Naming and rotation configuration for SaveSlotManager storage keys.
SaveSlotMetadata	class. User-facing and schema metadata embedded beside a slot's encoded game data.
serializeCanonical	function. Serializes JSON-compatible data after recursively sorting object keys.
SettingsStore	class. Atomic single-document settings storage, separate from named game-save slots.
SlotCancellationToken	class. Cooperative preflight cancellation flag for queued slot saves and loads.
UnknownFieldPolicy	enum. Chooses whether record decoding rejects undeclared fields or preserves them in CodecContext for round trips.

canonicalizeValue

import { canonicalizeValue } from "gamekit";
function canonicalizeValue(val: any): any

Recursively rebuilds objects with lexicographically sorted keys while preserving array order and scalar values.

• val: JSON-compatible value to normalize.
• Returns: Detached arrays/objects suitable for deterministic serialization.

Codec

import { Codec } from "gamekit";
class Codec<T>

Extensible bidirectional boundary between a runtime type and JSON-compatible save data. The base implementation is an identity codec; concrete codecs validate decode input and report expected failures through SaveResult.

Members

encode(value: T, context?: CodecContext): any

Encodes a runtime value; subclasses may consult resolver and preservation policy from the context.

• value: Runtime value to encode.
• context: Optional per-operation reference and unknown-field state.

decode(data: any, context?: CodecContext): SaveResult<T>

Decodes persisted data; the base class accepts it unchanged.

• data: JSON-compatible representation to decode.
• context: Optional resolver and preservation state shared by nested codecs.
• Returns: Successful typed value or a categorized validation failure.

CodecContext

import { CodecContext } from "gamekit";
class CodecContext

Per-operation codec services and policy, including reference resolution and preserved unknown fields. Reuse the same context across decode and encode when PRESERVE must round-trip forward-compatible fields.

Members

resolver: ReferenceResolver | null

Registry consulted by reference codecs, or null when references cannot resolve.

unknownFieldPolicy: UnknownFieldPolicy

Whether record codecs reject or retain undeclared properties.

referencePolicy: ReferencePolicy

Whether unresolved references fail or become null.

constructor( resolver: ReferenceResolver | null = null, unknownFieldPolicy: UnknownFieldPolicy = UnknownFieldPolicy.REJECT, referencePolicy: ReferencePolicy = ReferencePolicy.STRICT )

Configures services shared by nested codec calls.

• resolver: Reference registry, if the schema contains object identities.
• unknownFieldPolicy: Record behavior for undeclared properties.
• referencePolicy: Decode behavior for missing reference targets.

setPreservedUnknownFields(id: string, fields: any): void

Associates detached unknown-field data with a record identity for later encoding.

• id: Record identity chosen by the record codec.
• fields: Undeclared field object to retain.

getPreservedUnknownFields(id: string): any

Looks up unknown fields previously captured for a record identity.

• id: Record identity used during decoding.
• Returns: Preserved object, or undefined when none was captured.

Codecs

import { Codecs } from "gamekit";
class Codecs

Factory namespace for primitive and compositional save codecs.

Members

static int(): Codec<int>

Creates a codec accepting only finite integral JSON numbers.

static float(): Codec<float>

Creates a codec accepting finite JSON numbers.

static string(): Codec<string>

Creates a codec accepting string values.

static boolean(): Codec<boolean>

Creates a codec accepting boolean values.

static id(): Codec<string>

Creates a codec for non-empty string identifiers.

static optional<T>(codec: Codec<T>): Codec<T | null>

Wraps a codec so null round-trips without invoking the inner codec.

• codec: Inner codec for non-null values.

static array<T>(elementCodec: Codec<T>): Codec<T[]>

Applies one codec to each array element in order and stops at the first decode failure.

• elementCodec: Codec for every element.

static record<T>( fields: RecordField[], factory: (fields: any) => T, extractor: ((val: T, fieldName: string) => any) | null = null ): Codec<T>

Builds a record codec from declared fields and bidirectional value adapters.

• fields: Ordered field definitions written to the record.
• factory: Creates a typed value from successfully decoded named fields.
• extractor: Optional (value, fieldName) reader; direct property access is the default.

static taggedVariant<T>( tagField: string, variants: Map<string, Codec<any>>, tagExtractor: (value: T) => string ): Codec<T>

Builds a discriminated-union codec using a tag persisted in each record.

• tagField: Persisted discriminator property name.
• variants: Codecs indexed by accepted discriminator values.
• tagExtractor: Reads the discriminator from a runtime value during encode.

static reference<T>(kind: string, idExtractor: (value: T) => string): Codec<T>

Builds a codec that persists object identity and resolves it on load.

• kind: Namespace supplied to the context resolver.
• idExtractor: Reads the stable identifier written during encode.

FaultInjectingByteStorage

import { FaultInjectingByteStorage } from "gamekit";
class FaultInjectingByteStorage implements IByteStorage

Test decorator that injects deterministic storage failures, partial writes, and corruption before delegating. One-shot flags clear only when their operation and optional path pattern match.

Members

inner: IByteStorage

Underlying storage used whenever no fault intercepts the call.

failNextWrite: boolean = false

One-shot injected failure flag for the next matching write.

failNextRename: boolean = false

One-shot injected failure flag for the next matching rename.

failNextRead: boolean = false

One-shot injected failure flag for the next matching read.

failNextCopy: boolean = false

One-shot injected failure flag for the next matching copy.

failNextRemove: boolean = false

One-shot injected failure flag for the next matching remove.

failNextExists: boolean = false

One-shot injected failure flag for the next matching exists.

failNextList: boolean = false

One-shot injected failure flag for the next matching list.

failPattern: string = ""

Optional substring limiting path-sensitive one-shot faults; empty matches every path.

quotaExceeded: boolean = false

Persistent flag making every matching write report quota exhaustion.

storageMissing: boolean = false

Persistent flag making all storage operations report a missing device.

partialWriteBytes: int = -1

Non-negative one-shot character count written instead of complete content; -1 disables it.

corruptOnWrite: boolean = false

One-shot flag prefixing matching write content with an invalid marker.

constructor(inner: IByteStorage)

Wraps an existing storage implementation without copying its contents.

• inner: Backend receiving non-intercepted calls.

async read(path: string): Promise<SaveResult<string>>

Injects missing-device or matching one-shot read failure before delegating.

• path: Key tested against failPattern.

async write(path: string, content: string): Promise<SaveResult<boolean>>

Applies missing-device, quota, one-shot failure, partial-write, then corruption behavior in that priority.

• path: Destination key tested against failPattern.
• content: Original complete content.

async remove(path: string): Promise<SaveResult<boolean>>

Injects missing-device or matching one-shot removal failure before delegating.

• path: Key tested against failPattern.

async exists(path: string): Promise<SaveResult<boolean>>

Injects missing-device or matching one-shot existence failure before delegating.

• path: Key tested against failPattern.

async rename(oldPath: string, newPath: string): Promise<SaveResult<boolean>>

Injects rename failure when either source or destination matches, then delegates otherwise.

• oldPath: Source key.
• newPath: Rename destination participating in pattern matching.

async copy(srcPath: string, destPath: string): Promise<SaveResult<boolean>>

Injects copy failure when either key matches, then delegates otherwise.

• srcPath: Source key.
• destPath: Copy destination participating in pattern matching.

async list(prefix: string = ""): Promise<SaveResult<string[]>>

Injects missing-device or one-shot listing failure before delegation; failPattern does not filter list faults.

• prefix: Prefix forwarded to the underlying storage.

FsByteStorage

import { FsByteStorage } from "gamekit/src/save";
class FsByteStorage implements IByteStorage

FsByteStorage implements byte-oriented persistence for save documents and slots.

Members

baseDir: string

Directory used to resolve relative storage paths.

constructor(baseDir: string)

Initializes a fs byte storage with explicit dependencies.

• baseDir: Directory prepended to relative paths; absolute paths bypass it.

async read(path: string): Promise<SaveResult<string>>

FsByteStorage Reads bytes from the requested location.

• path: Source file as an absolute path or relative to baseDir.
• Returns: File contents, or an unavailable result when the file is absent or unreadable.

async write(path: string, content: string): Promise<SaveResult<boolean>>

FsByteStorage Persists the supplied bytes at the requested location.

• path: Destination file as an absolute path or relative to baseDir.
• content: Text payload written after creating missing parent directories.
• Returns: Success with true, or an unavailable result describing the filesystem error.

async remove(path: string): Promise<SaveResult<boolean>>

FsByteStorage Removes the current value if it is registered.

• path: Entry to remove, resolved against baseDir when relative.
• Returns: Success with true even when the path is already absent; filesystem failures are unavailable results.

async exists(path: string): Promise<SaveResult<boolean>>

FsByteStorage Reports whether the requested persisted entry exists.

• path: Entry to query, resolved against baseDir when relative.
• Returns: Success containing the existence flag, or an unavailable result if the check fails.

async rename(oldPath: string, newPath: string): Promise<SaveResult<boolean>>

Moves one entry, creating the destination's parent directories first.

• oldPath: Existing absolute path or path relative to baseDir.
• newPath: Destination absolute path or path relative to baseDir.
• Returns: Success with true, or an unavailable result describing the filesystem error.

async copy(srcPath: string, destPath: string): Promise<SaveResult<boolean>>

FsByteStorage Returns a detached copy safe to retain independently.

• srcPath: Existing absolute path or path relative to baseDir.
• destPath: Destination absolute path or path relative to baseDir.
• Returns: Success with true, or an unavailable result describing the filesystem error.

async list(prefix: string = ""): Promise<SaveResult<string[]>>

Lists direct entries in baseDir in lexical order.

• prefix: Optional filename prefix; an empty string includes every entry.
• Returns: Matching entry names, an empty list for a missing directory, or an unavailable result on failure.

IByteStorage

import { IByteStorage } from "gamekit";
interface IByteStorage

Asynchronous text-blob storage boundary used by atomic save and settings workflows. Environmental failures are returned as SaveResult rather than thrown. Paths are opaque keys to non-filesystem implementations.

Members

read(path: string): Promise<SaveResult<string>>

Reads the complete text blob at a path.

• path: Storage-relative key.
• Returns: Content or UNAVAILABLE when it cannot be read.

write(path: string, content: string): Promise<SaveResult<boolean>>

Replaces or creates a complete text blob.

• path: Destination storage key.
• content: Exact text to persist.

remove(path: string): Promise<SaveResult<boolean>>

Removes a blob; implementations may treat an absent path as success.

• path: Storage key to remove.

exists(path: string): Promise<SaveResult<boolean>>

Checks path presence without reading content.

• path: Storage key to test.

rename(oldPath: string, newPath: string): Promise<SaveResult<boolean>>

Moves one blob to a new key for final atomic replacement where the backend supports it.

• oldPath: Source key that must exist.
• newPath: Destination key to replace.

copy(srcPath: string, destPath: string): Promise<SaveResult<boolean>>

Copies source content to a second key without removing the source.

• srcPath: Source key to read without removal.
• destPath: Destination key to replace.

list(prefix?: string): Promise<SaveResult<string[]>>

Lists storage keys beginning with an optional prefix.

• prefix: Key prefix, or empty/omitted for all entries.
• Returns: Matching keys; deterministic implementations should sort them.

inspectSaveDocument

import { inspectSaveDocument } from "gamekit";
function inspectSaveDocument(text: string): SaveResult<SaveDocumentHeader>

Parses only a save envelope's positive integer version and optional string schema ID.

• text: Candidate JSON document.
• Returns: Header without touching payload data, or CORRUPT/MALFORMED for invalid input.

MemoryByteStorage

import { MemoryByteStorage } from "gamekit";
class MemoryByteStorage implements IByteStorage

Deterministic process-local IByteStorage for tests and ephemeral saves. Paths map directly to strings; all operations resolve immediately and listings are sorted.

Members

async read(path: string): Promise<SaveResult<string>>

Reads the exact string associated with a key.

• path: In-memory key.
• Returns: Content or UNAVAILABLE when absent.

async write(path: string, content: string): Promise<SaveResult<boolean>>

Creates or replaces one in-memory entry.

• path: Key to create or replace.
• content: Exact string to retain.

async remove(path: string): Promise<SaveResult<boolean>>

Deletes a key and succeeds even when it was absent.

• path: Key to delete.

async exists(path: string): Promise<SaveResult<boolean>>

Reports map membership without reading the value.

• path: Key to test.

async rename(oldPath: string, newPath: string): Promise<SaveResult<boolean>>

Moves content and replaces any destination entry.

• oldPath: Key whose entry is moved.
• newPath: Key receiving the moved entry.
• Returns: UNAVAILABLE if the source is absent.

async copy(srcPath: string, destPath: string): Promise<SaveResult<boolean>>

Duplicates content to a destination key, replacing its old value.

• srcPath: Key whose string is duplicated.
• destPath: Key receiving the duplicate.
• Returns: UNAVAILABLE if the source is absent.

async list(prefix: string = ""): Promise<SaveResult<string[]>>

Returns matching keys in lexical order.

• prefix: Optional prefix filter.

clear(): void

Deletes every in-memory entry synchronously.

MigrationStep

import { MigrationStep } from "gamekit";
class MigrationStep

One consecutive schema migration with optional validation on both sides of its version boundary.

Members

sourceVersion: int

Version accepted before migration.

targetVersion: int

Version produced after migration; always sourceVersion + 1.

migrateFn: (data: any) => any

Synchronous transform from source-shaped data to target-shaped data.

validateSourceFn: ((data: any) => SaveResult<boolean>) | null

Optional validation run immediately before the transform.

validateTargetFn: ((data: any) => SaveResult<boolean>) | null

Optional validation run immediately after the transform.

constructor( sourceVersion: int, targetVersion: int, migrateFn: (data: any) => any, validateSourceFn: ((data: any) => SaveResult<boolean>) | null = null, validateTargetFn: ((data: any) => SaveResult<boolean>) | null = null )

Defines a single n -> n+1 migration boundary.

• sourceVersion: Input document version.
• targetVersion: Exactly the next integer version.
• migrateFn: Transform returning non-null target data.
• validateSourceFn: Optional source-shape validator.
• validateTargetFn: Optional target-shape validator.
• Throws: Error unless target is exactly one greater than source.

RecordField

import { RecordField } from "gamekit";
class RecordField

Declares one named field in a record codec, including decode presence and default rules.

Members

name: string

Persisted property name.

codec: Codec<any>

Codec applied to this property's runtime and serialized values.

required: boolean

Whether a missing property is a malformed decode.

defaultValue: any

Runtime value supplied when an optional property is absent.

constructor(name: string, codec: Codec<any>, required: boolean = true, defaultValue: any = null)

Defines record behavior for one property.

• name: Persisted key.
• codec: Value codec for the key.
• required: Whether absence fails decoding.
• defaultValue: Value used when a non-required key is absent.

ReferencePolicy

import { ReferencePolicy } from "gamekit";
enum ReferencePolicy

Chooses whether an unresolved persisted reference fails decoding (STRICT) or decodes as null (ALLOW_NULL).

Member	Meaning
STRICT = 0	Fail decoding when a referenced value cannot be resolved.
ALLOW_NULL = 1	Represent an unresolved reference as null.

ReferenceResolver

import { ReferenceResolver } from "gamekit";
class ReferenceResolver

Resolves persisted (kind, id) pairs to live objects from a local registry with an optional fallback.

Members

constructor(fallbackResolver: ((kind: string, id: string) => any) | null = null)

Creates an empty local registry.

• fallbackResolver: Optional (kind, id) lookup used only after a local miss.

register(kind: string, id: string, target: any): void

Registers or replaces the local target for one namespaced identity.

• kind: Reference namespace.
• id: Stable identifier within that namespace.
• target: Live object returned by later resolution.

resolve(kind: string, id: string): any

Resolves locally first, then delegates to the fallback.

• kind: Reference namespace to search.
• id: Stable identity within the namespace.
• Returns: Registered/fallback target, or null when unresolved.

has(kind: string, id: string): boolean

Tests only the local registry without invoking the fallback.

• kind: Local reference namespace.
• id: Identity to test.

SaveDocument

import { SaveDocument } from "gamekit";
class SaveDocument

In-memory representation of a versioned save envelope and its encoded payload.

Members

version: int

Positive schema version describing data.

schemaId: string

Schema identity, or an empty string for legacy/unidentified documents.

data: any

Codec-produced JSON-compatible payload.

constructor(version: int, data: any, schemaId: string = "")

Wraps already encoded data; validation is performed by SaveSchema.load.

• version: Schema version of the payload.
• data: Encoded payload.
• schemaId: Optional schema identity.

SaveDocumentHeader

import { SaveDocumentHeader } from "gamekit";
class SaveDocumentHeader

Lightweight version and schema identity read without decoding a save payload.

Members

version: int

Positive version declared by the envelope.

schemaId: string

Declared schema identity, or empty when absent/non-string.

constructor(version: int, schemaId: string = "")

Captures inspected envelope metadata.

• version: Validated positive document version.
• schemaId: Optional schema identity.

SaveResult

import { SaveResult } from "gamekit";
class SaveResult<T>

Non-throwing outcome for expected persistence, compatibility, and data-quality failures. Successful results carry value; failures carry kind, message, and the version boundary where known.

Members

isOk: boolean

true only when value contains the requested result.

value: any

Successful payload, or null for factory-created failures.

kind: SaveResultKind

Machine-readable outcome category.

message: string

Human-readable diagnostic for a failed operation.

version: int

Document or migration version associated with the outcome; zero means unavailable.

constructor(isOk: boolean, value: any, kind: SaveResultKind, message: string, version: int = 0)

Creates an explicit outcome record; prefer the named factories at call sites.

• isOk: Success flag governing whether value is meaningful.
• value: Decoded value or operation payload.
• kind: Stable outcome category.
• message: Human-readable diagnostic, normally empty on success.
• version: Relevant schema version, or zero when unknown.

static ok<T>(value: any, version: int = 0): SaveResult<T>

Creates a successful result with kind OK and no diagnostic message.

• value: Successful payload.
• version: Schema version attached to the payload.

static unavailable<T>(message: string, version: int = 0): SaveResult<T>

Reports missing storage, missing slots, cancellation, or environmental I/O failure.

• message: Diagnostic suitable for logs or UI translation.
• version: Known document version, if any.

static malformed<T>(message: string, version: int = 0): SaveResult<T>

Reports a structurally valid envelope whose fields, validation, or migration data are invalid.

• message: Description of the rejected shape or boundary.
• version: Version at which validation failed.

static incompatible<T>(message: string, version: int = 0): SaveResult<T>

Reports a schema ID/version mismatch or missing migration path.

• message: Compatibility explanation.
• version: Document or boundary version that cannot be consumed.

static corrupt<T>(message: string, version: int = 0): SaveResult<T>

Reports unreadable serialization or a non-object save envelope.

• message: Parse or envelope diagnostic.
• version: Known version, normally zero when parsing failed.

SaveResultKind

import { SaveResultKind } from "gamekit";
enum SaveResultKind

Distinguishes success, environmental unavailability, invalid data, version incompatibility, and unreadable serialization.

Member	Meaning
OK = "ok"	The operation completed with a value.
UNAVAILABLE = "unavailable"	Environment or storage access prevented the operation.
MALFORMED = "malformed"	The data does not match its expected encoding.
INCOMPATIBLE = "incompatible"	The data version cannot be read by this schema.
CORRUPT = "corrupt"	Persisted bytes are damaged or incomplete.

SaveSchema

import { SaveSchema } from "gamekit";
class SaveSchema<T>

Versioned codec pipeline that canonicalizes writes and validates every consecutive migration boundary on reads. Expected document failures return SaveResult; constructor/registration misuse throws.

Members

schemaId: string

Identity compared with non-empty document schema IDs.

currentVersion: int

Positive version written by dump and reached by all migration paths.

codec: Codec<T>

Codec applied after migration on load and before envelope creation on dump.

constructor(schemaId: string, currentVersion: int, codec: Codec<T>)

Creates a schema with no historical migration steps or validators.

• schemaId: Expected envelope identity; empty accepts unidentified documents.
• currentVersion: Positive version for new writes.
• codec: Runtime payload codec.
• Throws: Error if current version is not positive.

addMigration(step: MigrationStep): void

Registers one migration keyed by its source version.

• step: Consecutive boundary used when loading that source version.
• Throws: Error if a step for the source version already exists.

addValidator(version: int, validator: (data: any) => SaveResult<boolean>): void

Registers a validation callback for one historical schema version.

• version: Document version whose encoded payload shape is checked.
• validator: Callback returning a success or diagnostic failure.

inspect(text: string): SaveResult<SaveDocumentHeader>

Reads version and schema ID without checking this schema's identity or decoding payload data.

• text: Candidate JSON envelope.
• Returns: Header metadata or categorized parse/shape failure.

dump(value: T, context?: CodecContext, pretty: boolean = false): SaveResult<string>

Encodes a runtime value into a canonical current-version envelope.

• value: Runtime payload to persist.
• context: Optional reference and unknown-field state passed to the codec.
• pretty: Whether to emit two-space-indented canonical JSON.
• Returns: Successful JSON text tagged with currentVersion.

load(text: string, context?: CodecContext): SaveResult<T>

Parses an envelope, verifies identity/version, migrates consecutively with before-and-after validation, then decodes.

• text: Candidate save JSON.
• context: Optional services shared through nested decode calls.
• Returns: Current-version value, or CORRUPT, MALFORMED, or INCOMPATIBLE without throwing expected data failures.

SaveSlotInfo

import { SaveSlotInfo } from "gamekit";
class SaveSlotInfo

Listing result for one primary slot, including recoverability and metadata health.

Members

slotId: string

Logical slot name without storage extensions.

metadata: SaveSlotMetadata | null

Parsed primary-or-backup metadata, or null when inspection failed.

hasBackup: boolean

Whether a backup blob exists for possible recovery.

isCorrupt: boolean

Whether metadata inspection failed for the listed slot.

constructor( slotId: string, metadata: SaveSlotMetadata | null, hasBackup: boolean = false, isCorrupt: boolean = false )

Captures one detached slot-list entry.

• slotId: Name represented by this listing entry.
• metadata: Parsed metadata when available.
• hasBackup: Backup-presence flag.
• isCorrupt: Inspection-failure flag.

SaveSlotManager

import { SaveSlotManager } from "gamekit";
class SaveSlotManager<T>

Coordinates named, game-defined save documents over caller-provided byte storage. One manager owns its per-slot operation queues until shutdown; schemas and storage remain supplied by the game.

Members

storage: IByteStorage

Byte storage receiving primary, temporary, and backup blobs.

schema: SaveSchema<T>

Current codec and migration pipeline for slot payloads.

extension: string

Primary key suffix.

tempExtension: string

Sibling temporary-write suffix.

backupExtension: string

Previous-primary backup suffix.

maxAutosaves: int

Autosave ring cardinality.

autosavePrefix: string

Prefix for zero-based autosave names.

constructor( storage: IByteStorage, schema: SaveSchema<T>, options?: any )

Creates independent per-slot queues and an autosave cursor at index zero.

• storage: Backend used for every blob operation.
• schema: Current payload schema.
• options: Optional suffix, autosave size, and prefix overrides.

async shutdown(): Promise<void>

Rejects new saves/loads/inspections and waits for all already queued slot operations to settle.

async saveSlot( slotId: string, data: T, metadata?: any, cancelToken?: SlotCancellationToken ): Promise<SaveResult<SaveSlotMetadata>>

Serializes behind prior work for the same slot, then writes temp, validates, backs up, and atomically renames.

• slotId: Logical name used to derive storage keys.
• data: Runtime payload encoded by the schema codec.
• metadata: Metadata instance or partial metadata object; missing schema fields are filled.
• cancelToken: Optional token checked when queued work begins.
• Returns: Final metadata on success, otherwise a categorized storage or validation failure.

async loadSlot( slotId: string, cancelToken?: SlotCancellationToken ): Promise<SaveResult<T>>

Loads through the schema after earlier work for this slot, falling back to backup and restoring primary when recovery succeeds.

• slotId: Slot to load from primary or backup.
• cancelToken: Optional token checked before storage access.
• Returns: Decoded current-version payload or the primary failure when recovery fails.

async inspectSlot( slotId: string ): Promise<SaveResult<SaveSlotMetadata>>

Reads metadata without decoding game data, trying backup after any primary inspection failure.

• slotId: Logical slot name serialized behind work for the same slot.
• Returns: Parsed primary or backup metadata.

async listSlots(): Promise<SaveResult<SaveSlotInfo[]>>

Lists primary slot keys, inspects their metadata, and returns entries sorted by slot ID.

• Returns: Slot information including backup presence and corruption flags.

async deleteSlot(slotId: string): Promise<SaveResult<boolean>>

Serially requests removal of a slot's primary, temporary, and backup blobs.

• slotId: Slot whose three derived keys are removed.
• Returns: Success after all removal attempts; individual removal results are intentionally ignored.

async rotateAutosave(data: T, metadata?: any): Promise<SaveResult<SaveSlotMetadata>>

Advances the in-memory round-robin cursor and saves to <prefix><index>.

• data: Runtime payload for the chosen autosave slot.
• metadata: Optional display and timestamp metadata.
• Returns: The delegated slot-save result.

async latestAutosave(): Promise<SaveResult<SaveSlotMetadata>>

Inspects the configured autosave ring and selects the greatest metadata timestamp.

• Returns: Latest readable metadata, or UNAVAILABLE when none can be inspected.

SaveSlotManagerOptions

import { SaveSlotManagerOptions } from "gamekit";
class SaveSlotManagerOptions

Naming and rotation configuration for SaveSlotManager storage keys.

Members

extension: string = ".sav"

Primary slot suffix, default .sav.

tempExtension: string = ".tmp"

Sibling temporary-write suffix, default .tmp.

backupExtension: string = ".bak"

Previous-primary backup suffix, default .bak.

maxAutosaves: int = 3

Number of names in the round-robin autosave ring.

autosavePrefix: string = "autosave_"

Prefix placed before the zero-based autosave ring index.

constructor( extension: string = ".sav", tempExtension: string = ".tmp", backupExtension: string = ".bak", maxAutosaves: int = 3, autosavePrefix: string = "autosave_" )

Supplies storage naming defaults and autosave ring size.

• extension: Primary suffix.
• tempExtension: Temporary suffix.
• backupExtension: Backup suffix.
• maxAutosaves: Autosave ring cardinality.
• autosavePrefix: Autosave name prefix.

SaveSlotMetadata

import { SaveSlotMetadata } from "gamekit";
class SaveSlotMetadata

User-facing and schema metadata embedded beside a slot's encoded game data.

Members

slotId: string

Logical slot name without file suffixes.

schemaId: string

Schema identity recorded at save time.

version: int

Payload schema version recorded at save time.

timestamp: int

Game-supplied integer timestamp used to choose the latest autosave.

playTime: float

Game-supplied play duration, conventionally in seconds.

title: string

Display label for save-selection UI.

custom: any

Game-defined JSON-compatible metadata; null construction input becomes an empty object.

constructor( slotId: string = "", schemaId: string = "", version: int = 1, timestamp: int = 0, playTime: float = 0.0, title: string = "", custom: any = null )

Builds metadata without imposing clock or presentation conventions.

• slotId: Name embedded in the slot envelope.
• schemaId: Save schema identity.
• version: Payload version.
• timestamp: Comparable game-selected timestamp.
• playTime: Game-selected duration.
• title: Human-readable slot label.
• custom: Additional JSON-compatible fields.

serializeCanonical

import { serializeCanonical } from "gamekit";
function serializeCanonical(value: any, pretty: boolean = false): string

Serializes JSON-compatible data after recursively sorting object keys.

• value: Data to canonicalize and encode.
• pretty: Whether to indent with two spaces; compact output is the default.
• Returns: Deterministic JSON text for equivalent values.

SettingsStore

import { SettingsStore } from "gamekit";
class SettingsStore<T>

Atomic single-document settings storage, separate from named game-save slots. Writes use temp validation, backup, and rename; loads recover a valid backup and restore primary.

Members

storage: IByteStorage

Backend holding primary, temporary, and backup settings blobs.

filename: string

Primary settings storage key.

schema: SaveSchema<T>

Codec and migration pipeline for the settings payload.

tempFilename: string

Sibling temporary key derived as <filename>.tmp.

backupFilename: string

Previous-primary key derived as <filename>.bak.

constructor( storage: IByteStorage, filename: string = "settings.json", schema: SaveSchema<T> )

Derives sibling temp and backup names from the primary key.

• storage: Backend for all settings blobs.
• filename: Primary key, defaulting to settings.json.
• schema: Versioned settings schema.

async save(settings: T): Promise<SaveResult<boolean>>

Encodes settings, validates a sibling temporary blob, backs up an existing primary, then renames the temp.

• settings: Runtime settings value.
• Returns: Success at the schema's current version, or a categorized encode/storage/validation failure.

async load(): Promise<SaveResult<T>>

Loads and migrates primary settings, or recovers a valid backup and copies it back to primary.

• Returns: Decoded settings; if recovery fails, the original primary failure is retained.

async hasSettings(): Promise<boolean>

Returns true only when the primary key's existence check succeeds and reports presence.

async clear(): Promise<SaveResult<boolean>>

Requests removal of primary, temp, and backup settings blobs.

• Returns: Success after all attempts; individual removal failures are intentionally ignored.

SlotCancellationToken

import { SlotCancellationToken } from "gamekit";
class SlotCancellationToken

Cooperative preflight cancellation flag for queued slot saves and loads. Cancellation is checked when an operation reaches the front of its per-slot queue, not during storage I/O already underway.

Members

cancel(): void

Permanently marks the token cancelled; repeated calls are inert.

get isCancelled(): boolean

Is true after cancellation has been requested.

UnknownFieldPolicy

import { UnknownFieldPolicy } from "gamekit";
enum UnknownFieldPolicy

Chooses whether record decoding rejects undeclared fields or preserves them in CodecContext for round trips.

Member	Meaning
REJECT = 0	Fail decoding when an undeclared field is present.
PRESERVE = 1	Retain undeclared fields for a later round trip.