local-lite 2.0.5 → 2.0.6

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.
package/README.md CHANGED
@@ -101,7 +101,7 @@ The package ships [Agent Skills](./skills) that AI coding assistants can load:
101
101
  * `local-lite-backups`: Cloud backups (OneDrive, Google Drive), AES-256-GCM database encryption, and restore.
102
102
  * `local-lite-schema`: Declarative cascading deletions (`onDelete`), append-only migrations, and FTS5 search.
103
103
  * `local-lite-storage`: Blob and file management, ExpoFileDriver, and cloud storage bucket sync.
104
- * `local-lite-react`: Reactive hooks (`useLiveQuery`, `useSyncStatus`, `useLocalAuth`, `useKV`), and 0ms optimistic writes.
104
+ * `local-lite-react`: Reactive hooks (`useLiveQuery`, `useSyncStatus`, `useLocalAuth`, `useKVStore`), and 0ms optimistic writes.
105
105
  * `local-lite-offline-actions`: Queued mutation outbox, encrypted secret preferences, and background scheduler.
106
106
  * `local-lite-custom-adapter`: Implementing custom REST, GraphQL, or WebSocket remote database adapters.
107
107
  * `local-lite-upgrade`: Migration checklist and breaking change reviews across version upgrades.
@@ -135,7 +135,7 @@ This recovers sync state; it does not repair corrupt SQLite files or cancel hung
135
135
  * **🔑 Google Sign-In Out of the Box:** Secure, zero-backend Google OAuth 2.0 (PKCE) authentication with automatic token refresh, user profile retrieval, persistent session storage, and `useGoogleAuth()` hook.
136
136
  * **📨 Action Outbox & Direct Email:** Enqueue transactional emails offline with 0ms local latency. Send directly via Nodemailer SMTP, Resend, SendGrid, Postmark, or Dev Mailbox. Full support for React Email JSX, auto-hydrating mobile `file://` attachments, rate limiting, and type-safe contracts (`defineAction`).
137
137
  * **🌐 Turnkey Server Endpoints (`local-lite/server`):** Mount self-hosted sync (`createSyncEndpoint`) and secure email relay (`createEmailEndpoint`) endpoints in 1 line of code for Next.js, Express, Fastify, or Node http.
138
- * **⚡ Fast Key-Value & Encrypted Preferences (`client.kv`):** Typed storage, TTL expiration, and AES-256-GCM zero-knowledge secret protection.
138
+ * **⚡ Fast Key-Value & Encrypted Preferences (`client.kvStore`):** Typed storage, TTL expiration, and AES-256-GCM zero-knowledge secret protection.
139
139
  * **🔍 Instant Full-Text Search (`client.search`):** SQLite FTS5 indexer with prefix matching, BM25 rank scoring, and highlighting.
140
140
  * **📁 Offline Media & Blob Storage (`client.storage`):** Decoupled binary attachments, SHA-256 verification, and cloud sync queue (S3/Supabase/Firebase).
141
141
  * **⏰ Offline Job Scheduler & Background Cron (`client.scheduler`):** Persistent background task runner supporting human schedules and 5-field cron.
