tsdf 17.0.0-alpha.4 → 17.0.0-alpha.5

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.d.ts CHANGED
@@ -53,6 +53,17 @@ type MutationSkipped = {
53
53
  kind: 'skipped';
54
54
  };
55
55
  declare const mutationSkipped: MutationSkipped;
56
+ /** Options passed to mutation error handlers. */
57
+ type StoreMutationErrorOptions = {
58
+ /**
59
+ * True when the mutation caller asked the shared error handler to stay quiet.
60
+ *
61
+ * Handlers are still called so apps can keep centralized logging, metrics, or
62
+ * custom recovery behavior while suppressing user-facing noise such as toast
63
+ * notifications.
64
+ */
65
+ silentErrors?: boolean;
66
+ };
56
67
  declare class StoreMutationError extends Error {
57
68
  readonly kind = "error";
58
69
  code: number;
@@ -1426,10 +1437,7 @@ type StoreManagerStoreDefaults = {
1426
1437
  readonly blockWindowClose: BlockWindowCloseHandler | null; /** Default focus revalidation policy for attached stores. */
1427
1438
  readonly revalidateOnWindowFocus: boolean | (() => boolean) | undefined;
1428
1439
  };
1429
- type StoreManagerMutationErrorHandler = (error: unknown, options: {
1430
- dontShowToast?: boolean;
1431
- silentErrors?: boolean;
1432
- }) => void;
1440
+ type StoreManagerMutationErrorHandler = (error: unknown, options: StoreMutationErrorOptions) => void;
1433
1441
  type StoreManagerOfflineApi<TUploadRef extends ValidPayload = ValidPayload> = {
1434
1442
  /** Returns the shared offline config, when configured. */getOfflineConfig: () => OfflineSessionConfig<TUploadRef> | undefined; /** Latest effective runtime config for this manager's offline session. */
1435
1443
  getOfflineRuntimeConfig: () => OfflineRuntimeConfig; /** Updates runtime controls for this manager's offline session. */
@@ -1656,9 +1664,13 @@ type CollectionStoreOptions<ItemState extends ValidStoreState, ItemPayload exten
1656
1664
  transportReconnectCooldownMs?: number;
1657
1665
  onInvalidate?: OnCollectionItemInvalidate<ItemState, ItemPayload>;
1658
1666
  onSchedulerEvent?: (event: RequestSchedulerEvents, data?: RequestSchedulerEventData) => void;
1659
- onMutationError?: ((error: unknown, options: {
1660
- silentErrors?: boolean;
1661
- }) => void) | null;
1667
+ /**
1668
+ * Store-specific mutation error handler.
1669
+ *
1670
+ * Overrides the manager fallback. Use `null` to disable inherited mutation
1671
+ * error handling for this store.
1672
+ */
1673
+ onMutationError?: ((error: unknown, options: StoreMutationErrorOptions) => void) | null;
1662
1674
  usesRealTimeUpdates?: boolean;
1663
1675
  /** Opt-in persistent storage configuration. When provided, cached items are loaded
1664
1676
  * from storage on first read and saved back on successful fetches.
@@ -1678,11 +1690,22 @@ type CollectionMutationPayload<ItemPayload extends ValidPayload> = ItemPayload |
1678
1690
  type CollectionMutationTarget<ItemPayload extends ValidPayload> = ItemPayload | ItemPayload[];
1679
1691
  type CollectionMutationPayloadToUse<ItemPayload extends ValidPayload> = CollectionMutationTarget<ItemPayload>;
1680
1692
  type CollectionMutationArgsBase<T, ItemPayload extends ValidPayload> = {
1681
- optimisticUpdate?: (payload: CollectionMutationPayloadToUse<ItemPayload>) => void | boolean;
1682
- mutation: (payload: CollectionMutationPayloadToUse<ItemPayload>) => Promise<T>;
1683
- onSuccess?: (response: Awaited<T>, payload: CollectionMutationPayloadToUse<ItemPayload>) => void;
1693
+ /**
1694
+ * Applies optimistic updates for the affected item payloads before the
1695
+ * mutation runs. Return `false` to cancel the mutation before the async
1696
+ * mutation function is called.
1697
+ */
1698
+ optimisticUpdate?: (payload: CollectionMutationPayloadToUse<ItemPayload>) => void | boolean; /** Performs the server mutation for the affected item payloads. */
1699
+ mutation: (payload: CollectionMutationPayloadToUse<ItemPayload>) => Promise<T>; /** Called after a successful online mutation. */
1700
+ onSuccess?: (response: Awaited<T>, payload: CollectionMutationPayloadToUse<ItemPayload>) => void; /** Invalidates affected items after a successful online mutation. */
1684
1701
  revalidateOnSuccess?: boolean;
1685
- silentErrors?: boolean;
1702
+ /**
1703
+ * Passes `{ silentErrors: true }` to `onMutationError`.
1704
+ *
1705
+ * The handler is still called so centralized logging and recovery can run,
1706
+ * but UI handlers can suppress user-facing notifications.
1707
+ */
1708
+ silentErrors?: boolean; /** Debounces mutations with the same context and payload. Superseded calls are skipped. */
1686
1709
  debounce?: {
1687
1710
  context: string;
1688
1711
  payload: __LEGIT_ANY__;
@@ -1866,9 +1889,13 @@ type DocumentStoreOptions<State extends ValidStoreState, TOfflineOperations exte
1866
1889
  transportReconnectCooldownMs?: number;
1867
1890
  mediumPriorityDelayMs?: number;
1868
1891
  onSchedulerEvent?: (event: RequestSchedulerEvents, data?: RequestSchedulerEventData) => void;
1869
- onMutationError?: ((error: unknown, options: {
1870
- dontShowToast?: boolean;
1871
- }) => void) | null;
1892
+ /**
1893
+ * Store-specific mutation error handler.
1894
+ *
1895
+ * Overrides the manager fallback. Use `null` to disable inherited mutation
1896
+ * error handling for this store.
1897
+ */
1898
+ onMutationError?: ((error: unknown, options: StoreMutationErrorOptions) => void) | null;
1872
1899
  usesRealTimeUpdates?: boolean;
1873
1900
  /** Opt-in persistent storage configuration. When provided, cached data is loaded
1874
1901
  * from storage on first read and saved back on successful fetches.
@@ -1879,18 +1906,30 @@ type DocumentStoreOptions<State extends ValidStoreState, TOfflineOperations exte
1879
1906
  type ResolvedDocumentOfflineOperations<TOfflineOperations> = TOfflineOperations extends null ? Record<never, never> : Exclude<TOfflineOperations, null>;
1880
1907
  type DocumentUpdateState<State extends ValidStoreState> = (produceNewData: (draftData: State) => State | void | undefined) => boolean;
1881
1908
  type DocumentMutationContext<State extends ValidStoreState> = {
1882
- updateState: DocumentUpdateState<State>;
1909
+ /** Updates the current document state during the mutation. Returns `false` when no document data is loaded. */updateState: DocumentUpdateState<State>; /** Document state at the moment the mutation function runs. */
1883
1910
  currentState: State | null;
1884
1911
  };
1885
1912
  type DocumentMutationArgsBase<State extends ValidStoreState, T> = {
1886
- optimisticUpdate?: (currentState: State | null) => void | boolean;
1887
- mutation: (ctx: DocumentMutationContext<State>) => Promise<T>;
1913
+ /**
1914
+ * Applies an optimistic document update before the mutation runs.
1915
+ *
1916
+ * Return `false` to cancel the mutation before the async mutation function is
1917
+ * called.
1918
+ */
1919
+ optimisticUpdate?: (currentState: State | null) => void | boolean; /** Performs the server mutation. */
1920
+ mutation: (ctx: DocumentMutationContext<State>) => Promise<T>; /** Debounces mutations with the same context and payload. Superseded calls are skipped. */
1888
1921
  debounce?: {
1889
1922
  context: string;
1890
1923
  payload: __LEGIT_ANY__;
1891
1924
  ms: number;
1892
1925
  };
1893
- dontShowErrorToast?: boolean;
1926
+ /**
1927
+ * Passes `{ silentErrors: true }` to `onMutationError`.
1928
+ *
1929
+ * The handler is still called so centralized logging and recovery can run,
1930
+ * but UI handlers can suppress user-facing notifications.
1931
+ */
1932
+ silentErrors?: boolean; /** Invalidates the document after a successful online mutation. */
1894
1933
  revalidateOnSuccess?: boolean;
1895
1934
  };
1896
1935
  type DocumentOnlineMutationArgs<State extends ValidStoreState, T> = DocumentMutationArgsBase<State, T> & {
@@ -2592,9 +2631,13 @@ type ListQueryStoreOptionsBase<ItemState extends ValidStoreState, QueryPayload e
2592
2631
  onInvalidateQuery?: OnListQueryInvalidate<QueryPayload>;
2593
2632
  onInvalidateItem?: OnListQueryItemInvalidate<ItemState, ItemPayload>;
2594
2633
  onSchedulerEvent?: (event: RequestSchedulerEvents, data?: RequestSchedulerEventData) => void;
2595
- onMutationError?: ((error: unknown, options: {
2596
- silentErrors?: boolean;
2597
- }) => void) | null; /** Opt-in hook-level query derivation from locally materialized items. */
2634
+ /**
2635
+ * Store-specific mutation error handler.
2636
+ *
2637
+ * Overrides the manager fallback. Use `null` to disable inherited mutation
2638
+ * error handling for this store.
2639
+ */
2640
+ onMutationError?: ((error: unknown, options: StoreMutationErrorOptions) => void) | null; /** Opt-in hook-level query derivation from locally materialized items. */
2598
2641
  derivedQueries?: DerivedQueriesConfig<ItemState, QueryPayload, ItemPayload>;
2599
2642
  getQueryKey?: (params: QueryPayload) => ValidPayload | unknown[];
2600
2643
  getItemKey?: (params: ItemPayload) => ValidPayload | unknown[];
@@ -2786,4 +2829,4 @@ declare function clearAllSessionStorage(sessionKey: string): Promise<void>;
2786
2829
  //#region src/persistentStorage/opfsOfflineUploadAdapter.d.ts
2787
2830
  declare const opfsOfflineUploadAdapter: OfflineUploadAdapter;
2788
2831
  //#endregion
2789
- export { ALL_QUERY_AND_ITEMS, type AsyncStorageAdapter, type AsyncStorageDiscoveredScope, type AsyncStorageDriver, type AsyncStorageDriverSetEntry, type AsyncStorageMetadataOrder, type AsyncStorageNamespaceCommitArgs, type AsyncStorageNamespaceCommitTouch, type AsyncStorageNamespaceCommitUpsert, type AsyncStorageNamespaceGetResult, type AsyncStorageNamespaceHandle, type AsyncStorageNamespaceKind, type AsyncStorageNamespaceScope, type AsyncStorageReadOptions, type BlockWindowCloseHandler, CollectionBrowserTabsMessage, CollectionInitialStateItem, CollectionItemStatus, type CollectionOfflineEntityRef, type CollectionOfflineOperationDefinition, type CollectionPersistentStorageConfig, CollectionStateCleanup, CollectionStore, CollectionStoreEvents, CollectionStoreOptions, CollectionStoreStoreEvents, CollectionUseMultipleItemsQuery, type ConvertedPersistentStorageDataSchema, type CreateStoreManagerOptions, type DefineCollectionOfflineOperations, type DefineDocumentOfflineOperations, type DefineListQueryOfflineOperations, type DefineOfflineOperation, type DerivedQueriesConfig, type DerivedQueryContext, type DerivedQuerySource, DocumentBrowserTabsMessage, type DocumentOfflineOperationDefinition, type DocumentPersistentStorageConfig, DocumentStatus, DocumentStore, DocumentStoreOptions, DocumentStoreState, DocumentStoreStoreEvents, type FetchListFnReturn, type FetchListFnReturnItem, type FieldsInput, type FieldsOption, GET_ALL, type GlobalOfflineEntity, type GlobalOfflineStatus, type IndexedDbPersistentStorageOptions, IsOffScreenContext, type ListQueryOfflineEntityRef, type ListQueryOfflineOperationDefinition, type ListQueryPersistentStorageConfig, type ListQueryStore, type ListQueryStoreEvents, type ListQueryStoreInitialData, type ListQueryStoreOptions, type ListQueryUseMultipleItemsQuery, type ListQueryUseMultipleListQueriesQuery, type MutationDebounce, type MutationSkipped, type OfflineAccumulationConfig, type OfflineAccumulationMergeContext, type OfflineConflictResolutionAction, type OfflineEntityMutationKind, type OfflineMutationDescriptor, type OfflineMutationInput, type OfflineMutationQueueingCause, type OfflineMutationQueueingConfig, type OfflineMutationQueueingPolicy, type OfflineMutationResult, type OfflineMutationUploadsInput, type OfflineOperationKind, type OfflineOperationUploadsContext, type OfflineQueueEntry, type OfflineReplayRetryConfig, type OfflineResolutionAction, type OfflineResolutionActionForOperation, type OfflineResolutionConflictParseError, type OfflineResolutionConflictParseErrorCode, type OfflineResolutionRecord, type OfflineResolutionRecordForOperation, type OfflineResolutionRecordForStore, type OfflineRetryExhaustedResolutionAction, type OfflineRuntimeConfig, type OfflineRuntimeConfigUpdate, type OfflineSession, type OfflineSessionConfig, type OfflineSessionUploadsConfig, type OfflineStoredUploadRecord, type OfflineSupersedeConfig, type OfflineSyncState, type OfflineTempEntitiesConfig, type OfflineTempEntitiesReconciliation, type OfflineTempEntityConfig, type OfflineTempEntityPendingEntry, type OfflineUpload, type OfflineUploadAdapter, type OfflineUploadProgress, type OfflineUploadSource, type OfflineUploadState, type OfflineUploadTransportContext, type OffsetPaginationConfig, OnCollectionItemInvalidate, OnDocumentInvalidate, type OnListQueryInvalidate, type OnListQueryItemInvalidate, type OperationConflict, type OperationResult, type OptimisticListUpdate, type ParsedOfflineResolutionConflictResultForOperation, type PartialResourcesConfig, type PayloadDebounce, type PersistentStorageBaseConfig, type PersistentStorageDataSchema, type PersistentStoragePreloadResult, type PersistentStorageSchema, type QueryFetchPayload, type QueryStatus, type StorageAdapter, type StoreError, StoreFetchError, type StoreManager, StoreMutationError, type TSDFItemQuery, type TSDFStatus, TSDFUseDocumentReturn, TSFDCollectionItem, TSFDCollectionState, type TSFDListQuery, type TSFDListQueryState, TSFDUseCollectionItemReturn, type TSFDUseListItemReturn, type TSFDUseListQueryReturn, type TSFDUsePendingOfflineItemsReturn, type ValidPayload, type ValidStoreState, clearAllSessionStorage, clearSessionStorage, createAsyncStorageAdapter, createCollectionStore, createDocumentStore, createIndexedDbPersistentStorage, createListQueryStore, createStoreManager, defaultOfflineRuntimeConfig, fetchTypePriority, getGlobalOfflineEntities, getGlobalOfflineResolutions, getGlobalOfflineStatus, indexedDbPersistentStorage, localPersistentStorage, mutationSkipped, opfsOfflineUploadAdapter, opfsPersistentStorage, useGlobalOfflineEntities, useGlobalOfflineResolutions, useGlobalOfflineStatus };
2832
+ export { ALL_QUERY_AND_ITEMS, type AsyncStorageAdapter, type AsyncStorageDiscoveredScope, type AsyncStorageDriver, type AsyncStorageDriverSetEntry, type AsyncStorageMetadataOrder, type AsyncStorageNamespaceCommitArgs, type AsyncStorageNamespaceCommitTouch, type AsyncStorageNamespaceCommitUpsert, type AsyncStorageNamespaceGetResult, type AsyncStorageNamespaceHandle, type AsyncStorageNamespaceKind, type AsyncStorageNamespaceScope, type AsyncStorageReadOptions, type BlockWindowCloseHandler, CollectionBrowserTabsMessage, CollectionInitialStateItem, CollectionItemStatus, type CollectionOfflineEntityRef, type CollectionOfflineOperationDefinition, type CollectionPersistentStorageConfig, CollectionStateCleanup, CollectionStore, CollectionStoreEvents, CollectionStoreOptions, CollectionStoreStoreEvents, CollectionUseMultipleItemsQuery, type ConvertedPersistentStorageDataSchema, type CreateStoreManagerOptions, type DefineCollectionOfflineOperations, type DefineDocumentOfflineOperations, type DefineListQueryOfflineOperations, type DefineOfflineOperation, type DerivedQueriesConfig, type DerivedQueryContext, type DerivedQuerySource, DocumentBrowserTabsMessage, type DocumentOfflineOperationDefinition, type DocumentPersistentStorageConfig, DocumentStatus, DocumentStore, DocumentStoreOptions, DocumentStoreState, DocumentStoreStoreEvents, type FetchListFnReturn, type FetchListFnReturnItem, type FieldsInput, type FieldsOption, GET_ALL, type GlobalOfflineEntity, type GlobalOfflineStatus, type IndexedDbPersistentStorageOptions, IsOffScreenContext, type ListQueryOfflineEntityRef, type ListQueryOfflineOperationDefinition, type ListQueryPersistentStorageConfig, type ListQueryStore, type ListQueryStoreEvents, type ListQueryStoreInitialData, type ListQueryStoreOptions, type ListQueryUseMultipleItemsQuery, type ListQueryUseMultipleListQueriesQuery, type MutationDebounce, type MutationSkipped, type OfflineAccumulationConfig, type OfflineAccumulationMergeContext, type OfflineConflictResolutionAction, type OfflineEntityMutationKind, type OfflineMutationDescriptor, type OfflineMutationInput, type OfflineMutationQueueingCause, type OfflineMutationQueueingConfig, type OfflineMutationQueueingPolicy, type OfflineMutationResult, type OfflineMutationUploadsInput, type OfflineOperationKind, type OfflineOperationUploadsContext, type OfflineQueueEntry, type OfflineReplayRetryConfig, type OfflineResolutionAction, type OfflineResolutionActionForOperation, type OfflineResolutionConflictParseError, type OfflineResolutionConflictParseErrorCode, type OfflineResolutionRecord, type OfflineResolutionRecordForOperation, type OfflineResolutionRecordForStore, type OfflineRetryExhaustedResolutionAction, type OfflineRuntimeConfig, type OfflineRuntimeConfigUpdate, type OfflineSession, type OfflineSessionConfig, type OfflineSessionUploadsConfig, type OfflineStoredUploadRecord, type OfflineSupersedeConfig, type OfflineSyncState, type OfflineTempEntitiesConfig, type OfflineTempEntitiesReconciliation, type OfflineTempEntityConfig, type OfflineTempEntityPendingEntry, type OfflineUpload, type OfflineUploadAdapter, type OfflineUploadProgress, type OfflineUploadSource, type OfflineUploadState, type OfflineUploadTransportContext, type OffsetPaginationConfig, OnCollectionItemInvalidate, OnDocumentInvalidate, type OnListQueryInvalidate, type OnListQueryItemInvalidate, type OperationConflict, type OperationResult, type OptimisticListUpdate, type ParsedOfflineResolutionConflictResultForOperation, type PartialResourcesConfig, type PayloadDebounce, type PersistentStorageBaseConfig, type PersistentStorageDataSchema, type PersistentStoragePreloadResult, type PersistentStorageSchema, type QueryFetchPayload, type QueryStatus, type StorageAdapter, type StoreError, StoreFetchError, type StoreManager, StoreMutationError, type StoreMutationErrorOptions, type TSDFItemQuery, type TSDFStatus, TSDFUseDocumentReturn, TSFDCollectionItem, TSFDCollectionState, type TSFDListQuery, type TSFDListQueryState, TSFDUseCollectionItemReturn, type TSFDUseListItemReturn, type TSFDUseListQueryReturn, type TSFDUsePendingOfflineItemsReturn, type ValidPayload, type ValidStoreState, clearAllSessionStorage, clearSessionStorage, createAsyncStorageAdapter, createCollectionStore, createDocumentStore, createIndexedDbPersistentStorage, createListQueryStore, createStoreManager, defaultOfflineRuntimeConfig, fetchTypePriority, getGlobalOfflineEntities, getGlobalOfflineResolutions, getGlobalOfflineStatus, indexedDbPersistentStorage, localPersistentStorage, mutationSkipped, opfsOfflineUploadAdapter, opfsPersistentStorage, useGlobalOfflineEntities, useGlobalOfflineResolutions, useGlobalOfflineStatus };
package/dist/main.js CHANGED
@@ -12225,7 +12225,7 @@ function createCollectionStore({ id, storeManager, fetchFn, batchFetchFn, getIte
12225
12225
  });
12226
12226
  if (restoredItemKeys.length > 0) touchItemsAndMaybeEnforceLimits(restoredItemKeys);
12227
12227
  }
12228
- if (!silentErrors && resolvedOnMutationError) resolvedOnMutationError(exception, { silentErrors });
12228
+ if (resolvedOnMutationError) resolvedOnMutationError(exception, { silentErrors });
12229
12229
  return error;
12230
12230
  }
12231
12231
  });
