tsdf 18.3.0 → 18.4.0

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-CcdWYuhc.js";
1
+ import { t as opfsPersistentStorage } from "./opfsPersistentStorage-BeUPOyk4.js";
2
2
  export { opfsPersistentStorage };
@@ -1,4 +1,4 @@
1
- import { t as AsyncStorageAdapter } from "./types-2UJIjziu.js";
1
+ import { t as AsyncStorageAdapter } from "./types-DUtkSBT8.js";
2
2
 
3
3
  //#region src/persistentStorage/opfsPersistentStorage.d.ts
4
4
  declare const opfsPersistentStorage: AsyncStorageAdapter;
@@ -403,7 +403,21 @@ type FieldsOption<HasPartialResources extends boolean> = HasPartialResources ext
403
403
  };
404
404
  //#endregion
405
405
  //#region src/persistentStorage/offlineUploadTypes.d.ts
406
- /** Lifecycle state for a session-scoped offline upload. */
406
+ /**
407
+ * Lifecycle state for a session-scoped offline upload.
408
+ *
409
+ * - `pending`: staged and waiting to be uploaded. An upload whose transport
410
+ * failed during replay with a failure TSDF retries on its own (session went
411
+ * offline, or the failure was classified as retryable) goes back to
412
+ * `pending` with `lastError` set.
413
+ * - `uploading`: the `upload` transport is running.
414
+ * - `uploaded`: the transport returned the final ref (`resolvedRef`).
415
+ * - `failed`: the last transport attempt failed and TSDF will not retry on
416
+ * its own: the dependent operation was moved to manual resolution, or the
417
+ * upload was started through `resolveOfflineUpload(s)`. A failed upload is
418
+ * not blocked: it is uploaded again when a dependent operation is replayed
419
+ * (resolution `retry`) or `resolveOfflineUpload(s)` is called again.
420
+ */
407
421
  type OfflineUploadState = 'pending' | 'uploading' | 'uploaded' | 'failed';
408
422
  /** Source that created a staged offline upload. */
409
423
  type OfflineUploadSource = 'manual' | 'mutation';
@@ -447,7 +461,11 @@ type OfflineUpload<TResolvedRef extends ValidPayload = ValidPayload> = {
447
461
  createdAt: number; /** Epoch timestamp for the latest upload metadata change. */
448
462
  updatedAt: number; /** Final server-side reference after upload completes. */
449
463
  resolvedRef?: TResolvedRef; /** Latest upload progress snapshot. */
450
- progress?: OfflineUploadProgress; /** Last upload failure message, when any. */
464
+ progress?: OfflineUploadProgress;
465
+ /**
466
+ * Message of the latest failed upload attempt. It stays set while the upload
467
+ * is retried and is cleared once the upload succeeds.
468
+ */
451
469
  lastError?: {
452
470
  message: string;
453
471
  };
@@ -463,6 +481,12 @@ type OfflineStoredUploadRecord<TResolvedRef extends ValidPayload = ValidPayload>
463
481
  /** Staged file blob restored from the upload adapter. */file: File; /** Last online session start time seen before the upload was stored. */
464
482
  lastOnlineSessionStartedAt?: number; /** File last-modified timestamp. */
465
483
  lastModified: number;
484
+ /**
485
+ * Store whose queued mutation attached this file, set on uploads with
486
+ * `source: 'mutation'`. Custom adapters must persist it: the file is removed
487
+ * once that store's queue no longer uses it.
488
+ */
489
+ storeName?: string;
466
490
  };
467
491
  /** Storage backend contract for session-scoped offline upload files. */
