local-lite 1.0.3 → 2.0.0

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.
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.MemoryServerSyncStorage = void 0;
3
+ exports.SQLiteServerSyncStorage = exports.MemoryServerSyncStorage = void 0;
4
4
  exports.createSyncEndpoint = createSyncEndpoint;
5
5
  /**
6
6
  * In-memory server sync storage.
@@ -10,6 +10,10 @@ class MemoryServerSyncStorage {
10
10
  tables = new Map();
11
11
  changeLog = [];
12
12
  monotonicCursor = 0;
13
+ maxChangeLogEntries;
14
+ constructor(options = {}) {
15
+ this.maxChangeLogEntries = options.maxChangeLogEntries ?? 10000;
16
+ }
13
17
  async applyOperations(operations, overrideTime) {
14
18
  const serverTime = overrideTime ?? Date.now();
15
19
  let applied = 0;
@@ -46,6 +50,11 @@ class MemoryServerSyncStorage {
46
50
  applied += 1;
47
51
  successfulIds.push(op.id);
48
52
  }
53
+ if (Number.isFinite(this.maxChangeLogEntries) &&
54
+ this.maxChangeLogEntries > 0 &&
55
+ this.changeLog.length > this.maxChangeLogEntries) {
56
+ this.changeLog.splice(0, this.changeLog.length - this.maxChangeLogEntries);
57
+ }
49
58
  return { applied, successfulIds, serverTime, cursor: this.monotonicCursor };
50
59
  }
51
60
  async getDeltas(tables, since, limit = 1000) {
@@ -63,8 +72,11 @@ class MemoryServerSyncStorage {
63
72
  latestMap.set(key, entry);
64
73
  if (entry.cursor > maxCursor)
65
74
  maxCursor = entry.cursor;
66
- if (entry.timestamp > maxCursor)
75
+ // Only fall back to wall-clock timestamp if the client's cursor is ahead of
76
+ // this in-memory instance (e.g. after a server restart).
77
+ if (since > this.monotonicCursor && entry.timestamp > maxCursor) {
67
78
  maxCursor = entry.timestamp;
79
+ }
68
80
  }
69
81
  const deltaList = Array.from(latestMap.values()).map((entry) => ({
70
82
  tableName: entry.tableName,
@@ -93,6 +105,206 @@ class MemoryServerSyncStorage {
93
105
  }
94
106
  }
95
107
  exports.MemoryServerSyncStorage = MemoryServerSyncStorage;
108
+ /**
109
+ * Persistent SQLite-backed ServerSyncStorage for production self-hosted sync servers.
110
+ * Works with any LocalDBAdapter (e.g. BetterSQLite3Adapter, NodeSQLiteAdapter, LibSQLAdapter).
111
+ */
112
+ class SQLiteServerSyncStorage {
113
+ db;
114
+ initPromise;
115
+ maxChangeLogEntries;
116
+ constructor(db, options = {}) {
117
+ this.db = db;
118
+ this.maxChangeLogEntries = options.maxChangeLogEntries ?? 10000;
119
+ }
120
+ async ensureSchema() {
121
+ if (!this.initPromise) {
122
+ this.initPromise = (async () => {
123
+ await this.db.execute(`CREATE TABLE IF NOT EXISTS _sync_server_records (
124
+ table_name TEXT NOT NULL,
125
+ row_id TEXT NOT NULL,
126
+ payload TEXT NOT NULL,
127
+ timestamp INTEGER NOT NULL,
128
+ operation TEXT NOT NULL,
129
+ cursor INTEGER NOT NULL,
130
+ PRIMARY KEY (table_name, row_id)
131
+ );`);
132
+ await this.db.execute(`CREATE TABLE IF NOT EXISTS _sync_server_changelog (
133
+ cursor INTEGER PRIMARY KEY AUTOINCREMENT,
134
+ table_name TEXT NOT NULL,
135
+ row_id TEXT NOT NULL,
136
+ payload TEXT NOT NULL,
137
+ timestamp INTEGER NOT NULL,
138
+ operation TEXT NOT NULL
139
+ );`);
140
+ await this.db.execute(`CREATE INDEX IF NOT EXISTS idx_sync_srv_log_table_cursor ON _sync_server_changelog (table_name, cursor);`);
141
+ })().catch((err) => {
142
+ this.initPromise = undefined;
143
+ throw err;
144
+ });
145
+ }
146
+ await this.initPromise;
147
+ }
148
+ async applyOperations(operations, overrideTime) {
149
+ await this.ensureSchema();
150
+ const serverTime = overrideTime ?? Date.now();
151
+ let applied = 0;
152
+ const successfulIds = [];
153
+ let latestCursor = 0;
154
+ await this.db.transaction(async (tx) => {
155
+ for (const op of operations) {
156
+ if (!op.tableName || !op.rowId)
157
+ continue;
158
+ const rowId = String(op.rowId);
159
+ const existingRows = await tx.execute(`SELECT payload, timestamp FROM _sync_server_records WHERE table_name = ? AND row_id = ? LIMIT 1`, [op.tableName, rowId]);
160
+ const existing = existingRows?.[0];
161
+ const opTime = op.timestamp ?? serverTime;
162
+ if (existing && Number(existing.timestamp) > opTime) {
163
+ successfulIds.push(op.id);
164
+ continue;
165
+ }
166
+ let existingPayload = {};
167
+ if (existing?.payload) {
168
+ try {
169
+ existingPayload =
170
+ typeof existing.payload === 'string'
171
+ ? JSON.parse(existing.payload)
172
+ : existing.payload;
173
+ }
174
+ catch {
175
+ existingPayload = {};
176
+ }
177
+ }
178
+ const isDelete = op.operation === 'DELETE';
179
+ const recordPayload = isDelete
180
+ ? { id: op.rowId, deleted: true }
181
+ : { ...existingPayload, ...(op.payload || {}), id: op.rowId };
182
+ const serializedPayload = JSON.stringify(recordPayload);
183
+ const recordTimestamp = Math.max(opTime, serverTime);
184
+ const insertRes = await tx.execute(`INSERT INTO _sync_server_changelog (table_name, row_id, payload, timestamp, operation) VALUES (?, ?, ?, ?, ?)`, [
185
+ op.tableName,
186
+ rowId,
187
+ serializedPayload,
188
+ recordTimestamp,
189
+ op.operation,
190
+ ]);
191
+ let cursor = Number(insertRes?.[0]?.lastInsertRowid ?? 0);
192
+ if (!cursor) {
193
+ const maxRows = await tx.execute(`SELECT MAX(cursor) AS cursor FROM _sync_server_changelog`);
194
+ cursor = Number(maxRows?.[0]?.cursor ?? 0);
195
+ }
196
+ await tx.execute(`INSERT INTO _sync_server_records (table_name, row_id, payload, timestamp, operation, cursor)
197
+ VALUES (?, ?, ?, ?, ?, ?)
198
+ ON CONFLICT (table_name, row_id) DO UPDATE SET
199
+ payload = excluded.payload,
200
+ timestamp = excluded.timestamp,
201
+ operation = excluded.operation,
202
+ cursor = excluded.cursor`, [
203
+ op.tableName,
204
+ rowId,
205
+ serializedPayload,
206
+ recordTimestamp,
207
+ op.operation,
208
+ cursor,
209
+ ]);
210
+ latestCursor = Math.max(latestCursor, cursor);
211
+ applied += 1;
212
+ successfulIds.push(op.id);
213
+ }
214
+ if (this.maxChangeLogEntries !== undefined &&
215
+ Number.isFinite(this.maxChangeLogEntries) &&
216
+ this.maxChangeLogEntries > 0 &&
217
+ latestCursor > this.maxChangeLogEntries) {
218
+ await tx.execute(`DELETE FROM _sync_server_changelog WHERE cursor <= ?`, [latestCursor - this.maxChangeLogEntries]);
219
+ }
220
+ });
221
+ if (latestCursor === 0) {
222
+ const maxRows = await this.db.execute(`SELECT MAX(cursor) AS cursor FROM _sync_server_changelog`);
223
+ latestCursor = Number(maxRows?.[0]?.cursor ?? 0);
224
+ }
225
+ return { applied, successfulIds, serverTime, cursor: latestCursor };
226
+ }
227
+ async getDeltas(tables, since, limit = 1000) {
228
+ await this.ensureSchema();
229
+ const serverTime = Date.now();
230
+ const safeLimit = Math.max(1, Math.floor(limit));
231
+ const maxRows = await this.db.execute(`SELECT MAX(cursor) AS maxCursor FROM _sync_server_changelog`);
232
+ const currentMaxCursor = Number(maxRows?.[0]?.maxCursor ?? 0);
233
+ const useCursorFilter = since <= currentMaxCursor;
234
+ const params = [since];
235
+ let whereClause = useCursorFilter ? `cursor > ?` : `timestamp > ?`;
236
+ if (tables.length > 0) {
237
+ const placeholders = tables.map(() => '?').join(', ');
238
+ whereClause += ` AND table_name IN (${placeholders})`;
239
+ params.push(...tables);
240
+ }
241
+ params.push(safeLimit + 1);
242
+ const rows = await this.db.execute(`SELECT cursor, table_name, row_id, payload, timestamp, operation
243
+ FROM _sync_server_changelog
244
+ WHERE ${whereClause}
245
+ ORDER BY cursor ASC
246
+ LIMIT ?`, params);
247
+ const hasMore = rows.length > safeLimit;
248
+ const paged = hasMore ? rows.slice(0, safeLimit) : rows;
249
+ const latestMap = new Map();
250
+ let maxCursor = since;
251
+ for (const row of paged) {
252
+ let parsedPayload = {};
253
+ try {
254
+ parsedPayload =
255
+ typeof row.payload === 'string'
256
+ ? JSON.parse(row.payload)
257
+ : (row.payload ?? {});
258
+ }
259
+ catch {
260
+ parsedPayload = {};
261
+ }
262
+ const key = `${row.table_name}:${row.row_id}`;
263
+ const ts = Number(row.timestamp);
264
+ const cur = Number(row.cursor);
265
+ latestMap.set(key, {
266
+ tableName: row.table_name,
267
+ operation: row.operation,
268
+ rowId: row.row_id,
269
+ payload: parsedPayload,
270
+ timestamp: ts,
271
+ });
272
+ if (useCursorFilter) {
273
+ if (cur > maxCursor)
274
+ maxCursor = cur;
275
+ }
276
+ else {
277
+ if (ts > maxCursor)
278
+ maxCursor = ts;
279
+ }
280
+ }
281
+ const deltaList = Array.from(latestMap.values());
282
+ return {
283
+ changes: {
284
+ timestamp: serverTime,
285
+ changes: deltaList,
286
+ hasMore,
287
+ },
288
+ cursor: maxCursor,
289
+ hasMore,
290
+ serverTime,
291
+ };
292
+ }
293
+ /**
294
+ * Compacts older changelog entries, retaining the most recent `retentionCount` rows.
295
+ */
296
+ async compactChangeLog(retentionCount = 10000) {
297
+ await this.ensureSchema();
298
+ if (!Number.isFinite(retentionCount) || retentionCount < 0)
299
+ return;
300
+ const maxRows = await this.db.execute(`SELECT MAX(cursor) AS cursor FROM _sync_server_changelog`);
301
+ const maxCursor = Number(maxRows?.[0]?.cursor ?? 0);
302
+ if (maxCursor > retentionCount) {
303
+ await this.db.execute(`DELETE FROM _sync_server_changelog WHERE cursor <= ?`, [maxCursor - retentionCount]);
304
+ }
305
+ }
306
+ }
307
+ exports.SQLiteServerSyncStorage = SQLiteServerSyncStorage;
96
308
  /**
97
309
  * Creates turnkey push and pull API endpoints for self-hosted multi-device data synchronization.
98
310
  */
