Browser persistence and file API

Store objects in IndexedDB and retain file stages for undo/redo and explicit sync. Import from @chester-hill-solutions/stow-s3/browser.

Defaults and limits

Behavior

• openBrowserEmbeddedStow needs an EmbeddedHost and persistence adapter.
• read fetches remotely only on a local miss.
• save and saveReceipt never upload; saveReceipt omits returned file bytes.
• sync uploads the selected stage.
• undo/redo persist the cursor.
• A save after undo removes the redo branch.
• adoptRemote requires any uncertain attempt to be resolved first.
• File-history instances do not close their underlying store or host.

Errors

• BrowserPersistenceError exposes the BrowserPersistenceErrorCode union.
• FileHistoryError exposes FileHistoryErrorCode, including conflict, history_boundary, history_corrupt and uncertain_write.
• Quota or persistence failures restore the previous committed state.
• Without Web Locks, the original adapter checks ownership only within one JavaScript realm.

Example

import { BrowserFileHistory } from "@chester-hill-solutions/stow-s3/browser";

const files = await BrowserFileHistory.open(store, { remoteBucket: "files", remote });
await files.save("note.txt", new TextEncoder().encode("offline edit"));
await files.undo("note.txt");
await files.redo("note.txt");
const status = await files.sync("note.txt");
// store and remote are supplied by your application.

Symbols

BROWSER_PERSISTENCE_FORMAT_VERSION · BrowserEmbeddedStow · BrowserFileHistory · BrowserFileHistoryOptions · BrowserObjectMutation · BrowserPersistenceError · BrowserPersistenceErrorCode · DeleteBucketChange · DeleteObjectChange · FileHistoryError · FileHistoryErrorCode · FileHistoryExport · FileHistoryStatus · FileReadResult · FileSaveOptions · FileSaveReceipt · FileVersion · IndexedDbPersistenceAdapter · IndexedDbPersistenceAdapterOptions · LockManagerLike · ObjectSyncRemote · openBrowserEmbeddedStow · PersistenceAdapter · PersistenceChange · PersistenceSnapshot · PersistentEmbeddedStowOptions · PutBucketChange · PutObjectChange · RemoteObjectBasis · SyncRemoteObject · SyncRemoteWrite

BROWSER_PERSISTENCE_FORMAT_VERSION

Supported IndexedDB object format version: 1.

const BROWSER_PERSISTENCE_FORMAT_VERSION: 1;

BrowserEmbeddedStow

class BrowserEmbeddedStow {
  static open(host: EmbeddedHost, options: PersistentEmbeddedStowOptions): Promise<BrowserEmbeddedStow>;
  static create(host: EmbeddedHost, adapter: PersistenceAdapter, namespace: string, options?: EmbeddedStowOptions): Promise<BrowserEmbeddedStow>;
  readonly handle: number;
  capabilities(): Promise<EmbeddedCapabilities>;
  usage(): Promise<EmbeddedUsage>;
  createBucket(bucket: string): Promise<void>;
  deleteBucket(bucket: string): Promise<void>;
  listBuckets(): Promise<EmbeddedBucket[]>;
  putObject(bucket: string, key: string, data: Uint8Array<ArrayBufferLike>, options?: EmbeddedPutOptions): Promise<EmbeddedObject>;
  getObject(bucket: string, key: string): Promise<EmbeddedObject>;
  headObject(bucket: string, key: string): Promise<EmbeddedObject>;
  listObjects(bucket: string, options?: EmbeddedListOptions): Promise<EmbeddedObjectPage>;
  deleteObject(bucket: string, key: string): Promise<void>;
  writeBatch(mutations: BrowserObjectMutation[]): Promise<void>;
  copyObject(sourceBucket: string, sourceKey: string, destinationBucket: string, destinationKey: string): Promise<EmbeddedObject>;
  reset(): Promise<void>;
  close(): Promise<void>;
}

BrowserEmbeddedStow.open

Open a handle. Retain it until operations finish, then close it.

