tsdf 17.0.2 → 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.
@@ -1,2 +1,2 @@
1
- import { t as opfsPersistentStorage } from "./opfsPersistentStorage-BB0qqnRz.js";
1
+ import { t as opfsPersistentStorage } from "./opfsPersistentStorage-BngS1m0X.js";
2
2
  export { opfsPersistentStorage };
@@ -1,2 +1,2 @@
1
- import { t as opfsPersistentStorage } from "./opfsPersistentStorage-D_k77Srq.js";
1
+ import { t as opfsPersistentStorage } from "./opfsPersistentStorage-JsSCNBTr.js";
2
2
  export { opfsPersistentStorage };
@@ -1,4 +1,4 @@
1
- import { t as AsyncStorageAdapter } from "./types-aWgyZHLj.js";
1
+ import { t as AsyncStorageAdapter } from "./types-BlyGC_PO.js";
2
2
 
3
3
  //#region src/persistentStorage/opfsPersistentStorage.d.ts
4
4
  declare const opfsPersistentStorage: AsyncStorageAdapter;
@@ -1,4 +1,4 @@
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";
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";
@@ -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; /** Convenience flag for `loading` or `refetching` states. */
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; /** Convenience flag for `loading` or `refetching` states. */
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/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 automatically invalidates the data, causing a refetch that reverts the optimistic update to the server's actual state.
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 updates to their pre-mutation state. Non-optimistic mutations leave state untouched on error.
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/package.json CHANGED
@@ -1,10 +1,13 @@
1
1
  {
2
2
  "name": "tsdf",
3
- "version": "17.0.2",
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": "github:lucasols/tsdf",
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",