@ramathibodi/nuxt-commons 4.0.12 → 4.0.14

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

@@ -25,11 +25,39 @@ export declare function useGraphqlModel<T extends GraphqlModelProps>(props: T):
     canCreate: import("vue").ComputedRef<boolean>;
     canUpdate: import("vue").ComputedRef<boolean>;
     canDelete: import("vue").ComputedRef<boolean>;
-    createItem: (item: Record<string, any>, callback?: FormDialogCallback, importing?: boolean) => Promise<void>;
-    importItems: (importItems: Record<string, any>[], callback?: FormDialogCallback) => void;
-    updateItem: (item: Record<string, any>, callback?: FormDialogCallback) => Promise<void>;
+    createItem: (item: Record<string, any>, callback?: FormDialogCallback, importing?: boolean, idempotencySalt?: string | number) => Promise<void>;
+    importItems: (importData: Record<string, any>[], callback?: FormDialogCallback) => void;
+    updateItem: (item: Record<string, any>, callback?: FormDialogCallback, idempotencySalt?: string | number) => Promise<void>;
     deleteItem: (item: Record<string, any>, callback?: FormDialogCallback) => Promise<any>;
     loadItems: (options: any) => Promise<void> | undefined;
     reload: () => Promise<void> | undefined;
     isLoading: import("vue").Ref<boolean, boolean>;
+    importProgress: {
+        isImporting: import("vue").Ref<boolean, boolean>;
+        total: import("vue").Ref<number, number>;
+        processed: import("vue").Ref<number, number>;
+        succeeded: import("vue").Ref<number, number>;
+        failed: import("vue").Ref<number, number>;
+        errors: import("vue").Ref<{
+            index: number;
+            item: any;
+            errorType: import("./importProgress.js").ImportErrorType;
+            message: string;
+            detail?: any;
+        }[], import("./importProgress.js").ImportError[] | {
+            index: number;
+            item: any;
+            errorType: import("./importProgress.js").ImportErrorType;
+            message: string;
+            detail?: any;
+        }[]>;
+        percent: import("vue").ComputedRef<number>;
+        resultVisible: import("vue").Ref<boolean, boolean>;
+        reset: () => void;
+        run: <T_1 = any>(items: T_1[], worker: import("./importProgress.js").ImportWorker<T_1>, options?: {
+            concurrency?: number;
+        }) => Promise<import("./importProgress.js").ImportSummary>;
+        retry: (indices?: number[]) => Promise<import("./importProgress.js").ImportSummary>;
+        dismissResult: () => void;
+    };
 };

package/dist/runtime/composables/graphqlModel.js

@@ -3,7 +3,7 @@ import { watchDebounced } from "@vueuse/core";
 import { useAlert } from "./alert.js";
 import { buildRequiredInputFields } from "./graphqlOperation.js";
 import { useGraphqlModelOperation } from "./graphqlModelOperation.js";
