@ramathibodi/nuxt-commons 4.0.5 → 4.0.6

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^4.3.1"
   },
-  "version": "4.0.5",
+  "version": "4.0.6",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/components/form/DateTime.vue

@@ -106,15 +106,11 @@ watchEffect(() => {
     }
   }
 });
-watch(computedDateRules, () => {
+watch([datePart, timePart, () => props.rules], () => {
   if (!props.readonly) nextTick(() => dateRef.value?.validate());
-}, {
-  deep: true
 });
-watch(computedTimeRules, () => {
+watch([datePart, timePart, () => props.rules], () => {
   if (!props.readonly) nextTick(() => timeRef.value?.validate());
-}, {
-  deep: true
 });
 watch(() => props.modelValue, () => {
   pauseEmit.value = true;

package/dist/runtime/composables/api.d.ts

@@ -1,14 +1,70 @@
 /**
  * useApi wraps authenticated HTTP calls, URL resolution, and optional response caching for runtime services.
+ *
+ * Caching contract for the `cache` parameter on get / getPromise / post / postPromise:
+ *
+ *   - `false` (default)             — no caching, every call hits the network.
+ *   - `true`                        — cache the response for 5 minutes (legacy default; preserved
+ *                                     for back-compat). Prefer `{ ttlSeconds }` for new code.
+ *   - `{ ttlSeconds: 5 }`           — cache for exactly 5 seconds. PREFERRED form.
+ *   - `{ ttlMs: 5000 }`             — same, expressed in milliseconds.
+ *   - `number` (legacy)             — DEPRECATED. Treated by an undocumented size-based
+ *                                     heuristic where values <= 60 are read as MINUTES and
+ *                                     values > 60 as SECONDS. Emits a console warning the
+ *                                     first time a session sees this form. Migrate to
+ *                                     `{ ttlSeconds }` / `{ ttlMs }` to remove the warning
+ *                                     and get unambiguous behaviour.
+ *
+ * Mutations that change resources read by a cached query should call
+ * `useApi().invalidate(prefix)` so the next read fetches fresh data. Without that,
+ * cached entries stay valid until their TTL expires — `localStorage` survives reloads,
+ * so users can see stale empty / outdated lists for the full TTL window even after
+ * creating data themselves.
+ *
  * This doc block is consumed by vue-docgen for generated API documentation.
  */
 import type { UseFetchOptions } from 'nuxt/app';
 import type { SearchParameters } from 'ofetch';
+/**
+ * Explicit cache options. Use this in new code instead of passing a bare number.
+ *  - `ttlSeconds`: cache lifetime in seconds. Mutually exclusive with `ttlMs`.
+ *  - `ttlMs`     : cache lifetime in milliseconds. Mutually exclusive with `ttlSeconds`.
+ */
+export type CacheOption = boolean | number | {
+    ttlSeconds: number;
+} | {
+    ttlMs: number;
+};
+export declare function _resetLegacyHeuristicWarning(): void;
+/**
+ * Resolve a cache option to seconds. Pure function, exported for tests.
+ *
+ *  - false / 0 / null / undefined → 0 (no cache)
+ *  - true                         → DEFAULT_TTL_SECONDS_FOR_TRUE
+ *  - { ttlSeconds: n }            → n  (clamped to >= 0, floored)
+ *  - { ttlMs: n }                 → ceil(n / 1000)
+ *  - number (legacy)              → heuristic + warn
+ */
+export declare function resolveCacheTtlSeconds(cache: CacheOption | undefined | null): number;
+/**
+ * Drop every `api-cache-*` localStorage entry whose stored URL contains `prefix`.
+ * Pass `undefined` (or no arg) to drop ALL api-cache entries.
+ *
+ * Recommended invalidation path after a mutation:
+ *
+ *   await useApi().postPromise('/model/resource/create', input)
+ *   useApi().invalidate('/model/resource')   // drops list + lookup caches
+ *
+ * Returns the number of entries removed. Safe to call when the cache is empty.
+ */
+declare function invalidateCache(prefix?: string): number;
 export declare function useApi(): {
     urlBuilder: (url: string | string[]) => string;
-    get: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: UseFetchOptions<unknown>, cache?: boolean | number) => Promise<T>;
-    getPromise: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: UseFetchOptions<unknown>, cache?: boolean | number) => Promise<T>;
-    post: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: UseFetchOptions<unknown>, cache?: boolean | number) => Promise<T>;
-    postPromise: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: UseFetchOptions<unknown>, cache?: boolean | number) => Promise<T>;
+    get: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: UseFetchOptions<unknown>, cache?: CacheOption) => Promise<T>;
+    getPromise: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: UseFetchOptions<unknown>, cache?: CacheOption) => Promise<T>;
+    post: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: UseFetchOptions<unknown>, cache?: CacheOption) => Promise<T>;
+    postPromise: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: UseFetchOptions<unknown>, cache?: CacheOption) => Promise<T>;
     hashKey: (data: any) => Promise<string>;
+    invalidate: typeof invalidateCache;
 };
+export {};

package/dist/runtime/composables/api.js

@@ -5,9 +5,65 @@ import { stableStringify } from "../utils/object.js";
 import { sha256 } from "../utils/hash.js";
 import { useRuntimeConfig } from "#imports";
 import { useAuthentication } from "../bridges/authentication.js";
