@abraca/dabra 0.5.0 → 0.7.0

package/src/AbracadabraClient.ts

@@ -6,7 +6,9 @@ import type {
 	PublicKeyInfo,
 	PermissionEntry,
 	HealthStatus,
+	ServerInfo,
 } from "./types.ts";
+import type { DocumentCache } from "./DocumentCache.ts";
 
 export interface AbracadabraClientConfig {
 	/** Server base URL (http or https). WebSocket URL is derived automatically. */
@@ -19,6 +21,13 @@ export interface AbracadabraClientConfig {
 	storageKey?: string;
 	/** Custom fetch implementation (useful for Node.js or testing). */
 	fetch?: typeof globalThis.fetch;
+	/**
+	 * Optional metadata cache. When provided, read methods (getDoc, listChildren,
+	 * getMe, listPermissions, listUploads) check the cache before hitting the
+	 * network. Write methods (deleteDoc, upload, deleteUpload) invalidate affected
+	 * cache entries automatically.
+	 */
+	cache?: DocumentCache;
 }
 
 export class AbracadabraClient {
@@ -27,12 +36,14 @@ export class AbracadabraClient {
 	private readonly persistAuth: boolean;
 	private readonly storageKey: string;
 	private readonly _fetch: typeof globalThis.fetch;
+	readonly cache: DocumentCache | null;
 
 	constructor(config: AbracadabraClientConfig) {
 		this.baseUrl = config.url.replace(/\/+$/, "");
 		this.persistAuth = config.persistAuth ?? typeof localStorage !== "undefined";
 		this.storageKey = config.storageKey ?? "abracadabra:auth";
 		this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
+		this.cache = config.cache ?? null;
 
 		// Load token: explicit > persisted > null
 		this._token = config.token ?? this.loadPersistedToken() ?? null;
@@ -175,7 +186,15 @@ export class AbracadabraClient {
 
 	/** Get the current user's profile. */
 	async getMe(): Promise<UserProfile> {
-		return this.request<UserProfile>("GET", "/users/me");
+		if (this.cache) {
+			const cached = await this.cache.getCurrentProfile();
+			if (cached) return cached;
+		}
+		const profile = await this.request<UserProfile>("GET", "/users/me");
+		if (this.cache) {
+			await this.cache.setCurrentProfile(profile).catch(() => null);
+		}
+		return profile;
 	}
 
 	/** Update the current user's display name. */
@@ -192,20 +211,38 @@ export class AbracadabraClient {
 
 	/** Get document metadata. */
 	async getDoc(docId: string): Promise<DocumentMeta> {
-		return this.request<DocumentMeta>("GET", `/docs/${encodeURIComponent(docId)}`);
+		if (this.cache) {
+			const cached = await this.cache.getDoc(docId);
+			if (cached) return cached;
+		}
+		const meta = await this.request<DocumentMeta>("GET", `/docs/${encodeURIComponent(docId)}`);
+		if (this.cache) {
+			await this.cache.setDoc(meta).catch(() => null);
+		}
+		return meta;
 	}
 
 	/** Delete a document (requires Owner role). Cascades to children and uploads. */
 	async deleteDoc(docId: string): Promise<void> {
 		await this.request("DELETE", `/docs/${encodeURIComponent(docId)}`);
+		if (this.cache) {
+			await this.cache.invalidateDoc(docId).catch(() => null);
+		}
 	}
 
 	/** List immediate child documents. */
 	async listChildren(docId: string): Promise<string[]> {
+		if (this.cache) {
+			const cached = await this.cache.getChildren(docId);
+			if (cached) return cached;
+		}
 		const res = await this.request<{ children: string[] }>(
 			"GET",
 			`/docs/${encodeURIComponent(docId)}/children`,
 		);
+		if (this.cache) {
+			await this.cache.setChildren(docId, res.children).catch(() => null);
+		}
 		return res.children;
 	}
 
@@ -222,10 +259,17 @@ export class AbracadabraClient {
 
 	/** List all permissions for a document (requires read access). */
 	async listPermissions(docId: string): Promise<PermissionEntry[]> {
+		if (this.cache) {
+			const cached = await this.cache.getPermissions(docId);
+			if (cached) return cached;
+		}
 		const res = await this.request<{ permissions: PermissionEntry[] }>(
 			"GET",
 			`/docs/${encodeURIComponent(docId)}/permissions`,
 		);
+		if (this.cache) {
+			await this.cache.setPermissions(docId, res.permissions).catch(() => null);
+		}
 		return res.permissions;
 	}
 
@@ -273,15 +317,26 @@ export class AbracadabraClient {
 		if (!res.ok) {
 			throw await this.toError(res);
 		}
-		return res.json() as Promise<UploadMeta>;
+		const meta = await res.json() as UploadMeta;
+		if (this.cache) {
+			await this.cache.invalidateUploads(docId).catch(() => null);
+		}
+		return meta;
 	}
 
 	/** List all uploads for a document. */
 	async listUploads(docId: string): Promise<UploadInfo[]> {
+		if (this.cache) {
+			const cached = await this.cache.getUploads(docId);
+			if (cached) return cached;
+		}
 		const res = await this.request<{ uploads: UploadInfo[] }>(
 			"GET",
 			`/docs/${encodeURIComponent(docId)}/uploads`,
 		);
+		if (this.cache) {
+			await this.cache.setUploads(docId, res.uploads).catch(() => null);
+		}
 		return res.uploads;
 	}
 
@@ -308,6 +363,9 @@ export class AbracadabraClient {
 			"DELETE",
 			`/docs/${encodeURIComponent(docId)}/uploads/${encodeURIComponent(uploadId)}`,
 		);
+		if (this.cache) {
+			await this.cache.invalidateUploads(docId).catch(() => null);
+		}
 	}
 
 	// ── System ───────────────────────────────────────────────────────────────
@@ -317,6 +375,14 @@ export class AbracadabraClient {
 		return this.request<HealthStatus>("GET", "/health", { auth: false });
 	}
 
+	/**
+	 * Fetch server metadata including the optional `index_doc_id` entry point.
+	 * No auth required.
+	 */
+	async serverInfo(): Promise<ServerInfo> {
+		return this.request<ServerInfo>("GET", "/info", { auth: false });
+	}
+
 	// ── Internals ────────────────────────────────────────────────────────────
 
 	private async request<T = void>(

package/src/AbracadabraProvider.ts

@@ -1,7 +1,7 @@
 import * as Y from "yjs";
-import { HocuspocusProvider } from "./HocuspocusProvider.ts";
-import type { HocuspocusProviderConfiguration } from "./HocuspocusProvider.ts";
-import type { HocuspocusProviderWebsocket } from "./HocuspocusProviderWebsocket.ts";
+import { AbracadabraBaseProvider } from "./AbracadabraBaseProvider.ts";
+import type { AbracadabraBaseProviderConfiguration } from "./AbracadabraBaseProvider.ts";
+import type { AbracadabraWS } from "./AbracadabraWS.ts";
 import { OfflineStore } from "./OfflineStore.ts";
 import { SubdocMessage } from "./OutgoingMessages/SubdocMessage.ts";
 import { UpdateMessage } from "./OutgoingMessages/UpdateMessage.ts";
@@ -15,7 +15,7 @@ import { AuthenticationMessage } from "./OutgoingMessages/AuthenticationMessage.
 import type { AbracadabraClient } from "./AbracadabraClient.ts";
 
 export interface AbracadabraProviderConfiguration
-	extends Omit<HocuspocusProviderConfiguration, "url" | "websocketProvider"> {
+	extends Omit<AbracadabraBaseProviderConfiguration, "url" | "websocketProvider"> {
 	/**
 	 * Subdocument loading strategy.
 	 * - "lazy"  (default) – child providers are created only when explicitly requested.
@@ -58,7 +58,7 @@ export interface AbracadabraProviderConfiguration
 	url?: string;
 
 	/** Shared WebSocket connection (use when multiplexing multiple root documents). */
-	websocketProvider?: HocuspocusProviderWebsocket;
+	websocketProvider?: AbracadabraWS;
 }
 
 /** Validate that a string is a UUID acceptable by the server's DocId parser. */
@@ -67,7 +67,7 @@ function isValidDocId(id: string): boolean {
 }
 
 /**
- * AbracadabraProvider extends HocuspocusProvider with:
+ * AbracadabraProvider extends AbracadabraBaseProvider with:
  *
  *  1. Subdocument lifecycle – intercepts Y.Doc subdoc events and syncs them
  *     with the server via MSG_SUBDOC (4) frames.  Child documents get their
@@ -87,7 +87,7 @@ function isValidDocId(id: string): boolean {
  *     can gate write operations without a network round-trip.  Role is
  *     refreshed from the server on every reconnect.
  */
-export class AbracadabraProvider extends HocuspocusProvider {
+export class AbracadabraProvider extends AbracadabraBaseProvider {
 	public effectiveRole: EffectiveRole = null;
 
 	private _client: AbracadabraClient | null;
@@ -110,7 +110,7 @@ export class AbracadabraProvider extends HocuspocusProvider {
 
 	constructor(configuration: AbracadabraProviderConfiguration) {
 		// Derive URL and token from client when not explicitly set.
-		const resolved = { ...configuration } as HocuspocusProviderConfiguration;
+		const resolved = { ...configuration } as AbracadabraBaseProviderConfiguration;
 		const client = configuration.client ?? null;
 
 		if (client) {
@@ -165,7 +165,7 @@ export class AbracadabraProvider extends HocuspocusProvider {
 		try {
 			const url =
 				config.url ??
-				(config.websocketProvider as HocuspocusProviderWebsocket | undefined)?.url ??
+				(config.websocketProvider as AbracadabraWS | undefined)?.url ??
 				client?.wsUrl;
 			if (url) return new URL(url).hostname;
 		} catch {
@@ -188,12 +188,16 @@ export class AbracadabraProvider extends HocuspocusProvider {
 	private async _initFromOfflineStore(): Promise<void> {
 		if (!this.offlineStore) return;
 
-		const snapshot = await this.offlineStore.getDocSnapshot().catch(() => null);
+		// Fetch snapshot and pending updates in parallel — each call opens the
+		// IDB database, so running them concurrently roughly halves the latency.
+		const [snapshot, pending] = await Promise.all([
+			this.offlineStore.getDocSnapshot().catch(() => null),
+			this.offlineStore.getPendingUpdates().catch(() => []),
+		]);
+
 		if (snapshot) {
 			Y.applyUpdate(this.document, snapshot, this.offlineStore);
 		}
-
-		const pending = await this.offlineStore.getPendingUpdates().catch(() => []);
 		for (const update of pending) {
 			Y.applyUpdate(this.document, update, this.offlineStore);
 		}
@@ -425,7 +429,7 @@ export class AbracadabraProvider extends HocuspocusProvider {
 		this.registerSubdoc(childDoc);
 
 		// Each child gets its own WebSocket connection.  Omitting
-		// websocketProvider lets HocuspocusProvider create one automatically
+		// websocketProvider lets AbracadabraBaseProvider create one automatically
 		// (manageSocket = true), so we do NOT call attach() manually.
 		const childProvider = new AbracadabraProvider({
 			name: childId,
@@ -523,7 +527,7 @@ export class AbracadabraProvider extends HocuspocusProvider {
 
 	get isConnected(): boolean {
 		return (
-			(this.configuration.websocketProvider as HocuspocusProviderWebsocket)
+			(this.configuration.websocketProvider as AbracadabraWS)
 				.status === "connected"
 		);
 	}

package/src/{HocuspocusProviderWebsocket.ts → AbracadabraWS.ts}

@@ -1,9 +1,9 @@
-import { WsReadyStates } from "@abraca/dabra-common";
+import { WsReadyStates } from "./types.ts";
 import { retry } from "@lifeomic/attempt";
 import * as time from "lib0/time";
 import type { Event, MessageEvent } from "ws";
 import EventEmitter from "./EventEmitter.ts";
-import type { HocuspocusProvider } from "./HocuspocusProvider.ts";
+import type { AbracadabraBaseProvider } from "./AbracadabraBaseProvider.ts";
 import { IncomingMessage } from "./IncomingMessage.ts";
 import { CloseMessage } from "./OutgoingMessages/CloseMessage.ts";
 import {
@@ -18,15 +18,21 @@ import {
   type onStatusParameters,
 } from "./types.ts";
 
-export type HocuspocusWebSocket = WebSocket & { identifier: string };
-export type HocusPocusWebSocket = HocuspocusWebSocket;
+export type AbracadabraWebSocketConn = WebSocket & { identifier: string };
+/** @deprecated Use AbracadabraWebSocketConn */
+export type HocuspocusWebSocket = AbracadabraWebSocketConn;
+/** @deprecated Use AbracadabraWebSocketConn */
+export type HocusPocusWebSocket = AbracadabraWebSocketConn;
 
-export type HocuspocusProviderWebsocketConfiguration = Required<
-  Pick<CompleteHocuspocusProviderWebsocketConfiguration, "url">
+export type AbracadabraWSConfiguration = Required<
+  Pick<CompleteAbracadabraWSConfiguration, "url">
 > &
-  Partial<CompleteHocuspocusProviderWebsocketConfiguration>;
+  Partial<CompleteAbracadabraWSConfiguration>;
 
-export interface CompleteHocuspocusProviderWebsocketConfiguration {
+/** @deprecated Use AbracadabraWSConfiguration */
+export type HocuspocusProviderWebsocketConfiguration = AbracadabraWSConfiguration;
+
+export interface CompleteAbracadabraWSConfiguration {
   /**
    * Whether to connect automatically when creating the provider instance. Default=true
    */
@@ -99,13 +105,16 @@ export interface CompleteHocuspocusProviderWebsocketConfiguration {
   /**
    * Map of attached providers keyed by documentName.
    */
-  providerMap: Map<string, HocuspocusProvider>;
+  providerMap: Map<string, AbracadabraBaseProvider>;
 }
 
-export class HocuspocusProviderWebsocket extends EventEmitter {
+/** @deprecated Use CompleteAbracadabraWSConfiguration */
+export type CompleteHocuspocusProviderWebsocketConfiguration = CompleteAbracadabraWSConfiguration;
+
+export class AbracadabraWS extends EventEmitter {
   private messageQueue: any[] = [];
 
-  public configuration: CompleteHocuspocusProviderWebsocketConfiguration = {
+  public configuration: CompleteAbracadabraWSConfiguration = {
     url: "",
     autoConnect: true,
     preserveTrailingSlash: false,
@@ -144,7 +153,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
     providerMap: new Map(),
   };
 
-  webSocket: HocusPocusWebSocket | null = null;
+  webSocket: AbracadabraWebSocketConn | null = null;
 
   webSocketHandlers: { [key: string]: any } = {};
 
@@ -165,7 +174,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
     reject: (reason?: any) => void;
   } | null = null;
 
-  constructor(configuration: HocuspocusProviderWebsocketConfiguration) {
+  constructor(configuration: AbracadabraWSConfiguration) {
     super();
     this.setConfiguration(configuration);
 
@@ -208,7 +217,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
     this.receivedOnOpenPayload = event;
   }
 
-  attach(provider: HocuspocusProvider) {
+  attach(provider: AbracadabraBaseProvider) {
     this.configuration.providerMap.set(provider.configuration.name, provider);
 
     if (this.status === WebSocketStatus.Disconnected && this.shouldConnect) {
@@ -220,7 +229,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
     }
   }
 
-  detach(provider: HocuspocusProvider) {
+  detach(provider: AbracadabraBaseProvider) {
     if (this.configuration.providerMap.has(provider.configuration.name)) {
       provider.send(CloseMessage, {
         documentName: provider.configuration.name,
@@ -230,7 +239,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
   }
 
   public setConfiguration(
-    configuration: Partial<HocuspocusProviderWebsocketConfiguration> = {},
+    configuration: Partial<AbracadabraWSConfiguration> = {},
   ): void {
     this.configuration = { ...this.configuration, ...configuration };
 
@@ -274,7 +283,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
           }
         },
       }).catch((error: any) => {
-        // If we aborted the connection attempt then don’t throw an error
+        // If we aborted the connection attempt then don't throw an error
         // ref: https://github.com/lifeomic/attempt/blob/master/src/index.ts#L136
         if (error && error.code !== "ATTEMPT_ABORTED") {
           throw error;
@@ -296,7 +305,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
   }
 
   // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-  attachWebSocketListeners(ws: HocusPocusWebSocket, reject: Function) {
+  attachWebSocketListeners(ws: AbracadabraWebSocketConn, reject: Function) {
     const { identifier } = ws;
     const onMessageHandler = (payload: any) => this.emit("message", payload);
     const onCloseHandler = (payload: any) => this.emit("close", { event: payload });
@@ -410,17 +419,17 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
   closeTries = 0;
 
   checkConnection() {
-    // Don’t check the connection when it’s not even established
+    // Don't check the connection when it's not even established
     if (this.status !== WebSocketStatus.Connected) {
       return;
     }
 
-    // Don’t close the connection while waiting for the first message
+    // Don't close the connection while waiting for the first message
     if (!this.lastMessageReceived) {
       return;
     }
 
-    // Don’t close the connection when a message was received recently
+    // Don't close the connection when a message was received recently
     if (
       this.configuration.messageReconnectTimeout >=
       time.getUnixTime() - this.lastMessageReceived
@@ -497,7 +506,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
       this.rejectConnectionAttempt();
     }
 
-    // Let’s update the connection status.
+    // Let's update the connection status.
     this.status = WebSocketStatus.Disconnected;
     this.emit("status", { status: WebSocketStatus.Disconnected });
 
@@ -535,3 +544,8 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
     this.cleanupWebSocket();
   }
 }
+
+/** @deprecated Use AbracadabraWS */
+export const HocuspocusProviderWebsocket = AbracadabraWS;
+/** @deprecated Use AbracadabraWS */
+export type HocuspocusProviderWebsocket = AbracadabraWS;

package/src/CloseEvents.ts

@@ -0,0 +1,49 @@
+export interface CloseEvent {
+	code: number;
+	reason: string;
+}
+
+/**
+ * The server is terminating the connection because a data frame was received
+ * that is too large.
+ * See: https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/code
+ */
+export const MessageTooBig: CloseEvent = {
+	code: 1009,
+	reason: "Message Too Big",
+};
+
+/**
+ * The server successfully processed the request, asks that the requester reset
+ * its document view, and is not returning any content.
+ */
+export const ResetConnection: CloseEvent = {
+	code: 4205,
+	reason: "Reset Connection",
+};
+
+/**
+ * Similar to Forbidden, but specifically for use when authentication is required and has
+ * failed or has not yet been provided.
+ */
+export const Unauthorized: CloseEvent = {
+	code: 4401,
+	reason: "Unauthorized",
+};
+
+/**
+ * The request contained valid data and was understood by the server, but the server
+ * is refusing action.
+ */
+export const Forbidden: CloseEvent = {
+	code: 4403,
+	reason: "Forbidden",
+};
+
+/**
+ * The server timed out waiting for the request.
+ */
+export const ConnectionTimeout: CloseEvent = {
+	code: 4408,
+	reason: "Connection Timeout",
+};

package/src/DocumentCache.ts

@@ -0,0 +1,210 @@
+/**
+ * IndexedDB-backed cache for REST API metadata (documents, children, profiles,
+ * permissions, uploads). Provides offline-first read access to data fetched
+ * from the server.
+ *
+ * Each entry carries a `cachedAt` timestamp; reads return null once the TTL
+ * has elapsed. The cache is scoped by server origin so the same app can work
+ * against multiple backends without cross-contamination.
+ *
+ * Designed to be passed to AbracadabraClientConfig.cache so the client
+ * automatically checks the cache before hitting the network.
+ */
+
+import type {
+	DocumentMeta,
+	UserProfile,
+	PermissionEntry,
+	UploadInfo,
+} from "./types.ts";
+
+const DB_VERSION = 1;
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+function idbAvailable(): boolean {
+	return typeof globalThis !== "undefined" && "indexedDB" in globalThis;
+}
+
+function openDb(origin: string): Promise<IDBDatabase> {
+	return new Promise((resolve, reject) => {
+		const req = globalThis.indexedDB.open(
+			`abracadabra:meta-cache:${origin}`,
+			DB_VERSION,
+		);
+
+		req.onupgradeneeded = (event) => {
+			const db = (event.target as IDBOpenDBRequest).result;
+			for (const name of ["doc_meta", "children", "user_profile", "permissions", "uploads"]) {
+				if (!db.objectStoreNames.contains(name)) {
+					db.createObjectStore(name);
+				}
+			}
+		};
+
+		req.onsuccess = () => resolve(req.result);
+		req.onerror = () => reject(req.error);
+	});
+}
+
+function txPromise<T>(store: IDBObjectStore, request: IDBRequest<T>): Promise<T> {
+	return new Promise((resolve, reject) => {
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = () => reject(request.error);
+	});
+}
+
+export interface DocumentCacheOptions {
+	/** How long cached entries remain valid. Default: 5 minutes. */
+	ttlMs?: number;
+}
+
+export class DocumentCache {
+	private readonly origin: string;
+	private readonly ttlMs: number;
+	private dbPromise: Promise<IDBDatabase | null> | null = null;
+	private db: IDBDatabase | null = null;
+
+	constructor(serverOrigin: string, opts?: DocumentCacheOptions) {
+		this.origin = serverOrigin;
+		this.ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
+	}
+
+	private getDb(): Promise<IDBDatabase | null> {
+		if (!idbAvailable()) return Promise.resolve(null);
+		if (!this.dbPromise) {
+			this.dbPromise = openDb(this.origin)
+				.catch(() => null)
+				.then((db) => {
+					this.db = db;
+					return db;
+				});
+		}
+		return this.dbPromise;
+	}
+
+	private isExpired(cachedAt: number): boolean {
+		return Date.now() - cachedAt > this.ttlMs;
+	}
+
+	// ── Generic TTL helpers ───────────────────────────────────────────────────
+
+	private async getWithTtl<T>(
+		storeName: string,
+		key: string,
+	): Promise<T | null> {
+		const db = await this.getDb();
+		if (!db) return null;
+		const tx = db.transaction(storeName, "readonly");
+		const result = await txPromise<{ value: T; cachedAt: number } | undefined>(
+			tx.objectStore(storeName),
+			tx.objectStore(storeName).get(key),
+		);
+		if (!result) return null;
+		if (this.isExpired(result.cachedAt)) {
+			// Stale — evict asynchronously and signal miss
+			this.deleteKey(storeName, key).catch(() => null);
+			return null;
+		}
+		return result.value;
+	}
+
+	private async setWithTtl<T>(storeName: string, key: string, value: T): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+		const entry = { value, cachedAt: Date.now() };
+		const tx = db.transaction(storeName, "readwrite");
+		await txPromise(
+			tx.objectStore(storeName),
+			tx.objectStore(storeName).put(entry, key),
+		);
+	}
+
+	private async deleteKey(storeName: string, key: string): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+		const tx = db.transaction(storeName, "readwrite");
+		await txPromise(tx.objectStore(storeName), tx.objectStore(storeName).delete(key));
+	}
+
+	// ── Document metadata ─────────────────────────────────────────────────────
+
+	async getDoc(docId: string): Promise<DocumentMeta | null> {
+		return this.getWithTtl<DocumentMeta>("doc_meta", docId);
+	}
+
+	async setDoc(meta: DocumentMeta): Promise<void> {
+		return this.setWithTtl("doc_meta", meta.id, meta);
+	}
+
+	async invalidateDoc(docId: string): Promise<void> {
+		await this.deleteKey("doc_meta", docId).catch(() => null);
+	}
+
+	// ── Children list ─────────────────────────────────────────────────────────
+
+	async getChildren(parentId: string): Promise<string[] | null> {
+		return this.getWithTtl<string[]>("children", parentId);
+	}
+
+	async setChildren(parentId: string, items: string[]): Promise<void> {
+		return this.setWithTtl("children", parentId, items);
+	}
+
+	async invalidateChildren(parentId: string): Promise<void> {
+		await this.deleteKey("children", parentId).catch(() => null);
+	}
+
+	// ── User profile ──────────────────────────────────────────────────────────
+
+	async getProfile(userId: string): Promise<UserProfile | null> {
+		return this.getWithTtl<UserProfile>("user_profile", userId);
+	}
+
+	async setProfile(profile: UserProfile): Promise<void> {
+		return this.setWithTtl("user_profile", profile.id, profile);
+	}
+
+	/** Get the cached profile for the currently authenticated user. */
+	async getCurrentProfile(): Promise<UserProfile | null> {
+		return this.getWithTtl<UserProfile>("user_profile", "__current__");
+	}
+
+	/** Cache a profile both by its ID and as the current user. */
+	async setCurrentProfile(profile: UserProfile): Promise<void> {
+		await Promise.all([
+			this.setWithTtl("user_profile", profile.id, profile),
+			this.setWithTtl("user_profile", "__current__", profile),
+		]);
+	}
+
+	// ── Permissions ───────────────────────────────────────────────────────────
+
+	async getPermissions(docId: string): Promise<PermissionEntry[] | null> {
+		return this.getWithTtl<PermissionEntry[]>("permissions", docId);
+	}
+
+	async setPermissions(docId: string, items: PermissionEntry[]): Promise<void> {
+		return this.setWithTtl("permissions", docId, items);
+	}
+
+	// ── Uploads list ──────────────────────────────────────────────────────────
+
+	async getUploads(docId: string): Promise<UploadInfo[] | null> {
+		return this.getWithTtl<UploadInfo[]>("uploads", docId);
+	}
+
+	async setUploads(docId: string, items: UploadInfo[]): Promise<void> {
+		return this.setWithTtl("uploads", docId, items);
+	}
+
+	async invalidateUploads(docId: string): Promise<void> {
+		await this.deleteKey("uploads", docId).catch(() => null);
+	}
+
+	// ── Lifecycle ─────────────────────────────────────────────────────────────
+
+	destroy(): void {
+		this.db?.close();
+		this.db = null;
+	}
+}