open(host: EmbeddedHost, options: PersistentEmbeddedStowOptions): Promise<BrowserEmbeddedStow>

Returns: Promise<BrowserEmbeddedStow>.

BrowserEmbeddedStow.create

create(host: EmbeddedHost, adapter: PersistenceAdapter, namespace: string, options?: EmbeddedStowOptions): Promise<BrowserEmbeddedStow>

Returns: Promise<BrowserEmbeddedStow>.

BrowserEmbeddedStow.capabilities

Return the operations and limits supported by this handle.

capabilities(): Promise<EmbeddedCapabilities>

Returns: Promise<EmbeddedCapabilities>.

BrowserEmbeddedStow.usage

Return current storage accounting.

usage(): Promise<EmbeddedUsage>

Returns: Promise<EmbeddedUsage>.

BrowserEmbeddedStow.createBucket

Create the named bucket before storing objects.

createBucket(bucket: string): Promise<void>

Returns: Promise<void>.

BrowserEmbeddedStow.deleteBucket

Remove an empty bucket; a nonempty bucket is refused.

deleteBucket(bucket: string): Promise<void>

Returns: Promise<void>.

BrowserEmbeddedStow.listBuckets

Return the buckets visible to the handle.

listBuckets(): Promise<EmbeddedBucket[]>

Returns: Promise<EmbeddedBucket[]>.

BrowserEmbeddedStow.putObject

Store complete bytes and metadata, subject to write conditions and quotas.

putObject(bucket: string, key: string, data: Uint8Array<ArrayBufferLike>, options?: EmbeddedPutOptions): Promise<EmbeddedObject>

Returns: Promise<EmbeddedObject>.

BrowserEmbeddedStow.getObject

Return complete object bytes and metadata.

getObject(bucket: string, key: string): Promise<EmbeddedObject>

Returns: Promise<EmbeddedObject>.

BrowserEmbeddedStow.headObject

Return object metadata without reading the body into the result.

headObject(bucket: string, key: string): Promise<EmbeddedObject>

Returns: Promise<EmbeddedObject>.

BrowserEmbeddedStow.listObjects

Return one page. Pass nextCursor to continue when truncated is true.

listObjects(bucket: string, options?: EmbeddedListOptions): Promise<EmbeddedObjectPage>

Returns: Promise<EmbeddedObjectPage>.

BrowserEmbeddedStow.deleteObject

Delete the selected object; deleting a missing object is idempotent.

deleteObject(bucket: string, key: string): Promise<void>

Returns: Promise<void>.

BrowserEmbeddedStow.writeBatch

Commit all related object mutations in one durable transaction or restore the previous state.

writeBatch(mutations: BrowserObjectMutation[]): Promise<void>

Returns: Promise<void>.

BrowserEmbeddedStow.copyObject

Copy source bytes and metadata to the destination object.

copyObject(sourceBucket: string, sourceKey: string, destinationBucket: string, destinationKey: string): Promise<EmbeddedObject>

Returns: Promise<EmbeddedObject>.

BrowserEmbeddedStow.reset

Clear storage state where the backend supports reset.

reset(): Promise<void>

Returns: Promise<void>.

BrowserEmbeddedStow.close

Release this handle. Do not submit new operations after closing it.

close(): Promise<void>

Returns: Promise<void>.

BrowserFileHistory

Durable file stages over the browser store.

class BrowserFileHistory {
  static open(store: BrowserEmbeddedStow, options: BrowserFileHistoryOptions): Promise<BrowserFileHistory>;
  read(key: string): Promise<FileReadResult>;
  save(key: string, data: Uint8Array<ArrayBufferLike>, options?: FileSaveOptions): Promise<FileReadResult>;
  saveReceipt(key: string, data: Uint8Array<ArrayBufferLike>, options?: FileSaveOptions): Promise<FileSaveReceipt>;
  status(key: string): Promise<FileHistoryStatus>;
  exportRetained(key: string, visit: (version: FileVersion, bytes: Uint8Array<ArrayBufferLike>, history: FileHistoryExport) => Promise<void>): Promise<FileHistoryExport>;
  undo(key: string): Promise<FileReadResult>;
  redo(key: string): Promise<FileReadResult>;
  sync(key: string): Promise<FileHistoryStatus>;
  adoptRemote(key: string): Promise<FileReadResult>;
}

