@lapis-notes/api 0.1.0

package/dist/storage/vault-session.d.ts

@@ -0,0 +1,37 @@
+import { type AppDatabase, type AppDatabaseCapabilities, type AppDatabaseDescriptor, type AppDatabaseProvider, type RuntimeTarget } from "./app-database";
+import type { VaultAdapter } from "./fs";
+import { type VaultProfile } from "./vault-state";
+export type VaultSessionAppDatabaseStatus = "ready" | "blocked";
+/** @deprecated Read providerId, role, transport, and capabilities instead. */
+export type VaultSessionAppDatabaseMode = "turso-owner" | "turso-native" | "turso-proxy" | "turso-blocked" | "memory-test";
+export interface VaultSessionAppDatabaseState {
+    status: VaultSessionAppDatabaseStatus;
+    /** @deprecated Compatibility summary derived from the provider descriptor. */
+    mode: VaultSessionAppDatabaseMode;
+    providerId: string;
+    role: AppDatabaseDescriptor["role"];
+    transport: AppDatabaseDescriptor["transport"];
+    capabilities: AppDatabaseCapabilities;
+    lockSupported: boolean;
+    message?: string;
+    ownerId?: string;
+    heartbeatAt?: number;
+}
+export interface VaultSession {
+    runtime: RuntimeTarget;
+    profile?: VaultProfile;
+    vaultAdapter: VaultAdapter;
+    appDatabase?: AppDatabase;
+    appDatabaseState: VaultSessionAppDatabaseState;
+    awaitAppDatabase?: (options?: {
+        signal?: AbortSignal;
+    }) => Promise<VaultSession>;
+    close: () => Promise<void>;
+}
+export declare function createVaultSession(vaultAdapter: VaultAdapter, options?: Partial<{
+    runtime: RuntimeTarget;
+    profile: VaultProfile;
+    appDatabase: AppDatabase;
+    appDatabaseProvider: AppDatabaseProvider;
+}>): Promise<VaultSession>;
+export declare function getVaultSessionId(session: VaultSession): string;

package/dist/storage/vault-session.js

