@coasys/ad4m 0.13.0-test-5 → 0.13.0-test-7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,145 @@
1
+ /**
2
+ * PersistentCache — two-tier persistent key-value cache abstraction.
3
+ *
4
+ * Provides an IndexedDB-backed implementation for browsers and a no-op
5
+ * NullCache fallback for Node.js / environments without IndexedDB.
6
+ *
7
+ * Design goals:
8
+ * - Lazy open: IDB connection is deferred until first access
9
+ * - Fire-and-forget writes: put() resolves immediately (best-effort persistence)
10
+ * - Graceful degradation: all IDB errors resolve (never reject), so callers
11
+ * never need try/catch around cache operations
12
+ * - Tree-shakeable: import only what you need
13
+ */
14
+
15
+ // ── Interface ────────────────────────────────────────────────────────
16
+
17
+ export interface PersistentCache<T = unknown> {
18
+ get(key: string): Promise<T | undefined>;
19
+ put(key: string, value: T): Promise<void>;
20
+ delete(key: string): Promise<void>;
21
+ clear(): Promise<void>;
22
+ }
23
+
24
+ // ── IndexedDB Implementation ─────────────────────────────────────────
25
+
26
+ export class IDBCache<T = unknown> implements PersistentCache<T> {
27
+ #dbName: string;
28
+ #storeName: string;
29
+ #dbPromise: Promise<IDBDatabase> | null = null;
30
+ #version = 1;
31
+
32
+ constructor(dbName: string, storeName: string) {
33
+ this.#dbName = dbName;
34
+ this.#storeName = storeName;
35
+ }
36
+
37
+ #open(): Promise<IDBDatabase> {
38
+ if (!this.#dbPromise) {
39
+ this.#dbPromise = new Promise<IDBDatabase>((resolve, reject) => {
40
+ const storeName = this.#storeName;
41
+ const req = indexedDB.open(this.#dbName, this.#version);
42
+ req.onupgradeneeded = () => {
43
+ const db = req.result;
44
+ if (!db.objectStoreNames.contains(storeName)) {
45
+ db.createObjectStore(storeName);
46
+ }
47
+ };
48
+ req.onsuccess = () => resolve(req.result);
49
+ req.onerror = () => reject(req.error);
50
+ });
51
+ }
52
+ return this.#dbPromise;
53
+ }
54
+
55
+ async get(key: string): Promise<T | undefined> {
56
+ try {
57
+ const db = await this.#open();
58
+ return new Promise<T | undefined>((resolve) => {
59
+ const tx = db.transaction(this.#storeName, 'readonly');
60
+ const store = tx.objectStore(this.#storeName);
61
+ const req = store.get(key);
62
+ req.onsuccess = () => resolve(req.result ?? undefined);
63
+ req.onerror = () => resolve(undefined);
64
+ });
65
+ } catch {
66
+ return undefined;
67
+ }
68
+ }
69
+
70
+ async put(key: string, value: T): Promise<void> {
71
+ try {
72
+ const db = await this.#open();
73
+ return new Promise<void>((resolve) => {
74
+ const tx = db.transaction(this.#storeName, 'readwrite');
75
+ const store = tx.objectStore(this.#storeName);
76
+ store.put(value, key);
77
+ tx.oncomplete = () => resolve();
78
+ tx.onerror = () => resolve(); // fire-and-forget
79
+ });
80
+ } catch {
81
+ // degrade gracefully
82
+ }
83
+ }
84
+
85
+ async delete(key: string): Promise<void> {
86
+ try {
87
+ const db = await this.#open();
88
+ return new Promise<void>((resolve) => {
89
+ const tx = db.transaction(this.#storeName, 'readwrite');
90
+ const store = tx.objectStore(this.#storeName);
91
+ store.delete(key);
92
+ tx.oncomplete = () => resolve();
93
+ tx.onerror = () => resolve();
94
+ });
95
+ } catch {
96
+ // degrade gracefully
97
+ }
98
+ }
99
+
100
+ async clear(): Promise<void> {
101
+ try {
102
+ const db = await this.#open();
103
+ return new Promise<void>((resolve) => {
104
+ const tx = db.transaction(this.#storeName, 'readwrite');
105
+ const store = tx.objectStore(this.#storeName);
106
+ store.clear();
107
+ tx.oncomplete = () => resolve();
108
+ tx.onerror = () => resolve();
109
+ });
110
+ } catch {
111
+ // degrade gracefully
112
+ }
113
+ }
114
+ }
115
+
116
+ // ── NullCache (no-op fallback for Node.js) ───────────────────────────
117
+
118
+ export class NullCache<T = unknown> implements PersistentCache<T> {
119
+ async get(_key: string): Promise<T | undefined> { return undefined; }
120
+ async put(_key: string, _value: T): Promise<void> {}
121
+ async delete(_key: string): Promise<void> {}
122
+ async clear(): Promise<void> {}
123
+ }
124
+
125
+ // ── Factory ──────────────────────────────────────────────────────────
126
+
127
+ /**
128
+ * Create a PersistentCache backed by IndexedDB (browser) or NullCache (Node.js).
129
+ *
130
+ * @param dbName - IndexedDB database name
131
+ * @param storeName - IndexedDB object store name
132
+ */
133
+ export function createPersistentCache<T = unknown>(
134
+ dbName: string,
135
+ storeName: string,
136
+ ): PersistentCache<T> {
137
+ try {
138
+ if (typeof indexedDB !== 'undefined') {
139
+ return new IDBCache<T>(dbName, storeName);
140
+ }
141
+ } catch {
142
+ // indexedDB access threw (e.g. in a worker with restricted globals)
143
+ }
144
+ return new NullCache<T>();
145
+ }