local-lite 0.0.28 → 0.0.30
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/dist/adapters/remote/convex.d.ts +7 -2
- package/dist/adapters/remote/convex.js +73 -40
- package/dist/adapters/remote/index.d.ts +2 -1
- package/dist/core/client.d.ts +6 -0
- package/dist/core/client.js +10 -0
- package/dist/core/meta-store.d.ts +3 -3
- package/dist/core/meta-store.js +6 -6
- package/dist/core/outbox-store.d.ts +9 -0
- package/dist/core/outbox-store.js +31 -0
- package/dist/core/sync-worker.d.ts +6 -0
- package/dist/core/sync-worker.js +68 -25
- package/dist/server/index.d.ts +33 -0
- package/dist/server/index.js +133 -0
- package/package.json +6 -1
|
@@ -47,6 +47,9 @@ export declare class ConvexRemoteAdapter implements RemoteDBAdapter {
|
|
|
47
47
|
private deletedColumn;
|
|
48
48
|
private updatedAtColumn;
|
|
49
49
|
private unsubscribeLive?;
|
|
50
|
+
private liveCallback?;
|
|
51
|
+
private liveScope?;
|
|
52
|
+
private liveGeneration;
|
|
50
53
|
logger: SyncLogger;
|
|
51
54
|
constructor(client: any, options?: ConvexRemoteAdapterOptions);
|
|
52
55
|
/**
|
|
@@ -60,11 +63,13 @@ export declare class ConvexRemoteAdapter implements RemoteDBAdapter {
|
|
|
60
63
|
/**
|
|
61
64
|
* Fetches delta changes from Convex since a given timestamp.
|
|
62
65
|
*/
|
|
63
|
-
fetchChanges(sinceTimestamp: number): Promise<DeltaChanges>;
|
|
66
|
+
fetchChanges(sinceTimestamp: number, scope?: Record<string, any>): Promise<DeltaChanges>;
|
|
64
67
|
/**
|
|
65
68
|
* Subscribes to live reactive query updates from Convex.
|
|
66
69
|
*/
|
|
67
|
-
subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): void;
|
|
70
|
+
subscribeToLiveChanges(callback: (changes: DeltaChanges) => void, scope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>)): () => void;
|
|
71
|
+
setSyncScope(scope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>)): void;
|
|
72
|
+
private refreshLiveSubscription;
|
|
68
73
|
/**
|
|
69
74
|
* Cleans up live subscriptions.
|
|
70
75
|
*/
|
|
@@ -34,6 +34,9 @@ class ConvexRemoteAdapter {
|
|
|
34
34
|
deletedColumn;
|
|
35
35
|
updatedAtColumn;
|
|
36
36
|
unsubscribeLive;
|
|
37
|
+
liveCallback;
|
|
38
|
+
liveScope;
|
|
39
|
+
liveGeneration = 0;
|
|
37
40
|
logger;
|
|
38
41
|
constructor(client, options = {}) {
|
|
39
42
|
if (!client) {
|
|
@@ -90,11 +93,12 @@ class ConvexRemoteAdapter {
|
|
|
90
93
|
/**
|
|
91
94
|
* Fetches delta changes from Convex since a given timestamp.
|
|
92
95
|
*/
|
|
93
|
-
async fetchChanges(sinceTimestamp) {
|
|
96
|
+
async fetchChanges(sinceTimestamp, scope) {
|
|
94
97
|
try {
|
|
95
98
|
const res = await this.client.query(this.pullQuery, {
|
|
96
99
|
sinceTimestamp,
|
|
97
100
|
tables: this.tables,
|
|
101
|
+
...(scope ? { scope } : {}),
|
|
98
102
|
});
|
|
99
103
|
if (!res) {
|
|
100
104
|
return { timestamp: sinceTimestamp, changes: [] };
|
|
@@ -145,56 +149,85 @@ class ConvexRemoteAdapter {
|
|
|
145
149
|
/**
|
|
146
150
|
* Subscribes to live reactive query updates from Convex.
|
|
147
151
|
*/
|
|
148
|
-
subscribeToLiveChanges(callback) {
|
|
149
|
-
|
|
152
|
+
subscribeToLiveChanges(callback, scope) {
|
|
153
|
+
this.liveCallback = callback;
|
|
154
|
+
this.liveScope = scope;
|
|
155
|
+
this.refreshLiveSubscription();
|
|
156
|
+
return () => {
|
|
157
|
+
if (this.liveCallback !== callback)
|
|
158
|
+
return;
|
|
159
|
+
this.liveCallback = undefined;
|
|
160
|
+
this.destroy();
|
|
161
|
+
};
|
|
162
|
+
}
|
|
163
|
+
setSyncScope(scope) {
|
|
164
|
+
this.liveScope = scope;
|
|
165
|
+
if (this.liveCallback)
|
|
166
|
+
this.refreshLiveSubscription();
|
|
167
|
+
}
|
|
168
|
+
refreshLiveSubscription() {
|
|
169
|
+
this.unsubscribeLive?.();
|
|
170
|
+
this.unsubscribeLive = undefined;
|
|
171
|
+
const generation = ++this.liveGeneration;
|
|
172
|
+
const callback = this.liveCallback;
|
|
173
|
+
if (!callback || typeof this.client.onUpdate !== 'function')
|
|
150
174
|
return;
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
changes
|
|
164
|
-
|
|
175
|
+
const subscribe = (scope) => {
|
|
176
|
+
if (generation !== this.liveGeneration || this.liveCallback !== callback)
|
|
177
|
+
return;
|
|
178
|
+
try {
|
|
179
|
+
const unsubscribe = this.client.onUpdate(this.pullQuery, { sinceTimestamp: Date.now() - 2000, tables: this.tables, ...(scope ? { scope } : {}) }, (data) => {
|
|
180
|
+
if (generation !== this.liveGeneration || !data)
|
|
181
|
+
return;
|
|
182
|
+
if (data.changes && Array.isArray(data.changes)) {
|
|
183
|
+
callback({ timestamp: Number(data.timestamp || Date.now()), changes: data.changes });
|
|
184
|
+
return;
|
|
185
|
+
}
|
|
186
|
+
if (Array.isArray(data) && data.length > 0) {
|
|
187
|
+
const changes = data.map((row) => {
|
|
188
|
+
const isSoftDeleted = Boolean(row[this.deletedColumn] === true);
|
|
189
|
+
const op = isSoftDeleted ? 'DELETE' : 'UPDATE';
|
|
190
|
+
const rowTime = getRowTimestamp(row[this.updatedAtColumn], row._creationTime);
|
|
191
|
+
const rowId = getRowId(row, this.primaryKey);
|
|
192
|
+
const tableName = row.tableName || row._table || (this.tables[0] ?? 'default');
|
|
193
|
+
return { tableName, operation: op, rowId, payload: isSoftDeleted ? null : row, timestamp: rowTime };
|
|
194
|
+
});
|
|
195
|
+
const maxTime = Math.max(...changes.map((change) => change.timestamp || 0));
|
|
196
|
+
callback({ timestamp: maxTime > 0 ? maxTime : Date.now(), changes });
|
|
197
|
+
}
|
|
198
|
+
});
|
|
199
|
+
if (generation !== this.liveGeneration) {
|
|
200
|
+
if (typeof unsubscribe === 'function')
|
|
201
|
+
unsubscribe();
|
|
165
202
|
return;
|
|
166
203
|
}
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
callback({
|
|
184
|
-
timestamp: maxTime > 0 ? maxTime : Date.now(),
|
|
185
|
-
changes,
|
|
186
|
-
});
|
|
187
|
-
}
|
|
188
|
-
});
|
|
204
|
+
this.unsubscribeLive = typeof unsubscribe === 'function' ? unsubscribe : undefined;
|
|
205
|
+
}
|
|
206
|
+
catch (err) {
|
|
207
|
+
console.warn('ConvexRemoteAdapter live subscription failed to initialize:', err);
|
|
208
|
+
}
|
|
209
|
+
};
|
|
210
|
+
try {
|
|
211
|
+
const scopeResult = typeof this.liveScope === 'function' ? this.liveScope() : this.liveScope;
|
|
212
|
+
if (scopeResult && typeof scopeResult.then === 'function') {
|
|
213
|
+
void Promise.resolve(scopeResult).then(subscribe).catch((err) => {
|
|
214
|
+
console.warn('ConvexRemoteAdapter live scope failed to resolve:', err);
|
|
215
|
+
});
|
|
216
|
+
}
|
|
217
|
+
else {
|
|
218
|
+
subscribe(scopeResult);
|
|
219
|
+
}
|
|
189
220
|
}
|
|
190
221
|
catch (err) {
|
|
191
|
-
console.warn('ConvexRemoteAdapter live
|
|
222
|
+
console.warn('ConvexRemoteAdapter live scope failed to resolve:', err);
|
|
192
223
|
}
|
|
193
224
|
}
|
|
194
225
|
/**
|
|
195
226
|
* Cleans up live subscriptions.
|
|
196
227
|
*/
|
|
197
228
|
destroy() {
|
|
229
|
+
this.liveGeneration++;
|
|
230
|
+
this.liveCallback = undefined;
|
|
198
231
|
if (this.unsubscribeLive) {
|
|
199
232
|
this.unsubscribeLive();
|
|
200
233
|
this.unsubscribeLive = undefined;
|
|
@@ -4,7 +4,8 @@ export interface RemoteDBAdapter {
|
|
|
4
4
|
/** Return a complete batch through timestamp; reject on partial failure. Supports optional scope for data filtering. */
|
|
5
5
|
fetchChanges(sinceTimestamp: number, scope?: Record<string, any>): Promise<DeltaChanges>;
|
|
6
6
|
/** Live events do not advance the durable pull checkpoint. Return cleanup when supported. */
|
|
7
|
-
subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): void | (() => void);
|
|
7
|
+
subscribeToLiveChanges(callback: (changes: DeltaChanges) => void, scope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>)): void | (() => void);
|
|
8
|
+
setSyncScope?(scope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>)): void;
|
|
8
9
|
}
|
|
9
10
|
export * from './supabase.js';
|
|
10
11
|
export * from './demo.js';
|
package/dist/core/client.d.ts
CHANGED
|
@@ -2,6 +2,7 @@ import { LocalDBAdapter, LocalTransaction } from '../adapters/local/index.js';
|
|
|
2
2
|
import { RemoteDBAdapter } from '../adapters/remote/index.js';
|
|
3
3
|
import { EventEmitter } from '../reactive/event-emitter.js';
|
|
4
4
|
import { SyncWorker } from './sync-worker.js';
|
|
5
|
+
import { type OutboxDeleteClause } from './outbox-store.js';
|
|
5
6
|
import { DatabaseMaintenance } from './maintenance.js';
|
|
6
7
|
import { SchemaManager } from './schema-manager.js';
|
|
7
8
|
import { BatchMutation, ConflictResolver, ConflictStrategy, MutateOptions, NetworkStatusProvider, OutboxRecord, OutboxStatus, QueryOptions, RetryConfig, SchemaMigration, SyncMetrics, SyncOp, TableChangeEvent, WhereFilter } from './types.js';
|
|
@@ -326,6 +327,11 @@ export declare class LocalFirstClient {
|
|
|
326
327
|
limit?: number;
|
|
327
328
|
offset?: number;
|
|
328
329
|
}): Promise<OutboxRecord[]>;
|
|
330
|
+
/**
|
|
331
|
+
* Deletes outbox entries matching one or more filter clauses. Intended for
|
|
332
|
+
* application cleanup of intentionally local-only or obsolete operations.
|
|
333
|
+
*/
|
|
334
|
+
deleteOutboxRecords(clauses: OutboxDeleteClause[]): Promise<void>;
|
|
329
335
|
/**
|
|
330
336
|
* Re-queues failed outbox mutations for retry by resetting their status to PENDING.
|
|
331
337
|
* Triggers an immediate sync push.
|
package/dist/core/client.js
CHANGED
|
@@ -1027,6 +1027,16 @@ class LocalFirstClient {
|
|
|
1027
1027
|
async getOutboxRecords(options) {
|
|
1028
1028
|
return await outbox_store_js_1.OutboxStore.getAllRecords(this.db, options);
|
|
1029
1029
|
}
|
|
1030
|
+
/**
|
|
1031
|
+
* Deletes outbox entries matching one or more filter clauses. Intended for
|
|
1032
|
+
* application cleanup of intentionally local-only or obsolete operations.
|
|
1033
|
+
*/
|
|
1034
|
+
async deleteOutboxRecords(clauses) {
|
|
1035
|
+
if (clauses.length === 0)
|
|
1036
|
+
return;
|
|
1037
|
+
await outbox_store_js_1.OutboxStore.deleteMatching(this.db, clauses);
|
|
1038
|
+
this.events.emit('sync_outbox', { operation: 'DELETE', rowId: 'filtered' });
|
|
1039
|
+
}
|
|
1030
1040
|
/**
|
|
1031
1041
|
* Re-queues failed outbox mutations for retry by resetting their status to PENDING.
|
|
1032
1042
|
* Triggers an immediate sync push.
|
|
@@ -16,13 +16,13 @@ export declare class MetaStore {
|
|
|
16
16
|
/**
|
|
17
17
|
* Retrieves the persisted last_synced_at cursor timestamp (in ms). Returns 0 if never synced.
|
|
18
18
|
*/
|
|
19
|
-
static getLastSyncedAt(db: LocalDBAdapter): Promise<number>;
|
|
19
|
+
static getLastSyncedAt(db: LocalDBAdapter, key?: string): Promise<number>;
|
|
20
20
|
/**
|
|
21
21
|
* Persists the last_synced_at cursor timestamp.
|
|
22
22
|
*/
|
|
23
|
-
static setLastSyncedAt(db: LocalDBAdapter | LocalTransaction, timestamp: number): Promise<void>;
|
|
23
|
+
static setLastSyncedAt(db: LocalDBAdapter | LocalTransaction, timestamp: number, key?: string): Promise<void>;
|
|
24
24
|
/**
|
|
25
25
|
* Clears the persisted cursor (forces next pull to re-query active remote records).
|
|
26
26
|
*/
|
|
27
|
-
static clearLastSyncedAt(db: LocalDBAdapter | LocalTransaction): Promise<void>;
|
|
27
|
+
static clearLastSyncedAt(db: LocalDBAdapter | LocalTransaction, key?: string): Promise<void>;
|
|
28
28
|
}
|
package/dist/core/meta-store.js
CHANGED
|
@@ -36,8 +36,8 @@ class MetaStore {
|
|
|
36
36
|
/**
|
|
37
37
|
* Retrieves the persisted last_synced_at cursor timestamp (in ms). Returns 0 if never synced.
|
|
38
38
|
*/
|
|
39
|
-
static async getLastSyncedAt(db) {
|
|
40
|
-
const val = await this.get(db,
|
|
39
|
+
static async getLastSyncedAt(db, key = 'last_synced_at') {
|
|
40
|
+
const val = await this.get(db, key);
|
|
41
41
|
if (!val)
|
|
42
42
|
return 0;
|
|
43
43
|
const parsed = parseInt(val, 10);
|
|
@@ -46,15 +46,15 @@ class MetaStore {
|
|
|
46
46
|
/**
|
|
47
47
|
* Persists the last_synced_at cursor timestamp.
|
|
48
48
|
*/
|
|
49
|
-
static async setLastSyncedAt(db, timestamp) {
|
|
50
|
-
await this.set(db,
|
|
49
|
+
static async setLastSyncedAt(db, timestamp, key = 'last_synced_at') {
|
|
50
|
+
await this.set(db, key, String(timestamp));
|
|
51
51
|
}
|
|
52
52
|
/**
|
|
53
53
|
* Clears the persisted cursor (forces next pull to re-query active remote records).
|
|
54
54
|
*/
|
|
55
|
-
static async clearLastSyncedAt(db) {
|
|
55
|
+
static async clearLastSyncedAt(db, key = 'last_synced_at') {
|
|
56
56
|
try {
|
|
57
|
-
await db.execute(`DELETE FROM sync_meta WHERE key =
|
|
57
|
+
await db.execute(`DELETE FROM sync_meta WHERE key = ?`, [key]);
|
|
58
58
|
}
|
|
59
59
|
catch {
|
|
60
60
|
// Ignored if table doesn't exist yet
|
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
import { LocalDBAdapter, LocalTransaction } from '../adapters/local/index.js';
|
|
2
2
|
import { OutboxRecord, OutboxStatus, SyncOp, SyncOperation } from './types.js';
|
|
3
|
+
export type OutboxFilterValue = string | number | boolean | null;
|
|
4
|
+
export interface OutboxDeleteClause {
|
|
5
|
+
tableName?: string;
|
|
6
|
+
operation?: string;
|
|
7
|
+
rowIds?: string[];
|
|
8
|
+
payloadIn?: Record<string, OutboxFilterValue[]>;
|
|
9
|
+
}
|
|
3
10
|
export declare class OutboxStore {
|
|
4
11
|
/**
|
|
5
12
|
* Initializes the sync_outbox schema if it does not already exist.
|
|
@@ -39,6 +46,8 @@ export declare class OutboxStore {
|
|
|
39
46
|
* Deletes a batch of successfully pushed outbox entries.
|
|
40
47
|
*/
|
|
41
48
|
static deleteCompleted(db: LocalDBAdapter, ids: string[]): Promise<void>;
|
|
49
|
+
/** Deletes outbox records matching one or more safe, parameterized clauses. */
|
|
50
|
+
static deleteMatching(db: LocalDBAdapter, clauses: OutboxDeleteClause[]): Promise<void>;
|
|
42
51
|
/**
|
|
43
52
|
* Deletes a single outbox record within an active transaction.
|
|
44
53
|
*/
|
|
@@ -162,6 +162,37 @@ class OutboxStore {
|
|
|
162
162
|
const placeholders = ids.map(() => '?').join(',');
|
|
163
163
|
await db.execute(`DELETE FROM sync_outbox WHERE id IN (${placeholders})`, ids);
|
|
164
164
|
}
|
|
165
|
+
/** Deletes outbox records matching one or more safe, parameterized clauses. */
|
|
166
|
+
static async deleteMatching(db, clauses) {
|
|
167
|
+
const alternatives = [];
|
|
168
|
+
const params = [];
|
|
169
|
+
for (const clause of clauses) {
|
|
170
|
+
const conditions = [];
|
|
171
|
+
if (clause.tableName) {
|
|
172
|
+
conditions.push('table_name = ?');
|
|
173
|
+
params.push(clause.tableName);
|
|
174
|
+
}
|
|
175
|
+
if (clause.operation) {
|
|
176
|
+
conditions.push('operation = ?');
|
|
177
|
+
params.push(clause.operation);
|
|
178
|
+
}
|
|
179
|
+
if (clause.rowIds?.length) {
|
|
180
|
+
conditions.push(`row_id IN (${clause.rowIds.map(() => '?').join(',')})`);
|
|
181
|
+
params.push(...clause.rowIds);
|
|
182
|
+
}
|
|
183
|
+
for (const [field, values] of Object.entries(clause.payloadIn ?? {})) {
|
|
184
|
+
if (!/^[A-Za-z0-9_]+$/.test(field) || values.length === 0)
|
|
185
|
+
continue;
|
|
186
|
+
conditions.push(`json_extract(CASE WHEN json_valid(payload) THEN payload ELSE '{}' END, ?) IN (${values.map(() => '?').join(',')})`);
|
|
187
|
+
params.push(`$.${field}`, ...values);
|
|
188
|
+
}
|
|
189
|
+
if (conditions.length > 0)
|
|
190
|
+
alternatives.push(`(${conditions.join(' AND ')})`);
|
|
191
|
+
}
|
|
192
|
+
if (alternatives.length === 0)
|
|
193
|
+
return;
|
|
194
|
+
await db.execute(`DELETE FROM sync_outbox WHERE ${alternatives.join(' OR ')}`, params);
|
|
195
|
+
}
|
|
165
196
|
/**
|
|
166
197
|
* Deletes a single outbox record within an active transaction.
|
|
167
198
|
*/
|
|
@@ -49,6 +49,8 @@ export declare class SyncWorker {
|
|
|
49
49
|
private isPulling;
|
|
50
50
|
private lastPulledTimestamp;
|
|
51
51
|
private cursorLoaded;
|
|
52
|
+
private lastSyncedAtKey;
|
|
53
|
+
private pullRequested;
|
|
52
54
|
private deltaQueue;
|
|
53
55
|
private statusRun?;
|
|
54
56
|
private statusRerunRequested;
|
|
@@ -115,10 +117,14 @@ export declare class SyncWorker {
|
|
|
115
117
|
*/
|
|
116
118
|
applyDeltasLocally(deltas: DeltaChanges, options?: {
|
|
117
119
|
advanceCursor?: boolean;
|
|
120
|
+
cursorKey?: string;
|
|
118
121
|
}): Promise<void>;
|
|
119
122
|
private processDeltasLocally;
|
|
120
123
|
getLastPulledTimestamp(): Promise<number>;
|
|
124
|
+
private loadCursor;
|
|
121
125
|
resetSyncCursor(): Promise<void>;
|
|
126
|
+
/** Clears a stale push error after an explicit sync stop/reconfiguration. */
|
|
127
|
+
clearPushError(): void;
|
|
122
128
|
/**
|
|
123
129
|
* Collects real-time engine telemetry snapshot.
|
|
124
130
|
*/
|
package/dist/core/sync-worker.js
CHANGED
|
@@ -13,6 +13,17 @@ const REACT_NATIVE_PKG = ['react', 'native'].join('-');
|
|
|
13
13
|
const PUSH_BATCH_SIZE = 50;
|
|
14
14
|
/** Maximum incoming delta changes applied in a single database transaction. */
|
|
15
15
|
const DELTA_CHUNK_SIZE = 250;
|
|
16
|
+
function stableScopeValue(value) {
|
|
17
|
+
if (Array.isArray(value))
|
|
18
|
+
return value.map(stableScopeValue);
|
|
19
|
+
if (value && typeof value === 'object') {
|
|
20
|
+
return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableScopeValue(value[key])]));
|
|
21
|
+
}
|
|
22
|
+
return value;
|
|
23
|
+
}
|
|
24
|
+
function getScopeCursorKey(scope) {
|
|
25
|
+
return scope === undefined ? 'last_synced_at' : `last_synced_at:scope:${JSON.stringify(stableScopeValue(scope))}`;
|
|
26
|
+
}
|
|
16
27
|
class SyncWorker {
|
|
17
28
|
db;
|
|
18
29
|
remote;
|
|
@@ -42,6 +53,8 @@ class SyncWorker {
|
|
|
42
53
|
isPulling = false;
|
|
43
54
|
lastPulledTimestamp = 0;
|
|
44
55
|
cursorLoaded = false;
|
|
56
|
+
lastSyncedAtKey = 'last_synced_at';
|
|
57
|
+
pullRequested = false;
|
|
45
58
|
deltaQueue = Promise.resolve();
|
|
46
59
|
statusRun;
|
|
47
60
|
statusRerunRequested = false;
|
|
@@ -129,7 +142,7 @@ class SyncWorker {
|
|
|
129
142
|
this.applyDeltasLocally(deltas, { advanceCursor: false }).catch((err) => {
|
|
130
143
|
this.logger.error('Error applying live remote deltas:', err);
|
|
131
144
|
});
|
|
132
|
-
});
|
|
145
|
+
}, this.syncScope);
|
|
133
146
|
if (typeof unsubscribe === 'function')
|
|
134
147
|
this.remoteUnsubscribe = unsubscribe;
|
|
135
148
|
// Subscribe to network connectivity changes (only pull on actual offline -> online transition)
|
|
@@ -316,6 +329,10 @@ class SyncWorker {
|
|
|
316
329
|
*/
|
|
317
330
|
setSyncScope(scope) {
|
|
318
331
|
this.syncScope = scope;
|
|
332
|
+
this.remote.setSyncScope?.(scope);
|
|
333
|
+
if (this.automaticSync && !this.isPaused) {
|
|
334
|
+
this.pullRemoteChanges().catch((err) => this.logger.error('Error pulling after sync scope change:', err));
|
|
335
|
+
}
|
|
319
336
|
}
|
|
320
337
|
async isOnline() {
|
|
321
338
|
try {
|
|
@@ -526,8 +543,12 @@ class SyncWorker {
|
|
|
526
543
|
* Pulls delta changes from the remote backend since lastPulledTimestamp.
|
|
527
544
|
*/
|
|
528
545
|
async pullRemoteChanges() {
|
|
529
|
-
if (this.
|
|
546
|
+
if (this.isPaused)
|
|
547
|
+
return;
|
|
548
|
+
if (this.isPulling) {
|
|
549
|
+
this.pullRequested = true;
|
|
530
550
|
return;
|
|
551
|
+
}
|
|
531
552
|
this.isPulling = true;
|
|
532
553
|
this.emitStatus();
|
|
533
554
|
const startTime = Date.now();
|
|
@@ -535,14 +556,13 @@ class SyncWorker {
|
|
|
535
556
|
if (!(await this.isOnline()))
|
|
536
557
|
return;
|
|
537
558
|
this.totalPullCycles++;
|
|
538
|
-
if (!this.cursorLoaded) {
|
|
539
|
-
this.lastPulledTimestamp = await meta_store_js_1.MetaStore.getLastSyncedAt(this.db);
|
|
540
|
-
this.cursorLoaded = true;
|
|
541
|
-
}
|
|
542
559
|
const scope = typeof this.syncScope === 'function' ? await this.syncScope() : this.syncScope;
|
|
560
|
+
const cursorKey = getScopeCursorKey(scope);
|
|
561
|
+
await this.loadCursor(cursorKey);
|
|
562
|
+
const sinceTimestamp = this.lastPulledTimestamp;
|
|
543
563
|
const deltas = scope !== undefined
|
|
544
|
-
? await this.remote.fetchChanges(
|
|
545
|
-
: await this.remote.fetchChanges(
|
|
564
|
+
? await this.remote.fetchChanges(sinceTimestamp, scope)
|
|
565
|
+
: await this.remote.fetchChanges(sinceTimestamp);
|
|
546
566
|
const durationMs = Date.now() - startTime;
|
|
547
567
|
this.lastPullDurationMs = durationMs;
|
|
548
568
|
this.lastPullTimestamp = Date.now();
|
|
@@ -550,10 +570,11 @@ class SyncWorker {
|
|
|
550
570
|
const changesCount = deltas?.changes?.length || 0;
|
|
551
571
|
if (deltas) {
|
|
552
572
|
this.totalPulledDeltas += changesCount;
|
|
553
|
-
await this.applyDeltasLocally(deltas);
|
|
554
|
-
if (deltas.timestamp && deltas.timestamp >
|
|
555
|
-
|
|
556
|
-
|
|
573
|
+
await this.applyDeltasLocally(deltas, { cursorKey });
|
|
574
|
+
if (deltas.timestamp && deltas.timestamp > sinceTimestamp) {
|
|
575
|
+
if (cursorKey === this.lastSyncedAtKey)
|
|
576
|
+
this.lastPulledTimestamp = deltas.timestamp;
|
|
577
|
+
await meta_store_js_1.MetaStore.setLastSyncedAt(this.db, deltas.timestamp, cursorKey);
|
|
557
578
|
}
|
|
558
579
|
}
|
|
559
580
|
const pullEvent = {
|
|
@@ -584,6 +605,10 @@ class SyncWorker {
|
|
|
584
605
|
finally {
|
|
585
606
|
this.isPulling = false;
|
|
586
607
|
this.emitStatus();
|
|
608
|
+
if (this.pullRequested && !this.isPaused) {
|
|
609
|
+
this.pullRequested = false;
|
|
610
|
+
void this.pullRemoteChanges();
|
|
611
|
+
}
|
|
587
612
|
}
|
|
588
613
|
}
|
|
589
614
|
/**
|
|
@@ -592,18 +617,21 @@ class SyncWorker {
|
|
|
592
617
|
*/
|
|
593
618
|
async applyDeltasLocally(deltas, options = {}) {
|
|
594
619
|
const task = async () => {
|
|
595
|
-
|
|
596
|
-
|
|
620
|
+
const cursorKey = options.cursorKey ?? this.lastSyncedAtKey;
|
|
621
|
+
if (options.advanceCursor !== false)
|
|
622
|
+
await this.loadCursor(cursorKey);
|
|
623
|
+
await this.processDeltasLocally(options.advanceCursor === false ? { ...deltas, timestamp: 0 } : deltas, cursorKey);
|
|
597
624
|
};
|
|
598
625
|
const next = this.deltaQueue.then(task, task);
|
|
599
626
|
this.deltaQueue = next.catch(() => { });
|
|
600
627
|
return await next;
|
|
601
628
|
}
|
|
602
|
-
async processDeltasLocally(deltas) {
|
|
629
|
+
async processDeltasLocally(deltas, cursorKey = this.lastSyncedAtKey) {
|
|
603
630
|
if (!deltas.changes || deltas.changes.length === 0) {
|
|
604
|
-
if (deltas.timestamp && deltas.timestamp > this.lastPulledTimestamp) {
|
|
605
|
-
await meta_store_js_1.MetaStore.setLastSyncedAt(this.db, deltas.timestamp);
|
|
606
|
-
|
|
631
|
+
if (deltas.timestamp && (cursorKey !== this.lastSyncedAtKey || deltas.timestamp > this.lastPulledTimestamp)) {
|
|
632
|
+
await meta_store_js_1.MetaStore.setLastSyncedAt(this.db, deltas.timestamp, cursorKey);
|
|
633
|
+
if (cursorKey === this.lastSyncedAtKey)
|
|
634
|
+
this.lastPulledTimestamp = deltas.timestamp;
|
|
607
635
|
}
|
|
608
636
|
return;
|
|
609
637
|
}
|
|
@@ -670,9 +698,10 @@ class SyncWorker {
|
|
|
670
698
|
});
|
|
671
699
|
}
|
|
672
700
|
// Advance durable checkpoint only when a valid pull timestamp was provided
|
|
673
|
-
if (isLastChunk && deltas.timestamp && deltas.timestamp > this.lastPulledTimestamp) {
|
|
674
|
-
await meta_store_js_1.MetaStore.setLastSyncedAt(tx, deltas.timestamp);
|
|
675
|
-
|
|
701
|
+
if (isLastChunk && deltas.timestamp && (cursorKey !== this.lastSyncedAtKey || deltas.timestamp > this.lastPulledTimestamp)) {
|
|
702
|
+
await meta_store_js_1.MetaStore.setLastSyncedAt(tx, deltas.timestamp, cursorKey);
|
|
703
|
+
if (cursorKey === this.lastSyncedAtKey)
|
|
704
|
+
this.lastPulledTimestamp = deltas.timestamp;
|
|
676
705
|
}
|
|
677
706
|
});
|
|
678
707
|
// Emit events after chunk commit
|
|
@@ -684,22 +713,36 @@ class SyncWorker {
|
|
|
684
713
|
await new Promise((resolve) => setTimeout(resolve, 0));
|
|
685
714
|
}
|
|
686
715
|
}
|
|
687
|
-
if (deltas.timestamp) {
|
|
716
|
+
if (deltas.timestamp && cursorKey === this.lastSyncedAtKey) {
|
|
688
717
|
this.lastPulledTimestamp = Math.max(this.lastPulledTimestamp, deltas.timestamp);
|
|
689
718
|
}
|
|
690
719
|
}
|
|
691
720
|
async getLastPulledTimestamp() {
|
|
721
|
+
const scope = typeof this.syncScope === 'function' ? await this.syncScope() : this.syncScope;
|
|
722
|
+
await this.loadCursor(getScopeCursorKey(scope));
|
|
723
|
+
return this.lastPulledTimestamp;
|
|
724
|
+
}
|
|
725
|
+
async loadCursor(key) {
|
|
726
|
+
if (key !== this.lastSyncedAtKey) {
|
|
727
|
+
this.lastSyncedAtKey = key;
|
|
728
|
+
this.cursorLoaded = false;
|
|
729
|
+
this.lastPulledTimestamp = 0;
|
|
730
|
+
}
|
|
692
731
|
if (!this.cursorLoaded) {
|
|
693
|
-
this.lastPulledTimestamp = await meta_store_js_1.MetaStore.getLastSyncedAt(this.db);
|
|
732
|
+
this.lastPulledTimestamp = await meta_store_js_1.MetaStore.getLastSyncedAt(this.db, key);
|
|
694
733
|
this.cursorLoaded = true;
|
|
695
734
|
}
|
|
696
|
-
return this.lastPulledTimestamp;
|
|
697
735
|
}
|
|
698
736
|
async resetSyncCursor() {
|
|
699
|
-
await meta_store_js_1.MetaStore.clearLastSyncedAt(this.db);
|
|
737
|
+
await meta_store_js_1.MetaStore.clearLastSyncedAt(this.db, this.lastSyncedAtKey);
|
|
700
738
|
this.lastPulledTimestamp = 0;
|
|
701
739
|
this.cursorLoaded = true;
|
|
702
740
|
}
|
|
741
|
+
/** Clears a stale push error after an explicit sync stop/reconfiguration. */
|
|
742
|
+
clearPushError() {
|
|
743
|
+
this.lastPushError = null;
|
|
744
|
+
this.emitStatus();
|
|
745
|
+
}
|
|
703
746
|
/**
|
|
704
747
|
* Collects real-time engine telemetry snapshot.
|
|
705
748
|
*/
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
export type ApiMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
|
|
2
|
+
export interface ApiRequestContext<TConfig = unknown> {
|
|
3
|
+
request: Request;
|
|
4
|
+
config: TConfig;
|
|
5
|
+
path: string;
|
|
6
|
+
params: Record<string, string>;
|
|
7
|
+
}
|
|
8
|
+
export type ApiHandler<TConfig = unknown> = (context: ApiRequestContext<TConfig>) => Response | Promise<Response>;
|
|
9
|
+
export type ApiMiddleware<TConfig = unknown> = (context: ApiRequestContext<TConfig>, next: () => Promise<Response>) => Response | Promise<Response>;
|
|
10
|
+
export type ApiEndpoint<TConfig = unknown> = Partial<Record<ApiMethod, ApiHandler<TConfig>>>;
|
|
11
|
+
export interface ServerConfig<TConfig = unknown> {
|
|
12
|
+
/** Server-only services and provider configuration passed to endpoint handlers. */
|
|
13
|
+
config: TConfig;
|
|
14
|
+
/** Explicit endpoint map. Keys are URL patterns such as `/api/bookings/:bookingId`. */
|
|
15
|
+
endpoints: Record<string, ApiEndpoint<TConfig>>;
|
|
16
|
+
/** Middleware applied to every generated endpoint, in declaration order. */
|
|
17
|
+
middleware?: ApiMiddleware<TConfig>[];
|
|
18
|
+
/** Safe error hook for server-side reporting. Response details are not exposed to clients. */
|
|
19
|
+
onError?: (error: unknown, context: ApiRequestContext<TConfig>) => void;
|
|
20
|
+
}
|
|
21
|
+
export type GeneratedApiHandlers = Record<string, Partial<Record<ApiMethod, (request: Request) => Promise<Response>>>>;
|
|
22
|
+
/** Define and validate an app's server/API configuration. */
|
|
23
|
+
export declare function defineServerConfig<TConfig>(config: ServerConfig<TConfig>): ServerConfig<TConfig>;
|
|
24
|
+
/**
|
|
25
|
+
* Build framework-neutral Request/Response handlers from one server config.
|
|
26
|
+
* App route files can re-export a generated method handler, while tests and
|
|
27
|
+
* custom servers can use `fetch()` as a single dispatcher.
|
|
28
|
+
*/
|
|
29
|
+
export declare function createServer<TConfig>(config: ServerConfig<TConfig>): {
|
|
30
|
+
handlers: GeneratedApiHandlers;
|
|
31
|
+
handler(path: string, method: ApiMethod): (request: Request) => Promise<Response>;
|
|
32
|
+
fetch(request: Request): Promise<Response>;
|
|
33
|
+
};
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.defineServerConfig = defineServerConfig;
|
|
4
|
+
exports.createServer = createServer;
|
|
5
|
+
function normalizePath(path) {
|
|
6
|
+
const normalized = `/${path.split('/').filter(Boolean).join('/')}`;
|
|
7
|
+
return normalized === '/' ? normalized : normalized.replace(/\/$/, '');
|
|
8
|
+
}
|
|
9
|
+
function matchPath(pattern, pathname) {
|
|
10
|
+
const patternSegments = normalizePath(pattern).split('/').filter(Boolean);
|
|
11
|
+
const pathSegments = normalizePath(pathname).split('/').filter(Boolean);
|
|
12
|
+
if (patternSegments.length !== pathSegments.length)
|
|
13
|
+
return null;
|
|
14
|
+
const params = {};
|
|
15
|
+
for (let index = 0; index < patternSegments.length; index += 1) {
|
|
16
|
+
const expected = patternSegments[index];
|
|
17
|
+
const actual = pathSegments[index];
|
|
18
|
+
if (expected.startsWith(':')) {
|
|
19
|
+
try {
|
|
20
|
+
params[expected.slice(1)] = decodeURIComponent(actual);
|
|
21
|
+
}
|
|
22
|
+
catch {
|
|
23
|
+
return null;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
else if (expected !== actual) {
|
|
27
|
+
return null;
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
return params;
|
|
31
|
+
}
|
|
32
|
+
function methodNotAllowed(methods) {
|
|
33
|
+
return Response.json({ error: 'Method Not Allowed' }, { status: 405, headers: { Allow: methods.join(', ') } });
|
|
34
|
+
}
|
|
35
|
+
/** Define and validate an app's server/API configuration. */
|
|
36
|
+
function defineServerConfig(config) {
|
|
37
|
+
for (const [path, endpoint] of Object.entries(config.endpoints)) {
|
|
38
|
+
if (!path.startsWith('/'))
|
|
39
|
+
throw new TypeError(`API endpoint path must start with '/': ${path}`);
|
|
40
|
+
if (!Object.values(endpoint).some(handler => typeof handler === 'function')) {
|
|
41
|
+
throw new TypeError(`API endpoint '${path}' must define at least one method handler.`);
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
return config;
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Build framework-neutral Request/Response handlers from one server config.
|
|
48
|
+
* App route files can re-export a generated method handler, while tests and
|
|
49
|
+
* custom servers can use `fetch()` as a single dispatcher.
|
|
50
|
+
*/
|
|
51
|
+
function createServer(config) {
|
|
52
|
+
const definitions = Object.entries(config.endpoints).map(([path, endpoint]) => ({
|
|
53
|
+
path: normalizePath(path),
|
|
54
|
+
endpoint,
|
|
55
|
+
}));
|
|
56
|
+
const run = async (request, pathPattern, endpoint) => {
|
|
57
|
+
const method = request.method.toUpperCase();
|
|
58
|
+
const url = new URL(request.url);
|
|
59
|
+
const params = matchPath(pathPattern, url.pathname);
|
|
60
|
+
const handler = endpoint[method];
|
|
61
|
+
const context = {
|
|
62
|
+
request,
|
|
63
|
+
config: config.config,
|
|
64
|
+
path: pathPattern,
|
|
65
|
+
params: params ?? {},
|
|
66
|
+
};
|
|
67
|
+
if (!params)
|
|
68
|
+
return Response.json({ error: 'Not Found' }, { status: 404 });
|
|
69
|
+
if (!handler)
|
|
70
|
+
return methodNotAllowed(Object.keys(endpoint));
|
|
71
|
+
const stack = config.middleware ?? [];
|
|
72
|
+
let index = -1;
|
|
73
|
+
const dispatch = async (position) => {
|
|
74
|
+
if (position <= index)
|
|
75
|
+
throw new Error('API middleware called next() more than once.');
|
|
76
|
+
index = position;
|
|
77
|
+
const middleware = stack[position];
|
|
78
|
+
if (!middleware)
|
|
79
|
+
return await handler(context);
|
|
80
|
+
return await middleware(context, () => dispatch(position + 1));
|
|
81
|
+
};
|
|
82
|
+
try {
|
|
83
|
+
return await dispatch(0);
|
|
84
|
+
}
|
|
85
|
+
catch (error) {
|
|
86
|
+
try {
|
|
87
|
+
config.onError?.(error, context);
|
|
88
|
+
}
|
|
89
|
+
catch {
|
|
90
|
+
// Reporting failures must not replace the original generic API response.
|
|
91
|
+
}
|
|
92
|
+
return Response.json({ error: 'Internal Server Error' }, { status: 500 });
|
|
93
|
+
}
|
|
94
|
+
};
|
|
95
|
+
const handlers = {};
|
|
96
|
+
for (const { path, endpoint } of definitions) {
|
|
97
|
+
handlers[path] = {};
|
|
98
|
+
for (const method of Object.keys(endpoint)) {
|
|
99
|
+
handlers[path][method] = (request) => run(request, path, endpoint);
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
return {
|
|
103
|
+
handlers,
|
|
104
|
+
handler(path, method) {
|
|
105
|
+
const normalized = normalizePath(path);
|
|
106
|
+
const definition = definitions.find(item => item.path === normalized);
|
|
107
|
+
if (!definition || !definition.endpoint[method]) {
|
|
108
|
+
throw new Error(`No ${method} API handler is configured for '${normalized}'.`);
|
|
109
|
+
}
|
|
110
|
+
return (request) => run(request, definition.path, definition.endpoint);
|
|
111
|
+
},
|
|
112
|
+
async fetch(request) {
|
|
113
|
+
const url = new URL(request.url);
|
|
114
|
+
const method = request.method.toUpperCase();
|
|
115
|
+
let pathMatched = false;
|
|
116
|
+
for (const definition of definitions) {
|
|
117
|
+
if (!matchPath(definition.path, url.pathname))
|
|
118
|
+
continue;
|
|
119
|
+
pathMatched = true;
|
|
120
|
+
if (!definition.endpoint[method])
|
|
121
|
+
continue;
|
|
122
|
+
return await run(request, definition.path, definition.endpoint);
|
|
123
|
+
}
|
|
124
|
+
if (pathMatched) {
|
|
125
|
+
const allowed = definitions
|
|
126
|
+
.filter(definition => matchPath(definition.path, url.pathname))
|
|
127
|
+
.flatMap(definition => Object.keys(definition.endpoint));
|
|
128
|
+
return methodNotAllowed([...new Set(allowed)]);
|
|
129
|
+
}
|
|
130
|
+
return Response.json({ error: 'Not Found' }, { status: 404 });
|
|
131
|
+
},
|
|
132
|
+
};
|
|
133
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "local-lite",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.30",
|
|
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",
|
|
@@ -31,6 +31,11 @@
|
|
|
31
31
|
"import": "./dist/config/index.js",
|
|
32
32
|
"default": "./dist/config/index.js"
|
|
33
33
|
},
|
|
34
|
+
"./server": {
|
|
35
|
+
"types": "./dist/server/index.d.ts",
|
|
36
|
+
"import": "./dist/server/index.js",
|
|
37
|
+
"default": "./dist/server/index.js"
|
|
38
|
+
},
|
|
34
39
|
"./schema": {
|
|
35
40
|
"types": "./dist/schema/index.d.ts",
|
|
36
41
|
"import": "./dist/schema/index.js",
|