Browser project and content API

Retain atomic multi-file revisions with shared immutable chunks. Import from @chester-hill-solutions/stow-s3/project.

Defaults and limits

Behavior

• Open the adapter's namespace before using ContentStore.
• BrowserProject.commit applies all changes as one revision; put, delete and fixed-length replaceRange are supported.
• read returns full bytes; readRange returns a bounded allocation; stream pins the selected revision.
• checkout selects a retained revision.
• sync uploads chunks before a conditional manifest write.
• Closing a project does not close its content store or adapter.
• Release abandoned stages explicitly before collection.
• migrateFileHistory preserves the source and requires unresolved sync attempts to be reconciled first.

Errors

• ProjectError exposes its code, including not_found, conflict, corrupt, invalid_options, history_boundary, read_too_large, remote_unavailable, uncertain_write and closed.
• Content adapters can raise BrowserPersistenceError or RangeError.
• This IndexedDB profile requires Web Locks.
• Unknown formats, invalid ranges and quota overflow fail without partial publication.

Example

import { BrowserProject, ContentStore, IndexedDbContentAdapter } from "@chester-hill-solutions/stow-s3/project";

const adapter = new IndexedDbContentAdapter();
await adapter.open("my-app");
const content = new ContentStore(adapter);
const project = await BrowserProject.open(content, { projectId: "notes" });
await project.commit([{ type: "put", key: "note.txt", data: new TextEncoder().encode("hello") }]);
const bytes = await project.readRange("note.txt", 0, 5);
await project.close();
await adapter.close();

Symbols

BrowserProject · BrowserProjectOptions · ContentAdapter · ContentChunk · ContentHead · ContentObjectHost · ContentPage · ContentProtection · ContentPublication · ContentRecord · ContentReference · ContentStageOptions · ContentStore · ContentStoreOptions · ContentUsage · IndexedDbContentAdapter · IndexedDbContentOptions · migrateFileHistory · ProjectChange · ProjectCommitOptions · ProjectError · ProjectFile · ProjectInput · ProjectRevision · ProjectStatus · StagedContent

BrowserProject

Durable project revisions over lazy immutable content.

class BrowserProject {
  readonly retentionLimit: number;
  static open(store: ContentStore, options: BrowserProjectOptions): Promise<BrowserProject>;
  status(): Promise<ProjectStatus>;
  listFiles(): Promise<ProjectFile[]>;
  commit(changes: ProjectChange[], options?: ProjectCommitOptions): Promise<ProjectStatus>;
  read(key: string): Promise<Uint8Array<ArrayBufferLike>>;
  readRange(key: string, start: number, end: number): Promise<Uint8Array<ArrayBufferLike>>;
  stream(key: string, options?: { signal?: AbortSignal | undefined; }): AsyncIterable<Uint8Array<ArrayBufferLike>>;
  undo(): Promise<ProjectStatus>;
  redo(): Promise<ProjectStatus>;
  checkout(revisionId: string): Promise<ProjectStatus>;
  migrationProgress(token: string): Promise<string | undefined>;
  sync(): Promise<ProjectStatus>;
  close(): Promise<void>;
}

BrowserProject.open

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

open(store: ContentStore, options: BrowserProjectOptions): Promise<BrowserProject>

Returns: Promise<BrowserProject>.

BrowserProject.status

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

status(): Promise<ProjectStatus>

Returns: Promise<ProjectStatus>.

BrowserProject.listFiles

Return the selected project's file manifest without reading payloads.

listFiles(): Promise<ProjectFile[]>

Returns: Promise<ProjectFile[]>.

BrowserProject.commit

Publish all requested file changes as one project revision.

commit(changes: ProjectChange[], options?: ProjectCommitOptions): Promise<ProjectStatus>

Returns: Promise<ProjectStatus>.

BrowserProject.read

Read the selected file's bytes.

read(key: string): Promise<Uint8Array<ArrayBufferLike>>

Returns: Promise<Uint8Array<ArrayBufferLike>>.

BrowserProject.readRange

Read byte offsets from start inclusive to end exclusive.

readRange(key: string, start: number, end: number): Promise<Uint8Array<ArrayBufferLike>>

Returns: Promise<Uint8Array<ArrayBufferLike>>.

BrowserProject.stream

Yield bounded content chunks; finish or close the reader to release protection.

stream(key: string, options?: { signal?: AbortSignal | undefined; }): AsyncIterable<Uint8Array<ArrayBufferLike>>

Returns: AsyncIterable<Uint8Array<ArrayBufferLike>>.

BrowserProject.undo

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

undo(): Promise<ProjectStatus>

Returns: Promise<ProjectStatus>.

