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 +2 -2
- package/bin/local-lite.mjs +215 -2
- package/dist/core/client.d.ts +3 -3
- package/dist/core/client.js +6 -6
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/kv-store/index.d.ts +3 -0
- package/dist/kv-store/index.js +19 -0
- package/dist/kv-store/manager.d.ts +52 -0
- package/dist/kv-store/manager.js +167 -0
- package/dist/kv-store/store.d.ts +13 -0
- package/dist/kv-store/store.js +85 -0
- package/dist/kv-store/types.d.ts +27 -0
- package/dist/kv-store/types.js +2 -0
- package/dist/react/index.d.ts +1 -1
- package/dist/react/index.js +1 -1
- package/dist/react/kv-store.d.ts +9 -0
- package/dist/react/kv-store.js +53 -0
- package/dist/schema/index.d.ts +0 -1
- package/dist/schema/index.js +0 -1
- package/dist/server/dashboard.d.ts +16 -0
- package/dist/server/dashboard.js +1364 -0
- package/dist/server/index.d.ts +1 -0
- package/dist/server/index.js +1 -0
- package/package.json +10 -5
- package/skills/local-lite-offline-actions/SKILL.md +11 -11
- package/skills/local-lite-react/SKILL.md +7 -7
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`, `
|
|
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.
|
|
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.
|
package/bin/local-lite.mjs
CHANGED
|
@@ -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', '
|
|
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;
|
package/dist/core/client.d.ts
CHANGED
|
@@ -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 {
|
|
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
|
-
|
|
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
|
|
118
|
+
readonly kvStore: KVStoreManager;
|
|
119
119
|
readonly search: SearchManager;
|
|
120
120
|
readonly storage: BlobStorageManager;
|
|
121
121
|
readonly scheduler: JobScheduler;
|
package/dist/core/client.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
'
|
|
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.
|
|
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.
|
|
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
|
-
'
|
|
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,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
|
+
}
|