@@ -13047,7 +13047,7 @@ function createDocumentStore({ id, storeManager, fetchFn, lowPriorityThrottleMs:
13047
13047
  function startMutation() {
13048
13048
  return scheduler.startMutation(DOC_REQUEST_ID);
13049
13049
  }
13050
- async function performMutation({ optimisticUpdate, mutation, debounce, dontShowErrorToast, revalidateOnSuccess, offline, upload }) {
13050
+ async function performMutation({ optimisticUpdate, mutation, debounce, silentErrors, revalidateOnSuccess, offline, upload }) {
13051
13051
  if (offline && offlineController && !offlineController.canQueueMutation()) return Result.err(toStoreMutationError(new OfflineSessionUnavailableError(), errorNormalizer));
13052
13052
  const mutationId = getAutoIncrementId();
13053
13053
  storeEvents.emit("mutationStart", { mutationId });
@@ -13078,7 +13078,7 @@ function createDocumentStore({ id, storeManager, fetchFn, lowPriorityThrottleMs:
13078
13078
  store.setKey("data", optimisticRollbackSnapshot ?? null, { action: "rollback-mutation-error" });
13079
13079
  publishDocumentSnapshot();
13080
13080
  });
13081
- if (resolvedOnMutationError) resolvedOnMutationError(exception, { dontShowToast: dontShowErrorToast });
13081
+ if (resolvedOnMutationError) resolvedOnMutationError(exception, { silentErrors });
13082
13082
  return toStoreMutationError(exception, errorNormalizer);
13083
13083
  }
13084
13084
  });
@@ -16316,7 +16316,7 @@ function createMutationApi({ store, fetchItemFn, partialResources, optimisticLis
16316
16316
  itemSnapshots: itemRollbackSnapshots,
16317
16317
  querySnapshots: queryRollbackSnapshots
16318
16318
  });
16319
- if (!silentErrors && onMutationError) onMutationError(exception, { silentErrors });
16319
+ if (onMutationError) onMutationError(exception, { silentErrors });
16320
16320
  if (onError) onError(error);
16321
16321
  return error;
16322
16322
  }