-import pLimit from "p-limit";
+import { useImportProgress } from "./importProgress.js";
 import { arrayWrap } from "../utils/array.js";
 export function useGraphqlModel(props) {
   const alert = useAlert();
@@ -15,6 +15,7 @@ export function useGraphqlModel(props) {
     search.value = keyword;
   }
   const isLoading = ref(false);
+  const importProgress = useImportProgress();
   const { operationCreate, operationUpdate, operationDelete, operationRead, operationReadPageable, operationSearch } = useGraphqlModelOperation(props);
   function keyToField(key) {
     const parts = key.split(".");
@@ -56,43 +57,49 @@ export function useGraphqlModel(props) {
   const canDelete = computed(() => {
     return !!operationDelete.value;
   });
-  function createItem(item, callback, importing = false) {
+  function createItem(item, callback, importing = false, idempotencySalt) {
     isLoading.value = true;
-    return operationCreate.value?.call(fields.value, { input: item }).then((result) => {
+    return operationCreate.value?.call(fields.value, { input: item }, void 0, idempotencySalt != null ? { idempotencySalt } : void 0).then((result) => {
       if (canServerPageable.value) {
         if (!importing) loadItems(currentOptions.value);
       } else items.value.push(result);
       if (callback && callback.setData) callback.setData(result);
     }).catch((error) => {
+      if (importing) throw error;
       alert?.addAlert({ alertType: "error", message: error });
     }).finally(() => {
       if (!importing) isLoading.value = false;
       if (callback) callback.done();
     });
   }
-  function importItems(importItems2, callback) {
+  function importItems(importData, callback) {
+    if (importProgress.isImporting.value) return;
+    if (importData.length === 0) {
+      if (callback) callback.done();
+      return;
+    }
     isLoading.value = true;
-    const limit = pLimit(50);
-    const importPromises = importItems2.map(
-      (item) => limit(
-        () => (item[props.modelKey || "id"] ? operationUpdate.value?.call(fields.value, { input: item }).then((result) => {
-          if (!result) {
-            return createItem(Object.assign({}, props.initialData, item), void 0, true);
-          }
-        }) : createItem(Object.assign({}, props.initialData, item), void 0, true)).catch((error) => {
-          alert?.addAlert({ alertType: "error", message: error });
-        })
-      )
-    );
-    Promise.all(importPromises).finally(() => {
+    const worker = (item, _index, salt) => {
+      const createAsNew = () => createItem(Object.assign({}, props.initialData, item), void 0, true, salt);
+      return item[props.modelKey || "id"] ? operationUpdate.value?.call(fields.value, { input: item }, void 0, salt != null ? { idempotencySalt: salt } : void 0).then((result) => {
+        if (!result) return createAsNew();
+      }) : createAsNew();
+    };
+    importProgress.run(importData, worker, { concurrency: props.importConcurrency }).then(({ succeeded, failed }) => {
+      if (failed > 0) {
+        importProgress.resultVisible.value = true;
+      } else {
+        alert?.addAlert({ alertType: "success", message: `\u0E19\u0E33\u0E40\u0E02\u0E49\u0E32\u0E2A\u0E33\u0E40\u0E23\u0E47\u0E08 ${succeeded} \u0E23\u0E32\u0E22\u0E01\u0E32\u0E23` });
+      }
+    }).finally(() => {
       isLoading.value = false;
       reload();
       if (callback) callback.done();
     });
   }
-  function updateItem(item, callback) {
+  function updateItem(item, callback, idempotencySalt) {
     isLoading.value = true;
-    return operationUpdate.value?.call(fields.value, { input: item }).then((result) => {
+    return operationUpdate.value?.call(fields.value, { input: item }, void 0, idempotencySalt != null ? { idempotencySalt } : void 0).then((result) => {
       if (canServerPageable.value) loadItems(currentOptions.value);
       else {
         const index = items.value.findIndex((item2) => item2[props.modelKey || "id"] === result[props.modelKey || "id"]);
@@ -184,6 +191,7 @@ export function useGraphqlModel(props) {
     deleteItem,
     loadItems,
     reload,
-    isLoading
+    isLoading,
+    importProgress
   };
 }

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

@@ -10,6 +10,7 @@ export interface GraphqlModelConfigProps {
     operationReadPageable?: graphqlOperationObject<any, any> | string;
     operationSearch?: graphqlOperationObject<any, any> | string;
     fields?: Array<string | object>;
+    importConcurrency?: number;
 }
 export declare function useGraphqlModelOperation<T extends GraphqlModelConfigProps>(props: T): {
     operationCreate: import("vue").ComputedRef<graphqlOperationObject<any, any>>;

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

@@ -1,5 +1,6 @@
 import { type ClassConstructor } from '../utils/object.js';
 import type { graphqlTypeObject, graphqlVariable } from '../types/graphqlOperation.js';
+import type { ApiIdempotencyOption } from './api.js';
 export declare function buildFields(operationFields: graphqlTypeObject, fields?: Array<string | Object> | ClassConstructor<any>, depth?: number): Array<string | Object>;
 export declare function buildVariables(outputVariables?: graphqlVariable[], inputVariables?: {
     [p: string]: any;
@@ -7,4 +8,4 @@ export declare function buildVariables(outputVariables?: graphqlVariable[], inpu
 export declare function buildRequiredInputFields(variables: graphqlVariable[] | undefined, inputField?: string): string[];
 export declare function useGraphQlOperation<T>(operationType: string, operation: string, fields?: Array<string | Object> | ClassConstructor<any>, variables?: {
     [p: string]: any;
-}, cache?: boolean | number): Promise<T>;
+}, cache?: boolean | number, options?: ApiIdempotencyOption): Promise<T>;

package/dist/runtime/composables/graphqlOperation.js

@@ -93,7 +93,7 @@ export function buildRequiredInputFields(variables, inputField = "input") {
     return [];
   }
 }
-export function useGraphQlOperation(operationType, operation, fields, variables, cache = false) {
+export function useGraphQlOperation(operationType, operation, fields, variables, cache = false, options) {
   const { graphqlOperation } = useGraphqlBridge();
   return new Promise((resolve, reject) => {
     let rejectReason = void 0;
@@ -107,8 +107,8 @@ export function useGraphQlOperation(operationType, operation, fields, variables,
     }
     if (graphqlOperation[operation]?.fields) {
       fields = buildFields(graphqlOperation[operation]?.fields, fields, 0);
-      if (operationType == "Query") useGraphQl().queryPromise(operation, fields, variables, cache).then((result) => resolve(result)).catch((error) => reject(error));
-      else if (operationType == "Mutation") useGraphQl().mutationPromise(operation, fields, variables).then((result) => resolve(result)).catch((error) => reject(error));
+      if (operationType == "Query") useGraphQl().queryPromise(operation, fields, variables, cache, options).then((result) => resolve(result)).catch((error) => reject(error));
+      else if (operationType == "Mutation") useGraphQl().mutationPromise(operation, fields, variables, options).then((result) => resolve(result)).catch((error) => reject(error));
       else reject("Invalid Operation Type");
     } else {
       reject("No schema of return data available");

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

@@ -0,0 +1,58 @@
+export type ImportErrorType = 'network' | 'timeout' | 'server' | 'unknown';
+export interface ImportError {
+    index: number;
+    item: any;
+    errorType: ImportErrorType;
+    message: string;
+    detail?: any;
+}
+export interface ImportSummary {
+    succeeded: number;
+    failed: number;
+    errors: ImportError[];
+}
+export type ImportWorker<T = any> = (item: T, index: number, salt: string) => Promise<any>;
+/**
+ * classifyImportError buckets a thrown import error into a coarse type and
+ * extracts a short message + raw detail, normalising ofetch FetchError and
+ * Apollo error shapes so callers can separate connection failures from
+ * server-returned errors.
+ */
+export declare function classifyImportError(error: any): {
+    errorType: ImportErrorType;
+    message: string;
+    detail?: any;
+};
+/**
+ * useImportProgress drives a concurrency-limited bulk import while exposing
+ * reactive progress. The runner continues on per-row errors and never rejects;
+ * callers read the resolved summary for the success/failure breakdown.
+ */
+export declare function useImportProgress(): {
+    isImporting: import("vue").Ref<boolean, boolean>;
+    total: import("vue").Ref<number, number>;
+    processed: import("vue").Ref<number, number>;
+    succeeded: import("vue").Ref<number, number>;
+    failed: import("vue").Ref<number, number>;
+    errors: import("vue").Ref<{
+        index: number;
+        item: any;
+        errorType: ImportErrorType;
+        message: string;
+        detail?: any;
+    }[], ImportError[] | {
+        index: number;
+        item: any;
+        errorType: ImportErrorType;
+        message: string;
+        detail?: any;
+    }[]>;
+    percent: import("vue").ComputedRef<number>;
+    resultVisible: import("vue").Ref<boolean, boolean>;
+    reset: () => void;
+    run: <T = any>(items: T[], worker: ImportWorker<T>, options?: {
+        concurrency?: number;
+    }) => Promise<ImportSummary>;
+    retry: (indices?: number[]) => Promise<ImportSummary>;
+    dismissResult: () => void;
+};

package/dist/runtime/composables/importProgress.js

@@ -0,0 +1,130 @@
+import { computed, ref } from "vue";
+import pLimit from "p-limit";
+export function classifyImportError(error) {
+  const isString = typeof error === "string";
+  const rawMessage = error?.message || (isString ? error : String(error));
+  const name = error?.name;
+  const status = error?.status ?? error?.statusCode ?? error?.response?.status;
+  const graphQLErrors = error?.graphQLErrors;
+  const networkError = error?.networkError;
+  if (name === "AbortError" || name === "TimeoutError" || /timeout|timed out|aborted/i.test(rawMessage)) {
+    return { errorType: "timeout", message: rawMessage, detail: error?.data };
+  }
+  if (networkError || /failed to fetch|fetch failed|network ?error|load failed/i.test(rawMessage)) {
+    return { errorType: "network", message: rawMessage, detail: networkError ?? error?.data };
+  }
+  if (status || Array.isArray(graphQLErrors) && graphQLErrors.length > 0 || isString) {
+    const detail = error?.data ?? (graphQLErrors?.length ? graphQLErrors : isString ? error : error?.response?._data);
+    const message = error?.data?.message || graphQLErrors?.[0]?.message || rawMessage || `Server error ${status ?? ""}`.trim();
+    return { errorType: "server", message, detail };
+  }
+  return { errorType: "unknown", message: rawMessage, detail: error?.data };
+}
+let _importRunSeq = 0;
+export function useImportProgress() {
+  const isImporting = ref(false);
+  const total = ref(0);
+  const processed = ref(0);
+  const succeeded = ref(0);
+  const failed = ref(0);
+  const errors = ref([]);
+  const resultVisible = ref(false);
+  let _items = [];
+  let _worker = null;
+  let _concurrency = 3;
+  let _runId = 0;
+  const percent = computed(
+    () => total.value ? Math.round(processed.value / total.value * 100) : 0
+  );
+  function reset() {
+    total.value = 0;
+    processed.value = 0;
+    succeeded.value = 0;
+    failed.value = 0;
+    errors.value = [];
+    resultVisible.value = false;
+  }
+  async function run(items, worker, options = {}) {
+    if (isImporting.value) {
+      return { succeeded: succeeded.value, failed: failed.value, errors: [...errors.value] };
+    }
+    reset();
+    total.value = items.length;
+    isImporting.value = true;
+    _items = items;
+    _worker = worker;
+    _concurrency = options.concurrency && options.concurrency > 0 ? options.concurrency : 3;
+    _runId = ++_importRunSeq;
+    const limit = pLimit(_concurrency);
+    try {
+      await Promise.all(
+        items.map(
+          (item, index) => limit(async () => {
+            try {
+              await worker(item, index, `import:${_runId}:${index}`);
+              succeeded.value++;
+            } catch (error) {
+              const info = classifyImportError(error);
+              console.error("[import] row failed", { index, errorType: info.errorType, item, message: info.message, detail: info.detail });
+              failed.value++;
+              errors.value.push({ index, item, ...info });
+            } finally {
+              processed.value++;
+            }
+          })
+        )
+      );
+    } finally {
+      isImporting.value = false;
+    }
+    return { succeeded: succeeded.value, failed: failed.value, errors: [...errors.value] };
+  }
+  function dismissResult() {
+    resultVisible.value = false;
+  }
+  async function retry(indices) {
+    if (isImporting.value || !_worker) {
+      return { succeeded: succeeded.value, failed: failed.value, errors: [...errors.value] };
+    }
+    const requested = indices && indices.length ? indices : errors.value.map((e) => e.index);
+    const targets = requested.filter((i) => errors.value.some((e) => e.index === i));
+    if (targets.length === 0) {
+      return { succeeded: succeeded.value, failed: failed.value, errors: [...errors.value] };
+    }
+    isImporting.value = true;
+    const limit = pLimit(_concurrency);
+    try {
+      await Promise.all(
+        targets.map(
+          (index) => limit(async () => {
+            const item = _items[index];
+            try {
+              await _worker(item, index, `import:${_runId}:${index}`);
+              const pos = errors.value.findIndex((e) => e.index === index);
+              if (pos !== -1) {
+                errors.value.splice(pos, 1);
+                failed.value = Math.max(0, failed.value - 1);
+                succeeded.value++;
+              }
+            } catch (error) {
+              const info = classifyImportError(error);
+              console.error("[import] row failed", { index, errorType: info.errorType, item, message: info.message, detail: info.detail });
+              const next = { index, item, ...info };
+              const pos = errors.value.findIndex((e) => e.index === index);
+              if (pos !== -1) errors.value[pos] = next;
+              else {
+                errors.value.push(next);
+                failed.value++;
+              }
+            }
+          })
+        )
+      );
+    } finally {
+      processed.value = succeeded.value + failed.value;
+      isImporting.value = false;
+    }
+    return { succeeded: succeeded.value, failed: failed.value, errors: [...errors.value] };
+  }
+  return { isImporting, total, processed, succeeded, failed, errors, percent, resultVisible, reset, run, retry, dismissResult };
+}

package/dist/runtime/types/graphqlOperation.d.ts

@@ -12,7 +12,18 @@ export interface graphqlOperationObject<T, U> {
   fields?: graphqlTypeObject
   operationType: 'Query' | 'Mutation'
   name: string
-  call: (fields?: Array<string | Object>, variables?: U, cache?: boolean | number) => Promise<T>
+  /**
+   * Execute this operation.
+   *
+   * The signature is shared by Query and Mutation operations:
+   * - `cache` applies to **Query** operations only (localStorage TTL / fetch policy).
+   *   It is **ignored for Mutation** operations — mutations are never cached, so a
+   *   value passed here has no effect.
+   * - `options.idempotencySalt` applies to **both** kinds: it is folded into the
+   *   request's `Idempotency-Key` (`SHA-256(<second>|<username>|<body>|<salt>)`).
+   *   Pass `options.idempotent: false` to skip the header for this call.
+   */
+  call: (fields?: Array<string | Object>, variables?: U, cache?: boolean | number, options?: { idempotent?: boolean, idempotencySalt?: string | number }) => Promise<T>
 }
 
 export interface graphqlTypeObject {

package/dist/runtime/utils/virtualize.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pure helpers for the ModelTable/ModelIterator virtualization layer (#246).
+ */
+/**
+ * Decide whether to render rows virtualized.
+ * @param count rendered-row count (items.length)
+ * @param override tri-state `virtual` prop: true/false force, undefined = auto
+ * @param threshold auto-virtualize above this count (default 500)
+ */
+export declare function shouldVirtualize(count: number, override: boolean | undefined, threshold: number | undefined): boolean;
+/**
+ * Cards-per-row for a Vuetify grid column span (out of 12).
+ * span 12 -> 1, 6 -> 2, 4 -> 3, 2 -> 6. Falsy / out-of-range -> 1 (full width).
+ */
+export declare function itemsPerRowForSpan(span: number | string | boolean | undefined): number;

package/dist/runtime/utils/virtualize.js

@@ -0,0 +1,10 @@
+export function shouldVirtualize(count, override, threshold) {
+  if (override === true) return true;
+  if (override === false) return false;
+  return count > (threshold ?? 500);
+}
+export function itemsPerRowForSpan(span) {
+  const n = Number(span);
+  if (!Number.isFinite(n) || n <= 0 || n > 12) return 1;
+  return Math.max(1, Math.floor(12 / n));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ramathibodi/nuxt-commons",
-  "version": "4.0.12",
+  "version": "4.0.14",
   "description": "Ramathibodi Nuxt modules for common components",
   "repository": {
     "type": "git",
@@ -49,6 +49,7 @@
     "dev:build": "nuxt build playground",
     "dev:generate": "nuxt generate playground",
     "playground:scaffold": "node scripts/scaffold-playground-pages.mjs",
+    "template:validate": "node scripts/validate-document-template.mjs",
     "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
     "docs:api:components": "vue-docgen -c docs/vue-docgen.config.cjs && npm run docs:ai:summary && node scripts/enrich-vue-docs-from-ai.mjs",
     "docs:api:composables": "typedoc --options docs/typedoc.json",

package/scripts/validate-document-template.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * Codegen-style validator for Document Template JSON.
+ *
+ * Usage:
+ *   node scripts/validate-document-template.mjs [file|glob ...] [options]
+ *   cat template.json | node scripts/validate-document-template.mjs
+ *
+ * Options:
+ *   --strict   Promote builder-unsafe warnings to errors (exit 1 on them too).
+ *   --json     Emit machine-readable JSON: [{ file, result }].
+ *   --quiet    Print errors only (suppress warnings and infos).
+ *   -h, --help Show this help.
+ *
+ * Exit code: 1 if any input has errors (warnings count as errors under --strict),
+ * otherwise 0.
+ *
+ * Shares the exact validation core used by the `useDocumentTemplate` runtime via
+ * jiti (the TypeScript loader Nuxt already ships), so the CLI and the composable
+ * can never diverge.
+ */
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve, relative } from 'node:path'
+import process from 'node:process'
+import { createJiti } from 'jiti'
+
+const dir = dirname(fileURLToPath(import.meta.url))
+const repoRoot = resolve(dir, '..')
+
+const jiti = createJiti(import.meta.url)
+const { validateDocumentTemplate } = await jiti.import(
+  resolve(repoRoot, 'src/runtime/composables/document/validateTemplate.ts'),
+)
+
+// --- arg parsing -----------------------------------------------------------
+const argv = process.argv.slice(2)
+const flags = new Set(argv.filter(a => a.startsWith('-')))
+const files = argv.filter(a => !a.startsWith('-'))
+
+if (flags.has('-h') || flags.has('--help')) {
+  printHelp()
+  process.exit(0)
+}
+
+const strict = flags.has('--strict')
+const asJson = flags.has('--json')
+const quiet = flags.has('--quiet')
+
+// --- input collection ------------------------------------------------------
+/** @type {{ file: string, content: string }[]} */
+const inputs = []
+
+if (files.length === 0) {
+  const stdin = readFileSync(0, 'utf8')
+  if (!stdin.trim()) {
+    console.error('No input: pass file paths/globs or pipe JSON via stdin.')
+    process.exit(2)
+  }
+  inputs.push({ file: '<stdin>', content: stdin })
+}
+else {
+  const resolved = await expandGlobs(files)
+  if (resolved.length === 0) {
+    console.error(`No files matched: ${files.join(', ')}`)
+    process.exit(2)
+  }
+  for (const f of resolved) {
+    try {
+      inputs.push({ file: f, content: readFileSync(f, 'utf8') })
+    }
+    catch (e) {
+      console.error(`Cannot read ${f}: ${e.message}`)
+      process.exit(2)
+    }
+  }
+}
+
+// --- validation ------------------------------------------------------------
+const results = inputs.map(({ file, content }) => ({
+  file,
+  result: validateDocumentTemplate(content, { strict }),
+}))
+
+const hadErrors = results.some(r => !r.result.valid)
+
+if (asJson) {
+  const rel = f => (f === '<stdin>' ? f : relative(repoRoot, resolve(f)))
+  console.log(JSON.stringify(results.map(r => ({ file: rel(r.file), result: r.result })), null, 2))
+  process.exit(hadErrors ? 1 : 0)
+}
+
+// --- human report ----------------------------------------------------------
+let totalErrors = 0
+let totalWarnings = 0
+let totalInfos = 0
+
+for (const { file, result } of results) {
+  const shown = quiet ? result.errors : result.issues
+  totalErrors += result.errors.length
+  totalWarnings += result.warnings.length
+  totalInfos += result.infos.length
+
+  const status = result.valid ? (result.warnings.length ? 'WARN' : 'OK') : 'FAIL'
+  console.log(`\n${status}  ${file}`)
+  if (shown.length === 0) {
+    if (!quiet) console.log('  no issues')
+    continue
+  }
+  for (const issue of shown) {
+    const tag = issue.severity.toUpperCase().padEnd(7)
+    const loc = issue.path || '(root)'
+    console.log(`  ${tag} ${loc}  ${issue.code}  ${issue.message}`)
+  }
+}
+
+console.log(
+  `\n${results.length} file(s): ${totalErrors} error(s), ${totalWarnings} warning(s), ${totalInfos} info(s)`
+  + (strict ? '  [strict]' : ''),
+)
+
+process.exit(hadErrors ? 1 : 0)
+
+// --- helpers ---------------------------------------------------------------
+async function expandGlobs(patterns) {
+  const out = []
+  for (const p of patterns) {
+    if (/[*?[\]{}]/.test(p)) {
+      try {
+        const { glob } = await import('node:fs/promises')
+        for await (const entry of glob(p)) out.push(entry)
+      }
+      catch {
+        console.error(`Globbing not supported in this Node version for "${p}"; pass explicit file paths.`)
+        process.exit(2)
+      }
+    }
+    else {
+      out.push(p)
+    }
+  }
+  // De-dupe while preserving order.
+  return [...new Set(out)]
+}
+
+function printHelp() {
+  console.log(`Validate Document Template JSON.
+
+Usage:
+  node scripts/validate-document-template.mjs [file|glob ...] [options]
+  cat template.json | node scripts/validate-document-template.mjs
+
+Options:
+  --strict   Promote builder-unsafe warnings to errors.
+  --json     Emit machine-readable JSON.
+  --quiet    Print errors only.
+  -h, --help Show this help.`)
+}

package/templates/.codegen/plugin-schema-object.cjs

@@ -104,19 +104,22 @@ module.exports = {
     return `
         import * as graphQlClass from "~/types/graphql"
         import { useGraphQlOperation } from "#imports";
+        import type { ApiIdempotencyOption } from "#imports";
         import type {
             graphqlInputObject,
             graphqlOperationObject,
             graphqlTypeObject,
             graphqlVariable
           } from "#build/types/graphqlOperation";
-        
+
         export const scalarType = ${JSON.stringify(scalarType)}
-        
-        function operationCall${'<' + 'T,U>'}(operationType:string, operation: string,fields?: ${'Array' + '<string | Object>'},variables?: U,cache: boolean | number = false) {
-            return useGraphQlOperation${'<' + 'T>'}(operationType,operation,fields,variables as {[p: string] : any} | undefined,cache)
+
+        function operationCall${'<' + 'T,U>'}(operationType:string, operation: string,fields?: ${'Array' + '<string | Object>'},variables?: U,cache: boolean | number = false,
+        options?: ApiIdempotencyOption) {
+            return useGraphQlOperation${'<' + 'T>'}(operationType,operation,fields,variables as {[p: string] : any} | undefined,cache,
+            options)
         }
-        
+
         function createGraphQLOperation${'<' + 'T,U>'}(operationType: "Query" | "Mutation",name: string,variables?: graphqlVariable[],fields?: graphqlTypeObject): graphqlOperationObject${'<' + 'T,U>'} {
             let returnGraphqlOperation : ${'Record' + '<string,any>'} = {
                 operationType,
@@ -124,14 +127,8 @@ module.exports = {
                 variables,
                 fields,
             }
-            if (operationType === "Mutation") {
-              returnGraphqlOperation['call'] = async function(fields?: ${'Array' + '<string | Object>'}, variables?: U): Promise${'<' + 'T>'} {
-                  return operationCall(operationType,name, fields, variables);
-              }
-            } else {
-              returnGraphqlOperation['call'] = async function(fields?: ${'Array' + '<string | Object>'}, variables?: U,cache: boolean | number = false): Promise${'<' + 'T>'} {
-                  return operationCall(operationType,name, fields, variables,cache);
-              }
+            returnGraphqlOperation['call'] = async function(fields?: ${'Array' + '<string | Object>'}, variables?: U, cache: boolean | number = false, options?: ApiIdempotencyOption): Promise${'<' + 'T>'} {
+                return operationCall(operationType,name, fields, variables, cache, options);
             }
             return returnGraphqlOperation as graphqlOperationObject${'<' + 'T,U>'}
         }