@syncular/client 0.64.0 → 0.65.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.
- package/README.md +1 -0
- package/dist/dev-profiler.d.ts +127 -0
- package/dist/dev-profiler.js +338 -0
- package/dist/devtools.d.ts +5 -0
- package/dist/devtools.js +13 -10
- package/dist/worker-core.d.ts +4 -1
- package/dist/worker-core.js +2 -3
- package/package.json +11 -3
- package/src/dev-profiler.ts +525 -0
- package/src/devtools.ts +17 -14
- package/src/worker-core.ts +7 -4
package/README.md
CHANGED
|
@@ -755,6 +755,7 @@ they own their buffer.
|
|
|
755
755
|
| `./sqlite` | Runtime-selected SQLite: `openSqliteDatabase` on Node or Bun |
|
|
756
756
|
| `./bun` | Explicit `bun:sqlite` binding: `openBunDatabase` |
|
|
757
757
|
| `./node` | Explicit built-in `node:sqlite` binding: `openNodeDatabase` |
|
|
758
|
+
| `./dev` | Development profiler: `createSyncProfiler`, `assertBudgets` |
|
|
758
759
|
|
|
759
760
|
Tests drive the real worker entry in a bun `Worker` with bun:sqlite
|
|
760
761
|
injected through the bootstrap's database-factory override
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@syncular/client/dev`: a development profiler. It wraps the database,
|
|
3
|
+
* the sync transport, the realtime connector and the client (or a worker or
|
|
4
|
+
* native handle) an app already constructs, and reports per live query, per
|
|
5
|
+
* statement, per round, per unit and per write burst. It keeps SQL text in
|
|
6
|
+
* memory, so `createSyncProfiler` refuses a build without a development or
|
|
7
|
+
* test signal. No production entry imports this module.
|
|
8
|
+
*/
|
|
9
|
+
import type { MutationInput, QueryReadSpec, QuerySnapshot } from './client.js';
|
|
10
|
+
import type { ClientDatabase } from './database.js';
|
|
11
|
+
import type { ClientDiagnosticsListener } from './diagnostics.js';
|
|
12
|
+
import type { ClientChangeListener } from './invalidation.js';
|
|
13
|
+
import type { SyncProgressListener } from './progress.js';
|
|
14
|
+
import type { RealtimeConnector, SyncTransport } from './transport.js';
|
|
15
|
+
/** The surface `profiler.client()` wraps: a `SyncClient`, a worker handle or a native handle. */
|
|
16
|
+
export interface ProfiledClient {
|
|
17
|
+
querySnapshot(spec: QueryReadSpec): QuerySnapshot | Promise<QuerySnapshot>;
|
|
18
|
+
mutate(mutations: readonly MutationInput[]): unknown;
|
|
19
|
+
onChange(listener: ClientChangeListener): () => void;
|
|
20
|
+
onProgress(listener: SyncProgressListener): () => void;
|
|
21
|
+
onDiagnostics(listener: ClientDiagnosticsListener): () => void;
|
|
22
|
+
}
|
|
23
|
+
export interface SyncProfilerOptions {
|
|
24
|
+
/** Milliseconds clock; tests pass a virtual one. Default `performance.now`. */
|
|
25
|
+
readonly now?: () => number;
|
|
26
|
+
/** The server's `maxSubscriptionsPerRequest`. Default 500. */
|
|
27
|
+
readonly unitLimit?: number;
|
|
28
|
+
/**
|
|
29
|
+
* Single-operation commits that start within this many milliseconds of the
|
|
30
|
+
* previous one join its write burst. Default 16.
|
|
31
|
+
*/
|
|
32
|
+
readonly burstWindowMs?: number;
|
|
33
|
+
/**
|
|
34
|
+
* Shared between a worker's profiler and the page's: the worker posts its
|
|
35
|
+
* statements and rounds, the page merges them into its report. Pass
|
|
36
|
+
* `new BroadcastChannel(name)` with the same name on both sides.
|
|
37
|
+
*/
|
|
38
|
+
readonly channel?: Pick<BroadcastChannel, 'postMessage' | 'onmessage'>;
|
|
39
|
+
}
|
|
40
|
+
export interface QueryProfile {
|
|
41
|
+
/** The owner id of a live query, or the SQL of an unowned read. */
|
|
42
|
+
readonly id: string;
|
|
43
|
+
readonly sql: string;
|
|
44
|
+
readonly tables: readonly string[];
|
|
45
|
+
readonly runs: number;
|
|
46
|
+
/** Runs whose rows equal the previous run's rows. */
|
|
47
|
+
readonly identicalRuns: number;
|
|
48
|
+
readonly totalMs: number;
|
|
49
|
+
readonly maxMs: number;
|
|
50
|
+
/** Rows of the last run. */
|
|
51
|
+
readonly rows: number;
|
|
52
|
+
/** Runs per changed table, plus `mount` (first run) and `refresh` (no table changed). */
|
|
53
|
+
readonly triggers: Readonly<Record<string, number>>;
|
|
54
|
+
}
|
|
55
|
+
export interface StatementProfile {
|
|
56
|
+
readonly sql: string;
|
|
57
|
+
readonly runs: number;
|
|
58
|
+
readonly totalMs: number;
|
|
59
|
+
readonly maxMs: number;
|
|
60
|
+
readonly rows: number;
|
|
61
|
+
}
|
|
62
|
+
export interface RoundProfile {
|
|
63
|
+
readonly via: 'http' | 'socket';
|
|
64
|
+
readonly requestBytes: number;
|
|
65
|
+
readonly responseBytes: number;
|
|
66
|
+
/** From sending the request to the last response byte. */
|
|
67
|
+
readonly ms: number;
|
|
68
|
+
}
|
|
69
|
+
export interface UnitProfile {
|
|
70
|
+
readonly unitId: string;
|
|
71
|
+
readonly table: string | undefined;
|
|
72
|
+
/** Segment bytes downloaded or received inline. */
|
|
73
|
+
readonly bytes: number;
|
|
74
|
+
readonly rows: number;
|
|
75
|
+
/** From the unit's first progress event to its last. */
|
|
76
|
+
readonly ms: number;
|
|
77
|
+
}
|
|
78
|
+
export interface ProfileReport {
|
|
79
|
+
readonly queries: readonly QueryProfile[];
|
|
80
|
+
readonly statements: readonly StatementProfile[];
|
|
81
|
+
/** The last 256 rounds. */
|
|
82
|
+
readonly rounds: readonly RoundProfile[];
|
|
83
|
+
readonly deltas: {
|
|
84
|
+
readonly count: number;
|
|
85
|
+
readonly bytes: number;
|
|
86
|
+
};
|
|
87
|
+
readonly units: {
|
|
88
|
+
/** `activeUnits` of the last diagnostics snapshot: the units the next pull sends. */
|
|
89
|
+
readonly active: number;
|
|
90
|
+
readonly peak: number;
|
|
91
|
+
readonly limit: number;
|
|
92
|
+
readonly bootstraps: readonly UnitProfile[];
|
|
93
|
+
};
|
|
94
|
+
readonly writes: {
|
|
95
|
+
readonly mutateCalls: number;
|
|
96
|
+
readonly operations: number;
|
|
97
|
+
/** Runs of more than one single-operation commit (`burstWindowMs`). */
|
|
98
|
+
readonly bursts: readonly {
|
|
99
|
+
readonly commits: number;
|
|
100
|
+
readonly tables: readonly string[];
|
|
101
|
+
}[];
|
|
102
|
+
};
|
|
103
|
+
}
|
|
104
|
+
export interface SyncProfiler {
|
|
105
|
+
database<D extends ClientDatabase>(database: D): D;
|
|
106
|
+
transport(transport: SyncTransport): SyncTransport;
|
|
107
|
+
realtime(connector: RealtimeConnector): RealtimeConnector;
|
|
108
|
+
client<C extends ProfiledClient>(client: C): C;
|
|
109
|
+
report(): ProfileReport;
|
|
110
|
+
reset(): void;
|
|
111
|
+
}
|
|
112
|
+
export interface ProfileBudgets {
|
|
113
|
+
readonly maxActiveUnits?: number;
|
|
114
|
+
/** Request plus response bytes of one round. */
|
|
115
|
+
readonly maxRoundBytes?: number;
|
|
116
|
+
readonly maxRunsPerQuery?: number;
|
|
117
|
+
/** Identical runs summed over all queries. */
|
|
118
|
+
readonly maxIdenticalRuns?: number;
|
|
119
|
+
/** Commits of the largest write burst. */
|
|
120
|
+
readonly maxWriteBurst?: number;
|
|
121
|
+
}
|
|
122
|
+
export declare function createSyncProfiler(options?: SyncProfilerOptions): SyncProfiler;
|
|
123
|
+
/**
|
|
124
|
+
* Throws `client.profile_budget_exceeded` listing every budget the report
|
|
125
|
+
* exceeds, with `budget`, `limit` and `measured` per entry in `details.exceeded`.
|
|
126
|
+
*/
|
|
127
|
+
export declare function assertBudgets(report: ProfileReport, budgets: ProfileBudgets): void;
|
|
@@ -0,0 +1,338 @@
|
|
|
1
|
+
import { developmentBuild } from './devtools.js';
|
|
2
|
+
import { ClientSyncError } from './errors.js';
|
|
3
|
+
import { canonicalValue } from './reactive-store.js';
|
|
4
|
+
/** A proxy that replaces `overrides` and binds every other method to `target`. */
|
|
5
|
+
function wrap(target, overrides) {
|
|
6
|
+
return new Proxy(target, {
|
|
7
|
+
get(object, key) {
|
|
8
|
+
if (Object.hasOwn(overrides, key))
|
|
9
|
+
return overrides[key];
|
|
10
|
+
const value = Reflect.get(object, key, object);
|
|
11
|
+
return typeof value === 'function' ? value.bind(object) : value;
|
|
12
|
+
},
|
|
13
|
+
});
|
|
14
|
+
}
|
|
15
|
+
export function createSyncProfiler(options = {}) {
|
|
16
|
+
if (!developmentBuild())
|
|
17
|
+
throw new ClientSyncError('client.profiler_in_production', 'createSyncProfiler requires a development or test build');
|
|
18
|
+
const now = options.now ?? (() => performance.now());
|
|
19
|
+
const burstWindowMs = options.burstWindowMs ?? 16;
|
|
20
|
+
const channel = options.channel;
|
|
21
|
+
const source = Math.random().toString(36).slice(2);
|
|
22
|
+
let queries = new Map();
|
|
23
|
+
// Per query: the canonical rows of its last run and the change sequence it saw.
|
|
24
|
+
let queryState = new Map();
|
|
25
|
+
let statements = new Map();
|
|
26
|
+
let rounds = [];
|
|
27
|
+
let deltas = { count: 0, bytes: 0 };
|
|
28
|
+
let units = { active: 0, peak: 0 };
|
|
29
|
+
let bootstraps = new Map();
|
|
30
|
+
let writes = {
|
|
31
|
+
mutateCalls: 0,
|
|
32
|
+
operations: 0,
|
|
33
|
+
bursts: [],
|
|
34
|
+
};
|
|
35
|
+
let burst;
|
|
36
|
+
let changeSeq = 0;
|
|
37
|
+
const changedAt = new Map();
|
|
38
|
+
const remote = new Map();
|
|
39
|
+
let posting = false;
|
|
40
|
+
const clear = () => {
|
|
41
|
+
queries = new Map();
|
|
42
|
+
queryState = new Map();
|
|
43
|
+
statements = new Map();
|
|
44
|
+
rounds = [];
|
|
45
|
+
deltas = { count: 0, bytes: 0 };
|
|
46
|
+
units = { active: units.active, peak: units.active };
|
|
47
|
+
bootstraps = new Map();
|
|
48
|
+
writes = { mutateCalls: 0, operations: 0, bursts: [] };
|
|
49
|
+
burst = undefined;
|
|
50
|
+
remote.clear();
|
|
51
|
+
};
|
|
52
|
+
const post = () => {
|
|
53
|
+
if (channel === undefined || posting)
|
|
54
|
+
return;
|
|
55
|
+
posting = true;
|
|
56
|
+
queueMicrotask(() => {
|
|
57
|
+
posting = false;
|
|
58
|
+
channel.postMessage({
|
|
59
|
+
syncularProfile: source,
|
|
60
|
+
statements: [...statements.values()],
|
|
61
|
+
rounds,
|
|
62
|
+
});
|
|
63
|
+
});
|
|
64
|
+
};
|
|
65
|
+
if (channel !== undefined)
|
|
66
|
+
channel.onmessage = (event) => {
|
|
67
|
+
const data = event.data;
|
|
68
|
+
if (data?.syncularProfileReset === true)
|
|
69
|
+
clear();
|
|
70
|
+
else if (typeof data?.syncularProfile === 'string')
|
|
71
|
+
remote.set(data.syncularProfile, {
|
|
72
|
+
statements: data.statements,
|
|
73
|
+
rounds: data.rounds,
|
|
74
|
+
});
|
|
75
|
+
};
|
|
76
|
+
const round = (entry) => {
|
|
77
|
+
rounds.push(entry);
|
|
78
|
+
if (rounds.length > 256)
|
|
79
|
+
rounds.shift();
|
|
80
|
+
post();
|
|
81
|
+
return entry;
|
|
82
|
+
};
|
|
83
|
+
const statement = (run) => (sql, params) => {
|
|
84
|
+
const startedAt = now();
|
|
85
|
+
const result = run(sql, params);
|
|
86
|
+
const ms = now() - startedAt;
|
|
87
|
+
const entry = statements.get(sql) ??
|
|
88
|
+
statements
|
|
89
|
+
.set(sql, { sql, runs: 0, totalMs: 0, maxMs: 0, rows: 0 })
|
|
90
|
+
.get(sql);
|
|
91
|
+
entry.runs += 1;
|
|
92
|
+
entry.totalMs += ms;
|
|
93
|
+
entry.maxMs = Math.max(entry.maxMs, ms);
|
|
94
|
+
if (Array.isArray(result))
|
|
95
|
+
entry.rows += result.length;
|
|
96
|
+
post();
|
|
97
|
+
return result;
|
|
98
|
+
};
|
|
99
|
+
return {
|
|
100
|
+
database: (database) => wrap(database, {
|
|
101
|
+
exec: statement((sql, params) => database.exec(sql, params)),
|
|
102
|
+
query: statement((sql, params) => database.query(sql, params)),
|
|
103
|
+
queryReadOnly: statement((sql, params) => database.queryReadOnly(sql, params)),
|
|
104
|
+
}),
|
|
105
|
+
transport: (transport) => async (request, signal) => {
|
|
106
|
+
const startedAt = now();
|
|
107
|
+
const response = await transport(request, signal);
|
|
108
|
+
round({
|
|
109
|
+
via: 'http',
|
|
110
|
+
requestBytes: request.length,
|
|
111
|
+
responseBytes: response.length,
|
|
112
|
+
ms: now() - startedAt,
|
|
113
|
+
});
|
|
114
|
+
return response;
|
|
115
|
+
},
|
|
116
|
+
realtime: (connector) => (handlers, clientId) => {
|
|
117
|
+
let open;
|
|
118
|
+
const socket = connector({
|
|
119
|
+
...handlers,
|
|
120
|
+
onBinary: (bytes) => {
|
|
121
|
+
// §8.7: tag 0x00 is a delta, tag 0x01 a chunk of the open round.
|
|
122
|
+
if (bytes[0] === 0) {
|
|
123
|
+
deltas.count += 1;
|
|
124
|
+
deltas.bytes += bytes.length - 1;
|
|
125
|
+
}
|
|
126
|
+
else if (open !== undefined) {
|
|
127
|
+
open.responseBytes += bytes.length - 1;
|
|
128
|
+
open.ms = now() - open.startedAt;
|
|
129
|
+
post();
|
|
130
|
+
}
|
|
131
|
+
handlers.onBinary(bytes);
|
|
132
|
+
},
|
|
133
|
+
}, clientId);
|
|
134
|
+
const profiled = (opened) => wrap(opened, {
|
|
135
|
+
sendBytes: (bytes) => {
|
|
136
|
+
if (bytes[0] === 1) {
|
|
137
|
+
const startedAt = now();
|
|
138
|
+
open = Object.assign(round({
|
|
139
|
+
via: 'socket',
|
|
140
|
+
requestBytes: bytes.length - 1,
|
|
141
|
+
responseBytes: 0,
|
|
142
|
+
ms: 0,
|
|
143
|
+
}), { startedAt });
|
|
144
|
+
}
|
|
145
|
+
opened.sendBytes(bytes);
|
|
146
|
+
},
|
|
147
|
+
});
|
|
148
|
+
return socket instanceof Promise
|
|
149
|
+
? socket.then(profiled)
|
|
150
|
+
: profiled(socket);
|
|
151
|
+
},
|
|
152
|
+
client: (client) => {
|
|
153
|
+
client.onChange((batch) => {
|
|
154
|
+
changeSeq += 1;
|
|
155
|
+
for (const change of batch.tables)
|
|
156
|
+
changedAt.set(change.table, changeSeq);
|
|
157
|
+
});
|
|
158
|
+
client.onDiagnostics((snapshot) => {
|
|
159
|
+
units.active = snapshot.activeUnits;
|
|
160
|
+
units.peak = Math.max(units.peak, snapshot.activeUnits);
|
|
161
|
+
});
|
|
162
|
+
client.onProgress((progress) => {
|
|
163
|
+
if (progress.unitId === undefined || progress.phase === 'request')
|
|
164
|
+
return;
|
|
165
|
+
let unit = bootstraps.get(progress.unitId);
|
|
166
|
+
if (unit === undefined) {
|
|
167
|
+
unit = {
|
|
168
|
+
unitId: progress.unitId,
|
|
169
|
+
table: progress.table,
|
|
170
|
+
bytes: 0,
|
|
171
|
+
rows: 0,
|
|
172
|
+
ms: 0,
|
|
173
|
+
startedAt: now(),
|
|
174
|
+
segment: undefined,
|
|
175
|
+
segmentBytes: 0,
|
|
176
|
+
segmentRows: 0,
|
|
177
|
+
};
|
|
178
|
+
bootstraps.set(progress.unitId, unit);
|
|
179
|
+
}
|
|
180
|
+
// A progress event repeats its segment's running totals; a new
|
|
181
|
+
// segment, or totals that went down, starts the next one.
|
|
182
|
+
if (progress.segmentId !== unit.segment ||
|
|
183
|
+
progress.bytesReceived < unit.segmentBytes ||
|
|
184
|
+
progress.rowsProcessed < unit.segmentRows) {
|
|
185
|
+
unit.bytes += unit.segmentBytes;
|
|
186
|
+
unit.rows += unit.segmentRows;
|
|
187
|
+
}
|
|
188
|
+
unit.segment = progress.segmentId;
|
|
189
|
+
unit.segmentBytes = progress.bytesReceived;
|
|
190
|
+
unit.segmentRows = progress.rowsProcessed;
|
|
191
|
+
unit.ms = now() - unit.startedAt;
|
|
192
|
+
});
|
|
193
|
+
const record = (spec, startedAt, seq, snapshot) => {
|
|
194
|
+
const id = spec.owner?.id ?? spec.sql;
|
|
195
|
+
const ms = now() - startedAt;
|
|
196
|
+
const query = queries.get(id) ??
|
|
197
|
+
queries
|
|
198
|
+
.set(id, {
|
|
199
|
+
id,
|
|
200
|
+
sql: spec.sql,
|
|
201
|
+
tables: spec.owner?.tables ?? [],
|
|
202
|
+
runs: 0,
|
|
203
|
+
identicalRuns: 0,
|
|
204
|
+
totalMs: 0,
|
|
205
|
+
maxMs: 0,
|
|
206
|
+
rows: 0,
|
|
207
|
+
triggers: {},
|
|
208
|
+
})
|
|
209
|
+
.get(id);
|
|
210
|
+
const previous = queryState.get(id);
|
|
211
|
+
const rows = canonicalValue(snapshot.rows);
|
|
212
|
+
const changed = query.tables.filter((table) => (changedAt.get(table) ?? 0) > (previous?.seq ?? 0));
|
|
213
|
+
const triggers = query.triggers;
|
|
214
|
+
for (const trigger of previous === undefined
|
|
215
|
+
? ['mount']
|
|
216
|
+
: changed.length > 0
|
|
217
|
+
? changed
|
|
218
|
+
: ['refresh'])
|
|
219
|
+
triggers[trigger] = (triggers[trigger] ?? 0) + 1;
|
|
220
|
+
if (previous?.rows === rows)
|
|
221
|
+
query.identicalRuns += 1;
|
|
222
|
+
queryState.set(id, { rows, seq });
|
|
223
|
+
query.runs += 1;
|
|
224
|
+
query.totalMs += ms;
|
|
225
|
+
query.maxMs = Math.max(query.maxMs, ms);
|
|
226
|
+
query.rows = snapshot.rows.length;
|
|
227
|
+
return snapshot;
|
|
228
|
+
};
|
|
229
|
+
return wrap(client, {
|
|
230
|
+
querySnapshot: (spec) => {
|
|
231
|
+
const startedAt = now();
|
|
232
|
+
const seq = changeSeq;
|
|
233
|
+
const snapshot = client.querySnapshot(spec);
|
|
234
|
+
return snapshot instanceof Promise
|
|
235
|
+
? snapshot.then((value) => record(spec, startedAt, seq, value))
|
|
236
|
+
: record(spec, startedAt, seq, snapshot);
|
|
237
|
+
},
|
|
238
|
+
mutate: (mutations) => {
|
|
239
|
+
writes.mutateCalls += 1;
|
|
240
|
+
writes.operations += mutations.length;
|
|
241
|
+
const at = now();
|
|
242
|
+
if (mutations.length !== 1)
|
|
243
|
+
burst = undefined;
|
|
244
|
+
else if (burst !== undefined && at - burst.at <= burstWindowMs) {
|
|
245
|
+
burst.at = at;
|
|
246
|
+
burst.commits += 1;
|
|
247
|
+
if (!burst.tables.includes(mutations[0].table))
|
|
248
|
+
burst.tables.push(mutations[0].table);
|
|
249
|
+
if (burst.commits === 2)
|
|
250
|
+
writes.bursts.push(burst);
|
|
251
|
+
}
|
|
252
|
+
else
|
|
253
|
+
burst = { commits: 1, tables: [mutations[0].table], at };
|
|
254
|
+
return client.mutate(mutations);
|
|
255
|
+
},
|
|
256
|
+
});
|
|
257
|
+
},
|
|
258
|
+
report: () => {
|
|
259
|
+
const merged = new Map();
|
|
260
|
+
for (const list of [
|
|
261
|
+
[...statements.values()],
|
|
262
|
+
...[...remote.values()].map((entry) => entry.statements),
|
|
263
|
+
])
|
|
264
|
+
for (const entry of list) {
|
|
265
|
+
const into = merged.get(entry.sql);
|
|
266
|
+
if (into === undefined)
|
|
267
|
+
merged.set(entry.sql, { ...entry });
|
|
268
|
+
else {
|
|
269
|
+
into.runs += entry.runs;
|
|
270
|
+
into.totalMs += entry.totalMs;
|
|
271
|
+
into.maxMs = Math.max(into.maxMs, entry.maxMs);
|
|
272
|
+
into.rows += entry.rows;
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
return {
|
|
276
|
+
queries: [...queries.values()].map((query) => ({
|
|
277
|
+
...query,
|
|
278
|
+
triggers: { ...query.triggers },
|
|
279
|
+
})),
|
|
280
|
+
statements: [...merged.values()],
|
|
281
|
+
rounds: [
|
|
282
|
+
...[...remote.values()].flatMap((entry) => entry.rounds),
|
|
283
|
+
...rounds,
|
|
284
|
+
].map((entry) => ({
|
|
285
|
+
via: entry.via,
|
|
286
|
+
requestBytes: entry.requestBytes,
|
|
287
|
+
responseBytes: entry.responseBytes,
|
|
288
|
+
ms: entry.ms,
|
|
289
|
+
})),
|
|
290
|
+
deltas: { ...deltas },
|
|
291
|
+
units: {
|
|
292
|
+
...units,
|
|
293
|
+
limit: options.unitLimit ?? 500,
|
|
294
|
+
bootstraps: [...bootstraps.values()].map((unit) => ({
|
|
295
|
+
unitId: unit.unitId,
|
|
296
|
+
table: unit.table,
|
|
297
|
+
bytes: unit.bytes + unit.segmentBytes,
|
|
298
|
+
rows: unit.rows + unit.segmentRows,
|
|
299
|
+
ms: unit.ms,
|
|
300
|
+
})),
|
|
301
|
+
},
|
|
302
|
+
writes: {
|
|
303
|
+
...writes,
|
|
304
|
+
bursts: writes.bursts.map((entry) => ({
|
|
305
|
+
commits: entry.commits,
|
|
306
|
+
tables: [...entry.tables],
|
|
307
|
+
})),
|
|
308
|
+
},
|
|
309
|
+
};
|
|
310
|
+
},
|
|
311
|
+
reset: () => {
|
|
312
|
+
clear();
|
|
313
|
+
channel?.postMessage({ syncularProfileReset: true });
|
|
314
|
+
},
|
|
315
|
+
};
|
|
316
|
+
}
|
|
317
|
+
/**
|
|
318
|
+
* Throws `client.profile_budget_exceeded` listing every budget the report
|
|
319
|
+
* exceeds, with `budget`, `limit` and `measured` per entry in `details.exceeded`.
|
|
320
|
+
*/
|
|
321
|
+
export function assertBudgets(report, budgets) {
|
|
322
|
+
const measured = {
|
|
323
|
+
maxActiveUnits: report.units.peak,
|
|
324
|
+
maxRoundBytes: Math.max(0, ...report.rounds.map((entry) => entry.requestBytes + entry.responseBytes)),
|
|
325
|
+
maxRunsPerQuery: Math.max(0, ...report.queries.map((query) => query.runs)),
|
|
326
|
+
maxIdenticalRuns: report.queries.reduce((sum, query) => sum + query.identicalRuns, 0),
|
|
327
|
+
maxWriteBurst: Math.max(0, ...report.writes.bursts.map((entry) => entry.commits)),
|
|
328
|
+
};
|
|
329
|
+
const exceeded = Object.entries(budgets)
|
|
330
|
+
.filter(([budget, limit]) => measured[budget] > limit)
|
|
331
|
+
.map(([budget, limit]) => ({
|
|
332
|
+
budget,
|
|
333
|
+
limit,
|
|
334
|
+
measured: measured[budget],
|
|
335
|
+
}));
|
|
336
|
+
if (exceeded.length > 0)
|
|
337
|
+
throw new ClientSyncError('client.profile_budget_exceeded', 'the profile report exceeds its budgets', false, { exceeded });
|
|
338
|
+
}
|
package/dist/devtools.d.ts
CHANGED
|
@@ -43,6 +43,11 @@ export interface DevtoolsEntry extends DevtoolsRegistration {
|
|
|
43
43
|
readonly scopeKeys: readonly string[];
|
|
44
44
|
};
|
|
45
45
|
}
|
|
46
|
+
/**
|
|
47
|
+
* @internal True when the build carries a development or test signal and no
|
|
48
|
+
* production one. The registry and `@syncular/client/dev` read it.
|
|
49
|
+
*/
|
|
50
|
+
export declare function developmentBuild(): boolean;
|
|
46
51
|
/**
|
|
47
52
|
* Register a client on the page registry. Returns the unregister function
|
|
48
53
|
* (a no-op when the registry is gated off) — call it from `close()`.
|
package/dist/devtools.js
CHANGED
|
@@ -1,18 +1,21 @@
|
|
|
1
1
|
const KEY = '__SYNCULAR__';
|
|
2
|
-
/**
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
2
|
+
/**
|
|
3
|
+
* @internal True when the build carries a development or test signal and no
|
|
4
|
+
* production one. The registry and `@syncular/client/dev` read it.
|
|
5
|
+
*/
|
|
6
|
+
export function developmentBuild() {
|
|
7
7
|
if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production')
|
|
8
|
-
return
|
|
9
|
-
|
|
8
|
+
return false;
|
|
9
|
+
return ((typeof import.meta.env !== 'undefined' &&
|
|
10
10
|
import.meta.env.DEV === true) ||
|
|
11
11
|
(typeof process !== 'undefined' &&
|
|
12
12
|
(process.env.NODE_ENV === 'development' ||
|
|
13
|
-
process.env.NODE_ENV === 'test')))
|
|
14
|
-
|
|
15
|
-
|
|
13
|
+
process.env.NODE_ENV === 'test')));
|
|
14
|
+
}
|
|
15
|
+
/** The page global to install on, or undefined when gated off. */
|
|
16
|
+
function registryHost() {
|
|
17
|
+
const g = globalThis;
|
|
18
|
+
return g.window !== undefined && developmentBuild() ? g : undefined;
|
|
16
19
|
}
|
|
17
20
|
function registryOn(host) {
|
|
18
21
|
const existing = host[KEY];
|
package/dist/worker-core.d.ts
CHANGED
|
@@ -31,7 +31,10 @@ export interface SyncWorkerOverrides {
|
|
|
31
31
|
* deadlines and the client's §8.5 heartbeat watchdog.
|
|
32
32
|
*/
|
|
33
33
|
readonly scheduleBackground?: (callback: () => void, delayMs: number) => () => void;
|
|
34
|
-
|
|
34
|
+
/** `http` reads the current host auth set, as the default transport does. */
|
|
35
|
+
readonly createTransport?: (config: WorkerInitConfig, http: {
|
|
36
|
+
readonly headers: () => Readonly<Record<string, string>>;
|
|
37
|
+
}) => SyncTransport;
|
|
35
38
|
readonly createSegments?: (config: WorkerInitConfig) => SegmentDownloader | undefined;
|
|
36
39
|
/**
|
|
37
40
|
* Custom realtime connector, e.g. one that mints a fresh ticket per
|
package/dist/worker-core.js
CHANGED
|
@@ -220,7 +220,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
220
220
|
}
|
|
221
221
|
}
|
|
222
222
|
const remote = overrides.createTransport !== undefined
|
|
223
|
-
? overrides.createTransport(config)
|
|
223
|
+
? overrides.createTransport(config, http)
|
|
224
224
|
: httpSyncTransport(config.endpoints.syncUrl, http);
|
|
225
225
|
const remoteSegments = overrides.createSegments !== undefined
|
|
226
226
|
? overrides.createSegments(config)
|
|
@@ -485,8 +485,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
485
485
|
}
|
|
486
486
|
async function defaultOpenDatabase(config) {
|
|
487
487
|
if (config.database.mode !== 'persistent') {
|
|
488
|
-
throw new ClientSyncError(WORKER_FAILED_CODE, "database mode 'custom' requires
|
|
489
|
-
'worker bootstrap (startSyncWorker({ openDatabase }))');
|
|
488
|
+
throw new ClientSyncError(WORKER_FAILED_CODE, "database mode 'custom' requires startSyncWorker({ openDatabase })");
|
|
490
489
|
}
|
|
491
490
|
return openPersistentWasmDatabase(config.database.name, {
|
|
492
491
|
...(config.database.directory !== undefined
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/client",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.65.0",
|
|
4
4
|
"description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "Benjamin Kniffler",
|
|
@@ -97,6 +97,14 @@
|
|
|
97
97
|
"types": "./dist/native-bridge.d.ts",
|
|
98
98
|
"default": "./dist/native-bridge.js"
|
|
99
99
|
}
|
|
100
|
+
},
|
|
101
|
+
"./dev": {
|
|
102
|
+
"bun": "./src/dev-profiler.ts",
|
|
103
|
+
"browser": "./dist/dev-profiler.js",
|
|
104
|
+
"import": {
|
|
105
|
+
"types": "./dist/dev-profiler.d.ts",
|
|
106
|
+
"default": "./dist/dev-profiler.js"
|
|
107
|
+
}
|
|
100
108
|
}
|
|
101
109
|
},
|
|
102
110
|
"files": [
|
|
@@ -113,11 +121,11 @@
|
|
|
113
121
|
},
|
|
114
122
|
"dependencies": {
|
|
115
123
|
"@sqlite.org/sqlite-wasm": "^3.53.0-build1",
|
|
116
|
-
"@syncular/core": "0.
|
|
124
|
+
"@syncular/core": "0.65.0"
|
|
117
125
|
},
|
|
118
126
|
"devDependencies": {
|
|
119
127
|
"@electric-sql/pglite": "^0.5.4",
|
|
120
|
-
"@syncular/server": "0.
|
|
128
|
+
"@syncular/server": "0.65.0",
|
|
121
129
|
"playwright": "1.63.0",
|
|
122
130
|
"vite": "8.3.4"
|
|
123
131
|
}
|
|
@@ -0,0 +1,525 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@syncular/client/dev`: a development profiler. It wraps the database,
|
|
3
|
+
* the sync transport, the realtime connector and the client (or a worker or
|
|
4
|
+
* native handle) an app already constructs, and reports per live query, per
|
|
5
|
+
* statement, per round, per unit and per write burst. It keeps SQL text in
|
|
6
|
+
* memory, so `createSyncProfiler` refuses a build without a development or
|
|
7
|
+
* test signal. No production entry imports this module.
|
|
8
|
+
*/
|
|
9
|
+
import type { MutationInput, QueryReadSpec, QuerySnapshot } from './client';
|
|
10
|
+
import type { ClientDatabase, SqlValue } from './database';
|
|
11
|
+
import { developmentBuild } from './devtools';
|
|
12
|
+
import type { ClientDiagnosticsListener } from './diagnostics';
|
|
13
|
+
import { ClientSyncError } from './errors';
|
|
14
|
+
import type { ClientChangeListener } from './invalidation';
|
|
15
|
+
import type { SyncProgressListener } from './progress';
|
|
16
|
+
import { canonicalValue } from './reactive-store';
|
|
17
|
+
import type { RealtimeConnector, SyncTransport } from './transport';
|
|
18
|
+
|
|
19
|
+
/** The surface `profiler.client()` wraps: a `SyncClient`, a worker handle or a native handle. */
|
|
20
|
+
export interface ProfiledClient {
|
|
21
|
+
querySnapshot(spec: QueryReadSpec): QuerySnapshot | Promise<QuerySnapshot>;
|
|
22
|
+
mutate(mutations: readonly MutationInput[]): unknown;
|
|
23
|
+
onChange(listener: ClientChangeListener): () => void;
|
|
24
|
+
onProgress(listener: SyncProgressListener): () => void;
|
|
25
|
+
onDiagnostics(listener: ClientDiagnosticsListener): () => void;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export interface SyncProfilerOptions {
|
|
29
|
+
/** Milliseconds clock; tests pass a virtual one. Default `performance.now`. */
|
|
30
|
+
readonly now?: () => number;
|
|
31
|
+
/** The server's `maxSubscriptionsPerRequest`. Default 500. */
|
|
32
|
+
readonly unitLimit?: number;
|
|
33
|
+
/**
|
|
34
|
+
* Single-operation commits that start within this many milliseconds of the
|
|
35
|
+
* previous one join its write burst. Default 16.
|
|
36
|
+
*/
|
|
37
|
+
readonly burstWindowMs?: number;
|
|
38
|
+
/**
|
|
39
|
+
* Shared between a worker's profiler and the page's: the worker posts its
|
|
40
|
+
* statements and rounds, the page merges them into its report. Pass
|
|
41
|
+
* `new BroadcastChannel(name)` with the same name on both sides.
|
|
42
|
+
*/
|
|
43
|
+
readonly channel?: Pick<BroadcastChannel, 'postMessage' | 'onmessage'>;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
export interface QueryProfile {
|
|
47
|
+
/** The owner id of a live query, or the SQL of an unowned read. */
|
|
48
|
+
readonly id: string;
|
|
49
|
+
readonly sql: string;
|
|
50
|
+
readonly tables: readonly string[];
|
|
51
|
+
readonly runs: number;
|
|
52
|
+
/** Runs whose rows equal the previous run's rows. */
|
|
53
|
+
readonly identicalRuns: number;
|
|
54
|
+
readonly totalMs: number;
|
|
55
|
+
readonly maxMs: number;
|
|
56
|
+
/** Rows of the last run. */
|
|
57
|
+
readonly rows: number;
|
|
58
|
+
/** Runs per changed table, plus `mount` (first run) and `refresh` (no table changed). */
|
|
59
|
+
readonly triggers: Readonly<Record<string, number>>;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export interface StatementProfile {
|
|
63
|
+
readonly sql: string;
|
|
64
|
+
readonly runs: number;
|
|
65
|
+
readonly totalMs: number;
|
|
66
|
+
readonly maxMs: number;
|
|
67
|
+
readonly rows: number;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export interface RoundProfile {
|
|
71
|
+
readonly via: 'http' | 'socket';
|
|
72
|
+
readonly requestBytes: number;
|
|
73
|
+
readonly responseBytes: number;
|
|
74
|
+
/** From sending the request to the last response byte. */
|
|
75
|
+
readonly ms: number;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
export interface UnitProfile {
|
|
79
|
+
readonly unitId: string;
|
|
80
|
+
readonly table: string | undefined;
|
|
81
|
+
/** Segment bytes downloaded or received inline. */
|
|
82
|
+
readonly bytes: number;
|
|
83
|
+
readonly rows: number;
|
|
84
|
+
/** From the unit's first progress event to its last. */
|
|
85
|
+
readonly ms: number;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
export interface ProfileReport {
|
|
89
|
+
readonly queries: readonly QueryProfile[];
|
|
90
|
+
readonly statements: readonly StatementProfile[];
|
|
91
|
+
/** The last 256 rounds. */
|
|
92
|
+
readonly rounds: readonly RoundProfile[];
|
|
93
|
+
readonly deltas: { readonly count: number; readonly bytes: number };
|
|
94
|
+
readonly units: {
|
|
95
|
+
/** `activeUnits` of the last diagnostics snapshot: the units the next pull sends. */
|
|
96
|
+
readonly active: number;
|
|
97
|
+
readonly peak: number;
|
|
98
|
+
readonly limit: number;
|
|
99
|
+
readonly bootstraps: readonly UnitProfile[];
|
|
100
|
+
};
|
|
101
|
+
readonly writes: {
|
|
102
|
+
readonly mutateCalls: number;
|
|
103
|
+
readonly operations: number;
|
|
104
|
+
/** Runs of more than one single-operation commit (`burstWindowMs`). */
|
|
105
|
+
readonly bursts: readonly {
|
|
106
|
+
readonly commits: number;
|
|
107
|
+
readonly tables: readonly string[];
|
|
108
|
+
}[];
|
|
109
|
+
};
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
export interface SyncProfiler {
|
|
113
|
+
database<D extends ClientDatabase>(database: D): D;
|
|
114
|
+
transport(transport: SyncTransport): SyncTransport;
|
|
115
|
+
realtime(connector: RealtimeConnector): RealtimeConnector;
|
|
116
|
+
client<C extends ProfiledClient>(client: C): C;
|
|
117
|
+
report(): ProfileReport;
|
|
118
|
+
reset(): void;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
export interface ProfileBudgets {
|
|
122
|
+
readonly maxActiveUnits?: number;
|
|
123
|
+
/** Request plus response bytes of one round. */
|
|
124
|
+
readonly maxRoundBytes?: number;
|
|
125
|
+
readonly maxRunsPerQuery?: number;
|
|
126
|
+
/** Identical runs summed over all queries. */
|
|
127
|
+
readonly maxIdenticalRuns?: number;
|
|
128
|
+
/** Commits of the largest write burst. */
|
|
129
|
+
readonly maxWriteBurst?: number;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
type Mutable<T> = { -readonly [K in keyof T]: T[K] };
|
|
133
|
+
type UnitState = Mutable<UnitProfile> & {
|
|
134
|
+
startedAt: number;
|
|
135
|
+
segment: string | undefined;
|
|
136
|
+
segmentBytes: number;
|
|
137
|
+
segmentRows: number;
|
|
138
|
+
};
|
|
139
|
+
|
|
140
|
+
/** A proxy that replaces `overrides` and binds every other method to `target`. */
|
|
141
|
+
function wrap<T extends object>(target: T, overrides: Partial<T>): T {
|
|
142
|
+
return new Proxy(target, {
|
|
143
|
+
get(object, key) {
|
|
144
|
+
if (Object.hasOwn(overrides, key)) return overrides[key as keyof T];
|
|
145
|
+
const value: unknown = Reflect.get(object, key, object);
|
|
146
|
+
return typeof value === 'function' ? value.bind(object) : value;
|
|
147
|
+
},
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
export function createSyncProfiler(
|
|
152
|
+
options: SyncProfilerOptions = {},
|
|
153
|
+
): SyncProfiler {
|
|
154
|
+
if (!developmentBuild())
|
|
155
|
+
throw new ClientSyncError(
|
|
156
|
+
'client.profiler_in_production',
|
|
157
|
+
'createSyncProfiler requires a development or test build',
|
|
158
|
+
);
|
|
159
|
+
const now = options.now ?? (() => performance.now());
|
|
160
|
+
const burstWindowMs = options.burstWindowMs ?? 16;
|
|
161
|
+
const channel = options.channel;
|
|
162
|
+
const source = Math.random().toString(36).slice(2);
|
|
163
|
+
let queries = new Map<string, Mutable<QueryProfile>>();
|
|
164
|
+
// Per query: the canonical rows of its last run and the change sequence it saw.
|
|
165
|
+
let queryState = new Map<string, { rows: string; seq: number }>();
|
|
166
|
+
let statements = new Map<string, Mutable<StatementProfile>>();
|
|
167
|
+
let rounds: Mutable<RoundProfile>[] = [];
|
|
168
|
+
let deltas = { count: 0, bytes: 0 };
|
|
169
|
+
let units = { active: 0, peak: 0 };
|
|
170
|
+
let bootstraps = new Map<string, UnitState>();
|
|
171
|
+
let writes = {
|
|
172
|
+
mutateCalls: 0,
|
|
173
|
+
operations: 0,
|
|
174
|
+
bursts: [] as { commits: number; tables: string[] }[],
|
|
175
|
+
};
|
|
176
|
+
let burst: { commits: number; tables: string[]; at: number } | undefined;
|
|
177
|
+
let changeSeq = 0;
|
|
178
|
+
const changedAt = new Map<string, number>();
|
|
179
|
+
const remote = new Map<
|
|
180
|
+
string,
|
|
181
|
+
Pick<ProfileReport, 'statements' | 'rounds'>
|
|
182
|
+
>();
|
|
183
|
+
let posting = false;
|
|
184
|
+
const clear = () => {
|
|
185
|
+
queries = new Map();
|
|
186
|
+
queryState = new Map();
|
|
187
|
+
statements = new Map();
|
|
188
|
+
rounds = [];
|
|
189
|
+
deltas = { count: 0, bytes: 0 };
|
|
190
|
+
units = { active: units.active, peak: units.active };
|
|
191
|
+
bootstraps = new Map();
|
|
192
|
+
writes = { mutateCalls: 0, operations: 0, bursts: [] };
|
|
193
|
+
burst = undefined;
|
|
194
|
+
remote.clear();
|
|
195
|
+
};
|
|
196
|
+
|
|
197
|
+
const post = () => {
|
|
198
|
+
if (channel === undefined || posting) return;
|
|
199
|
+
posting = true;
|
|
200
|
+
queueMicrotask(() => {
|
|
201
|
+
posting = false;
|
|
202
|
+
channel.postMessage({
|
|
203
|
+
syncularProfile: source,
|
|
204
|
+
statements: [...statements.values()],
|
|
205
|
+
rounds,
|
|
206
|
+
});
|
|
207
|
+
});
|
|
208
|
+
};
|
|
209
|
+
if (channel !== undefined)
|
|
210
|
+
channel.onmessage = (event: MessageEvent) => {
|
|
211
|
+
const data = event.data as {
|
|
212
|
+
syncularProfile?: unknown;
|
|
213
|
+
syncularProfileReset?: unknown;
|
|
214
|
+
} & Pick<ProfileReport, 'statements' | 'rounds'>;
|
|
215
|
+
if (data?.syncularProfileReset === true) clear();
|
|
216
|
+
else if (typeof data?.syncularProfile === 'string')
|
|
217
|
+
remote.set(data.syncularProfile, {
|
|
218
|
+
statements: data.statements,
|
|
219
|
+
rounds: data.rounds,
|
|
220
|
+
});
|
|
221
|
+
};
|
|
222
|
+
|
|
223
|
+
const round = (entry: Mutable<RoundProfile>) => {
|
|
224
|
+
rounds.push(entry);
|
|
225
|
+
if (rounds.length > 256) rounds.shift();
|
|
226
|
+
post();
|
|
227
|
+
return entry;
|
|
228
|
+
};
|
|
229
|
+
const statement =
|
|
230
|
+
<R>(run: (sql: string, params?: readonly SqlValue[]) => R) =>
|
|
231
|
+
(sql: string, params?: readonly SqlValue[]): R => {
|
|
232
|
+
const startedAt = now();
|
|
233
|
+
const result = run(sql, params);
|
|
234
|
+
const ms = now() - startedAt;
|
|
235
|
+
const entry =
|
|
236
|
+
statements.get(sql) ??
|
|
237
|
+
statements
|
|
238
|
+
.set(sql, { sql, runs: 0, totalMs: 0, maxMs: 0, rows: 0 })
|
|
239
|
+
.get(sql)!;
|
|
240
|
+
entry.runs += 1;
|
|
241
|
+
entry.totalMs += ms;
|
|
242
|
+
entry.maxMs = Math.max(entry.maxMs, ms);
|
|
243
|
+
if (Array.isArray(result)) entry.rows += result.length;
|
|
244
|
+
post();
|
|
245
|
+
return result;
|
|
246
|
+
};
|
|
247
|
+
|
|
248
|
+
return {
|
|
249
|
+
database: (database) =>
|
|
250
|
+
wrap(database, {
|
|
251
|
+
exec: statement((sql, params) => database.exec(sql, params)),
|
|
252
|
+
query: statement((sql, params) => database.query(sql, params)),
|
|
253
|
+
queryReadOnly: statement((sql, params) =>
|
|
254
|
+
database.queryReadOnly(sql, params),
|
|
255
|
+
),
|
|
256
|
+
} as Partial<typeof database>),
|
|
257
|
+
|
|
258
|
+
transport: (transport) => async (request, signal) => {
|
|
259
|
+
const startedAt = now();
|
|
260
|
+
const response = await transport(request, signal);
|
|
261
|
+
round({
|
|
262
|
+
via: 'http',
|
|
263
|
+
requestBytes: request.length,
|
|
264
|
+
responseBytes: response.length,
|
|
265
|
+
ms: now() - startedAt,
|
|
266
|
+
});
|
|
267
|
+
return response;
|
|
268
|
+
},
|
|
269
|
+
|
|
270
|
+
realtime: (connector) => (handlers, clientId) => {
|
|
271
|
+
let open: (Mutable<RoundProfile> & { startedAt: number }) | undefined;
|
|
272
|
+
const socket = connector(
|
|
273
|
+
{
|
|
274
|
+
...handlers,
|
|
275
|
+
onBinary: (bytes) => {
|
|
276
|
+
// §8.7: tag 0x00 is a delta, tag 0x01 a chunk of the open round.
|
|
277
|
+
if (bytes[0] === 0) {
|
|
278
|
+
deltas.count += 1;
|
|
279
|
+
deltas.bytes += bytes.length - 1;
|
|
280
|
+
} else if (open !== undefined) {
|
|
281
|
+
open.responseBytes += bytes.length - 1;
|
|
282
|
+
open.ms = now() - open.startedAt;
|
|
283
|
+
post();
|
|
284
|
+
}
|
|
285
|
+
handlers.onBinary(bytes);
|
|
286
|
+
},
|
|
287
|
+
},
|
|
288
|
+
clientId,
|
|
289
|
+
);
|
|
290
|
+
const profiled = (opened: Awaited<typeof socket>) =>
|
|
291
|
+
wrap(opened, {
|
|
292
|
+
sendBytes: (bytes: Uint8Array) => {
|
|
293
|
+
if (bytes[0] === 1) {
|
|
294
|
+
const startedAt = now();
|
|
295
|
+
open = Object.assign(
|
|
296
|
+
round({
|
|
297
|
+
via: 'socket',
|
|
298
|
+
requestBytes: bytes.length - 1,
|
|
299
|
+
responseBytes: 0,
|
|
300
|
+
ms: 0,
|
|
301
|
+
}),
|
|
302
|
+
{ startedAt },
|
|
303
|
+
);
|
|
304
|
+
}
|
|
305
|
+
opened.sendBytes(bytes);
|
|
306
|
+
},
|
|
307
|
+
});
|
|
308
|
+
return socket instanceof Promise
|
|
309
|
+
? socket.then(profiled)
|
|
310
|
+
: profiled(socket);
|
|
311
|
+
},
|
|
312
|
+
|
|
313
|
+
client: (client) => {
|
|
314
|
+
client.onChange((batch) => {
|
|
315
|
+
changeSeq += 1;
|
|
316
|
+
for (const change of batch.tables)
|
|
317
|
+
changedAt.set(change.table, changeSeq);
|
|
318
|
+
});
|
|
319
|
+
client.onDiagnostics((snapshot) => {
|
|
320
|
+
units.active = snapshot.activeUnits;
|
|
321
|
+
units.peak = Math.max(units.peak, snapshot.activeUnits);
|
|
322
|
+
});
|
|
323
|
+
client.onProgress((progress) => {
|
|
324
|
+
if (progress.unitId === undefined || progress.phase === 'request')
|
|
325
|
+
return;
|
|
326
|
+
let unit = bootstraps.get(progress.unitId);
|
|
327
|
+
if (unit === undefined) {
|
|
328
|
+
unit = {
|
|
329
|
+
unitId: progress.unitId,
|
|
330
|
+
table: progress.table,
|
|
331
|
+
bytes: 0,
|
|
332
|
+
rows: 0,
|
|
333
|
+
ms: 0,
|
|
334
|
+
startedAt: now(),
|
|
335
|
+
segment: undefined,
|
|
336
|
+
segmentBytes: 0,
|
|
337
|
+
segmentRows: 0,
|
|
338
|
+
};
|
|
339
|
+
bootstraps.set(progress.unitId, unit);
|
|
340
|
+
}
|
|
341
|
+
// A progress event repeats its segment's running totals; a new
|
|
342
|
+
// segment, or totals that went down, starts the next one.
|
|
343
|
+
if (
|
|
344
|
+
progress.segmentId !== unit.segment ||
|
|
345
|
+
progress.bytesReceived < unit.segmentBytes ||
|
|
346
|
+
progress.rowsProcessed < unit.segmentRows
|
|
347
|
+
) {
|
|
348
|
+
unit.bytes += unit.segmentBytes;
|
|
349
|
+
unit.rows += unit.segmentRows;
|
|
350
|
+
}
|
|
351
|
+
unit.segment = progress.segmentId;
|
|
352
|
+
unit.segmentBytes = progress.bytesReceived;
|
|
353
|
+
unit.segmentRows = progress.rowsProcessed;
|
|
354
|
+
unit.ms = now() - unit.startedAt;
|
|
355
|
+
});
|
|
356
|
+
const record = (
|
|
357
|
+
spec: QueryReadSpec,
|
|
358
|
+
startedAt: number,
|
|
359
|
+
seq: number,
|
|
360
|
+
snapshot: QuerySnapshot,
|
|
361
|
+
) => {
|
|
362
|
+
const id = spec.owner?.id ?? spec.sql;
|
|
363
|
+
const ms = now() - startedAt;
|
|
364
|
+
const query =
|
|
365
|
+
queries.get(id) ??
|
|
366
|
+
queries
|
|
367
|
+
.set(id, {
|
|
368
|
+
id,
|
|
369
|
+
sql: spec.sql,
|
|
370
|
+
tables: spec.owner?.tables ?? [],
|
|
371
|
+
runs: 0,
|
|
372
|
+
identicalRuns: 0,
|
|
373
|
+
totalMs: 0,
|
|
374
|
+
maxMs: 0,
|
|
375
|
+
rows: 0,
|
|
376
|
+
triggers: {},
|
|
377
|
+
})
|
|
378
|
+
.get(id)!;
|
|
379
|
+
const previous = queryState.get(id);
|
|
380
|
+
const rows = canonicalValue(snapshot.rows);
|
|
381
|
+
const changed = query.tables.filter(
|
|
382
|
+
(table) => (changedAt.get(table) ?? 0) > (previous?.seq ?? 0),
|
|
383
|
+
);
|
|
384
|
+
const triggers = query.triggers as Record<string, number>;
|
|
385
|
+
for (const trigger of previous === undefined
|
|
386
|
+
? ['mount']
|
|
387
|
+
: changed.length > 0
|
|
388
|
+
? changed
|
|
389
|
+
: ['refresh'])
|
|
390
|
+
triggers[trigger] = (triggers[trigger] ?? 0) + 1;
|
|
391
|
+
if (previous?.rows === rows) query.identicalRuns += 1;
|
|
392
|
+
queryState.set(id, { rows, seq });
|
|
393
|
+
query.runs += 1;
|
|
394
|
+
query.totalMs += ms;
|
|
395
|
+
query.maxMs = Math.max(query.maxMs, ms);
|
|
396
|
+
query.rows = snapshot.rows.length;
|
|
397
|
+
return snapshot;
|
|
398
|
+
};
|
|
399
|
+
return wrap(client, {
|
|
400
|
+
querySnapshot: (spec: QueryReadSpec) => {
|
|
401
|
+
const startedAt = now();
|
|
402
|
+
const seq = changeSeq;
|
|
403
|
+
const snapshot = client.querySnapshot(spec);
|
|
404
|
+
return snapshot instanceof Promise
|
|
405
|
+
? snapshot.then((value) => record(spec, startedAt, seq, value))
|
|
406
|
+
: record(spec, startedAt, seq, snapshot);
|
|
407
|
+
},
|
|
408
|
+
mutate: (mutations: readonly MutationInput[]) => {
|
|
409
|
+
writes.mutateCalls += 1;
|
|
410
|
+
writes.operations += mutations.length;
|
|
411
|
+
const at = now();
|
|
412
|
+
if (mutations.length !== 1) burst = undefined;
|
|
413
|
+
else if (burst !== undefined && at - burst.at <= burstWindowMs) {
|
|
414
|
+
burst.at = at;
|
|
415
|
+
burst.commits += 1;
|
|
416
|
+
if (!burst.tables.includes(mutations[0]!.table))
|
|
417
|
+
burst.tables.push(mutations[0]!.table);
|
|
418
|
+
if (burst.commits === 2) writes.bursts.push(burst);
|
|
419
|
+
} else burst = { commits: 1, tables: [mutations[0]!.table], at };
|
|
420
|
+
return client.mutate(mutations);
|
|
421
|
+
},
|
|
422
|
+
} as Partial<typeof client>);
|
|
423
|
+
},
|
|
424
|
+
|
|
425
|
+
report: () => {
|
|
426
|
+
const merged = new Map<string, Mutable<StatementProfile>>();
|
|
427
|
+
for (const list of [
|
|
428
|
+
[...statements.values()],
|
|
429
|
+
...[...remote.values()].map((entry) => entry.statements),
|
|
430
|
+
])
|
|
431
|
+
for (const entry of list) {
|
|
432
|
+
const into = merged.get(entry.sql);
|
|
433
|
+
if (into === undefined) merged.set(entry.sql, { ...entry });
|
|
434
|
+
else {
|
|
435
|
+
into.runs += entry.runs;
|
|
436
|
+
into.totalMs += entry.totalMs;
|
|
437
|
+
into.maxMs = Math.max(into.maxMs, entry.maxMs);
|
|
438
|
+
into.rows += entry.rows;
|
|
439
|
+
}
|
|
440
|
+
}
|
|
441
|
+
return {
|
|
442
|
+
queries: [...queries.values()].map((query) => ({
|
|
443
|
+
...query,
|
|
444
|
+
triggers: { ...query.triggers },
|
|
445
|
+
})),
|
|
446
|
+
statements: [...merged.values()],
|
|
447
|
+
rounds: [
|
|
448
|
+
...[...remote.values()].flatMap((entry) => entry.rounds),
|
|
449
|
+
...rounds,
|
|
450
|
+
].map((entry) => ({
|
|
451
|
+
via: entry.via,
|
|
452
|
+
requestBytes: entry.requestBytes,
|
|
453
|
+
responseBytes: entry.responseBytes,
|
|
454
|
+
ms: entry.ms,
|
|
455
|
+
})),
|
|
456
|
+
deltas: { ...deltas },
|
|
457
|
+
units: {
|
|
458
|
+
...units,
|
|
459
|
+
limit: options.unitLimit ?? 500,
|
|
460
|
+
bootstraps: [...bootstraps.values()].map((unit) => ({
|
|
461
|
+
unitId: unit.unitId,
|
|
462
|
+
table: unit.table,
|
|
463
|
+
bytes: unit.bytes + unit.segmentBytes,
|
|
464
|
+
rows: unit.rows + unit.segmentRows,
|
|
465
|
+
ms: unit.ms,
|
|
466
|
+
})),
|
|
467
|
+
},
|
|
468
|
+
writes: {
|
|
469
|
+
...writes,
|
|
470
|
+
bursts: writes.bursts.map((entry) => ({
|
|
471
|
+
commits: entry.commits,
|
|
472
|
+
tables: [...entry.tables],
|
|
473
|
+
})),
|
|
474
|
+
},
|
|
475
|
+
};
|
|
476
|
+
},
|
|
477
|
+
|
|
478
|
+
reset: () => {
|
|
479
|
+
clear();
|
|
480
|
+
channel?.postMessage({ syncularProfileReset: true });
|
|
481
|
+
},
|
|
482
|
+
};
|
|
483
|
+
}
|
|
484
|
+
|
|
485
|
+
/**
|
|
486
|
+
* Throws `client.profile_budget_exceeded` listing every budget the report
|
|
487
|
+
* exceeds, with `budget`, `limit` and `measured` per entry in `details.exceeded`.
|
|
488
|
+
*/
|
|
489
|
+
export function assertBudgets(
|
|
490
|
+
report: ProfileReport,
|
|
491
|
+
budgets: ProfileBudgets,
|
|
492
|
+
): void {
|
|
493
|
+
const measured: Record<keyof ProfileBudgets, number> = {
|
|
494
|
+
maxActiveUnits: report.units.peak,
|
|
495
|
+
maxRoundBytes: Math.max(
|
|
496
|
+
0,
|
|
497
|
+
...report.rounds.map((entry) => entry.requestBytes + entry.responseBytes),
|
|
498
|
+
),
|
|
499
|
+
maxRunsPerQuery: Math.max(0, ...report.queries.map((query) => query.runs)),
|
|
500
|
+
maxIdenticalRuns: report.queries.reduce(
|
|
501
|
+
(sum, query) => sum + query.identicalRuns,
|
|
502
|
+
0,
|
|
503
|
+
),
|
|
504
|
+
maxWriteBurst: Math.max(
|
|
505
|
+
0,
|
|
506
|
+
...report.writes.bursts.map((entry) => entry.commits),
|
|
507
|
+
),
|
|
508
|
+
};
|
|
509
|
+
const exceeded = Object.entries(budgets)
|
|
510
|
+
.filter(
|
|
511
|
+
([budget, limit]) => measured[budget as keyof ProfileBudgets] > limit,
|
|
512
|
+
)
|
|
513
|
+
.map(([budget, limit]) => ({
|
|
514
|
+
budget,
|
|
515
|
+
limit,
|
|
516
|
+
measured: measured[budget as keyof ProfileBudgets],
|
|
517
|
+
}));
|
|
518
|
+
if (exceeded.length > 0)
|
|
519
|
+
throw new ClientSyncError(
|
|
520
|
+
'client.profile_budget_exceeded',
|
|
521
|
+
'the profile report exceeds its budgets',
|
|
522
|
+
false,
|
|
523
|
+
{ exceeded },
|
|
524
|
+
);
|
|
525
|
+
}
|
package/src/devtools.ts
CHANGED
|
@@ -56,23 +56,26 @@ interface DevtoolsRegistry {
|
|
|
56
56
|
|
|
57
57
|
const KEY = '__SYNCULAR__';
|
|
58
58
|
|
|
59
|
+
/**
|
|
60
|
+
* @internal True when the build carries a development or test signal and no
|
|
61
|
+
* production one. The registry and `@syncular/client/dev` read it.
|
|
62
|
+
*/
|
|
63
|
+
export function developmentBuild(): boolean {
|
|
64
|
+
if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production')
|
|
65
|
+
return false;
|
|
66
|
+
return (
|
|
67
|
+
(typeof import.meta.env !== 'undefined' &&
|
|
68
|
+
(import.meta.env.DEV as boolean | string | undefined) === true) ||
|
|
69
|
+
(typeof process !== 'undefined' &&
|
|
70
|
+
(process.env.NODE_ENV === 'development' ||
|
|
71
|
+
process.env.NODE_ENV === 'test'))
|
|
72
|
+
);
|
|
73
|
+
}
|
|
74
|
+
|
|
59
75
|
/** The page global to install on, or undefined when gated off. */
|
|
60
76
|
function registryHost(): Record<string, unknown> | undefined {
|
|
61
77
|
const g = globalThis as Record<string, unknown> & { window?: unknown };
|
|
62
|
-
|
|
63
|
-
if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production')
|
|
64
|
-
return undefined;
|
|
65
|
-
if (
|
|
66
|
-
!(
|
|
67
|
-
(typeof import.meta.env !== 'undefined' &&
|
|
68
|
-
(import.meta.env.DEV as boolean | string | undefined) === true) ||
|
|
69
|
-
(typeof process !== 'undefined' &&
|
|
70
|
-
(process.env.NODE_ENV === 'development' ||
|
|
71
|
-
process.env.NODE_ENV === 'test'))
|
|
72
|
-
)
|
|
73
|
-
)
|
|
74
|
-
return undefined;
|
|
75
|
-
return g;
|
|
78
|
+
return g.window !== undefined && developmentBuild() ? g : undefined;
|
|
76
79
|
}
|
|
77
80
|
|
|
78
81
|
function registryOn(host: Record<string, unknown>): DevtoolsRegistry {
|
package/src/worker-core.ts
CHANGED
|
@@ -72,7 +72,11 @@ export interface SyncWorkerOverrides {
|
|
|
72
72
|
callback: () => void,
|
|
73
73
|
delayMs: number,
|
|
74
74
|
) => () => void;
|
|
75
|
-
|
|
75
|
+
/** `http` reads the current host auth set, as the default transport does. */
|
|
76
|
+
readonly createTransport?: (
|
|
77
|
+
config: WorkerInitConfig,
|
|
78
|
+
http: { readonly headers: () => Readonly<Record<string, string>> },
|
|
79
|
+
) => SyncTransport;
|
|
76
80
|
readonly createSegments?: (
|
|
77
81
|
config: WorkerInitConfig,
|
|
78
82
|
) => SegmentDownloader | undefined;
|
|
@@ -398,7 +402,7 @@ export function startSyncWorkerCore(
|
|
|
398
402
|
}
|
|
399
403
|
const remote =
|
|
400
404
|
overrides.createTransport !== undefined
|
|
401
|
-
? overrides.createTransport(config)
|
|
405
|
+
? overrides.createTransport(config, http)
|
|
402
406
|
: httpSyncTransport(config.endpoints.syncUrl, http);
|
|
403
407
|
const remoteSegments =
|
|
404
408
|
overrides.createSegments !== undefined
|
|
@@ -702,8 +706,7 @@ async function defaultOpenDatabase(
|
|
|
702
706
|
if (config.database.mode !== 'persistent') {
|
|
703
707
|
throw new ClientSyncError(
|
|
704
708
|
WORKER_FAILED_CODE,
|
|
705
|
-
"database mode 'custom' requires
|
|
706
|
-
'worker bootstrap (startSyncWorker({ openDatabase }))',
|
|
709
|
+
"database mode 'custom' requires startSyncWorker({ openDatabase })",
|
|
707
710
|
);
|
|
708
711
|
}
|
|
709
712
|
return openPersistentWasmDatabase(config.database.name, {
|