zova-module-a-model 5.1.37 → 5.1.39

package/src/bean/bean.model/bean.model.useStateGeneral.ts

@@ -3,11 +3,11 @@ import type { DefaultError, QueryClient, QueryKey, UseQueryOptions } from '@tans
 import type {
   DefinedInitialQueryOptions,
   UndefinedInitialQueryOptions,
-} from '../../common/types.js';
-import type { ModelUseQueryDefinedReturnType, ModelUseQueryReturnType } from '../../types/query.js';
-import type { StateType } from '../../types/query.js';
+} from '../../common/types.ts';
+import type { ModelUseQueryDefinedReturnType, ModelUseQueryReturnType } from '../../types/query.ts';
+import type { StateType } from '../../types/query.ts';
 
-import { BeanModelUseState } from './bean.model.useState.js';
+import { BeanModelUseState } from './bean.model.useState.ts';
 
 export class BeanModelUseStateGeneral extends BeanModelUseState {
   $useState<

package/src/bean/bean.modelBase.ts

@@ -1,7 +1,7 @@
 import { Virtual } from 'zova';
 import { Bean } from 'zova-module-a-bean';
 
-import { BeanModelFirst } from './bean.model/bean.model.first.js';
+import { BeanModelFirst } from './bean.model/bean.model.first.ts';
 
 @Bean()
 @Virtual()

package/src/common/cookieWrapper.ts

@@ -3,10 +3,10 @@ import type { CookieOptions } from 'zova';
 
 import { BeanSimple } from 'zova';
 
-import type { QueryMetaPersister } from '../types/index.js';
+import type { QueryMetaPersister } from '../types/index.ts';
 
-import { __ThisModule__ } from '../.metadata/this.js';
-import { resolveMaxAgeTime } from '../types/index.js';
+import { __ThisModule__ } from '../.metadata/this.ts';
+import { resolveMaxAgeTime } from '../types/index.ts';
 
 export class CookieWrapper extends BeanSimple {
   options: QueryMetaPersister;

package/src/config/config.ts

@@ -3,7 +3,7 @@ import type { CookieOptions, ZovaSys } from 'zova';
 
 import { defaultShouldDehydrateQuery } from '@tanstack/vue-query';
 
-import type { MaxAgeTime, StaleTimeFunction } from '../types/index.js';
+import type { MaxAgeTime, StaleTimeFunction } from '../types/index.ts';
 
 const defaultOptions: DefaultOptions = {
   queries: {

package/src/index.ts

@@ -1,3 +1,3 @@
-export * from './.metadata/index.js';
-export * from './lib/index.js';
-export * from './types/index.js';
+export * from './.metadata/index.ts';
+export * from './lib/index.ts';
+export * from './types/index.ts';

package/src/lib/index.ts

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

package/src/lib/model.ts

@@ -1,6 +1,6 @@
 import { createBeanDecorator } from 'zova';
 
-import type { IDecoratorModelOptions } from '../types/model.js';
+import type { IDecoratorModelOptions } from '../types/model.ts';
 
 export function Model<T extends IDecoratorModelOptions>(options?: T): ClassDecorator {
   return createBeanDecorator('model', 'ctx', true, options);

package/src/lib/modelPersistence.ts

@@ -0,0 +1,204 @@
+import type { Query, QueryClient, QueryOptions } from '@tanstack/query-core';
+
+import { notifyManager } from '@tanstack/query-core';
+import { markRaw, shallowRef } from 'vue';
+
+export type ModelPersistenceScope = readonly [string | null, string | null, string | null];
+export interface ModelPersistenceValues {
+  instanceId?: string | number | null;
+  siteId?: string | number | null;
+  userId?: string | number | null;
+}
+export interface ModelPersistenceToken {
+  readonly scope: ModelPersistenceScope;
+  readonly epoch: number;
+}
+
+const normalize = (value: string | number | null | undefined) =>
+  value == null ? null : String(value);
+
+export function getModelPersistenceStorageKey(
+  appName: string,
+  scope: ModelPersistenceScope,
+  logicalKey: string,
+): string {
+  return JSON.stringify(['zova-model-db', 1, appName, scope, logicalKey]);
+}
+
+export function isModelPersistenceDb(options?: unknown): boolean {
+  if (options === false) return false;
+  const persister =
+    options && typeof options === 'object' ? (options as { storage?: string; sync?: boolean }) : {};
+  return (persister.storage ?? (persister.sync ? 'local' : 'db')) === 'db';
+}
+
+function emptyQueryState() {
+  return {
+    data: undefined,
+    dataUpdateCount: 0,
+    dataUpdatedAt: 0,
+    error: null,
+    errorUpdateCount: 0,
+    errorUpdatedAt: 0,
+    fetchFailureCount: 0,
+    fetchFailureReason: null,
+    fetchMeta: null,
+    isInvalidated: false,
+    status: 'pending' as const,
+    fetchStatus: 'idle' as const,
+  };
+}
+
+/** App-owned identity; independent of the module providing the current Passport. */
+export class ModelPersistenceContext {
+  private _epoch = 0;
+  private _version = shallowRef(0);
+  private _scope: ModelPersistenceScope;
+  private _registered = false;
+  private _hydrated = new Set<Query>();
+  private _listeners = new Set<(token: ModelPersistenceToken) => void>();
+
+  constructor(
+    private _queryClient: QueryClient,
+    siteId?: string | number | null,
+  ) {
+    // IoC owners can be reactive; do not let Vue unwrap this class's private refs
+    // or proxy TanStack Query instances retained for hydration adoption.
+    markRaw(this);
+    this._scope = Object.freeze([null, normalize(siteId), null]);
+  }
+
+  get epoch(): number {
+    void this._version.value;
+    return this._epoch;
+  }
+
+  capture(): ModelPersistenceToken {
+    return Object.freeze({ scope: this._scope, epoch: this.epoch });
+  }
+
+  current(token: ModelPersistenceToken): boolean {
+    return token.epoch === this.epoch && token.scope === this._scope;
+  }
+
+  markHydrated(queries: Query[]) {
+    if (!this._registered) {
+      for (const query of queries) this._hydrated.add(query);
+    }
+  }
+
+  touch(query?: Query): void {
+    // A transferred Query that has since participated in DB work belongs to the
+    // actual invocation scope, not the one-time hydration adoption baseline.
+    if (query) this._hydrated.delete(query);
+  }
+
+  subscribe(listener: (token: ModelPersistenceToken) => void): () => void {
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  }
+
+  update(
+    values: ModelPersistenceValues,
+    options: { initial?: boolean; refetchActive?: boolean } = {},
+  ): void {
+    const scope: ModelPersistenceScope = Object.freeze([
+      normalize(values.instanceId),
+      normalize(values.siteId),
+      normalize(values.userId),
+    ]);
+    const adopt = !this._registered && options.initial === true;
+    this._registered = true;
+    if (scope.every((value, index) => value === this._scope[index])) {
+      this._hydrated.clear();
+      return;
+    }
+    const affected = this._queryClient
+      .getQueryCache()
+      .getAll()
+      .filter(
+        query =>
+          isModelPersistenceDb(query.meta?.persister) && !(adopt && this._hydrated.has(query)),
+      );
+    this._scope = scope;
+    this._hydrated.clear();
+    this._invalidate(affected);
+    // Outgoing relogin/logout still resets immediately, but must not refetch
+    // protected queries after their authentication has been removed.
+    if (options.refetchActive === false) return;
+    const token = this.capture();
+    // The identity owner installs authentication before publishing this transition.
+    // Defer refetch until all synchronous reset/listener work has finished.
+    void Promise.resolve().then(() => {
+      if (this.current(token)) {
+        return this._queryClient.refetchQueries({
+          type: 'active',
+          predicate: query => affected.includes(query),
+        });
+      }
+    });
+  }
+
+  clear(): void {
+    this._hydrated.clear();
+    this._invalidate(this._queryClient.getQueryCache().getAll());
+  }
+
+  private _invalidate(queries: Query[]): void {
+    this._epoch++;
+    // Cancel every retryer before resetting any query. Silent + non-reverting avoids
+    // the old fetch's asynchronous cancellation handler publishing an error/reset.
+    for (const query of queries) void query.cancel({ silent: true, revert: false });
+    notifyManager.batch(() => {
+      for (const query of queries) {
+        query.setOptions({
+          ...query.options,
+          initialData: undefined,
+          initialDataUpdatedAt: undefined,
+        });
+        for (const observer of query.observers) {
+          observer.setOptions({
+            ...observer.options,
+            initialData: undefined,
+            initialDataUpdatedAt: undefined,
+            placeholderData: undefined,
+          });
+        }
+        query.setState(emptyQueryState());
+      }
+    });
+    this._version.value++;
+    const token = this.capture();
+    for (const listener of this._listeners) listener(token);
+  }
+
+  /** Keep later observer option reapplication from reinstalling an old identity. */
+  guardOptions<T extends QueryOptions>(options: T): T {
+    if (!isModelPersistenceDb(options.meta?.persister)) return options;
+    const token = this.capture();
+    const initialData = options.initialData;
+    const initialDataUpdatedAt = options.initialDataUpdatedAt;
+    const placeholderData = (options as T & { placeholderData?: unknown }).placeholderData;
+    return {
+      ...options,
+      initialData: () =>
+        this.current(token)
+          ? typeof initialData === 'function'
+            ? initialData()
+            : initialData
+          : undefined,
+      initialDataUpdatedAt: () =>
+        this.current(token)
+          ? typeof initialDataUpdatedAt === 'function'
+            ? initialDataUpdatedAt()
+            : initialDataUpdatedAt
+          : undefined,
+      placeholderData: (...args: unknown[]) =>
+        this.current(token)
+          ? typeof placeholderData === 'function'
+            ? placeholderData(...args)
+            : placeholderData
+          : undefined,
+    };
+  }
+}

package/src/lib/persistenceQueue.ts

@@ -0,0 +1,50 @@
+export class PersistenceQueue {
+  private _tail: Promise<unknown> = Promise.resolve();
+  private _sequence = 0;
+  private _failure?: { sequence: number; error: unknown };
+  private _generation = 0;
+  private _keyGenerations = new Map<string, number>();
+
+  generation(key: string): string {
+    return `${this._generation}:${this._keyGenerations.get(key) ?? 0}`;
+  }
+
+  invalidate(key: string) {
+    this._keyGenerations.set(key, (this._keyGenerations.get(key) ?? 0) + 1);
+  }
+
+  invalidateAll() {
+    this._generation++;
+    this._keyGenerations.clear();
+  }
+
+  enqueue<T>(operation: () => T | PromiseLike<T>): Promise<T> {
+    const sequence = ++this._sequence;
+    const result = this._tail.then(operation);
+    this._tail = result.catch(error => {
+      this._failure ??= { sequence, error };
+    });
+    return result;
+  }
+
+  async flush(): Promise<void> {
+    const sequence = this._sequence;
+    await this._tail;
+    if (this._failure && this._failure.sequence <= sequence) {
+      const { error } = this._failure;
+      this._failure = undefined;
+      throw error;
+    }
+  }
+}
+
+const queues = new WeakMap<object, PersistenceQueue>();
+
+export function getPersistenceQueue(storage: object): PersistenceQueue {
+  let queue = queues.get(storage);
+  if (!queue) {
+    queue = new PersistenceQueue();
+    queues.set(storage, queue);
+  }
+  return queue;
+}

package/src/lib/queryRefetch.ts

@@ -1,6 +1,6 @@
 import type { Query, RefetchOptions } from '@tanstack/query-core';
 
-import type { QueryRefetchOptions } from '../types/query.js';
+import type { QueryRefetchOptions } from '../types/query.ts';
 
 type QueryRefetch<TResult> = (options?: RefetchOptions) => Promise<TResult>;
 type QueryRefetchWithFetchOptions<TResult> = (

package/src/lib/utils.ts

@@ -1,4 +1,4 @@
-import type { DataQuery } from '../types/query.js';
+import type { DataQuery } from '../types/query.ts';
 
 export type TypeQueryEnsureLoadedFn<TData, TError = Error | null> = () =>
   | DataQuery<TData, TError>

package/src/monkey.ts

@@ -11,7 +11,7 @@ import { useQueryClient } from '@tanstack/vue-query';
 import { markRaw } from 'vue';
 import { BeanSimple } from 'zova';
 
-import { ServiceStorage } from './service/storage.js';
+import { ServiceStorage } from './service/storage.ts';
 
 export class Monkey
   extends BeanSimple
@@ -47,6 +47,11 @@ export class Monkey
   }
 
   async beanInit(bean: BeanContainer, beanInstance: BeanBase) {
+    bean.defineProperty(beanInstance, '$modelPersistence', {
+      enumerable: false,
+      configurable: true,
+      get: () => this._storage,
+    });
     bean.defineProperty(beanInstance, '$queryClient', {
       enumerable: false,
       configurable: true,

package/src/service/storage.ts

@@ -1,12 +1,49 @@
-import type { VueQueryPluginOptions } from '@tanstack/vue-query';
+import type { Query, VueQueryPluginOptions } from '@tanstack/vue-query';
 
 import { dehydrate, hydrate, QueryCache, QueryClient, VueQueryPlugin } from '@tanstack/vue-query';
 import { BeanBase, deepExtend } from 'zova';
 import { Service } from 'zova-module-a-bean';
 
+import type { ModelPersistenceToken, ModelPersistenceValues } from '../lib/modelPersistence.ts';
+
+import { ModelPersistenceContext } from '../lib/modelPersistence.ts';
+
 @Service()
 export class ServiceStorage extends BeanBase {
   private _queryClient: QueryClient;
+  private _persistence: ModelPersistenceContext;
+
+  get epoch() {
+    return this._persistence.epoch;
+  }
+
+  capture() {
+    return this._persistence.capture();
+  }
+
+  current(token: ModelPersistenceToken) {
+    return this._persistence.current(token);
+  }
+
+  update(values: ModelPersistenceValues, options?: { initial?: boolean; refetchActive?: boolean }) {
+    this._persistence.update(values, options);
+  }
+
+  subscribe(listener: (token: ModelPersistenceToken) => void) {
+    return this._persistence.subscribe(listener);
+  }
+
+  clear() {
+    this._persistence.clear();
+  }
+
+  touch(query?: Query) {
+    this._persistence.touch(query);
+  }
+
+  guardOptions<T extends Parameters<ModelPersistenceContext['guardOptions']>[0]>(options: T): T {
+    return this._persistence.guardOptions(options);
+  }
 
   async moduleLoaded() {
     // options
@@ -22,6 +59,7 @@ export class ServiceStorage extends BeanBase {
       defaultOptions: options,
       queryCache,
     }));
+    this._persistence = new ModelPersistenceContext(queryClient, this.sys.env.SITE_ID);
     // use plugin
     const vueQueryPluginOptions: VueQueryPluginOptions = { queryClient };
     this.app.vue.use(VueQueryPlugin, vueQueryPluginOptions);
@@ -43,7 +81,14 @@ export class ServiceStorage extends BeanBase {
     }
     // client
     if (process.env.CLIENT && this.ctx.meta.$ssr.isRuntimeSsrPreHydration) {
-      hydrate(this._queryClient, this.ctx.meta.$ssr.stateDefer.query);
+      const state = this.ctx.meta.$ssr.stateDefer.query;
+      hydrate(this._queryClient, state);
+      this._persistence.markHydrated(
+        (state?.queries ?? []).flatMap(item => {
+          const query = this._queryClient.getQueryCache().get(item.queryHash);
+          return query ? [query] : [];
+        }),
+      );
     }
   }
 }

package/src/types/index.ts

@@ -1,2 +1,2 @@
-export * from './model.js';
-export * from './query.js';
+export * from './model.ts';
+export * from './query.ts';

package/src/types/query.ts

@@ -12,11 +12,14 @@ import type {
 } from '@tanstack/vue-query';
 import type { DebuggerOptions, UnwrapNestedRefs } from 'vue';
 
+import type { ServiceStorage } from '../service/storage.ts';
+
 import 'zova';
 
 declare module 'zova' {
   export interface BeanBase {
     $queryClient: ReturnType<typeof useQueryClient>;
+    $modelPersistence: ServiceStorage;
   }
 }