BrowserFileHistory.open

Open a handle. Retain it until operations finish, then close it.

open(store: BrowserEmbeddedStow, options: BrowserFileHistoryOptions): Promise<BrowserFileHistory>

Returns: Promise<BrowserFileHistory>.

BrowserFileHistory.read

Read the selected file's bytes.

read(key: string): Promise<FileReadResult>

Returns: Promise<FileReadResult>.

BrowserFileHistory.save

Commit a complete local file stage before resolving.

save(key: string, data: Uint8Array<ArrayBufferLike>, options?: FileSaveOptions): Promise<FileReadResult>

Returns: Promise<FileReadResult>.

BrowserFileHistory.saveReceipt

Commit a local stage and return its receipt without copying file bytes back.

saveReceipt(key: string, data: Uint8Array<ArrayBufferLike>, options?: FileSaveOptions): Promise<FileSaveReceipt>

Returns: Promise<FileSaveReceipt>.

BrowserFileHistory.status

Return the selected revision, retained history and pending sync state.

status(key: string): Promise<FileHistoryStatus>

Returns: Promise<FileHistoryStatus>.

BrowserFileHistory.exportRetained

Call visit for each retained stage while holding source history stable.

exportRetained(key: string, visit: (version: FileVersion, bytes: Uint8Array<ArrayBufferLike>, history: FileHistoryExport) => Promise<void>): Promise<FileHistoryExport>

Returns: Promise<FileHistoryExport>.

BrowserFileHistory.undo

Select the preceding retained revision; fail at the history boundary.

undo(key: string): Promise<FileReadResult>

Returns: Promise<FileReadResult>.

BrowserFileHistory.redo

Select the next retained revision; fail at the history boundary.

redo(key: string): Promise<FileReadResult>

Returns: Promise<FileReadResult>.

BrowserFileHistory.sync

Publish the selected revision with the saved remote condition; preserve local work on conflict.

sync(key: string): Promise<FileHistoryStatus>

Returns: Promise<FileHistoryStatus>.

BrowserFileHistory.adoptRemote

Record the current remote bytes as a confirmed stage after reconciliation.

adoptRemote(key: string): Promise<FileReadResult>

Returns: Promise<FileReadResult>.

BrowserFileHistoryOptions

interface BrowserFileHistoryOptions {
  remoteBucket: string;
  remote?: ObjectSyncRemote | undefined;
  historyBucket?: string | undefined;
  maxVersions?: number | undefined;
}

BrowserObjectMutation

All changes in a batch commit together, including failures in the WASM runtime.

type BrowserObjectMutation = {
    type: "put";
    bucket: string;
    key: string;
    data: Uint8Array;
    options?: EmbeddedPutOptions;
} | {
    type: "delete";
    bucket: string;
    key: string;
};

BrowserPersistenceError

class BrowserPersistenceError  extends Error {
  readonly code: BrowserPersistenceErrorCode;
  constructor(code: BrowserPersistenceErrorCode, message: string);
}

BrowserPersistenceError.constructor

function Object() { [native code] }

constructor(code: BrowserPersistenceErrorCode, message: string)

Returns: BrowserPersistenceError.

BrowserPersistenceErrorCode

type BrowserPersistenceErrorCode = "persistence_unsupported" | "persistence_denied" | "already_open" | "persistence_error" | "persistence_corrupt" | "quota_exceeded" | "closed";

DeleteBucketChange

type DeleteBucketChange = {
    type: "deleteBucket";
    bucket: string;
};

DeleteObjectChange

type DeleteObjectChange = {
    type: "deleteObject";
    bucket: string;
    key: string;
};

FileHistoryError

class FileHistoryError  extends Error {
  constructor(code: FileHistoryErrorCode, message: string);
}

FileHistoryError.constructor

