@lapis-notes/api 0.1.0

package/dist/storage/blob-store.d.ts

@@ -0,0 +1,12 @@
+import type { DataWriteOptions, Stat } from "./fs";
+export interface BlobStoreLike {
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<Stat | null>;
+    readBytes(path: string): Promise<ArrayBuffer>;
+    writeBytes(path: string, data: ArrayBuffer, options?: DataWriteOptions): Promise<void>;
+    delete(path: string): Promise<void>;
+    copy(path: string, newPath: string): Promise<void>;
+    move(path: string, newPath: string): Promise<void>;
+    createObjectUrl?(path: string): Promise<string>;
+    revokeObjectUrl?(url: string): void;
+}

package/dist/storage/blob-store.js

@@ -0,0 +1 @@
+export {};

package/dist/storage/browser-app-database-coordination.d.ts

@@ -0,0 +1,35 @@
+export interface BrowserAppDatabaseHeartbeat {
+    type: "db-owner-heartbeat";
+    vaultId: string;
+    ownerId: string;
+    timestamp: number;
+}
+export declare class BrowserAppDatabaseCoordinator {
+    readonly vaultId: string;
+    readonly tabId: string;
+    readonly ownerId: string;
+    readonly lockName: string;
+    readonly channelName: string;
+    readonly rpcChannelName: string;
+    private releaseLock;
+    private heartbeatChannel;
+    private heartbeatTimer;
+    private lastHeartbeatAt;
+    private lastOwnerId;
+    constructor(vaultId: string);
+    static hasLockApi(): boolean;
+    get heartbeatStaleAfterMs(): number;
+    get observedOwnerId(): string | null;
+    get observedHeartbeatAt(): number | null;
+    tryAcquireOwnership(): Promise<boolean>;
+    startHeartbeat(): void;
+    waitForOwnership(options?: Partial<{
+        signal: AbortSignal;
+    }>): Promise<boolean>;
+    release(): void;
+    close(): void;
+    private ensureHeartbeatChannel;
+    private hasRecentHeartbeat;
+    private publishHeartbeat;
+}
+export declare function isBrowserAppDatabaseAbort(error: unknown): boolean;

package/dist/storage/browser-app-database-coordination.js

