tsdf 17.0.0-rc.1 → 17.0.1

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 { i as createAsyncStorageAdapter } from "./asyncStorageAdapter-BBKVK1S_.js";
1
+ import { i as createAsyncStorageAdapter } from "./asyncStorageAdapter-BuGjbXYA.js";
2
2
  export { createAsyncStorageAdapter };
@@ -7,19 +7,76 @@ import { sleep } from "@ls-stack/utils/sleep";
7
7
  import { rc_array, rc_discriminated_union, rc_literals, rc_number, rc_object, rc_parse, rc_parse_json, rc_record, rc_string, rc_tuple, rc_unknown } from "runcheck";
8
8
  import { asPossiblyUndefined } from "@ls-stack/utils/typingFnUtils";
9
9
  //#region src/persistentStorage/scheduleIdleCleanup.ts
10
+ const FALLBACK_IDLE_BUDGET_MS = 12;
11
+ const MIN_IDLE_TIME_REMAINING_MS = 1;
12
+ function getMonotonicNow() {
13
+ return performance.now();
14
+ }
15
+ /**
16
+ * Timeout-fired idle callbacks and the timer fallback do not receive a usable
17
+ * browser deadline. Give those ordinary tasks a small synthetic budget so
18
+ * maintenance still yields instead of running to completion on a busy page.
19
+ */
20
+ function normalizeIdleDeadline(deadline) {
21
+ if (deadline !== void 0 && !deadline.didTimeout) return deadline;
22
+ const startedAt = getMonotonicNow();
23
+ return {
24
+ didTimeout: true,
25
+ timeRemaining: () => Math.max(0, FALLBACK_IDLE_BUDGET_MS - (getMonotonicNow() - startedAt))
26
+ };
27
+ }
10
28
  /**
11
29
  * Schedules a fire-and-forget cleanup callback during idle time.
12
- * Uses `requestIdleCallback` when available, falls back to `setTimeout(fn, 2000)`.
30
+ * Uses `requestIdleCallback` when available, falling back to a timer-backed
31
+ * synthetic 12 ms deadline.
13
32
  */
14
33
  function scheduleIdleCleanup(callback) {
15
34
  if (typeof requestIdleCallback === "function") {
16
- const idleCallbackId = requestIdleCallback(() => callback(), { timeout: 3e3 });
35
+ const idleCallbackId = requestIdleCallback((deadline) => callback(normalizeIdleDeadline(deadline)), { timeout: 3e3 });
17
36
  return () => cancelIdleCallback(idleCallbackId);
18
37
  } else {
19
- const timeoutId = setTimeout(callback, 2e3);
38
+ const timeoutId = setTimeout(() => callback(normalizeIdleDeadline(void 0)), 2e3);
20
39
  return () => clearTimeout(timeoutId);
21
40
  }
22
41
  }
42
+ /**
43
+ * Tracks the current idle deadline and schedules cancellable continuations
44
+ * when a maintenance pass exhausts it.
45
+ */
46
+ function createIdleCleanupContext(initialDeadline) {
47
+ let currentDeadline = initialDeadline;
48
+ let continuationCount = 0;
49
+ let canceled = false;
50
+ let cancelContinuation = null;
51
+ let resolveContinuation = null;
52
+ return {
53
+ cancel() {
54
+ if (canceled) return;
55
+ canceled = true;
56
+ cancelContinuation?.();
57
+ cancelContinuation = null;
58
+ resolveContinuation?.(null);
59
+ resolveContinuation = null;
60
+ },
61
+ getContinuationCount: () => continuationCount,
62
+ isCanceled: () => canceled,
63
+ shouldYield: () => canceled || currentDeadline.timeRemaining() <= MIN_IDLE_TIME_REMAINING_MS,
64
+ async yieldIfNeeded() {
65
+ if (canceled) return false;
66
+ if (currentDeadline.timeRemaining() > MIN_IDLE_TIME_REMAINING_MS) return true;
67
+ const nextDeadline = await new Promise((resolve) => {
68
+ resolveContinuation = resolve;
69
+ cancelContinuation = scheduleIdleCleanup(resolve);
70
+ });
71
+ cancelContinuation = null;
72
+ resolveContinuation = null;
73
+ if (nextDeadline === null) return false;
74
+ currentDeadline = nextDeadline;
75
+ continuationCount++;
76
+ return true;
77
+ }
78
+ };
79
+ }
23
80
  const INITIAL_MAINTENANCE_CLEANUP_DELAY_MS = 1e4;
