API: the store

Everything import { ... } from 'selfstore' gives you. The narrative version is the quick start; this page is the surface, exhaustively.

import { selfstore } from 'selfstore';

const store = await selfstore<{ todos: Todo }>('todo-app');

function selfstore<S extends Record<string, SimpleRecord>>(
  app: string,
  options?: SimpleOptions
): Promise<SimpleStore<S>>;

The type parameter maps collection names to record shapes, so store.all('todos') returns readonly Todo[] rather than a bag of unknowns. Omit it and every record is Record<string, unknown>.

SimpleOptions

Every field is optional; the defaults carry a real app.

SimpleStore

Data

Files

Bytes ride in the same store, the same backup and the same merge as records.

type FileBytes = Uint8Array | ArrayBuffer | Blob;

interface PutFileInput {
  bytes: FileBytes;
  name?: string;
  mime?: string;
  /** Omit it: the default is the SHA-256 of the bytes, and that default is the feature. */
  id?: string;
}

The id defaults to the SHA-256 of the bytes, and that is load bearing rather than a convenience. Files merge by a union on their id, with no clock to order two bodies: when two devices hold different bytes under the same id, one is kept and the other is dropped - silently, because at that level there is nothing to compare and nothing to report. A content id makes that unreachable, since different bytes are a different file and the union keeps both.

So putFile refuses different bytes under an id you named yourself - identical bytes are a no-op, different bytes throw a TypeError naming the way out - and { replace: true } says you meant it. Correct for a body only ever written on one device; a silent loser as soon as two devices write it.

That same union is what makes a CRDT document safe to carry here. Yjs and Automerge updates are commutative and idempotent, so storing each update under its content id turns the union into the CRDT merge: no device’s update is lost when the copies meet, and folding them is the entire read path.

Two limits, stated rather than discovered: file deletions do not propagate (there are no tombstones for files), so a device that was offline re-contributes files another device removed - tie a file’s lifetime to a record and let the record’s deletion drive the cleanup. And everything is in memory, so this is for documents and images, not archives.

Destinations

An existing backup at the destination is merged with this device. An encrypted one needs its password up front: PASSWORD_REQUIRED is thrown before anything changes.

disconnect() goes back to device-only; the destination keeps its last backup. addReplica writes the same encrypted backup to a second destination on every save, and a broken copy never gates the store - see resilience.

Encryption

Backup files

The boolean from downloadBackup is the one people miss. A save dialog the user dismissed returns false, the pending flag stands, and telling them they have a backup would be a lie.

Status and lifecycle

subscribe fires on every state change; onChange fires only on data changes. Bind a save badge to the first and a list to the second.

The escape hatches

flowHost is what a widget’s store property actually consumes. An app built on the advanced store hands a flow the same three members itself.

Status types

type StorageState =
  | 'ephemeral' | 'cache-only' | 'saving'
  | 'saved' | 'pending-download' | 'needs-attention';

type Severity = 'ok' | 'info' | 'warn' | 'danger';

type StatusAction = 'choose-destination' | 'download' | 'reconnect' | 'unlock';

interface StatusDescriptor {
  state: StorageState;
  severity: Severity;
  actionable: boolean;
  action?: StatusAction;
  labelKey: string;    // stable i18n key; the app owns the copy
}

The descriptor is ranked: when several things are true at once, the most important wins. That is why you read status.action rather than deriving a remedy from the flags yourself - and why <selfstore-gate> can decide on its own whether to be on screen.

Mode is 'persistent' | 'ephemeral'. TargetKind is 'device' | 'file-manual' | (string & {}) - deliberately open, so a custom target’s kind flows through.

Errors

interface StoreError {
  code: SelfstoreErrorCode;
  labelKey: string;   // show this, mapped to your copy
  message: string;    // developer detail for logs. Never display it.
}

SelfstoreErrorCode has 19 members; the full table with what each one means and whether it is transient lives on error codes.

Backup files, without a store

backup() and restore() build and read the file format directly - useful for a one-off export, a migration script, or a Node-side tool.

const blob = await backup(snapshot)
  .as('my-app', '2.1.0')
  .encryptedWith(password)
  .alsoOpenedWith(recoveryCode)
  .verified()
  .toBlob();

Why .verified() exists. A backup encrypted with a key nobody can reproduce, truncated, or built from an empty snapshot looks exactly like a good one: right name, right date, plausible size. The difference shows up on the day of the disaster. Reading it back costs one decrypt of data the app already holds.

Why alsoOpenedWith exists. A password that lives in one person’s memory is the likeliest way a local-first backup dies - no server can reset it. Each secret wraps the same data key, so either opens the file and neither can read the other. Reading needs no change: withPassword(code) already tries every slot.

Reading

const snapshot = await restore(file).withPassword(pw).read();

Standalone helpers

Desktop shell

Inside a native webview the File System Access API is usually absent, so the disk file home would degrade to download-on-demand. Register the shell’s own filesystem and dialog calls and it writes a real path instead. The narrative version, with the Tauri one-liner, is desktop shell.

interface DesktopFileBridge {
  readFile(path: string): Promise<Uint8Array>;
  writeFile(path: string, data: Uint8Array): Promise<void>;
  stat(path: string): Promise<{ mtime?: Date | number | null } | null>;
  exists(path: string): Promise<boolean>;
  save(options: { defaultPath?: string; filters?: DesktopDialogFilter[] }): Promise<string | null>;
  open(options: {
    multiple?: boolean;
    filters?: DesktopDialogFilter[];
  }): Promise<string | string[] | null>;
}

interface DesktopDialogFilter {
  name: string;
  extensions: string[];
}

Only mtime is read out of stat, as the version marker, and a shell that cannot report one may leave it absent. open may answer with an array, so a host can pass its shell’s function through unchanged.

PasswordPolicy

interface PasswordPolicy {
  minLength?: number;          // in code points, so an emoji counts as one
  requireLowercase?: boolean;  // any script with case
  requireUppercase?: boolean;
  requireDigit?: boolean;
  requireSymbol?: boolean;     // anything that is not a letter or a number
}

interface PasswordCheck {
  ok: boolean;
  unmet: PasswordRequirement[];   // stable order; empty when ok
}

type PasswordRequirement = 'minLength' | 'lowercase' | 'uppercase' | 'digit' | 'symbol';

An empty or absent policy passes everything. Because checkPasswordPolicy is the same function the store enforces with, a live strength hint can never disagree with the rejection the user is about to hit.

The other entry points