@@ -1,5 +1,10 @@
1
- import type { SupabaseClient } from '@supabase/supabase-js';
2
1
  import { BlobRecord, RemoteStorageUploader } from './types.js';
2
+ export interface SupabaseStorageClientLike {
3
+ storage?: {
4
+ from: (bucket: string) => any;
5
+ };
6
+ from?: (bucket: string) => any;
7
+ }
3
8
  export interface SupabaseStorageUploaderOptions {
4
9
  /**
5
10
  * Supabase Storage bucket name (e.g. 'avatars', 'property-photos', 'documents').
@@ -41,4 +46,4 @@ export interface SupabaseStorageUploaderInstance extends RemoteStorageUploader {
41
46
  /**
42
47
  * Creates a RemoteStorageUploader that syncs binary files to Supabase Storage buckets.
43
48
  */
44
- export declare function createSupabaseStorageUploader(supabase: SupabaseClient | any, options: SupabaseStorageUploaderOptions): SupabaseStorageUploaderInstance;
49
+ export declare function createSupabaseStorageUploader(supabase: SupabaseStorageClientLike | any, options: SupabaseStorageUploaderOptions): SupabaseStorageUploaderInstance;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "local-lite",
3
- "version": "1.0.3",
3
+ "version": "2.0.0",
4
4
  "description": "Never let a lost connection break a promise. Local-first sync that faithfully keeps data safe until you're back online.",
5
5
  "license": "MIT",
6
6
  "main": "dist/index.js",
@@ -213,16 +213,15 @@
213
213
  }
