tsdf 17.0.0-alpha.8 → 17.0.0-alpha.9
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 +2 -1
- package/dist/{asyncStorageAdapter-kvAIhrBD.d.ts → asyncStorageAdapter-BMYAF6rt.d.ts} +1 -1
- package/dist/asyncStorageAdapter-BZSj1ZO5.js +1868 -0
- package/dist/asyncStorageAdapters-DbyKyARM.js +3 -0
- package/dist/indexed-db-storage.d.ts +4 -2
- package/dist/indexed-db-storage.js +2 -1
- package/dist/indexedDbPersistentStorage-DlUjN1qY.js +902 -0
- package/dist/main.d.ts +410 -244
- package/dist/main.js +16153 -1
- package/dist/opfs-storage.d.ts +1 -1
- package/dist/opfs-storage.js +2 -1
- package/dist/opfsPersistentStorage-BO_uDxe4.js +838 -0
- package/dist/{opfsPersistentStorage-D_fecOJg.d.ts → opfsPersistentStorage-CBnUebnf.d.ts} +1 -1
- package/dist/{types-DkNgE_f9.d.ts → types-2zQlbxtw.d.ts} +132 -63
- package/docs/README.md +14 -14
- package/docs/batch-fetching.md +1 -1
- package/docs/browser-tabs-sync.md +2 -0
- package/docs/collection-store.md +24 -22
- package/docs/document-store.md +4 -2
- package/docs/fetch-scheduling.md +7 -7
- package/docs/list-query-store.md +35 -33
- package/docs/mutations.md +2 -0
- package/docs/persistent-storage.md +2 -0
- package/docs/real-time-updates.md +5 -5
- package/docs/store-manager.md +31 -12
- package/package.json +6 -3
- package/dist/asyncStorageAdapter-CgG3vm0t.js +0 -1
- package/dist/asyncStorageAdapters-eagaD77Y.js +0 -1
- package/dist/indexedDbPersistentStorage-JYXvMjTG.js +0 -1
- package/dist/opfsPersistentStorage-DS-SWDSq.js +0 -1
|
@@ -1,8 +1,30 @@
|
|
|
1
1
|
import { __LEGIT_ANY__ } from "@ls-stack/utils/saferTyping";
|
|
2
|
-
import { Result } from "t-result";
|
|
2
|
+
import { Result, ResultValidErrors } from "t-result";
|
|
3
3
|
import { RcType } from "runcheck";
|
|
4
4
|
import { StandardSchemaV1 } from "@standard-schema/spec";
|
|
5
5
|
|
|
6
|
+
//#region src/debug.d.ts
|
|
7
|
+
/** Debug log severity used to choose the default console method. */
|
|
8
|
+
type TSDFDebugLogLevel = 'log' | 'warn' | 'error';
|
|
9
|
+
/** Internal subsystem that emitted a debug log entry. */
|
|
10
|
+
type TSDFDebugLogArea = 'browser-tabs' | 'persistent-storage';
|
|
11
|
+
/** Operations emitted by the persistent storage subsystem. */
|
|
12
|
+
type TSDFPersistentStorageDebugOperation = 'clear' | 'commit' | 'list-keys' | 'list-metadata' | 'list-metadata-by-filter' | 'load' | 'load-many' | 'read-entry' | 'read-protected-keys' | 'remove' | 'save' | 'schedule-save' | 'sync-load' | 'sync-protected-keys' | 'write';
|
|
13
|
+
/** Operations emitted by the browser-tab sync subsystem. */
|
|
14
|
+
type TSDFBrowserTabsDebugOperation = 'leader-change' | 'publish' | 'publish-skipped' | 'receive' | 'receive-skipped' | 'session-change' | 'transport-close' | 'transport-open' | 'transport-unavailable';
|
|
15
|
+
/** Structured debug log entry emitted by TSDF internals. */
|
|
16
|
+
type TSDFDebugLogEntry = {
|
|
17
|
+
/** Subsystem that emitted the entry. */area: TSDFDebugLogArea; /** Severity of the entry. */
|
|
18
|
+
level: TSDFDebugLogLevel; /** Human-readable summary of the operation. */
|
|
19
|
+
message: string; /** Stable operation id, such as `publish`, `load`, or `write`. */
|
|
20
|
+
operation: TSDFPersistentStorageDebugOperation | TSDFBrowserTabsDebugOperation; /** Structured operation metadata for filtering and diagnostics. */
|
|
21
|
+
details?: Readonly<Record<string, unknown>>;
|
|
22
|
+
};
|
|
23
|
+
/** Custom debug logger invoked for each emitted TSDF debug entry. */
|
|
24
|
+
type TSDFDebugLogger = (entry: TSDFDebugLogEntry) => void;
|
|
25
|
+
/** Enables manager-wide debug logging for browser-tab sync and persistence. */
|
|
26
|
+
type TSDFDebugOptions = boolean | TSDFDebugLogger;
|
|
27
|
+
//#endregion
|
|
6
28
|
//#region src/requestScheduler.d.ts
|
|
7
29
|
type RequestSchedulerEvents = 'scheduled-fetch-started' | 'rt-fetch-scheduled' | 'rt-fetch-cancelled' | 'scheduled-rt-fetch-started' | 'medium-priority-scheduled' | 'medium-priority-fetch-started' | 'medium-priority-cancelled' | 'batch-size-triggered';
|
|
8
30
|
type RequestSchedulerEventData = {
|
|
@@ -15,9 +37,20 @@ type ScheduleFetchOptions = {
|
|
|
15
37
|
};
|
|
16
38
|
//#endregion
|
|
17
39
|
//#region src/utils/storeShared.d.ts
|
|
40
|
+
/** Shared fetch lifecycle status used by TSDF stores and hooks. */
|
|
18
41
|
type TSDFStatus = 'loading' | 'error' | 'refetching' | 'success';
|
|
42
|
+
/** Payload shapes supported by store keying and fetch APIs. */
|
|
19
43
|
type ValidPayload = number | string | Record<string, unknown>;
|
|
44
|
+
/** State shapes supported by TSDF caches. */
|
|
20
45
|
type ValidStoreState = Record<string, unknown> | unknown[];
|
|
46
|
+
type UnwrapTSDFResult<T> = T extends {
|
|
47
|
+
ok: true;
|
|
48
|
+
value: infer Value;
|
|
49
|
+
} ? Value : T extends {
|
|
50
|
+
ok: false;
|
|
51
|
+
error: ResultValidErrors;
|
|
52
|
+
} ? never : T;
|
|
53
|
+
type MaybeTSDFResult<T> = T | Result<T, ResultValidErrors>;
|
|
21
54
|
/**
|
|
22
55
|
* Debounce settings for payload-driven automatic fetches in store hooks.
|
|
23
56
|
*
|
|
@@ -38,16 +71,18 @@ type PayloadDebounce = {
|
|
|
38
71
|
*/
|
|
39
72
|
leading?: boolean;
|
|
40
73
|
};
|
|
74
|
+
/** Normalized error shape used by fetch and mutation APIs. */
|
|
41
75
|
type StoreError = {
|
|
42
|
-
code: number;
|
|
43
|
-
id: string;
|
|
44
|
-
message: string;
|
|
45
|
-
path?: string;
|
|
76
|
+
/** Numeric application or transport error code. */code: number; /** Stable machine-readable error id. */
|
|
77
|
+
id: string; /** Human-readable error message. */
|
|
78
|
+
message: string; /** Optional request path associated with the failure. */
|
|
79
|
+
path?: string; /** Optional HTTP method associated with the failure. */
|
|
46
80
|
method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
|
|
47
81
|
};
|
|
48
82
|
declare const fetchTypePriority: Record<FetchType, number>;
|
|
83
|
+
/** Result error returned when a debounced or canceled mutation never runs. */
|
|
49
84
|
type MutationSkipped = {
|
|
50
|
-
kind: 'skipped';
|
|
85
|
+
/** Stable discriminator for skipped mutations. */kind: 'skipped';
|
|
51
86
|
};
|
|
52
87
|
declare const mutationSkipped: MutationSkipped;
|
|
53
88
|
/** Options passed to mutation error handlers. */
|
|
@@ -61,75 +96,97 @@ type StoreMutationErrorOptions = {
|
|
|
61
96
|
*/
|
|
62
97
|
silentErrors?: boolean;
|
|
63
98
|
};
|
|
99
|
+
/** Error wrapper returned by mutation APIs after normalization. */
|
|
64
100
|
declare class StoreMutationError extends Error {
|
|
101
|
+
/** Stable discriminator matching result-style mutation errors. */
|
|
65
102
|
readonly kind = "error";
|
|
103
|
+
/** Numeric application or transport error code. */
|
|
66
104
|
code: number;
|
|
105
|
+
/** Stable machine-readable error id. */
|
|
67
106
|
id: string;
|
|
107
|
+
/** Optional request path associated with the failure. */
|
|
68
108
|
path?: string;
|
|
109
|
+
/** Optional HTTP method associated with the failure. */
|
|
69
110
|
method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
|
|
70
111
|
constructor(error: StoreError, options?: ErrorOptions);
|
|
71
112
|
}
|
|
113
|
+
/** Error wrapper returned by fetch APIs after normalization. */
|
|
72
114
|
declare class StoreFetchError extends Error {
|
|
115
|
+
/** Numeric application or transport error code. */
|
|
73
116
|
code: number;
|
|
117
|
+
/** Stable machine-readable error id. */
|
|
74
118
|
id: string;
|
|
119
|
+
/** Fetch failure category. */
|
|
75
120
|
type: 'fetch' | 'aborted' | 'timeout';
|
|
121
|
+
/** Optional request path associated with the failure. */
|
|
76
122
|
path?: string;
|
|
123
|
+
/** Optional HTTP method associated with the failure. */
|
|
77
124
|
method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
|
|
78
125
|
constructor(error: StoreError, type: 'fetch' | 'aborted' | 'timeout');
|
|
79
126
|
}
|
|
80
127
|
//#endregion
|
|
81
128
|
//#region src/persistentStorage/offlineUploadTypes.d.ts
|
|
129
|
+
/** Lifecycle state for a session-scoped offline upload. */
|
|
82
130
|
type OfflineUploadState = 'pending' | 'uploading' | 'uploaded' | 'failed';
|
|
131
|
+
/** Source that created a staged offline upload. */
|
|
83
132
|
type OfflineUploadSource = 'manual' | 'mutation';
|
|
133
|
+
/** Progress snapshot reported while uploading a staged file. */
|
|
84
134
|
type OfflineUploadProgress = {
|
|
85
|
-
progress: number;
|
|
86
|
-
loadedBytes?: number;
|
|
135
|
+
/** Normalized progress from `0` to `1`. */progress: number; /** Loaded byte count, when available from the transport. */
|
|
136
|
+
loadedBytes?: number; /** Total byte count, when available from the transport. */
|
|
87
137
|
totalBytes?: number;
|
|
88
138
|
};
|
|
139
|
+
/** Public metadata for a file staged for offline mutation replay. */
|
|
89
140
|
type OfflineUpload<TResolvedRef extends ValidPayload = ValidPayload> = {
|
|
90
|
-
id: string;
|
|
91
|
-
sessionKey: string;
|
|
92
|
-
source: OfflineUploadSource;
|
|
93
|
-
state: OfflineUploadState;
|
|
94
|
-
fileName: string;
|
|
95
|
-
mimeType: string;
|
|
96
|
-
sizeBytes: number;
|
|
97
|
-
createdAt: number;
|
|
98
|
-
updatedAt: number;
|
|
99
|
-
resolvedRef?: TResolvedRef;
|
|
100
|
-
progress?: OfflineUploadProgress;
|
|
141
|
+
/** Stable upload id used by offline operation inputs. */id: string; /** Session key that owns this upload. */
|
|
142
|
+
sessionKey: string; /** Source that created this upload. */
|
|
143
|
+
source: OfflineUploadSource; /** Current upload lifecycle state. */
|
|
144
|
+
state: OfflineUploadState; /** Original file name. */
|
|
145
|
+
fileName: string; /** MIME type recorded for the staged file. */
|
|
146
|
+
mimeType: string; /** File size in bytes. */
|
|
147
|
+
sizeBytes: number; /** Epoch timestamp when the upload was staged. */
|
|
148
|
+
createdAt: number; /** Epoch timestamp for the latest upload metadata change. */
|
|
149
|
+
updatedAt: number; /** Final server-side reference after upload completes. */
|
|
150
|
+
resolvedRef?: TResolvedRef; /** Latest upload progress snapshot. */
|
|
151
|
+
progress?: OfflineUploadProgress; /** Last upload failure message, when any. */
|
|
101
152
|
lastError?: {
|
|
102
153
|
message: string;
|
|
103
154
|
};
|
|
104
155
|
};
|
|
156
|
+
/** Persisted offline upload record including the staged file object. */
|
|
105
157
|
type OfflineStoredUploadRecord<TResolvedRef extends ValidPayload = ValidPayload> = OfflineUpload<TResolvedRef> & {
|
|
106
|
-
file: File;
|
|
107
|
-
lastOnlineSessionStartedAt?: number;
|
|
158
|
+
/** Staged file blob restored from the upload adapter. */file: File; /** Last online session start time seen before the upload was stored. */
|
|
159
|
+
lastOnlineSessionStartedAt?: number; /** File last-modified timestamp. */
|
|
108
160
|
lastModified: number;
|
|
109
161
|
};
|
|
162
|
+
/** Storage backend contract for session-scoped offline upload files. */
|
|
110
163
|
type OfflineUploadAdapter = {
|
|
111
|
-
save<TResolvedRef extends ValidPayload>(sessionKey: string, id: string, record: OfflineStoredUploadRecord<TResolvedRef>): Promise<void>;
|
|
112
|
-
load<TResolvedRef extends ValidPayload>(sessionKey: string, id: string): Promise<OfflineStoredUploadRecord<TResolvedRef> | null>;
|
|
113
|
-
list<TResolvedRef extends ValidPayload>(sessionKey: string): Promise<OfflineStoredUploadRecord<TResolvedRef>[]>;
|
|
114
|
-
remove(sessionKey: string, id: string): Promise<void>;
|
|
115
|
-
clearSession(sessionKey: string): Promise<void>;
|
|
164
|
+
/** Saves or replaces one staged upload record. */save<TResolvedRef extends ValidPayload>(sessionKey: string, id: string, record: OfflineStoredUploadRecord<TResolvedRef>): Promise<void>; /** Loads one staged upload record by id. */
|
|
165
|
+
load<TResolvedRef extends ValidPayload>(sessionKey: string, id: string): Promise<OfflineStoredUploadRecord<TResolvedRef> | null>; /** Lists all staged upload records for a session. */
|
|
166
|
+
list<TResolvedRef extends ValidPayload>(sessionKey: string): Promise<OfflineStoredUploadRecord<TResolvedRef>[]>; /** Removes one staged upload record. */
|
|
167
|
+
remove(sessionKey: string, id: string): Promise<void>; /** Removes all staged upload records for a session. */
|
|
168
|
+
clearSession(sessionKey: string): Promise<void>; /** Test-only reset hook used by TSDF internals. */
|
|
116
169
|
resetForTests?(): void;
|
|
117
170
|
};
|
|
171
|
+
/** Context passed to the configured offline upload transport. */
|
|
118
172
|
type OfflineUploadTransportContext = {
|
|
119
|
-
id: string;
|
|
120
|
-
sessionKey: string;
|
|
121
|
-
file: File;
|
|
173
|
+
/** Stable upload id being transported. */id: string; /** Session key that owns this upload. */
|
|
174
|
+
sessionKey: string; /** File to upload. */
|
|
175
|
+
file: File; /** Reports upload progress back to TSDF. */
|
|
122
176
|
onProgress: (progress: OfflineUploadProgress) => void;
|
|
123
177
|
};
|
|
178
|
+
/** Upload handling config for an offline session. */
|
|
124
179
|
type OfflineSessionUploadsConfig<TResolvedRef extends ValidPayload = ValidPayload> = {
|
|
125
|
-
adapter: OfflineUploadAdapter;
|
|
126
|
-
upload: (ctx: OfflineUploadTransportContext) => Promise<TResolvedRef>;
|
|
180
|
+
/** Adapter used to persist staged files until replay can upload them. */adapter: OfflineUploadAdapter; /** Upload transport that returns the final server-side file reference. */
|
|
181
|
+
upload: (ctx: OfflineUploadTransportContext) => Promise<TResolvedRef>; /** Maximum number of concurrent upload transports. */
|
|
127
182
|
concurrency?: number;
|
|
128
183
|
};
|
|
184
|
+
/** Files attached to an offline-capable mutation call, keyed by upload id. */
|
|
129
185
|
type OfflineMutationUploadsInput = Record<string, Blob | File>;
|
|
130
186
|
type OfflineAttachedUploadIds = Record<string, string>;
|
|
187
|
+
/** Resolved upload files and references available while an offline operation replays. */
|
|
131
188
|
type OfflineOperationUploadsContext<TResolvedRef extends ValidPayload = ValidPayload> = {
|
|
132
|
-
filesById: Record<string, File>;
|
|
189
|
+
/** Locally staged files by upload id. */filesById: Record<string, File>; /** Final uploaded refs by upload id. */
|
|
133
190
|
resolvedRefsById: Record<string, TResolvedRef>;
|
|
134
191
|
};
|
|
135
192
|
//#endregion
|
|
@@ -504,7 +561,7 @@ type OfflineQueueEntry<TInput = unknown, TConflict = unknown> = {
|
|
|
504
561
|
};
|
|
505
562
|
/** Built-in resolution actions for retry exhaustion records. */
|
|
506
563
|
type OfflineRetryExhaustedResolutionAction = {
|
|
507
|
-
action: 'retry';
|
|
564
|
+
/** Requeues the failed mutation for another replay attempt. */action: 'retry';
|
|
508
565
|
/**
|
|
509
566
|
* Controls whether retrying a resolution should also requeue retryable
|
|
510
567
|
* descendants from the same temp-lifecycle dependency chain.
|
|
@@ -512,7 +569,7 @@ type OfflineRetryExhaustedResolutionAction = {
|
|
|
512
569
|
*/
|
|
513
570
|
scope?: 'self' | 'self-and-descendants';
|
|
514
571
|
} | {
|
|
515
|
-
action: 'discard';
|
|
572
|
+
/** Discards the exhausted mutation and clears its resolution record. */action: 'discard';
|
|
516
573
|
};
|
|
517
574
|
/**
|
|
518
575
|
* Built-in resolution actions for persisted conflict records.
|
|
@@ -525,12 +582,12 @@ type OfflineRetryExhaustedResolutionAction = {
|
|
|
525
582
|
* @typeParam TResult - Result shape returned by the external conflict resolution call.
|
|
526
583
|
*/
|
|
527
584
|
type OfflineConflictResolutionAction<TInput = unknown, TResult = unknown> = {
|
|
528
|
-
action: 'discard';
|
|
585
|
+
/** Discards the conflict and clears its resolution record. */action: 'discard';
|
|
529
586
|
} | {
|
|
530
|
-
action: 'requeue';
|
|
587
|
+
/** Requeues the operation with replacement input. */action: 'requeue'; /** Replacement operation input. */
|
|
531
588
|
input: TInput;
|
|
532
589
|
} | {
|
|
533
|
-
action: 'commit';
|
|
590
|
+
/** Commits an externally resolved conflict and clears bookkeeping. */action: 'commit'; /** Result returned by the external conflict resolution call, when needed for reconciliation. */
|
|
534
591
|
result?: TResult;
|
|
535
592
|
};
|
|
536
593
|
/**
|
|
@@ -1155,9 +1212,9 @@ type ParsedOfflineResolutionConflictResultForStore<TOperations> = ParsedOfflineR
|
|
|
1155
1212
|
* @typeParam TName - Operation name whose stored resolution shape should be extracted.
|
|
1156
1213
|
*/
|
|
1157
1214
|
type OfflineResolutionRecordForOperation<TOperations, TName extends keyof TOperations & string> = (OfflineConflictResolutionRecord<OperationConflict<TOperations, TName>, OperationInput<TOperations, TName>> & {
|
|
1158
|
-
operation: TName;
|
|
1215
|
+
/** Operation name associated with this resolution record. */operation: TName;
|
|
1159
1216
|
}) | (OfflineRetryExhaustedResolutionRecord<OperationInput<TOperations, TName>> & {
|
|
1160
|
-
operation: TName;
|
|
1217
|
+
/** Operation name associated with this resolution record. */operation: TName;
|
|
1161
1218
|
});
|
|
1162
1219
|
/**
|
|
1163
1220
|
* Union of operation-aware offline resolution records for an operation registry.
|
|
@@ -1166,6 +1223,7 @@ type OfflineResolutionRecordForOperation<TOperations, TName extends keyof TOpera
|
|
|
1166
1223
|
* @typeParam TName - Optional subset of operation names to include.
|
|
1167
1224
|
*/
|
|
1168
1225
|
type OfflineResolutionRecordForStore<TOperations, TName extends keyof TOperations & string = keyof TOperations & string> = { [K in TName]: OfflineResolutionRecordForOperation<TOperations, K> }[TName];
|
|
1226
|
+
/** Failure code returned when parsing a stored offline conflict payload. */
|
|
1169
1227
|
type OfflineResolutionConflictParseErrorCode = 'not-conflict' | 'offline-not-configured' | 'operation-not-found' | 'conflict-handling-missing' | 'invalid-conflict-payload';
|
|
1170
1228
|
/** Error returned when decoding a stored offline conflict payload fails. */
|
|
1171
1229
|
declare class OfflineResolutionConflictParseError extends Error {
|
|
@@ -1184,16 +1242,20 @@ declare class OfflineResolutionConflictParseError extends Error {
|
|
|
1184
1242
|
}
|
|
1185
1243
|
//#endregion
|
|
1186
1244
|
//#region src/persistentStorage/types.d.ts
|
|
1245
|
+
/** Logical namespaces used by managed async persistent storage. */
|
|
1187
1246
|
type AsyncStorageNamespaceKind = 'document' | 'collection.item' | 'listQuery.item' | 'listQuery.query' | 'offline.queue' | 'offline.conflict' | 'offline.entity' | '__internal.protected';
|
|
1247
|
+
/** Identifies one logical persistent-storage namespace. */
|
|
1188
1248
|
type AsyncStorageNamespaceScope = {
|
|
1189
|
-
sessionKey: string;
|
|
1190
|
-
storeName: string;
|
|
1249
|
+
/** Session key owning this namespace. */sessionKey: string; /** Store id owning this namespace. */
|
|
1250
|
+
storeName: string; /** Type of records stored in this namespace. */
|
|
1191
1251
|
kind: AsyncStorageNamespaceKind;
|
|
1192
1252
|
};
|
|
1193
1253
|
type AsyncStorageTouchMode = 'never' | 'coarse' | 'force';
|
|
1254
|
+
/** Read behavior for managed async namespace operations. */
|
|
1194
1255
|
type AsyncStorageReadOptions = {
|
|
1195
|
-
touch?: AsyncStorageTouchMode;
|
|
1256
|
+
/** Whether reading should update LRU access metadata. */touch?: AsyncStorageTouchMode;
|
|
1196
1257
|
};
|
|
1258
|
+
/** Sort order for listing async storage metadata. */
|
|
1197
1259
|
type AsyncStorageMetadataOrder = 'key' | 'lru-asc' | 'lru-desc';
|
|
1198
1260
|
type AsyncStorageEntryMetadataBase = {
|
|
1199
1261
|
key: string;
|
|
@@ -1206,40 +1268,46 @@ type AsyncStorageEntryMetadataBase = {
|
|
|
1206
1268
|
type AsyncStorageEntryMetadata<TCustomMetadata extends Record<string, unknown> = Record<string, unknown>> = AsyncStorageEntryMetadataBase & {
|
|
1207
1269
|
customMetadata: TCustomMetadata;
|
|
1208
1270
|
};
|
|
1271
|
+
/** Value and metadata returned from a managed async namespace read. */
|
|
1209
1272
|
type AsyncStorageNamespaceGetResult<TValue, TCustomMetadata extends Record<string, unknown> = Record<string, unknown>> = {
|
|
1210
|
-
value: TValue;
|
|
1273
|
+
/** Stored value decoded from the namespace. */value: TValue; /** Managed metadata associated with the stored value. */
|
|
1211
1274
|
metadata: AsyncStorageEntryMetadata<TCustomMetadata>;
|
|
1212
1275
|
};
|
|
1276
|
+
/** Upsert entry committed to a managed async namespace. */
|
|
1213
1277
|
type AsyncStorageNamespaceCommitUpsert<TValue, TCustomMetadata extends Record<string, unknown> = Record<string, unknown>> = {
|
|
1214
|
-
key: string;
|
|
1215
|
-
value: TValue;
|
|
1216
|
-
serializedValue?: string;
|
|
1217
|
-
sizeBytes?: number;
|
|
1218
|
-
version: number;
|
|
1278
|
+
/** Raw namespace key to write. */key: string; /** Decoded value to store. */
|
|
1279
|
+
value: TValue; /** Pre-serialized JSON string, when the caller already has it. */
|
|
1280
|
+
serializedValue?: string; /** Serialized JSON size used for persistence budgeting. */
|
|
1281
|
+
sizeBytes?: number; /** Cache version associated with this value. */
|
|
1282
|
+
version: number; /** Custom metadata stored alongside the value. */
|
|
1219
1283
|
metadata?: TCustomMetadata;
|
|
1220
1284
|
};
|
|
1285
|
+
/** Touch entry committed to update managed async namespace LRU metadata. */
|
|
1221
1286
|
type AsyncStorageNamespaceCommitTouch = {
|
|
1222
|
-
key: string;
|
|
1287
|
+
/** Raw namespace key to touch. */key: string; /** Explicit access timestamp. Defaults to the adapter's current time. */
|
|
1223
1288
|
lastAccessAt?: number;
|
|
1224
1289
|
};
|
|
1225
1290
|
type AsyncStorageNamespaceStaticPolicy = {
|
|
1226
1291
|
maxBytes?: number;
|
|
1227
1292
|
pinnedKeys?: string[];
|
|
1228
1293
|
};
|
|
1294
|
+
/** Batched write/remove/touch operation for a managed async namespace. */
|
|
1229
1295
|
type AsyncStorageNamespaceCommitArgs<TValue, TCustomMetadata extends Record<string, unknown> = Record<string, unknown>> = {
|
|
1230
|
-
upserts?: AsyncStorageNamespaceCommitUpsert<TValue, TCustomMetadata>[];
|
|
1231
|
-
removes?: string[];
|
|
1232
|
-
staticPolicy?: AsyncStorageNamespaceStaticPolicy | null;
|
|
1296
|
+
/** Entries to create or replace. */upserts?: AsyncStorageNamespaceCommitUpsert<TValue, TCustomMetadata>[]; /** Raw namespace keys to remove. */
|
|
1297
|
+
removes?: string[]; /** Static cleanup policy applied during this commit. */
|
|
1298
|
+
staticPolicy?: AsyncStorageNamespaceStaticPolicy | null; /** Existing entries whose access metadata should be updated. */
|
|
1233
1299
|
touches?: AsyncStorageNamespaceCommitTouch[];
|
|
1234
1300
|
};
|
|
1301
|
+
/** Raw entry passed to low-level async storage driver bulk writes. */
|
|
1235
1302
|
type AsyncStorageDriverSetEntry = {
|
|
1236
|
-
key: string;
|
|
1237
|
-
value: unknown;
|
|
1238
|
-
serializedValue?: string;
|
|
1303
|
+
/** Raw record key to write. */key: string; /** Raw value to store. */
|
|
1304
|
+
value: unknown; /** Pre-serialized JSON string, when available. */
|
|
1305
|
+
serializedValue?: string; /** Serialized value size used for budgeting. */
|
|
1239
1306
|
sizeBytes?: number;
|
|
1240
1307
|
};
|
|
1308
|
+
/** Scope discovered by a low-level async storage driver. */
|
|
1241
1309
|
type AsyncStorageDiscoveredScope = {
|
|
1242
|
-
/** Known raw record keys for this scope. `null` if keys were not enumerated during discovery. */knownRecordKeys: string[] | null;
|
|
1310
|
+
/** Known raw record keys for this scope. `null` if keys were not enumerated during discovery. */knownRecordKeys: string[] | null; /** Discovered namespace scope. */
|
|
1243
1311
|
scope: AsyncStorageNamespaceScope;
|
|
1244
1312
|
};
|
|
1245
1313
|
/** Low-level async backend contract implemented by custom storage drivers. */
|
|
@@ -1255,21 +1323,22 @@ type AsyncStorageDriver = {
|
|
|
1255
1323
|
setMany(scope: AsyncStorageNamespaceScope, entries: AsyncStorageDriverSetEntry[]): Promise<void>; /** Bulk remove for multiple keys in a single call. */
|
|
1256
1324
|
removeMany(scope: AsyncStorageNamespaceScope, keys: string[]): Promise<void>;
|
|
1257
1325
|
};
|
|
1326
|
+
/** Managed namespace handle opened by an async storage adapter. */
|
|
1258
1327
|
type AsyncStorageNamespaceHandle<TValue, TCustomMetadata extends Record<string, unknown> = Record<string, unknown>> = {
|
|
1259
|
-
get(key: string, options?: AsyncStorageReadOptions): Promise<AsyncStorageNamespaceGetResult<TValue, TCustomMetadata> | null>;
|
|
1260
|
-
getMany(keys: string[], options?: AsyncStorageReadOptions): Promise<Array<AsyncStorageNamespaceGetResult<TValue, TCustomMetadata> | null>>;
|
|
1261
|
-
listKeys(): Promise<string[]>;
|
|
1262
|
-
commit(args: AsyncStorageNamespaceCommitArgs<TValue, TCustomMetadata>): Promise<void>;
|
|
1328
|
+
/** Reads one decoded value and metadata by raw namespace key. */get(key: string, options?: AsyncStorageReadOptions): Promise<AsyncStorageNamespaceGetResult<TValue, TCustomMetadata> | null>; /** Reads many decoded values and metadata records by raw namespace key. */
|
|
1329
|
+
getMany(keys: string[], options?: AsyncStorageReadOptions): Promise<Array<AsyncStorageNamespaceGetResult<TValue, TCustomMetadata> | null>>; /** Lists raw record keys in this namespace. */
|
|
1330
|
+
listKeys(): Promise<string[]>; /** Applies batched writes, removes, touches, and cleanup policy changes. */
|
|
1331
|
+
commit(args: AsyncStorageNamespaceCommitArgs<TValue, TCustomMetadata>): Promise<void>; /** Lists metadata for all records in this namespace. */
|
|
1263
1332
|
listMetadata(args?: {
|
|
1264
1333
|
order?: AsyncStorageMetadataOrder;
|
|
1265
|
-
}): Promise<AsyncStorageEntryMetadata<TCustomMetadata>[]>;
|
|
1334
|
+
}): Promise<AsyncStorageEntryMetadata<TCustomMetadata>[]>; /** Lists metadata matching a custom metadata equality filter. */
|
|
1266
1335
|
listMetadataByFilter?(args: {
|
|
1267
1336
|
filter: {
|
|
1268
1337
|
equals: unknown;
|
|
1269
1338
|
key: string;
|
|
1270
1339
|
};
|
|
1271
1340
|
order?: AsyncStorageMetadataOrder;
|
|
1272
|
-
}): Promise<AsyncStorageEntryMetadata<TCustomMetadata>[]>;
|
|
1341
|
+
}): Promise<AsyncStorageEntryMetadata<TCustomMetadata>[]>; /** Removes every record in this namespace. */
|
|
1273
1342
|
clear(): Promise<void>;
|
|
1274
1343
|
};
|
|
1275
1344
|
/** Managed async adapter consumed by TSDF persistence internals. */
|
|
@@ -1403,4 +1472,4 @@ type ListQueryPersistentStorageFields<QueryPayload extends ValidPayload, ItemPay
|
|
|
1403
1472
|
/** Persistent storage config for ListQueryStore. */
|
|
1404
1473
|
type ListQueryPersistentStorageConfig<ItemState extends ValidStoreState, QueryPayload extends ValidPayload = ValidPayload, ItemPayload extends ValidPayload = ValidPayload, StorageState = unknown, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload> = null> = StorePersistentStorageBaseConfig<ItemState, StorageState> & PublicStoreOfflineConfigField<TOfflineOperations> & ListQueryPersistentStorageFields<QueryPayload, ItemPayload>;
|
|
1405
1474
|
//#endregion
|
|
1406
|
-
export { OfflineResolutionRecord as $, DefineListQueryOfflineOperations as A,
|
|
1475
|
+
export { OfflineResolutionRecord as $, DefineListQueryOfflineOperations as A, PayloadDebounce as At, OfflineEntityMutationKind as B, mutationSkipped as Bt, PersistentStorageSchema as C, OfflineUploadAdapter as Ct, CollectionOfflineOperationDefinition as D, OfflineUploadTransportContext as Dt, CollectionOfflineEntityRef as E, OfflineUploadState as Et, ListQueryOfflineEntityRef as F, TSDFStatus as Ft, OfflineMutationQueueingPolicy as G, ScheduleFetchResults as Gt, OfflineMutationInput as H, RequestSchedulerEventData as Ht, ListQueryOfflineOperationDefinition as I, UnwrapTSDFResult as It, OfflineReplayRetryConfig as J, TSDFDebugLogLevel as Jt, OfflineOperationKind as K, TSDFDebugLogArea as Kt, OfflineAccumulationConfig as L, ValidPayload as Lt, DocumentOfflineOperationDefinition as M, StoreFetchError as Mt, GlobalOfflineEntity as N, StoreMutationError as Nt, DefineCollectionOfflineOperations as O, MaybeTSDFResult as Ot, GlobalOfflineStatus as P, StoreMutationErrorOptions as Pt, OfflineResolutionConflictParseErrorCode as Q, OfflineAccumulationMergeContext as R, ValidStoreState as Rt, PersistentStoragePreloadResult as S, OfflineUpload as St, AnyOfflineOperationDefinition as T, OfflineUploadSource as Tt, OfflineMutationQueueingCause as U, RequestSchedulerEvents as Ut, OfflineMutationDescriptor as V, FetchType as Vt, OfflineMutationQueueingConfig as W, ScheduleFetchOptions as Wt, OfflineResolutionActionForOperation as X, TSDFDebugOptions as Xt, OfflineResolutionAction as Y, TSDFDebugLogger as Yt, OfflineResolutionConflictParseError as Z, ListQueryOfflineOperationsConfig as _, defaultOfflineRuntimeConfig as _t, AsyncStorageMetadataOrder as a, OfflineSession as at, PersistentStorageDataSchema as b, OfflineSessionUploadsConfig as bt, AsyncStorageNamespaceCommitUpsert as c, OfflineSyncState as ct, AsyncStorageNamespaceKind as d, OfflineTempEntityConfig as dt, OfflineResolutionRecordForOperation as et, AsyncStorageNamespaceScope as f, OfflineTempEntityPendingEntry as ft, DocumentPersistentStorageConfig as g, ParsedOfflineResolutionConflictResultForStore as gt, ConvertedPersistentStorageDataSchema as h, ParsedOfflineResolutionConflictResultForOperation as ht, AsyncStorageDriverSetEntry as i, OfflineRuntimeConfigUpdate as it, DefineOfflineOperation as j, StoreError as jt, DefineDocumentOfflineOperations as k, MutationSkipped as kt, AsyncStorageNamespaceGetResult as l, OfflineTempEntitiesConfig as lt, CollectionPersistentStorageConfig as m, OperationResult as mt, AsyncStorageDiscoveredScope as n, OfflineRetryExhaustedResolutionAction as nt, AsyncStorageNamespaceCommitArgs as o, OfflineSessionConfig as ot, AsyncStorageReadOptions as p, OperationConflict as pt, OfflineQueueEntry as q, TSDFDebugLogEntry as qt, AsyncStorageDriver as r, OfflineRuntimeConfig as rt, AsyncStorageNamespaceCommitTouch as s, OfflineSupersedeConfig as st, AsyncStorageAdapter as t, OfflineResolutionRecordForStore as tt, AsyncStorageNamespaceHandle as u, OfflineTempEntitiesReconciliation as ut, ListQueryPersistentStorageConfig as v, OfflineMutationUploadsInput as vt, StorageAdapter as w, OfflineUploadProgress as wt, PersistentStorageErrorHandler as x, OfflineStoredUploadRecord as xt, PersistentStorageBaseConfig as y, OfflineOperationUploadsContext as yt, OfflineConflictResolutionAction as z, fetchTypePriority as zt };
|
package/docs/README.md
CHANGED
|
@@ -82,17 +82,17 @@ function UserProfile() {
|
|
|
82
82
|
|
|
83
83
|
All three store types share these creation options:
|
|
84
84
|
|
|
85
|
-
| Option | Type | Required | Description
|
|
86
|
-
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | -------- |
|
|
87
|
-
| `storeManager` | `StoreManager` | Yes | Shared global config with session scoping, store defaults, and global store controls
|
|
88
|
-
| `lowPriorityThrottleMs` | `number` | No | Overrides the manager default minimum interval between low-priority fetches
|
|
89
|
-
| `baseCoalescingWindowMs` | `number` | No | Overrides the manager default window to group multiple fetch requests into a batch
|
|
90
|
-
| `mediumPriorityDelayMs` | `number` | No | Delay before medium-priority fetches execute
|
|
91
|
-
| `dynamicRealtimeThrottleMs` | `(params) => number` | No |
|
|
92
|
-
| `revalidateOnWindowFocus` | `boolean \| (() => boolean)` | No | Overrides the manager default for refetching data when window regains focus. Use `false` to disable
|
|
93
|
-
| `transportReconnectCooldownMs` | `number` | No | Cooldown for repeated transport reconnect revalidation
|
|
94
|
-
| `persistentStorage` | `DocumentPersistentStorageConfig<...> \| CollectionPersistentStorageConfig<...> \| ListQueryPersistentStorageConfig<...>` | No | Configure cache persistence and optional session-based offline behavior
|
|
95
|
-
| `usesRealTimeUpdates` | `boolean` | No | Enables [real-time update mode](./real-time-updates.md)
|
|
96
|
-
| `onSchedulerEvent` | `(event) => void` | No | Callback for [scheduler events](./fetch-scheduling.md)
|
|
97
|
-
| `onMutationError` | `(error, options) => void \| null` | No | Store-specific handler for [mutation](./mutations.md) errors. Overrides the manager fallback; use `null` to disable it
|
|
98
|
-
| `id` | `string` | Yes | Stable logical store id used for debug labels, persistence namespaces, and [Browser Tabs Sync](./browser-tabs-sync.md)
|
|
85
|
+
| Option | Type | Required | Description |
|
|
86
|
+
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
87
|
+
| `storeManager` | `StoreManager` | Yes | Shared global config with session scoping, store defaults, and global store controls |
|
|
88
|
+
| `lowPriorityThrottleMs` | `number` | No | Overrides the manager default minimum interval between low-priority fetches |
|
|
89
|
+
| `baseCoalescingWindowMs` | `number` | No | Overrides the manager default window to group multiple fetch requests into a batch |
|
|
90
|
+
| `mediumPriorityDelayMs` | `number` | No | Delay before medium-priority fetches execute |
|
|
91
|
+
| `dynamicRealtimeThrottleMs` | `(params) => number` | No | Overrides the manager default dynamic throttle for [real-time updates](./real-time-updates.md). Built-in manager default: `100ms` focused, `1000ms` background |
|
|
92
|
+
| `revalidateOnWindowFocus` | `boolean \| (() => boolean)` | No | Overrides the manager default for refetching data when window regains focus. Use `false` to disable |
|
|
93
|
+
| `transportReconnectCooldownMs` | `number` | No | Cooldown for repeated transport reconnect revalidation |
|
|
94
|
+
| `persistentStorage` | `DocumentPersistentStorageConfig<...> \| CollectionPersistentStorageConfig<...> \| ListQueryPersistentStorageConfig<...>` | No | Configure cache persistence and optional session-based offline behavior |
|
|
95
|
+
| `usesRealTimeUpdates` | `boolean` | No | Enables [real-time update mode](./real-time-updates.md) |
|
|
96
|
+
| `onSchedulerEvent` | `(event) => void` | No | Callback for [scheduler events](./fetch-scheduling.md) |
|
|
97
|
+
| `onMutationError` | `(error, options) => void \| null` | No | Store-specific handler for [mutation](./mutations.md) errors. Overrides the manager fallback; use `null` to disable it |
|
|
98
|
+
| `id` | `string` | Yes | Stable logical store id used for debug labels, persistence namespaces, and [Browser Tabs Sync](./browser-tabs-sync.md) |
|
package/docs/batch-fetching.md
CHANGED
|
@@ -104,7 +104,7 @@ getItemsBatchKey: (payload) => {
|
|
|
104
104
|
|
|
105
105
|
## Max Batch Size
|
|
106
106
|
|
|
107
|
-
When `maxBatchSize` is set, the scheduler triggers an immediate fetch (skipping the remaining coalescing window) once the batch reaches that size
|
|
107
|
+
When `maxBatchSize` is set, the scheduler triggers an immediate fetch (skipping the remaining coalescing window) once the batch reaches that size. List Query Store uses `maxItemBatchSize` for the same behavior, and it defaults to `50`:
|
|
108
108
|
|
|
109
109
|
```ts
|
|
110
110
|
{
|
|
@@ -35,6 +35,8 @@ Tabs use a versioned message model so later snapshots do not overwrite fresher r
|
|
|
35
35
|
- When `sessionKey` changes (for example, login/logout), sync state is refreshed for the new session.
|
|
36
36
|
- If transport is unavailable, sync becomes inactive silently.
|
|
37
37
|
|
|
38
|
+
Enable `createStoreManager({ debug: true, ... })` to inspect transport open/close, publish, receive, skipped-message events, and leader changes. Leader-change entries include the elected `leaderTabId`, whether the local tab is the leader, the local tab rank, and the ranked live-tab snapshot. Pass a logger function as `debug` to route those entries to your own observability tool.
|
|
39
|
+
|
|
38
40
|
## Required options
|
|
39
41
|
|
|
40
42
|
Add the following options to any store that should sync:
|
package/docs/collection-store.md
CHANGED
|
@@ -28,28 +28,30 @@ const productStore = createCollectionStore<Product, string>({
|
|
|
28
28
|
|
|
29
29
|
## Options
|
|
30
30
|
|
|
31
|
-
| Option | Type
|
|
32
|
-
| ------------------------------ |
|
|
33
|
-
| `id` | `string`
|
|
34
|
-
| `storeManager` | `StoreManager`
|
|
35
|
-
| `fetchFn` | `(params
|
|
36
|
-
| `batchFetchFn` | `(payloads
|
|
37
|
-
| `getItemsBatchKey` | `(payload: ItemPayload) => string \| false`
|
|
38
|
-
| `maxBatchSize` | `number`
|
|
39
|
-
| `maxItems` | `number`
|
|
40
|
-
| `onStateCleanup` | `(cleanup) => void`
|
|
41
|
-
| `getCollectionItemKey` | `(params: ItemPayload) => ValidPayload \| unknown[]`
|
|
42
|
-
| `lowPriorityThrottleMs` | `number`
|
|
43
|
-
| `baseCoalescingWindowMs` | `number`
|
|
44
|
-
| `mediumPriorityDelayMs` | `number`
|
|
45
|
-
| `dynamicRealtimeThrottleMs` | `(params) => number`
|
|
46
|
-
| `revalidateOnWindowFocus` | `boolean \| (() => boolean)`
|
|
47
|
-
| `transportReconnectCooldownMs` | `number`
|
|
48
|
-
| `usesRealTimeUpdates` | `boolean`
|
|
49
|
-
| `persistentStorage` | `CollectionPersistentStorageConfig<ItemState, ItemPayload>`
|
|
50
|
-
| `onInvalidate` | `(props: { itemState, payload, priority }) => void`
|
|
51
|
-
| `onSchedulerEvent` | `(event, data?) => void`
|
|
52
|
-
| `onMutationError` | `(error, options: { silentErrors?: boolean }) => void`
|
|
31
|
+
| Option | Type | Required | Description |
|
|
32
|
+
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
33
|
+
| `id` | `string` | Yes | Stable logical store id used for debug labels, persistence namespaces, and [Browser Tabs Sync](./browser-tabs-sync.md) |
|
|
34
|
+
| `storeManager` | `StoreManager` | Yes | Shared global config with `getSessionKey`, `errorNormalizer`, and global store controls |
|
|
35
|
+
| `fetchFn` | `(params, signal) => Promise<ItemState \| Result<ItemState, Error>>` | Yes | Fetches a single item |
|
|
36
|
+
| `batchFetchFn` | `(payloads, signal, batchKey) => Promise<Map<ItemPayload, ItemState \| Error \| Result<ItemState, Error>> \| Result<Map>>` | No | See [Batch Fetching](./batch-fetching.md) |
|
|
37
|
+
| `getItemsBatchKey` | `(payload: ItemPayload) => string \| false` | No | Groups batch fetches by key. `false` falls back to per-item fetch |
|
|
38
|
+
| `maxBatchSize` | `number` | No | Triggers immediate fetch when batch reaches this size |
|
|
39
|
+
| `maxItems` | `number` | No | Maximum cached items kept in memory. Defaults to `5000`. See [Cache Limits](./cache-limits.md) |
|
|
40
|
+
| `onStateCleanup` | `(cleanup) => void` | No | Called when memory cache eviction removes items. See [Cache Limits](./cache-limits.md) |
|
|
41
|
+
| `getCollectionItemKey` | `(params: ItemPayload) => ValidPayload \| unknown[]` | No | Custom key derivation from payload |
|
|
42
|
+
| `lowPriorityThrottleMs` | `number` | No | Overrides the manager default. See [Fetch Scheduling](./fetch-scheduling.md) |
|
|
43
|
+
| `baseCoalescingWindowMs` | `number` | No | Overrides the manager default. See [Fetch Scheduling](./fetch-scheduling.md) |
|
|
44
|
+
| `mediumPriorityDelayMs` | `number` | No | Delay for medium-priority fetches |
|
|
45
|
+
| `dynamicRealtimeThrottleMs` | `(params) => number` | No | Overrides the manager default. See [Real-Time Updates](./real-time-updates.md) |
|
|
46
|
+
| `revalidateOnWindowFocus` | `boolean \| (() => boolean)` | No | Refetch on window focus |
|
|
47
|
+
| `transportReconnectCooldownMs` | `number` | No | Cooldown for repeated transport reconnect revalidation |
|
|
48
|
+
| `usesRealTimeUpdates` | `boolean` | No | See [Real-Time Updates](./real-time-updates.md) |
|
|
49
|
+
| `persistentStorage` | `CollectionPersistentStorageConfig<ItemState, ItemPayload>` | No | Configure cache persistence. See [Persistent Storage](./persistent-storage.md) |
|
|
50
|
+
| `onInvalidate` | `(props: { itemState, payload, priority }) => void` | No | Called when an item is invalidated |
|
|
51
|
+
| `onSchedulerEvent` | `(event, data?) => void` | No | Scheduler event listener |
|
|
52
|
+
| `onMutationError` | `(error, options: { silentErrors?: boolean }) => void` | No | Global mutation error handler |
|
|
53
|
+
|
|
54
|
+
Fetch callbacks return promises. The resolved value may be either plain data or a `Result`. `Result.ok(data)` is stored as successful data; `Result.err(error)` is normalized into the item error state.
|
|
53
55
|
|
|
54
56
|
## Item State Shape
|
|
55
57
|
|
package/docs/document-store.md
CHANGED
|
@@ -32,10 +32,10 @@ const userStore = createDocumentStore<User>({
|
|
|
32
32
|
| ------------------------------ | -------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
33
33
|
| `id` | `string` | Yes | Stable logical store id used for debug labels, persistence namespaces, and [Browser Tabs Sync](./browser-tabs-sync.md) |
|
|
34
34
|
| `storeManager` | `StoreManager` | Yes | Shared global config with `getSessionKey`, `errorNormalizer`, and global store controls |
|
|
35
|
-
| `fetchFn` | `(signal: AbortSignal) => Promise<State
|
|
35
|
+
| `fetchFn` | `(signal: AbortSignal) => Promise<State \| Result<State, Error>>` | Yes | Fetches the document data |
|
|
36
36
|
| `lowPriorityThrottleMs` | `number` | No | Overrides the manager default. See [Fetch Scheduling](./fetch-scheduling.md) |
|
|
37
37
|
| `baseCoalescingWindowMs` | `number` | No | Overrides the manager default. See [Fetch Scheduling](./fetch-scheduling.md) |
|
|
38
|
-
| `dynamicRealtimeThrottleMs` | `(params: { lastFetchDuration: number; windowIsNotFocused: boolean }) => number` | No | See [Real-Time Updates](./real-time-updates.md)
|
|
38
|
+
| `dynamicRealtimeThrottleMs` | `(params: { lastFetchDuration: number; windowIsNotFocused: boolean }) => number` | No | Overrides the manager default. See [Real-Time Updates](./real-time-updates.md) |
|
|
39
39
|
| `revalidateOnWindowFocus` | `boolean \| (() => boolean)` | No | Refetch on window focus |
|
|
40
40
|
| `transportReconnectCooldownMs` | `number` | No | Cooldown for repeated transport reconnect revalidation |
|
|
41
41
|
| `mediumPriorityDelayMs` | `number` | No | Delay for medium-priority fetches |
|
|
@@ -44,6 +44,8 @@ const userStore = createDocumentStore<User>({
|
|
|
44
44
|
| `onSchedulerEvent` | `(event) => void` | No | Scheduler event listener |
|
|
45
45
|
| `onMutationError` | `(error, options: { silentErrors?: boolean }) => void` | No | Global mutation error handler |
|
|
46
46
|
|
|
47
|
+
`fetchFn` returns a promise. The resolved value may be either plain data or a `Result`. `Result.ok(data)` is stored as successful data; `Result.err(error)` is normalized into the store error state.
|
|
48
|
+
|
|
47
49
|
## State Shape
|
|
48
50
|
|
|
49
51
|
```ts
|
package/docs/fetch-scheduling.md
CHANGED
|
@@ -69,13 +69,13 @@ This is useful for background refetches that should yield to user-initiated acti
|
|
|
69
69
|
|
|
70
70
|
## Configuration Reference
|
|
71
71
|
|
|
72
|
-
| Option
|
|
73
|
-
|
|
|
74
|
-
| `lowPriorityThrottleMs`
|
|
75
|
-
| `baseCoalescingWindowMs`
|
|
76
|
-
| `mediumPriorityDelayMs`
|
|
77
|
-
| `dynamicRealtimeThrottleMs`
|
|
78
|
-
| `maxBatchSize`
|
|
72
|
+
| Option | Required | Description |
|
|
73
|
+
| ----------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
74
|
+
| `lowPriorityThrottleMs` | No | Manager default minimum interval between low-priority fetches, or a store-level override. Defaults to `5` |
|
|
75
|
+
| `baseCoalescingWindowMs` | No | Manager default time window to group multiple requests into a single batch, or a store-level override. Defaults to `10` |
|
|
76
|
+
| `mediumPriorityDelayMs` | No | Delay before medium-priority fetches execute |
|
|
77
|
+
| `dynamicRealtimeThrottleMs` | No | Manager default or store override returning throttle duration for real-time updates. Built-in default: `100ms` focused, `1000ms` background. See [Real-Time Updates](./real-time-updates.md) |
|
|
78
|
+
| `maxBatchSize` / `maxItemBatchSize` | No | Collection/ListQuery batch cap. List Query `maxItemBatchSize` defaults to `50`. Triggers immediate fetch when reached |
|
|
79
79
|
|
|
80
80
|
## Typical Configuration
|
|
81
81
|
|