tsdf 17.0.0 → 17.0.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/async-storage.d.ts +1 -1
- package/dist/async-storage.js +1 -1
- package/dist/{asyncStorageAdapter-BBKVK1S_.js → asyncStorageAdapter-BuGjbXYA.js} +154 -5
- package/dist/{asyncStorageAdapter-CMohMeKm.d.ts → asyncStorageAdapter-DuAUANgu.d.ts} +1 -1
- package/dist/{asyncStorageAdapters-CkGt87Po.js → asyncStorageAdapters-ClUvxNQA.js} +2 -2
- package/dist/indexed-db-storage.d.ts +1 -1
- package/dist/indexed-db-storage.js +1 -1
- package/dist/{indexedDbPersistentStorage-D5tGmD77.js → indexedDbPersistentStorage-BSlgLveB.js} +1 -1
- package/dist/main.d.ts +56 -30
- package/dist/main.js +842 -255
- package/dist/opfs-storage.d.ts +1 -1
- package/dist/opfs-storage.js +1 -1
- package/dist/{opfsPersistentStorage-Ci0JcCo5.d.ts → opfsPersistentStorage-BB0qqnRz.d.ts} +1 -1
- package/dist/{opfsPersistentStorage-B_lVflof.js → opfsPersistentStorage-D_k77Srq.js} +1 -1
- package/dist/{types-D0ttVGmj.d.ts → types-aWgyZHLj.d.ts} +1 -1
- package/docs/fetch-scheduling.md +6 -1
- package/docs/hooks.md +39 -4
- package/docs/persistent-storage.md +1 -0
- package/docs/shared-types.md +2 -1
- package/package.json +1 -1
package/dist/opfs-storage.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import { t as opfsPersistentStorage } from "./opfsPersistentStorage-
|
|
1
|
+
import { t as opfsPersistentStorage } from "./opfsPersistentStorage-BB0qqnRz.js";
|
|
2
2
|
export { opfsPersistentStorage };
|
package/dist/opfs-storage.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import { t as opfsPersistentStorage } from "./opfsPersistentStorage-
|
|
1
|
+
import { t as opfsPersistentStorage } from "./opfsPersistentStorage-D_k77Srq.js";
|
|
2
2
|
export { opfsPersistentStorage };
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { G as getPayloadRecordKey, J as parseAsyncStorageRecordKey, U as encodePersistedAsyncNamespaceKind, W as getNamespaceId, Y as parsePersistedAsyncNamespaceKind, _ as getTSDFDebugTimingMs, g as emitTSDFDebugLog, i as createAsyncStorageAdapter } from "./asyncStorageAdapter-BuGjbXYA.js";
|
|
2
2
|
import { getCompositeKey } from "@ls-stack/utils/getCompositeKey";
|
|
3
3
|
import { __LEGIT_CAST__ } from "@ls-stack/utils/saferTyping";
|
|
4
4
|
import { isObject } from "@ls-stack/utils/typeGuards";
|
|
@@ -58,7 +58,7 @@ type MaybeTSDFResult<T> = T | Result<T, ResultValidErrors>;
|
|
|
58
58
|
*
|
|
59
59
|
* The hook still reads data from state using the latest payload immediately.
|
|
60
60
|
* Only the automatic fetch side is delayed. Single hooks do not support
|
|
61
|
-
* combining this with `
|
|
61
|
+
* combining this with `requireFreshData`.
|
|
62
62
|
*/
|
|
63
63
|
type PayloadDebounce = {
|
|
64
64
|
/** Debounce window in milliseconds before the latest payload is fetched. */ms: number;
|
package/docs/fetch-scheduling.md
CHANGED
|
@@ -11,7 +11,7 @@ Every fetch request has a priority that determines its behavior:
|
|
|
11
11
|
| `lowPriority` | Hook mount (default), window focus revalidation | Throttled — skipped if a fetch happened recently (within `lowPriorityThrottleMs`) |
|
|
12
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
13
|
| `realtimeUpdate` | Real-time data pushes | Uses `dynamicRealtimeThrottleMs` for adaptive throttling based on last fetch duration |
|
|
14
|
-
| `highPriority` | Explicit invalidation, `
|
|
14
|
+
| `highPriority` | Explicit invalidation, `requireFreshData` | Executes immediately (after coalescing window). Never throttled |
|
|
15
15
|
|
|
16
16
|
## Throttling
|
|
17
17
|
|
|
@@ -23,6 +23,11 @@ lowPriorityThrottleMs: 40 * 60 * 1_000
|
|
|
23
23
|
|
|
24
24
|
If a hook mounts within the configured throttle window after the last fetch completed, the low-priority fetch is **skipped** because the data is still fresh enough.
|
|
25
25
|
|
|
26
|
+
`requireFreshData` deliberately bypasses this mount throttling by scheduling a
|
|
27
|
+
high-priority fetch even when successful cached data exists. Use it only when a
|
|
28
|
+
component must wait for a server refresh attempt before reporting a ready
|
|
29
|
+
status; applying it broadly can turn remounts into repeated network requests.
|
|
30
|
+
|
|
26
31
|
## Coalescing
|
|
27
32
|
|
|
28
33
|
When multiple fetch requests arrive in a short window, they are coalesced into a single batch:
|
package/docs/hooks.md
CHANGED
|
@@ -22,7 +22,40 @@ These options are available across all data hooks:
|
|
|
22
22
|
| `disableRefetchOnMount` | `false` (or `true` when `usesRealTimeUpdates` is enabled) | Only fetches if data was explicitly invalidated or has never been loaded. Skips the low-priority refetch that normally happens on mount |
|
|
23
23
|
| `returnIdleStatus` | `true` when disabled, `false` otherwise | When `false`, maps `idle` status to `loading` so the UI shows a loading state immediately |
|
|
24
24
|
| `returnRefetchingStatus` | `false` | When `false`, maps `refetching` status to `success` so the UI doesn't flicker during background refetches |
|
|
25
|
-
| `
|
|
25
|
+
| `requireFreshData` | `false` | Unconditionally schedules a high-priority mount fetch and reports `loading` until it settles. Use sparingly because mounts can cause extra requests |
|
|
26
|
+
|
|
27
|
+
## `requireFreshData`
|
|
28
|
+
|
|
29
|
+
Most components should use the default mount behavior. TSDF normally serves
|
|
30
|
+
cached data immediately and uses low-priority mount scheduling, which allows
|
|
31
|
+
the scheduler to throttle or skip redundant requests.
|
|
32
|
+
|
|
33
|
+
Set `requireFreshData: true` only when a component must not report itself as
|
|
34
|
+
ready until it has attempted to refresh from the server:
|
|
35
|
+
|
|
36
|
+
```tsx
|
|
37
|
+
const result = store.useDocument({ requireFreshData: true });
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
This option changes both fetching and the returned status:
|
|
41
|
+
|
|
42
|
+
- Every enabled hook mount unconditionally schedules a `highPriority` fetch,
|
|
43
|
+
even when the cache already contains successful data.
|
|
44
|
+
- Cached data remains available in `data`, but `status` is reported as
|
|
45
|
+
`loading` and `isLoading` as `true` until the refresh settles.
|
|
46
|
+
- A successful refresh reports `success`; a failed refresh reports `error`.
|
|
47
|
+
The option requires a refresh attempt—it cannot guarantee fresh data when
|
|
48
|
+
the request fails.
|
|
49
|
+
- It takes precedence over `disableRefetches` and `disableRefetchOnMount`.
|
|
50
|
+
Disabled hooks do not fetch.
|
|
51
|
+
- Scheduler coalescing can merge simultaneous work, but repeated mounts can
|
|
52
|
+
still produce repeated network requests.
|
|
53
|
+
|
|
54
|
+
Avoid enabling this broadly in shared hooks, list rows, or route-level
|
|
55
|
+
components. Doing so bypasses TSDF's normal low-priority mount throttling and
|
|
56
|
+
can significantly increase request volume. Prefer the default cache behavior,
|
|
57
|
+
targeted invalidation, or an explicit user-triggered refresh unless readiness
|
|
58
|
+
truly depends on a new server response.
|
|
26
59
|
|
|
27
60
|
## `debouncePayload`
|
|
28
61
|
|
|
@@ -44,7 +77,7 @@ Behavior:
|
|
|
44
77
|
- Intermediate payloads are skipped if they are replaced before the debounce
|
|
45
78
|
window ends
|
|
46
79
|
- `useItem` and `useListQuery` throw if `debouncePayload` is combined with
|
|
47
|
-
`
|
|
80
|
+
`requireFreshData`
|
|
48
81
|
|
|
49
82
|
### Basic trailing debounce
|
|
50
83
|
|
|
@@ -158,7 +191,8 @@ const item = store.useItem(selectedItemId, {
|
|
|
158
191
|
This is useful when `selectedItemId` changes rapidly, such as typeahead-driven
|
|
159
192
|
selection or fast keyboard navigation.
|
|
160
193
|
|
|
161
|
-
`
|
|
194
|
+
`requireFreshData` cannot be combined with `debouncePayload` on single hooks
|
|
195
|
+
because the required refresh must be scheduled immediately.
|
|
162
196
|
|
|
163
197
|
### List Query Store specific options
|
|
164
198
|
|
|
@@ -225,7 +259,8 @@ const result = store.useListQuery(
|
|
|
225
259
|
);
|
|
226
260
|
```
|
|
227
261
|
|
|
228
|
-
`
|
|
262
|
+
`requireFreshData` cannot be combined with `debouncePayload` on `useListQuery`
|
|
263
|
+
because the required refresh must be scheduled immediately.
|
|
229
264
|
|
|
230
265
|
This is useful for search forms and filter panels where the query payload
|
|
231
266
|
changes on every keystroke.
|
|
@@ -137,6 +137,7 @@ TSDF does not choose a persistence adapter automatically. Pass one of the built-
|
|
|
137
137
|
- Can hydrate synchronously during initial state creation for `DocumentStore`.
|
|
138
138
|
- `CollectionStore` and `ListQueryStore` use lazy hydration for unknown entries from initial keys scan.
|
|
139
139
|
- Writes are debounced and may be dropped if serialization errors occur.
|
|
140
|
+
- Scheduled expiration and byte-budget maintenance is split across browser idle deadlines. Timeout-fired callbacks and browsers without `requestIdleCallback` use short timer-backed slices, so large scans and eviction batches yield between slices while keeping payload entries and manifests consistent.
|
|
140
141
|
- When a write hits the browser `QuotaExceededError` (the shared origin quota is full, e.g. because other parts of the app filled `localStorage`), TSDF automatically evicts its own least recently used entries — across all TSDF stores and sessions — and retries, escalating to all non-offline-protected entries if needed. Offline data and non-TSDF keys are never touched. If even that cannot free enough space, a single descriptive error is reported through `onPersistentStorageError` and persistence writes are silently skipped until the next page load. Removals of persisted entries (e.g. after deleting an item) still go through while writes are disabled, so deleted data never resurrects on the next load.
|
|
141
142
|
|
|
142
143
|
Use it with:
|
package/docs/shared-types.md
CHANGED
|
@@ -108,7 +108,8 @@ Important behavior:
|
|
|
108
108
|
- If cached data already exists for the latest payload, the hook can still
|
|
109
109
|
return it immediately while the fetch is deferred
|
|
110
110
|
- `useItem` and `useListQuery` do not support combining `debouncePayload` with
|
|
111
|
-
`
|
|
111
|
+
`requireFreshData`, because that option requires an immediate high-priority
|
|
112
|
+
refresh
|
|
112
113
|
|
|
113
114
|
Example:
|
|
114
115
|
|