@markwasfy/loko 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,367 @@
+/**
+ * Core type definitions for loko.
+ *
+ * Design notes:
+ * - Server-assigned `version` is the authority for conflict resolution and delta
+ *   sync, NOT client wall-clock time. Device clocks drift, so `updatedAt` is kept
+ *   purely for display and as a hint for the default resolver.
+ * - `dirty` is never stored: it is derived as `localRev > lastPushedLocalRev`.
+ */
+/** A record stored locally, wrapping the user's data `T` with sync metadata. */
+interface StoredDoc<T = unknown> {
+    /** Primary key within the collection. */
+    id: string;
+    /** Collection name this record belongs to. */
+    collection: string;
+    /** The user's payload. `null` only ever paired with a tombstone (`deletedAt`). */
+    data: T;
+    /** Wall-clock ms of the last local edit. Display/hint only — never the sync authority. */
+    updatedAt: number;
+    /** Tombstone marker (soft delete) so deletions propagate. `null` = live record. */
+    deletedAt: number | null;
+    /** Bumped on every local edit. */
+    localRev: number;
+    /** Value of `localRev` at the last successful push ack. */
+    lastPushedLocalRev: number;
+    /** Server-assigned version this record was last synced to/from (0 = never synced). */
+    remoteVersion: number;
+    /** Wall-clock ms of the last successful sync touching this record. */
+    syncedAt: number | null;
+}
+/** `true` when a record has local edits not yet acknowledged by the server. */
+declare function isDirty(doc: Pick<StoredDoc, "localRev" | "lastPushedLocalRev">): boolean;
+/** A change transmitted over the wire (push/pull). */
+interface Change<T = unknown> {
+    collection: string;
+    id: string;
+    /** Payload, or `null` for a deletion. */
+    data: T | null;
+    /** Server-assigned version. For outgoing (push) changes this is the client's
+     *  last-known `remoteVersion` (the base the edit was made against). */
+    version: number;
+    /** Display value / resolver hint only. */
+    updatedAt: number;
+    /** Whether this change is a deletion. */
+    deleted: boolean;
+}
+/** Opaque, monotonically increasing server sequence used as a pull cursor. */
+type Cursor = string | number;
+/** Result of pushing local changes to the server. */
+interface PushResult {
+    /** Records the server accepted, with their newly committed versions. */
+    acked: Array<{
+        id: string;
+        collection: string;
+        version: number;
+    }>;
+    /**
+     * Records the server rejected because it was already ahead (e.g. client sent
+     * v5 but server has v6). Surfaced at push time so conflicts aren't only
+     * discovered on the next pull. May be omitted/empty.
+     */
+    conflicts?: Array<Change>;
+    /** Server sequence after this push; lets the client advance its pull cursor. */
+    cursor: Cursor;
+}
+/** Result of pulling remote changes since a cursor. */
+interface PullResult {
+    changes: Array<Change>;
+    cursor: Cursor;
+}
+/**
+ * Transport between the local store and a backend. Bring your own — implement
+ * this against REST, Supabase, Firebase, WebSockets, anything.
+ */
+interface SyncAdapter {
+    push(changes: Change[]): Promise<PushResult>;
+    pull(since: Cursor): Promise<PullResult>;
+}
+/** A handle for atomic multi-record writes within {@link StorageAdapter.transact}. */
+interface StorageTx {
+    put(doc: StoredDoc): void;
+    delete(collection: string, id: string): void;
+    setMeta(key: string, value: unknown): void;
+}
+/**
+ * Pluggable persistence layer. Ships with `indexedDBStorage()` (browser default)
+ * and `memoryStorage()` (tests/Node/SSR).
+ */
+interface StorageAdapter {
+    /** Open/prepare the store for the given database name. */
+    init(name: string): Promise<void>;
+    get(collection: string, id: string): Promise<StoredDoc | undefined>;
+    /** All records in a collection, including tombstones. */
+    getAll(collection: string): Promise<StoredDoc[]>;
+    put(doc: StoredDoc): Promise<void>;
+    bulkPut(docs: StoredDoc[]): Promise<void>;
+    /**
+     * Run `fn` as an atomic, all-or-nothing transaction. Underpins `bulkPut`
+     * today and `sync.transaction()` (reserved) tomorrow. A throw rolls back.
+     */
+    transact(fn: (tx: StorageTx) => void | Promise<void>): Promise<void>;
+    /** All records with unsynced local edits, across every collection. */
+    getDirty(): Promise<StoredDoc[]>;
+    getMeta<V = unknown>(key: string): Promise<V | undefined>;
+    setMeta(key: string, value: unknown): Promise<void>;
+    /** Release resources (close DB, channels). */
+    close(): Promise<void>;
+}
+/**
+ * Decides the winner when a local edit and a remote change collide. The default
+ * is {@link lastWriteWins}. Conflict resolution is per-record, not per-field:
+ * to merge fields, return a record built from both sides.
+ */
+type ConflictResolver = <T = unknown>(local: StoredDoc<T> | undefined, remote: Change<T>) => StoredDoc<T>;
+/** Options declared once per collection via {@link Sync.defineCollection}. */
+interface CollectionOptions {
+    /** Field on the record used as the id. Defaults to `"id"`. */
+    primaryKey?: string;
+    /**
+     * Indexed fields. Accepted and validated in v1 but not yet used for querying
+     * (reserved for indexed reads on the roadmap).
+     */
+    indexes?: string[];
+}
+type SyncStatus = "idle" | "syncing" | "offline" | "error";
+/** Map of event name -> payload for the typed emitter. */
+interface SyncEvents {
+    /** A record changed locally or via sync. */
+    change: {
+        collection: string;
+        id: string;
+        doc: StoredDoc | undefined;
+    };
+    /** A full sync cycle completed. */
+    sync: {
+        pushed: number;
+        pulled: number;
+    };
+    /** Sync status transitioned. */
+    status: {
+        status: SyncStatus;
+    };
+    /** Something went wrong (sync, storage, transport). */
+    error: {
+        error: unknown;
+    };
+}
+interface SyncConfig {
+    /** Logical database name; also namespaces the multi-tab BroadcastChannel. */
+    name: string;
+    /** Where records live. Defaults to `indexedDBStorage()` in the browser. */
+    storage: StorageAdapter;
+    /** How to talk to the backend. Optional — omit for a purely local store. */
+    adapter?: SyncAdapter;
+    /** Conflict strategy. Defaults to {@link lastWriteWins}. */
+    conflict?: ConflictResolver;
+    /**
+     * When `true` (default), sync on reconnect and on an interval (leader tab only).
+     * Pass a number to override the polling interval in ms (0 disables polling).
+     */
+    autoSync?: boolean | number;
+}
+
+/** Internal wiring handed to each {@link Collection} by the owning Sync instance. */
+interface CollectionContext {
+    storage: StorageAdapter;
+    primaryKey: string;
+    indexes: string[];
+    /** Resolves once storage is initialized; awaited before every storage access. */
+    ready: Promise<void>;
+    /**
+     * Called after a local write. The Sync engine emits a `change` event,
+     * broadcasts to other tabs, and schedules autoSync.
+     */
+    onLocalWrite(doc: StoredDoc): void;
+}
+/**
+ * A typed view over one collection of records. Reads/writes the user's payload
+ * `T` and tracks sync metadata under the hood. `T` must carry the primary key
+ * field (default `"id"`).
+ */
+declare class Collection<T extends Record<string, unknown> = Record<string, unknown>> {
+    readonly name: string;
+    private readonly ctx;
+    private readonly subscribers;
+    private readonly oneSubscribers;
+    private refreshScheduled;
+    constructor(name: string, ctx: CollectionContext);
+    private idOf;
+    /** Read a single live record by id (tombstones return `undefined`). */
+    get(id: string): Promise<T | undefined>;
+    /** All live records in the collection (tombstones excluded). */
+    all(): Promise<T[]>;
+    /** Insert or update a record. Returns the stored record. */
+    put(record: T): Promise<T>;
+    /** Insert or update many records atomically (one transaction). */
+    bulkPut(records: T[]): Promise<void>;
+    /** Soft-delete a record (writes a tombstone so the deletion syncs). */
+    delete(id: string): Promise<void>;
+    /** Build the next StoredDoc for a local write, bumping `localRev`. */
+    private nextDoc;
+    /**
+     * Subscribe to the whole collection. The callback fires immediately with the
+     * current records, then on every change (local, sync, or other tab).
+     * Returns an unsubscribe function.
+     */
+    subscribe(cb: (items: T[]) => void): () => void;
+    /** Subscribe to a single record by id. */
+    subscribeOne(id: string, cb: (item: T | undefined) => void): () => void;
+    /**
+     * Notify subscribers that this collection changed. Coalesces bursts (e.g.
+     * bulkPut, a sync batch) into a single refresh per microtask. Called by the
+     * Sync engine for local writes, pulled changes, and cross-tab updates.
+     */
+    notify(): void;
+}
+
+declare class Sync {
+    private readonly storage;
+    private readonly adapter;
+    private readonly resolver;
+    private readonly emitter;
+    private readonly collections;
+    private readonly options;
+    private readonly tabs;
+    private readonly background;
+    private readonly autoSync;
+    private readonly ready;
+    private _status;
+    private inFlight;
+    private clientId;
+    constructor(config: SyncConfig);
+    private init;
+    /** Declare a collection's options once (at init). Returns the collection. */
+    defineCollection<T extends Record<string, unknown>>(name: string, options?: CollectionOptions): Collection<T>;
+    /** Access a collection. Auto-defines with defaults if not yet declared. */
+    collection<T extends Record<string, unknown>>(name: string): Collection<T>;
+    private getOrCreate;
+    /**
+     * Convenience for simple key -> value cases. Stored as a SINGLE record in the
+     * reserved `_kv` collection, so it syncs as one coarse record. Not smart
+     * per-item sync — use real collections (`collection().put`) for that.
+     */
+    store<V>(key: string, value: V): Promise<void>;
+    /** Read a value previously written with {@link store}. */
+    get<V>(key: string): Promise<V | undefined>;
+    get status(): SyncStatus;
+    /** Resolves once storage is initialized (clientId loaded, leader elected). */
+    whenReady(): Promise<void>;
+    /** Subscribe to a lifecycle event. Returns an unsubscribe function. */
+    on<K extends keyof SyncEvents>(event: K, fn: (payload: SyncEvents[K]) => void): () => void;
+    /**
+     * Run a full sync cycle: push local changes, then pull remote ones. Concurrent
+     * calls share the same in-flight run. No-op when no adapter is configured.
+     */
+    sync(): Promise<{
+        pushed: number;
+        pulled: number;
+    }>;
+    private push;
+    private pull;
+    /** Apply one remote change, returning the StoredDoc to write, or `undefined` to skip. */
+    private resolveRemote;
+    private applyRemote;
+    private handleLocalWrite;
+    private notifyAndBroadcast;
+    private onTabMessage;
+    private setStatus;
+    /** Opt into Service Worker Background Sync (no-op if unsupported). */
+    registerBackgroundSync(tag?: string): Promise<boolean>;
+    /** Tear down listeners, timers, and channels, and close storage. */
+    close(): Promise<void>;
+}
+/** Create a Sync instance. See {@link SyncConfig}. */
+declare function createSync(config: SyncConfig): Sync;
+
+interface IndexedDBStorageOptions {
+    /** Override the IDBFactory (e.g. inject fake-indexeddb in tests). */
+    indexedDB?: IDBFactory;
+}
+/**
+ * Default browser {@link StorageAdapter}, backed by IndexedDB. Zero dependencies.
+ *
+ * Records live in a `docs` store keyed by `[collection, id]` with a `collection`
+ * index for range scans; key/value meta lives in a `meta` store.
+ *
+ * `transact` buffers writes synchronously inside the callback, then applies them
+ * in a single IndexedDB transaction — so a throw rolls everything back, and we
+ * never hold an IDB transaction open across an `await` (which would auto-close it).
+ */
+declare function indexedDBStorage(options?: IndexedDBStorageOptions): StorageAdapter;
+
+/**
+ * In-memory {@link StorageAdapter} for tests, Node, and SSR. Not persistent.
+ *
+ * `transact` buffers writes and applies them atomically: if `fn` throws, no
+ * change is committed (the rollback guarantee `bulkPut` and `transaction` rely on).
+ */
+declare function memoryStorage(): StorageAdapter;
+
+interface RestAdapterOptions {
+    /**
+     * Base URL of the sync endpoints. The adapter calls:
+     * - `POST {url}/push`  body `{ changes }`            -> `{ acked, conflicts?, cursor }`
+     * - `GET  {url}/pull?since={cursor}`                 -> `{ changes, cursor }`
+     */
+    url: string;
+    /** Extra headers (e.g. auth). Called per request so tokens can refresh. */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Override `fetch` (e.g. for tests or custom retry/agent behavior). */
+    fetch?: typeof fetch;
+}
+/**
+ * Default HTTP {@link SyncAdapter}. Implements a tiny, copy-pasteable protocol;
+ * see `examples/server` for a reference backend.
+ */
+declare function restAdapter(options: RestAdapterOptions): SyncAdapter;
+
+/**
+ * A minimal in-memory "server". Assigns a monotonically increasing `version` to
+ * every committed change (this `version` is the conflict-resolution authority,
+ * not client clocks) and exposes it as the pull cursor. Share one server across
+ * several {@link memoryAdapter} instances to simulate multiple clients in tests.
+ */
+declare class MemoryServer {
+    private records;
+    private seq;
+    private key;
+    commit(changes: Change[]): PushResult;
+    changesSince(since: Cursor): {
+        changes: Change[];
+        cursor: Cursor;
+    };
+    private toChange;
+}
+/**
+ * In-memory {@link SyncAdapter} for tests and demos. Pass a shared
+ * {@link MemoryServer} to connect multiple simulated clients to one backend.
+ */
+declare function memoryAdapter(server?: MemoryServer): SyncAdapter;
+
+/**
+ * Build a clean local record by fully adopting a remote change. Used for
+ * fast-forward (non-conflicting) updates and when the remote wins a conflict.
+ * The resulting record is NOT dirty (`localRev === lastPushedLocalRev`).
+ */
+declare function docFromRemote<T>(remote: Change<T>, now?: number): StoredDoc<T>;
+/**
+ * Default conflict strategy: **last write wins** by wall-clock `updatedAt`, with
+ * the already-committed remote winning ties. Conflict resolution is per-record:
+ * the winning record replaces the loser wholesale (no field merge).
+ *
+ * - Remote wins  -> adopt remote (record becomes clean).
+ * - Local wins   -> keep local data, rebased onto the remote's version, and left
+ *   dirty so it re-pushes and overwrites the server on the next sync.
+ */
+declare function lastWriteWins(): ConflictResolver;
+
+/**
+ * Opt-in helper to register a Service Worker Background Sync trigger, for true
+ * background sync when the page is closed. The core works fully without this;
+ * your service worker must listen for the `sync` event with the same tag and
+ * message clients to call `sync.sync()`.
+ */
+declare function registerBackgroundSync(tag?: string): Promise<boolean>;
+
+export { type Change, Collection, type CollectionOptions, type ConflictResolver, type Cursor, type IndexedDBStorageOptions, MemoryServer, type PullResult, type PushResult, type RestAdapterOptions, type StorageAdapter, type StorageTx, type StoredDoc, Sync, type SyncAdapter, type SyncConfig, type SyncEvents, type SyncStatus, createSync, docFromRemote, indexedDBStorage, isDirty, lastWriteWins, memoryAdapter, memoryStorage, registerBackgroundSync, restAdapter };