@@ -0,0 +1,196 @@
+import { EMPTY_APP_DATABASE_CAPABILITIES, MemoryAppDatabase, } from "./app-database";
+import { BrowserCoordinatedAppDatabase } from "./browser-coordinated-app-database";
+import { BrowserAppDatabaseCoordinator } from "./browser-app-database-coordination";
+import { TursoWasmAppDatabaseProvider, canUseTursoWasmDatabase, } from "./turso-app-database";
+import { getAdapterVaultId } from "./vault-state";
+function compatibilityMode(descriptor) {
+    if (descriptor.engine === "memory")
+        return "memory-test";
+    if (descriptor.role === "owner")
+        return "turso-owner";
+    if (descriptor.role === "proxy")
+        return "turso-proxy";
+    if (descriptor.transport === "native")
+        return "turso-native";
+    return "turso-owner";
+}
+function readyState(database, lockSupported, details = {}) {
+    const descriptor = database.descriptor;
+    return {
+        status: "ready",
+        mode: compatibilityMode(descriptor),
+        providerId: descriptor.providerId,
+        role: descriptor.role,
+        transport: descriptor.transport,
+        capabilities: descriptor.capabilities,
+        lockSupported,
+        ...details,
+    };
+}
+function blockedState(message, lockSupported, details = {}) {
+    return {
+        status: "blocked",
+        mode: "turso-blocked",
+        providerId: "turso-wasm-local",
+        role: "blocked",
+        transport: "wasm-worker",
+        capabilities: {
+            ...EMPTY_APP_DATABASE_CAPABILITIES,
+            localEmbeddings: true,
+            crossTabCoordination: lockSupported,
+        },
+        lockSupported,
+        message,
+        ...details,
+    };
+}
+function holdBrowserAppDatabaseOwnership(database, coordinator) {
+    const close = database.close.bind(database);
+    let released = false;
+    database.close = async () => {
+        try {
+            await close();
+        }
+        finally {
+            if (released)
+                return;
+            released = true;
+            coordinator.close();
+        }
+    };
+    return database;
+}
+async function openOwnedBrowserAppDatabase(vaultId, coordinator, provider) {
+    const database = new BrowserCoordinatedAppDatabase(vaultId, coordinator, true, provider);
+    await database.open();
+    return {
+        appDatabase: holdBrowserAppDatabaseOwnership(database, coordinator),
+        state: readyState(database, true, {
+            mode: "turso-owner",
+            role: "owner",
+            ownerId: coordinator.ownerId,
+            heartbeatAt: Date.now(),
+        }),
+        coordinator,
+        provider,
+    };
+}
+async function createBrowserAppDatabase(vaultId, provider) {
+    const lockSupported = BrowserAppDatabaseCoordinator.hasLockApi();
+    if (!canUseTursoWasmDatabase()) {
+        return {
+            state: blockedState("Turso requires OPFS and cross-origin isolation in this browser.", lockSupported),
+            provider,
+        };
+    }
+    if (!lockSupported) {
+        return {
+            state: blockedState("Turso requires the Web Locks API to protect this vault database.", false),
+            provider,
+        };
+    }
+    const coordinator = new BrowserAppDatabaseCoordinator(vaultId);
+    const acquired = await coordinator.tryAcquireOwnership();
+    if (acquired) {
+        return openOwnedBrowserAppDatabase(vaultId, coordinator, provider);
+    }
+    if (typeof BroadcastChannel === "undefined") {
+        return {
+            state: blockedState("App database already open in another tab.", true, {
+                ownerId: coordinator.observedOwnerId ?? undefined,
+                heartbeatAt: coordinator.observedHeartbeatAt ?? undefined,
+            }),
+            coordinator,
+            provider,
+        };
+    }
+    const database = new BrowserCoordinatedAppDatabase(vaultId, coordinator, false, provider);
+    await database.open();
+    return {
+        appDatabase: database,
+        state: readyState(database, true, {
+            mode: "turso-proxy",
+            role: "proxy",
+            message: "App database requests are being delegated to another tab.",
+            ownerId: coordinator.observedOwnerId ?? undefined,
+            heartbeatAt: coordinator.observedHeartbeatAt ?? undefined,
+        }),
+        coordinator,
+        provider,
+    };
+}
+async function createPreferredAppDatabase(vaultId, runtime, provider) {
+    if (runtime === "test") {
+        const database = provider
+            ? await provider.open({ vaultId, runtime, role: "test" })
+            : new MemoryAppDatabase(vaultId);
+        if (!provider)
+            await database.open();
+        return { appDatabase: database, state: readyState(database, false) };
+    }
+    if (runtime === "deno-desktop") {
+        const database = provider
+            ? await provider.open({ vaultId, runtime, role: "direct" })
+            : await new TursoWasmAppDatabaseProvider().open({
+                vaultId,
+                runtime,
+                role: "direct",
+            });
+        return { appDatabase: database, state: readyState(database, false) };
+    }
+    if (runtime === "web-pwa") {
+        return createBrowserAppDatabase(vaultId, provider ?? new TursoWasmAppDatabaseProvider());
+    }
+    throw new Error(`Unsupported application database runtime: ${runtime}`);
+}
+function createVaultSessionFactory(vaultAdapter, runtime, profile, vaultId) {
+    const createFromResolution = (resolution) => ({
+        runtime,
+        profile,
+        vaultAdapter,
+        appDatabase: resolution.appDatabase,
+        appDatabaseState: resolution.state,
+        awaitAppDatabase: resolution.state.status === "blocked" &&
+            resolution.coordinator &&
+            resolution.provider
+            ? async (awaitOptions = {}) => {
+                const acquired = await resolution.coordinator.waitForOwnership(awaitOptions);
+                if (!acquired) {
+                    return createFromResolution({
+                        ...resolution,
+                        state: {
+                            ...resolution.state,
+                            ownerId: resolution.coordinator?.observedOwnerId ?? undefined,
+                            heartbeatAt: resolution.coordinator?.observedHeartbeatAt ?? undefined,
+                        },
+                    });
+                }
+                return createFromResolution(await openOwnedBrowserAppDatabase(vaultId, resolution.coordinator, resolution.provider));
+            }
+            : undefined,
+        close: async () => {
+            await resolution.appDatabase?.close();
+            resolution.coordinator?.close();
+        },
+    });
+    return createFromResolution;
+}
+export async function createVaultSession(vaultAdapter, options = {}) {
+    const vaultId = getAdapterVaultId(vaultAdapter);
+    const runtime = options.runtime ?? "web-pwa";
+    const createFromResolution = createVaultSessionFactory(vaultAdapter, runtime, options.profile, vaultId);
+    if (options.appDatabase) {
+        await options.appDatabase.open();
+        return createFromResolution({
+            appDatabase: options.appDatabase,
+            state: readyState(options.appDatabase, false),
+        });
+    }
+    return createFromResolution(await createPreferredAppDatabase(vaultId, runtime, options.appDatabaseProvider));
+}
+export function getVaultSessionId(session) {
+    const adapter = session.vaultAdapter;
+    return (adapter.getVaultId?.() ??
+        session.appDatabase?.vaultId ??
+        session.vaultAdapter.getName());
+}