214
214
  },
215
215
  "devDependencies": {
216
- "@supabase/supabase-js": "^2.118.0",
217
- "@types/node": "^26.6.5",
216
+ "@types/node": "^26.6.6",
218
217
  "@types/nodemailer": "^8.0.2",
219
218
  "@types/react": "^19.3.0",
220
219
  "@types/uuid": "^11.0.0",
221
- "expo-sqlite": "^58.0.14",
220
+ "expo-sqlite": "^58.0.17",
222
221
  "nodemailer": "^10.5.0",
223
222
  "react": "^19.3.1",
224
223
  "typescript": "^7.0.2",
225
- "vitest": "^5.0.5"
224
+ "vitest": "^5.1.0"
226
225
  },
227
226
  "dependencies": {
228
227
  "@noble/hashes": "^2.4.0",
@@ -35,7 +35,7 @@ import { defineSyncConfig } from 'local-lite/config';
35
35
  export const syncConfig = defineSyncConfig({
36
36
  database: () => SQLite.openDatabaseAsync('app.db'),
37
37
  tables: ['tasks'],
38
- localAuth: {
38
+ auth: {
39
39
  // Optional table names (defaults: '_local_users', '_local_user_tokens')
40
40
  usersTable: '_local_users',
41
41
  tokensTable: '_local_user_tokens',
@@ -114,7 +114,7 @@ export const syncConfig = defineSyncConfig({
114
114
  touchUpdatedAt: true,
115
115
 
116
116
  // 6. Zero-backend local SQLite authentication
117
- localAuth: {
117
+ auth: {
118
118
  minPasswordLength: 8,
119
119
  maxFailedAttempts: 5,
120
120
  lockoutDurationMs: 15 * 60 * 1000, // 15 minutes
@@ -1,16 +1,42 @@
1
1
  ---
2
2
  name: local-lite-upgrade
3
- description: Review a codebase that uses the local-lite npm package for code that must change after a local-lite upgrade. Use when upgrading local-lite, migrating from legacy options, fixing bundler errors in Metro/Web, or updating authentication and adapters.
3
+ description: Review a codebase that uses the local-lite npm package for code that must change after a local-lite upgrade. Use when upgrading local-lite, migrating from legacy options or aliases, fixing bundler errors in Metro/Web, or updating authentication, queries, and adapters.
4
4
  ---
5
5
 
6
6
  # local-lite upgrade review
7
7
 
8
8
  Checklist and automated review instructions for upgrading apps to the latest version of `local-lite`.
9
9
 
10
- ## 1. Upgrade Checklist
10
+ ## 1. Upgrade Checklist (2.0.0 & Legacy Migrations)
11
11
 
12
12
  Search the codebase for each affected pattern and apply the migration:
13
13
 
14
+ ### Removed Configuration Aliases (`localAuth`, `maxRetries`, `autoHydrateJSON`)
15
+ * **Old**: `createSyncClient({ localAuth: ..., maxRetries: 5, autoHydrateJSON: true })`
16
+ * **New**: `createSyncClient({ auth: ..., retry: 5, jsonColumns: { todos: ['meta'] } })`
17
+ * **Action**:
18
+ - Replace `localAuth` with `auth`.
19
+ - Replace top-level `maxRetries` on `LocalFirstClient` / `defineSyncConfig` / `SyncWorker` with `retry: number | RetryConfig`.
20
+ - Replace `autoHydrateJSON: true` with explicit `jsonColumns` per table.
21
+
22
+ ### Query Method & Operator Aliases (`find`, unprefixed operators)
23
+ * **Old**: `client.find('todos', { where: { count: { gt: 5 } } })`
24
+ * **New**: `client.findMany('todos', { where: { count: { $gt: 5 } } })`
25
+ * **Action**:
26
+ - Replace `client.find()` / `tx.find()` with `findMany()`.
27
+ - Prefix all `QueryOptions.where` operators with `$` (`$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$contains`, `$startsWith`, `$endsWith`, `$null`).
28
+ - Note: `$contains`, `$startsWith`, and `$endsWith` now escape literal `%` and `_` characters (`LIKE ? ESCAPE '\'`).
29
+
30
+ ### Demo Adapter Imports in `local-lite/config`
31
+ * **Old**: `import { MemoryDemoRemoteAdapter, NoopRemoteAdapter } from 'local-lite/config'`
32
+ * **New**: `import { MemoryDemoRemoteAdapter, NoopRemoteAdapter } from 'local-lite'` (or `'local-lite/core'`)
33
+
34
+ ### Hardened Defaults & Server Storage
35
+ * **Remote Timeouts**: `SyncWorker` defaults to `requestTimeoutMs: 30000` (with `AbortSignal` forwarded to `SelfHostedRemoteAdapter`). Set `requestTimeoutMs: 0` to disable.
36
+ * **Persistent Self-Hosted Server**: Prefer `SQLiteServerSyncStorage` from `local-lite/server` over `MemoryServerSyncStorage` in production; both default to `maxChangeLogEntries: 10000`.
37
+ * **Expo SQLite**: `ExpoSQLiteAdapter` requires Expo SDK 51+ (`runAsync()` / `execAsync()`).
38
+ * **Expo SQLite**: `ExpoSQLiteAdapter` requires Expo SDK 54+ (`runAsync()` / `execAsync()`).
39
+
14
40
  ### Schema Migrations (`schemaMigrations` vs `migrations`)
15
41
  * **Old**: `createSyncClient({ migrations: [ ... ] })`
16
42
  * **New**: `createSyncClient({ schemaMigrations: [ { version: 1, up: [ ... ] } ] })`
@@ -40,15 +66,12 @@ Search the codebase for each affected pattern and apply the migration:
40
66
  * **New**: `import { ... } from 'local-lite/email'`
41
67
  * **Action**: Update imports to the unified email module supporting Nodemailer, Resend, SendGrid, Postmark, and Dev Mailbox.
42
68
 
43
- ### Self-Hosted Sync
44
- * **Old**: Requiring Supabase or Convex for multi-client synchronization.
45
- * **New**: Use `defineSyncConfig({ server: { url: 'https://api.yourdomain.com/sync', token: '...' } })` with turnkey `createSyncEndpoint()` from `local-lite/server`.
46
-
47
69
  ---
48
70
 
49
71
  ## 2. Review Workflow
50
72
 
51
- 1. Scan `sync.config.ts` (or client creation files) for deprecated options (`migrations`, legacy adapters).
52
- 2. Verify all synced tables contain `id TEXT PRIMARY KEY` and `updated_at INTEGER NOT NULL`.
73
+ 1. Scan `sync.config.ts` and `LocalFirstClient` instantiations for removed options (`localAuth`, `maxRetries`, `autoHydrateJSON`, `migrations`).
74
+ 2. Scan `find(` calls and `where:` objects for unprefixed operators (`eq`, `gt`, `in`, `contains`, etc.).
53
75
  3. Verify `schemaMigrations` versions are strictly sequential integers starting from 1.
54
- 4. Report each match with file path and line number alongside minimal migration code.
76
+ 4. Check `expo-sqlite` mocks/instances provide `runAsync()` for parameterized writes.
77
+ 5. Report each match with file path and line number alongside minimal migration code.