function Object() { [native code] }

constructor(code: FileHistoryErrorCode, message: string)

Returns: FileHistoryError.

FileHistoryErrorCode

type FileHistoryErrorCode = "not_found" | "conflict" | "history_boundary" | "remote_unavailable" | "history_corrupt" | "invalid_options" | "uncertain_write";

FileHistoryExport

interface FileHistoryExport {
  key: string;
  remoteBucket: string;
  versions: FileVersion[];
  currentVersionId: string;
}

FileHistoryStatus

interface FileHistoryStatus {
  key: string;
  versions: FileVersion[];
  currentVersionId: string;
  pending: boolean;
  canUndo: boolean;
  canRedo: boolean;
  remoteETag?: string | undefined;
  hasUncertainWrite: boolean;
}

FileReadResult

interface FileReadResult {
  data: Uint8Array<ArrayBufferLike>;
  version: FileVersion;
  status: FileHistoryStatus;
}

FileSaveOptions

interface FileSaveOptions  extends Pick<EmbeddedPutOptions, "contentType" | "metadata"> {
  label?: string | undefined;
}

FileSaveReceipt

A committed save without materializing the saved file again.

type FileSaveReceipt = Omit<FileReadResult, "data">;

FileVersion

interface FileVersion {
  id: string;
  createdAt: string;
  label?: string | undefined;
  contentType?: string | undefined;
  metadata?: Record<string, string> | undefined;
}

IndexedDbPersistenceAdapter

class IndexedDbPersistenceAdapter  implements PersistenceAdapter {
  constructor(options?: IndexedDbPersistenceAdapterOptions);
  open(namespace: string): Promise<void>;
  load(namespace: string): Promise<PersistenceSnapshot | null>;
  commit(namespace: string, expectedGeneration: number, changes: PersistenceChange[]): Promise<number>;
  clear(namespace: string, expectedGeneration: number): Promise<number>;
  close(): Promise<void>;
}

IndexedDbPersistenceAdapter.constructor

function Object() { [native code] }

constructor(options?: IndexedDbPersistenceAdapterOptions)

Returns: IndexedDbPersistenceAdapter.

IndexedDbPersistenceAdapter.open

Open a handle. Retain it until operations finish, then close it.

open(namespace: string): Promise<void>

Returns: Promise<void>.

IndexedDbPersistenceAdapter.load

load(namespace: string): Promise<PersistenceSnapshot | null>

Returns: Promise<PersistenceSnapshot | null>.

IndexedDbPersistenceAdapter.commit

Publish all requested file changes as one project revision.

commit(namespace: string, expectedGeneration: number, changes: PersistenceChange[]): Promise<number>

Returns: Promise<number>.

IndexedDbPersistenceAdapter.clear

clear(namespace: string, expectedGeneration: number): Promise<number>

Returns: Promise<number>.

IndexedDbPersistenceAdapter.close

Release this handle. Do not submit new operations after closing it.

close(): Promise<void>

Returns: Promise<void>.

IndexedDbPersistenceAdapterOptions

interface IndexedDbPersistenceAdapterOptions {
  indexedDB?: IDBFactory | undefined;
  databaseName?: string | undefined;
  manifestStoreName?: string | undefined;
  bucketStoreName?: string | undefined;
  objectStoreName?: string | undefined;
  lockManager?: LockManagerLike | undefined;
  lockName?: ((namespace: string) => string) | undefined;
}

LockManagerLike

interface LockManagerLike {
  request(name: string, options: { mode: "exclusive"; ifAvailable?: boolean | undefined; }, callback: (lock: unknown) => Promise<void>): Promise<void>;
}

LockManagerLike.request

request(name: string, options: { mode: "exclusive"; ifAvailable?: boolean | undefined; }, callback: (lock: unknown) => Promise<void>): Promise<void>

Returns: Promise<void>.

ObjectSyncRemote

Host-owned credentials, networking and conditional object writes.