package/dist/storage/vault-state.d.ts

@@ -0,0 +1,74 @@
+import type { DataAdapter } from "./fs";
+import { type UseStore } from "./keyval";
+export type VaultStorageKind = "opfs" | "file-system-access" | "desktop-folder";
+export type BootstrapAppearanceMode = "dark" | "light" | "system";
+export interface VaultProfileDemoMetadata {
+    source: "e2e-vault";
+    fixtureVersion: string;
+}
+export interface VaultProfile {
+    id: string;
+    name: string;
+    kind: VaultStorageKind;
+    createdAt: number;
+    updatedAt: number;
+    handle?: unknown;
+    demo?: VaultProfileDemoMetadata;
+}
+export interface KeyValueStore {
+    get<T = unknown>(key: IDBValidKey): Promise<T | undefined>;
+    set(key: IDBValidKey, value: unknown): Promise<void>;
+    setMany(entries: [IDBValidKey, unknown][]): Promise<void>;
+    getMany<T = unknown>(keys: IDBValidKey[]): Promise<T[]>;
+    del(key: IDBValidKey): Promise<void>;
+    keys(): Promise<IDBValidKey[]>;
+}
+export declare class IndexedDbKeyValueStore implements KeyValueStore {
+    readonly dbName: string;
+    readonly storeName: string;
+    readonly store: UseStore;
+    constructor(dbName?: string, storeName?: string, store?: UseStore);
+    get<T = unknown>(key: IDBValidKey): Promise<T | undefined>;
+    set(key: IDBValidKey, value: unknown): Promise<void>;
+    setMany(entries: [IDBValidKey, unknown][]): Promise<void>;
+    getMany<T = unknown>(items: IDBValidKey[]): Promise<T[]>;
+    del(key: IDBValidKey): Promise<void>;
+    keys(): Promise<IDBValidKey[]>;
+}
+export declare class MemoryKeyValueStore implements KeyValueStore {
+    private values;
+    get<T = unknown>(key: IDBValidKey): Promise<T | undefined>;
+    set(key: IDBValidKey, value: unknown): Promise<void>;
+    setMany(entries: [IDBValidKey, unknown][]): Promise<void>;
+    getMany<T = unknown>(keys: IDBValidKey[]): Promise<T[]>;
+    del(key: IDBValidKey): Promise<void>;
+    keys(): Promise<IDBValidKey[]>;
+}
+export declare function getDefaultVaultStateStore(): KeyValueStore;
+export declare function setDefaultVaultStateStore(store: KeyValueStore | null): void;
+export declare class ScopedVaultStore {
+    readonly vaultId: string;
+    readonly namespace: string;
+    readonly store: KeyValueStore;
+    constructor(vaultId: string, namespace: string, store?: KeyValueStore);
+    private key;
+    get<T = unknown>(key: IDBValidKey): Promise<T | undefined>;
+    set(key: IDBValidKey, value: unknown): Promise<void>;
+    setMany(entries: [IDBValidKey, unknown][]): Promise<void>;
+    getMany<T = unknown>(items: IDBValidKey[]): Promise<T[]>;
+    del(key: IDBValidKey): Promise<void>;
+    keys(): Promise<string[]>;
+}
+export declare function getAdapterVaultId(adapter: DataAdapter): string;
+export declare function saveVaultProfile(profile: VaultProfile, store?: KeyValueStore): Promise<void>;
+export declare function replaceVaultProfile(previousId: string, profile: VaultProfile, store?: KeyValueStore): Promise<void>;
+export declare function deleteVaultProfile(id: string, store?: KeyValueStore): Promise<void>;
+export declare function clearVaultScopedState(vaultId: string, store?: KeyValueStore): Promise<void>;
+export declare function getVaultProfile(id: string, store?: KeyValueStore): Promise<VaultProfile | undefined>;
+export declare function getCurrentVaultProfile(store?: KeyValueStore): Promise<VaultProfile | undefined>;
+export declare function clearCurrentVaultProfile(store?: KeyValueStore): Promise<void>;
+export declare function listVaultProfiles(store?: KeyValueStore): Promise<VaultProfile[]>;
+export declare function getBootstrapAppearanceMode(store?: KeyValueStore): Promise<BootstrapAppearanceMode>;
+export declare function saveBootstrapAppearanceMode(mode: BootstrapAppearanceMode, store?: KeyValueStore): Promise<void>;
+export type BrowserVaultIdPrefix = "opfs";
+export declare function generateBrowserVaultId(prefix: BrowserVaultIdPrefix, name: string): string;