468
492
  type OfflineUploadAdapter = {
@@ -492,7 +516,19 @@ type OfflineUploadTransportContext = {
492
516
  };
493
517
  /** Upload handling config for an offline session. */
494
518
  type OfflineSessionUploadsConfig<TResolvedRef extends ValidPayload = ValidPayload> = {
495
- /** Adapter used to persist staged files until replay can upload them. */adapter: OfflineUploadAdapter; /** Upload transport that returns the final server-side file reference. */
519
+ /** Adapter used to persist staged files until replay can upload them. */adapter: OfflineUploadAdapter;
520
+ /**
521
+ * Upload transport that returns the final server-side file reference.
522
+ *
523
+ * Reject (throw) to report a failure. When the upload runs as a dependency
524
+ * of a replayed operation, the thrown error goes through the session's
525
+ * `classifyFailure` / `classifyRetryableFailure` hooks with `ctx.uploadId`
526
+ * set, exactly like a failed `execute`: classify connection problems as
527
+ * `'network'` / `'outage'` (or as retryable) so they are retried, and leave
528
+ * permanent ones (file too large, type not accepted) unclassified so the
529
+ * operation goes to manual resolution. Throw errors those hooks can tell
530
+ * apart.
531
+ */
496
532
  upload: (ctx: OfflineUploadTransportContext) => Promise<TResolvedRef>; /** Maximum number of concurrent upload transports. */
497
533
  concurrency?: number;
498
534
  };
@@ -583,6 +619,16 @@ type OfflineFailureContext = {
583
619
  storeType: OfflineStoreType; /** Optional operation name associated with the failure. */
584
620
  operationName?: string; /** Session key used by browser tab and persistence scoping. */
585
621
  sessionKey: string;
622
+ /**
623
+ * Set when replaying `operationName` (`phase: 'sync'`) failed while
624
+ * resolving one of its `dependsOnUploads` uploads: the id of that upload.
625
+ * The operation's `execute` was not called. The error is usually the one
626
+ * thrown by the session `upload` transport, but it can also be a storage
627
+ * error reading or updating the staged upload, or the error for an upload
628
+ * that no longer exists. `undefined` for every failure that did not come
629
+ * from a dependency upload.
630
+ */
631
+ uploadId?: string;
586
632
  };
587
633
  /** Re-check strategy for recovery probing. Omitted fields use built-in defaults (which differ between network and outage modes). */
588
634
  type OfflineRecoveryProbeConfig = {
@@ -658,6 +704,10 @@ type OfflineSessionConfig<TUploadRef extends ValidPayload = ValidPayload> = {
658
704
  * `network` activates network offline handling for future operations only
659
705
  * when `network.enabled` is true. Existing offline recovery may keep using
660
706
  * classifications until already-active work finishes recovering.
707
+ *
708
+ * Failures of the `uploads.upload` transport during replay are classified
709
+ * here too, with `ctx.uploadId` set: `outage` / `network` keep the upload
710
+ * `pending` and the dependent operation queued until the session recovers.
661
711
  */
662
712
  classifyFailure?: (error: unknown, ctx: OfflineFailureContext) => Promise<OfflineFailureClassification> | OfflineFailureClassification;
663
713
  /**
@@ -669,6 +719,11 @@ type OfflineSessionConfig<TUploadRef extends ValidPayload = ValidPayload> = {
669
719
  * case the entry still enters `needs-confirmation` so `shouldSkipSync` /
670
720
  * conflict checks can run before the mutation is promoted to manual
671
721
  * resolution.
722
+ *
723
+ * When `ctx.uploadId` is set the failure came from a dependency upload and
724
+ * the mutation was not sent: return `true` to run the upload again on the
725
+ * `replayRetry` cadence, or `false` for a permanent failure (file rejected),
726
+ * which moves the operation to manual resolution right away.
672
727
  */
673
728
  classifyRetryableFailure?: (error: unknown, ctx: OfflineFailureContext) => Promise<boolean> | boolean; /** Network detection strategy and browser integration. */
674
729
  network?: OfflineNetworkModeConfig; /** Outage detection and recovery strategy for remote failures. */
@@ -711,6 +766,42 @@ type GlobalOfflineStatus = {
711
766
  };
712
767
  /** Queue state of an offline mutation entry. */
713
768
  type OfflineSyncState = 'pending' | 'syncing' | 'needs-confirmation';
769
+ /**
770
+ * Offline sync state of one collection/list-query item, returned by the
771
+ * stores' `useItemOfflineState(...)` and `getItemOfflineState(...)`.
772
+ */
773
+ type ItemOfflineState = {
774
+ /**
775
+ * Where the item's offline work stands (same value as the item's
776
+ * {@link GlobalOfflineEntity.syncState}):
777
+ *
778
+ * - `pending`: queued, waiting to be sent
779
+ * - `syncing`: being sent
780
+ * - `needs-confirmation`: a send failed and it is not known whether it
781
+ * reached the server, so the mutation is re-checked or retried
782
+ * - `resolution-required`: waiting for a manual resolution
783
+ *
784
+ * With several mutations queued for the item this is the most urgent state
785
+ * among them (`needs-confirmation` > `syncing` > `pending`): the item is
786
+ * `syncing` while any of its mutations is being sent (`pendingMutations`
787
+ * drops as each one finishes).
788
+ */
789
+ syncState: OfflineSyncState | 'resolution-required'; /** Number of queued mutations of the item still waiting to sync. */
790
+ pendingMutations: number; /** Whether the item is waiting for a manual resolution. */
791
+ requiresResolution: boolean;
792
+ /**
793
+ * Whether the item was created offline through a `tempEntity` /
794
+ * `tempEntities` operation and the server has not confirmed it yet, so it is
795
+ * still tracked under its temporary payload. Creations queued without a temp
796
+ * entity (e.g. with a client-generated id) report `false`. It stays `true`
797
+ * while the creation itself is being sent, so the server may already have
798
+ * it while `syncState` is `syncing` or `needs-confirmation`; only with
799
+ * `syncState: 'pending'` has it not been sent yet. Once the server entity is
800
+ * reconciled, the temporary payload has no state anymore and the final
801
+ * payload reports any mutation still queued with `isUnsentCreation: false`.
802
+ */
803
+ isUnsentCreation: boolean;
804
+ };
714
805
  /** Aggregated offline status for a tracked document/item/query entity. */
715
806
  type GlobalOfflineEntity = {
716
807
  /** Internal entity identifier tracked by offline machinery. */id: string; /** Session key for this offline entity. */
@@ -720,7 +811,13 @@ type GlobalOfflineEntity = {
720
811
  entityKey: string; /** Entity kind used in queue partitioning. */
721
812
  entityKind: OfflineEntityKind; /** Effective lifecycle derived from queued operations targeting this entity. */
722
813
  kind: OfflineEntityMutationKind; /** Number of pending mutations waiting for sync. */
723
- pendingMutations: number; /** Current sync state for the entity. */
814
+ pendingMutations: number;
815
+ /**
816
+ * Current sync state for the entity. With several mutations queued for it
817
+ * this is the most urgent state among them (`needs-confirmation` >
818
+ * `syncing` > `pending`): the entity is `syncing` while any of its mutations
819
+ * is being sent.
820
+ */
724
821
  syncState: OfflineSyncState | 'resolution-required'; /** Whether the entity currently requires manual resolution. */
725
822
  requiresResolution: boolean; /** Resolution ids currently blocking this entity from being resolved/applied. */
726
823
  blockedByResolutionIds: string[]; /** Child resolution ids currently derived from this entity's dependency chain. */
@@ -789,7 +886,11 @@ type OfflineRetryExhaustedResolutionRecordBase<TInput = unknown> = {
789
886
  operation: string; /** Input value that exhausted replay retries. */
790
887
  input: TInput; /** Timestamp when the original queued mutation was enqueued. */
791
888
  enqueuedAt: number; /** Entity references involved in the resolution. */
792
- entityRefs: OfflineEntityRef[]; /** Last replay error snapshot captured before exhaustion. */
889
+ entityRefs: OfflineEntityRef[];
890
+ /**
891
+ * Last replay error snapshot captured before exhaustion. When a dependency
892
+ * upload failed permanently, this is the error of the `upload` transport.
893
+ */
793
894
  lastReplayError: {
794
895
  message: string;
795
896
  }; /** Resolution creation timestamp. */
@@ -823,12 +924,31 @@ type OfflineSession<TUploadRef extends ValidPayload = ValidPayload> = {
823
924
  getOfflineStatus: () => GlobalOfflineStatus; /** Returns the latest aggregated offline entities for the session. */
824
925
  getOfflineEntities: () => readonly GlobalOfflineEntity[]; /** Returns the latest aggregated conflict/retry resolutions for the session. */
825
926
  getOfflineResolutions: () => readonly OfflineResolutionRecord[]; /** Returns the latest session-scoped offline uploads for the session. */
826
- getOfflineUploads: () => readonly OfflineUpload<TUploadRef>[]; /** Resolves a staged upload id to its latest final ref, uploading first if needed. */
827
- resolveOfflineUpload: (id: string) => Promise<TUploadRef>; /** Resolves multiple staged upload ids to their latest final refs. */
828
- resolveOfflineUploads: (ids: readonly string[]) => Promise<Record<string, TUploadRef>>; /** Saves a session-scoped upload locally for later dependency resolution or ref usage. */
927
+ getOfflineUploads: () => readonly OfflineUpload<TUploadRef>[];
928
+ /**
929
+ * Resolves a staged upload id to its latest final ref, uploading first if
930
+ * needed. Rejects with the error thrown by the `upload` transport, leaving
931
+ * the upload `failed`; the session failure classifiers are not consulted.
932
+ */
933
+ resolveOfflineUpload: (id: string) => Promise<TUploadRef>;
934
+ /**
935
+ * Resolves multiple staged upload ids to their latest final refs. Rejects
936
+ * with the first transport error, like `resolveOfflineUpload`.
937
+ */
938
+ resolveOfflineUploads: (ids: readonly string[]) => Promise<Record<string, TUploadRef>>;
939
+ /**
940
+ * Saves a session-scoped upload locally for later dependency resolution or
941
+ * ref usage. It is deleted automatically once the queued work that depends
942
+ * on it leaves the queue.
943
+ */
829
944
  saveOfflineUpload: (args: SaveOfflineUploadArgs) => Promise<void>; /** Replaces a previously stored session-scoped upload, keeping its metadata unless new metadata is passed. */
830
945
  replaceOfflineUpload: (args: ReplaceOfflineUploadArgs) => Promise<void>; /** Loads a previously stored session-scoped upload. */
831
- loadOfflineUpload: (id: string) => Promise<File | null>; /** Deletes a stored upload when it is no longer referenced. */
946
+ loadOfflineUpload: (id: string) => Promise<File | null>;
947
+ /**
948
+ * Deletes a stored upload that no queued work references. Only needed for
949
+ * uploads no queued mutation used: the others are deleted with the work that
950
+ * depends on them.
951
+ */
832
952
  deleteOfflineUpload: (id: string) => Promise<void>; /** React hook subscribing to the session's global offline status. */
833
953
  useOfflineStatus: () => GlobalOfflineStatus; /** React hook subscribing to the session's aggregated offline entities. */
834
954
  useOfflineEntities: () => readonly GlobalOfflineEntity[]; /** React hook subscribing to the session's aggregated conflict/retry resolutions. */
@@ -1161,7 +1281,18 @@ type ConfiguredTempEntityFields<TInput, TTempResult, TTempId extends ValidPayloa
1161
1281
  * @typeParam TTempResult - Result returned by `execute`, used only when `tempEntity` or `tempEntities` needs to reconcile the final server entity. Defaults to `void`.
1162
1282
  */
1163
1283
  type OfflineOperationDefinition<TInput, TConflict, TTempResult = void, TServerSnapshot = unknown, TTempId extends ValidPayload = string, TPendingEntity = unknown, TFinalPayload extends ValidPayload = ValidPayload, TFinalData = unknown, TUploadRef extends ValidPayload = ValidPayload> = {
1164
- /** Schema used to validate incoming operation input. */inputSchema: PersistentStorageSchema<TInput>; /** Lifecycle classification for the queued operation. */
1284
+ /** Schema used to validate incoming operation input. */inputSchema: PersistentStorageSchema<TInput>;
1285
+ /**
1286
+ * Lifecycle classification for the queued operation. TSDF derives the
1287
+ * lifecycle of each entity the operation references (`getEntityRefs`) from
1288
+ * it.
1289
+ *
1290
+ * Every item a `create` references is treated as created by it: discarding
1291
+ * a `create` without temp entity removes all of them locally, without
1292
+ * refetching them. Return only the
1293
+ * created items, change existing items in a separate `update` operation, and
1294
+ * reference the items the creation needs with `dependsOn`.
1295
+ */
1165
1296
  kind: OfflineOperationKind;
1166
1297
  /**
1167
1298
  * Optional queue pruning for newer operations that supersede older queued work.
@@ -1301,7 +1432,12 @@ type DocumentOperationServerSnapshot<TOptions extends DefineOfflineOperation> =
1301
1432
  * ```
1302
1433
  */
1303
1434
  type DocumentOfflineOperationDefinition<State extends ValidStoreState, TOptions extends DefineOfflineOperation = DefineOfflineOperation, TUploadRef extends ValidPayload = ValidPayload> = WithoutTempEntity<OfflineOperationDefinition<DocumentOperationInput<TOptions>, DocumentOperationConflict<TOptions>, DocumentOperationResult<TOptions>, DocumentOperationServerSnapshot<TOptions>, string, unknown, ValidPayload, unknown, TUploadRef>> & {
1304
- /** Declares which upload ids must finish before replaying this operation. */dependsOnUploads?: (ctx: OperationEntityRefsContext<DocumentOperationInput<TOptions>>) => string[];
1435
+ /**
1436
+ * Declares which upload ids must finish before replaying this operation.
1437
+ * A staged upload is deleted once the last queued operation or resolution
1438
+ * record that declares it leaves the queue.
1439
+ */
1440
+ dependsOnUploads?: (ctx: OperationEntityRefsContext<DocumentOperationInput<TOptions>>) => string[];
1305
1441
  } & ([State] extends [never] ? never : unknown);
1306
1442
  /**
1307
1443
  * Builds a document offline operations map from a compact operation spec.
@@ -1387,7 +1523,12 @@ type CollectionOfflineOperationDefinition<ItemState extends ValidStoreState, Ite
1387
1523
  * Declares which collection item refs must resolve before replaying this
1388
1524
  * operation.
1389
1525
  */
1390
- dependsOn?: (ctx: OperationEntityRefsContext<TInput>) => CollectionOfflineEntityRef<ItemPayloadUnused>[]; /** Declares which upload ids must finish before replaying this operation. */
1526
+ dependsOn?: (ctx: OperationEntityRefsContext<TInput>) => CollectionOfflineEntityRef<ItemPayloadUnused>[];
1527
+ /**
1528
+ * Declares which upload ids must finish before replaying this operation.
1529
+ * A staged upload is deleted once the last queued operation or resolution
1530
+ * record that declares it leaves the queue.
1531
+ */
1391
1532
  dependsOnUploads?: (ctx: OperationEntityRefsContext<TInput>) => string[];
1392
1533
  } & ([ItemState | ItemPayloadUnused] extends [never] ? never : unknown);
1393
1534
  /**
@@ -1458,7 +1599,12 @@ type ListQueryOfflineOperationDefinition<ItemState extends ValidStoreState, Quer
1458
1599
  * Declares which list item refs must resolve before replaying this
1459
1600
  * operation.
1460
1601
  */
1461
- dependsOn?: (ctx: OperationEntityRefsContext<TInput>) => ListQueryOfflineEntityRef<ItemPayloadUnused>[]; /** Declares which upload ids must finish before replaying this operation. */
1602
+ dependsOn?: (ctx: OperationEntityRefsContext<TInput>) => ListQueryOfflineEntityRef<ItemPayloadUnused>[];
1603
+ /**
1604
+ * Declares which upload ids must finish before replaying this operation.
1605
+ * A staged upload is deleted once the last queued operation or resolution
1606
+ * record that declares it leaves the queue.
1607
+ */
1462
1608
  dependsOnUploads?: (ctx: OperationEntityRefsContext<TInput>) => string[];
1463
1609
  } & ([ItemState | QueryPayload | ItemPayloadUnused] extends [never] ? never : unknown);
1464
1610
  /**
@@ -1831,4 +1977,4 @@ type ListQueryPersistentStorageFields<QueryPayload extends ValidPayload, ItemPay
1831
1977
  /** Persistent storage config for ListQueryStore. */
1832
1978
  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>;
1833
1979
  //#endregion
1834
- export { OfflineResolutionConflictParseError as $, TSFDUseListQueryReturn as $t, DefineListQueryOfflineOperations as A, OfflineUploadTransportContext as At, OfflineEntityMutationKind as B, ListQueryUseMultipleItemsQuery as Bt, PersistentStorageSchema as C, TSDFFocusDebugOperation as Cn, OfflineSessionUploadsConfig as Ct, CollectionOfflineOperationDefinition as D, OfflineUploadProgress as Dt, CollectionOfflineEntityRef as E, OfflineUploadAdapter as Et, ListQueryOfflineEntityRef as F, DerivedQuerySource as Ft, OfflineMutationQueueingPolicy as G, OptimisticListUpdate as Gt, OfflineMutationInput as H, OffsetPaginationConfig as Ht, ListQueryOfflineOperationDefinition as I, FetchListFnReturn as It, OfflineReplayRetryConfig as J, QueryStatus as Jt, OfflineOperationKind as K, PartialResourcesConfig as Kt, OfflineAccumulationConfig as L, FetchListFnReturnItem as Lt, DocumentOfflineOperationDefinition as M, SaveOfflineUploadArgs as Mt, GlobalOfflineEntity as N, DerivedQueriesConfig as Nt, DefineCollectionOfflineOperations as O, OfflineUploadSource as Ot, GlobalOfflineStatus as P, DerivedQueryContext as Pt, OfflineResolutionActionForOperation as Q, TSFDUseListItemReturn as Qt, OfflineAccumulationMergeContext as R, FieldsInput as Rt, PersistentStoragePreloadResult as S, TSDFDebugLogger as Sn, OfflineOperationUploadsContext as St, AnyOfflineOperationDefinition as T, OfflineUpload as Tt, OfflineMutationQueueingCause as U, OnListQueryInvalidate as Ut, OfflineMutationDescriptor as V, ListQueryUseMultipleListQueriesQuery as Vt, OfflineMutationQueueingConfig as W, OnListQueryItemInvalidate as Wt, OfflineResolutionActionError as X, TSFDListQuery as Xt, OfflineResolutionAction as Y, TSDFItemQuery as Yt, OfflineResolutionActionErrorCode as Z, TSFDListQueryState as Zt, ListQueryOfflineOperationsConfig as _, ScheduleFetchOptions as _n, OperationResult as _t, AsyncStorageMetadataOrder as a, StoreFetchError as an, OfflineRetryExhaustedResolutionAction as at, PersistentStorageDataSchema as b, TSDFDebugLogEntry as bn, defaultOfflineRuntimeConfig as bt, AsyncStorageNamespaceCommitUpsert as c, TSDFStatus as cn, OfflineSession as ct, AsyncStorageNamespaceKind as d, ValidStoreState as dn, OfflineSyncState as dt, TSFDUsePendingOfflineItemsReturn as en, OfflineResolutionConflictParseErrorCode as et, AsyncStorageNamespaceScope as f, fetchTypePriority as fn, OfflineTempEntitiesConfig as ft, DocumentPersistentStorageConfig as g, RequestSchedulerEvents as gn, OperationConflict as gt, ConvertedPersistentStorageDataSchema as h, RequestSchedulerEventData as hn, OfflineTempEntityPendingEntry as ht, AsyncStorageDriverSetEntry as i, StoreError as in, OfflineResolutionRecordForStore as it, DefineOfflineOperation as j, ReplaceOfflineUploadArgs as jt, DefineDocumentOfflineOperations as k, OfflineUploadState as kt, AsyncStorageNamespaceGetResult as l, UnwrapTSDFResult as ln, OfflineSessionConfig as lt, CollectionPersistentStorageConfig as m, FetchType as mn, OfflineTempEntityConfig as mt, AsyncStorageDiscoveredScope as n, MutationSkipped as nn, OfflineResolutionRecord as nt, AsyncStorageNamespaceCommitArgs as o, StoreMutationError as on, OfflineRuntimeConfig as ot, AsyncStorageReadOptions as p, mutationSkipped as pn, OfflineTempEntitiesReconciliation as pt, OfflineQueueEntry as q, QueryFetchPayload as qt, AsyncStorageDriver as r, PayloadDebounce as rn, OfflineResolutionRecordForOperation as rt, AsyncStorageNamespaceCommitTouch as s, StoreMutationErrorOptions as sn, OfflineRuntimeConfigUpdate as st, AsyncStorageAdapter as t, MaybeTSDFResult as tn, OfflineResolutionGenericAction as tt, AsyncStorageNamespaceHandle as u, ValidPayload as un, OfflineSupersedeConfig as ut, ListQueryPersistentStorageConfig as v, ScheduleFetchResults as vn, ParsedOfflineResolutionConflictResultForOperation as vt, StorageAdapter as w, TSDFLoggerOptions as wn, OfflineStoredUploadRecord as wt, PersistentStorageErrorHandler as x, TSDFDebugLogLevel as xn, OfflineMutationUploadsInput as xt, PersistentStorageBaseConfig as y, TSDFDebugLogArea as yn, ParsedOfflineResolutionConflictResultForStore as yt, OfflineConflictResolutionAction as z, FieldsOption as zt };
1980
+ export { OfflineResolutionAction as $, TSDFItemQuery as $t, DefineListQueryOfflineOperations as A, OfflineUploadAdapter as At, OfflineConflictResolutionAction as B, FetchListFnReturn as Bt, PersistentStorageSchema as C, TSDFDebugLogArea as Cn, ParsedOfflineResolutionConflictResultForStore as Ct, CollectionOfflineOperationDefinition as D, TSDFFocusDebugOperation as Dn, OfflineSessionUploadsConfig as Dt, CollectionOfflineEntityRef as E, TSDFDebugLogger as En, OfflineOperationUploadsContext as Et, ItemOfflineState as F, ReplaceOfflineUploadArgs as Ft, OfflineMutationDescriptor as G, ListQueryUseMultipleListQueriesQuery as Gt, OfflineFailureClassification as H, FieldsInput as Ht, ListQueryOfflineEntityRef as I, SaveOfflineUploadArgs as It, OfflineMutationQueueingConfig as J, OnListQueryItemInvalidate as Jt, OfflineMutationInput as K, OffsetPaginationConfig as Kt, ListQueryOfflineOperationDefinition as L, DerivedQueriesConfig as Lt, DocumentOfflineOperationDefinition as M, OfflineUploadSource as Mt, GlobalOfflineEntity as N, OfflineUploadState as Nt, DefineCollectionOfflineOperations as O, TSDFLoggerOptions as On, OfflineStoredUploadRecord as Ot, GlobalOfflineStatus as P, OfflineUploadTransportContext as Pt, OfflineReplayRetryConfig as Q, QueryStatus as Qt, OfflineAccumulationConfig as R, DerivedQueryContext as Rt, PersistentStoragePreloadResult as S, ScheduleFetchResults as Sn, ParsedOfflineResolutionConflictResultForOperation as St, AnyOfflineOperationDefinition as T, TSDFDebugLogLevel as Tn, OfflineMutationUploadsInput as Tt, OfflineFailureContext as U, FieldsOption as Ut, OfflineEntityMutationKind as V, FetchListFnReturnItem as Vt, OfflineFailurePhase as W, ListQueryUseMultipleItemsQuery as Wt, OfflineOperationKind as X, PartialResourcesConfig as Xt, OfflineMutationQueueingPolicy as Y, OptimisticListUpdate as Yt, OfflineQueueEntry as Z, QueryFetchPayload as Zt, ListQueryOfflineOperationsConfig as _, mutationSkipped as _n, OfflineTempEntitiesReconciliation as _t, AsyncStorageMetadataOrder as a, MaybeTSDFResult as an, OfflineResolutionGenericAction as at, PersistentStorageDataSchema as b, RequestSchedulerEvents as bn, OperationConflict as bt, AsyncStorageNamespaceCommitUpsert as c, StoreError as cn, OfflineResolutionRecordForStore as ct, AsyncStorageNamespaceKind as d, StoreMutationErrorOptions as dn, OfflineRuntimeConfigUpdate as dt, TSFDListQuery as en, OfflineResolutionActionError as et, AsyncStorageNamespaceScope as f, TSDFStatus as fn, OfflineSession as ft, DocumentPersistentStorageConfig as g, fetchTypePriority as gn, OfflineTempEntitiesConfig as gt, ConvertedPersistentStorageDataSchema as h, ValidStoreState as hn, OfflineSyncState as ht, AsyncStorageDriverSetEntry as i, TSFDUsePendingOfflineItemsReturn as in, OfflineResolutionConflictParseErrorCode as it, DefineOfflineOperation as j, OfflineUploadProgress as jt, DefineDocumentOfflineOperations as k, OfflineUpload as kt, AsyncStorageNamespaceGetResult as l, StoreFetchError as ln, OfflineRetryExhaustedResolutionAction as lt, CollectionPersistentStorageConfig as m, ValidPayload as mn, OfflineSupersedeConfig as mt, AsyncStorageDiscoveredScope as n, TSFDUseListItemReturn as nn, OfflineResolutionActionForOperation as nt, AsyncStorageNamespaceCommitArgs as o, MutationSkipped as on, OfflineResolutionRecord as ot, AsyncStorageReadOptions as p, UnwrapTSDFResult as pn, OfflineSessionConfig as pt, OfflineMutationQueueingCause as q, OnListQueryInvalidate as qt, AsyncStorageDriver as r, TSFDUseListQueryReturn as rn, OfflineResolutionConflictParseError as rt, AsyncStorageNamespaceCommitTouch as s, PayloadDebounce as sn, OfflineResolutionRecordForOperation as st, AsyncStorageAdapter as t, TSFDListQueryState as tn, OfflineResolutionActionErrorCode as tt, AsyncStorageNamespaceHandle as u, StoreMutationError as un, OfflineRuntimeConfig as ut, ListQueryPersistentStorageConfig as v, FetchType as vn, OfflineTempEntityConfig as vt, StorageAdapter as w, TSDFDebugLogEntry as wn, defaultOfflineRuntimeConfig as wt, PersistentStorageErrorHandler as x, ScheduleFetchOptions as xn, OperationResult as xt, PersistentStorageBaseConfig as y, RequestSchedulerEventData as yn, OfflineTempEntityPendingEntry as yt, OfflineAccumulationMergeContext as z, DerivedQuerySource as zt };
@@ -80,13 +80,14 @@ The overall store state is `Record<string, TSFDCollectionItem | null>` where key
80
80
 
81
81
  ### Hooks
82
82
 
83
- | Hook | Description | Details |
84
- | ---------------------------------------- | ------------------------------------- | ------------------------------------------------------------- |
85
- | `useItem(payload, options?)` | Fetch and subscribe to a single item | See [Hooks - useItem](./hooks.md#useitem) |
86
- | `useMultipleItems(items, options?)` | Fetch and subscribe to multiple items | See [Hooks - useMultipleItems](./hooks.md#usemultipleitems) |
87
- | `useListItemIsLoading(payload, options)` | Detect if a sub-item is loading | See [Hooks - useListItem Hooks](./hooks.md#uselistitem-hooks) |
88
- | `useListItemIsDeleted(payload, options)` | Detect if a sub-item was deleted | See [Hooks - useListItem Hooks](./hooks.md#uselistitem-hooks) |
89
- | `useListItem(payload, options)` | Combined loading + deletion detection | See [Hooks - useListItem Hooks](./hooks.md#uselistitem-hooks) |
83
+ | Hook | Description | Details |
84
+ | ---------------------------------------- | --------------------------------------- | ----------------------------------------------------------------- |
85
+ | `useItem(payload, options?)` | Fetch and subscribe to a single item | See [Hooks - useItem](./hooks.md#useitem) |
86
+ | `useMultipleItems(items, options?)` | Fetch and subscribe to multiple items | See [Hooks - useMultipleItems](./hooks.md#usemultipleitems) |
87
+ | `useItemOfflineState(payload)` | Read the offline sync state of one item | See [Hooks - useItemOfflineState](./hooks.md#useitemofflinestate) |
88
+ | `useListItemIsLoading(payload, options)` | Detect if a sub-item is loading | See [Hooks - useListItem Hooks](./hooks.md#uselistitem-hooks) |
89
+ | `useListItemIsDeleted(payload, options)` | Detect if a sub-item was deleted | See [Hooks - useListItem Hooks](./hooks.md#uselistitem-hooks) |
90
+ | `useListItem(payload, options)` | Combined loading + deletion detection | See [Hooks - useListItem Hooks](./hooks.md#uselistitem-hooks) |
90
91
 
91
92
  ### Methods
92
93
 
@@ -113,6 +114,7 @@ The overall store state is `Record<string, TSFDCollectionItem | null>` where key
113
114
  | Method | Description |
114
115
  | ----------------------------------------------------- | ----------------------------------------------------------------- |
115
116
  | `getOfflineEntities()` / `useOfflineEntities()` | Read offline entities scoped to this store |
117
+ | `getItemOfflineState(payload)` | Read the offline sync state of one item, `null` if nothing queued |
116
118
  | `getOfflineResolutions()` / `useOfflineResolutions()` | Read manual conflict/retry resolutions scoped to this store |
117
119
  | `parseOfflineResolutionConflict(resolution)` | Narrow a persisted resolution to this store's operation types |
118
120
  | `resolveOfflineResolution(id, operation, action)` | Resolve, retry, discard, requeue, or commit an offline resolution |
package/docs/hooks.md CHANGED
@@ -149,7 +149,7 @@ store.useDocument({ disabled: true });
149
149
 
150
150
  - `data` - The selected data (or `null` if not loaded)
151
151
  - `status` - `'idle'` | `'loading'` | `'success'` | `'error'` | `'refetching'`
152
- - `error` - The `StoreError` if the fetch failed, otherwise `null`
152
+ - `error` - The `StoreError` if the fetch failed, otherwise `null`. While [offline](./offline.md#reading-while-offline), it is only set when there is no cached data to return; check it with `isOfflineStoreError(error)`
153
153
  - `isLoading` - Shorthand for `status === 'loading'`
154
154
  - `pendingSync` - `true` while local offline changes for this document still need to sync to the server
155
155
 
@@ -204,7 +204,7 @@ because the required refresh must be scheduled immediately.
204
204
 
205
205
  - `data` - The selected data (or `null`)
206
206
  - `status` - `'idle'` | `'loading'` | `'success'` | `'error'` | `'refetching'` | `'deleted'`
207
- - `error` - The `StoreError` if the fetch failed
207
+ - `error` - The `StoreError` if the fetch failed. While [offline](./offline.md#reading-while-offline), it is only set when there is no cached data to return; check it with `isOfflineStoreError(error)`
208
208
  - `isLoading` - Shorthand for `status === 'loading'`
209
209
  - `payload` - The resolved payload
210
210
  - `itemStateKey` - The internal key for this item
@@ -280,7 +280,7 @@ changes on every keystroke.
280
280
  - `isDerived` - Whether the result is currently coming from `derivedQueries` instead of an exact cached/fetched query
281
281
  - `isLoading` - Shorthand for `status === 'loading'`
282
282
  - `isLoadingMore` - Shorthand for `status === 'loadingMore'`
283
- - `error` - The `StoreError` if the fetch failed
283
+ - `error` - The `StoreError` if the fetch failed. While [offline](./offline.md#reading-while-offline), it is only set when there is no cached data to return; check it with `isOfflineStoreError(error)`
284
284
  - `payload` - The resolved payload
285
285
  - `queryKey` - The internal key for this query
286
286
  - `pendingSync` - `true` while local offline changes for this query still need to sync to the server
@@ -329,6 +329,81 @@ Behavior:
329
329
  - `items` - Visible pending items (or selected items)
330
330
  - `deletedItems` - Payloads for pending deletes
331
331
 
332
+ ## useItemOfflineState
333
+
334
+ **Stores**: [Collection Store](./collection-store.md), [List Query Store](./list-query-store.md)
335
+
336
+ Returns the offline sync state of one item, or `null` when the item has nothing
337
+ queued and no manual resolution waiting. It does not fetch anything. Use it for
338
+ per-row sync badges:
339
+
340
+ ```tsx
341
+ const Row = memo(function Row({ itemPayload }: { itemPayload: UserPayload }) {
342
+ const offlineState = store.useItemOfflineState(itemPayload);
343
+
344
+ if (!offlineState) return null;
345
+ if (offlineState.requiresResolution)
346
+ return <Badge>Needs your attention</Badge>;
347
+ if (offlineState.syncState === 'syncing') return <Badge>Syncing</Badge>;
348
+ return <Badge>Waiting to sync</Badge>;
349
+ });
350
+ ```
351
+
352
+ Behavior:
353
+
354
+ - The component re-renders only when the state of its own item changes, not
355
+ when other items of the store are queued, replayed, or resolved
356
+ - A falsy payload (`null`, `undefined`, `false`) returns `null`
357
+ - Stores without offline support always return `null`
358
+ - `store.getItemOfflineState(itemPayload)` reads the same state without
359
+ subscribing, for event handlers
360
+
361
+ ### Return value
362
+
363
+ `null`, or an `ItemOfflineState`:
364
+
365
+ - `syncState` - `'pending'` (waiting to be sent), `'syncing'` (being sent),
366
+ `'needs-confirmation'` (a send failed and it is not known whether it reached
367
+ the server, so it is re-checked or retried) or `'resolution-required'`. With
368
+ several mutations queued for the item this is the most urgent state among
369
+ them (`'needs-confirmation'` > `'syncing'` > `'pending'`): the item is
370
+ `'syncing'` while any of its mutations is being sent
371
+ - `pendingMutations` - Number of queued mutations of the item still waiting to
372
+ sync
373
+ - `requiresResolution` - `true` while the item waits for a manual resolution
374
+ (see [Offline - Conflict Resolution](./offline.md#conflict-resolution))
375
+ - `isUnsentCreation` - `true` while the item was created offline (a
376
+ `tempEntity` / `tempEntities` operation) and the server has not confirmed it
377
+ yet, so it is still tracked under its temporary payload. Creations queued
378
+ without a temp entity (e.g. with a client-generated id) report `false`
379
+
380
+ ### Items created offline
381
+
382
+ An item created offline is tracked under its temporary payload until the server
383
+ confirms it. After that the temporary payload returns `null`, and the final
384
+ payload reports the mutations that are still queued for the item (for example
385
+ an edit made right after creating it) with `isUnsentCreation: false`.
386
+
387
+ ```ts
388
+ function onDeleteClick(itemPayload: UserPayload) {
389
+ const offlineState = store.getItemOfflineState(itemPayload);
390
+
391
+ // A creation that was not sent yet only exists locally, so deleting it
392
+ // only discards local work: no need to ask before deleting for everyone.
393
+ const isLocalOnly =
394
+ offlineState?.isUnsentCreation && offlineState.syncState === 'pending';
395
+
396
+ if (isLocalOnly || confirmDeleteForEveryone()) {
397
+ deleteUser(itemPayload);
398
+ }
399
+ }
400
+ ```
401
+
402
+ `isUnsentCreation` stays `true` while the creation itself is being sent, until
403
+ the server result is reconciled. The server may already have the item while
404
+ `syncState` is `'syncing'` or `'needs-confirmation'`, which is why the example
405
+ also checks for `'pending'`.
406
+
332
407
  ## useMultipleItems
333
408
 
334
409
  **Stores**: [Collection Store](./collection-store.md), [List Query Store](./list-query-store.md)
@@ -207,6 +207,7 @@ Behavior:
207
207
  | ------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------- |
208
208
  | `useListQuery(payload, options?)` | Fetch and subscribe to a list query | See [Hooks - useListQuery](./hooks.md#uselistquery) |
209
209
  | `usePendingOfflineItems(options?)` | Read queued offline items without fetching | See [Hooks - usePendingOfflineItems](./hooks.md#usependingofflineitems) |
210
+ | `useItemOfflineState(payload)` | Read the offline sync state of one item | See [Hooks - useItemOfflineState](./hooks.md#useitemofflinestate) |
210
211
  | `useMultipleListQueries(queries, options?)` | Fetch multiple list queries | See [Hooks - useMultipleListQueries](./hooks.md#usemultiplelistqueries) |
211
212
  | `useItem(payload, options?)` | Fetch and subscribe to a single item | See [Hooks - useItem](./hooks.md#useitem) |
212
213
  | `useMultipleItems(items, options?)` | Fetch multiple individual items | See [Hooks - useMultipleItems](./hooks.md#usemultipleitems) |
@@ -242,6 +243,7 @@ Behavior:
242
243
  | Method | Description |
243
244
  | ----------------------------------------------------- | ----------------------------------------------------------------- |
244
245
  | `getOfflineEntities()` / `useOfflineEntities()` | Read offline entities scoped to this store |
246
+ | `getItemOfflineState(payload)` | Read the offline sync state of one item, `null` if nothing queued |
245
247
  | `getOfflineResolutions()` / `useOfflineResolutions()` | Read manual conflict/retry resolutions scoped to this store |
246
248
  | `parseOfflineResolutionConflict(resolution)` | Narrow a persisted resolution to this store's operation types |
247
249
  | `resolveOfflineResolution(id, operation, action)` | Resolve, retry, discard, requeue, or commit an offline resolution |