tsdf 17.0.0-beta.0 → 17.0.0-beta.2
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/main.js +80 -55
- package/docs/fetch-scheduling.md +9 -7
- package/package.json +1 -1
package/dist/main.js
CHANGED
|
@@ -6939,8 +6939,8 @@ var RequestScheduler = class {
|
|
|
6939
6939
|
phase: { type: "idle" },
|
|
6940
6940
|
pending: {
|
|
6941
6941
|
scheduledRequests: /* @__PURE__ */ new Map(),
|
|
6942
|
-
rtuDelayed:
|
|
6943
|
-
mediumPriorityDelayed:
|
|
6942
|
+
rtuDelayed: /* @__PURE__ */ new Map(),
|
|
6943
|
+
mediumPriorityDelayed: /* @__PURE__ */ new Map(),
|
|
6944
6944
|
mutationsInProgress: /* @__PURE__ */ new Map()
|
|
6945
6945
|
},
|
|
6946
6946
|
timing: {
|
|
@@ -6959,7 +6959,7 @@ var RequestScheduler = class {
|
|
|
6959
6959
|
}
|
|
6960
6960
|
get hasPendingFetch() {
|
|
6961
6961
|
const { phase, pending } = this.#state;
|
|
6962
|
-
return phase.type !== "idle" || pending.scheduledRequests.size > 0 || pending.rtuDelayed
|
|
6962
|
+
return phase.type !== "idle" || pending.scheduledRequests.size > 0 || pending.rtuDelayed.size > 0 || pending.mediumPriorityDelayed.size > 0;
|
|
6963
6963
|
}
|
|
6964
6964
|
get fetchIsInProgress() {
|
|
6965
6965
|
return this.#state.phase.type === "fetching";
|
|
@@ -7067,8 +7067,8 @@ var RequestScheduler = class {
|
|
|
7067
7067
|
reset() {
|
|
7068
7068
|
const { phase, pending, abort } = this.#state;
|
|
7069
7069
|
if (phase.type === "coalescing") clearTimeout(phase.timeoutId);
|
|
7070
|
-
|
|
7071
|
-
|
|
7070
|
+
for (const rtu of pending.rtuDelayed.values()) clearTimeout(rtu.timeoutId);
|
|
7071
|
+
for (const delayed of pending.mediumPriorityDelayed.values()) clearTimeout(delayed.timeoutId);
|
|
7072
7072
|
if (abort.controller) abort.controller.abort();
|
|
7073
7073
|
this.#state = this.#createInitialState();
|
|
7074
7074
|
}
|
|
@@ -7078,15 +7078,18 @@ var RequestScheduler = class {
|
|
|
7078
7078
|
* regains focus so a refetch priced with the background throttle doesn't
|
|
7079
7079
|
* keep the tab stale. Never extends the pending delay. */
|
|
7080
7080
|
reevaluateDelayedRTU() {
|
|
7081
|
-
|
|
7082
|
-
if (
|
|
7081
|
+
if (!this.#dynamicRealtimeThrottleMs) return;
|
|
7082
|
+
if (this.#state.pending.rtuDelayed.size === 0) return;
|
|
7083
7083
|
const { timing } = this.#state;
|
|
7084
|
-
|
|
7085
|
-
|
|
7086
|
-
|
|
7087
|
-
|
|
7088
|
-
this.#
|
|
7089
|
-
this.#
|
|
7084
|
+
const newFireAt = timing.lastFetchStartTime + timing.lastFetchDuration + this.#dynamicRealtimeThrottleMs(timing.lastFetchDuration);
|
|
7085
|
+
for (const rtu of Array.from(this.#state.pending.rtuDelayed.values())) {
|
|
7086
|
+
if (newFireAt >= rtu.fireAt) continue;
|
|
7087
|
+
clearTimeout(rtu.timeoutId);
|
|
7088
|
+
this.#state.pending.rtuDelayed.delete(rtu.requestId);
|
|
7089
|
+
if (!this.#scheduleDelayedRTU(Date.now(), rtu.requestId, rtu.payload, rtu.remoteStartCancelable)) {
|
|
7090
|
+
this.#onEvent?.("scheduled-rt-fetch-started");
|
|
7091
|
+
this.#scheduleRequest(rtu.requestId, "highPriority", rtu.payload, void 0, rtu.remoteStartCancelable);
|
|
7092
|
+
}
|
|
7090
7093
|
}
|
|
7091
7094
|
}
|
|
7092
7095
|
cancelCoalescingRequests(requestIds) {
|
|
@@ -7102,20 +7105,24 @@ var RequestScheduler = class {
|
|
|
7102
7105
|
this.#finalizePendingRequestCallbacks(scheduledRequest, false);
|
|
7103
7106
|
wasCancelled = true;
|
|
7104
7107
|
}
|
|
7105
|
-
const
|
|
7106
|
-
|
|
7107
|
-
|
|
7108
|
-
|
|
7108
|
+
for (const requestId of requestIds) {
|
|
7109
|
+
const rtuDelayed = this.#state.pending.rtuDelayed.get(requestId);
|
|
7110
|
+
if (rtuDelayed && matchesShouldCancel(shouldCancel, requestId, rtuDelayed)) {
|
|
7111
|
+
this.#clearRtuDelayed(requestId);
|
|
7112
|
+
wasCancelled = true;
|
|
7113
|
+
}
|
|
7109
7114
|
}
|
|
7110
|
-
const
|
|
7111
|
-
|
|
7112
|
-
|
|
7113
|
-
|
|
7115
|
+
for (const requestId of requestIds) {
|
|
7116
|
+
const mediumDelayed = this.#state.pending.mediumPriorityDelayed.get(requestId);
|
|
7117
|
+
if (mediumDelayed && matchesShouldCancel(shouldCancel, requestId, mediumDelayed)) {
|
|
7118
|
+
this.#cancelMediumPriority(requestId);
|
|
7119
|
+
wasCancelled = true;
|
|
7120
|
+
}
|
|
7114
7121
|
}
|
|
7115
|
-
if (this.#state.phase.type === "fetching") {
|
|
7116
|
-
const rtuAfterFetch = this.#state.phase.rtuAfterFetch;
|
|
7117
|
-
if (rtuAfterFetch &&
|
|
7118
|
-
this.#state.phase.rtuAfterFetch
|
|
7122
|
+
if (this.#state.phase.type === "fetching") for (const requestId of requestIds) {
|
|
7123
|
+
const rtuAfterFetch = this.#state.phase.rtuAfterFetch.get(requestId);
|
|
7124
|
+
if (rtuAfterFetch && matchesShouldCancel(shouldCancel, requestId, rtuAfterFetch)) {
|
|
7125
|
+
this.#state.phase.rtuAfterFetch.delete(requestId);
|
|
7119
7126
|
wasCancelled = true;
|
|
7120
7127
|
}
|
|
7121
7128
|
}
|
|
@@ -7251,10 +7258,12 @@ var RequestScheduler = class {
|
|
|
7251
7258
|
fetchId,
|
|
7252
7259
|
startTime,
|
|
7253
7260
|
fetchingRequests,
|
|
7254
|
-
rtuAfterFetch:
|
|
7261
|
+
rtuAfterFetch: /* @__PURE__ */ new Map()
|
|
7255
7262
|
};
|
|
7256
|
-
|
|
7257
|
-
|
|
7263
|
+
for (const requestId of requests.keys()) {
|
|
7264
|
+
this.#clearRtuDelayed(requestId);
|
|
7265
|
+
this.#cancelMediumPriority(requestId);
|
|
7266
|
+
}
|
|
7258
7267
|
const shouldAbort = this.#createShouldAbort(fetchId, requests, abortController);
|
|
7259
7268
|
const batchRequests = Array.from(requests.entries()).map(([requestId, request]) => ({
|
|
7260
7269
|
requestId,
|
|
@@ -7278,13 +7287,15 @@ var RequestScheduler = class {
|
|
|
7278
7287
|
}
|
|
7279
7288
|
if (Array.from(results.values()).some((value) => value)) this.#state.timing.lastFetchDuration = Date.now() - startTime;
|
|
7280
7289
|
const { fetchingRequests: callbacks, rtuAfterFetch } = this.#state.phase;
|
|
7281
|
-
this.#clearRtuDelayed();
|
|
7282
7290
|
this.#state.phase = { type: "idle" };
|
|
7283
7291
|
for (const [requestId, { awaitCallbacks }] of callbacks) {
|
|
7284
7292
|
const wasAborted = this.#state.lastAbortedRequests.has(requestId);
|
|
7285
7293
|
for (const callback of awaitCallbacks) callback(wasAborted);
|
|
7286
7294
|
}
|
|
7287
|
-
|
|
7295
|
+
for (const rtu of rtuAfterFetch.values()) if (!this.#scheduleDelayedRTU(Date.now(), rtu.requestId, rtu.payload, rtu.remoteStartCancelable)) {
|
|
7296
|
+
this.#onEvent?.("scheduled-rt-fetch-started");
|
|
7297
|
+
this.#scheduleRequest(rtu.requestId, "highPriority", rtu.payload, void 0, rtu.remoteStartCancelable);
|
|
7298
|
+
}
|
|
7288
7299
|
this.#flushScheduledRequests();
|
|
7289
7300
|
return true;
|
|
7290
7301
|
}
|
|
@@ -7368,30 +7379,35 @@ var RequestScheduler = class {
|
|
|
7368
7379
|
}
|
|
7369
7380
|
return false;
|
|
7370
7381
|
}
|
|
7371
|
-
#clearRtuDelayed() {
|
|
7372
|
-
const rtu = this.#state.pending.rtuDelayed;
|
|
7382
|
+
#clearRtuDelayed(requestId) {
|
|
7383
|
+
const rtu = this.#state.pending.rtuDelayed.get(requestId);
|
|
7373
7384
|
if (rtu) {
|
|
7374
7385
|
clearTimeout(rtu.timeoutId);
|
|
7375
|
-
this.#state.pending.rtuDelayed
|
|
7386
|
+
this.#state.pending.rtuDelayed.delete(requestId);
|
|
7376
7387
|
this.#onEvent?.("rt-fetch-cancelled");
|
|
7377
7388
|
}
|
|
7378
7389
|
}
|
|
7379
7390
|
#handleRealtimeUpdate(startTime, requestId, payload, remoteStartCancelable) {
|
|
7380
7391
|
const { timing, phase, pending } = this.#state;
|
|
7381
7392
|
if (!timing.lastFetchDuration || !timing.lastFetchStartTime || !this.#dynamicRealtimeThrottleMs) return false;
|
|
7382
|
-
|
|
7383
|
-
|
|
7384
|
-
|
|
7393
|
+
const existingDelayed = pending.rtuDelayed.get(requestId);
|
|
7394
|
+
if (existingDelayed) {
|
|
7395
|
+
existingDelayed.payload = this.#coalescePayload ? this.#coalescePayload(existingDelayed.payload, payload) : payload;
|
|
7396
|
+
existingDelayed.remoteStartCancelable = existingDelayed.remoteStartCancelable && remoteStartCancelable;
|
|
7385
7397
|
return true;
|
|
7386
7398
|
}
|
|
7387
7399
|
if (phase.type === "fetching") {
|
|
7388
|
-
phase.rtuAfterFetch
|
|
7400
|
+
const existing = phase.rtuAfterFetch.get(requestId);
|
|
7401
|
+
if (existing) {
|
|
7402
|
+
existing.payload = this.#coalescePayload ? this.#coalescePayload(existing.payload, payload) : payload;
|
|
7403
|
+
existing.remoteStartCancelable = existing.remoteStartCancelable && remoteStartCancelable;
|
|
7404
|
+
} else phase.rtuAfterFetch.set(requestId, {
|
|
7389
7405
|
requestId,
|
|
7390
7406
|
payload,
|
|
7391
7407
|
priority: "realtimeUpdate",
|
|
7392
7408
|
addedAt: startTime,
|
|
7393
7409
|
remoteStartCancelable
|
|
7394
|
-
};
|
|
7410
|
+
});
|
|
7395
7411
|
return true;
|
|
7396
7412
|
}
|
|
7397
7413
|
if (pending.mutationsInProgress.has(requestId)) {
|
|
@@ -7407,9 +7423,11 @@ var RequestScheduler = class {
|
|
|
7407
7423
|
const minimumRealtimeInterval = this.#dynamicRealtimeThrottleMs(timing.lastFetchDuration);
|
|
7408
7424
|
if (timeSinceLastFetch >= minimumRealtimeInterval) return false;
|
|
7409
7425
|
const delay = minimumRealtimeInterval - timeSinceLastFetch;
|
|
7410
|
-
this.#state.pending.rtuDelayed
|
|
7426
|
+
const existing = this.#state.pending.rtuDelayed.get(requestId);
|
|
7427
|
+
if (existing) clearTimeout(existing.timeoutId);
|
|
7428
|
+
this.#state.pending.rtuDelayed.set(requestId, {
|
|
7411
7429
|
timeoutId: setTimeout(() => {
|
|
7412
|
-
this.#state.pending.rtuDelayed
|
|
7430
|
+
this.#state.pending.rtuDelayed.delete(requestId);
|
|
7413
7431
|
this.#onEvent?.("scheduled-rt-fetch-started");
|
|
7414
7432
|
this.#scheduleRequest(requestId, "highPriority", payload, void 0, remoteStartCancelable);
|
|
7415
7433
|
}, delay),
|
|
@@ -7419,7 +7437,7 @@ var RequestScheduler = class {
|
|
|
7419
7437
|
addedAt: startTime,
|
|
7420
7438
|
remoteStartCancelable,
|
|
7421
7439
|
fireAt: startTime + delay
|
|
7422
|
-
};
|
|
7440
|
+
});
|
|
7423
7441
|
this.#onEvent?.("rt-fetch-scheduled", { delayMs: delay });
|
|
7424
7442
|
return true;
|
|
7425
7443
|
}
|
|
@@ -7427,36 +7445,43 @@ var RequestScheduler = class {
|
|
|
7427
7445
|
const delayMs = customDelayMs ?? this.#mediumPriorityDelayMs;
|
|
7428
7446
|
if (delayMs === void 0) throw new Error("[tsdf] mediumPriorityDelayMs must be configured to use mediumPriority fetch type");
|
|
7429
7447
|
if (!this.#state.timing.lastFetchStartTime) return this.#scheduleRequest(requestId, "highPriority", payload, void 0, remoteStartCancelable);
|
|
7430
|
-
|
|
7431
|
-
|
|
7448
|
+
const existing = this.#state.pending.mediumPriorityDelayed.get(requestId);
|
|
7449
|
+
let mergedPayload = payload;
|
|
7450
|
+
let mergedRemoteStartCancelable = remoteStartCancelable;
|
|
7451
|
+
if (existing) {
|
|
7452
|
+
clearTimeout(existing.timeoutId);
|
|
7453
|
+
mergedPayload = this.#coalescePayload ? this.#coalescePayload(existing.payload, payload) : payload;
|
|
7454
|
+
mergedRemoteStartCancelable = existing.remoteStartCancelable && remoteStartCancelable;
|
|
7455
|
+
}
|
|
7456
|
+
this.#state.pending.mediumPriorityDelayed.set(requestId, {
|
|
7432
7457
|
timeoutId: setTimeout(() => {
|
|
7433
7458
|
this.#executeMediumPriorityFetch(requestId);
|
|
7434
7459
|
}, delayMs),
|
|
7435
7460
|
requestId,
|
|
7436
|
-
payload,
|
|
7461
|
+
payload: mergedPayload,
|
|
7437
7462
|
priority: "mediumPriority",
|
|
7438
7463
|
addedAt: startTime,
|
|
7439
|
-
remoteStartCancelable
|
|
7440
|
-
};
|
|
7464
|
+
remoteStartCancelable: mergedRemoteStartCancelable
|
|
7465
|
+
});
|
|
7441
7466
|
this.#onEvent?.("medium-priority-scheduled", { delayMs });
|
|
7442
7467
|
return "medium-scheduled";
|
|
7443
7468
|
}
|
|
7444
7469
|
#executeMediumPriorityFetch(requestId) {
|
|
7445
|
-
const delayedRequest = this.#state.pending.mediumPriorityDelayed;
|
|
7446
|
-
if (!delayedRequest
|
|
7447
|
-
this.#state.pending.mediumPriorityDelayed
|
|
7470
|
+
const delayedRequest = this.#state.pending.mediumPriorityDelayed.get(requestId);
|
|
7471
|
+
if (!delayedRequest) return;
|
|
7472
|
+
this.#state.pending.mediumPriorityDelayed.delete(requestId);
|
|
7448
7473
|
this.#onEvent?.("medium-priority-fetch-started");
|
|
7449
|
-
|
|
7450
|
-
if (phase.type !== "idle" || pending.mutationsInProgress.has(requestId)) {
|
|
7474
|
+
if (this.#state.phase.type === "fetching") {
|
|
7451
7475
|
this.#addToScheduledRequests(requestId, delayedRequest.payload, "mediumPriority", Date.now(), delayedRequest.remoteStartCancelable);
|
|
7452
7476
|
return;
|
|
7453
7477
|
}
|
|
7454
7478
|
this.#scheduleRequest(requestId, "highPriority", delayedRequest.payload, void 0, delayedRequest.remoteStartCancelable);
|
|
7455
7479
|
}
|
|
7456
|
-
#cancelMediumPriority() {
|
|
7457
|
-
|
|
7458
|
-
|
|
7459
|
-
|
|
7480
|
+
#cancelMediumPriority(requestId) {
|
|
7481
|
+
const delayed = this.#state.pending.mediumPriorityDelayed.get(requestId);
|
|
7482
|
+
if (delayed) {
|
|
7483
|
+
clearTimeout(delayed.timeoutId);
|
|
7484
|
+
this.#state.pending.mediumPriorityDelayed.delete(requestId);
|
|
7460
7485
|
this.#onEvent?.("medium-priority-cancelled");
|
|
7461
7486
|
}
|
|
7462
7487
|
}
|
package/docs/fetch-scheduling.md
CHANGED
|
@@ -6,12 +6,12 @@ TSDF uses a `RequestScheduler` to intelligently manage when and how fetches are
|
|
|
6
6
|
|
|
7
7
|
Every fetch request has a priority that determines its behavior:
|
|
8
8
|
|
|
9
|
-
| Priority | When used | Behavior
|
|
10
|
-
| ---------------- | ----------------------------------------------- |
|
|
11
|
-
| `lowPriority` | Hook mount (default), window focus revalidation | Throttled — skipped if a fetch happened recently (within `lowPriorityThrottleMs`)
|
|
12
|
-
| `mediumPriority` | Background refetches | Delayed by `mediumPriorityDelayMs`, then executed. Cancelled if another fetch starts. If the store has never been fetched, automatically promotes to `highPriority` |
|
|
13
|
-
| `realtimeUpdate` | Real-time data pushes | Uses `dynamicRealtimeThrottleMs` for adaptive throttling based on last fetch duration
|
|
14
|
-
| `highPriority` | Explicit invalidation, `ensureIsLoaded` | Executes immediately (after coalescing window). Never throttled
|
|
9
|
+
| Priority | When used | Behavior |
|
|
10
|
+
| ---------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| `lowPriority` | Hook mount (default), window focus revalidation | Throttled — skipped if a fetch happened recently (within `lowPriorityThrottleMs`) |
|
|
12
|
+
| `mediumPriority` | Background refetches | Delayed by `mediumPriorityDelayMs`, then executed. Cancelled if another fetch including the same request starts. If the store has never been fetched, automatically promotes to `highPriority` |
|
|
13
|
+
| `realtimeUpdate` | Real-time data pushes | Uses `dynamicRealtimeThrottleMs` for adaptive throttling based on last fetch duration |
|
|
14
|
+
| `highPriority` | Explicit invalidation, `ensureIsLoaded` | Executes immediately (after coalescing window). Never throttled |
|
|
15
15
|
|
|
16
16
|
## Throttling
|
|
17
17
|
|
|
@@ -62,11 +62,13 @@ This prevents race conditions where a fetch could overwrite optimistic updates.
|
|
|
62
62
|
Medium-priority fetches have special behavior:
|
|
63
63
|
|
|
64
64
|
1. The fetch is delayed by `mediumPriorityDelayMs`
|
|
65
|
-
2. If another fetch (of any priority) starts during the delay, the medium-priority fetch is cancelled
|
|
65
|
+
2. If another fetch (of any priority) for the same data starts during the delay, the medium-priority fetch is cancelled
|
|
66
66
|
3. If the store has never been fetched (`wasLoaded === false`), the fetch is promoted to `highPriority` immediately
|
|
67
67
|
|
|
68
68
|
This is useful for background refetches that should yield to user-initiated actions.
|
|
69
69
|
|
|
70
|
+
Delayed medium-priority fetches are tracked per request: on schedulers shared by multiple items (batch fetching via `getItemsBatchKey`), each item keeps its own delay timer, and a fetch of one item does not cancel another item's pending medium-priority refetch. Re-invalidating the same item during the delay resets its timer.
|
|
71
|
+
|
|
70
72
|
## Configuration Reference
|
|
71
73
|
|
|
72
74
|
| Option | Required | Description |
|