BrowserProject.redo

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

redo(): Promise<ProjectStatus>

Returns: Promise<ProjectStatus>.

BrowserProject.checkout

Select the retained revision identified by revisionId.

checkout(revisionId: string): Promise<ProjectStatus>

Returns: Promise<ProjectStatus>.

BrowserProject.migrationProgress

Return the retained destination revision ID for a migration token, if present.

migrationProgress(token: string): Promise<string | undefined>

Returns: Promise<string | undefined>.

BrowserProject.sync

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

sync(): Promise<ProjectStatus>

Returns: Promise<ProjectStatus>.

BrowserProject.close

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

close(): Promise<void>

Returns: Promise<void>.

BrowserProjectOptions

interface BrowserProjectOptions {
  projectId: string;
  maxVersions?: number | undefined;
  maxReadBytes?: number | undefined;
  maxManifestBytes?: number | undefined;
  remote?: ObjectSyncRemote | undefined;
  remoteBucket?: string | undefined;
}

ContentAdapter

interface ContentAdapter {
  open(namespace: string): Promise<void>;
  getHead(name: string): Promise<ContentHead>;
  getRecord(id: string): Promise<ContentRecord | null>;
  listRecords(options?: { after?: string | undefined; limit?: number | undefined; } | undefined): Promise<ContentPage>;
  getChunk(hash: string): Promise<Uint8Array<ArrayBufferLike> | null>;
  stageChunk(stageId: string, hash: string, data: Uint8Array<ArrayBufferLike>): Promise<void>;
  releaseStage(stageId: string): Promise<void>;
  listStages(): Promise<string[]>;
  publish(publication: ContentPublication): Promise<ContentHead>;
  protect(name: string, recordIds: string[], options?: { lifetime?: "handle" | "durable" | undefined; } | undefined): Promise<void>;
  listProtections(): Promise<ContentProtection[]>;
  collect(options?: { retainRecordIds?: string[] | undefined; } | undefined): Promise<ContentUsage>;
  usage(): Promise<ContentUsage>;
  close(): Promise<void>;
}

ContentAdapter.open

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

open(namespace: string): Promise<void>

Returns: Promise<void>.

ContentAdapter.getHead

getHead(name: string): Promise<ContentHead>

Returns: Promise<ContentHead>.

ContentAdapter.getRecord

getRecord(id: string): Promise<ContentRecord | null>

Returns: Promise<ContentRecord | null>.

ContentAdapter.listRecords

listRecords(options?: { after?: string | undefined; limit?: number | undefined; } | undefined): Promise<ContentPage>

Returns: Promise<ContentPage>.

ContentAdapter.getChunk

getChunk(hash: string): Promise<Uint8Array<ArrayBufferLike> | null>

Returns: Promise<Uint8Array<ArrayBufferLike> | null>.

ContentAdapter.stageChunk

stageChunk(stageId: string, hash: string, data: Uint8Array<ArrayBufferLike>): Promise<void>

Returns: Promise<void>.

ContentAdapter.releaseStage

releaseStage(stageId: string): Promise<void>

Returns: Promise<void>.

ContentAdapter.listStages

listStages(): Promise<string[]>

Returns: Promise<string[]>.

ContentAdapter.publish

publish(publication: ContentPublication): Promise<ContentHead>

Returns: Promise<ContentHead>.

ContentAdapter.protect

protect(name: string, recordIds: string[], options?: { lifetime?: "handle" | "durable" | undefined; } | undefined): Promise<void>

Returns: Promise<void>.

ContentAdapter.listProtections

listProtections(): Promise<ContentProtection[]>

Returns: Promise<ContentProtection[]>.

ContentAdapter.collect

collect(options?: { retainRecordIds?: string[] | undefined; } | undefined): Promise<ContentUsage>

Returns: Promise<ContentUsage>.

ContentAdapter.usage

Return current storage accounting.

usage(): Promise<ContentUsage>

Returns: Promise<ContentUsage>.

ContentAdapter.close

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

close(): Promise<void>

Returns: Promise<void>.

ContentChunk

interface ContentChunk {
  hash: string;
  size: number;
}

ContentHead

interface ContentHead {
  name: string;
  generation: number;
  recordId: string | null;
}

ContentObjectHost

Host persistence beneath the shared Go object runtime; bytes are never replayed at open.

class ContentObjectHost  implements HostObjectStoreBridge {
  checkConditions?: ((metadata: string) => string) | undefined;
  constructor(store: ContentStore, options?: { name?: string | undefined; maxStreams?: number | undefined; });
  hasActiveStage(stageId: string): boolean;
  call(metadata: string, data: Uint8Array<ArrayBufferLike>): Promise<EmbeddedBinaryResponse>;
}

