tsdf 17.0.1 → 17.0.3
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-CMohMeKm.d.ts → asyncStorageAdapter-DgsuE-T8.d.ts} +1 -1
- package/dist/{asyncStorageAdapter-BuGjbXYA.js → asyncStorageAdapter-URS9eulL.js} +165 -25
- package/dist/{asyncStorageAdapters-ClUvxNQA.js → asyncStorageAdapters-Bxrrj_Mt.js} +2 -2
- package/dist/indexed-db-storage.d.ts +1 -1
- package/dist/indexed-db-storage.js +1 -1
- package/dist/{indexedDbPersistentStorage-BSlgLveB.js → indexedDbPersistentStorage-BameJ4st.js} +11 -1
- package/dist/main.d.ts +34 -30
- package/dist/main.js +856 -257
- package/dist/opfs-storage.d.ts +1 -1
- package/dist/opfs-storage.js +1 -1
- package/dist/{opfsPersistentStorage-Ci0JcCo5.d.ts → opfsPersistentStorage-BngS1m0X.d.ts} +1 -1
- package/dist/{opfsPersistentStorage-D_k77Srq.js → opfsPersistentStorage-JsSCNBTr.js} +1 -1
- package/dist/{types-D0ttVGmj.d.ts → types-BlyGC_PO.d.ts} +3 -3
- package/docs/browser-tabs-sync.md +2 -0
- package/docs/fetch-scheduling.md +6 -1
- package/docs/hooks.md +39 -4
- package/docs/mutations.md +7 -3
- package/docs/persistent-storage.md +2 -0
- package/docs/shared-types.md +2 -1
- package/package.json +5 -2
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-BngS1m0X.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-JsSCNBTr.js";
|
|
2
2
|
export { opfsPersistentStorage };
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { $ as parseAsyncStorageRecordKey, J as getNamespaceId, Y as getPayloadRecordKey, b as getTSDFDebugTimingMs, et as parsePersistedAsyncNamespaceKind, i as createAsyncStorageAdapter, q as encodePersistedAsyncNamespaceKind, y as emitTSDFDebugLog } from "./asyncStorageAdapter-URS9eulL.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;
|
|
@@ -175,7 +175,7 @@ type TSFDUseListQueryReturn<Selected, QueryPayload, QueryMetadata extends undefi
|
|
|
175
175
|
error: StoreError | null; /** Stable store key for the current query payload. */
|
|
176
176
|
queryKey: string; /** Whether another page is available. */
|
|
177
177
|
hasMore: boolean; /** Whether this result was derived from local items instead of fetched directly. */
|
|
178
|
-
isDerived: boolean; /**
|
|
178
|
+
isDerived: boolean; /** Shorthand for `status === 'loading'`. Stays `false` while loaded data is `refetching`. */
|
|
179
179
|
isLoading: boolean; /** Whether a `loadMore(...)` request is currently active. */
|
|
180
180
|
isLoadingMore: boolean; /** Whether this result has local offline changes that still need to sync to the server. */
|
|
181
181
|
pendingSync: boolean; /** Caller-provided metadata copied from the query descriptor. */
|
|
@@ -187,7 +187,7 @@ type TSFDUseListItemReturn<Selected, ItemPayload, QueryMetadata extends undefine
|
|
|
187
187
|
status: QueryStatus | 'idle' | 'deleted'; /** Item payload for this result, or `null` when unavailable. */
|
|
188
188
|
payload: ItemPayload | null; /** Requested partial-resource fields that are still pending. */
|
|
189
189
|
loadingFields?: string[]; /** Last item fetch error, if any. */
|
|
190
|
-
error: StoreError | null; /**
|
|
190
|
+
error: StoreError | null; /** Shorthand for `status === 'loading'`. Stays `false` while loaded data is `refetching`. */
|
|
191
191
|
isLoading: boolean; /** Stable store key for the current item payload. */
|
|
192
192
|
itemStateKey: string; /** Whether this result has local offline changes that still need to sync to the server. */
|
|
193
193
|
pendingSync: boolean; /** Caller-provided metadata copied from the query descriptor. */
|
|
@@ -28,6 +28,8 @@ Tabs use a versioned message model so later snapshots do not overwrite fresher r
|
|
|
28
28
|
- Background tabs are ranked and may receive an extended coalescing window (`base` + `backgroundCoalescingDelayMs` + background rank \* `1000ms`), which helps avoid duplicate background refetch work. The first background tab uses rank `0`, so the default first background window is `base + 3000ms`.
|
|
29
29
|
- `fetch-start` messages let sibling tabs drop duplicate scheduled work when another tab is already fetching the same request IDs.
|
|
30
30
|
- Confirmed snapshots from one tab are only applied to others when remote ordering says they are newer than the current version.
|
|
31
|
+
- While a tab has a mutation in flight for a document, item, or query, confirmed snapshots from other tabs for it are ignored so they cannot overwrite the local optimistic state. When the last mutation ends, the tab revalidates that data unless its state already matches the latest ignored snapshot, so all tabs converge again.
|
|
32
|
+
- Sync is best effort: if a message cannot be posted (for example, state holding functions makes `BroadcastChannel` throw a `DataCloneError`), it is skipped with a development-only warning and the local fetch, mutation, or state update still completes normally.
|
|
31
33
|
|
|
32
34
|
## Isolation
|
|
33
35
|
|
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.
|
package/docs/mutations.md
CHANGED
|
@@ -81,7 +81,7 @@ The payload can be:
|
|
|
81
81
|
|
|
82
82
|
## Mutation Lifecycle
|
|
83
83
|
|
|
84
|
-
1. **Lock**: The scheduler is locked for the affected items/queries, preventing concurrent fetches
|
|
84
|
+
1. **Lock**: The scheduler is locked for the affected items/queries, preventing concurrent fetches. An in-flight fetch for them is aborted so it can't commit stale data, and it is retried once the lock is released. Calls awaiting the aborted fetch (e.g. `awaitFetch`, `getItemFromStateOrFetch`) resolve with the retry's result
|
|
85
85
|
2. **Optimistic update**: If provided, runs immediately. If it returns `false`, the mutation is cancelled
|
|
86
86
|
3. **Debounce** (optional): Waits for `ms` milliseconds. During debounce, the window close is blocked
|
|
87
87
|
4. **Execute mutation**: The async mutation function runs
|
|
@@ -128,7 +128,7 @@ await store.performMutation('item-id', {
|
|
|
128
128
|
});
|
|
129
129
|
```
|
|
130
130
|
|
|
131
|
-
If the mutation **fails**, TSDF
|
|
131
|
+
If the mutation **fails**, TSDF reverts the optimistic update (see [Error Handling](#error-handling)).
|
|
132
132
|
|
|
133
133
|
### Cancelling a Mutation
|
|
134
134
|
|
|
@@ -159,6 +159,8 @@ await store.performMutation({
|
|
|
159
159
|
|
|
160
160
|
During the debounce period, the window close is blocked to prevent data loss.
|
|
161
161
|
|
|
162
|
+
Superseded calls never send their mutation, so their optimistic updates are handed to the call that superseded them: if that call fails, the state goes back to what it was before the first superseded call.
|
|
163
|
+
|
|
162
164
|
## Revalidation on Success
|
|
163
165
|
|
|
164
166
|
| Option | Behavior |
|
|
@@ -171,7 +173,9 @@ During the debounce period, the window close is blocked to prevent data loss.
|
|
|
171
173
|
|
|
172
174
|
### Error Handling
|
|
173
175
|
|
|
174
|
-
On error, TSDF **rolls back** optimistic
|
|
176
|
+
On error, TSDF **rolls back** the optimistic update by restoring the pre-mutation data of each document, item or query it changed. If another mutation changed or saved that data while the mutation was in flight, e.g. a concurrent mutation that succeeded, TSDF revalidates it, keeping any newer data until then, so the state converges to the server once that refetch succeeds. Invalidations received while the mutation was in flight are kept.
|
|
177
|
+
|
|
178
|
+
Non-optimistic mutations leave state untouched on error.
|
|
175
179
|
|
|
176
180
|
## List Query Store Specific Options
|
|
177
181
|
|
|
@@ -131,6 +131,8 @@ Session-level `mutationQueueing` can allow or disallow durable offline mutation
|
|
|
131
131
|
|
|
132
132
|
TSDF does not choose a persistence adapter automatically. Pass one of the built-in adapters or a custom async adapter in every `persistentStorage` config.
|
|
133
133
|
|
|
134
|
+
Scheduled collection and list-query maintenance is deadline-aware for every adapter. TSDF slices its own metadata validation, filtering, and byte-budget ordering across idle callbacks, carrying its progress from one callback to the next. Async adapters additionally commit removals in bounded batches, with each batch using a self-contained driver transaction or write; TSDF never keeps an IndexedDB, OPFS, or custom-driver transaction open while waiting for another idle deadline. Each batch is a conditional remove: the adapter checks every entry's access time, size, version, and offline protection against what the run planned from, in the same write that removes it, and keeps entries that changed meanwhile. TSDF then schedules another maintenance pass that plans from fresh metadata. Adapters created with `createAsyncStorageAdapter` (including the built-in OPFS and IndexedDB adapters) perform this check atomically; for other custom adapters TSDF re-reads metadata right before removing, so a write landing in between is not detected.
|
|
135
|
+
|
|
134
136
|
### `local-sync`
|
|
135
137
|
|
|
136
138
|
- Uses managed `localStorage` entries.
|
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
|
|
package/package.json
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "tsdf",
|
|
3
|
-
"version": "17.0.
|
|
3
|
+
"version": "17.0.3",
|
|
4
4
|
"description": "A data fetching solution based on t-state",
|
|
5
5
|
"license": "PolyForm-Noncommercial-1.0.0",
|
|
6
6
|
"author": "Lucas Santos",
|
|
7
|
-
"repository":
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "github:lucasols/tsdf"
|
|
10
|
+
},
|
|
8
11
|
"type": "module",
|
|
9
12
|
"main": "./dist/main.js",
|
|
10
13
|
"types": "./dist/main.d.ts",
|