@@ -0,0 +1,207 @@
+const HEARTBEAT_INTERVAL_MS = 1_000;
+const HEARTBEAT_STALE_AFTER_MS = HEARTBEAT_INTERVAL_MS * 3;
+const RETRY_JITTER_MIN_MS = 150;
+const RETRY_JITTER_MAX_MS = 650;
+function createTabId() {
+    if (typeof crypto !== "undefined" &&
+        typeof crypto.randomUUID === "function") {
+        return crypto.randomUUID();
+    }
+    return `tab-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+function isAbortError(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+function withAbortDelay(durationMs, signal) {
+    if (signal?.aborted) {
+        return Promise.resolve(false);
+    }
+    return new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            cleanup();
+            resolve(true);
+        }, durationMs);
+        const abort = () => {
+            cleanup();
+            resolve(false);
+        };
+        const cleanup = () => {
+            clearTimeout(timeout);
+            signal?.removeEventListener("abort", abort);
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+function retryDelayMs() {
+    return Math.floor(RETRY_JITTER_MIN_MS +
+        Math.random() * (RETRY_JITTER_MAX_MS - RETRY_JITTER_MIN_MS));
+}
+export class BrowserAppDatabaseCoordinator {
+    vaultId;
+    tabId = createTabId();
+    ownerId = this.tabId;
+    lockName;
+    channelName;
+    rpcChannelName;
+    releaseLock = null;
+    heartbeatChannel = null;
+    heartbeatTimer = null;
+    lastHeartbeatAt = 0;
+    lastOwnerId = null;
+    constructor(vaultId) {
+        this.vaultId = vaultId;
+        this.lockName = `lapis-notes-app-database-owner:${vaultId}`;
+        this.channelName = `lapis-notes-db-coordination:${vaultId}`;
+        this.rpcChannelName = `lapis-notes-db-rpc:${vaultId}`;
+    }
+    static hasLockApi() {
+        return (typeof navigator !== "undefined" &&
+            typeof navigator.locks?.request === "function");
+    }
+    get heartbeatStaleAfterMs() {
+        return HEARTBEAT_STALE_AFTER_MS;
+    }
+    get observedOwnerId() {
+        return this.lastOwnerId;
+    }
+    get observedHeartbeatAt() {
+        return this.lastHeartbeatAt || null;
+    }
+    async tryAcquireOwnership() {
+        if (!BrowserAppDatabaseCoordinator.hasLockApi()) {
+            return false;
+        }
+        if (this.releaseLock) {
+            return true;
+        }
+        let resolveReady;
+        let rejectReady;
+        const ready = new Promise((resolve, reject) => {
+            resolveReady = resolve;
+            rejectReady = reject;
+        });
+        let unlock;
+        const released = { value: false };
+        const holdLock = new Promise((resolve) => {
+            unlock = () => {
+                if (released.value) {
+                    return;
+                }
+                released.value = true;
+                resolve();
+            };
+        });
+        void navigator.locks
+            .request(this.lockName, { mode: "exclusive", ifAvailable: true }, async (lock) => {
+            if (!lock) {
+                resolveReady(null);
+                return;
+            }
+            this.releaseLock = unlock;
+            this.lastOwnerId = this.ownerId;
+            this.lastHeartbeatAt = Date.now();
+            resolveReady(unlock);
+            await holdLock;
+        })
+            .catch((error) => {
+            rejectReady(error);
+        });
+        try {
+            return Boolean(await ready);
+        }
+        catch (error) {
+            this.release();
+            throw error;
+        }
+    }
+    startHeartbeat() {
+        if (!this.releaseLock) {
+            return;
+        }
+        this.ensureHeartbeatChannel();
+        this.publishHeartbeat();
+        if (this.heartbeatTimer) {
+            return;
+        }
+        this.heartbeatTimer = setInterval(() => {
+            this.publishHeartbeat();
+        }, HEARTBEAT_INTERVAL_MS);
+    }
+    async waitForOwnership(options = {}) {
+        const { signal } = options;
+        if (signal?.aborted) {
+            return false;
+        }
+        this.ensureHeartbeatChannel();
+        while (!signal?.aborted) {
+            if (!this.hasRecentHeartbeat()) {
+                const acquired = await this.tryAcquireOwnership();
+                if (acquired) {
+                    return true;
+                }
+            }
+            const heartbeatAge = this.lastHeartbeatAt
+                ? Date.now() - this.lastHeartbeatAt
+                : Number.POSITIVE_INFINITY;
+            const waitMs = heartbeatAge < HEARTBEAT_STALE_AFTER_MS
+                ? Math.max(RETRY_JITTER_MIN_MS, HEARTBEAT_STALE_AFTER_MS - heartbeatAge + retryDelayMs())
+                : retryDelayMs();
+            const shouldContinue = await withAbortDelay(waitMs, signal);
+            if (!shouldContinue) {
+                return false;
+            }
+        }
+        return false;
+    }
+    release() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        this.releaseLock?.();
+        this.releaseLock = null;
+    }
+    close() {
+        this.release();
+        this.heartbeatChannel?.close();
+        this.heartbeatChannel = null;
+    }
+    ensureHeartbeatChannel() {
+        if (this.heartbeatChannel || typeof BroadcastChannel === "undefined") {
+            return;
+        }
+        this.heartbeatChannel = new BroadcastChannel(this.channelName);
+        this.heartbeatChannel.addEventListener("message", (event) => {
+            const heartbeat = event.data;
+            if (!heartbeat ||
+                heartbeat.type !== "db-owner-heartbeat" ||
+                heartbeat.vaultId !== this.vaultId ||
+                heartbeat.ownerId === this.ownerId) {
+                return;
+            }
+            this.lastOwnerId = heartbeat.ownerId;
+            this.lastHeartbeatAt = heartbeat.timestamp;
+        });
+    }
+    hasRecentHeartbeat() {
+        return (this.lastHeartbeatAt > 0 &&
+            Date.now() - this.lastHeartbeatAt < HEARTBEAT_STALE_AFTER_MS);
+    }
+    publishHeartbeat() {
+        if (!this.heartbeatChannel) {
+            return;
+        }
+        const heartbeat = {
+            type: "db-owner-heartbeat",
+            vaultId: this.vaultId,
+            ownerId: this.ownerId,
+            timestamp: Date.now(),
+        };
+        this.lastOwnerId = heartbeat.ownerId;
+        this.lastHeartbeatAt = heartbeat.timestamp;
+        this.heartbeatChannel.postMessage(heartbeat);
+    }
+}
+export function isBrowserAppDatabaseAbort(error) {
+    return isAbortError(error);
+}

package/dist/storage/browser-coordinated-app-database.d.ts

@@ -0,0 +1,109 @@
+import type { AppDatabase, AppDatabaseChangeListener, AppDatabaseDescriptor, AppDatabaseFileHistory, AppDatabaseIndexedFile, AppDatabaseIndexedFileManifestPage, AppDatabaseIndexedFileManifestQuery, AppDatabaseIndexedMetadataPage, AppDatabaseIndexedMetadataPageQuery, AppDatabaseIndexedMetadataQuery, AppDatabaseIndexedMetadataRow, AppDatabaseKind, AppDatabaseMetadataFacetQuery, AppDatabaseMetadataFacetRow, AppDatabaseMetadataLinkQuery, AppDatabaseMemoryCandidateInput, AppDatabaseMemoryCandidateQuery, AppDatabaseMemoryCandidateResult, AppDatabaseMemoryJobClaimInput, AppDatabaseMemoryJobRecord, AppDatabaseMemoryJobUpdateInput, AppDatabaseMemoryRecallSignalRecord, AppDatabaseMemorySourceRecord, AppDatabaseProvider, AppDatabaseNotificationRecord, AppDatabaseSearchIndexStats, AppDatabaseNotebookState, AppDatabaseSearchOptions, AppDatabaseSearchResult, AppDatabaseStoreFileHistoryRevisionInput, AppDatabaseStoreFileHistoryRevisionResult, MetadataCacheSnapshot, SearchDocumentRecord, SearchDocumentManifestPage, SearchDocumentManifestQuery, SearchEmbeddingProviderConfig, SearchEmbeddingRuntimeStatus, AppDatabaseLinkRecord } from "./app-database";
+import type { AppDatabaseTaskChildQuery, AppDatabaseTaskQuery, AppDatabaseTaskRecord } from "./task-projection";
+import { BrowserAppDatabaseCoordinator } from "./browser-app-database-coordination";
+export type BrowserCoordinatedAppDatabaseMode = "turso-owner" | "turso-proxy";
+export declare class BrowserCoordinatedAppDatabase implements AppDatabase {
+    readonly vaultId: string;
+    private readonly coordinator;
+    private startsOwned;
+    private readonly provider;
+    get kind(): AppDatabaseKind;
+    get descriptor(): AppDatabaseDescriptor;
+    private localDatabase;
+    private remoteDescriptor;
+    private rpcChannel;
+    private pendingRequests;
+    private opened;
+    private closed;
+    private ownershipMonitorAbortController;
+    private promotionPromise;
+    private servingRequests;
+    private coordinationModeListeners;
+    private changeListeners;
+    private localChangeUnsubscribe;
+    private lastSeenRevision;
+    constructor(vaultId: string, coordinator: BrowserAppDatabaseCoordinator, startsOwned: boolean, provider?: AppDatabaseProvider);
+    get coordinationMode(): BrowserCoordinatedAppDatabaseMode;
+    onCoordinationModeChange(listener: (mode: BrowserCoordinatedAppDatabaseMode) => void): () => void;
+    open(): Promise<void>;
+    migrate(): Promise<void>;
+    close(): Promise<void>;
+    beginSearchIndexingBatch(): Promise<void>;
+    endSearchIndexingBatch(): Promise<void>;
+    configureSearchEmbeddingProvider(provider: SearchEmbeddingProviderConfig | null): Promise<void>;
+    getSearchEmbeddingProvider(): Promise<SearchEmbeddingProviderConfig | null>;
+    getSearchEmbeddingRuntimeStatus(): Promise<SearchEmbeddingRuntimeStatus | null>;
+    getSearchIndexStats(): Promise<AppDatabaseSearchIndexStats>;
+    getMeta<T = unknown>(key: string): Promise<T | undefined>;
+    setMeta(key: string, value: unknown): Promise<void>;
+    getNotebookState(sourcePath: string): Promise<AppDatabaseNotebookState | undefined>;
+    setNotebookState(sourcePath: string, state: AppDatabaseNotebookState): Promise<void>;
+    deleteNotebookState(sourcePath: string): Promise<void>;
+    loadMetadataSnapshot(): Promise<MetadataCacheSnapshot | null>;
+    saveMetadataSnapshot(snapshot: MetadataCacheSnapshot): Promise<void>;
+    getFileHistory(path: string): Promise<AppDatabaseFileHistory | null>;
+    storeFileHistoryRevision(input: AppDatabaseStoreFileHistoryRevisionInput): Promise<AppDatabaseStoreFileHistoryRevisionResult>;
+    listNotifications(): Promise<AppDatabaseNotificationRecord[]>;
+    upsertNotification(record: AppDatabaseNotificationRecord): Promise<void>;
+    markNotificationRead(id: string): Promise<void>;
+    clearNotification(id: string): Promise<void>;
+    clearAllNotifications(): Promise<void>;
+    getMemorySourceState(sourceKey: string): Promise<AppDatabaseMemorySourceRecord | undefined>;
+    listMemorySourceStates(): Promise<AppDatabaseMemorySourceRecord[]>;
+    upsertMemorySourceState(record: AppDatabaseMemorySourceRecord): Promise<void>;
+    deleteMemorySourceState(sourceKey: string): Promise<void>;
+    upsertMemoryCandidate(input: AppDatabaseMemoryCandidateInput): Promise<void>;
+    queryMemoryCandidates(query?: AppDatabaseMemoryCandidateQuery): Promise<AppDatabaseMemoryCandidateResult[]>;
+    deleteMemoryCandidatesByConversation(conversationId: string): Promise<void>;
+    recordMemoryRecallSignal(record: AppDatabaseMemoryRecallSignalRecord): Promise<void>;
+    listMemoryRecallSignals(targetRef?: string): Promise<AppDatabaseMemoryRecallSignalRecord[]>;
+    claimMemoryJob(input: AppDatabaseMemoryJobClaimInput): Promise<AppDatabaseMemoryJobRecord | null>;
+    updateMemoryJob(input: AppDatabaseMemoryJobUpdateInput): Promise<AppDatabaseMemoryJobRecord | null>;
+    listMemoryJobs(scopeKey?: string): Promise<AppDatabaseMemoryJobRecord[]>;
+    clearMemoryDerivedState(): Promise<void>;
+    getChangeRevision(): Promise<number>;
+    subscribeToChanges(listener: AppDatabaseChangeListener): () => void;
+    upsertIndexedFile(record: AppDatabaseIndexedFile): Promise<void>;
+    getIndexedFile(path: string): Promise<AppDatabaseIndexedMetadataRow | undefined>;
+    listIndexedFileManifest(query?: AppDatabaseIndexedFileManifestQuery): Promise<AppDatabaseIndexedFileManifestPage>;
+    deleteIndexedFile(path: string): Promise<void>;
+    renameIndexedFile(oldPath: string, newPath: string): Promise<void>;
+    queryIndexedMetadata(query?: AppDatabaseIndexedMetadataQuery): Promise<AppDatabaseIndexedMetadataRow[]>;
+    queryIndexedMetadataPage(query?: AppDatabaseIndexedMetadataPageQuery): Promise<AppDatabaseIndexedMetadataPage>;
+    queryMetadataFacets(query: AppDatabaseMetadataFacetQuery): Promise<AppDatabaseMetadataFacetRow[]>;
+    queryMetadataLinks(query: AppDatabaseMetadataLinkQuery): Promise<AppDatabaseLinkRecord[]>;
+    upsertSearchDocument(document: SearchDocumentRecord): Promise<void>;
+    deleteSearchDocument(path: string): Promise<void>;
+    getSearchDocument(path: string): Promise<SearchDocumentRecord | undefined>;
+    listSearchDocumentManifest(query?: SearchDocumentManifestQuery): Promise<SearchDocumentManifestPage>;
+    listSearchDocuments(): Promise<SearchDocumentRecord[]>;
+    rebuildSearchIndex(): Promise<void>;
+    searchDocuments(query: string, options?: AppDatabaseSearchOptions): Promise<AppDatabaseSearchResult[]>;
+    searchDocumentPaths(query: string, options?: AppDatabaseSearchOptions): Promise<string[]>;
+    upsertTaskProjection(record: AppDatabaseTaskRecord): Promise<void>;
+    deleteTaskProjection(path: string): Promise<void>;
+    queryTasks(query?: AppDatabaseTaskQuery): Promise<AppDatabaseTaskRecord[]>;
+    getTaskRow(lookup: {
+        path?: string;
+        id?: string;
+    }): Promise<AppDatabaseTaskRecord | undefined>;
+    listChildLinks(query: AppDatabaseTaskChildQuery): Promise<AppDatabaseLinkRecord[]>;
+    listTaskDescendants(path: string): Promise<AppDatabaseTaskRecord[]>;
+    registerProjectionDefinition(definition: import("./index-projection").IndexProjectionDefinitionRecord): Promise<void>;
+    unregisterProjectionDefinition(projectionId: string): Promise<void>;
+    replaceProjectionSource(input: import("./index-projection").ReplaceProjectionSourceInput): Promise<void>;
+    markProjectionSourceError(input: import("./index-projection").MarkProjectionSourceErrorInput): Promise<void>;
+    deleteProjectionSource(projectionId: string, sourcePath: string, writerPluginId?: string): Promise<void>;
+    queryProjection<T = Record<string, unknown>>(projectionId: string, query?: import("./index-projection").IndexQuery, readerPluginId?: string): Promise<import("./index-projection").IndexQueryResult<T>>;
+    getProjectionRow<T = Record<string, unknown>>(projectionId: string, rowId: string, readerPluginId?: string): Promise<T | null>;
+    queryRelated<T = Record<string, unknown>>(query: import("./index-projection").IndexRelatedQuery, readerPluginId?: string): Promise<import("./index-projection").IndexQueryResult<T>>;
+    private invoke;
+    private ensureRpcChannel;
+    private invokeRemote;
+    private handleRemoteRequest;
+    private startOwnershipMonitor;
+    private promoteToOwner;
+    private openLocalDatabase;
+    private notifyCoordinationModeChange;
+    private acceptChange;
+}