@@ -19,10 +19,14 @@ const targets = {
19
19
  const usage = `Usage:
20
20
  local-lite install-skills [--target copilot|claude|antigravity|cursor|agent] [--dir <path>] [--force]
21
21
  local-lite db:generate --schema <path> [--tables <path>] [--out <dir>] [--name <name>] [--dialect mysql|postgres|sqlite] [--server-schema <path>] [--dry-run]
22
+ local-lite dashboard [--db <path>] [--port <number>] [--ui-port <number>] [--host <host>] [--readonly] [--token <secret>] [--title <title>] [--no-open] [--no-vite]
23
+ local-lite dev [--db <path>] [--port <number>] [--ui-port <number>] [--host <host>] [--readonly] [--token <secret>] [--title <title>] [--repo <owner/repo>] [--force] [--no-open]
22
24
 
23
25
  Commands:
24
26
  install-skills Copy bundled AI skills into your project.
25
- db:generate Generate incremental SQL migrations from a schema dictionary.`;
27
+ db:generate Generate incremental SQL migrations from a schema dictionary.
28
+ dashboard Launch the local-lite web dashboard for a SQLite database.
29
+ dev Pull the Vite dashboard from GitHub into ./dashboard, install deps, and serve it.`;
26
30
 
27
31
  function parseSkillsArgs(argv) {
28
32
  const options = { target: 'copilot', dir: undefined, force: false };
@@ -126,7 +130,7 @@ async function installSkills(options) {
126
130
 
127
131
  async function runDbGen(options) {
128
132
  const { generateSqlMigration } = await import(
129
- pathToFileURL(path.resolve(__dirname, '..', 'dist', 'schema', 'index.js')).href
133
+ pathToFileURL(path.resolve(__dirname, '..', 'dist', 'schema', 'sqlMigrations.js')).href
130
134
  );
131
135
  const schemaExports = await loadModuleExports(options.schema);
132
136
  const dictionary =
@@ -172,12 +176,221 @@ async function runDbGen(options) {
172
176
  }
173
177
  }
174
178
 
179
+ function parseDashboardArgs(argv) {
180
+ const options = {
181
+ db: ':memory:',
182
+ port: 4321,
183
+ uiPort: 5173,
184
+ host: '127.0.0.1',
185
+ readOnly: false,
186
+ token: undefined,
187
+ title: undefined,
188
+ open: true,
189
+ noVite: false,
190
+ repo: 'georgechitechi/local-lite',
191
+ force: false,
192
+ };
193
+ for (let i = 0; i < argv.length; i++) {
194
+ const arg = argv[i];
195
+ if (arg === '--readonly') options.readOnly = true;
196
+ else if (arg === '--no-open') options.open = false;
197
+ else if (arg === '--no-vite') options.noVite = true;
198
+ else if (arg === '--force') options.force = true;
199
+ else if (arg === '--repo') options.repo = argv[++i];
200
+ else if (arg === '--db') options.db = argv[++i];
201
+ else if (arg === '--port') options.port = Number(argv[++i]);
202
+ else if (arg === '--ui-port') options.uiPort = Number(argv[++i]);
203
+ else if (arg === '--host') options.host = argv[++i];
204
+ else if (arg === '--token') options.token = argv[++i];
205
+ else if (arg === '--title') options.title = argv[++i];
206
+ else if (arg !== '--') throw new Error(`Unknown option: ${arg}`);
207
+ }
208
+ if (!options.db) throw new Error('--db <path> cannot be empty.');
209
+ if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535) {
210
+ throw new Error('--port must be a valid TCP port (0-65535).');
211
+ }
212
+ if (!Number.isInteger(options.uiPort) || options.uiPort < 0 || options.uiPort > 65535) {
213
+ throw new Error('--ui-port must be a valid TCP port (0-65535).');
214
+ }
215
+ return options;
216
+ }
217
+
218
+ async function openDashboardDbAdapter(dbPath) {
219
+ const resolved = dbPath === ':memory:' ? ':memory:' : path.resolve(process.cwd(), dbPath);
220
+ try {
221
+ const nodeSqlite = await import('node:sqlite');
222
+ const mod = await import(
223
+ pathToFileURL(path.resolve(__dirname, '..', 'dist', 'adapters', 'local', 'node-sqlite.js')).href
224
+ );
225
+ const NodeSQLiteAdapter = mod.NodeSQLiteAdapter ?? mod.default?.NodeSQLiteAdapter;
226
+ const db = new nodeSqlite.DatabaseSync(resolved);
227
+ return { adapter: new NodeSQLiteAdapter(db), label: resolved, close: () => db.close() };
228
+ } catch {
229
+ // Fallback to better-sqlite3 if node:sqlite is unavailable
230
+ }
231
+
232
+ const requireFromCwd = createRequire(path.join(process.cwd(), 'package.json'));
233
+ try {
234
+ const BetterSqlite3 = requireFromCwd('better-sqlite3');
235
+ const mod = await import(
236
+ pathToFileURL(path.resolve(__dirname, '..', 'dist', 'adapters', 'local', 'better-sqlite3.js')).href
237
+ );
238
+ const BetterSQLite3Adapter = mod.BetterSQLite3Adapter ?? mod.default?.BetterSQLite3Adapter;
239
+ const db = new BetterSqlite3(resolved);
240
+ return { adapter: new BetterSQLite3Adapter(db), label: resolved, close: () => db.close() };
241
+ } catch {
242
+ throw new Error(
243
+ 'No SQLite driver available. Run on Node 22+ (node:sqlite) or install "better-sqlite3".',
244
+ );
245
+ }
246
+ }
247
+
248
+ async function runDashboard(options) {
249
+ const http = await import('node:http');
250
+ const dashboardMod = await import(
251
+ pathToFileURL(path.resolve(__dirname, '..', 'dist', 'server', 'dashboard.js')).href
252
+ );
253
+ const createDashboardHandler =
254
+ dashboardMod.createDashboardHandler ?? dashboardMod.default?.createDashboardHandler;
255
+ if (typeof createDashboardHandler !== 'function') {
256
+ throw new Error(
257
+ 'Dashboard module not built. Run "npm run build" first.',
258
+ );
259
+ }
260
+ const { adapter, label, close } = await openDashboardDbAdapter(options.db);
261
+ const handler = createDashboardHandler(adapter, {
262
+ title: options.title ?? `local-lite (${path.basename(label)})`,
263
+ readOnly: options.readOnly,
264
+ authToken: options.token,
265
+ });
266
+
267
+ const server = http.createServer(async (req, res) => {
268
+ try {
269
+ const origin = `http://${req.headers.host || `${options.host}:${options.port}`}`;
270
+ const url = new URL(req.url || '/', origin);
271
+ const chunks = [];
272
+ for await (const chunk of req) chunks.push(chunk);
273
+ const body = chunks.length > 0 ? Buffer.concat(chunks) : undefined;
274
+ const webReq = new Request(url.toString(), {
275
+ method: req.method,
276
+ headers: req.headers,
277
+ body: req.method === 'GET' || req.method === 'HEAD' ? undefined : body,
278
+ });
279
+ const webRes = await handler(webReq);
280
+ res.statusCode = webRes.status;
281
+ webRes.headers.forEach((value, key) => res.setHeader(key, value));
282
+ const buf = Buffer.from(await webRes.arrayBuffer());
283
+ res.end(buf);
284
+ } catch (err) {
285
+ res.statusCode = 500;
286
+ res.setHeader('Content-Type', 'application/json');
287
+ res.end(JSON.stringify({ error: err instanceof Error ? err.message : 'Internal error' }));
288
+ }
289
+ });
290
+
291
+ await new Promise((resolve) => server.listen(options.port, options.host, resolve));
292
+ const address = server.address();
293
+ const actualPort = typeof address === 'object' && address ? address.port : options.port;
294
+ const apiOrigin = `http://${options.host}:${actualPort}`;
295
+ const tokenSuffix = options.token ? `?token=${encodeURIComponent(options.token)}` : '';
296
+ console.log(`local-lite API server running at ${apiOrigin}/${tokenSuffix}`);
297
+ console.log(`Database: ${label} (${options.readOnly ? 'read-only' : 'read/write'})`);
298
+
299
+ let viteProc = null;
300
+ const { existsSync } = await import('node:fs');
301
+ const pkgDashboardDir = path.resolve(__dirname, '..', 'dashboard');
302
+ const cwdDashboardDir = path.resolve(process.cwd(), 'dashboard');
303
+ const dashboardDir =
304
+ options.dashboardDir ??
305
+ (existsSync(path.join(pkgDashboardDir, 'package.json')) ? pkgDashboardDir : cwdDashboardDir);
306
+ const viteBin = path.join(dashboardDir, 'node_modules', 'vite', 'bin', 'vite.js');
307
+ if (!options.noVite) {
308
+ if (existsSync(viteBin)) {
309
+ const { spawn } = await import('node:child_process');
310
+ const viteArgs = [
311
+ viteBin,
312
+ '--host',
313
+ options.host,
314
+ '--port',
315
+ String(options.uiPort),
316
+ ];
317
+ if (options.open) {
318
+ viteArgs.push('--open', tokenSuffix || '/');
319
+ }
320
+ viteProc = spawn(process.execPath, viteArgs, {
321
+ cwd: dashboardDir,
322
+ env: {
323
+ ...process.env,
324
+ LOCAL_LITE_API_TARGET: apiOrigin,
325
+ },
326
+ stdio: 'inherit',
327
+ });
328
+ } else {
329
+ console.log('Vite dashboard dependencies not installed; serving built-in fallback UI.');
330
+ }
331
+ }
332
+
333
+ const shutdown = () => {
334
+ if (viteProc && !viteProc.killed) {
335
+ try { viteProc.kill(); } catch {}
336
+ }
337
+ server.close(() => {
338
+ try { close(); } catch {}
339
+ process.exit(0);
340
+ });
341
+ };
342
+ process.on('SIGINT', shutdown);
343
+ process.on('SIGTERM', shutdown);
344
+ }
345
+
346
+ async function runDev(options) {
347
+ const { existsSync } = await import('node:fs');
348
+ const { spawnSync } = await import('node:child_process');
349
+ const targetDir = path.resolve(process.cwd(), 'dashboard');
350
+ const pkgJsonPath = path.join(targetDir, 'package.json');
351
+ const viteBin = path.join(targetDir, 'node_modules', 'vite', 'bin', 'vite.js');
352
+
353
+ if (!existsSync(pkgJsonPath) || options.force) {
354
+ console.log(`Pulling dashboard from ${options.repo}/dashboard into ./dashboard...`);
355
+ const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
356
+ const degitArgs = ['--yes', 'degit', `${options.repo}/dashboard`, 'dashboard'];
357
+ if (options.force) degitArgs.push('--force');
358
+ const pullRes = spawnSync(npxCmd, degitArgs, {
359
+ cwd: process.cwd(),
360
+ stdio: 'inherit',
361
+ shell: process.platform === 'win32',
362
+ });
363
+ if (pullRes.error || pullRes.status !== 0) {
364
+ throw new Error(`Failed to pull dashboard from ${options.repo}/dashboard.`);
365
+ }
366
+ }
367
+
368
+ if (!existsSync(viteBin)) {
369
+ console.log('Installing dashboard dependencies...');
370
+ const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
371
+ const installRes = spawnSync(npmCmd, ['--prefix', 'dashboard', 'install'], {
372
+ cwd: process.cwd(),
373
+ stdio: 'inherit',
374
+ shell: process.platform === 'win32',
375
+ });
376
+ if (installRes.error || installRes.status !== 0) {
377
+ throw new Error('Failed to install dashboard dependencies.');
378
+ }
379
+ }
380
+
381
+ await runDashboard({ ...options, dashboardDir: targetDir });
382
+ }
383
+
175
384
  const [command, ...rest] = process.argv.slice(2);
