@interocitor/core 0.0.0-beta.10

package/dist/storage/local-store.js

@@ -0,0 +1,490 @@
+/**
+ * Local storage layer — IndexedDB
+ *
+ * This is a cache, not the source of truth.
+ * If cleared, the app rehydrates from cloud.
+ *
+ * Stores:
+ *  - rows: the current merged state of all tables
+ *  - outbox: change entries pending upload
+ *  - cursors: byte offsets into each device's change log
+ *  - meta: device ID, last snapshot epoch, etc.
+ */
+const DEFAULT_DB_NAME = 'interocitor';
+const DEFAULT_DB_VERSION = 1;
+const CACHE_FINGERPRINT_META_KEY = 'interocitor:cache:fingerprint';
+const STORES = {
+    rows: 'rows', // key: "{table}/{rowId}"
+    outbox: 'outbox', // key: auto-increment
+    cursors: 'cursors', // key: deviceId
+    meta: 'meta', // key: string
+};
+const SCHEMA_INDEX_PREFIX = 'idx:';
+function schemaIndexName(table, indexName) {
+    return `${SCHEMA_INDEX_PREFIX}${table}:${indexName}`;
+}
+function schemaIndexKeyPath(field) {
+    // Index key is composite: [table, payload-field-value]. Both live under
+    // namespaced parents now. ColumnEntry stores the user value under `.value`.
+    return ['_meta.table', `payload.${field}.value`];
+}
+function normalizeSchema(schema) {
+    if (!schema)
+        return undefined;
+    return schema;
+}
+function domStringListToArray(list) {
+    const out = [];
+    for (let i = 0; i < list.length; i++) {
+        const item = list.item(i);
+        if (item)
+            out.push(item);
+    }
+    return out;
+}
+function expectedSchemaIndexes(schema) {
+    const expected = new Map();
+    if (!schema)
+        return expected;
+    for (const table of Object.keys(schema.tables).sort()) {
+        const def = schema.tables[table];
+        const fieldEntries = Object.entries(def.fields ?? {}).sort(([a], [b]) => a.localeCompare(b));
+        for (const [fieldName, input] of fieldEntries) {
+            const fieldDef = normalizeFieldInput(input);
+            if (!fieldDef.index && !fieldDef.unique)
+                continue;
+            expected.set(schemaIndexName(table, `by_${fieldName}`), {
+                keyPath: schemaIndexKeyPath(fieldName),
+                unique: fieldDef.unique ?? false,
+            });
+        }
+        const indexes = [...(def.indexes ?? [])].sort((a, b) => a.name.localeCompare(b.name) || a.field.localeCompare(b.field));
+        for (const index of indexes) {
+            expected.set(schemaIndexName(table, index.name), {
+                keyPath: schemaIndexKeyPath(index.field),
+                unique: index.unique ?? false,
+            });
+        }
+    }
+    return expected;
+}
+function normalizeFieldInput(input) {
+    return {
+        index: input.index ?? false,
+        unique: input.unique ?? false,
+    };
+}
+function readColumnValue(row, field) {
+    const entry = row.payload?.[field];
+    if (entry === undefined)
+        return undefined;
+    return entry.value;
+}
+function compare(a, b) {
+    const av = a instanceof Date ? a.getTime() : a;
+    const bv = b instanceof Date ? b.getTime() : b;
+    if (av < bv)
+        return -1;
+    if (av > bv)
+        return 1;
+    return 0;
+}
+function matchesClause(value, clause) {
+    if (value === undefined || value === null)
+        return false;
+    switch (clause.op) {
+        case 'equals':
+            return compare(value, clause.value) === 0;
+        case 'above':
+            return compare(value, clause.value) > 0;
+        case 'aboveOrEqual':
+            return compare(value, clause.value) >= 0;
+        case 'below':
+            return compare(value, clause.value) < 0;
+        case 'belowOrEqual':
+            return compare(value, clause.value) <= 0;
+        case 'between': {
+            const lowerCmp = compare(value, clause.lower);
+            const upperCmp = compare(value, clause.upper);
+            const lowerOk = clause.lowerOpen ? lowerCmp > 0 : lowerCmp >= 0;
+            const upperOk = clause.upperOpen ? upperCmp < 0 : upperCmp <= 0;
+            return lowerOk && upperOk;
+        }
+        case 'startsWith':
+            return typeof value === 'string' && value.startsWith(String(clause.value));
+        case 'anyOf':
+            return (clause.values ?? []).some(v => compare(value, v) === 0);
+        default:
+            return false;
+    }
+}
+function hasSchemaIndex(schema, table, field) {
+    const tableSchema = schema?.tables[table];
+    if (!tableSchema)
+        return undefined;
+    const legacy = tableSchema.indexes?.find(index => index.field === field);
+    if (legacy)
+        return legacy;
+    const fromField = tableSchema.fields?.[field];
+    if (!fromField)
+        return undefined;
+    const fieldDef = normalizeFieldInput(fromField);
+    if (!fieldDef.index && !fieldDef.unique)
+        return undefined;
+    return {
+        name: `by_${field}`,
+        field,
+        unique: fieldDef.unique,
+    };
+}
+function rangeForClause(table, clause) {
+    // Schema indexes are keyed as [table, fieldValue]. Range queries must bound
+    // both sides of the compound key; lowerBound([table, value]) alone would also
+    // include later table names, and upperBound([table, value]) would include
+    // earlier table names.
+    const tableLowerBound = [table];
+    const tableUpperBound = [table, []];
+    switch (clause.op) {
+        case 'equals':
+            return IDBKeyRange.only([table, clause.value]);
+        case 'above':
+            return IDBKeyRange.bound([table, clause.value], tableUpperBound, true, false);
+        case 'aboveOrEqual':
+            return IDBKeyRange.bound([table, clause.value], tableUpperBound, false, false);
+        case 'below':
+            return IDBKeyRange.bound(tableLowerBound, [table, clause.value], false, true);
+        case 'belowOrEqual':
+            return IDBKeyRange.bound(tableLowerBound, [table, clause.value], false, false);
+        case 'between':
+            return IDBKeyRange.bound([table, clause.lower], [table, clause.upper], clause.lowerOpen ?? false, clause.upperOpen ?? false);
+        case 'startsWith': {
+            const prefix = String(clause.value ?? '');
+            return IDBKeyRange.bound([table, prefix], [table, `${prefix}\uFFFF`], false, false);
+        }
+        case 'anyOf':
+            return null;
+        default:
+            return null;
+    }
+}
+function reconcileSchemaIndexes(rowsStore, schema) {
+    const expected = expectedSchemaIndexes(schema);
+    const existing = domStringListToArray(rowsStore.indexNames).filter(name => name.startsWith(SCHEMA_INDEX_PREFIX));
+    for (const indexName of existing) {
+        if (!expected.has(indexName)) {
+            rowsStore.deleteIndex(indexName);
+        }
+    }
+    for (const [indexName, def] of expected.entries()) {
+        if (!rowsStore.indexNames.contains(indexName)) {
+            rowsStore.createIndex(indexName, def.keyPath, { unique: def.unique });
+        }
+    }
+}
+function openDB(dbName, dbVersion, schema) {
+    return new Promise((resolve, reject) => {
+        const req = dbVersion === undefined ? indexedDB.open(dbName) : indexedDB.open(dbName, dbVersion);
+        req.onupgradeneeded = () => {
+            const db = req.result;
+            if (!db.objectStoreNames.contains(STORES.rows)) {
+                // keyPath uses dotted path into the new namespaced row shape.
+                // IndexedDB resolves "_meta.key" against the stored object.
+                const rows = db.createObjectStore(STORES.rows, { keyPath: '_meta.key' });
+                rows.createIndex('by_table', '_meta.table', { unique: false });
+            }
+            if (!db.objectStoreNames.contains(STORES.outbox)) {
+                db.createObjectStore(STORES.outbox, { autoIncrement: true });
+            }
+            if (!db.objectStoreNames.contains(STORES.cursors)) {
+                db.createObjectStore(STORES.cursors);
+            }
+            if (!db.objectStoreNames.contains(STORES.meta)) {
+                db.createObjectStore(STORES.meta);
+            }
+            const rowsStore = req.transaction?.objectStore(STORES.rows);
+            if (rowsStore)
+                reconcileSchemaIndexes(rowsStore, schema);
+        };
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
+}
+function tx(db, stores, mode) {
+    return db.transaction(stores, mode);
+}
+function reqToPromise(req) {
+    return new Promise((resolve, reject) => {
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
+}
+function txComplete(transaction) {
+    return new Promise((resolve, reject) => {
+        transaction.oncomplete = () => resolve();
+        transaction.onerror = () => reject(transaction.error);
+    });
+}
+// ─── Public API ──────────────────────────────────────────────────────
+/**
+ * Default IndexedDB-backed local persistence layer used by {@link Interocitor}.
+ *
+ * Most applications do not need to interact with this class directly unless
+ * they are supplying a custom `localStoreFactory` or swapping local storage at
+ * runtime for testing or advanced integrations.
+ */
+export class LocalStore {
+    /**
+     * @param dbName    IndexedDB database name. Use distinct names to isolate
+     *                  multiple engine instances on the same origin.
+     *                  Default: "interocitor"
+     * @param dbVersion IndexedDB schema version. Default: 1
+     */
+    constructor(dbName, dbVersion, schema) {
+        this.db = null;
+        this.schema = normalizeSchema(schema);
+        this.dbName = dbName ?? DEFAULT_DB_NAME;
+        this.configuredDbVersion = dbVersion;
+        this.expectedIndexes = expectedSchemaIndexes(this.schema);
+        this.desiredFingerprint = JSON.stringify(Array.from(this.expectedIndexes.entries()).map(([name, def]) => ({
+            name,
+            keyPath: def.keyPath,
+            unique: def.unique,
+        })));
+    }
+    async readCacheFingerprint(db) {
+        const t = tx(db, STORES.meta, 'readonly');
+        const value = await reqToPromise(t.objectStore(STORES.meta).get(CACHE_FINGERPRINT_META_KEY));
+        return typeof value === 'string' ? value : undefined;
+    }
+    async writeCacheFingerprint(db) {
+        const t = tx(db, STORES.meta, 'readwrite');
+        t.objectStore(STORES.meta).put(this.desiredFingerprint, CACHE_FINGERPRINT_META_KEY);
+        await txComplete(t);
+    }
+    needsRepair(db, storedFingerprint) {
+        if (!db.objectStoreNames.contains(STORES.rows))
+            return true;
+        const rows = tx(db, STORES.rows, 'readonly').objectStore(STORES.rows);
+        const existing = new Set(domStringListToArray(rows.indexNames).filter(name => name.startsWith(SCHEMA_INDEX_PREFIX)));
+        if (storedFingerprint !== this.desiredFingerprint)
+            return true;
+        if (existing.size !== this.expectedIndexes.size)
+            return true;
+        for (const name of this.expectedIndexes.keys()) {
+            if (!existing.has(name))
+                return true;
+        }
+        return false;
+    }
+    async open() {
+        const requestedVersion = this.configuredDbVersion ?? DEFAULT_DB_VERSION;
+        let db = await openDB(this.dbName, undefined, this.schema);
+        const reopenAt = async (nextVersion) => {
+            db.close();
+            return openDB(this.dbName, nextVersion, this.schema);
+        };
+        if (db.version < requestedVersion) {
+            db = await reopenAt(requestedVersion);
+        }
+        let storedFingerprint = await this.readCacheFingerprint(db);
+        const repairVersion = this.needsRepair(db, storedFingerprint)
+            ? Math.max(db.version + 1, requestedVersion)
+            : null;
+        if (repairVersion !== null) {
+            db = await reopenAt(repairVersion);
+            storedFingerprint = await this.readCacheFingerprint(db);
+        }
+        if (storedFingerprint !== this.desiredFingerprint) {
+            await this.writeCacheFingerprint(db);
+        }
+        this.db = db;
+    }
+    close() {
+        this.db?.close();
+        this.db = null;
+    }
+    ensureDB() {
+        if (!this.db)
+            throw new Error('LocalStore not opened');
+        return this.db;
+    }
+    // ── Rows ─────────────────────────────────────────────────────────
+    rowKey(table, rowId) {
+        return `${table}/${rowId}`;
+    }
+    async getRow(table, rowId) {
+        const db = this.ensureDB();
+        const t = tx(db, STORES.rows, 'readonly');
+        const store = t.objectStore(STORES.rows);
+        const result = await reqToPromise(store.get(this.rowKey(table, rowId)));
+        return result;
+    }
+    /** Stamp the composite IndexedDB key into row._meta.key. Pure. */
+    withKey(row) {
+        return {
+            ...row,
+            _meta: { ...row._meta, key: this.rowKey(row._meta.table, row._meta.rowId) },
+            payload: row.payload,
+        };
+    }
+    async putRow(row) {
+        const db = this.ensureDB();
+        const t = tx(db, STORES.rows, 'readwrite');
+        const store = t.objectStore(STORES.rows);
+        store.put(this.withKey(row));
+        await txComplete(t);
+    }
+    async putRows(rows) {
+        if (rows.length === 0)
+            return;
+        const db = this.ensureDB();
+        const t = tx(db, STORES.rows, 'readwrite');
+        const store = t.objectStore(STORES.rows);
+        for (const row of rows) {
+            store.put(this.withKey(row));
+        }
+        await txComplete(t);
+    }
+    async getTable(table) {
+        const db = this.ensureDB();
+        const t = tx(db, STORES.rows, 'readonly');
+        const store = t.objectStore(STORES.rows);
+        const index = store.index('by_table');
+        const results = await reqToPromise(index.getAll(table));
+        return results.filter(r => !r._meta.deleted);
+    }
+    async queryWhere(table, clause) {
+        const db = this.ensureDB();
+        const indexDef = hasSchemaIndex(this.schema, table, clause.field);
+        if (!indexDef) {
+            const rows = await this.getTable(table);
+            return rows.filter(row => matchesClause(readColumnValue(row, clause.field), clause));
+        }
+        const t = tx(db, STORES.rows, 'readonly');
+        const store = t.objectStore(STORES.rows);
+        const indexName = schemaIndexName(table, indexDef.name);
+        if (!store.indexNames.contains(indexName)) {
+            const rows = await this.getTable(table);
+            return rows.filter(row => matchesClause(readColumnValue(row, clause.field), clause));
+        }
+        const index = store.index(indexName);
+        if (clause.op === 'anyOf') {
+            const values = clause.values ?? [];
+            const merged = new Map();
+            for (const value of values) {
+                const matches = await reqToPromise(index.getAll(IDBKeyRange.only([table, value])));
+                for (const row of matches) {
+                    if (!row._meta.deleted && row._meta.table === table) {
+                        merged.set(`${row._meta.table}/${row._meta.rowId}`, row);
+                    }
+                }
+            }
+            return Array.from(merged.values());
+        }
+        const range = rangeForClause(table, clause);
+        const results = await reqToPromise(index.getAll(range ?? undefined));
+        return results.filter(row => !row._meta.deleted && row._meta.table === table);
+    }
+    async getTableNames() {
+        const db = this.ensureDB();
+        // Intentionally avoids openKeyCursor: Safari rejects null as a key range
+        // argument in some IDB versions. A full-store getAll() is safe everywhere
+        // and acceptable here — called once at init on an otherwise-empty DB.
+        const t = tx(db, STORES.rows, 'readonly');
+        const store = t.objectStore(STORES.rows);
+        const all = await reqToPromise(store.getAll());
+        const names = new Set();
+        for (const row of all) {
+            const table = row._meta?.table;
+            if (table)
+                names.add(table);
+        }
+        return Array.from(names);
+    }
+    async getAllRows() {
+        const db = this.ensureDB();
+        const t = tx(db, STORES.rows, 'readonly');
+        const store = t.objectStore(STORES.rows);
+        return reqToPromise(store.getAll());
+    }
+    async clearRows() {
+        const db = this.ensureDB();
+        const t = tx(db, STORES.rows, 'readwrite');
+        t.objectStore(STORES.rows).clear();
+        await txComplete(t);
+    }
+    // ── Outbox ───────────────────────────────────────────────────────
+    async pushOutbox(entry) {
+        await this.pushOutboxEntries([entry]);
+    }
+    async pushOutboxEntries(entries) {
+        if (entries.length === 0)
+            return;
+        const db = this.ensureDB();
+        const t = tx(db, STORES.outbox, 'readwrite');
+        const store = t.objectStore(STORES.outbox);
+        for (const entry of entries)
+            store.add(entry);
+        await txComplete(t);
+    }
+    async drainOutbox() {
+        const db = this.ensureDB();
+        const t = tx(db, STORES.outbox, 'readwrite');
+        const store = t.objectStore(STORES.outbox);
+        const entries = await reqToPromise(store.getAll());
+        store.clear();
+        await txComplete(t);
+        return entries;
+    }
+    async outboxSize() {
+        const db = this.ensureDB();
+        const t = tx(db, STORES.outbox, 'readonly');
+        return reqToPromise(t.objectStore(STORES.outbox).count());
+    }
+    // ── Cursors ──────────────────────────────────────────────────────
+    async getCursor(deviceId) {
+        const db = this.ensureDB();
+        const t = tx(db, STORES.cursors, 'readonly');
+        const result = await reqToPromise(t.objectStore(STORES.cursors).get(deviceId));
+        return result || 0;
+    }
+    async setCursor(deviceId, offset) {
+        const db = this.ensureDB();
+        const t = tx(db, STORES.cursors, 'readwrite');
+        t.objectStore(STORES.cursors).put(offset, deviceId);
+        await txComplete(t);
+    }
+    async getAllCursors() {
+        const db = this.ensureDB();
+        const t = tx(db, STORES.cursors, 'readonly');
+        const store = t.objectStore(STORES.cursors);
+        const keys = await reqToPromise(store.getAllKeys());
+        const values = await reqToPromise(store.getAll());
+        const cursors = {};
+        for (let i = 0; i < keys.length; i++) {
+            cursors[keys[i]] = values[i];
+        }
+        return cursors;
+    }
+    // ── Meta ─────────────────────────────────────────────────────────
+    async getMeta(key) {
+        const db = this.ensureDB();
+        const t = tx(db, STORES.meta, 'readonly');
+        return reqToPromise(t.objectStore(STORES.meta).get(key));
+    }
+    async setMeta(key, value) {
+        const db = this.ensureDB();
+        const t = tx(db, STORES.meta, 'readwrite');
+        t.objectStore(STORES.meta).put(value, key);
+        await txComplete(t);
+    }
+    /** Nuke everything. Used before full rehydration. */
+    async clearAll() {
+        const db = this.ensureDB();
+        const t = tx(db, Object.values(STORES), 'readwrite');
+        for (const name of Object.values(STORES)) {
+            t.objectStore(name).clear();
+        }
+        await txComplete(t);
+    }
+}

package/dist/storage/reset.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Delete an Interocitor IndexedDB database after callers have disconnected
+ * and cleared credentials.
+ *
+ * This is intentionally low-level: it only deletes the local IndexedDB
+ * database named by `dbName`. Apps should call it as the final destructive
+ * local reset step, then reload before creating or joining a new mesh.
+ */
+export declare function resetLocalDatabase(dbName?: string): Promise<void>;
+//# sourceMappingURL=reset.d.ts.map

package/dist/storage/reset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reset.d.ts","sourceRoot":"","sources":["../../src/storage/reset.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CASxE"}

package/dist/storage/reset.js

@@ -0,0 +1,18 @@
+/**
+ * Delete an Interocitor IndexedDB database after callers have disconnected
+ * and cleared credentials.
+ *
+ * This is intentionally low-level: it only deletes the local IndexedDB
+ * database named by `dbName`. Apps should call it as the final destructive
+ * local reset step, then reload before creating or joining a new mesh.
+ */
+export function resetLocalDatabase(dbName = 'interocitor') {
+    return new Promise((resolve, reject) => {
+        const req = indexedDB.deleteDatabase(dbName);
+        req.onsuccess = () => resolve();
+        req.onerror = () => reject(req.error ?? new Error(`Failed to delete IndexedDB database "${dbName}"`));
+        req.onblocked = () => {
+            reject(new Error(`Cannot delete IndexedDB database "${dbName}" while another connection is open`));
+        };
+    });
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@interocitor/core",
+  "version": "0.0.0-beta.10",
+  "description": "Encrypted local-first CRDT database that syncs over cloud storage without a purpose-built backend.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./adapters/google-drive": {
+      "import": "./dist/adapters/google-drive.js",
+      "types": "./dist/adapters/google-drive.d.ts"
+    },
+    "./adapters/webdav": {
+      "import": "./dist/adapters/webdav.js",
+      "types": "./dist/adapters/webdav.d.ts"
+    },
+    "./adapters/cloudflare": {
+      "import": "./dist/adapters/cloudflare.js",
+      "types": "./dist/adapters/cloudflare.d.ts"
+    },
+    "./adapters/memory": {
+      "import": "./dist/adapters/memory.js",
+      "types": "./dist/adapters/memory.d.ts"
+    },
+    "./storage/local-store": {
+      "import": "./dist/storage/local-store.js",
+      "types": "./dist/storage/local-store.d.ts"
+    },
+    "./storage/reset": {
+      "import": "./dist/storage/reset.js",
+      "types": "./dist/storage/reset.d.ts"
+    },
+    "./handshake/qr": {
+      "import": "./dist/handshake/qr-public.js",
+      "types": "./dist/handshake/qr-public.d.ts"
+    },
+    "./crypto/keys": {
+      "import": "./dist/crypto/keys.js",
+      "types": "./dist/crypto/keys.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf ./dist && tsc -p tsconfig.json",
+    "validate": "node ./dist/index.js",
+    "test:e2e": "yarn build && yarn exec playwright test -c ./playwright.config.ts",
+    "test:e2e:todo": "yarn build && yarn exec playwright test -c ./playwright.config.ts tests/e2e/todo-webdav.spec.ts"
+  },
+  "keywords": [
+    "local-first",
+    "crdt",
+    "sync",
+    "offline-first",
+    "google-drive",
+    "webdav",
+    "encrypted",
+    "mesh",
+    "indexeddb"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@playwright/test": "^1.54.2",
+    "typescript": "^6.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}