ContentObjectHost.constructor

function Object() { [native code] }

constructor(store: ContentStore, options?: { name?: string | undefined; maxStreams?: number | undefined; })

Returns: ContentObjectHost.

ContentObjectHost.hasActiveStage

hasActiveStage(stageId: string): boolean

Returns: boolean.

ContentObjectHost.call

call(metadata: string, data: Uint8Array<ArrayBufferLike>): Promise<EmbeddedBinaryResponse>

Returns: Promise<EmbeddedBinaryResponse>.

ContentPage

interface ContentPage {
  records: ContentRecord[];
  next?: string | undefined;
}

ContentProtection

interface ContentProtection {
  name: string;
  recordIds: string[];
  lifetime: "handle" | "durable";
}

ContentPublication

interface ContentPublication {
  head: string;
  expectedGeneration: number;
  record: ContentRecord;
  additionalRecords?: ContentRecord[] | undefined;
  stageId: string;
}

ContentRecord

interface ContentRecord {
  id: string;
  metadata: Uint8Array<ArrayBufferLike>;
  contents: ContentReference[];
  references: string[];
}

ContentReference

interface ContentReference {
  size: number;
  chunks: ContentChunk[];
}

ContentStageOptions

interface ContentStageOptions {
  stageId?: string | undefined;
  signal?: AbortSignal | undefined;
}

ContentStore

class ContentStore {
  constructor(adapter: ContentAdapter, options?: ContentStoreOptions);
  stage(input: Uint8Array<ArrayBufferLike> | AsyncIterable<Uint8Array<ArrayBufferLike>>, options?: ContentStageOptions): Promise<StagedContent>;
  stream(content: ContentReference, options?: { start?: number | undefined; end?: number | undefined; signal?: AbortSignal | undefined; }): AsyncIterable<Uint8Array<ArrayBufferLike>>;
  readRange(content: ContentReference, start?: number, end?: number): Promise<Uint8Array<ArrayBufferLike>>;
  usage(): Promise<ContentUsage>;
  clearCache(): void;
}

ContentStore.constructor

function Object() { [native code] }

constructor(adapter: ContentAdapter, options?: ContentStoreOptions)

Returns: ContentStore.

ContentStore.stage

Write immutable chunks without publishing a head; retain the stage ID for publication or cleanup.

stage(input: Uint8Array<ArrayBufferLike> | AsyncIterable<Uint8Array<ArrayBufferLike>>, options?: ContentStageOptions): Promise<StagedContent>

Returns: Promise<StagedContent>.

ContentStore.stream

Yield bounded content chunks; finish or close the reader to release protection.

stream(content: ContentReference, options?: { start?: number | undefined; end?: number | undefined; signal?: AbortSignal | undefined; }): AsyncIterable<Uint8Array<ArrayBufferLike>>

Returns: AsyncIterable<Uint8Array<ArrayBufferLike>>.

ContentStore.readRange

Read byte offsets from start inclusive to end exclusive.

readRange(content: ContentReference, start?: number, end?: number): Promise<Uint8Array<ArrayBufferLike>>

Returns: Promise<Uint8Array<ArrayBufferLike>>.

ContentStore.usage

Return current storage accounting.

usage(): Promise<ContentUsage>

Returns: Promise<ContentUsage>.

ContentStore.clearCache

Release cached payload bytes without changing durable storage.

clearCache(): void

Returns: void.

ContentStoreOptions

interface ContentStoreOptions {
  chunkBytes?: number | undefined;
  cacheBytes?: number | undefined;
}

ContentUsage

interface ContentUsage {
  physicalBytes: number;
  chunks: number;
  records: number;
  bookkeepingBytes?: number | undefined;
  cacheBytes?: number | undefined;
}

IndexedDbContentAdapter

class IndexedDbContentAdapter  implements ContentAdapter {
  constructor(options?: IndexedDbContentOptions);
  open(namespace: string): Promise<void>;
  getHead(name: string): Promise<ContentHead>;
  getRecord(id: string): Promise<ContentRecord | null>;
  listRecords(options?: { after?: string | undefined; limit?: number | undefined; }): Promise<ContentPage>;
  getChunk(hash: string): Promise<Uint8Array<ArrayBufferLike> | null>;
  stageChunk(stageId: string, hash: string, bytes: Uint8Array<ArrayBufferLike>): Promise<void>;
  listStages(): Promise<string[]>;
  releaseStage(stageId: string): Promise<void>;
  publish(publication: ContentPublication): Promise<ContentHead>;
  listProtections(): Promise<ContentProtection[]>;
  protect(name: string, recordIds: string[], options?: { lifetime?: "handle" | "durable" | undefined; }): Promise<void>;
  collect(options?: { retainRecordIds?: string[] | undefined; }): Promise<ContentUsage>;
  usage(): Promise<ContentUsage>;
  close(): Promise<void>;
}