176
385
  try {
177
386
  if (command === 'install-skills') {
178
387
  await installSkills(parseSkillsArgs(rest));
179
388
  } else if (command === 'db:generate') {
180
389
  await runDbGen(parseDbGenArgs(rest));
390
+ } else if (command === 'dashboard') {
391
+ await runDashboard(parseDashboardArgs(rest));
392
+ } else if (command === 'dev') {
393
+ await runDev(parseDashboardArgs(rest));
181
394
  } else {
182
395
  console.log(usage);
183
396
  process.exitCode = command && command !== '--help' && command !== '-h' ? 1 : 0;
@@ -12,7 +12,7 @@ import { type ExportJsonOptions, type ImportJsonOptions, type ExportCsvOptions,
12
12
  import { type BackupStorage, type CreateDatabaseBackupOptions, type EncryptedBackupOptions, type RestoreEncryptedBackupOptions } from '../backups/index.js';
13
13
  import { ActionManager, type ActionManagerOptions } from '../actions/index.js';
14
14
  import { ApiKeyManager, type ApiKeyManagerOptions } from '../keys/index.js';
15
- import { KVManager, type KVStoreOptions } from '../kv/index.js';
15
+ import { KVStoreManager, type KVStoreOptions } from '../kv-store/index.js';
16
16
  import { SearchManager } from '../search/index.js';
17
17
  import { BlobStorageManager, type BlobStorageManagerOptions } from '../storage/index.js';
18
18
  import { JobScheduler, type JobSchedulerOptions } from '../scheduler/index.js';
@@ -61,7 +61,7 @@ export interface LocalFirstClientConfig {
61
61
  touchUpdatedAt?: boolean | string;
62
62
  actions?: ActionManagerOptions;
63
63
  keys?: ApiKeyManagerOptions;
64
- kv?: KVStoreOptions;
64
+ kvStore?: KVStoreOptions;
65
65
  storage?: BlobStorageManagerOptions;
66
66
  scheduler?: JobSchedulerOptions;
67
67
  session?: SessionManagerOptions;
@@ -115,7 +115,7 @@ export declare class LocalFirstClient {
115
115
  readonly maintenance: DatabaseMaintenance;
116
116
  readonly actions: ActionManager;
117
117
  readonly keys: ApiKeyManager;
118
- readonly kv: KVManager;
118
+ readonly kvStore: KVStoreManager;
119
119
  readonly search: SearchManager;
120
120
  readonly storage: BlobStorageManager;
121
121
  readonly scheduler: JobScheduler;
@@ -16,7 +16,7 @@ const portability_js_1 = require("../utils/portability.js");
16
16
  const index_js_1 = require("../backups/index.js");
17
17
  const index_js_2 = require("../actions/index.js");
18
18
  const index_js_3 = require("../keys/index.js");
19
- const index_js_4 = require("../kv/index.js");
19
+ const index_js_4 = require("../kv-store/index.js");
20
20
  const index_js_5 = require("../search/index.js");
21
21
  const index_js_6 = require("../storage/index.js");
22
22
  const index_js_7 = require("../scheduler/index.js");
@@ -379,7 +379,7 @@ class LocalFirstClient {
379
379
  maintenance;
380
380
  actions;
381
381
  keys;
382
- kv;
382
+ kvStore;
383
383
  search;
384
384
  storage;
385
385
  scheduler;
@@ -438,7 +438,7 @@ class LocalFirstClient {
438
438
  this.schemaManager = new schema_manager_js_1.SchemaManager();
439
439
  this.maintenance = new maintenance_js_1.DatabaseMaintenance(this.db, () => [
440
440
  ...this.tables,
441
- '_local_kv',
441
+ '_local_kv_store',
442
442
  '_local_blobs',
443
443
  '_local_scheduled_jobs',
444
444
  '_local_job_runs',
@@ -450,7 +450,7 @@ class LocalFirstClient {
450
450
  ]);
451
451
  const actionNetwork = config.actions?.network ?? config.network;
452
452
  this.keys = new index_js_3.ApiKeyManager(this.db, config.keys);
453
- this.kv = new index_js_4.KVManager(this.db, this.events, config.kv);
453
+ this.kvStore = new index_js_4.KVStoreManager(this.db, this.events, config.kvStore);
454
454
  this.search = new index_js_5.SearchManager(this.db, this.events, (table, id) => this.findById(table, id));
455
455
  let storageUploader = config.storage?.uploader;
456
456
  if (!storageUploader && config.storage) {
@@ -697,7 +697,7 @@ class LocalFirstClient {
697
697
  await outbox_store_js_1.OutboxStore.resetStaleProcessing(this.db);
698
698
  await this.actions.initialize();
699
699
  await this.keys.initialize();
700
- await this.kv.initialize();
700
+ await this.kvStore.initialize();
701
701
  await this.storage.initialize();
702
702
  await this.scheduler.initialize();
703
703
  await this.session.initialize();
@@ -1303,7 +1303,7 @@ class LocalFirstClient {
1303
1303
  async reset(options = {}) {
1304
1304
  this.stop();
1305
1305
  const internalTables = [
1306
- '_local_kv',
1306
+ '_local_kv_store',
1307
1307
  '_local_blobs',
1308
1308
  '_local_scheduled_jobs',
1309
1309
  '_local_job_runs',
package/dist/index.d.ts CHANGED
@@ -24,7 +24,7 @@ export * from './auth/index.js';
24
24
  export * from './backups/index.js';
25
25
  export * from './actions/index.js';
26
26
  export * from './keys/index.js';
27
- export * from './kv/index.js';
27
+ export * from './kv-store/index.js';
28
28
  export * from './search/index.js';
29
29
  export * from './storage/index.js';
30
30
  export * from './scheduler/index.js';
package/dist/index.js CHANGED
@@ -40,7 +40,7 @@ __exportStar(require("./auth/index.js"), exports);
40
40
  __exportStar(require("./backups/index.js"), exports);
41
41
  __exportStar(require("./actions/index.js"), exports);
42
42
  __exportStar(require("./keys/index.js"), exports);
43
- __exportStar(require("./kv/index.js"), exports);
43
+ __exportStar(require("./kv-store/index.js"), exports);
44
44
  __exportStar(require("./search/index.js"), exports);
45
45
  __exportStar(require("./storage/index.js"), exports);
46
46
  __exportStar(require("./scheduler/index.js"), exports);
@@ -0,0 +1,3 @@
1
+ export * from './types.js';
2
+ export * from './store.js';
3
+ export * from './manager.js';
@@ -0,0 +1,19 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
+ for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
+ };
16
+ Object.defineProperty(exports, "__esModule", { value: true });
17
+ __exportStar(require("./types.js"), exports);
18
+ __exportStar(require("./store.js"), exports);
19
+ __exportStar(require("./manager.js"), exports);
@@ -0,0 +1,52 @@
1
+ import { DBExecutable } from '../core/schema-manager.js';
2
+ import { EventEmitter } from '../reactive/event-emitter.js';
3
+ import { KVStoreRecord, KVStoreSetOptions, KVStoreSetSecretOptions, KVStoreOptions } from './types.js';
4
+ export declare class KVStoreManager {
5
+ private db;
6
+ private tableName;
7
+ private events?;
8
+ constructor(db: DBExecutable, eventsOrOptions?: EventEmitter | KVStoreOptions, options?: KVStoreOptions);
9
+ initialize(): Promise<void>;
10
+ /**
11
+ * Sets a value in the key-value store with optional TTL.
12
+ * Emits an event on the event emitter if configured.
13
+ */
14
+ set(key: string, value: any, options?: KVStoreSetOptions): Promise<void>;
15
+ /**
16
+ * Retrieves the value for a key, returning defaultValue if not found or expired.
17
+ */
18
+ get<T = any>(key: string, defaultValue?: T): Promise<T | undefined>;
19
+ /**
20
+ * Retrieves the full KVStoreRecord metadata for a key.
21
+ */
22
+ getRecord(key: string): Promise<KVStoreRecord | null>;
23
+ /**
24
+ * Checks whether a non-expired key exists in the store.
25
+ */
26
+ has(key: string): Promise<boolean>;
27
+ /**
28
+ * Removes a key from the store.
29
+ * Emits an event on the event emitter if configured.
30
+ */
31
+ delete(key: string): Promise<void>;
32
+ /**
33
+ * Lists all non-expired keys, optionally filtered by a prefix.
34
+ */
35
+ keys(prefix?: string): Promise<string[]>;
36
+ /**
37
+ * Clears all stored key-value pairs.
38
+ */
39
+ clear(): Promise<void>;
40
+ /**
41
+ * Stores an encrypted secret using AES-256-GCM + PBKDF2 passphrase encryption.
42
+ */
43
+ setSecret(key: string, secretValue: any, options: KVStoreSetSecretOptions): Promise<void>;
44
+ /**
45
+ * Decrypts and retrieves a stored secret.
46
+ */
47
+ getSecret<T = any>(key: string, passphrase: string, defaultValue?: T): Promise<T | undefined>;
48
+ /**
49
+ * Purges all expired keys immediately.
50
+ */
51
+ pruneExpired(): Promise<number>;
52
+ }
@@ -0,0 +1,167 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.KVStoreManager = void 0;
4
+ const encryption_js_1 = require("../backups/encryption.js");
5
+ const signed_token_js_1 = require("../keys/signed-token.js");
6
+ const store_js_1 = require("./store.js");
7
+ class KVStoreManager {
8
+ db;
9
+ tableName;
10
+ events;
11
+ constructor(db, eventsOrOptions, options) {
12
+ this.db = db;
13
+ let opts = {};
14
+ if (eventsOrOptions &&
15
+ typeof eventsOrOptions.emit === 'function') {
16
+ this.events = eventsOrOptions;
17
+ opts = options || {};
18
+ }
19
+ else if (eventsOrOptions) {
20
+ opts = eventsOrOptions;
21
+ }
22
+ this.tableName = opts.tableName ?? store_js_1.DEFAULT_KV_STORE_TABLE;
23
+ }
24
+ async initialize() {
25
+ await store_js_1.KVStore.ensureSchema(this.db, this.tableName);
26
+ }
27
+ /**
28
+ * Sets a value in the key-value store with optional TTL.
29
+ * Emits an event on the event emitter if configured.
30
+ */
31
+ async set(key, value, options = {}) {
32
+ const now = Date.now();
33
+ const expiresAt = options.expiresAt !== undefined
34
+ ? options.expiresAt
35
+ : options.ttlMs !== undefined
36
+ ? now + options.ttlMs
37
+ : null;
38
+ let type;
39
+ let valueStr;
40
+ if (typeof value === 'string') {
41
+ type = 'string';
42
+ valueStr = value;
43
+ }
44
+ else if (typeof value === 'number') {
45
+ type = 'number';
46
+ valueStr = String(value);
47
+ }
48
+ else if (typeof value === 'boolean') {
49
+ type = 'boolean';
50
+ valueStr = value ? '1' : '0';
51
+ }
52
+ else {
53
+ type = 'json';
54
+ valueStr = JSON.stringify(value ?? null);
55
+ }
56
+ await store_js_1.KVStore.set(this.db, this.tableName, key, valueStr, type, now, expiresAt);
57
+ this.events?.emit(this.tableName, { operation: 'SET', key, value });
58
+ }
59
+ /**
60
+ * Retrieves the value for a key, returning defaultValue if not found or expired.
61
+ */
62
+ async get(key, defaultValue) {
63
+ const record = await store_js_1.KVStore.get(this.db, this.tableName, key);
64
+ if (!record)
65
+ return defaultValue;
66
+ if (record.expiresAt && record.expiresAt <= Date.now()) {
67
+ // Lazy deletion of expired key
68
+ store_js_1.KVStore.delete(this.db, this.tableName, key).catch(() => { });
69
+ return defaultValue;
70
+ }
71
+ return record.value;
72
+ }
73
+ /**
74
+ * Retrieves the full KVStoreRecord metadata for a key.
75
+ */
76
+ async getRecord(key) {
77
+ const record = await store_js_1.KVStore.get(this.db, this.tableName, key);
78
+ if (!record)
79
+ return null;
80
+ if (record.expiresAt && record.expiresAt <= Date.now()) {
81
+ store_js_1.KVStore.delete(this.db, this.tableName, key).catch(() => { });
82
+ return null;
83
+ }
84
+ return record;
85
+ }
86
+ /**
87
+ * Checks whether a non-expired key exists in the store.
88
+ */
89
+ async has(key) {
90
+ const val = await this.get(key);
91
+ return val !== undefined;
92
+ }
93
+ /**
94
+ * Removes a key from the store.
95
+ * Emits an event on the event emitter if configured.
96
+ */
97
+ async delete(key) {
98
+ await store_js_1.KVStore.delete(this.db, this.tableName, key);
99
+ this.events?.emit(this.tableName, { operation: 'DELETE', key });
100
+ }
101
+ /**
102
+ * Lists all non-expired keys, optionally filtered by a prefix.
103
+ */
104
+ async keys(prefix) {
105
+ return store_js_1.KVStore.listKeys(this.db, this.tableName, prefix);
106
+ }
107
+ /**
108
+ * Clears all stored key-value pairs.
109
+ */
110
+ async clear() {
111
+ await store_js_1.KVStore.clear(this.db, this.tableName);
112
+ this.events?.emit(this.tableName, { operation: 'CLEAR' });
113
+ }
114
+ /**
115
+ * Stores an encrypted secret using AES-256-GCM + PBKDF2 passphrase encryption.
116
+ */
117
+ async setSecret(key, secretValue, options) {
118
+ if (!options.passphrase) {
119
+ throw new Error('Passphrase is required to store encrypted secret.');
120
+ }
121
+ const strValue = typeof secretValue === 'string'
122
+ ? secretValue
123
+ : JSON.stringify(secretValue);
124
+ const plainBytes = new TextEncoder().encode(strValue);
125
+ const encryptedBytes = await (0, encryption_js_1.encryptBackupData)(plainBytes, options.passphrase);
126
+ const encryptedBase64 = (0, signed_token_js_1.base64UrlEncode)(encryptedBytes);
127
+ const now = Date.now();
128
+ const expiresAt = options.expiresAt !== undefined
129
+ ? options.expiresAt
130
+ : options.ttlMs !== undefined
131
+ ? now + options.ttlMs
132
+ : null;
133
+ await store_js_1.KVStore.set(this.db, this.tableName, key, encryptedBase64, 'encrypted', now, expiresAt);
134
+ this.events?.emit(this.tableName, { operation: 'SET_SECRET', key });
135
+ }
136
+ /**
137
+ * Decrypts and retrieves a stored secret.
138
+ */
139
+ async getSecret(key, passphrase, defaultValue) {
140
+ const record = await store_js_1.KVStore.get(this.db, this.tableName, key);
141
+ if (!record)
142
+ return defaultValue;
143
+ if (record.expiresAt && record.expiresAt <= Date.now()) {
144
+ store_js_1.KVStore.delete(this.db, this.tableName, key).catch(() => { });
145
+ return defaultValue;
146
+ }
147
+ if (record.type !== 'encrypted') {
148
+ return record.value;
149
+ }
150
+ const encryptedBytes = (0, signed_token_js_1.base64UrlDecode)(record.value);
151
+ const decryptedBytes = await (0, encryption_js_1.decryptBackupData)(encryptedBytes, passphrase);
152
+ const text = new TextDecoder().decode(decryptedBytes);
153
+ try {
154
+ return JSON.parse(text);
155
+ }
156
+ catch {
157
+ return text;
158
+ }
159
+ }
160
+ /**
161
+ * Purges all expired keys immediately.
162
+ */
163
+ async pruneExpired() {
164
+ return store_js_1.KVStore.pruneExpired(this.db, this.tableName);
165
+ }
166
+ }
167
+ exports.KVStoreManager = KVStoreManager;
@@ -0,0 +1,13 @@
1
+ import { DBExecutable } from '../core/schema-manager.js';
2
+ import { KVStoreRecord } from './types.js';
3
+ export declare const DEFAULT_KV_STORE_TABLE = "_local_kv_store";
4
+ export declare function mapKVStoreRow(r: any): KVStoreRecord;
5
+ export declare class KVStore {
6
+ static ensureSchema(db: DBExecutable, tableName?: string): Promise<void>;
7
+ static set(db: DBExecutable, tableName: string | undefined, key: string, valueStr: string, type: string, now: number, expiresAt: number | null): Promise<void>;
8
+ static get(db: DBExecutable, tableName: string | undefined, key: string): Promise<KVStoreRecord | null>;
9
+ static delete(db: DBExecutable, tableName: string | undefined, key: string): Promise<boolean>;
10
+ static listKeys(db: DBExecutable, tableName?: string, prefix?: string): Promise<string[]>;
11
+ static clear(db: DBExecutable, tableName?: string): Promise<void>;
12
+ static pruneExpired(db: DBExecutable, tableName?: string): Promise<number>;
13
+ }