@anzusystems/common-admin 1.47.0-beta.dev-1790143991 → 2.0.0-rc.1

package/dist/domains/api/composables/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","names":["axios","hasBody","isUndefined","res","isNull","HELPER_OWNED","ownedByHelper","rest","options","key","rendererInstance","renderer","requestedUrl","url","sent","failure","dispatched","built","client","isString","createAbortable","controllers","generation","loading","ref","syncLoading","abortAll","controller","cancelPrevious","relay","external","fn","err"],"sources":["../../../../src/domains/api/composables/request.ts"],"sourcesContent":["import type { AxiosClientFn } from '@/domains/api/utils/client'\nimport axios, { type AxiosInstance, type AxiosRequestConfig } from 'axios'\nimport { isNull, isString, isUndefined } from '@/shared/utils/common'\nimport { ref, type Ref } from 'vue'\n\n/**\n * Whether the response carries a body at all.\n *\n * `''` is not an empty document, it is what axios hands back when no bytes arrived: its adapter\n * returns `responseText`, and `transformResponse` only attempts `JSON.parse` when the string is\n * truthy, so a 204 and a body-less 200 both arrive as `''`. `0` and `false` do parse and are real\n * values -- reading them as absent is the bug this replaces.\n *\n * `null` is treated as absent too. It is distinguishable from `''` at runtime, but nothing can carry\n * it in the type: the response type excludes `null` so that a command site cannot declare itself as\n * returning one.\n */\nexport const hasBody = (res: { data: unknown }): boolean =>\n  !isUndefined(res.data) && !isNull(res.data) && res.data !== ''\n\n/**\n * Strips what the helper decides from whatever the caller passed as `options`.\n *\n * The type says these cannot be set, but a type says nothing at runtime: `data` in particular\n * survived the spread whenever no body was passed, so a caller could put a body on a GET through\n * the back door and skip the serialisation with it.\n */\nconst HELPER_OWNED = ['method', 'url', 'data', 'signal'] as const\n\nexport const ownedByHelper = <T extends object>(options: T): Omit<T, (typeof HELPER_OWNED)[number]> => {\n  const rest = { ...options } as Record<string, unknown>\n  for (const key of HELPER_OWNED) delete rest[key]\n\n  return rest as Omit<T, (typeof HELPER_OWNED)[number]>\n}\n\n/**\n * Renders a config axios kept, and nothing else. It has no `baseURL` and no `params` of its own, so\n * what comes out is what the config carries.\n *\n * Built on first use rather than at module load: importing this library should not create an axios\n * instance. A consumer that mocks axios and counts `create` calls would otherwise see one it never\n * made -- which is exactly how this was found, in a fleet test asserting that its own client is\n * built once.\n */\nlet rendererInstance: AxiosInstance | undefined\nconst renderer = (): AxiosInstance => (rendererInstance ??= axios.create())\n\n/**\n * The url as axios will actually request it: the client's `baseURL` and default `params`, the\n * request's own `params`, and whatever `paramsSerializer` renders them.\n *\n * Built by axios itself rather than approximated: a url recorded before the call is not the one\n * that went out, and an approximation renders arrays, nested objects and dates differently from the\n * wire -- which is worse than no url, because it looks findable and is not. It is handed the same\n * config the request was given, minus what this helper owns, for the same reason: a call carrying\n * its own `paramsSerializer` or `baseURL` is asking for a url that the defaults do not produce.\n *\n * `undefined` in, `undefined` out: a call that failed before it had a url has none to report, and\n * asking axios for one would answer with the client's root -- a url that was never requested and\n * that reads like an endpoint. An empty string is different: that is a call whose url really is the\n * client root, and it gets rendered.\n *\n * Rendered from the config axios actually used whenever there is one: the one it keeps on its own\n * error, or the one it keeps on the response it did return, which covers the failures the helper\n * raises itself after reading that response. Both are the request as it went out -- merged, and past\n * any request interceptor that rewrote the url or the params -- while anything rebuilt here is a\n * reconstruction, and by the time a failure is described the factory may hand back a different\n * instance or its defaults may have moved on.\n *\n * A config that axios kept is rendered through an instance with no defaults of its own, for that\n * same reason: `getUri` merges the instance's defaults *under* the config it is given, so rendering\n * it through the caller's client would let a default added since the request appear in a url that\n * never carried it. The rebuild is the one case that does want those defaults -- there is no record\n * of the request to read them from -- so it goes through the client.\n *\n * Never throws. It runs on every failure path, inside the catch, so an exception here would replace\n * the error the caller is waiting for with one about building a diagnostic string -- and a client\n * without `getUri` (a hand-built stub, a mock) must not turn a mapped failure into a `TypeError`.\n */\nexport const requestedUrl = (\n  client: AxiosClientFn,\n  url: string | undefined,\n  options: AxiosRequestConfig = {},\n  failure?: unknown,\n  dispatched?: AxiosRequestConfig\n): string | undefined => {\n  if (isUndefined(url)) return undefined\n\n  try {\n    const sent = (axios.isAxiosError(failure) ? failure.config : undefined) ?? dispatched\n    const built: unknown = isUndefined(sent)\n      ? client().getUri({ ...ownedByHelper(options), url })\n      : renderer().getUri(sent)\n\n    // A stub can answer with anything. The declared type says string, so it has to be one.\n    return isString(built) ? built : url\n  } catch {\n    return url\n  }\n}\n\nexport type Abortable = {\n  /** Runs one call with a signal of its own, registered so `abort()` can reach it. */\n  run: <T>(fn: (signal: AbortSignal, generation: number) => Promise<T>, external?: AbortSignal) => Promise<T>\n  /** Stops every call this instance still has in flight. */\n  abort: () => void\n  /** The generation a call starts in; a stale one must not write to state the caller can see. */\n  generation: () => number\n  /** Whether this instance has anything in flight. */\n  loading: Ref<boolean>\n}\n\nexport type AbortableOptions = {\n  /**\n   * Each call supersedes the one before it. The abort happens before the new call registers, so\n   * \"the latest wins\" holds by construction rather than by how the two calls happen to interleave.\n   */\n  cancelPrevious?: boolean\n}\n\nexport const createAbortable = (options: AbortableOptions = {}): Abortable => {\n  const { cancelPrevious = false } = options\n  const controllers = new Set<AbortController>()\n  let generation = 0\n\n  /**\n   * True while this instance has a request in flight.\n   *\n   * It is derived from the set rather than counted, which is what makes it safe to turn\n   * `cancelPrevious` on. The pattern everywhere in the fleet is a `loading` ref the caller clears in\n   * a `finally`, and under `cancelPrevious` that `finally` belongs to the call that was just\n   * superseded -- so the spinner goes out while the call the user is waiting for is still running.\n   * Here the superseded call's controller leaves the set at the same moment the new one joins it, so\n   * the value never dips between the two.\n   */\n  const loading = ref(false)\n  const syncLoading = () => {\n    loading.value = controllers.size > 0\n  }\n\n  const abortAll = () => {\n    controllers.forEach((controller) => controller.abort())\n    controllers.clear()\n  }\n\n  const run = async <T>(\n    fn: (signal: AbortSignal, generation: number) => Promise<T>,\n    external?: AbortSignal\n  ): Promise<T> => {\n    // Before the new controller is registered, or the abort would take the new call with it.\n    if (cancelPrevious) abortAll()\n\n    generation += 1\n    const controller = new AbortController()\n    controllers.add(controller)\n    syncLoading()\n\n    // The external signal is relayed rather than passed through: `abort()` has to keep working, and\n    // it can only reach a controller this set owns.\n    const relay = () => controller.abort()\n    if (external) {\n      if (external.aborted) controller.abort()\n      else external.addEventListener('abort', relay, { once: true })\n    }\n\n    try {\n      return await fn(controller.signal, generation)\n    } catch (err: unknown) {\n      // A call can have more than one request under its signal -- the batch sends a page set at\n      // once -- and when one of them fails the rest are work nobody is waiting for any more. Stop\n      // them here, while the controller is still reachable: the `finally` below drops it from the\n      // set, and after that a later `abort()` has nothing to abort them with.\n      controller.abort()\n      throw err\n    } finally {\n      external?.removeEventListener('abort', relay)\n      controllers.delete(controller)\n      syncLoading()\n    }\n  }\n\n  return {\n    run,\n    abort: () => {\n      // Bumped so a call already on its way back cannot write to the caller's state afterwards.\n      generation += 1\n      abortAll()\n      syncLoading()\n    },\n    generation: () => generation,\n    loading,\n  }\n}\n"],"mappings":";;;;AAiBA,IAAaC,KAAW,MACtB,CAACC,EAAYC,EAAI,IAAI,KAAK,CAACC,EAAOD,EAAI,IAAI,KAAKA,EAAI,SAAS,IASxDE,IAAe;CAAC;CAAU;CAAO;CAAQ;AAAQ,GAE1CC,KAAmC,MAAuD;CACrG,IAAMC,IAAO,EAAE,GAAGC,EAAQ;CAC1B,KAAK,IAAMC,KAAOJ,GAAc,OAAOE,EAAKE;CAE5C,OAAOF;AACT,GAWIG,GACEC,UAAiC,MAAqBX,EAAM,OAAO,GAkC5DY,KACX,GACA,GACA,IAA8B,CAAC,GAC/B,GACA,MACuB;CACvB,IAAI,GAAYC,CAAG,GAEnB,IAAI;EACF,IAAMC,KAAQd,EAAM,aAAae,CAAO,IAAIA,EAAQ,SAAS,KAAA,MAAcC,GACrEC,IAAiBf,EAAYY,CAAI,IACnCI,EAAO,CAAC,CAAC,OAAO;GAAE,GAAGZ,EAAcE,CAAO;GAAG;EAAI,CAAC,IAClDG,EAAS,CAAC,CAAC,OAAOG,CAAI;EAG1B,OAAOK,EAASF,CAAK,IAAIA,IAAQJ;CACnC,QAAQ;EACN,OAAOA;CACT;AACF,GAqBaO,KAAmB,IAA4B,CAAC,MAAiB;CAC5E,IAAM,EAAE,oBAAiB,OAAUZ,GAC7Ba,oBAAc,IAAI,IAAqB,GACzCC,IAAa,GAYXC,IAAUC,EAAI,EAAK,GACnBC,UAAoB;EACxB,EAAQ,QAAQJ,EAAY,OAAO;CACrC,GAEMK,UAAiB;EAErB,AADAL,EAAY,SAAS,MAAeM,EAAW,MAAM,CAAC,GACtDN,EAAY,MAAM;CACpB;CAsCA,OAAO;EACL,YApCA,GACA,MACe;GAIf,AAFIO,KAAgBF,EAAS,GAE7B,KAAc;GACd,IAAMC,IAAa,IAAI,gBAAgB;GAEvC,AADAN,EAAY,IAAIM,CAAU,GAC1BF,EAAY;GAIZ,IAAMI,UAAcF,EAAW,MAAM;GACrC,AAAIG,MACEA,EAAS,UAASH,EAAW,MAAM,IAClCG,EAAS,iBAAiB,SAASD,GAAO,EAAE,MAAM,GAAK,CAAC;GAG/D,IAAI;IACF,OAAO,MAAME,EAAGJ,EAAW,QAAQL,CAAU;GAC/C,SAASU,GAAc;IAMrB,MADAL,EAAW,MAAM,GACXK;GACR,UAAU;IAGR,AAFAF,GAAU,oBAAoB,SAASD,CAAK,GAC5CR,EAAY,OAAOM,CAAU,GAC7BF,EAAY;GACd;EACF;EAIE,aAAa;GAIX,AAFA,KAAc,GACdC,EAAS,GACTD,EAAY;EACd;EACA,kBAAkBH;EAClB;CACF;AACF"}

package/dist/domains/api/composables/useApiFetchByIds.d.ts

@@ -0,0 +1,57 @@
+import { UrlParams } from '../utils/apiHelper';
+import { AxiosRequestConfig } from 'axios';
+import { DocId, IntegerId } from '../../../shared/types/common';
+import { Ref } from 'vue';
+import { AxiosClientFn } from '../utils/client';
+export type UseApiFetchByIdsParams = {
+    client: AxiosClientFn;
+    system: string;
+    entity: string;
+    /** i18n scope for field-level validation failures; defaults to `system` / `entity`. */
+    validationSystem?: string;
+    validationEntity?: string;
+    urlTemplate?: string;
+    urlParams?: UrlParams;
+    /** Anything axios takes except what this helper decides: the method, the url, the body and the signal. */
+    options?: Omit<AxiosRequestConfig, 'method' | 'url' | 'data' | 'signal'>;
+    isSearchApi?: boolean;
+    field?: string;
+    cancelPrevious?: boolean;
+};
+export type FetchByIdsParams = {
+    urlTemplate?: string;
+    urlParams?: UrlParams;
+    /** Stops this one call, leaving the instance's other calls alone. */
+    signal?: AbortSignal;
+};
+/**
+ * Ids per request. A cache drains everything queued in one go, and a thousand ids in a query string is
+ * past the 8 KB request line a proxy takes by default -- the request would come back 414.
+ */
+export declare const FETCH_BY_IDS_BATCH_SIZE = 100;
+export declare const useApiFetchByIds: <T>(params: UseApiFetchByIdsParams) => UseApiFetchByIdsReturnType<T>;
+export type UseApiFetchByIdsReturnType<T> = {
+    execute: (ids: DocId[] | IntegerId[], params?: FetchByIdsParams) => Promise<T[]>;
+    abort: () => void;
+    /**
+     * True while this instance has a request in flight, false once the last one settles.
+     *
+     * It is here so a caller does not have to keep its own: the hand-rolled version is a ref cleared in
+     * a `finally`, and that `finally` belongs to whichever call ended -- including one that
+     * `cancelPrevious` just superseded, which turns the spinner off while the call the user is waiting
+     * for is still running. This one never dips between a superseded call and the one that replaced it.
+     *
+     * Two things to know before replacing a hand-rolled flag with it.
+     *
+     * It covers what this helper does and nothing the caller does afterwards. A flag that also spans a
+     * follow-up cached fetch, a mapping pass or a second endpoint is not the same flag, and swapping it
+     * for this one turns the spinner off too early. Keep your own where it means more than "this helper
+     * is working".
+     *
+     * It belongs to the instance, so it is only reachable if you hold the instance. A factory that
+     * builds one per call and hands back the promise alone -- `const { execute } = useX()` inside the
+     * function that calls it -- cannot expose `loading`, `abort` or `cancelPrevious` at all. Hoist the
+     * instance to where the caller lives first.
+     */
+    loading: Ref<boolean>;
+};

package/dist/domains/api/composables/useApiFetchByIds.js

@@ -0,0 +1,61 @@
+import { isDefined as e, isUndefined as t } from "../../../shared/utils/common.js";
+import { AnzuFatalError as n } from "../../../shared/error/AnzuFatalError.js";
+import "../../../shared/statusCodes.js";
+import { AnzuApiResponseCodeError as r } from "../../../shared/error/AnzuApiResponseCodeError.js";
+import { replaceUrlParameters as i } from "../utils/apiHelper.js";
+import { isValidHTTPStatus as a } from "../utils/response.js";
+import { mapApiError as o, report as s } from "../utils/apiErrors.js";
+import { createAbortable as c, hasBody as l, ownedByHelper as u, requestedUrl as d } from "./request.js";
+import { readListBody as f } from "../utils/listBody.js";
+import { useApiQueryBuilder as p } from "./useApiQueryBuilder.js";
+var m = (e, t, n = "id") => {
+	let { querySetLimit: r, querySetOffset: i, querySetOrder: a, queryBuild: o, queryAddFilter: s, queryAdd: c } = p(), l = e.length;
+	return r(l), i(1, l), a(n, !1), t ? c(n, e.join(",")) : s("in", n, e.join(",")), o();
+}, h = (p) => {
+	let { client: h, system: g, entity: _, validationSystem: v, validationEntity: y, urlTemplate: b, urlParams: x, options: S = {}, isSearchApi: C = !1, field: w = "id", cancelPrevious: T = !1 } = p, E = c({ cancelPrevious: T }), D = async (c, p) => {
+		let { urlTemplate: T, urlParams: D, signal: O } = p, k, A;
+		try {
+			let o = await E.run((r) => {
+				let a = e(T) ? T : b;
+				if (t(a)) throw new n(void 0, "Url template is undefined");
+				let o = e(D) ? D : x, s = (t(o) ? a : i(a, o)) + m(c, C, w), l = h();
+				return k = s, l.get(s, {
+					...u(S),
+					signal: r
+				});
+			}, O);
+			A = o.config;
+			let s = () => d(h, k, S, void 0, A);
+			if (!a(o.status)) throw new r(o.status);
+			if (o.status === 204) return [];
+			if (!l(o)) throw new r(o.status, void 0, "Expected a response body, url: " + s());
+			return f(o.data, o.status, s()).items;
+		} catch (e) {
+			let t = {
+				system: g,
+				entity: _,
+				validationSystem: v,
+				validationEntity: y,
+				url: d(h, k, S, e, A)
+			};
+			throw s(o(e, t), t);
+		}
+	};
+	return {
+		execute: async (e, t = {}) => {
+			if (e.length <= 100) return D(e, t);
+			let n = [];
+			for (let r = 0; r < e.length; r += 100) {
+				let i = e.slice(r, r + 100);
+				n.push(...await D(i, t));
+			}
+			return n;
+		},
+		abort: E.abort,
+		loading: E.loading
+	};
+};
+//#endregion
+export { h as useApiFetchByIds };
+
+//# sourceMappingURL=useApiFetchByIds.js.map

package/dist/domains/api/composables/useApiFetchByIds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useApiFetchByIds.js","names":["generateByIdsApiQuery","useApiQueryBuilder","limit","ids","querySetLimit","querySetOffset","querySetOrder","field","isSearchApi","queryAdd","queryAddFilter","queryBuild","useApiFetchByIds","params","abortable","createAbortable","executeBatch","urlTemplateOverride","urlParamsOverride","fetchParams","url","dispatched","res","template","isDefined","urlTemplate","isUndefined","AnzuFatalError","resolvedParams","urlParams","requestUrl","replaceUrlParameters","instance","client","ownedByHelper","options","abortSignal","signal","asSent","requestedUrl","isValidHTTPStatus","AnzuApiResponseCodeError","hasBody","readListBody","err","context","report","mapApiError","items","start","batch"],"sources":["../../../../src/domains/api/composables/useApiFetchByIds.ts"],"sourcesContent":["import { AnzuFatalError } from '@/shared/error/AnzuFatalError'\nimport { AnzuApiResponseCodeError } from '@/shared/error/AnzuApiResponseCodeError'\nimport { replaceUrlParameters, type UrlParams } from '@/domains/api/utils/apiHelper'\nimport { isValidHTTPStatus } from '@/domains/api/utils/response'\nimport type { AxiosRequestConfig } from 'axios'\nimport { HTTP_STATUS_NO_CONTENT } from '@/shared/statusCodes'\nimport type { DocId, IntegerId } from '@/shared/types/common'\nimport { isDefined, isUndefined } from '@/shared/utils/common'\nimport type { Ref } from 'vue'\nimport type { AxiosClientFn } from '@/domains/api/utils/client'\nimport { useApiQueryBuilder } from '@/domains/api/composables/useApiQueryBuilder'\nimport { mapApiError, report } from '@/domains/api/utils/apiErrors'\nimport { createAbortable, hasBody, ownedByHelper, requestedUrl } from '@/domains/api/composables/request'\nimport { readListBody } from '@/domains/api/utils/listBody'\n\nexport type UseApiFetchByIdsParams = {\n  client: AxiosClientFn\n  system: string\n  entity: string\n  /** i18n scope for field-level validation failures; defaults to `system` / `entity`. */\n  validationSystem?: string\n  validationEntity?: string\n  urlTemplate?: string\n  urlParams?: UrlParams\n  /** Anything axios takes except what this helper decides: the method, the url, the body and the signal. */\n  options?: Omit<AxiosRequestConfig, 'method' | 'url' | 'data' | 'signal'>\n  isSearchApi?: boolean\n  field?: string\n  cancelPrevious?: boolean\n}\n\nexport type FetchByIdsParams = {\n  urlTemplate?: string\n  urlParams?: UrlParams\n  /** Stops this one call, leaving the instance's other calls alone. */\n  signal?: AbortSignal\n}\n\n/**\n * Ids per request. A cache drains everything queued in one go, and a thousand ids in a query string is\n * past the 8 KB request line a proxy takes by default -- the request would come back 414.\n */\nexport const FETCH_BY_IDS_BATCH_SIZE = 100\n\n/** The `filter_in` query that fetches exactly the ids asked for, in one request. */\nconst generateByIdsApiQuery = (ids: IntegerId[] | DocId[], isSearchApi: boolean, field = 'id'): string => {\n  const { querySetLimit, querySetOffset, querySetOrder, queryBuild, queryAddFilter, queryAdd } = useApiQueryBuilder()\n  const limit = ids.length\n  querySetLimit(limit)\n  querySetOffset(1, limit)\n  querySetOrder(field, false)\n  if (isSearchApi) queryAdd(field, ids.join(','))\n  else queryAddFilter('in', field, ids.join(','))\n\n  return queryBuild()\n}\n\nexport const useApiFetchByIds = <T>(params: UseApiFetchByIdsParams): UseApiFetchByIdsReturnType<T> => {\n  const {\n    client,\n    system,\n    entity,\n    validationSystem,\n    validationEntity,\n    urlTemplate,\n    urlParams,\n    options = {},\n    isSearchApi = false,\n    field = 'id',\n    cancelPrevious = false,\n  } = params\n  const abortable = createAbortable({ cancelPrevious })\n\n  const executeBatch = async (ids: DocId[] | IntegerId[], fetchParams: FetchByIdsParams): Promise<T[]> => {\n    const { urlTemplate: urlTemplateOverride, urlParams: urlParamsOverride, signal } = fetchParams\n\n    // Assigned inside `run`, once, at the moment there is a url to ask for; undefined until then,\n    // which is what a failure before dispatch honestly reports.\n    let url: string | undefined\n    // The config axios used, kept for the failures this helper raises after reading the response:\n    // they carry no config of their own, and rebuilding one describes the request as the client\n    // would send it now rather than as it was sent.\n    let dispatched: AxiosRequestConfig | undefined\n\n    try {\n      const res = await abortable.run((abortSignal) => {\n        // Derived inside `run`, the way the list does it: `run` opens the generation and, with\n        // `cancelPrevious`, stops the call before this one, so work done ahead of it would let a\n        // call that never dispatches leave its predecessor running. Inside the try as well, so a\n        // caller that forgot the template gets the same error class as every other failure rather\n        // than a bare `Error`.\n        const template = isDefined(urlTemplateOverride) ? urlTemplateOverride : urlTemplate\n        if (isUndefined(template)) throw new AnzuFatalError(undefined, 'Url template is undefined')\n\n        const resolvedParams = isDefined(urlParamsOverride) ? urlParamsOverride : urlParams\n        const baseUrl = isUndefined(resolvedParams) ? template : replaceUrlParameters(template, resolvedParams)\n        const requestUrl = baseUrl + generateByIdsApiQuery(ids, isSearchApi, field)\n        const instance = client()\n\n        // Recorded last, when nothing between here and the call can throw any more: a client factory\n        // that fails is a request that never happened, and the report says so by naming no url.\n        url = requestUrl\n\n        return instance.get(requestUrl, { ...ownedByHelper(options), signal: abortSignal })\n      }, signal)\n\n      dispatched = res.config\n      // The url the report will name, so a message and the context beside it cannot disagree about\n      // which request failed when an interceptor rewrote it on the way out.\n      const asSent = () => requestedUrl(client, url, options, undefined, dispatched)\n      if (!isValidHTTPStatus(res.status)) throw new AnzuApiResponseCodeError(res.status)\n\n      // Nothing matched the ids -- an empty answer, not a broken one.\n      if (res.status === HTTP_STATUS_NO_CONTENT) return []\n\n      if (!hasBody(res)) {\n        throw new AnzuApiResponseCodeError(res.status, undefined, 'Expected a response body, url: ' + asSent())\n      }\n\n      return readListBody<T>(res.data, res.status, asSent()).items\n    } catch (err: unknown) {\n      // Built once and handed to both, the way the batch does it: half the work on the failure path,\n      // and one place that could go wrong instead of two.\n      const context = {\n        system,\n        entity,\n        validationSystem,\n        validationEntity,\n        url: requestedUrl(client, url, options, err, dispatched),\n      }\n\n      throw report(mapApiError(err, context), context)\n    }\n  }\n\n  // One batch after another, not side by side: with `cancelPrevious` each batch would stop the one\n  // before it. A failed batch fails the call, as a single request would.\n  const execute = async (ids: DocId[] | IntegerId[], fetchParams: FetchByIdsParams = {}): Promise<T[]> => {\n    if (ids.length <= FETCH_BY_IDS_BATCH_SIZE) return executeBatch(ids, fetchParams)\n    const items: T[] = []\n    for (let start = 0; start < ids.length; start += FETCH_BY_IDS_BATCH_SIZE) {\n      const batch = ids.slice(start, start + FETCH_BY_IDS_BATCH_SIZE) as DocId[] | IntegerId[]\n      items.push(...(await executeBatch(batch, fetchParams)))\n    }\n    return items\n  }\n\n  return { execute, abort: abortable.abort, loading: abortable.loading }\n}\n\nexport type UseApiFetchByIdsReturnType<T> = {\n  execute: (ids: DocId[] | IntegerId[], params?: FetchByIdsParams) => Promise<T[]>\n  abort: () => void\n  /**\n   * True while this instance has a request in flight, false once the last one settles.\n   *\n   * It is here so a caller does not have to keep its own: the hand-rolled version is a ref cleared in\n   * a `finally`, and that `finally` belongs to whichever call ended -- including one that\n   * `cancelPrevious` just superseded, which turns the spinner off while the call the user is waiting\n   * for is still running. This one never dips between a superseded call and the one that replaced it.\n   *\n   * Two things to know before replacing a hand-rolled flag with it.\n   *\n   * It covers what this helper does and nothing the caller does afterwards. A flag that also spans a\n   * follow-up cached fetch, a mapping pass or a second endpoint is not the same flag, and swapping it\n   * for this one turns the spinner off too early. Keep your own where it means more than \"this helper\n   * is working\".\n   *\n   * It belongs to the instance, so it is only reachable if you hold the instance. A factory that\n   * builds one per call and hands back the promise alone -- `const { execute } = useX()` inside the\n   * function that calls it -- cannot expose `loading`, `abort` or `cancelPrevious` at all. Hoist the\n   * instance to where the caller lives first.\n   */\n  loading: Ref<boolean>\n}\n"],"mappings":";;;;;;;;;;AA6CA,IAAMA,KAAyB,GAA4B,GAAsB,IAAQ,SAAiB;CACxG,IAAM,EAAE,kBAAe,mBAAgB,kBAAe,eAAY,mBAAgB,gBAAaC,EAAmB,GAC5GC,IAAQC,EAAI;CAOlB,OANAC,EAAcF,CAAK,GACnBG,EAAe,GAAGH,CAAK,GACvBI,EAAcC,GAAO,EAAK,GACtBC,IAAaC,EAASF,GAAOJ,EAAI,KAAK,GAAG,CAAC,IACzCO,EAAe,MAAMH,GAAOJ,EAAI,KAAK,GAAG,CAAC,GAEvCQ,EAAW;AACpB,GAEaC,KAAuB,MAAkE;CACpG,IAAM,EACJ,WACA,WACA,WACA,qBACA,qBACA,gBACA,cACA,aAAU,CAAC,GACX,iBAAc,IACd,WAAQ,MACR,oBAAiB,OACfC,GACEC,IAAYC,EAAgB,EAAE,kBAAe,CAAC,GAE9CC,IAAe,OAAO,GAA4B,MAAgD;EACtG,IAAM,EAAE,aAAaC,GAAqB,WAAWC,GAAmB,cAAWC,GAI/EC,GAIAC;EAEJ,IAAI;GACF,IAAMC,IAAM,MAAMR,EAAU,KAAK,MAAgB;IAM/C,IAAMS,IAAWC,EAAUP,CAAmB,IAAIA,IAAsBQ;IACxE,IAAIC,EAAYH,CAAQ,GAAG,MAAM,IAAII,EAAe,KAAA,GAAW,2BAA2B;IAE1F,IAAMC,IAAiBJ,EAAUN,CAAiB,IAAIA,IAAoBW,GAEpEC,KADUJ,EAAYE,CAAc,IAAIL,IAAWQ,EAAqBR,GAAUK,CAAc,KACzE5B,EAAsBG,GAAKK,GAAaD,CAAK,GACpEyB,IAAWC,EAAO;IAMxB,OAFA,IAAMH,GAECE,EAAS,IAAIF,GAAY;KAAE,GAAGI,EAAcC,CAAO;KAAG,QAAQC;IAAY,CAAC;GACpF,GAAGC,CAAM;GAET,IAAaf,EAAI;GAGjB,IAAMgB,UAAeC,EAAaN,GAAQb,GAAKe,GAAS,KAAA,GAAWd,CAAU;GAC7E,IAAI,CAACmB,EAAkBlB,EAAI,MAAM,GAAG,MAAM,IAAImB,EAAyBnB,EAAI,MAAM;GAGjF,IAAIA,EAAI,WAAA,KAAmC,OAAO,CAAC;GAEnD,IAAI,CAACoB,EAAQpB,CAAG,GACd,MAAM,IAAImB,EAAyBnB,EAAI,QAAQ,KAAA,GAAW,oCAAoCgB,EAAO,CAAC;GAGxG,OAAOK,EAAgBrB,EAAI,MAAMA,EAAI,QAAQgB,EAAO,CAAC,CAAC,CAAC;EACzD,SAASM,GAAc;GAGrB,IAAMC,IAAU;IACd;IACA;IACA;IACA;IACA,KAAKN,EAAaN,GAAQb,GAAKe,GAASS,GAAKvB,CAAU;GACzD;GAEA,MAAMyB,EAAOC,EAAYH,GAAKC,CAAO,GAAGA,CAAO;EACjD;CACF;CAcA,OAAO;EAAE,gBAVc,GAA4B,IAAgC,CAAC,MAAoB;GACtG,IAAI1C,EAAI,UAAA,KAAmC,OAAOa,EAAab,GAAKgB,CAAW;GAC/E,IAAM6B,IAAa,CAAC;GACpB,KAAK,IAAIC,IAAQ,GAAGA,IAAQ9C,EAAI,QAAQ,KAAA,KAAkC;IACxE,IAAM+C,IAAQ/C,EAAI,MAAM8C,GAAOA,IAAA,GAA+B;IAC9D,EAAM,KAAK,GAAI,MAAMjC,EAAakC,GAAO/B,CAAW,CAAE;GACxD;GACA,OAAO6B;EACT;EAEkB,OAAOlC,EAAU;EAAO,SAASA,EAAU;CAAQ;AACvE"}

package/dist/domains/api/composables/useApiFetchItems.d.ts

@@ -0,0 +1,101 @@
+import { UrlParams } from '../utils/apiHelper';
+import { AxiosRequestConfig } from 'axios';
+import { Ref } from 'vue';
+import { AxiosClientFn } from '../utils/client';
+/** Which of the two shapes a list arrives in. */
+export type ItemsShape = 'envelope' | 'array';
+export type UseApiFetchItemsParams = {
+    client: AxiosClientFn;
+    system: string;
+    entity: string;
+    /** i18n scope for field-level validation failures; defaults to `system` / `entity`. */
+    validationSystem?: string;
+    validationEntity?: string;
+    /**
+     * The url, query and all: whatever built the query has already run by the time it gets here.
+     *
+     * `urlParams` are substituted into the PATH only -- `/article/:id/routes?locale=:locale` fills in
+     * `:id` and sends `:locale` as it stands. This is the helper written for hand-made queries, so it
+     * is the one place someone would reach for a placeholder in the query; put the value in the query
+     * when building it, or pass it through `options.params` and let axios serialise it.
+     */
+    urlTemplate?: string;
+    urlParams?: UrlParams;
+    /** Anything axios takes except what this helper decides: the method, the url, the body and the signal. */
+    options?: Omit<AxiosRequestConfig, 'method' | 'url' | 'data' | 'signal'>;
+    cancelPrevious?: boolean;
+    /**
+     * Default `GET`, which is what 17 of the fleet's list reads and every existing caller here use.
+     *
+     * The others are here because a list is not only ever the answer to a read: a filter too big for a
+     * url goes out as a POST, and a mutation can answer with the list it just changed -- a swap, a
+     * shift, an upsert-all. What this helper is about is the answer, not the verb.
+     */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH';
+    /**
+     * Default `'envelope'`, because that is the fleet's norm and the exception is what gets declared.
+     *
+     * Leaving it out cannot go wrong quietly: the reader refuses the shape that was not declared, so a
+     * forgotten `'array'` fails on the first run rather than handing back something that is not a list.
+     */
+    shape?: ItemsShape;
+};
+export type FetchItemsParams<B = never> = {
+    urlTemplate?: string;
+    urlParams?: UrlParams;
+    /** `null` omits the body, as everywhere in this family. */
+    body?: B;
+    /** Stops this one call, leaving the instance's other calls alone. */
+    signal?: AbortSignal;
+};
+/**
+ * A list from an endpoint the caller has already written the query for, with no pagination.
+ *
+ * It exists because the fleet kept doing this through `useApiRequest<ApiResponseList<T[]>>`: build a
+ * query by hand -- an order, a limit, a fixed filter -- bake it into the url, and read `.data` off
+ * the envelope that comes back. That is a list fetch with the list part missing: nothing checks that
+ * `data` is an array, so a malformed answer still hands back `undefined` typed as `T[]`, which is
+ * the bug this whole family was built to end.
+ *
+ * `useApiFetchList` cannot serve them: it asks for a pagination ref, a `filterData` and a
+ * `filterConfig`, and these calls have none -- their filters are decided at the call site and are
+ * not the user's to change. So this is that helper with the pagination taken out: same core, same
+ * error mapping, same list-body check, and it answers with the items rather than the envelope.
+ *
+ * Read is the usual case, not the only one: a filter too big for a url goes out as a POST, and a
+ * mutation can answer with the list it just changed. The helper is about what comes back.
+ *
+ * Which shape it comes back in is declared, not guessed. `shape` picks the reader and the reader
+ * refuses the other shape, the way `optionalBody` makes a caller declare a body instead of leaving
+ * the helper to accept whatever turns up. A wrong declaration therefore fails loudly on the first
+ * run, which is what makes having a default safe at all.
+ *
+ * It writes no metadata. An endpoint whose paging the user drives is `useApiFetchList`; a list read
+ * page by page to the end is `useApiFetchListBatch`.
+ */
+export declare const useApiFetchItems: <T, B = never>(params: UseApiFetchItemsParams) => UseApiFetchItemsReturnType<T, B>;
+export type UseApiFetchItemsReturnType<T, B = never> = {
+    execute: (params?: FetchItemsParams<B>) => Promise<T[]>;
+    abort: () => void;
+    /**
+     * True while this instance has a request in flight, false once the last one settles.
+     *
+     * It is here so a caller does not have to keep its own: the hand-rolled version is a ref cleared in
+     * a `finally`, and that `finally` belongs to whichever call ended -- including one that
+     * `cancelPrevious` just superseded, which turns the spinner off while the call the user is waiting
+     * for is still running. This one never dips between a superseded call and the one that replaced it.
+     *
+     * Two things to know before replacing a hand-rolled flag with it.
+     *
+     * It covers what this helper does and nothing the caller does afterwards. A flag that also spans a
+     * follow-up cached fetch, a mapping pass or a second endpoint is not the same flag, and swapping it
+     * for this one turns the spinner off too early. Keep your own where it means more than "this helper
+     * is working".
+     *
+     * It belongs to the instance, so it is only reachable if you hold the instance. A factory that
+     * builds one per call and hands back the promise alone -- `const { execute } = useX()` inside the
+     * function that calls it -- cannot expose `loading`, `abort` or `cancelPrevious` at all. Hoist the
+     * instance to where the caller lives first.
+     */
+    loading: Ref<boolean>;
+};

package/dist/domains/api/composables/useApiFetchItems.js

@@ -0,0 +1,56 @@
+import { isDefined as e, isNull as t, isUndefined as n } from "../../../shared/utils/common.js";
+import { AnzuFatalError as r } from "../../../shared/error/AnzuFatalError.js";
+import "../../../shared/statusCodes.js";
+import { AnzuApiResponseCodeError as i } from "../../../shared/error/AnzuApiResponseCodeError.js";
+import { replaceUrlParameters as a } from "../utils/apiHelper.js";
+import { isValidHTTPStatus as o } from "../utils/response.js";
+import { mapApiError as s, report as c } from "../utils/apiErrors.js";
+import { createAbortable as l, hasBody as u, ownedByHelper as d, requestedUrl as f } from "./request.js";
+import { readArrayBody as p, readListBody as m } from "../utils/listBody.js";
+//#region src/domains/api/composables/useApiFetchItems.ts
+var h = (h) => {
+	let { client: g, system: _, entity: v, validationSystem: y, validationEntity: b, urlTemplate: x, urlParams: S, options: C = {}, cancelPrevious: w = !1, method: T = "GET", shape: E = "envelope" } = h, D = l({ cancelPrevious: w });
+	return {
+		execute: async (l = {}) => {
+			let { urlTemplate: h, urlParams: w, body: O, signal: k } = l, A, j;
+			try {
+				let s = await D.run((i) => {
+					let o = e(h) ? h : x;
+					if (n(o)) throw new r(void 0, "Url template is undefined");
+					let s = !t(O) && !n(O);
+					if (T === "GET" && s) throw new r(void 0, "A GET request does not carry a body -- set method, or pass the value through options.params");
+					let c = e(w) ? w : S, l = n(c) ? o : a(o, c), u = {
+						...d(C),
+						method: T,
+						url: l,
+						signal: i
+					};
+					s && (u.data = JSON.stringify(O));
+					let f = g();
+					return A = l, f.request(u);
+				}, k);
+				j = s.config;
+				let c = () => f(g, A, C, void 0, j);
+				if (!o(s.status)) throw new i(s.status);
+				if (s.status === 204) return [];
+				if (!u(s)) throw new i(s.status, void 0, "Expected a response body, url: " + c());
+				return E === "array" ? p(s.data, s.status, c()) : m(s.data, s.status, c()).items;
+			} catch (e) {
+				let t = {
+					system: _,
+					entity: v,
+					validationSystem: y,
+					validationEntity: b,
+					url: f(g, A, C, e, j)
+				};
+				throw c(s(e, t), t);
+			}
+		},
+		abort: D.abort,
+		loading: D.loading
+	};
+};
+//#endregion
+export { h as useApiFetchItems };
+
+//# sourceMappingURL=useApiFetchItems.js.map

package/dist/domains/api/composables/useApiFetchItems.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useApiFetchItems.js","names":["useApiFetchItems","params","abortable","createAbortable","urlTemplateOverride","urlParamsOverride","fetchParams","url","dispatched","res","template","isDefined","urlTemplate","isUndefined","AnzuFatalError","sendsBody","isNull","body","method","resolvedParams","urlParams","requestUrl","replaceUrlParameters","config","ownedByHelper","options","abortSignal","instance","client","signal","asSent","requestedUrl","isValidHTTPStatus","AnzuApiResponseCodeError","hasBody","shape","readArrayBody","readListBody","err","context","report","mapApiError"],"sources":["../../../../src/domains/api/composables/useApiFetchItems.ts"],"sourcesContent":["import { AnzuFatalError } from '@/shared/error/AnzuFatalError'\nimport { AnzuApiResponseCodeError } from '@/shared/error/AnzuApiResponseCodeError'\nimport { replaceUrlParameters, type UrlParams } from '@/domains/api/utils/apiHelper'\nimport { isValidHTTPStatus } from '@/domains/api/utils/response'\nimport type { AxiosRequestConfig } from 'axios'\nimport { HTTP_STATUS_NO_CONTENT } from '@/shared/statusCodes'\nimport { isDefined, isNull, isUndefined } from '@/shared/utils/common'\nimport type { Ref } from 'vue'\nimport type { AxiosClientFn } from '@/domains/api/utils/client'\nimport { mapApiError, report } from '@/domains/api/utils/apiErrors'\nimport { createAbortable, hasBody, ownedByHelper, requestedUrl } from '@/domains/api/composables/request'\nimport { readArrayBody, readListBody } from '@/domains/api/utils/listBody'\n\n/** Which of the two shapes a list arrives in. */\nexport type ItemsShape = 'envelope' | 'array'\n\nexport type UseApiFetchItemsParams = {\n  client: AxiosClientFn\n  system: string\n  entity: string\n  /** i18n scope for field-level validation failures; defaults to `system` / `entity`. */\n  validationSystem?: string\n  validationEntity?: string\n  /**\n   * The url, query and all: whatever built the query has already run by the time it gets here.\n   *\n   * `urlParams` are substituted into the PATH only -- `/article/:id/routes?locale=:locale` fills in\n   * `:id` and sends `:locale` as it stands. This is the helper written for hand-made queries, so it\n   * is the one place someone would reach for a placeholder in the query; put the value in the query\n   * when building it, or pass it through `options.params` and let axios serialise it.\n   */\n  urlTemplate?: string\n  urlParams?: UrlParams\n  /** Anything axios takes except what this helper decides: the method, the url, the body and the signal. */\n  options?: Omit<AxiosRequestConfig, 'method' | 'url' | 'data' | 'signal'>\n  cancelPrevious?: boolean\n  /**\n   * Default `GET`, which is what 17 of the fleet's list reads and every existing caller here use.\n   *\n   * The others are here because a list is not only ever the answer to a read: a filter too big for a\n   * url goes out as a POST, and a mutation can answer with the list it just changed -- a swap, a\n   * shift, an upsert-all. What this helper is about is the answer, not the verb.\n   */\n  method?: 'GET' | 'POST' | 'PUT' | 'PATCH'\n  /**\n   * Default `'envelope'`, because that is the fleet's norm and the exception is what gets declared.\n   *\n   * Leaving it out cannot go wrong quietly: the reader refuses the shape that was not declared, so a\n   * forgotten `'array'` fails on the first run rather than handing back something that is not a list.\n   */\n  shape?: ItemsShape\n}\n\nexport type FetchItemsParams<B = never> = {\n  urlTemplate?: string\n  urlParams?: UrlParams\n  /** `null` omits the body, as everywhere in this family. */\n  body?: B\n  /** Stops this one call, leaving the instance's other calls alone. */\n  signal?: AbortSignal\n}\n\n/**\n * A list from an endpoint the caller has already written the query for, with no pagination.\n *\n * It exists because the fleet kept doing this through `useApiRequest<ApiResponseList<T[]>>`: build a\n * query by hand -- an order, a limit, a fixed filter -- bake it into the url, and read `.data` off\n * the envelope that comes back. That is a list fetch with the list part missing: nothing checks that\n * `data` is an array, so a malformed answer still hands back `undefined` typed as `T[]`, which is\n * the bug this whole family was built to end.\n *\n * `useApiFetchList` cannot serve them: it asks for a pagination ref, a `filterData` and a\n * `filterConfig`, and these calls have none -- their filters are decided at the call site and are\n * not the user's to change. So this is that helper with the pagination taken out: same core, same\n * error mapping, same list-body check, and it answers with the items rather than the envelope.\n *\n * Read is the usual case, not the only one: a filter too big for a url goes out as a POST, and a\n * mutation can answer with the list it just changed. The helper is about what comes back.\n *\n * Which shape it comes back in is declared, not guessed. `shape` picks the reader and the reader\n * refuses the other shape, the way `optionalBody` makes a caller declare a body instead of leaving\n * the helper to accept whatever turns up. A wrong declaration therefore fails loudly on the first\n * run, which is what makes having a default safe at all.\n *\n * It writes no metadata. An endpoint whose paging the user drives is `useApiFetchList`; a list read\n * page by page to the end is `useApiFetchListBatch`.\n */\nexport const useApiFetchItems = <T, B = never>(params: UseApiFetchItemsParams): UseApiFetchItemsReturnType<T, B> => {\n  const {\n    client,\n    system,\n    entity,\n    validationSystem,\n    validationEntity,\n    urlTemplate,\n    urlParams,\n    options = {},\n    cancelPrevious = false,\n    method = 'GET',\n    shape = 'envelope',\n  } = params\n  const abortable = createAbortable({ cancelPrevious })\n\n  const execute = async (fetchParams: FetchItemsParams<B> = {}): Promise<T[]> => {\n    const { urlTemplate: urlTemplateOverride, urlParams: urlParamsOverride, body, signal } = fetchParams\n\n    // Assigned inside `run`, at the moment there is a url to ask for; undefined until then, which is\n    // what a failure before dispatch honestly reports.\n    let url: string | undefined\n    let dispatched: AxiosRequestConfig | undefined\n\n    try {\n      const res = await abortable.run((abortSignal) => {\n        // Derived inside `run`, the way the rest of the family does it: `run` opens the generation\n        // and, with `cancelPrevious`, stops the call before this one.\n        const template = isDefined(urlTemplateOverride) ? urlTemplateOverride : urlTemplate\n        if (isUndefined(template)) throw new AnzuFatalError(undefined, 'Url template is undefined')\n\n        // `null` omits the body, as it always has -- a caller that means to send JSON `null` wraps it.\n        const sendsBody = !isNull(body) && !isUndefined(body)\n\n        // Because `method` defaults to GET: a caller who wrote a body and forgot `method: 'POST'`\n        // would otherwise send a GET without its filter, and nothing downstream would notice.\n        if (method === 'GET' && sendsBody) {\n          throw new AnzuFatalError(\n            undefined,\n            'A GET request does not carry a body -- set method, or pass the value through options.params'\n          )\n        }\n\n        const resolvedParams = isDefined(urlParamsOverride) ? urlParamsOverride : urlParams\n        const requestUrl = isUndefined(resolvedParams) ? template : replaceUrlParameters(template, resolvedParams)\n\n        // `options` first, then what this helper owns: a caller cannot reach in and set the method,\n        // the url, the body or the signal through it.\n        const config: AxiosRequestConfig = {\n          ...ownedByHelper(options),\n          method,\n          url: requestUrl,\n          signal: abortSignal,\n        }\n        if (sendsBody) config.data = JSON.stringify(body)\n\n        const instance = client()\n\n        // Recorded last, when nothing between here and the call can throw any more. It used to sit\n        // safely above the dispatch because nothing here could fail; `JSON.stringify` can -- a\n        // circular body would otherwise be reported as a request to a url nobody ever called.\n        url = requestUrl\n\n        return instance.request(config)\n      }, signal)\n\n      dispatched = res.config\n      // The url the report will name, so a message and the context beside it cannot disagree about\n      // which request failed when an interceptor rewrote it on the way out.\n      const asSent = () => requestedUrl(client, url, options, undefined, dispatched)\n      if (!isValidHTTPStatus(res.status)) throw new AnzuApiResponseCodeError(res.status)\n\n      // Nothing matched -- an empty answer, not a broken one.\n      if (res.status === HTTP_STATUS_NO_CONTENT) return []\n\n      if (!hasBody(res)) {\n        throw new AnzuApiResponseCodeError(res.status, undefined, 'Expected a response body, url: ' + asSent())\n      }\n\n      return shape === 'array'\n        ? readArrayBody<T>(res.data, res.status, asSent())\n        : readListBody<T>(res.data, res.status, asSent()).items\n    } catch (err: unknown) {\n      const context = {\n        system,\n        entity,\n        validationSystem,\n        validationEntity,\n        url: requestedUrl(client, url, options, err, dispatched),\n      }\n\n      throw report(mapApiError(err, context), context)\n    }\n  }\n\n  return { execute, abort: abortable.abort, loading: abortable.loading }\n}\n\nexport type UseApiFetchItemsReturnType<T, B = never> = {\n  execute: (params?: FetchItemsParams<B>) => Promise<T[]>\n  abort: () => void\n  /**\n   * True while this instance has a request in flight, false once the last one settles.\n   *\n   * It is here so a caller does not have to keep its own: the hand-rolled version is a ref cleared in\n   * a `finally`, and that `finally` belongs to whichever call ended -- including one that\n   * `cancelPrevious` just superseded, which turns the spinner off while the call the user is waiting\n   * for is still running. This one never dips between a superseded call and the one that replaced it.\n   *\n   * Two things to know before replacing a hand-rolled flag with it.\n   *\n   * It covers what this helper does and nothing the caller does afterwards. A flag that also spans a\n   * follow-up cached fetch, a mapping pass or a second endpoint is not the same flag, and swapping it\n   * for this one turns the spinner off too early. Keep your own where it means more than \"this helper\n   * is working\".\n   *\n   * It belongs to the instance, so it is only reachable if you hold the instance. A factory that\n   * builds one per call and hands back the promise alone -- `const { execute } = useX()` inside the\n   * function that calls it -- cannot expose `loading`, `abort` or `cancelPrevious` at all. Hoist the\n   * instance to where the caller lives first.\n   */\n  loading: Ref<boolean>\n}\n"],"mappings":";;;;;;;;;;AAuFA,IAAaA,KAAkC,MAAqE;CAClH,IAAM,EACJ,WACA,WACA,WACA,qBACA,qBACA,gBACA,cACA,aAAU,CAAC,GACX,oBAAiB,IACjB,YAAS,OACT,WAAQ,eACNC,GACEC,IAAYC,EAAgB,EAAE,kBAAe,CAAC;CAiFpD,OAAO;EAAE,gBA/Ec,IAAmC,CAAC,MAAoB;GAC7E,IAAM,EAAE,aAAaC,GAAqB,WAAWC,GAAmB,SAAM,cAAWC,GAIrFC,GACAC;GAEJ,IAAI;IACF,IAAMC,IAAM,MAAMP,EAAU,KAAK,MAAgB;KAG/C,IAAMQ,IAAWC,EAAUP,CAAmB,IAAIA,IAAsBQ;KACxE,IAAIC,EAAYH,CAAQ,GAAG,MAAM,IAAII,EAAe,KAAA,GAAW,2BAA2B;KAG1F,IAAMC,IAAY,CAACC,EAAOC,CAAI,KAAK,CAACJ,EAAYI,CAAI;KAIpD,IAAIC,MAAW,SAASH,GACtB,MAAM,IAAID,EACR,KAAA,GACA,6FACF;KAGF,IAAMK,IAAiBR,EAAUN,CAAiB,IAAIA,IAAoBe,GACpEC,IAAaR,EAAYM,CAAc,IAAIT,IAAWY,EAAqBZ,GAAUS,CAAc,GAInGI,IAA6B;MACjC,GAAGC,EAAcC,CAAO;MACxB;MACA,KAAKJ;MACL,QAAQK;KACV;KACA,AAAIX,MAAW,EAAO,OAAO,KAAK,UAAUE,CAAI;KAEhD,IAAMU,IAAWC,EAAO;KAOxB,OAFA,IAAMP,GAECM,EAAS,QAAQJ,CAAM;IAChC,GAAGM,CAAM;IAET,IAAapB,EAAI;IAGjB,IAAMqB,UAAeC,EAAaH,GAAQrB,GAAKkB,GAAS,KAAA,GAAWjB,CAAU;IAC7E,IAAI,CAACwB,EAAkBvB,EAAI,MAAM,GAAG,MAAM,IAAIwB,EAAyBxB,EAAI,MAAM;IAGjF,IAAIA,EAAI,WAAA,KAAmC,OAAO,CAAC;IAEnD,IAAI,CAACyB,EAAQzB,CAAG,GACd,MAAM,IAAIwB,EAAyBxB,EAAI,QAAQ,KAAA,GAAW,oCAAoCqB,EAAO,CAAC;IAGxG,OAAOK,MAAU,UACbC,EAAiB3B,EAAI,MAAMA,EAAI,QAAQqB,EAAO,CAAC,IAC/CO,EAAgB5B,EAAI,MAAMA,EAAI,QAAQqB,EAAO,CAAC,CAAC,CAAC;GACtD,SAASQ,GAAc;IACrB,IAAMC,IAAU;KACd;KACA;KACA;KACA;KACA,KAAKR,EAAaH,GAAQrB,GAAKkB,GAASa,GAAK9B,CAAU;IACzD;IAEA,MAAMgC,EAAOC,EAAYH,GAAKC,CAAO,GAAGA,CAAO;GACjD;EACF;EAEkB,OAAOrC,EAAU;EAAO,SAASA,EAAU;CAAQ;AACvE"}

package/dist/domains/api/composables/useApiFetchList.d.ts

@@ -0,0 +1,60 @@
+import { UrlParams } from '../utils/apiHelper';
+import { AxiosRequestConfig } from 'axios';
+import { FilterConfig, FilterData } from '../../filters/composables/filterFactory';
+import { Ref } from 'vue';
+import { Pagination } from './pagination';
+import { AxiosClientFn } from '../utils/client';
+export type UseApiFetchListParams = {
+    client: AxiosClientFn;
+    system: string;
+    entity: string;
+    /** i18n scope for field-level validation failures; defaults to `system` / `entity`. */
+    validationSystem?: string;
+    validationEntity?: string;
+    urlTemplate?: string;
+    urlParams?: UrlParams;
+    /** Anything axios takes except what this helper decides: the method, the url, the body and the signal. */
+    options?: Omit<AxiosRequestConfig, 'method' | 'url' | 'data' | 'signal'>;
+    cancelPrevious?: boolean;
+};
+export type FetchListParams = {
+    urlTemplate?: string;
+    urlParams?: UrlParams;
+    forceElastic?: boolean;
+    /** Stops this one call, leaving the instance's other calls alone. */
+    signal?: AbortSignal;
+    /**
+     * `false`: a failure of this one call is thrown as ever, and not handed to the api error logger.
+     *
+     * As in `useApiRequest`: for a caller that reads a list again on a timer and has reported its first failure
+     * already. It is the caller's to say which call that is, call by call; an instance has no such switch.
+     */
+    report?: boolean;
+};
+export declare const generateListQuery: (pagination: Ref<Pagination>, filterData: FilterData<any>, filterConfig: FilterConfig<any>) => string;
+export declare const useApiFetchList: <T>(params: UseApiFetchListParams) => UseApiFetchListReturnType<T>;
+export type UseApiFetchListReturnType<T> = {
+    execute: (pagination: Ref<Pagination>, filterData: FilterData<any>, filterConfig: FilterConfig<any>, params?: FetchListParams) => Promise<T[]>;
+    abort: () => void;
+    /**
+     * True while this instance has a request in flight, false once the last one settles.
+     *
+     * It is here so a caller does not have to keep its own: the hand-rolled version is a ref cleared in
+     * a `finally`, and that `finally` belongs to whichever call ended -- including one that
+     * `cancelPrevious` just superseded, which turns the spinner off while the call the user is waiting
+     * for is still running. This one never dips between a superseded call and the one that replaced it.
+     *
+     * Two things to know before replacing a hand-rolled flag with it.
+     *
+     * It covers what this helper does and nothing the caller does afterwards. A flag that also spans a
+     * follow-up cached fetch, a mapping pass or a second endpoint is not the same flag, and swapping it
+     * for this one turns the spinner off too early. Keep your own where it means more than "this helper
+     * is working".
+     *
+     * It belongs to the instance, so it is only reachable if you hold the instance. A factory that
+     * builds one per call and hands back the promise alone -- `const { execute } = useX()` inside the
+     * function that calls it -- cannot expose `loading`, `abort` or `cancelPrevious` at all. Hoist the
+     * instance to where the caller lives first.
+     */
+    loading: Ref<boolean>;
+};

package/dist/domains/api/composables/useApiFetchList.js

@@ -0,0 +1,69 @@
+import { isDefined as e, isNull as t, isUndefined as n } from "../../../shared/utils/common.js";
+import { AnzuFatalError as r } from "../../../shared/error/AnzuFatalError.js";
+import "../../../shared/statusCodes.js";
+import { AnzuApiResponseCodeError as i } from "../../../shared/error/AnzuApiResponseCodeError.js";
+import { replaceUrlParameters as a } from "../utils/apiHelper.js";
+import { isValidHTTPStatus as o } from "../utils/response.js";
+import { mapApiError as s, report as c } from "../utils/apiErrors.js";
+import { createAbortable as l, hasBody as u, ownedByHelper as d, requestedUrl as f } from "./request.js";
+import { SortOrder as p } from "../types/SortOrder.js";
+import { readListBody as m } from "../utils/listBody.js";
+import { useApiQueryBuilder as h } from "./useApiQueryBuilder.js";
+//#region src/domains/api/composables/useApiFetchList.ts
+var g = (e, t, n) => {
+	let { querySetLimit: r, querySetOffset: i, querySetOrder: a, queryBuild: o, querySetFilters: s } = h();
+	return r(e.value.rowsPerPage), i(e.value.page, e.value.rowsPerPage), e.value.sortBy && a(e.value.sortBy.key, e.value.sortBy.order === p.Desc), s(t, n), o();
+}, _ = (p) => {
+	let { client: h, system: _, entity: v, validationSystem: y, validationEntity: b, urlTemplate: x, urlParams: S, options: C = {}, cancelPrevious: w = !1 } = p, T = l({ cancelPrevious: w });
+	return {
+		execute: async (l, p, w, E = {}) => {
+			let { urlTemplate: D, urlParams: O, forceElastic: k = !1, signal: A, report: j = !0 } = E, M, N, P = 0, F, I = (e) => {
+				T.generation() === P && F?.aborted !== !0 && A?.aborted !== !0 && (l.value = {
+					...l.value,
+					...e
+				});
+			};
+			try {
+				let s = await T.run((t, i) => {
+					P = i, F = t;
+					let o = e(D) ? D : x;
+					if (n(o)) throw new r(void 0, "Url template is undefined");
+					let s = e(O) ? O : S, c = w.general.elastic || k ? "/search" : "", u = (n(s) ? o : a(o, s)) + c + g(l, p, w), f = h();
+					return M = u, f.get(u, {
+						...d(C),
+						signal: t
+					});
+				}, A);
+				N = s.config;
+				let c = () => f(h, M, C, void 0, N);
+				if (!o(s.status)) throw new i(s.status);
+				if (s.status === 204) return I({
+					totalCount: 0,
+					hasNextPage: t(l.value.hasNextPage) ? null : !1,
+					currentViewCount: 0
+				}), [];
+				if (!u(s)) throw new i(s.status, void 0, "Expected a response body, url: " + c());
+				let _ = m(s.data, s.status, c());
+				return _.mode !== "unknown" && I({
+					..._.pagination,
+					currentViewCount: _.items.length
+				}), _.items;
+			} catch (e) {
+				let t = {
+					system: _,
+					entity: v,
+					validationSystem: y,
+					validationEntity: b,
+					url: f(h, M, C, e, N)
+				}, n = s(e, t);
+				throw j ? c(n, t) : n;
+			}
+		},
+		abort: T.abort,
+		loading: T.loading
+	};
+};
+//#endregion
+export { g as generateListQuery, _ as useApiFetchList };
+
+//# sourceMappingURL=useApiFetchList.js.map

package/dist/domains/api/composables/useApiFetchList.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useApiFetchList.js","names":["generateListQuery","useApiQueryBuilder","querySetLimit","pagination","querySetOffset","querySetOrder","SortOrder","querySetFilters","filterData","filterConfig","queryBuild","useApiFetchList","params","abortable","createAbortable","urlTemplateOverride","urlParamsOverride","reported","fetchParams","url","dispatched","generation","ownSignal","writePagination","signal","next","res","currentGeneration","abortSignal","template","isDefined","urlTemplate","isUndefined","AnzuFatalError","resolvedParams","urlParams","searchApi","forceElastic","requestUrl","replaceUrlParameters","instance","client","ownedByHelper","options","asSent","requestedUrl","isValidHTTPStatus","AnzuApiResponseCodeError","isNull","hasBody","list","readListBody","err","context","error","mapApiError","report"],"sources":["../../../../src/domains/api/composables/useApiFetchList.ts"],"sourcesContent":["import { AnzuFatalError } from '@/shared/error/AnzuFatalError'\nimport { AnzuApiResponseCodeError } from '@/shared/error/AnzuApiResponseCodeError'\nimport { replaceUrlParameters, type UrlParams } from '@/domains/api/utils/apiHelper'\nimport { isValidHTTPStatus } from '@/domains/api/utils/response'\nimport type { AxiosRequestConfig } from 'axios'\nimport { useApiQueryBuilder } from '@/domains/api/composables/useApiQueryBuilder'\nimport { HTTP_STATUS_NO_CONTENT } from '@/shared/statusCodes'\nimport type { FilterConfig, FilterData } from '@/domains/filters/composables/filterFactory'\nimport type { Ref } from 'vue'\nimport { isDefined, isNull, isUndefined } from '@/shared/utils/common'\nimport type { Pagination } from '@/domains/api/composables/pagination'\nimport { SortOrder } from '@/domains/api/types/SortOrder'\nimport type { AxiosClientFn } from '@/domains/api/utils/client'\nimport { mapApiError, report } from '@/domains/api/utils/apiErrors'\nimport { createAbortable, hasBody, ownedByHelper, requestedUrl } from '@/domains/api/composables/request'\nimport { readListBody } from '@/domains/api/utils/listBody'\n\nexport type UseApiFetchListParams = {\n  client: AxiosClientFn\n  system: string\n  entity: string\n  /** i18n scope for field-level validation failures; defaults to `system` / `entity`. */\n  validationSystem?: string\n  validationEntity?: string\n  urlTemplate?: string\n  urlParams?: UrlParams\n  /** Anything axios takes except what this helper decides: the method, the url, the body and the signal. */\n  options?: Omit<AxiosRequestConfig, 'method' | 'url' | 'data' | 'signal'>\n  cancelPrevious?: boolean\n}\n\nexport type FetchListParams = {\n  urlTemplate?: string\n  urlParams?: UrlParams\n  forceElastic?: boolean\n  /** Stops this one call, leaving the instance's other calls alone. */\n  signal?: AbortSignal\n  /**\n   * `false`: a failure of this one call is thrown as ever, and not handed to the api error logger.\n   *\n   * As in `useApiRequest`: for a caller that reads a list again on a timer and has reported its first failure\n   * already. It is the caller's to say which call that is, call by call; an instance has no such switch.\n   */\n  report?: boolean\n}\n\nexport const generateListQuery = (\n  pagination: Ref<Pagination>,\n  filterData: FilterData<any>,\n  filterConfig: FilterConfig<any>\n): string => {\n  const { querySetLimit, querySetOffset, querySetOrder, queryBuild, querySetFilters } = useApiQueryBuilder()\n  querySetLimit(pagination.value.rowsPerPage)\n  querySetOffset(pagination.value.page, pagination.value.rowsPerPage)\n  if (pagination.value.sortBy) {\n    querySetOrder(pagination.value.sortBy.key, pagination.value.sortBy.order === SortOrder.Desc)\n  }\n  querySetFilters(filterData, filterConfig)\n  return queryBuild()\n}\n\nexport const useApiFetchList = <T>(params: UseApiFetchListParams): UseApiFetchListReturnType<T> => {\n  const {\n    client,\n    system,\n    entity,\n    validationSystem,\n    validationEntity,\n    urlTemplate,\n    urlParams,\n    options = {},\n    cancelPrevious = false,\n  } = params\n  const abortable = createAbortable({ cancelPrevious })\n\n  const execute = async (\n    pagination: Ref<Pagination>,\n    filterData: FilterData<any>,\n    filterConfig: FilterConfig<any>,\n    fetchParams: FetchListParams = {}\n  ): Promise<T[]> => {\n    const {\n      urlTemplate: urlTemplateOverride,\n      urlParams: urlParamsOverride,\n      forceElastic = false,\n      signal,\n      report: reported = true,\n    } = fetchParams\n\n    // Assigned inside `run`, once, at the moment there is a url to ask for. It stays undefined until\n    // then, and that is what a failure before dispatch reports: the field says which url was\n    // requested, and a call that never reached the wire requested none. Neither the client root nor\n    // the path it was going to build is an answer to that question.\n    let url: string | undefined\n    // The config axios used, kept for the failures this helper raises after reading the response:\n    // they carry no config of their own, and rebuilding one describes the request as the client\n    // would send it now rather than as it was sent.\n    let dispatched: AxiosRequestConfig | undefined\n\n    // Handed over by `run`, not read before it: `run` is what opens a new generation, so a value\n    // taken beforehand belongs to the previous call and would never match.\n    let generation = 0\n    let ownSignal: AbortSignal | undefined\n    const writePagination = (next: Partial<Pagination>) => {\n      // Two ways to stop being the call whose answer counts, and both have to be checked: a newer\n      // call opened a generation, or this one was cancelled through a signal of its own. Aborting\n      // does not stop a response already on its way, so either can still arrive and write.\n      //\n      // The generation belongs to the instance, not to this `pagination` ref, so one instance serves\n      // one list. Two concurrent calls on a shared instance writing to different refs would leave\n      // the older ref unwritten -- correct for the same list shown twice, wrong for two lists.\n      if (abortable.generation() !== generation) return\n      if (ownSignal?.aborted === true) return\n      // The caller's own signal, read directly rather than through the relay `run` set up for it.\n      // `run` drops that relay as soon as the response is in hand, and the write happens after --\n      // so an abort landing in between leaves `ownSignal` untouched, and the call the caller just\n      // stopped would go on to write the pagination. This is the only state the family writes\n      // outside `run`, so it is the only place the gap exists.\n      if (signal?.aborted === true) return\n      pagination.value = { ...pagination.value, ...next }\n    }\n\n    try {\n      const res = await abortable.run((abortSignal, currentGeneration) => {\n        generation = currentGeneration\n        ownSignal = abortSignal\n\n        // The whole url is derived here, inside `run`, and that is the point of putting it here:\n        // `run` is what opens a new generation and, with `cancelPrevious`, stops the call before\n        // this one. Anything done ahead of it belongs to no generation yet, so a missing template or\n        // a malformed filter config -- both of which throw while the url is being built -- would\n        // leave the previous call current, and its answer, arriving afterwards, would write\n        // pagination for a query the caller has already replaced. It also keeps all of it inside the\n        // try, so the caller gets the same error class as for every other failure rather than a bare\n        // `Error` nothing in the fleet is written to catch.\n        const template = isDefined(urlTemplateOverride) ? urlTemplateOverride : urlTemplate\n        if (isUndefined(template)) throw new AnzuFatalError(undefined, 'Url template is undefined')\n\n        const resolvedParams = isDefined(urlParamsOverride) ? urlParamsOverride : urlParams\n        const searchApi = filterConfig.general.elastic || forceElastic ? '/search' : ''\n        const baseUrl =\n          (isUndefined(resolvedParams) ? template : replaceUrlParameters(template, resolvedParams)) + searchApi\n        const requestUrl = baseUrl + generateListQuery(pagination, filterData, filterConfig)\n        const instance = client()\n\n        // Recorded last, when nothing between here and the call can throw any more: a client factory\n        // that fails is a request that never happened, and the report says so by naming no url.\n        url = requestUrl\n\n        return instance.get(requestUrl, { ...ownedByHelper(options), signal: abortSignal })\n      }, signal)\n\n      dispatched = res.config\n      // The url the report will name, so a message and the context beside it cannot disagree about\n      // which request failed when an interceptor rewrote it on the way out.\n      const asSent = () => requestedUrl(client, url, options, undefined, dispatched)\n      if (!isValidHTTPStatus(res.status)) throw new AnzuApiResponseCodeError(res.status)\n\n      // 204 is an empty list, and the metadata has to say so -- left alone it keeps answering for\n      // the previous query.\n      if (res.status === HTTP_STATUS_NO_CONTENT) {\n        // A 204 says the list is empty; it says nothing about which kind of list it is. So the mode\n        // the pagination is already in decides which field gets cleared: a counted list keeps\n        // `null`, and an infinite one keeps a boolean and gets `false` -- which is what it means,\n        // \"there is nothing after this\". Writing `null` for both put an infinite list into counted\n        // mode, where `ASubjectSelect` reads a next page as available and its autoload fires again\n        // on the same 204, and `ADatatablePagination` offers Next and Last on an empty page.\n        const stillCounted = isNull(pagination.value.hasNextPage)\n        writePagination({ totalCount: 0, hasNextPage: stillCounted ? null : false, currentViewCount: 0 })\n        return []\n      }\n\n      if (!hasBody(res)) {\n        throw new AnzuApiResponseCodeError(res.status, undefined, 'Expected a response body, url: ' + asSent())\n      }\n\n      const list = readListBody<T>(res.data, res.status, asSent())\n      // Only when the response said something about paging at all: a body that named no mode has\n      // said nothing to write, and a count of what just arrived would be the one field left\n      // describing a query nobody asked about.\n      if (list.mode !== 'unknown') writePagination({ ...list.pagination, currentViewCount: list.items.length })\n\n      return list.items\n    } catch (err: unknown) {\n      // Built once and handed to both, the way the batch does it: half the work on the failure path,\n      // and one place that could go wrong instead of two.\n      const context = {\n        system,\n        entity,\n        validationSystem,\n        validationEntity,\n        url: requestedUrl(client, url, options, err, dispatched),\n      }\n\n      const error = mapApiError(err, context)\n\n      throw reported ? report(error, context) : error\n    }\n  }\n\n  return { execute, abort: abortable.abort, loading: abortable.loading }\n}\n\nexport type UseApiFetchListReturnType<T> = {\n  execute: (\n    pagination: Ref<Pagination>,\n    filterData: FilterData<any>,\n    filterConfig: FilterConfig<any>,\n    params?: FetchListParams\n  ) => Promise<T[]>\n  abort: () => void\n  /**\n   * True while this instance has a request in flight, false once the last one settles.\n   *\n   * It is here so a caller does not have to keep its own: the hand-rolled version is a ref cleared in\n   * a `finally`, and that `finally` belongs to whichever call ended -- including one that\n   * `cancelPrevious` just superseded, which turns the spinner off while the call the user is waiting\n   * for is still running. This one never dips between a superseded call and the one that replaced it.\n   *\n   * Two things to know before replacing a hand-rolled flag with it.\n   *\n   * It covers what this helper does and nothing the caller does afterwards. A flag that also spans a\n   * follow-up cached fetch, a mapping pass or a second endpoint is not the same flag, and swapping it\n   * for this one turns the spinner off too early. Keep your own where it means more than \"this helper\n   * is working\".\n   *\n   * It belongs to the instance, so it is only reachable if you hold the instance. A factory that\n   * builds one per call and hands back the promise alone -- `const { execute } = useX()` inside the\n   * function that calls it -- cannot expose `loading`, `abort` or `cancelPrevious` at all. Hoist the\n   * instance to where the caller lives first.\n   */\n  loading: Ref<boolean>\n}\n"],"mappings":";;;;;;;;;;;;AA8CA,IAAaA,KACX,GACA,GACA,MACW;CACX,IAAM,EAAE,kBAAe,mBAAgB,kBAAe,eAAY,uBAAoBC,EAAmB;CAOzG,OANAC,EAAcC,EAAW,MAAM,WAAW,GAC1CC,EAAeD,EAAW,MAAM,MAAMA,EAAW,MAAM,WAAW,GAC9DA,EAAW,MAAM,UACnBE,EAAcF,EAAW,MAAM,OAAO,KAAKA,EAAW,MAAM,OAAO,UAAUG,EAAU,IAAI,GAE7FC,EAAgBC,GAAYC,CAAY,GACjCC,EAAW;AACpB,GAEaC,KAAsB,MAAgE;CACjG,IAAM,EACJ,WACA,WACA,WACA,qBACA,qBACA,gBACA,cACA,aAAU,CAAC,GACX,oBAAiB,OACfC,GACEC,IAAYC,EAAgB,EAAE,kBAAe,CAAC;CA+HpD,OAAO;EAAE,gBA5HP,GACA,GACA,GACA,IAA+B,CAAC,MACf;GACjB,IAAM,EACJ,aAAaC,GACb,WAAWC,GACX,kBAAe,IACf,WACA,QAAQC,IAAW,OACjBC,GAMAC,GAIAC,GAIAC,IAAa,GACbC,GACEC,KAAmB,MAA8B;IAQrD,AAAIV,EAAU,WAAW,MAAMQ,KAC3BC,GAAW,YAAY,MAMvBE,GAAQ,YAAY,OACxB,EAAW,QAAQ;KAAE,GAAGrB,EAAW;KAAO,GAAGsB;IAAK;GACpD;GAEA,IAAI;IACF,IAAMC,IAAM,MAAMb,EAAU,KAAK,GAAa,MAAsB;KAElE,AADA,IAAac,GACb,IAAYC;KAUZ,IAAMC,IAAWC,EAAUf,CAAmB,IAAIA,IAAsBgB;KACxE,IAAIC,EAAYH,CAAQ,GAAG,MAAM,IAAII,EAAe,KAAA,GAAW,2BAA2B;KAE1F,IAAMC,IAAiBJ,EAAUd,CAAiB,IAAIA,IAAoBmB,GACpEC,IAAY3B,EAAa,QAAQ,WAAW4B,IAAe,YAAY,IAGvEC,KADHN,EAAYE,CAAc,IAAIL,IAAWU,EAAqBV,GAAUK,CAAc,KAAKE,IACjEpC,EAAkBG,GAAYK,GAAYC,CAAY,GAC7E+B,IAAWC,EAAO;KAMxB,OAFA,IAAMH,GAECE,EAAS,IAAIF,GAAY;MAAE,GAAGI,EAAcC,CAAO;MAAG,QAAQf;KAAY,CAAC;IACpF,GAAGJ,CAAM;IAET,IAAaE,EAAI;IAGjB,IAAMkB,UAAeC,EAAaJ,GAAQtB,GAAKwB,GAAS,KAAA,GAAWvB,CAAU;IAC7E,IAAI,CAAC0B,EAAkBpB,EAAI,MAAM,GAAG,MAAM,IAAIqB,EAAyBrB,EAAI,MAAM;IAIjF,IAAIA,EAAI,WAAA,KASN,OADAH,EAAgB;KAAE,YAAY;KAAG,aADZyB,EAAO7C,EAAW,MAAM,WACC,IAAe,OAAO;KAAO,kBAAkB;IAAE,CAAC,GACzF,CAAC;IAGV,IAAI,CAAC8C,EAAQvB,CAAG,GACd,MAAM,IAAIqB,EAAyBrB,EAAI,QAAQ,KAAA,GAAW,oCAAoCkB,EAAO,CAAC;IAGxG,IAAMM,IAAOC,EAAgBzB,EAAI,MAAMA,EAAI,QAAQkB,EAAO,CAAC;IAM3D,OAFIM,EAAK,SAAS,aAAW3B,EAAgB;KAAE,GAAG2B,EAAK;KAAY,kBAAkBA,EAAK,MAAM;IAAO,CAAC,GAEjGA,EAAK;GACd,SAASE,GAAc;IAGrB,IAAMC,IAAU;KACd;KACA;KACA;KACA;KACA,KAAKR,EAAaJ,GAAQtB,GAAKwB,GAASS,GAAKhC,CAAU;IACzD,GAEMkC,IAAQC,EAAYH,GAAKC,CAAO;IAEtC,MAAMpC,IAAWuC,EAAOF,GAAOD,CAAO,IAAIC;GAC5C;EACF;EAEkB,OAAOzC,EAAU;EAAO,SAASA,EAAU;CAAQ;AACvE"}

package/dist/domains/api/composables/useApiFetchListBatch.d.ts

@@ -0,0 +1,57 @@
+import { UrlParams } from '../utils/apiHelper';
+import { AxiosRequestConfig } from 'axios';
+import { FilterConfig, FilterData } from '../../filters/composables/filterFactory';
+import { Ref } from 'vue';
+import { AxiosClientFn } from '../utils/client';
+export type UseApiFetchListBatchParams = {
+    client: AxiosClientFn;
+    system: string;
+    entity: string;
+    /** i18n scope for field-level validation failures; defaults to `system` / `entity`. */
+    validationSystem?: string;
+    validationEntity?: string;
+    urlTemplate?: string;
+    urlParams?: UrlParams;
+    /** Anything axios takes except what this helper decides: the method, the url, the body and the signal. */
+    options?: Omit<AxiosRequestConfig, 'method' | 'url' | 'data' | 'signal'>;
+    cancelPrevious?: boolean;
+};
+export type FetchListBatchParams = {
+    /** Stops this one call, leaving the instance's other calls alone. */
+    signal?: AbortSignal;
+    urlTemplate?: string;
+    urlParams?: UrlParams;
+    sortBy?: string;
+    sortDesc?: boolean;
+    batchSize?: number;
+    forceElastic?: boolean;
+};
+export declare const useApiFetchListBatch: <T>(params: UseApiFetchListBatchParams) => UseApiFetchListBatchReturnType<T>;
+export type UseApiFetchListBatchReturnType<T> = {
+    execute: (filterData: FilterData<any>, filterConfig: FilterConfig<any>, params?: FetchListBatchParams) => Promise<T[]>;
+    abort: () => void;
+    /**
+     * True while this instance is working, false once it stops.
+     *
+     * Here that is the whole walk, not one request: a batch reads every page, and the flag stays up
+     * across the gaps between them and across the reading of each answer.
+     *
+     * It is here so a caller does not have to keep its own: the hand-rolled version is a ref cleared in
+     * a `finally`, and that `finally` belongs to whichever call ended -- including one that
+     * `cancelPrevious` just superseded, which turns the spinner off while the call the user is waiting
+     * for is still running. This one never dips between a superseded call and the one that replaced it.
+     *
+     * Two things to know before replacing a hand-rolled flag with it.
+     *
+     * It covers what this helper does and nothing the caller does afterwards. A flag that also spans a
+     * follow-up cached fetch, a mapping pass or a second endpoint is not the same flag, and swapping it
+     * for this one turns the spinner off too early. Keep your own where it means more than "this helper
+     * is working".
+     *
+     * It belongs to the instance, so it is only reachable if you hold the instance. A factory that
+     * builds one per call and hands back the promise alone -- `const { execute } = useX()` inside the
+     * function that calls it -- cannot expose `loading`, `abort` or `cancelPrevious` at all. Hoist the
+     * instance to where the caller lives first.
+     */
+    loading: Ref<boolean>;
+};