24
81
  /**
25
82
  * Gives startup maintenance a short grace period before using the regular
@@ -32,7 +89,7 @@ function scheduleInitialMaintenanceCleanup(callback) {
32
89
  }
33
90
  let cancelIdleCleanup = null;
34
91
  const timeoutId = setTimeout(() => {
35
- cancelIdleCleanup = scheduleIdleCleanup(callback);
92
+ cancelIdleCleanup = scheduleIdleCleanup(() => callback());
36
93
  }, INITIAL_MAINTENANCE_CLEANUP_DELAY_MS);
37
94
  return () => {
38
95
  clearTimeout(timeoutId);
@@ -298,6 +355,8 @@ var OfflineResolutionConflictParseError = class extends Error {
298
355
  };
299
356
  //#endregion
300
357
  //#region src/persistentStorage/persistenceUtils.ts
358
+ const MAINTENANCE_SORT_CHUNK_SIZE = 100;
359
+ const MAINTENANCE_LOOP_CHUNK_SIZE = 25;
301
360
  /**
302
361
  * Creates a key set that auto-clears entries after a microtask.
303
362
  * Used to deduplicate sync storage reads within the same event loop tick.
@@ -399,6 +458,96 @@ function keepEntriesWithinByteBudget(entries, getKey, getLastAccessAt, getSizeBy
399
458
  unprotectedBytes
400
459
  };
401
460
  }
461
+ /** Deadline-aware variant used by synchronous localStorage maintenance. */
462
+ async function keepEntriesWithinByteBudgetDuringIdle(entries, getKey, getLastAccessAt, getSizeBytes, isPinned, isProtected, maxBytes, idleContext) {
463
+ const keptKeys = /* @__PURE__ */ new Set();
464
+ let unprotectedBytes = 0;
465
+ for (const [entryIndex, entry] of entries.entries()) {
466
+ if (entryIndex % MAINTENANCE_LOOP_CHUNK_SIZE === 0 && !await idleContext.yieldIfNeeded()) return null;
467
+ if (!isProtected(entry)) unprotectedBytes += getSizeBytes(entry);
468
+ }
469
+ if (unprotectedBytes <= maxBytes) {
470
+ for (const [entryIndex, entry] of entries.entries()) {
471
+ if (entryIndex % MAINTENANCE_LOOP_CHUNK_SIZE === 0 && !await idleContext.yieldIfNeeded()) return null;
472
+ keptKeys.add(getKey(entry));
473
+ }
474
+ return {
475
+ keptKeys,
476
+ unprotectedBytes
477
+ };
478
+ }
479
+ const compareEntries = (left, right) => {
480
+ const leftProtected = isProtected(left);
481
+ const rightProtected = isProtected(right);
482
+ if (leftProtected && !rightProtected) return -1;
483
+ if (!leftProtected && rightProtected) return 1;
484
+ const leftPinned = isPinned(left);
485
+ const rightPinned = isPinned(right);
486
+ if (leftPinned && !rightPinned) return -1;
487
+ if (!leftPinned && rightPinned) return 1;
488
+ return getLastAccessAt(right) - getLastAccessAt(left);
489
+ };
490
+ const sortedChunks = [];
491
+ for (let chunkStart = 0; chunkStart < entries.length; chunkStart += MAINTENANCE_SORT_CHUNK_SIZE) {
492
+ if (!await idleContext.yieldIfNeeded()) return null;
493
+ sortedChunks.push(entries.slice(chunkStart, chunkStart + MAINTENANCE_SORT_CHUNK_SIZE).sort(compareEntries));
494
+ }
495
+ let mergeChunks = sortedChunks;
496
+ while (mergeChunks.length > 1) {
497
+ const nextMergeChunks = [];
498
+ for (let chunkIndex = 0; chunkIndex < mergeChunks.length; chunkIndex += 2) {
499
+ if (!await idleContext.yieldIfNeeded()) return null;
500
+ const leftChunk = mergeChunks[chunkIndex];
501
+ const rightChunk = mergeChunks[chunkIndex + 1];
502
+ if (leftChunk === void 0) continue;
503
+ if (rightChunk === void 0) {
504
+ nextMergeChunks.push(leftChunk);
505
+ continue;
506
+ }
507
+ const mergedChunk = [];
508
+ let leftIndex = 0;
509
+ let rightIndex = 0;
510
+ while (leftIndex < leftChunk.length || rightIndex < rightChunk.length) {
511
+ if (mergedChunk.length % MAINTENANCE_LOOP_CHUNK_SIZE === 0 && !await idleContext.yieldIfNeeded()) return null;
512
+ const leftEntry = leftChunk[leftIndex];
513
+ const rightEntry = rightChunk[rightIndex];
514
+ if (rightEntry === void 0 || leftEntry !== void 0 && compareEntries(leftEntry, rightEntry) <= 0) {
515
+ if (leftEntry !== void 0) mergedChunk.push(leftEntry);
516
+ leftIndex++;
517
+ } else {
518
+ mergedChunk.push(rightEntry);
519
+ rightIndex++;
520
+ }
521
+ }
522
+ nextMergeChunks.push(mergedChunk);
523
+ }
524
+ mergeChunks = nextMergeChunks;
525
+ }
526
+ const sortedEntries = mergeChunks[0] ?? [];
527
+ let keptUnprotectedBytes = 0;
528
+ for (const [entryIndex, entry] of sortedEntries.entries()) {
529
+ if (entryIndex % MAINTENANCE_LOOP_CHUNK_SIZE === 0 && !await idleContext.yieldIfNeeded()) return null;
530
+ const key = getKey(entry);
531
+ if (isProtected(entry)) {
532
+ keptKeys.add(key);
533
+ continue;
534
+ }
535
+ const sizeBytes = getSizeBytes(entry);
536
+ if (isPinned(entry)) {
537
+ keptKeys.add(key);
538
+ keptUnprotectedBytes += sizeBytes;
539
+ continue;
540
+ }
541
+ if (keptUnprotectedBytes + sizeBytes <= maxBytes) {
542
+ keptKeys.add(key);
543
+ keptUnprotectedBytes += sizeBytes;
544
+ }
545
+ }
546
+ return {
547
+ keptKeys,
548
+ unprotectedBytes
549
+ };
550
+ }
402
551
  //#endregion