package/dist/storage/vault-state.js

@@ -0,0 +1,181 @@
+import { createStore, del, get, getMany, keys, set, setMany, } from "./keyval";
+export class IndexedDbKeyValueStore {
+    dbName;
+    storeName;
+    store;
+    constructor(dbName = "lapis-notes-vault-state", storeName = "state", store = createStore(dbName, storeName)) {
+        this.dbName = dbName;
+        this.storeName = storeName;
+        this.store = store;
+    }
+    get(key) {
+        return get(key, this.store);
+    }
+    set(key, value) {
+        return set(key, value, this.store);
+    }
+    setMany(entries) {
+        return setMany(entries, this.store);
+    }
+    getMany(items) {
+        return getMany(items, this.store);
+    }
+    del(key) {
+        return del(key, this.store);
+    }
+    keys() {
+        return keys(this.store);
+    }
+}
+export class MemoryKeyValueStore {
+    values = new Map();
+    async get(key) {
+        return this.values.get(key);
+    }
+    async set(key, value) {
+        this.values.set(key, value);
+    }
+    async setMany(entries) {
+        entries.forEach(([key, value]) => this.values.set(key, value));
+    }
+    async getMany(keys) {
+        return keys.map((key) => this.values.get(key));
+    }
+    async del(key) {
+        this.values.delete(key);
+    }
+    async keys() {
+        return [...this.values.keys()];
+    }
+}
+let defaultStore = null;
+export function getDefaultVaultStateStore() {
+    defaultStore ||= new IndexedDbKeyValueStore();
+    return defaultStore;
+}
+export function setDefaultVaultStateStore(store) {
+    defaultStore = store;
+}
+export class ScopedVaultStore {
+    vaultId;
+    namespace;
+    store;
+    constructor(vaultId, namespace, store = getDefaultVaultStateStore()) {
+        this.vaultId = vaultId;
+        this.namespace = namespace;
+        this.store = store;
+    }
+    key(key) {
+        return `vault:${this.vaultId}:${this.namespace}:${String(key)}`;
+    }
+    get(key) {
+        return this.store.get(this.key(key));
+    }
+    set(key, value) {
+        return this.store.set(this.key(key), value);
+    }
+    setMany(entries) {
+        return this.store.setMany(entries.map(([key, value]) => [this.key(key), value]));
+    }
+    getMany(items) {
+        return this.store.getMany(items.map((key) => this.key(key)));
+    }
+    del(key) {
+        return this.store.del(this.key(key));
+    }
+    async keys() {
+        const prefix = this.key("");
+        return (await this.store.keys())
+            .map(String)
+            .filter((key) => key.startsWith(prefix))
+            .map((key) => key.slice(prefix.length));
+    }
+}
+export function getAdapterVaultId(adapter) {
+    const candidate = adapter;
+    return candidate.getVaultId?.() ?? `adapter:${adapter.getName()}`;
+}
+const CURRENT_PROFILE_KEY = "profile:current";
+const PROFILE_PREFIX = "profile:";
+const BOOTSTRAP_APPEARANCE_MODE_KEY = "bootstrap:appearance:baseColorSchema";
+function profileKey(id) {
+    return `${PROFILE_PREFIX}${id}`;
+}
+function isBootstrapAppearanceMode(value) {
+    return value === "dark" || value === "light" || value === "system";
+}
+export async function saveVaultProfile(profile, store = getDefaultVaultStateStore()) {
+    await store.setMany([
+        [profileKey(profile.id), profile],
+        [CURRENT_PROFILE_KEY, profile.id],
+    ]);
+}
+export async function replaceVaultProfile(previousId, profile, store = getDefaultVaultStateStore()) {
+    const currentId = await store.get(CURRENT_PROFILE_KEY);
+    if (previousId !== profile.id) {
+        await store.del(profileKey(previousId));
+    }
+    await store.set(profileKey(profile.id), profile);
+    if (currentId === previousId || currentId === profile.id) {
+        await store.set(CURRENT_PROFILE_KEY, profile.id);
+    }
+}
+export async function deleteVaultProfile(id, store = getDefaultVaultStateStore()) {
+    const currentId = await store.get(CURRENT_PROFILE_KEY);
+    await store.del(profileKey(id));
+    if (currentId === id) {
+        await store.del(CURRENT_PROFILE_KEY);
+    }
+}
+export async function clearVaultScopedState(vaultId, store = getDefaultVaultStateStore()) {
+    const prefix = `vault:${vaultId}:`;
+    const keysToDelete = (await store.keys())
+        .map(String)
+        .filter((key) => key.startsWith(prefix));
+    await Promise.all(keysToDelete.map((key) => store.del(key)));
+}
+export async function getVaultProfile(id, store = getDefaultVaultStateStore()) {
+    return store.get(profileKey(id));
+}
+export async function getCurrentVaultProfile(store = getDefaultVaultStateStore()) {
+    const id = await store.get(CURRENT_PROFILE_KEY);
+    return id ? getVaultProfile(id, store) : undefined;
+}
+export async function clearCurrentVaultProfile(store = getDefaultVaultStateStore()) {
+    await store.del(CURRENT_PROFILE_KEY);
+}
+export async function listVaultProfiles(store = getDefaultVaultStateStore()) {
+    const profileKeys = (await store.keys())
+        .map(String)
+        .filter((key) => key.startsWith(PROFILE_PREFIX) && key !== CURRENT_PROFILE_KEY);
+    return (await store.getMany(profileKeys))
+        .filter(Boolean)
+        .sort((left, right) => {
+        const updatedDelta = (right.updatedAt ?? 0) - (left.updatedAt ?? 0);
+        if (updatedDelta !== 0) {
+            return updatedDelta;
+        }
+        const createdDelta = (right.createdAt ?? 0) - (left.createdAt ?? 0);
+        if (createdDelta !== 0) {
+            return createdDelta;
+        }
+        return left.name.localeCompare(right.name);
+    });
+}
+export async function getBootstrapAppearanceMode(store = getDefaultVaultStateStore()) {
+    const stored = await store.get(BOOTSTRAP_APPEARANCE_MODE_KEY);
+    return isBootstrapAppearanceMode(stored) ? stored : "system";
+}
+export async function saveBootstrapAppearanceMode(mode, store = getDefaultVaultStateStore()) {
+    await store.set(BOOTSTRAP_APPEARANCE_MODE_KEY, mode);
+}
+export function generateBrowserVaultId(prefix, name) {
+    const slug = name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 32) || "vault";
+    const suffix = Math.random().toString(36).slice(2, 6);
+    return `${prefix}-${slug}-${suffix}`;
+}