+const DEFAULT_TTL_SECONDS_FOR_TRUE = 5 * 60;
+const CACHE_PREFIX = "api-cache-";
+let _legacyHeuristicWarned = false;
+function warnLegacyHeuristic(value, resolvedSeconds) {
+  if (_legacyHeuristicWarned) return;
+  _legacyHeuristicWarned = true;
+  console.warn(
+    `[useApi] cache=${value} resolved to ${resolvedSeconds}s via the legacy heuristic (values <=60 are minutes, >60 are seconds). This is ambiguous \u2014 pass { ttlSeconds: N } or { ttlMs: N } instead. See useApi() docblock for details.`
+  );
+}
+export function _resetLegacyHeuristicWarning() {
+  _legacyHeuristicWarned = false;
+}
+export function resolveCacheTtlSeconds(cache) {
+  if (!cache) return 0;
+  if (typeof cache === "boolean") return DEFAULT_TTL_SECONDS_FOR_TRUE;
+  if (typeof cache === "number") {
+    const n = Math.max(0, Number(cache));
+    if (!Number.isFinite(n) || n === 0) return 0;
+    const resolved = n > 60 ? n : n * 60;
+    warnLegacyHeuristic(n, resolved);
+    return resolved;
+  }
+  if (typeof cache === "object") {
+    if ("ttlSeconds" in cache) return Math.max(0, Math.floor(Number(cache.ttlSeconds) || 0));
+    if ("ttlMs" in cache) return Math.max(0, Math.ceil((Number(cache.ttlMs) || 0) / 1e3));
+  }
+  return 0;
+}
+function invalidateCache(prefix) {
+  if (typeof window === "undefined" || !window.localStorage) return 0;
+  const keys = [];
+  for (let i = 0; i < window.localStorage.length; i++) {
+    const k = window.localStorage.key(i);
+    if (k && k.startsWith(CACHE_PREFIX)) keys.push(k);
+  }
+  let removed = 0;
+  for (const k of keys) {
+    if (!prefix) {
+      try {
+        ls.remove(k);
+        removed++;
+      } catch {
+      }
+      continue;
+    }
+    try {
+      const raw = window.localStorage.getItem(k);
+      if (raw && raw.includes(prefix)) {
+        ls.remove(k);
+        removed++;
+      }
+    } catch {
+    }
+  }
+  return removed;
+}
 export function useApi() {
   const config = useRuntimeConfig();
-  const CACHE_PREFIX = "api-cache-";
   function urlBuilder(url) {
     let returnUrl;
     if (Array.isArray(url)) {
@@ -64,12 +120,6 @@ export function useApi() {
     const jsonString = stableStringify(data);
     return sha256(jsonString);
   }
-  function computeTtlSecond(cache) {
-    if (!cache) return 0;
-    if (typeof cache === "boolean") return 5 * 60;
-    let ttlNum = Math.max(0, Number(cache));
-    return ttlNum > 60 ? ttlNum : ttlNum * 60;
-  }
   function safeGetCache(key) {
     try {
       const v = ls.get(key);
@@ -80,7 +130,7 @@ export function useApi() {
   }
   async function ofetchWithCache(url, method, body, params, options, cache) {
     const builtUrl = urlBuilder(url);
-    const ttl = computeTtlSecond(cache);
+    const ttl = resolveCacheTtlSeconds(cache);
     if (ttl === 0) {
       return ofetch(builtUrl, optionBuilder(method, body, params, options));
     }
@@ -94,5 +144,5 @@ export function useApi() {
     ls.set(key, result, { ttl });
     return result;
   }
-  return { urlBuilder, get, getPromise, post, postPromise, hashKey };
+  return { urlBuilder, get, getPromise, post, postPromise, hashKey, invalidate: invalidateCache };
 }

package/dist/runtime/composables/graphql.d.ts

@@ -1,5 +1,6 @@
 import { type UseMutationReturn } from '@vue/apollo-composable';
 import { type ClassConstructor } from '../utils/object.js';
+import { type CacheOption } from './api.js';
 declare type VariableOptions = {
     type?: string;
     name?: string;
@@ -11,7 +12,7 @@ declare type VariableOptions = {
 };
 export declare function useGraphQl(): {
     query: <T>(operation: string, fields: Array<string | Object> | ClassConstructor<any>, variables?: VariableOptions, cache?: boolean) => import("@vue/apollo-composable").UseQueryReturn<T, Record<string, never>>;
-    queryPromise: <T>(operation: string, fields: Array<string | Object> | ClassConstructor<any>, variables?: VariableOptions, cache?: boolean | number) => Promise<T>;
+    queryPromise: <T>(operation: string, fields: Array<string | Object> | ClassConstructor<any>, variables?: VariableOptions, cache?: CacheOption) => Promise<T>;
     mutation: <T>(operation: string, fields: Array<string | Object> | ClassConstructor<any>, variables?: VariableOptions) => UseMutationReturn<any, any>;
     mutationPromise: <T>(operation: string, fields: Array<string | Object> | ClassConstructor<any>, variables?: VariableOptions) => Promise<T>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ramathibodi/nuxt-commons",
-  "version": "4.0.5",
+  "version": "4.0.6",
   "description": "Ramathibodi Nuxt modules for common components",
   "repository": {
     "type": "git",