zerodrift 1.1.0 → 1.2.0

package/README.md

@@ -218,6 +218,12 @@ const { data: teamIssues } = useRecordsByIndex(Issue, "teamId", teamId);
 const { data: comments } = useRelation(issue?.comments);    // a relation
 const { phase } = useBootstrapStatus();
 
+// Every read hook takes an optional trailing `{ pause }` — while true it reads
+// the pool but holds all fetching (auto-fire and reload) until flipped false:
+const { data: c } = useRecordsByIndex(store.comment, "issueId", issueId, {
+  pause: !panelOpen,
+});
+
 issue.title = "New title";
 issue.save();
 

package/dist/core/StoreManager.d.ts

@@ -40,6 +40,17 @@ export declare class RestrictDeleteError extends Error {
     restrictedByProperty: string;
     constructor(deletedModelName: string, deletedModelId: string, restrictedByModel: string, restrictedByProperty: string);
 }
+/** Per-call options for the `evict*` methods. */
+export interface EvictOptions {
+    /**
+     * Drop matching instances from the in-memory pool only, leaving the rows in
+     * IndexedDB (and the collection-coverage cache) intact. Use it on a layer
+     * switch to free memory now and rehydrate fast from IDB on return — no server
+     * round-trip. Default false: both the pool and IDB are cleared, and a future
+     * load refetches from the server.
+     */
+    keepInDb?: boolean;
+}
 export interface BootstrapResponse {
     lastSyncId: number;
     subscribedSyncGroups: string[];
@@ -726,17 +737,20 @@ export declare class StoreManager<TContext = unknown> {
      * Predicate receives hydrated instances (pool) and raw records (IDB); write
      * predicates that test plain property values so they work on both shapes.
      * IDB side is a full cursor scan — prefer `evictByIndex` when the match is
-     * "indexed column equals value".
+     * "indexed column equals value". Pass `{ keepInDb: true }` to release only
+     * the pool and leave the IDB rows cached. Returns the number of rows dropped.
      */
-    evictWhere(modelName: string, predicate: (m: Record<string, unknown>) => boolean): Promise<number>;
+    evictWhere(modelName: string, predicate: (m: Record<string, unknown>) => boolean, opts?: EvictOptions): Promise<number>;
     /**
      * Remove every record where `record[indexKey] === value`, using the IDB
      * index for the database side. Pool side is still a linear scan (no
      * secondary in-memory index by field value). Also clears the matching
      * `loadedCollections` cache key so a future `getOrLoadCollection(modelName,
      * indexKey, value)` re-fetches from the server instead of trusting IDB.
+     * Pass `{ keepInDb: true }` to release only the pool — IDB rows and the
+     * coverage entry are left intact, so the next load rehydrates from IDB.
      */
-    evictByIndex(modelName: string, indexKey: string, value: string): Promise<void>;
+    evictByIndex(modelName: string, indexKey: string, value: string, opts?: EvictOptions): Promise<void>;
     /**
      * Cascade `evictByIndex` across every model type that owns this FK. Use
      * when an "owner" id (workspaceId, teamId, userId, …) goes away and the
@@ -744,8 +758,10 @@ export declare class StoreManager<TContext = unknown> {
      * declare `indexKey` as `indexed: true` are skipped — `deleteModelsByIndex`
      * falls back to a full-store cursor scan when the index is missing, and
      * walking every store at every call is rarely what the caller wants.
+     * `opts` is forwarded to each `evictByIndex` — pass `{ keepInDb: true }` to
+     * release the pool for the whole scope while keeping IDB warm (layer switch).
      */
-    evictAllByIndex(indexKey: string, value: string): Promise<void>;
+    evictAllByIndex(indexKey: string, value: string, opts?: EvictOptions): Promise<void>;
     /** Pool-first bulk lookup by ID (for OwnedCollection resolution). */
     getOrLoadByIds<T extends BaseModel = BaseModel>(modelName: string, ids: string[]): Promise<T[]>;
     /** Pool-first single-model lookup by ID. */

package/dist/core/StoreManager.js

@@ -1551,10 +1551,14 @@ export class StoreManager {
      * Predicate receives hydrated instances (pool) and raw records (IDB); write
      * predicates that test plain property values so they work on both shapes.
      * IDB side is a full cursor scan — prefer `evictByIndex` when the match is
-     * "indexed column equals value".
+     * "indexed column equals value". Pass `{ keepInDb: true }` to release only
+     * the pool and leave the IDB rows cached. Returns the number of rows dropped.
      */
-    async evictWhere(modelName, predicate) {
+    async evictWhere(modelName, predicate, opts = {}) {
         const poolCount = this.evictFromPool(modelName, predicate);
+        if (opts.keepInDb === true) {
+            return poolCount;
+        }
         const records = await this.database.readAllModels(modelName);
         const ids = records.filter(predicate).map((r) => r.id);
         if (ids.length > 0) {
@@ -1568,9 +1572,16 @@ export class StoreManager {
      * secondary in-memory index by field value). Also clears the matching
      * `loadedCollections` cache key so a future `getOrLoadCollection(modelName,
      * indexKey, value)` re-fetches from the server instead of trusting IDB.
+     * Pass `{ keepInDb: true }` to release only the pool — IDB rows and the
+     * coverage entry are left intact, so the next load rehydrates from IDB.
      */
-    async evictByIndex(modelName, indexKey, value) {
+    async evictByIndex(modelName, indexKey, value, opts = {}) {
         this.evictFromPool(modelName, (m) => m[indexKey] === value);
+        if (opts.keepInDb === true) {
+            // Pool-only release: IDB rows and the collection-coverage entry stay,
+            // so a future getOrLoadCollection rehydrates from IDB without refetch.
+            return;
+        }
         await this.database.deleteModelsByIndex(modelName, indexKey, value);
         this.partialIndexCoverage.delete(StoreManager.collectionKey(modelName, indexKey, value));
         if (indexKey === ALL_INDEX_KEY_SENTINEL) {
@@ -1597,10 +1608,12 @@ export class StoreManager {
      * declare `indexKey` as `indexed: true` are skipped — `deleteModelsByIndex`
      * falls back to a full-store cursor scan when the index is missing, and
      * walking every store at every call is rarely what the caller wants.
+     * `opts` is forwarded to each `evictByIndex` — pass `{ keepInDb: true }` to
+     * release the pool for the whole scope while keeping IDB warm (layer switch).
      */
-    async evictAllByIndex(indexKey, value) {
+    async evictAllByIndex(indexKey, value, opts = {}) {
         const models = ModelRegistry.allModels().filter((meta) => meta.properties.get(indexKey)?.indexed === true);
-        await Promise.all(models.map((meta) => this.evictByIndex(meta.name, indexKey, value)));
+        await Promise.all(models.map((meta) => this.evictByIndex(meta.name, indexKey, value, opts)));
     }
     /** Pool-first bulk lookup by ID (for OwnedCollection resolution). */
     async getOrLoadByIds(modelName, ids) {

package/dist/core/index.d.ts

@@ -9,7 +9,7 @@ export { MemoryAdapter } from "./MemoryAdapter.js";
 export { BootstrapType } from "./Database.js";
 export type { DatabaseMeta, StorageAdapter } from "./Database.js";
 export { StoreManager, RestrictDeleteError } from "./StoreManager.js";
-export type { BootstrapResponse, BootstrapFetcher, BootstrapFetcherOptions, FetcherContext, StoreManagerConfig, TransportConfig, LoadingConfig, PersistenceConfig, HooksConfig, AdvancedConfig, OnDemandConfig, OnDemandFetcher, OnDemandBatchFetcher, ModelStreamConfig, } from "./StoreManager.js";
+export type { BootstrapResponse, EvictOptions, BootstrapFetcher, BootstrapFetcherOptions, FetcherContext, StoreManagerConfig, TransportConfig, LoadingConfig, PersistenceConfig, HooksConfig, AdvancedConfig, OnDemandConfig, OnDemandFetcher, OnDemandBatchFetcher, ModelStreamConfig, } from "./StoreManager.js";
 export type { UndoableAction } from "./Transaction.js";
 export type { TransactionSender, BatchResponse, UndoableActionHandlers, UndoResult, } from "./TransactionQueue.js";
 export type { SyncAction, DeltaPacket, SSEEndpoint, SyncMessageTransform, } from "./SyncConnection.js";

package/dist/react/index.d.ts

@@ -59,6 +59,17 @@ export interface AsyncResource<T> {
     error: Error | null;
     reload: () => Promise<void>;
 }
+/** Per-call options shared by the load-aware read hooks. */
+export interface UseQueryOptions {
+    /**
+     * When true, hold all fetching — auto-fire on mount/dependency change *and*
+     * `reload()` are suppressed until it flips false. The hook still reads the
+     * pool synchronously, so anything already resident renders immediately;
+     * only the async backfill waits. Use it to defer a fetch until a prerequisite
+     * is ready (auth resolved, a parent record loaded, a panel actually opened).
+     */
+    pause?: boolean;
+}
 /** Returns `store.batch` — the sync overload yields the `batchId` string,
  * the async overload a `Promise<string>`. */
 export declare function useBatch(): StoreManager["batch"];
@@ -68,8 +79,8 @@ export declare function useUndoRedo(): {
     canUndo: boolean;
     canRedo: boolean;
 };
-export declare function useRelation<T extends BaseModel = BaseModel>(relation: LazyCollectionBase<T> | null | undefined): AsyncResource<T[]>;
-export declare function useRelation<T extends BaseModel = BaseModel>(relation: BackRef<T> | null | undefined): AsyncResource<T | null>;
+export declare function useRelation<T extends BaseModel = BaseModel>(relation: LazyCollectionBase<T> | null | undefined, opts?: UseQueryOptions): AsyncResource<T[]>;
+export declare function useRelation<T extends BaseModel = BaseModel>(relation: BackRef<T> | null | undefined, opts?: UseQueryOptions): AsyncResource<T | null>;
 type AnyNamespace = EntityNamespace<any, any, any>;
 type ModelCtor<T extends BaseModel = BaseModel> = abstract new (...args: any[]) => T;
 type Handle = AnyNamespace | ModelCtor;
@@ -83,10 +94,10 @@ type RecordOf<H> = H extends ModelCtor<infer T> ? T : RecordOfNamespace<H>;
  * namespace, unconstrained `string` for a decorator class. */
 type IndexKeyOf<H> = H extends ModelCtor ? string : IndexKeyOfNamespace<H>;
 /** Reactive single record by id. Pool-first sync read; async backfill on miss. */
-export declare function useRecord<H extends Handle>(handle: H, id: string | null | undefined): AsyncResource<RecordOf<H> | null>;
+export declare function useRecord<H extends Handle>(handle: H, id: string | null | undefined, opts?: UseQueryOptions): AsyncResource<RecordOf<H> | null>;
 /** Reactive list of records, optionally filtered to (and ordered by) `ids`. */
-export declare function useRecords<H extends Handle>(handle: H, ids?: string[] | null): AsyncResource<RecordOf<H>[]>;
+export declare function useRecords<H extends Handle>(handle: H, ids?: string[] | null, opts?: UseQueryOptions): AsyncResource<RecordOf<H>[]>;
 /** Reactive list of records matching one value, or any of several, on a
  * foreign-key index. */
-export declare function useRecordsByIndex<H extends Handle>(handle: H, indexKey: IndexKeyOf<H>, value: string | readonly string[] | null | undefined): AsyncResource<RecordOf<H>[]>;
+export declare function useRecordsByIndex<H extends Handle>(handle: H, indexKey: IndexKeyOf<H>, value: string | readonly string[] | null | undefined, opts?: UseQueryOptions): AsyncResource<RecordOf<H>[]>;
 export {};

package/dist/react/index.js

@@ -184,12 +184,13 @@ const settled = (ready, isLoading, error) => ready && !isLoading && error == nul
 // (schema namespace or model class) to a registry name and delegate here,
 // so the pool-subscription / loader machinery lives in exactly one place.
 /** Reactive single model by id. Pool-first sync read; async backfill on miss. */
-function useRecordByName(modelName, id) {
+function useRecordByName(modelName, id, opts) {
     const { sm, status } = useSyncEngine();
     const pool = sm.objectPool;
     const ready = status.phase === BootstrapPhase.Ready;
+    const pause = opts?.pause ?? false;
     const item = usePoolSnapshot(modelName, () => id != null ? (pool.getById(modelName, id) ?? null) : null);
-    const { isLoading, error, reload } = useLoader(() => sm.getOrLoadById(modelName, id), ready && id != null, `${modelName}:${id ?? ""}`, 
+    const { isLoading, error, reload } = useLoader(() => sm.getOrLoadById(modelName, id), ready && id != null && !pause, `${modelName}:${id ?? ""}`, 
     // Skip the load when the pool already has the entry — eager models
     // render with isLoading: false from frame zero.
     () => id != null && pool.getById(modelName, id) == null);
@@ -205,10 +206,11 @@ function useRecordByName(modelName, id) {
  * set. Without `ids`: every instance in the pool. With `ids`: just those, in
  * the order given, with async backfill for any missing from the pool. The
  * ids array is compared by content so inline literals don't cause re-fetches. */
-function useRecordsByName(modelName, ids) {
+function useRecordsByName(modelName, ids, opts) {
     const { sm, status } = useSyncEngine();
     const pool = sm.objectPool;
     const ready = status.phase === BootstrapPhase.Ready;
+    const pause = opts?.pause ?? false;
     const idsKey = ids?.join(",") ?? "";
     const all = usePoolSnapshot(modelName, () => pool.getAll(modelName));
     const items = useMemo(() => {
@@ -220,7 +222,7 @@ function useRecordsByName(modelName, ids) {
             .map((id) => byId.get(id))
             .filter((m) => m != null);
     }, [all, idsKey]);
-    const { isLoading, error, reload } = useLoader(() => sm.getOrLoadByIds(modelName, ids ?? []), ready && ids != null && ids.length > 0, `${modelName}:${idsKey}`, () => ids != null && ids.some((id) => pool.getById(modelName, id) == null));
+    const { isLoading, error, reload } = useLoader(() => sm.getOrLoadByIds(modelName, ids ?? []), ready && ids != null && ids.length > 0 && !pause, `${modelName}:${idsKey}`, () => ids != null && ids.some((id) => pool.getById(modelName, id) == null));
     return {
         data: ready ? items : [],
         isLoading,
@@ -239,9 +241,10 @@ function useRecordsByName(modelName, ids) {
  * For one-round-trip multi-value fetches, configure
  * `onDemandIndexBatchFetcher` + `serverSupportsCompoundIndexKeys: true` —
  * see `agent-docs/04-lazy-loading.md`. */
-function useRecordsByIndexName(modelName, indexKey, value) {
+function useRecordsByIndexName(modelName, indexKey, value, opts) {
     const { sm, status } = useSyncEngine();
     const ready = status.phase === BootstrapPhase.Ready;
+    const pause = opts?.pause ?? false;
     const values = value == null
         ? []
         : (Array.isArray(value) ? value : [value]).filter((v) => v != null && v !== "");
@@ -261,7 +264,7 @@ function useRecordsByIndexName(modelName, indexKey, value) {
     }, [all, indexKey, valuesKey, hasValues]);
     const { isLoading, error, reload } = useLoader(async () => {
         await Promise.all(values.map((v) => sm.getOrLoadCollection(modelName, indexKey, v)));
-    }, ready && hasValues, `${modelName}:${indexKey}:${valuesKey}`, () => hasValues &&
+    }, ready && hasValues && !pause, `${modelName}:${indexKey}:${valuesKey}`, () => hasValues &&
         values.some((v) => !sm.isCollectionLoaded(modelName, indexKey, v)));
     return {
         data: ready ? items : [],
@@ -301,9 +304,10 @@ export function useUndoRedo() {
         canRedo: redoDepth > 0,
     };
 }
-export function useRelation(relation) {
+export function useRelation(relation, opts) {
     const [tick, forceRender] = useState(0);
     const isBackRef = relation instanceof BackRef;
+    const pause = opts?.pause ?? false;
     // Collections expose watch() for invalidation; BackRef does not.
     useEffect(() => {
         if (relation == null || isBackRef) {
@@ -312,10 +316,10 @@ export function useRelation(relation) {
         return relation.watch(() => forceRender((n) => n + 1));
     }, [relation, isBackRef]);
     useEffect(() => {
-        if (relation != null && !relation.isLoaded && !relation.isLoading) {
+        if (!pause && relation != null && !relation.isLoaded && !relation.isLoading) {
             relation.load().then(() => forceRender((n) => n + 1));
         }
-    }, [relation, tick]);
+    }, [relation, tick, pause]);
     if (relation == null) {
         // Can't tell collection from back-ref at null; `[]` is the map-safe
         // default. A null back-ref reads `[]` rather than `null` — harmless
@@ -337,6 +341,9 @@ export function useRelation(relation) {
         isLoaded: relation.isLoaded ?? false,
         error: relation.error ?? null,
         reload: async () => {
+            if (pause) {
+                return;
+            }
             await (isBackRef
                 ? relation.load()
                 : relation.reload());
@@ -367,15 +374,15 @@ function handleRegistryName(handle) {
 // has `__mobx`/`store`; RecordOf has schema fields + extensions). One cast
 // per wrapper, contained.
 /** Reactive single record by id. Pool-first sync read; async backfill on miss. */
-export function useRecord(handle, id) {
-    return useRecordByName(handleRegistryName(handle), id);
+export function useRecord(handle, id, opts) {
+    return useRecordByName(handleRegistryName(handle), id, opts);
 }
 /** Reactive list of records, optionally filtered to (and ordered by) `ids`. */
-export function useRecords(handle, ids) {
-    return useRecordsByName(handleRegistryName(handle), ids);
+export function useRecords(handle, ids, opts) {
+    return useRecordsByName(handleRegistryName(handle), ids, opts);
 }
 /** Reactive list of records matching one value, or any of several, on a
  * foreign-key index. */
-export function useRecordsByIndex(handle, indexKey, value) {
-    return useRecordsByIndexName(handleRegistryName(handle), indexKey, value);
+export function useRecordsByIndex(handle, indexKey, value, opts) {
+    return useRecordsByIndexName(handleRegistryName(handle), indexKey, value, opts);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zerodrift",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "private": false,
   "description": "A TypeScript local-first sync engine: synchronous in-memory reads, optimistic writes, realtime SSE sync, offline IndexedDB persistence. Runs in the browser and in Node.",
   "license": "MIT",