@superbee/core 0.1.6 → 0.2.0-pre.1

package/dist/indexeddb-backend.d.ts

@@ -0,0 +1,165 @@
+/**
+ * IndexedDB-backed {@link JournaledBackend}: the browser-local working copy's first persistent
+ * store candidate, sitting behind the same core seam as {@link FilesystemBackend} and
+ * {@link MemoryBackend} and proven by the same adapter contract kit, plus the journal seam the
+ * sync runtime needs (`journaled-backend.ts`), proven by that kit's journal rows.
+ *
+ * Storage shape mirrors the filesystem adapter, not the memory adapter: a concept document is
+ * stored as its exact OKF-serialized string and parsed on every read, so the read body carries
+ * the serializer's normalization (the trailing newline) and the version token is
+ * `versionOfBytes(raw)` over the same bytes the disk copy would hold. Reserved files are stored
+ * as raw strings and blobs as raw bytes, both content-addressed with the shared primitives, so a
+ * document, reserved file, or blob carries one token on disk, in memory, and in the browser.
+ *
+ * Compare-and-swap is one IndexedDB readwrite transaction per mutation: the current record is
+ * read, compared, and replaced (or the transaction aborted with a {@link VersionConflict}) before
+ * the transaction commits. IndexedDB serializes readwrite transactions that overlap on a store,
+ * so two adapter instances (two tabs, two workers) over the same database cannot both win a
+ * conditional write. A write resolves only after the transaction's `complete` event, which is
+ * the point a local-save indicator may follow. That is a commit promise, not a power-loss
+ * promise: the browser decides when committed pages reach stable storage.
+ *
+ * Two further stores serve the working copy's synchronization: `intents` journals every local
+ * write as a pending-change intent committed in the same transaction as the document record
+ * ({@link IndexedDbBackend.writeJournaled}), and `meta` holds opaque key-value rows such as the
+ * bootstrap marker and per-document shared bases. The adapter owns the transaction mechanics;
+ * what the rows mean belongs to the sync component that writes them, and what the verbs
+ * promise is stated once on the seam.
+ *
+ * This module imports no Node builtin so it bundles for the browser; the IndexedDB factory is
+ * injectable so a Node test can supply an in-memory implementation without touching globals.
+ */
+import { type IntentPatch, type IntentRecord, type JournaledBackend, type JournaledReadResult, type JournaledWriteOptions, type MetaRecord } from "./journaled-backend.js";
+import type { OperationState } from "./uncertain-write.js";
+import type { BlobKey, ConceptId, DeleteOptions, OkfDocument, ReadBlobResult, ReadResult, ReservedFilename, ReservedReadResult, StorageCapabilities, Version, VersionInfo, WriteOptions } from "./types.js";
+export { IntentHoldConflict, IntentStateConflict } from "./journaled-backend.js";
+export type { IntentPatch, IntentRecord, JournaledReadResult, JournaledWriteOptions, MetaRecord, NewIntentRecord } from "./journaled-backend.js";
+type Handler = ((this: any, event: any) => any) | null;
+export interface IdbRequestLike<T = unknown> {
+    readonly result: T;
+    readonly error: unknown;
+    onsuccess: Handler;
+    onerror: Handler;
+}
+export interface IdbOpenRequestLike extends IdbRequestLike<IdbDatabaseLike> {
+    onupgradeneeded: Handler;
+    onblocked: Handler;
+    readonly transaction: IdbTransactionLike | null;
+}
+export interface IdbObjectStoreLike {
+    get(key: string): IdbRequestLike;
+    getAll(): IdbRequestLike<unknown[]>;
+    getAllKeys(): IdbRequestLike<unknown[]>;
+    count(key: string): IdbRequestLike<number>;
+    put(value: unknown): IdbRequestLike;
+    delete(key: string): IdbRequestLike;
+}
+export interface IdbTransactionLike {
+    objectStore(name: string): IdbObjectStoreLike;
+    abort(): void;
+    readonly error: unknown;
+    oncomplete: Handler;
+    onerror: Handler;
+    onabort: Handler;
+}
+export interface IdbDatabaseLike {
+    readonly version: number;
+    readonly objectStoreNames: {
+        contains(name: string): boolean;
+        readonly length: number;
+    };
+    createObjectStore(name: string, options?: {
+        keyPath?: string;
+    }): unknown;
+    transaction(storeNames: string | string[], mode?: "readonly" | "readwrite"): IdbTransactionLike;
+    close(): void;
+    onversionchange: Handler;
+}
+export interface IdbFactoryLike {
+    open(name: string, version?: number): IdbOpenRequestLike;
+}
+export interface IndexedDbBackendOptions {
+    /** The IndexedDB database holding this working copy; one bundle per database. */
+    databaseName: string;
+    /** The factory to open it with. Defaults to the host's global `indexedDB`. */
+    indexedDB?: IdbFactoryLike;
+}
+/** The database does not carry this adapter's schema and the adapter refuses to touch it. */
+export declare class IndexedDbSchemaError extends Error {
+    readonly name = "IndexedDbSchemaError";
+}
+/** Bumping this requires a migration in `upgrade`; the handler refuses any other older layout. */
+export declare const INDEXEDDB_SCHEMA_VERSION = 1;
+/**
+ * A persistent browser-local OKF store implementing the {@link JournaledBackend} contract over
+ * IndexedDB. One instance per bundle per JavaScript realm; several instances over the same
+ * database name are peers whose conditional writes are serialized by the database.
+ */
+export declare class IndexedDbBackend implements JournaledBackend {
+    #private;
+    /**
+     * What a resolved write promises: the IndexedDB transaction reported `complete`. Whether the
+     * committed pages survive power loss is the browser's and the operating system's decision.
+     */
+    readonly durability: "transaction-committed";
+    constructor(options: IndexedDbBackendOptions);
+    /** Whether an IndexedDB factory is reachable, so a caller can fall back to another store. */
+    static available(indexedDB?: IdbFactoryLike): boolean;
+    /** The database name this adapter opens. */
+    get databaseName(): string;
+    capabilities(): StorageCapabilities;
+    /** Release the database handle. The next operation reopens it lazily. */
+    close(): void;
+    read(id: ConceptId): Promise<ReadResult>;
+    readMany(ids: ConceptId[]): Promise<ReadResult[]>;
+    write(id: ConceptId, doc: OkfDocument, options?: WriteOptions): Promise<Version>;
+    delete(id: ConceptId, options?: DeleteOptions): Promise<boolean>;
+    exists(id: ConceptId): Promise<boolean>;
+    list(prefix?: string): Promise<ConceptId[]>;
+    versions(id: ConceptId): Promise<VersionInfo[]>;
+    readReserved(dir: string, name: ReservedFilename): Promise<ReservedReadResult | null>;
+    writeReserved(dir: string, name: ReservedFilename, content: string, options?: WriteOptions): Promise<Version>;
+    /**
+     * One transaction over documents, intents, and meta: the document compare-and-swap of
+     * {@link write}, plus (optionally) deleting a superseded intent, recording a new intent for
+     * the written bytes, and putting meta rows. Every step is conditional on every other: a
+     * failed document CAS records no intent, and a superseded intent whose state moved fails the
+     * whole write with {@link IntentStateConflict} so the caller composes against fresh state.
+     * With `requireSettled`, an unsettled intent on the target fails it with
+     * {@link IntentHoldConflict} before the document is touched.
+     */
+    writeJournaled(id: ConceptId, doc: OkfDocument, options?: JournaledWriteOptions): Promise<{
+        version: Version;
+        raw: string;
+        intent: IntentRecord | null;
+    }>;
+    /**
+     * The document, every intent targeting it, and the named meta rows, from ONE readonly
+     * transaction over documents, reserved, intents, and meta. A caller deriving where a document
+     * stands (its bytes against its shared base and its journal) reads them here so a write in
+     * another realm between separate reads can never show it a document of one moment beside a
+     * journal of another; with this snapshot a mismatch is a genuine working-copy defect.
+     */
+    readWithJournal(id: ConceptId, options?: {
+        meta?: readonly string[];
+    }): Promise<JournaledReadResult>;
+    /** Intents in local commit order, optionally restricted to one or more states. */
+    listIntents(state?: OperationState | readonly OperationState[]): Promise<IntentRecord[]>;
+    readIntent(requestId: string): Promise<IntentRecord | undefined>;
+    /**
+     * Compare-and-swap on an intent's `state`: the patch applies only while the record is in
+     * `expectedState`, together with any meta rows, in one transaction. A different state or a
+     * missing record rejects with {@link IntentStateConflict} and writes nothing.
+     */
+    updateIntent(requestId: string, expectedState: OperationState, patch: IntentPatch, options?: {
+        meta?: MetaRecord[];
+    }): Promise<IntentRecord>;
+    readMeta<T = unknown>(key: string): Promise<T | undefined>;
+    writeMeta(key: string, value: unknown): Promise<void>;
+    readBlob(key: BlobKey): Promise<ReadBlobResult | null>;
+    writeBlob(key: BlobKey, bytes: Uint8Array, contentType?: string, options?: WriteOptions): Promise<Version>;
+    deleteBlob(key: BlobKey, options?: DeleteOptions): Promise<boolean>;
+    existsBlob(key: BlobKey): Promise<boolean>;
+    listBlobs(prefix?: string): Promise<BlobKey[]>;
+}
+//# sourceMappingURL=indexeddb-backend.d.ts.map

package/dist/indexeddb-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexeddb-backend.d.ts","sourceRoot":"","sources":["../src/indexeddb-backend.ts"],"names":[],"mappings":"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"}