@@ -49,7 +49,7 @@ const productStore = createCollectionStore<Product, string>({
49
49
  | `persistentStorage` | `CollectionPersistentStorageConfig<ItemState, ItemPayload>` | No | Configure cache persistence. See [Persistent Storage](./persistent-storage.md) |
50
50
  | `onInvalidate` | `(props: { itemState, payload, priority }) => void` | No | Called when an item is invalidated |
51
51
  | `onSchedulerEvent` | `(event, data?) => void` | No | Scheduler event listener |
52
- | `onMutationError` | `(error, options: { silentErrors? }) => void` | No | Global mutation error handler |
52
+ | `onMutationError` | `(error, options: { silentErrors?: boolean }) => void` | No | Global mutation error handler |
53
53
 
54
54
  ## Item State Shape
55
55
 
@@ -42,7 +42,7 @@ const userStore = createDocumentStore<User>({
42
42
  | `usesRealTimeUpdates` | `boolean` | No | Enables [Real-Time Updates](./real-time-updates.md) mode |
43
43
  | `persistentStorage` | `DocumentPersistentStorageConfig<State>` | No | Configure cache persistence. See [Persistent Storage](./persistent-storage.md) |
44
44
  | `onSchedulerEvent` | `(event) => void` | No | Scheduler event listener |
45
- | `onMutationError` | `(error, options: { dontShowToast?: boolean }) => void` | No | Global mutation error handler |
45
+ | `onMutationError` | `(error, options: { silentErrors?: boolean }) => void` | No | Global mutation error handler |
46
46
 
47
47
  ## State Shape
48
48
 
@@ -80,7 +80,7 @@ The type parameters are:
80
80
  | `onInvalidateItem` | `(props: { itemState, payload, priority }) => void` | Called when an item is invalidated |
81
81
  | `persistentStorage` | `ListQueryPersistentStorageConfig<ItemState, QueryPayload, ItemPayload>` | Configure cache persistence. See [Persistent Storage](./persistent-storage.md) |
82
82
  | `onSchedulerEvent` | `(event, data?) => void` | Scheduler event listener |
83
- | `onMutationError` | `(error, options) => void` | Global mutation error handler |
83
+ | `onMutationError` | `(error, options: { silentErrors?: boolean }) => void` | Global mutation error handler |
84
84
 
85
85
  ### FetchListFnReturn
86
86
 
package/docs/mutations.md CHANGED
@@ -25,6 +25,9 @@ const result = await store.performMutation({
25
25
 
26
26
  // After success, invalidate data to refetch from the server
27
27
  revalidateOnSuccess: true,
28
+
29
+ // Ask the global/store onMutationError handler to stay quiet
30
+ silentErrors: true,
28
31
  });
29
32
 
30
33
  if (result.ok) {
@@ -81,7 +84,7 @@ The payload can be:
81
84
  3. **Debounce** (optional): Waits for `ms` milliseconds. During debounce, the window close is blocked
82
85
  4. **Execute mutation**: The async mutation function runs
83
86
  5. **On success**: Calls `onSuccess`, optionally invalidates data
84
- 6. **On error**: Reverts to server state by invalidating, normalizes the error, calls `onMutationError`
87
+ 6. **On error**: Rolls back optimistic state, normalizes the error, and calls `onMutationError` with the `silentErrors` flag
85
88
  7. **Unlock**: The scheduler is unlocked, pending fetches resume
86
89
 
87
90
  ## Return Value
@@ -178,7 +181,7 @@ await store.performMutation(payload, {
178
181
  items: false,
179
182
  },
180
183
 
181
- // Suppress the global onMutationError handler
184
+ // Ask the global/store onMutationError handler to stay quiet
182
185
  silentErrors: true,
183
186
 
184
187
  // Callbacks
@@ -32,6 +32,18 @@ It contains the normalized `StoreError` fields plus:
32
32
  - `kind: 'error'`
33
33
  - `cause` — the original thrown value, preserved via `Error.cause`
34
34
 
35
+ ## StoreMutationErrorOptions
36
+
37
+ Options passed to store-level and manager-level `onMutationError` handlers:
38
+
39
+ ```ts
40
+ type StoreMutationErrorOptions = { silentErrors?: boolean };
41
+ ```
42
+
43
+ When `silentErrors` is true, the handler is still called. Use the flag to keep
44
+ centralized logging or recovery behavior while suppressing user-facing
45
+ notifications such as error toasts.
46
+
35
47
  ## MutationSkipped
36
48
 
37
49
  A sentinel returned by `performMutation` when the mutation is intentionally not
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tsdf",
3
- "version": "17.0.0-alpha.4",
3
+ "version": "17.0.0-alpha.5",
4
4
  "description": "A data fetching solution based on t-state",
5
5
  "license": "MIT",
6
6
  "author": "Lucas Santos",