interface ObjectSyncRemote {
  headObject(bucket: string, key: string): Promise<{ etag: string; size: number; metadata?: Record<string, string> | undefined; sha256?: string | undefined; } | null>;
  getObject(bucket: string, key: string): Promise<SyncRemoteObject | null>;
  putObject(bucket: string, key: string, data: Uint8Array<ArrayBufferLike>, options: SyncRemoteWrite): Promise<{ etag: string; }>;
}

ObjectSyncRemote.headObject

Return object metadata without reading the body into the result.

headObject(bucket: string, key: string): Promise<{ etag: string; size: number; metadata?: Record<string, string> | undefined; sha256?: string | undefined; } | null>

Returns: Promise<{ etag: string; size: number; metadata?: Record<string, string> | undefined; sha256?: string | undefined; } | null>.

ObjectSyncRemote.getObject

Return complete object bytes and metadata.

getObject(bucket: string, key: string): Promise<SyncRemoteObject | null>

Returns: Promise<SyncRemoteObject | null>.

ObjectSyncRemote.putObject

Store complete bytes and metadata, subject to write conditions and quotas.

putObject(bucket: string, key: string, data: Uint8Array<ArrayBufferLike>, options: SyncRemoteWrite): Promise<{ etag: string; }>

Returns: Promise<{ etag: string; }>.

openBrowserEmbeddedStow

openBrowserEmbeddedStow(host: EmbeddedHost, options: PersistentEmbeddedStowOptions): Promise<BrowserEmbeddedStow>

Returns: Promise<BrowserEmbeddedStow>.

PersistenceAdapter

interface PersistenceAdapter {
  open(namespace: string): Promise<void>;
  load(namespace: string): Promise<PersistenceSnapshot | null | undefined>;
  commit(namespace: string, expectedGeneration: number, changes: PersistenceChange[]): Promise<number>;
  clear(namespace: string, expectedGeneration: number): Promise<number>;
  close(): Promise<void>;
}

PersistenceAdapter.open

Open a handle. Retain it until operations finish, then close it.

open(namespace: string): Promise<void>

Returns: Promise<void>.

PersistenceAdapter.load

load(namespace: string): Promise<PersistenceSnapshot | null | undefined>

Returns: Promise<PersistenceSnapshot | null | undefined>.

PersistenceAdapter.commit

Publish all requested file changes as one project revision.

commit(namespace: string, expectedGeneration: number, changes: PersistenceChange[]): Promise<number>

Returns: Promise<number>.

PersistenceAdapter.clear

clear(namespace: string, expectedGeneration: number): Promise<number>

Returns: Promise<number>.

PersistenceAdapter.close

Release this handle. Do not submit new operations after closing it.

close(): Promise<void>

Returns: Promise<void>.

PersistenceChange

type PersistenceChange = PutBucketChange | DeleteBucketChange | PutObjectChange | DeleteObjectChange;

PersistenceSnapshot

interface PersistenceSnapshot {
  formatVersion: 1;
  generation: number;
  buckets: EmbeddedBucket[];
  objects: EmbeddedObject[];
}

PersistentEmbeddedStowOptions

interface PersistentEmbeddedStowOptions  extends EmbeddedStowOptions {
  namespace: string;
  persistence: PersistenceAdapter;
}

PutBucketChange

type PutBucketChange = {
    type: "putBucket";
    bucket: EmbeddedBucket;
};

PutObjectChange

type PutObjectChange = {
    type: "putObject";
    object: EmbeddedObject;
};

RemoteObjectBasis

The remote must enforce this condition atomically with its write.

type RemoteObjectBasis = {
    etag: string;
} | {
    absent: true;
};

SyncRemoteObject

interface SyncRemoteObject {
  data: Uint8Array<ArrayBufferLike>;
  etag: string;
  contentType?: string | undefined;
  metadata?: Record<string, string> | undefined;
  saveId?: string | undefined;
}

SyncRemoteWrite

interface SyncRemoteWrite {
  basis: RemoteObjectBasis;
  saveId: string;
  contentType?: string | undefined;
  metadata?: Record<string, string> | undefined;
  sha256?: string | undefined;
}