403
552
  //#region src/persistentStorage/persistentStorageDefaults.ts
404
553
  const defaultMaxBytes = {
@@ -1962,4 +2111,4 @@ function serializeProtectedRef(ref) {
1962
2111
  return serializeProtectedRef$1(ref);
1963
2112
  }
1964
2113
  //#endregion
1965
- export { isModeEffectivelyActive as A, parseCompactLocalStorageEntry as B, isQuotaExceededError as C, compactOfflineStatusSnapshotSchema as D, OfflineResolutionConflictParseError as E, getSessionProtectedKeysSnapshot as F, getPersistedNamespaceId as G, encodePersistedAsyncNamespaceKind as H, setSessionProtectedKeysSnapshot as I, parsePersistedAsyncNamespaceKind as J, normalizeStaticPolicy as K, getNavigatorLockManager as L, offlineItemEntityRefSchema as M, offlineResolutionRecordSchema as N, defaultOfflineRuntimeConfig as O, clearSessionProtectedKeysSnapshot as P, warnIfNavigatorLockUnavailable as R, getSerializedStringSize as S, serializeJsonForStorage as T, getNamespaceId as U, compareMetadata as V, getPayloadRecordKey as W, INITIAL_MAINTENANCE_CLEANUP_DELAY_MS as X, serializeProtectedRef$1 as Y, scheduleIdleCleanup as Z, getTSDFDebugTimingMs as _, estimateManagedAsyncStorageEntrySizeBytes as a, createShouldIgnoreItemPredicate as b, readAsyncStorageNamespaceIndexStateUsingDriver as c, unregisterAsyncStartupStoreCleanup as d, parseAsyncStorageNamespaceKind as f, emitTSDFDebugLog as g, logPersistentStorageQuotaCleanup as h, createAsyncStorageAdapter as i, isOfflineModeStatusValue as j, getIsOfflineModeFromStatus as k, registerAsyncStartupStoreCleanup as l, getOfflineSessionStatusStorageKey as m, ASYNC_STORAGE_MAX_AGE_MS as n, getProtectedKeysFromMetadata as o, OFFLINE_SESSION_STATUS_STORE_NAME as p, parseAsyncStorageRecordKey as q, buildPersistedStaticPolicy as r, mergeManagedAsyncStorageCustomMetadata as s, ASYNC_MAINTENANCE_LOCAL_STORAGE_KEY as t, serializeProtectedRef as u, resolveTSDFLogger as v, keepEntriesWithinByteBudget as w, createTimedKeySet as x, getDefaultMaxBytesForScope as y, createCompactLocalStorageEntry as z };
2114
+ export { scheduleIdleCleanup as $, getIsOfflineModeFromStatus as A, createCompactLocalStorageEntry as B, isQuotaExceededError as C, OfflineResolutionConflictParseError as D, serializeJsonForStorage as E, clearSessionProtectedKeysSnapshot as F, getPayloadRecordKey as G, compareMetadata as H, getSessionProtectedKeysSnapshot as I, parseAsyncStorageRecordKey as J, getPersistedNamespaceId as K, setSessionProtectedKeysSnapshot as L, isOfflineModeStatusValue as M, offlineItemEntityRefSchema as N, compactOfflineStatusSnapshotSchema as O, offlineResolutionRecordSchema as P, createIdleCleanupContext as Q, getNavigatorLockManager as R, getSerializedStringSize as S, keepEntriesWithinByteBudgetDuringIdle as T, encodePersistedAsyncNamespaceKind as U, parseCompactLocalStorageEntry as V, getNamespaceId as W, serializeProtectedRef$1 as X, parsePersistedAsyncNamespaceKind as Y, INITIAL_MAINTENANCE_CLEANUP_DELAY_MS as Z, getTSDFDebugTimingMs as _, estimateManagedAsyncStorageEntrySizeBytes as a, createShouldIgnoreItemPredicate as b, readAsyncStorageNamespaceIndexStateUsingDriver as c, unregisterAsyncStartupStoreCleanup as d, parseAsyncStorageNamespaceKind as f, emitTSDFDebugLog as g, logPersistentStorageQuotaCleanup as h, createAsyncStorageAdapter as i, isModeEffectivelyActive as j, defaultOfflineRuntimeConfig as k, registerAsyncStartupStoreCleanup as l, getOfflineSessionStatusStorageKey as m, ASYNC_STORAGE_MAX_AGE_MS as n, getProtectedKeysFromMetadata as o, OFFLINE_SESSION_STATUS_STORE_NAME as p, normalizeStaticPolicy as q, buildPersistedStaticPolicy as r, mergeManagedAsyncStorageCustomMetadata as s, ASYNC_MAINTENANCE_LOCAL_STORAGE_KEY as t, serializeProtectedRef as u, resolveTSDFLogger as v, keepEntriesWithinByteBudget as w, createTimedKeySet as x, getDefaultMaxBytesForScope as y, warnIfNavigatorLockUnavailable as z };
@@ -1,3 +1,3 @@
1
- import { t as opfsPersistentStorage } from "./opfsPersistentStorage-B_lVflof.js";
2
- import { n as indexedDbPersistentStorage } from "./indexedDbPersistentStorage-D5tGmD77.js";
1
+ import { t as opfsPersistentStorage } from "./opfsPersistentStorage-D_k77Srq.js";
2
+ import { n as indexedDbPersistentStorage } from "./indexedDbPersistentStorage-BSlgLveB.js";
3
3
  export { indexedDbPersistentStorage, opfsPersistentStorage };
@@ -1,2 +1,2 @@
1
- import { n as indexedDbPersistentStorage, t as createIndexedDbPersistentStorage } from "./indexedDbPersistentStorage-D5tGmD77.js";
1
+ import { n as indexedDbPersistentStorage, t as createIndexedDbPersistentStorage } from "./indexedDbPersistentStorage-BSlgLveB.js";
2
2
  export { createIndexedDbPersistentStorage, indexedDbPersistentStorage };
@@ -1,4 +1,4 @@
1
- import { G as getPersistedNamespaceId, H as encodePersistedAsyncNamespaceKind, J as parsePersistedAsyncNamespaceKind, K as normalizeStaticPolicy, T as serializeJsonForStorage, U as getNamespaceId, V as compareMetadata, W as getPayloadRecordKey, Y as serializeProtectedRef, _ as getTSDFDebugTimingMs, a as estimateManagedAsyncStorageEntrySizeBytes, g as emitTSDFDebugLog, i as createAsyncStorageAdapter, q as parseAsyncStorageRecordKey } from "./asyncStorageAdapter-BBKVK1S_.js";
1
+ import { E as serializeJsonForStorage, G as getPayloadRecordKey, H as compareMetadata, J as parseAsyncStorageRecordKey, K as getPersistedNamespaceId, U as encodePersistedAsyncNamespaceKind, W as getNamespaceId, X as serializeProtectedRef, Y as parsePersistedAsyncNamespaceKind, _ as getTSDFDebugTimingMs, a as estimateManagedAsyncStorageEntrySizeBytes, g as emitTSDFDebugLog, i as createAsyncStorageAdapter, q as normalizeStaticPolicy } from "./asyncStorageAdapter-BuGjbXYA.js";
2
2
  import { __LEGIT_CAST__ } from "@ls-stack/utils/saferTyping";
3
3
  import { isObject } from "@ls-stack/utils/typeGuards";
4
4
  //#region src/persistentStorage/indexedDbAsyncStorageAdapter.ts
package/dist/main.d.ts CHANGED
@@ -95,7 +95,13 @@ type CreateStoreManagerOptions<TUploadRef extends ValidPayload = ValidPayload> =
95
95
  * stores attached to this manager. Return `false` to disable session-scoped
96
96
  * behavior while no account is loaded.
97
97
  */
98
- getSessionKey: () => string | false; /** Normalizes raw exceptions into the shared StoreError shape. */
98
+ getSessionKey: () => string | false;
99
+ /**
100
+ * Returns the stable app build version used to isolate browser-tab sync
101
+ * across deployments. The callback is evaluated once when the manager is
102
+ * created.
103
+ */
104
+ getAppVersion?: () => string; /** Normalizes raw exceptions into the shared StoreError shape. */
99
105
  errorNormalizer: (exception: Error) => StoreError; /** Default minimum interval between low-priority fetches for attached stores. Defaults to 40 minutes. */
100
106
  lowPriorityThrottleMs?: number; /** Default coalescing window for attached stores. Defaults to 16ms. */
101
107
  baseCoalescingWindowMs?: number; /** Extra browser-tab coalescing delay applied only while a tab is in the background. Defaults to 3000ms. */
@@ -1193,8 +1199,18 @@ declare function useGlobalOfflineEntities(sessionKey: string): readonly GlobalOf
1193
1199
  */
1194
1200
  declare function useGlobalOfflineResolutions(sessionKey: string): readonly OfflineResolutionRecord[];
1195
1201
  //#endregion
1202
+ //#region src/persistentStorage/scheduleIdleCleanup.d.ts
1203
+ type IdleCleanupContext = {
1204
+ cancel(): void;
1205
+ getContinuationCount(): number;
1206
+ isCanceled(): boolean;
1207
+ shouldYield(): boolean;
1208
+ yieldIfNeeded(): Promise<boolean>;
1209
+ };
1210
+ //#endregion
1196
1211
  //#region src/persistentStorage/localStorageMetadata.d.ts
1197
1212
  type ManagedLocalStorageIo = {
1213
+ invalidate?(key: string): void;
1198
1214
  getItem(key: string): string | null;
1199
1215
  setItem(key: string, value: string): void;
1200
1216
  removeItem(key: string): void;
@@ -1238,6 +1254,16 @@ type UpsertNamespaceEntryParams = {
1238
1254
  meta?: unknown;
1239
1255
  };
1240
1256
  declare function upsertManagedLocalStorageNamespaceEntry(params: UpsertNamespaceEntryParams, io?: ManagedLocalStorageIo): string;
1257
+ type ManagedLocalStorageNamespaceRemovalCandidate = {
1258
+ entryKey: string;
1259
+ lastAccessAt: number;
1260
+ offlineProtected: boolean;
1261
+ };
1262
+ type ManagedLocalStorageNamespaceRemovalResult = {
1263
+ processedCount: number;
1264
+ removedEntryKeys: string[];
1265
+ staleEntryKeys: string[];
1266
+ };
1241
1267
  //#endregion
1242
1268
  //#region src/persistentStorage/storageAdapter.d.ts
1243
1269
  type LocalStorageMetadataOptions = {
@@ -1249,6 +1275,7 @@ type LocalStorageMetadataOptions = {
1249
1275
  type LocalPersistentStorage = {
1250
1276
  kind: 'local-sync';
1251
1277
  runLocked<T>(callback: () => T | Promise<T>): Promise<T>;
1278
+ runMaintenanceLocked<T>(context: IdleCleanupContext, callback: () => T | Promise<T>): Promise<T>;
1252
1279
  readRaw(key: string): string | null;
1253
1280
  write<T>(key: string, value: T): {
1254
1281
  rawValue: string;
@@ -1267,11 +1294,12 @@ type LocalPersistentStorage = {
1267
1294
  upsertNamespaceEntry(args: Parameters<typeof upsertManagedLocalStorageNamespaceEntry>[0]): string;
1268
1295
  touchSingleEntry(payloadKey: string): boolean;
1269
1296
  touchNamespaceEntry(payloadKey: string, namespacePrefix: string): boolean;
1297
+ removeNamespaceEntriesIfUnchanged(storagePrefix: string, candidates: ManagedLocalStorageNamespaceRemovalCandidate[], candidateIndex: number, shouldYield: () => boolean): ManagedLocalStorageNamespaceRemovalResult;
1270
1298
  clearManifest(manifestKey: string): void;
1271
1299
  clearSession(sessionKey: string): void;
1272
- registerMaintenanceCallback(manifestKey: string, callback: () => Promise<void>): void;
1300
+ registerMaintenanceCallback(manifestKey: string, callback: (context?: IdleCleanupContext) => Promise<void>): void;
1273
1301
  unregisterMaintenanceCallback(manifestKey: string): void;
1274
- runMaintenance(forceManifestKeys?: Iterable<string>): Promise<void>;
1302
+ runMaintenance(forceManifestKeys: Iterable<string> | undefined, context: IdleCleanupContext): Promise<void>;
1275
1303
  readProtectedStorageKeys(sessionKey: string): Set<string>;
1276
1304
  syncSessionProtectedKeys(sessionKey: string, protectedKeys: Iterable<string>): void;
1277
1305
  };