cabloy 5.1.207 → 5.1.209

package/zova/src/suite-vendor/a-zova/modules/a-model/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-module-a-model",
-  "version": "5.1.37",
+  "version": "5.1.38",
   "gitHead": "09d901d17140a80ee0764211b441cda72fd94663",
   "description": "core",
   "keywords": [

package/zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.persister.ts

@@ -1,90 +1,147 @@
 import type { Query, QueryKey } from '@tanstack/vue-query';
 
+import { CancelledError, notifyManager } from '@tanstack/query-core';
 import { experimental_createQueryPersister } from '@tanstack/query-persist-client-core';
+import { hashKey } from '@tanstack/vue-query';
 import localforage from 'localforage';
 import { SymbolBeanFullName } from 'zova';
 
+import type { ModelPersistenceToken } from '../../lib/modelPersistence.js';
 import type { QueryMetaPersister } from '../../types/index.js';
 
 import { CookieWrapper } from '../../common/cookieWrapper.js';
+import { getModelPersistenceStorageKey } from '../../lib/modelPersistence.js';
+import { getPersistenceQueue } from '../../lib/persistenceQueue.js';
 import { createQueryPersister } from '../../lib/queryPersister.js';
 import { resolveMaxAgeTime } from '../../types/index.js';
 import { BeanModelLast } from './bean.model.last.js';
 
 export class BeanModelPersister extends BeanModelLast {
+  private _persisterRestoreErrors = new Set<string>();
+
+  $persisterError(queryKey: QueryKey): boolean {
+    const query = this.self.$queryFind({ queryKey });
+    const options = this._adjustPersisterOptions(query?.meta?.persister);
+    return (
+      !!options &&
+      this._persisterRestoreErrors.has(this._getPersisterStorageKey(options, query, queryKey))
+    );
+  }
+
   private _persisterLoad_inner<T>(
-    storage: Storage,
-    storageKey: string,
     storedData: any,
     query: Query,
     options: QueryMetaPersister,
-  ): T | undefined {
-    if (!storedData) return undefined;
+  ): { data?: T; remove: boolean; timestamps?: { dataUpdatedAt: number; errorUpdatedAt: number } } {
+    if (!storedData) return { remove: false };
     const persistedQuery = options.deserialize
       ? options.deserialize(storedData as string, options.deserializeDefault!)
       : options.deserializeDefault!(storedData as string);
-
     if (persistedQuery.state.dataUpdatedAt) {
       const queryAge = Date.now() - persistedQuery.state.dataUpdatedAt;
       const expired = queryAge > (resolveMaxAgeTime(options.maxAge, query) ?? Infinity);
       const busted = persistedQuery.buster !== options.buster;
-      if (expired || busted) {
-        storage.removeItem(storageKey);
-      } else {
-        // Set proper updatedAt, since resolving in the first pass overrides those values
-        query.setState({
-          dataUpdatedAt: persistedQuery.state.dataUpdatedAt,
-          errorUpdatedAt: persistedQuery.state.errorUpdatedAt,
-        });
-        return persistedQuery.state.data as T;
+      if (!expired && !busted) {
+        return {
+          data: persistedQuery.state.data as T,
+          remove: false,
+          timestamps: {
+            dataUpdatedAt: persistedQuery.state.dataUpdatedAt,
+            errorUpdatedAt: persistedQuery.state.errorUpdatedAt,
+          },
+        };
       }
-    } else {
-      storage.removeItem(storageKey);
     }
+    return { remove: true };
   }
 
   $persisterLoad<T>(queryKey: QueryKey): Promise<T | undefined> | T | undefined {
+    const ctx = this.ctx;
+    if (ctx?.disposed) return undefined;
+    const persistence = this.$modelPersistence;
     const query = this.self.$queryFind({ queryKey });
     if (!query) return undefined;
     const options = this._adjustPersisterOptions(query.meta?.persister);
     if (!options) return undefined;
     const storage = this._getPersisterStorage(options, query);
     if (!storage) return undefined;
-    const storageKey = this._getPersisterStorageKey(options, query);
-    try {
-      const storedData = storage.getItem(storageKey);
-      if (options.sync) {
-        return this._persisterLoad_inner(storage as any, storageKey, storedData, query, options);
-      } else {
-        return (storedData as Promise<T>).then(storedData => {
-          return this._persisterLoad_inner(storage as any, storageKey, storedData, query, options);
+    const token = persistence.capture();
+    if (options.storage === 'db') persistence.touch(query);
+    const storageKey = this._getPersisterStorageKey(options, query, undefined, token);
+    this._persisterRestoreErrors.delete(storageKey);
+    const queue = getPersistenceQueue(storage);
+    const generation = queue.generation(storageKey);
+    const current = () =>
+      !ctx?.disposed &&
+      generation === queue.generation(storageKey) &&
+      (options.storage !== 'db' || persistence.current(token));
+    if (!options.sync) {
+      return queue
+        .enqueue(async () => {
+          if (!current()) return undefined;
+          const storedData = await storage.getItem(storageKey);
+          if (!current()) return undefined;
+          try {
+            const result = this._persisterLoad_inner<T>(storedData, query, options);
+            if (!current()) return undefined;
+            if (result.timestamps) query.setState(result.timestamps);
+            if (result.remove) await storage.removeItem(storageKey);
+            return current() ? result.data : undefined;
+          } catch {
+            if (!current()) return undefined;
+            this._persisterRestoreErrors.add(storageKey);
+            await storage.removeItem(storageKey);
+            this._reportPersisterError('restore');
+            return undefined;
+          }
+        })
+        .catch(() => {
+          if (current()) {
+            this._persisterRestoreErrors.add(storageKey);
+            this._reportPersisterError('restore');
+          }
+          return undefined;
         });
+    }
+    try {
+      const result = this._persisterLoad_inner<T>(storage.getItem(storageKey), query, options);
+      if (result.timestamps) query.setState(result.timestamps);
+      if (result.remove) storage.removeItem(storageKey);
+      return result.data;
+    } catch {
+      this._persisterRestoreErrors.add(storageKey);
+      this._reportPersisterError('restore');
+      try {
+        storage.removeItem(storageKey);
+      } catch {
+        this._reportPersisterError('remove');
       }
-    } catch (err) {
-      if (process.env.DEV) {
-        console.error(err);
-        console.warn(
-          'Encountered an error attempting to restore query cache from persisted location.',
-        );
-      }
-      storage.removeItem(storageKey);
     }
   }
 
-  $persisterSave(queryKey: QueryKey) {
+  $persisterGeneration(queryKey: QueryKey): string {
     const query = this.self.$queryFind({ queryKey });
-    if (!query) return;
+    const options = this._adjustPersisterOptions(query?.meta?.persister);
+    if (!options) return '';
+    const storage = this._getPersisterStorage(options, query);
+    if (!storage) return '';
+    const storageKey = this._getPersisterStorageKey(options, query, queryKey);
+    return `${options.storage === 'db' ? this.$modelPersistence.epoch : ''}:${storageKey}:${getPersistenceQueue(storage).generation(storageKey)}`;
+  }
+
+  $persisterSave(queryKey: QueryKey): Promise<void> {
+    const query = this.self.$queryFind({ queryKey });
+    if (!query) return Promise.resolve();
     const options = this._adjustPersisterOptions(query.meta?.persister);
-    if (!options) return;
-    this._persisterSave(query, options);
+    if (!options) return Promise.resolve();
+    return this._persisterSave(query, options);
   }
 
   $persisterSaveTo(queryKey: QueryKey, storageTarget: 'cookie' | 'local', value?: unknown) {
     const query = this.self.$queryFind({ queryKey });
     if (!query) {
-      if (process.env.DEV) {
+      if (process.env.DEV)
         console.warn('Cannot save persisted query because it was not found', queryKey);
-      }
       return;
     }
     const persister =
@@ -98,72 +155,252 @@ export class BeanModelPersister extends BeanModelLast {
           ? String(obj?.state?.data ?? '')
           : JSON.stringify(obj?.state?.data),
     });
-    if (!options) return;
-    this._persisterSave(query, options, value);
+    if (options) this._persisterSave(query, options, value);
   }
 
-  private _persisterSave(query: Query, options: QueryMetaPersister, value?: unknown) {
-    const storage = this._getPersisterStorage(options, query);
-    if (!storage) return;
-    const storageKey = this._getPersisterStorageKey(options, query);
+  private _serializePersister(query: Query, options: QueryMetaPersister, value?: unknown): string {
     const params = {
       state: value === undefined ? query.state : { ...query.state, data: value },
       queryKey: query.queryKey,
       queryHash: query.queryHash,
       buster: options.buster,
     };
-    const data = options.serialize
+    return options.serialize
       ? options.serialize(params, options.serializeDefault!)
       : options.serializeDefault!(params);
-    if (options.sync === true) {
-      storage.setItem(storageKey, data);
-    } else {
-      // Persist if we have storage defined, we use timeout to get proper state to be persisted
-      setTimeout(() => {
+  }
+
+  private _persisterSave(
+    query: Query,
+    options: QueryMetaPersister,
+    value?: unknown,
+  ): Promise<void> {
+    const storage = this._getPersisterStorage(options, query);
+    if (!storage) return Promise.resolve();
+    if (options.storage === 'db') this.$modelPersistence.touch(query);
+    const storageKey = this._getPersisterStorageKey(options, query);
+    const queue = getPersistenceQueue(storage);
+    queue.invalidate(storageKey);
+    let data: string;
+    try {
+      data = this._serializePersister(query, options, value);
+    } catch (error) {
+      return this._handlePersisterOperation(
+        queue.enqueue(() => {
+          throw error;
+        }),
+        'save',
+      );
+    }
+    if (options.sync === true && options.storage !== 'db') {
+      try {
         storage.setItem(storageKey, data);
-      }, 0);
+        return Promise.resolve();
+      } catch (error) {
+        return this._handlePersisterOperation(Promise.reject(error), 'save');
+      }
     }
+    // Accepted explicit writes keep their captured physical identity. The shared
+    // queue orders them before a later remove or full-store clear.
+    return this._handlePersisterOperation(
+      queue.enqueue(async () => {
+        await storage.setItem(storageKey, data);
+      }),
+      'save',
+    );
   }
 
-  $persisterRemove(queryKey: QueryKey) {
+  $persisterRemove(queryKey: QueryKey, persister?: QueryMetaPersister): Promise<void> {
     const query = this.self.$queryFind({ queryKey });
-    if (!query) return;
-    const options = this._adjustPersisterOptions(query.meta?.persister);
-    if (!options) return;
+    if (!query && !persister) return Promise.resolve();
+    const options = this._adjustPersisterOptions(persister ?? query?.meta?.persister);
+    if (!options) return Promise.resolve();
     const storage = this._getPersisterStorage(options, query);
-    if (!storage) return;
-    const storageKey = this._getPersisterStorageKey(options, query);
-    if (options.sync === true) {
-      storage.removeItem(storageKey);
-    } else {
-      // Persist if we have storage defined, we use timeout to get proper state to be persisted
-      setTimeout(() => {
+    if (!storage) return Promise.resolve();
+    if (options.storage === 'db') this.$modelPersistence.touch(query);
+    const storageKey = this._getPersisterStorageKey(options, query, queryKey);
+    const queue = getPersistenceQueue(storage);
+    queue.invalidate(storageKey);
+    if (options.sync === true && options.storage !== 'db') {
+      try {
         storage.removeItem(storageKey);
-      }, 0);
+        return Promise.resolve();
+      } catch (error) {
+        return this._handlePersisterOperation(Promise.reject(error), 'remove');
+      }
     }
+    return this._handlePersisterOperation(
+      queue.enqueue(async () => {
+        await storage.removeItem(storageKey);
+      }),
+      'remove',
+    );
+  }
+
+  async $persisterFlush(): Promise<void> {
+    if (process.env.SERVER) return;
+    await getPersistenceQueue(localforage).flush();
+  }
+
+  private _handlePersisterOperation<T>(operation: Promise<T>, action: string): Promise<T> {
+    operation.catch(() => this._reportPersisterError(action));
+    return operation;
+  }
+
+  private _reportPersisterError(action: string) {
+    if (process.env.DEV)
+      console.warn(`Encountered an error attempting to ${action} persisted query cache.`);
   }
 
   protected _createPersister(options?: QueryMetaPersister | boolean): any {
     options = this._adjustPersisterOptions(options);
     if (!options) return undefined;
-    const persisterFn = experimental_createQueryPersister({
-      storage: this._getPersisterStorage(options) as any,
-      maxAge: options.maxAge as number,
-      refetchOnRestore: options.refetchOnRestore,
-      prefix: options.prefix,
-      buster: options.buster,
-    }).persisterFn;
-    return createQueryPersister(persisterFn);
+    if (options.storage === 'db') return this._createDbPersister(options);
+    const storage = this._getPersisterStorage(options);
+    const persisterOptions = options;
+    return createQueryPersister((queryFn, context, query) => {
+      const queue = storage ? getPersistenceQueue(storage) : undefined;
+      const storageKey = `${persisterOptions.prefix}-${query.queryHash}`;
+      const generation = queue?.generation(storageKey);
+      const current = () => generation === queue?.generation(storageKey);
+      const orderedStorage =
+        storage && queue && !persisterOptions.sync
+          ? {
+              getItem: (key: string) =>
+                queue.enqueue(() => (current() ? storage.getItem(key) : undefined)),
+              setItem: (key: string, data: string) =>
+                this._handlePersisterOperation(
+                  queue.enqueue(async () => {
+                    if (current()) await storage.setItem(key, data);
+                  }),
+                  'save',
+                ),
+              removeItem: (key: string) =>
+                this._handlePersisterOperation(
+                  queue.enqueue(async () => {
+                    if (current()) await storage.removeItem(key);
+                  }),
+                  'remove',
+                ),
+            }
+          : storage;
+      return experimental_createQueryPersister({
+        storage: orderedStorage as any,
+        maxAge: persisterOptions.maxAge as number,
+        refetchOnRestore: persisterOptions.refetchOnRestore,
+        prefix: persisterOptions.prefix,
+        buster: persisterOptions.buster,
+      }).persisterFn(queryFn, context, query);
+    });
+  }
+
+  private _createDbPersister(options: QueryMetaPersister) {
+    const ctx = this.ctx;
+    const persistence = this.$modelPersistence;
+    // Do not use the upstream persister here: its deferred timestamp/refetch/save
+    // callbacks can run after a scope transition or owner disposal.
+    return async (queryFn, context, query: Query) => {
+      if (ctx?.disposed) throw new CancelledError({ silent: true, revert: false });
+      persistence.touch(query);
+      const token = persistence.capture();
+      const storage = this._getPersisterStorage(options, query);
+      const queue = storage && getPersistenceQueue(storage);
+      const storageKey = this._getPersisterStorageKey(options, query, undefined, token);
+      const generation = queue?.generation(storageKey);
+      const current = () =>
+        !ctx?.disposed &&
+        persistence.current(token) &&
+        generation === queue?.generation(storageKey);
+      const assertCurrent = () => {
+        if (!current()) throw new CancelledError({ silent: true, revert: false });
+      };
+      const bypass =
+        (query.state.fetchMeta as { bypassPersister?: boolean } | null)?.bypassPersister === true;
+      if (!bypass && storage && queue && query.state.data === undefined) {
+        this._persisterRestoreErrors.delete(storageKey);
+        const restored = await queue
+          .enqueue(async () => {
+            if (!current()) return undefined;
+            try {
+              const storedData = await storage.getItem(storageKey);
+              if (!current()) return undefined;
+              const result = this._persisterLoad_inner(storedData, query, options);
+              if (!current()) return undefined;
+              if (result.remove) await storage.removeItem(storageKey);
+              return current() ? result : undefined;
+            } catch {
+              if (current()) {
+                this._persisterRestoreErrors.add(storageKey);
+                await storage.removeItem(storageKey);
+                this._reportPersisterError('restore');
+              }
+              return undefined;
+            }
+          })
+          .catch(() => {
+            if (current()) {
+              this._persisterRestoreErrors.add(storageKey);
+              this._reportPersisterError('restore');
+            }
+            return undefined;
+          });
+        assertCurrent();
+        if (restored?.data !== undefined) {
+          notifyManager.schedule(() => {
+            if (!current()) return;
+            if (restored.timestamps) query.setState(restored.timestamps);
+            if (
+              options.refetchOnRestore === 'always' ||
+              (options.refetchOnRestore === true && query.isStale())
+            ) {
+              void query.fetch().catch(() => undefined);
+            }
+          });
+          return restored.data;
+        }
+      }
+      assertCurrent();
+      let result;
+      try {
+        result = await queryFn(context);
+      } catch (error) {
+        assertCurrent();
+        throw error;
+      }
+      assertCurrent();
+      if (!bypass && storage && queue) {
+        notifyManager.schedule(() => {
+          if (!current()) return;
+          let data: string;
+          try {
+            data = this._serializePersister(query, options, result);
+          } catch (error) {
+            this._handlePersisterOperation(
+              queue.enqueue(() => {
+                throw error;
+              }),
+              'save',
+            );
+            return;
+          }
+          this._handlePersisterOperation(
+            queue.enqueue(async () => {
+              if (current()) await storage.setItem(storageKey, data);
+            }),
+            'save',
+          );
+        });
+      }
+      return result;
+    };
   }
 
   protected _adjustPersisterOptions(options?: QueryMetaPersister | boolean) {
     if (options === false) return undefined;
-    if (options === undefined || options === true) {
-      options = {};
-    } else {
-      options = { ...options };
-    }
+    options = options === undefined || options === true ? {} : { ...options };
     options.storage = options.storage ?? (options.sync ? 'local' : 'db');
+    // DB storage is always asynchronous, including custom explicitly synced options.
+    if (options.storage === 'db') options.sync = false;
     options.maxAge = options.maxAge ?? this.scopeSelf.config.persister.maxAge[options.storage];
     options.refetchOnRestore =
       options.refetchOnRestore ?? this.scopeSelf.config.persister.refetchOnRestore;
@@ -174,22 +411,32 @@ export class BeanModelPersister extends BeanModelLast {
     return options;
   }
 
-  protected _getPersisterStorageKey(options: QueryMetaPersister, query: Query) {
-    if (options.storageKeySimplify) return String(query.queryKey[query.queryKey.length - 1]);
-    return `${options.prefix}-${query.queryHash}`;
+  protected _getPersisterStorageKey(
+    options: QueryMetaPersister,
+    query?: Query,
+    queryKey?: QueryKey,
+    token?: ModelPersistenceToken,
+  ) {
+    const key = query?.queryKey ?? this._forceQueryKeyPrefix(queryKey);
+    const logicalKey = options.storageKeySimplify
+      ? String(key[key.length - 1])
+      : `${options.prefix}-${query?.queryHash ?? hashKey(key)}`;
+    return options.storage === 'db'
+      ? getModelPersistenceStorageKey(
+          this.sys.env.APP_NAME ?? '',
+          (token ?? this.$modelPersistence.capture()).scope,
+          logicalKey,
+        )
+      : logicalKey;
   }
 
   protected _getPersisterStorage(options?: QueryMetaPersister | boolean, query?: Query) {
     options = this._adjustPersisterOptions(options);
     if (!options) return undefined;
-    // cookie
     if (options.storage === 'cookie')
       return this.bean._newBeanSimple(CookieWrapper, false, options, query);
-    // check server
     if (process.env.SERVER) return undefined;
-    // local
     if (options.storage === 'local') return localStorage;
-    // db
     if (options.storage === 'db') return localforage;
   }
 
@@ -205,9 +452,7 @@ export class BeanModelPersister extends BeanModelLast {
     if (!queryKey) queryKey = [];
     if (!this._prefixIsBeanFullName(queryKey[0])) {
       const prefixes = [this[SymbolBeanFullName]];
-      if (this.$onionOptions?.enableSelector) {
-        prefixes.push(this.selector);
-      }
+      if (this.$onionOptions?.enableSelector) prefixes.push(this.selector);
       queryKey = prefixes.concat(queryKey as any);
     }
     return queryKey;
@@ -215,6 +460,5 @@ export class BeanModelPersister extends BeanModelLast {
 
   private _prefixIsBeanFullName(prefix?: any) {
     return prefix === this[SymbolBeanFullName];
-    // return (prefix && typeof prefix === 'string' && prefix.split('.').length === 3);
   }
 }

package/zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.query.ts

@@ -17,6 +17,7 @@ import { cast } from 'zova';
 
 import type { MaybeRefDeep, NoUnknown } from '../../common/types.js';
 
+import { getPersistenceQueue } from '../../lib/persistenceQueue.js';
 import { BeanModelCookie } from './bean.model.cookie.js';
 
 export class BeanModelQuery extends BeanModelCookie {
@@ -83,12 +84,16 @@ export class BeanModelQuery extends BeanModelCookie {
   }
 
   async $clear() {
-    const queries = this.$queryClient.getQueryCache().getAll();
-    for (const query of queries) {
-      query?.setData(undefined);
-    }
-    // remove all db cache
-    await localforage.clear();
+    const queue = getPersistenceQueue(localforage);
+    // Invalidate in-flight restores and scheduled persisters before clearing memory.
+    queue.invalidateAll();
+    const clear = process.env.SERVER
+      ? Promise.resolve()
+      : queue.enqueue(async () => {
+          await localforage.clear();
+        });
+    this.$modelPersistence.clear();
+    await clear;
   }
 
   $normalizeFilters<T extends {}>(filters?: T): T {

package/zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.useQuery.ts

@@ -43,7 +43,9 @@ export class BeanModelUseQuery extends BeanModelQuery {
   $useQuery(options, queryClient) {
     const queryKey = this.self._forceQueryKeyPrefix(options.queryKey);
     const persister = this._createPersister(options.meta?.persister);
-    options = Object.assign({}, options, { queryKey, persister });
+    options = this.$modelPersistence.guardOptions(
+      Object.assign({}, options, { queryKey, persister }),
+    );
     // staleTime
     const sync = typeof options.meta?.persister === 'object' && options.meta?.persister?.sync;
     if (sync !== true) {

package/zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.useState.ts

@@ -346,17 +346,33 @@ export class BeanModelUseState extends BeanModelUseQuery {
   }
 
   private _handleAsyncDataGet(options, queryClient, persister) {
+    if (this.ctx?.disposed) return undefined;
+    // Track the context even when the disabled Query already contains data.
+    // A scope switch must invalidate the custom-ref consumer synchronously.
+    void this.$modelPersistence.epoch;
     const query = this.$useStateData(options, queryClient);
     if (query.data !== undefined) return query.data;
     return this._handleAsyncDataGet_inner(options, queryClient, persister);
   }
 
   private async _handleAsyncDataGet_inner(options, queryClient, persister) {
+    const ctx = this.ctx;
+    if (ctx?.disposed) return undefined;
+    const persistence = this.$modelPersistence;
     const queryKey = options.queryKey;
+    const token = persistence.capture();
     const query = this.$useStateData(options, queryClient);
     if (persister) {
+      const generation = this.$persisterGeneration(queryKey);
       const data = await this.$persisterLoad(queryKey);
-      if (data !== undefined) {
+      if (
+        ctx?.disposed ||
+        !persistence.current(token) ||
+        generation !== this.$persisterGeneration(queryKey)
+      ) {
+        return undefined;
+      }
+      if (data !== undefined && query.data === undefined) {
         this.$setQueryData(queryKey, data, false);
       }
     }

package/zova/src/suite-vendor/a-zova/modules/a-model/src/lib/index.ts

@@ -1,2 +1,3 @@
 export * from './model.js';
+export * from './modelPersistence.js';
 export * from './utils.js';