@ramathibodi/nuxt-commons 4.0.4 → 4.0.6

package/dist/runtime/components/model/iterator.vue.d.ts

@@ -37,12 +37,12 @@ declare function openDialog(item?: object): void;
 declare var __VLS_15: {
     operation: {
         openDialog: typeof openDialog;
-        createItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>);
-        importItems: ((importItems: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void) | ((importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void);
-        updateItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>);
-        deleteItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<unknown>);
-        reload: (() => void) | (() => void);
-        setSearch: ((keyword: string) => void) | ((keyword: string) => void);
+        createItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>;
+        importItems: (importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void;
+        updateItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        deleteItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        reload: () => void;
+        setSearch: (keyword: string) => void;
         canServerPageable: boolean;
         canServerSearch: boolean;
         canCreate: boolean;
@@ -73,12 +73,12 @@ declare var __VLS_15: {
     item: import("vuetify/lib/components/VDataIterator/composables/items.mjs").DataIteratorItem<Record<string, any>>;
     operation: {
         openDialog: typeof openDialog;
-        createItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>);
-        importItems: ((importItems: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void) | ((importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void);
-        updateItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>);
-        deleteItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<unknown>);
-        reload: (() => void) | (() => void);
-        setSearch: ((keyword: string) => void) | ((keyword: string) => void);
+        createItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>;
+        importItems: (importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void;
+        updateItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        deleteItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        reload: () => void;
+        setSearch: (keyword: string) => void;
         canServerPageable: boolean;
         canServerSearch: boolean;
         canCreate: boolean;
@@ -92,12 +92,12 @@ declare var __VLS_15: {
     items: Record<string, any>[];
     operation: {
         openDialog: typeof openDialog;
-        createItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>);
-        importItems: ((importItems: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void) | ((importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void);
-        updateItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>);
-        deleteItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<unknown>);
-        reload: (() => void) | (() => void);
-        setSearch: ((keyword: string) => void) | ((keyword: string) => void);
+        createItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>;
+        importItems: (importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void;
+        updateItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        deleteItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        reload: () => void;
+        setSearch: (keyword: string) => void;
         canServerPageable: boolean;
         canServerSearch: boolean;
         canCreate: boolean;
@@ -124,17 +124,17 @@ declare var __VLS_15: {
     itemsCount: number;
     groupedItems: readonly (import("vuetify/lib/components/VDataIterator/composables/items.mjs").DataIteratorItem<Record<string, any>> | import("vuetify/lib/components/VDataTable/composables/group.mjs").Group<import("vuetify/lib/components/VDataIterator/composables/items.mjs").DataIteratorItem<Record<string, any>>> | import("vuetify/lib/components/VDataTable/composables/group.mjs").GroupSummary<import("vuetify/lib/components/VDataIterator/composables/items.mjs").DataIteratorItem<Record<string, any>>>)[];
 }, __VLS_92: {
-    reload: (() => void) | (() => void);
+    reload: () => void;
 }, __VLS_108: {
     items: Record<string, any>[];
     operation: {
         openDialog: typeof openDialog;
-        createItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>);
-        importItems: ((importItems: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void) | ((importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void);
-        updateItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>);
-        deleteItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<unknown>);
-        reload: (() => void) | (() => void);
-        setSearch: ((keyword: string) => void) | ((keyword: string) => void);
+        createItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>;
+        importItems: (importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void;
+        updateItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        deleteItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        reload: () => void;
+        setSearch: (keyword: string) => void;
         canServerPageable: boolean;
         canServerSearch: boolean;
         canCreate: boolean;
@@ -145,12 +145,12 @@ declare var __VLS_15: {
     items: Record<string, any>[];
     operation: {
         openDialog: typeof openDialog;
-        createItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>);
-        importItems: ((importItems: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void) | ((importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void);
-        updateItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>);
-        deleteItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<unknown>);
-        reload: (() => void) | (() => void);
-        setSearch: ((keyword: string) => void) | ((keyword: string) => void);
+        createItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>;
+        importItems: (importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void;
+        updateItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        deleteItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        reload: () => void;
+        setSearch: (keyword: string) => void;
         canServerPageable: boolean;
         canServerSearch: boolean;
         canCreate: boolean;
@@ -160,12 +160,12 @@ declare var __VLS_15: {
 }, __VLS_175: never, __VLS_176: {
     operation: {
         openDialog: typeof openDialog;
-        createItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>);
-        importItems: ((importItems: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void) | ((importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void);
-        updateItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>);
-        deleteItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<unknown>);
-        reload: (() => void) | (() => void);
-        setSearch: ((keyword: string) => void) | ((keyword: string) => void);
+        createItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>;
+        importItems: (importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void;
+        updateItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        deleteItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        reload: () => void;
+        setSearch: (keyword: string) => void;
         canServerPageable: boolean;
         canServerSearch: boolean;
         canCreate: boolean;
@@ -175,12 +175,12 @@ declare var __VLS_15: {
 }, __VLS_201: never, __VLS_202: {
     operation: {
         openDialog: typeof openDialog;
-        createItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>);
-        importItems: ((importItems: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void) | ((importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void);
-        updateItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>);
-        deleteItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<unknown>);
-        reload: (() => void) | (() => void);
-        setSearch: ((keyword: string) => void) | ((keyword: string) => void);
+        createItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>;
+        importItems: (importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void;
+        updateItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        deleteItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        reload: () => void;
+        setSearch: (keyword: string) => void;
         canServerPageable: boolean;
         canServerSearch: boolean;
         canCreate: boolean;
@@ -233,15 +233,15 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     itemsPerPage: number;
     api: boolean;
 }>>, {
-    reload: (() => void) | (() => void);
+    reload: () => void;
     operation: import("vue").Ref<{
         openDialog: typeof openDialog;
-        createItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>);
-        importItems: ((importItems: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void) | ((importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void);
-        updateItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>);
-        deleteItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<unknown>);
-        reload: (() => void) | (() => void);
-        setSearch: ((keyword: string) => void) | ((keyword: string) => void);
+        createItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>;
+        importItems: (importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void;
+        updateItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        deleteItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        reload: () => void;
+        setSearch: (keyword: string) => void;
         canServerPageable: boolean;
         canServerSearch: boolean;
         canCreate: boolean;
@@ -249,12 +249,12 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
         canDelete: boolean;
     }, {
         openDialog: typeof openDialog;
-        createItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>);
-        importItems: ((importItems: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void) | ((importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void);
-        updateItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>);
-        deleteItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<unknown>);
-        reload: (() => void) | (() => void);
-        setSearch: ((keyword: string) => void) | ((keyword: string) => void);
+        createItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>;
+        importItems: (importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void;
+        updateItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        deleteItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        reload: () => void;
+        setSearch: (keyword: string) => void;
         canServerPageable: import("vue").ComputedRef<boolean>;
         canServerSearch: import("vue").ComputedRef<boolean>;
         canCreate: import("vue").ComputedRef<boolean>;
@@ -262,12 +262,12 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
         canDelete: import("vue").ComputedRef<boolean>;
     } | {
         openDialog: typeof openDialog;
-        createItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>);
-        importItems: ((importItems: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void) | ((importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void);
-        updateItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<void>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>);
-        deleteItem: ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>) | ((item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<unknown>);
-        reload: (() => void) | (() => void);
-        setSearch: ((keyword: string) => void) | ((keyword: string) => void);
+        createItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback, importing?: boolean) => Promise<any>;
+        importItems: (importItemsList: Record<string, any>[], callback?: import("../../types/formDialog.js").FormDialogCallback) => void;
+        updateItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        deleteItem: (item: Record<string, any>, callback?: import("../../types/formDialog.js").FormDialogCallback) => Promise<any>;
+        reload: () => void;
+        setSearch: (keyword: string) => void;
         canServerPageable: boolean;
         canServerSearch: boolean;
         canCreate: boolean;

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

@@ -1,6 +1,54 @@
 /**
- * useAlert manages reactive alert state, creation helpers, and queue lifecycle used by notification components.
- * This doc block is consumed by vue-docgen for generated API documentation.
+ * Reactive alert queue shared between `createAlert()` (provider) and `useAlert()` (consumer).
+ *
+ * ## Setup
+ * `createAlert()` must be called **once** in an ancestor component — typically the root
+ * `app.vue` in a Nuxt app — to register the provider via Vue `provide()`. The `<Alert />`
+ * component only *consumes* the queue; it does not set it up. If no ancestor calls
+ * `createAlert()`, every `useAlert()` call returns `null` and toast pushes will throw.
+ *
+ * ```vue
+ * <!-- app.vue -->
+ * <script lang="ts" setup>
+ * createAlert()
+ * </script>
+ *
+ * <template>
+ *   <VApp>
+ *     <NuxtLayout><NuxtPage /></NuxtLayout>
+ *     <DialogHost />
+ *     <Alert />
+ *   </VApp>
+ * </template>
+ * ```
+ *
+ * ## Usage
+ * `useAlert()` returns an `AlertProvide | null`. There are **no** convenience methods
+ * like `.success()` / `.error()` / `.warning()` / `.info()` — push items via `addAlert`:
+ *
+ * ```ts
+ * const alert = useAlert()
+ * alert?.addAlert({ alertType: 'success', message: 'Saved' })
+ * alert?.addAlert({ alertType: 'error',   message: 'Failed: ' + err.message })
+ * alert?.addAlert({ alertType: 'warning', message: 'Check your input' })
+ * alert?.addAlert({ alertType: 'info',    message: 'Processing...' })
+ * ```
+ *
+ * `alertType` must be one of `'success' | 'error' | 'warning' | 'info'`. `message` is
+ * required — items without a `message` are silently dropped. Optional fields:
+ * `alertLocation` (default `'default'`, lets multiple `<Alert />` hosts filter),
+ * `alertExpireIn` (ms, default 60000), `alertIcon`, `data`.
+ *
+ * Always null-check the handle: `alert?.addAlert(...)`.
+ *
+ * ## Returned API (`AlertProvide`)
+ * - `addAlert(item)` — push a new alert onto the queue.
+ * - `takeAlert(location?)` — pop the next alert for the given location (default `'default'`).
+ * - `hasAlert(location?)` — whether anything is queued for the given location.
+ * - `clear()` — drop all queued alerts.
+ * - `items` — the underlying reactive ref (for custom consumers).
+ *
+ * Expired items (past `alertDateTime + alertExpireIn`) are auto-pruned once per second.
  */
 import { type InjectionKey, type Ref } from 'vue';
 import type { AlertItem } from '../types/alert.js';

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/apiLookupList.d.ts

@@ -1,6 +1,7 @@
 /**
- * useApiLookupList loads and normalizes lookup options for fields that depend on remote or cached reference lists,
- * using REST API calls via useApi().postPromise() instead of GraphQL.
+ * useApiLookupList loads and normalizes lookup options for fields that depend on remote or cached reference lists.
+ * Routes both the lookup-load Read (props.modelName) and the selection-resolution Read (props.modelSelectedItem)
+ * through useApiModelOperation, which owns the API-mode URL/body rules.
  * This doc block is consumed by vue-docgen for generated API documentation.
  */
 import { type Ref } from 'vue';

package/dist/runtime/composables/apiLookupList.js

@@ -2,8 +2,7 @@ import { computed, ref, shallowRef, watch } from "vue";
 import { watchDebounced } from "@vueuse/core";
 import { union, isEmpty, isArray, sortBy, castArray } from "lodash-es";
 import { useFuzzy } from "./utils/fuzzy.js";
-import { useApi } from "./api.js";
-import { buildApiEndpoint } from "./apiModel.js";
+import { useApiModelOperation } from "./apiModelOperation.js";
 export function useApiLookupList(props, emit, selectedItems) {
   const modelItems = shallowRef([]);
   const items = shallowRef([]);
@@ -50,13 +49,8 @@ export function useApiLookupList(props, emit, selectedItems) {
       variables[props.serverSearchKey] = searchData.value;
     }
     try {
-      const result = await useApi().postPromise(
-        buildApiEndpoint(props.modelName),
-        { fields: queryFields.value, variables },
-        void 0,
-        void 0,
-        props.cache
-      );
+      const ops = useApiModelOperation(props.modelName);
+      const result = await ops.read(queryFields.value, variables, props.cache);
       if (id !== requestId) return;
       if (isArray(result)) {
         modelItems.value = result;
@@ -127,13 +121,8 @@ export function useApiLookupList(props, emit, selectedItems) {
         const key = props.modelSelectedItemKey || "id";
         const variables = { ...props.modelSelectedItemBy || {} };
         variables[key] = stillMissing;
-        const result = await useApi().postPromise(
-          buildApiEndpoint(props.modelSelectedItem),
-          { fields: queryFields.value, variables },
-          void 0,
-          void 0,
-          props.cache
-        );
+        const ops = useApiModelOperation(props.modelSelectedItem);
+        const result = await ops.read(queryFields.value, variables, props.cache);
         const resolved = castArray(result);
         for (const obj of resolved) {
           const v = obj?.[props.itemValue];

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

@@ -33,7 +33,7 @@ export declare function useApiModel<T extends ApiModelComposableProps>(props: T)
     createItem: (item: Record<string, any>, callback?: FormDialogCallback, importing?: boolean) => Promise<any>;
     importItems: (importItemsList: Record<string, any>[], callback?: FormDialogCallback) => void;
     updateItem: (item: Record<string, any>, callback?: FormDialogCallback) => Promise<any>;
-    deleteItem: (item: Record<string, any>, callback?: FormDialogCallback) => Promise<unknown>;
+    deleteItem: (item: Record<string, any>, callback?: FormDialogCallback) => Promise<any>;
     loadItems: (options: any) => void;
     reload: () => void;
     isLoading: import("vue").Ref<boolean, boolean>;

package/dist/runtime/composables/apiModel.js

@@ -1,7 +1,7 @@
 import { computed, onMounted, ref } from "vue";
 import { watchDebounced } from "@vueuse/core";
 import { useAlert } from "./alert.js";
-import { useApi } from "./api.js";
+import { useApiModelOperation } from "./apiModelOperation.js";
 import { arrayWrap } from "../utils/array.js";
 import pLimit from "p-limit";
 export function stripModelByQualifier(modelName) {
@@ -14,7 +14,7 @@ export function buildApiEndpoint(modelName, action) {
 }
 export function useApiModel(props) {
   const alert = useAlert();
-  const api = useApi();
+  const ops = computed(() => useApiModelOperation(props.modelName));
   const items = ref([]);
   const itemsLength = ref(0);
   const search = ref();
@@ -49,13 +49,9 @@ export function useApiModel(props) {
     }
     return [.../* @__PURE__ */ new Set([...fieldsProps, ...tmpFields])];
   });
-  function mutationModelName() {
-    return stripModelByQualifier(props.modelName);
-  }
   function createItem(item, callback, importing = false) {
     isLoading.value = true;
-    const endpoint = buildApiEndpoint(mutationModelName(), "create");
-    return api.postPromise(endpoint, { input: item, fields: fields.value }).then((result) => {
+    return ops.value.create(item, fields.value).then((result) => {
       if (canServerPageable.value) {
         if (!importing) loadItems(currentOptions.value);
       } else {
@@ -92,8 +88,7 @@ export function useApiModel(props) {
   }
   function updateItem(item, callback) {
     isLoading.value = true;
-    const endpoint = buildApiEndpoint(mutationModelName(), "update");
-    return api.postPromise(endpoint, { input: item, fields: fields.value }).then((result) => {
+    return ops.value.update(item, fields.value).then((result) => {
       if (canServerPageable.value) {
         loadItems(currentOptions.value);
       } else {
@@ -113,8 +108,7 @@ export function useApiModel(props) {
   }
   function deleteItem(item, callback) {
     isLoading.value = true;
-    const endpoint = buildApiEndpoint(mutationModelName(), "delete");
-    return api.postPromise(endpoint, { input: item, fields: fields.value }).catch((error) => {
+    return ops.value.delete(item, fields.value).catch((error) => {
       alert?.addAlert({ alertType: "error", message: error?.message || String(error) });
     }).finally(() => {
       isLoading.value = false;
@@ -124,17 +118,15 @@ export function useApiModel(props) {
   }
   function loadItems(options) {
     currentOptions.value = options;
-    const endpoint = buildApiEndpoint(props.modelName, "pageable");
     isLoading.value = true;
-    api.postPromise(
-      endpoint,
-      Object.assign({}, props.modelBy, {
-        variables: props.modelBy,
-        fields: fields.value,
+    ops.value.readPageable(
+      fields.value,
+      props.modelBy,
+      {
         page: options?.page,
         perPage: options?.itemsPerPage,
         sortBy: options?.sortBy
-      })
+      }
     ).then((result) => {
       items.value = result.data;
       itemsLength.value = result.meta.totalItems;
@@ -151,10 +143,9 @@ export function useApiModel(props) {
       loadItems(currentOptions.value);
     } else {
       isLoading.value = true;
-      const endpoint = buildApiEndpoint(props.modelName);
-      api.postPromise(
-        endpoint,
-        { variables: props.modelBy, fields: fields.value }
+      ops.value.read(
+        fields.value,
+        props.modelBy
       ).then((result) => {
         items.value = arrayWrap(result);
       }).catch((error) => {