IndexedDbContentAdapter.constructor

function Object() { [native code] }

constructor(options?: IndexedDbContentOptions)

Returns: IndexedDbContentAdapter.

IndexedDbContentAdapter.open

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

open(namespace: string): Promise<void>

Returns: Promise<void>.

IndexedDbContentAdapter.getHead

getHead(name: string): Promise<ContentHead>

Returns: Promise<ContentHead>.

IndexedDbContentAdapter.getRecord

getRecord(id: string): Promise<ContentRecord | null>

Returns: Promise<ContentRecord | null>.

IndexedDbContentAdapter.listRecords

listRecords(options?: { after?: string | undefined; limit?: number | undefined; }): Promise<ContentPage>

Returns: Promise<ContentPage>.

IndexedDbContentAdapter.getChunk

getChunk(hash: string): Promise<Uint8Array<ArrayBufferLike> | null>

Returns: Promise<Uint8Array<ArrayBufferLike> | null>.

IndexedDbContentAdapter.stageChunk

stageChunk(stageId: string, hash: string, bytes: Uint8Array<ArrayBufferLike>): Promise<void>

Returns: Promise<void>.

IndexedDbContentAdapter.listStages

listStages(): Promise<string[]>

Returns: Promise<string[]>.

IndexedDbContentAdapter.releaseStage

releaseStage(stageId: string): Promise<void>

Returns: Promise<void>.

IndexedDbContentAdapter.publish

publish(publication: ContentPublication): Promise<ContentHead>

Returns: Promise<ContentHead>.

IndexedDbContentAdapter.listProtections

listProtections(): Promise<ContentProtection[]>

Returns: Promise<ContentProtection[]>.

IndexedDbContentAdapter.protect

protect(name: string, recordIds: string[], options?: { lifetime?: "handle" | "durable" | undefined; }): Promise<void>

Returns: Promise<void>.

IndexedDbContentAdapter.collect

collect(options?: { retainRecordIds?: string[] | undefined; }): Promise<ContentUsage>

Returns: Promise<ContentUsage>.

IndexedDbContentAdapter.usage

Return current storage accounting.

usage(): Promise<ContentUsage>

Returns: Promise<ContentUsage>.

IndexedDbContentAdapter.close

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

close(): Promise<void>

Returns: Promise<void>.

IndexedDbContentOptions

interface IndexedDbContentOptions {
  indexedDB?: IDBFactory | undefined;
  databaseName?: string | undefined;
  lockManager?: LockManagerLike | undefined;
  quotaBytes?: number | undefined;
}

migrateFileHistory

Copy retained legacy stages into a dedicated project without changing the source or discarding uncertain sync attempts.

migrateFileHistory(source: Pick<BrowserFileHistory, "exportRetained">, key: string, target: BrowserProject): Promise<ProjectStatus>

Returns: Promise<ProjectStatus>.

ProjectChange

type ProjectChange = {
    type: "put";
    key: string;
    data: ProjectInput;
    contentType?: string;
    metadata?: Record<string, string>;
} | {
    type: "delete";
    key: string;
} | {
    type: "replaceRange";
    key: string;
    offset: number;
    data: Uint8Array;
};

ProjectCommitOptions

interface ProjectCommitOptions {
  label?: string | undefined;
  signal?: AbortSignal | undefined;
  migrationToken?: string | undefined;
}

ProjectError

class ProjectError  extends Error {
  constructor(code: ProjectErrorCode, message: string);
}

ProjectError.constructor

function Object() { [native code] }

constructor(code: ProjectErrorCode, message: string)

Returns: ProjectError.

ProjectFile

interface ProjectFile {
  key: string;
  content: ContentReference;
  contentType?: string | undefined;
  metadata?: Record<string, string> | undefined;
}

ProjectInput

type ProjectInput = Uint8Array | AsyncIterable<Uint8Array>;

ProjectRevision

interface ProjectRevision {
  id: string;
  createdAt: string;
  label?: string | undefined;
}

ProjectStatus

interface ProjectStatus {
  projectId: string;
  generation: number;
  versions: ProjectRevision[];
  currentVersionId: string | null;
  pending: boolean;
  canUndo: boolean;
  canRedo: boolean;
  hasUncertainWrite: boolean;
}

StagedContent

interface StagedContent {
  stageId: string;
  content: ContentReference;
}