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

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

@@ -0,0 +1,116 @@
+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 { SortOrder as f } from "../types/SortOrder.js";
+import { readListBody as p } from "../utils/listBody.js";
+import { generateListQuery as m } from "./useApiFetchList.js";
+import { usePagination as h } from "./pagination.js";
+import { ref as g } from "vue";
+//#region src/domains/api/composables/useApiFetchListBatch.ts
+var _ = class extends Error {
+	pageUrl;
+	failure;
+	dispatched;
+	constructor(e, t, n) {
+		super("Batch page failed"), this.name = "PageFailure", this.pageUrl = e, this.failure = t, this.dispatched = n;
+	}
+}, v = (v) => {
+	let { client: y, system: b, entity: x, validationSystem: S, validationEntity: C, urlTemplate: w, urlParams: T, options: E = {}, cancelPrevious: D = !1 } = v, O = c({ cancelPrevious: D });
+	return {
+		execute: async (c, v, D = {}) => {
+			let { urlTemplate: k, urlParams: A, sortBy: j = "id", sortDesc: M = !0, batchSize: N = 100, forceElastic: P = !1, signal: F } = D;
+			try {
+				return await O.run(async (o) => {
+					let s = e(k) ? k : w;
+					if (t(s)) throw new n(void 0, "Url template is undefined");
+					if (N < 1) throw new n(void 0, "batchSize must be at least 1, got " + N);
+					let b = e(A) ? A : T, x = v.general.elastic || P ? "/search" : "", S = (t(b) ? s : i(s, b)) + x, C = y(), { pagination: D } = h(j, M ? f.Desc : f.Asc, { rowsPerPage: N }), O = async (e) => {
+						let t = S + m(e, c, v);
+						try {
+							return {
+								res: await C.get(t, {
+									...u(E),
+									signal: o
+								}),
+								pageUrl: t
+							};
+						} catch (e) {
+							throw new _(t, e);
+						}
+					}, F = (e, t) => d(y, t, E, void 0, e.config), I = (e, t) => {
+						if (!a(e.status)) throw new _(t, new r(e.status), e.config);
+						if (e.status === 204) return {
+							items: [],
+							mode: "unknown",
+							totalCount: 0,
+							hasNextPage: !1,
+							countIsBound: !1,
+							empty: !0
+						};
+						if (!l(e)) throw new _(t, new r(e.status, void 0, "Expected a response body, url: " + F(e, t)), e.config);
+						let n;
+						try {
+							n = p(e.data, e.status, F(e, t));
+						} catch (n) {
+							throw new _(t, n, e.config);
+						}
+						return {
+							items: n.items,
+							mode: n.mode,
+							totalCount: n.pagination.totalCount ?? 0,
+							hasNextPage: n.pagination.hasNextPage === !0,
+							countIsBound: n.countIsBound,
+							empty: !1
+						};
+					}, L = await O(D), R = I(L.res, L.pageUrl), z = [...R.items];
+					if (R.empty) return z;
+					let B = R.items.length > 0 && R.items.length < D.value.rowsPerPage;
+					if (B && (D.value.rowsPerPage = R.items.length), R.mode === "infinite") {
+						let e = R.hasNextPage;
+						for (; e;) {
+							D.value.page++;
+							let t = await O(D), n = I(t.res, t.pageUrl);
+							if (z.push(...n.items), n.empty) break;
+							e = n.hasNextPage;
+						}
+						return z;
+					}
+					if (R.mode !== "counted" || z.length >= R.totalCount) return z;
+					if (B || R.countIsBound) {
+						for (;;) {
+							D.value.page++;
+							let e = await O(D), t = I(e.res, e.pageUrl);
+							if (z.push(...t.items), t.items.length < D.value.rowsPerPage) break;
+						}
+						return z;
+					}
+					let V = Math.ceil(R.totalCount / D.value.rowsPerPage);
+					return V <= 1 || (await Promise.all(Array.from({ length: V - 1 }, (e, t) => O(g({
+						...D.value,
+						page: t + 2
+					})).then((e) => I(e.res, e.pageUrl))))).forEach((e) => z.push(...e.items)), z;
+				}, F);
+			} catch (e) {
+				let t = e instanceof _ ? e : null, n = {
+					system: b,
+					entity: x,
+					validationSystem: S,
+					validationEntity: C,
+					url: d(y, t?.pageUrl, E, t?.failure ?? e, t?.dispatched)
+				};
+				throw s(o(t?.failure ?? e, n), n);
+			}
+		},
+		abort: O.abort,
+		loading: O.loading
+	};
+};
+//#endregion
+export { v as useApiFetchListBatch };
+
+//# sourceMappingURL=useApiFetchListBatch.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useApiFetchListBatch.js","names":["PageFailure","pageUrl","failure","dispatched","useApiFetchListBatch","params","abortable","createAbortable","urlTemplateOverride","urlParamsOverride","fetchParams","template","isDefined","urlTemplate","isUndefined","AnzuFatalError","batchSize","resolvedParams","urlParams","searchApi","filterConfig","forceElastic","baseUrl","replaceUrlParameters","instance","client","usePagination","sortBy","sortDesc","SortOrder","get","generateListQuery","page","filterData","ownedByHelper","options","abortSignal","err","asSent","requestedUrl","res","readPage","isValidHTTPStatus","AnzuApiResponseCodeError","hasBody","body","readListBody","firstPage","pagination","first","results","capped","hasNextPage","nextPage","next","pageCount","ref","index","signal","failed","context","report","mapApiError"],"sources":["../../../../src/domains/api/composables/useApiFetchListBatch.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, AxiosResponse } from 'axios'\nimport { HTTP_STATUS_NO_CONTENT } from '@/shared/statusCodes'\nimport type { FilterConfig, FilterData } from '@/domains/filters/composables/filterFactory'\nimport { type Ref, ref } from 'vue'\nimport { isDefined, isUndefined } from '@/shared/utils/common'\nimport { type Pagination, usePagination } from '@/domains/api/composables/pagination'\nimport { SortOrder } from '@/domains/api/types/SortOrder'\nimport type { AxiosClientFn } from '@/domains/api/utils/client'\nimport { generateListQuery } from '@/domains/api/composables/useApiFetchList'\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 UseApiFetchListBatchParams = {\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 FetchListBatchParams = {\n  /** Stops this one call, leaving the instance's other calls alone. */\n  signal?: AbortSignal\n  urlTemplate?: string\n  urlParams?: UrlParams\n  sortBy?: string\n  sortDesc?: boolean\n  batchSize?: number\n  forceElastic?: boolean\n}\n\n/**\n * Carries the url of the page a failure happened on out to the catch that reports it.\n *\n * Nothing outside this file sees it: the catch unwraps it before mapping, so the caller gets the\n * same classes it would get from any other helper.\n */\nclass PageFailure extends Error {\n  readonly pageUrl: string\n  readonly failure: unknown\n  /**\n   * The config axios used for this page, when the page answered and it was this helper that\n   * refused what came back. A page that failed in transport needs none: axios kept its own.\n   */\n  readonly dispatched?: AxiosRequestConfig\n\n  constructor(pageUrl: string, failure: unknown, dispatched?: AxiosRequestConfig) {\n    super('Batch page failed')\n    this.name = 'PageFailure'\n    this.pageUrl = pageUrl\n    this.failure = failure\n    this.dispatched = dispatched\n  }\n}\n\nexport const useApiFetchListBatch = <T>(params: UseApiFetchListBatchParams): UseApiFetchListBatchReturnType<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    filterData: FilterData<any>,\n    filterConfig: FilterConfig<any>,\n    fetchParams: FetchListBatchParams = {}\n  ): Promise<T[]> => {\n    const {\n      urlTemplate: urlTemplateOverride,\n      urlParams: urlParamsOverride,\n      sortBy = 'id',\n      sortDesc = true,\n      batchSize = 100,\n      forceElastic = false,\n      signal,\n    } = fetchParams\n\n    try {\n      return await abortable.run(async (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 a call that throws on a missing\n        // template or a malformed filter config would otherwise leave its predecessor running.\n        // Inside the try as well, so that failure arrives as the same error class as every other.\n        const template = isDefined(urlTemplateOverride) ? urlTemplateOverride : urlTemplate\n        if (isUndefined(template)) throw new AnzuFatalError(undefined, 'Url template is undefined')\n\n        // A page size below one cannot end the walk: every page is then \"not shorter than the one\n        // asked for\", so the loop has no exit and the helper becomes an unbounded stream of\n        // requests. It is the caller's mistake, and it arrives as the same error class as the\n        // caller's other mistakes rather than as a backend that never stops answering.\n        if (batchSize < 1) throw new AnzuFatalError(undefined, 'batchSize must be at least 1, got ' + batchSize)\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        // One instance for the whole batch: a call is one call, and a factory that answers\n        // differently per page would have its pages talking to two backends.\n        const instance = client()\n\n        const { pagination } = usePagination(sortBy, sortDesc ? SortOrder.Desc : SortOrder.Asc, {\n          rowsPerPage: batchSize,\n        })\n\n        // The page's own url travels with its response: a batch that failed on page three has to\n        // be able to say which page that was, and the base url cannot.\n        const get = async (page: Ref<Pagination>) => {\n          const pageUrl = baseUrl + generateListQuery(page, filterData, filterConfig)\n\n          try {\n            return { res: await instance.get(pageUrl, { ...ownedByHelper(options), signal: abortSignal }), pageUrl }\n          } catch (err: unknown) {\n            // Tagged here, where the page is still known. A shared variable cannot do this job: the\n            // counted branch dispatches every page before any of them answers, so it would always\n            // hold the last one and name the wrong page for the one that actually failed.\n            throw new PageFailure(pageUrl, err)\n          }\n        }\n\n        // The url the report will name for this page, so a message and the context beside it cannot\n        // disagree about which request failed when an interceptor rewrote it on the way out.\n        const asSent = (res: AxiosResponse, pageUrl: string) =>\n          requestedUrl(client, pageUrl, options, undefined, res.config)\n\n        // Every page is read the same way, the ones after the first included: a 2xx with no body at\n        // all has broken its contract, wherever in the sequence it sits -- a server that fails on\n        // page three is not \"finished\". The 204 branch is defensive rather than expected: these\n        // backends answer an empty list as a 200 with a body, so a list never arrives as a 204, and\n        // the branch is here for an endpoint that one day does.\n\n        const readPage = (res: AxiosResponse, pageUrl: string) => {\n          if (!isValidHTTPStatus(res.status)) {\n            throw new PageFailure(pageUrl, new AnzuApiResponseCodeError(res.status), res.config)\n          }\n          if (res.status === HTTP_STATUS_NO_CONTENT) {\n            return {\n              items: [] as T[],\n              mode: 'unknown' as const,\n              totalCount: 0,\n              hasNextPage: false,\n              countIsBound: false,\n              empty: true,\n            }\n          }\n          if (!hasBody(res)) {\n            throw new PageFailure(\n              pageUrl,\n              new AnzuApiResponseCodeError(\n                res.status,\n                undefined,\n                'Expected a response body, url: ' + asSent(res, pageUrl)\n              ),\n              res.config\n            )\n          }\n\n          let body\n          try {\n            body = readListBody<T>(res.data, res.status, asSent(res, pageUrl))\n          } catch (err: unknown) {\n            throw new PageFailure(pageUrl, err, res.config)\n          }\n\n          return {\n            items: body.items,\n            mode: body.mode,\n            totalCount: body.pagination.totalCount ?? 0,\n            hasNextPage: body.pagination.hasNextPage === true,\n            countIsBound: body.countIsBound,\n            empty: false,\n          }\n        }\n\n        const firstPage = await get(pagination)\n        const first = readPage(firstPage.res, firstPage.pageUrl)\n        const results: T[] = [...first.items]\n        if (first.empty) return results\n\n        // A first page shorter than the one asked for means the offsets cannot be trusted: every page\n        // after it is addressed by arithmetic on a page size, and the server has just shown that the\n        // size it uses is not the size requested. Read as the server's real page size -- a capped\n        // `limit`, which backends do -- and taken from page one, which has already answered.\n        //\n        // Before the branch, not inside it: both ways of walking a list address their pages this way,\n        // and hardening one of them is how the counted branch was fixed while the infinite one went\n        // on losing rows.\n        //\n        // It is a reading, not a fact. The other reading would be a server that applies `limit` and\n        // then drops rows -- permissions, soft deletes -- while counting `totalCount` before that:\n        // its window really is the requested size, so stepping by the shorter one overlaps and rows\n        // repeat at each boundary. A sweep of the shared path found no such dropping, so the reading\n        // taken here is the one these backends support; the trade is deliberate anyway, because\n        // repeated rows are visible to whoever reads the list and missing ones are not.\n        //\n        // What the ambiguity does buy is the caution below: once the arithmetic is in doubt, the\n        // pages are walked one at a time rather than fired off together, so a wrong guess costs\n        // requests one by one rather than a burst of them, and stops at the first empty page.\n        const capped = first.items.length > 0 && first.items.length < pagination.value.rowsPerPage\n        if (capped) pagination.value.rowsPerPage = first.items.length\n\n        // Infinite lists walk page by page, because only the answer says whether another exists.\n        if (first.mode === 'infinite') {\n          let hasNextPage = first.hasNextPage\n          while (hasNextPage) {\n            pagination.value.page++\n            const nextPage = await get(pagination)\n            const next = readPage(nextPage.res, nextPage.pageUrl)\n            results.push(...next.items)\n            if (next.empty) break\n            hasNextPage = next.hasNextPage\n          }\n\n          return results\n        }\n\n        // A list that named neither mode has said nothing about further pages, so the first is all\n        // there is.\n        if (first.mode !== 'counted') return results\n\n        // Two ways the count cannot be divided into a page count. The server may have said so itself\n        // -- `bigTable`, which is on by default, makes `totalCount` a look-ahead of `offset + limit + 1`\n        // rather than a total, corrected to the real number only on the page that comes back short.\n        // Dividing that by the page size answers 2, whatever the list's real length: a batch over\n        // 5000 rows would return 200 of them and resolve as though it were finished. Or the page size\n        // itself had to be guessed, in which case the count divides by a number the server has\n        // already contradicted.\n        //\n        // Either way the walk is sequential and ends where the data does -- a page shorter than the\n        // one asked for is the server saying there is no more, and it is the same signal the\n        // repository uses to correct the count in the first place.\n        // Already holding as many rows as the count names, so there is nothing to walk to. This is\n        // also what makes a short first page unambiguous: the repository corrects `totalCount` to the\n        // real total exactly when a page comes back shorter than the limit it applied, so a list that\n        // simply ends satisfies this, while a server that capped the limit reports its look-ahead\n        // instead and does not.\n        if (results.length >= first.totalCount) return results\n\n        if (capped || first.countIsBound) {\n          for (;;) {\n            pagination.value.page++\n            const nextPage = await get(pagination)\n            const next = readPage(nextPage.res, nextPage.pageUrl)\n            results.push(...next.items)\n            if (next.items.length < pagination.value.rowsPerPage) break\n          }\n\n          return results\n        }\n\n        // Counted lists know how many pages there are, so the rest go out together.\n        const pageCount = Math.ceil(first.totalCount / pagination.value.rowsPerPage)\n        if (pageCount <= 1) return results\n\n        // Each page is read as it arrives, not after all of them have. Reading them afterwards meant\n        // a page that answered with a broken body was not noticed until every sibling had settled --\n        // and a sibling that never answers made that never, so the call hung on a failure it was\n        // already holding. Rejecting here reaches `run`, which stops the siblings.\n        const rest = await Promise.all(\n          Array.from({ length: pageCount - 1 }, (_unused, index) =>\n            get(ref({ ...pagination.value, page: index + 2 })).then((page) => readPage(page.res, page.pageUrl))\n          )\n        )\n        // A 204 among them contributes nothing and the others are kept -- there is no sequence to\n        // stop here, they all went out at once.\n        rest.forEach((page) => results.push(...page.items))\n\n        return results\n      }, signal)\n    } catch (err: unknown) {\n      const failed = err instanceof PageFailure ? err : null\n      // Only a page can name a url here, and it names its own. The base url is not an answer: it was\n      // never requested, and a failure that belongs to no page -- a missing template, a filter config\n      // that will not render -- happened before any page existed. Nothing else can fail after a page\n      // has gone out, because everything from the dispatch onwards is tagged as a `PageFailure`.\n      const context = {\n        system,\n        entity,\n        validationSystem,\n        validationEntity,\n        url: requestedUrl(client, failed?.pageUrl, options, failed?.failure ?? err, failed?.dispatched),\n      }\n\n      throw report(mapApiError(failed?.failure ?? err, context), context)\n    }\n  }\n\n  return { execute, abort: abortable.abort, loading: abortable.loading }\n}\n\nexport type UseApiFetchListBatchReturnType<T> = {\n  execute: (filterData: FilterData<any>, filterConfig: FilterConfig<any>, params?: FetchListBatchParams) => Promise<T[]>\n  abort: () => void\n  /**\n   * True while this instance is working, false once it stops.\n   *\n   * Here that is the whole walk, not one request: a batch reads every page, and the flag stays up\n   * across the gaps between them and across the reading of each answer.\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":";;;;;;;;;;;;;;AAgDA,IAAMA,IAAN,cAA0B,MAAM;CAC9B;CACA;CAKA;CAEA,YAAY,GAAiB,GAAkB,GAAiC;EAK9E,AAJA,MAAM,mBAAmB,GACzB,KAAK,OAAO,eACZ,KAAK,UAAUC,GACf,KAAK,UAAUC,GACf,KAAK,aAAaC;CACpB;AACF,GAEaC,KAA2B,MAA0E;CAChH,IAAM,EACJ,WACA,WACA,WACA,qBACA,qBACA,gBACA,cACA,aAAU,CAAC,GACX,oBAAiB,OACfC,GACEC,IAAYC,EAAgB,EAAE,kBAAe,CAAC;CAkOpD,OAAO;EAAE,gBA/NP,GACA,GACA,IAAoC,CAAC,MACpB;GACjB,IAAM,EACJ,aAAaC,GACb,WAAWC,GACX,YAAS,MACT,cAAW,IACX,eAAY,KACZ,kBAAe,IACf,cACEC;GAEJ,IAAI;IACF,OAAO,MAAMJ,EAAU,IAAI,OAAO,MAAgB;KAKhD,IAAMK,IAAWC,EAAUJ,CAAmB,IAAIA,IAAsBK;KACxE,IAAIC,EAAYH,CAAQ,GAAG,MAAM,IAAII,EAAe,KAAA,GAAW,2BAA2B;KAM1F,IAAIC,IAAY,GAAG,MAAM,IAAID,EAAe,KAAA,GAAW,uCAAuCC,CAAS;KAEvG,IAAMC,IAAiBL,EAAUH,CAAiB,IAAIA,IAAoBS,GACpEC,IAAYC,EAAa,QAAQ,WAAWC,IAAe,YAAY,IACvEC,KACHR,EAAYG,CAAc,IAAIN,IAAWY,EAAqBZ,GAAUM,CAAc,KAAKE,GAGxFK,IAAWC,EAAO,GAElB,EAAE,kBAAeC,EAAcC,GAAQC,IAAWC,EAAU,OAAOA,EAAU,KAAK,EACtF,aAAab,EACf,CAAC,GAIKc,IAAM,OAAO,MAA0B;MAC3C,IAAM7B,IAAUqB,IAAUS,EAAkBC,GAAMC,GAAYb,CAAY;MAE1E,IAAI;OACF,OAAO;QAAE,KAAK,MAAMI,EAAS,IAAIvB,GAAS;SAAE,GAAGiC,EAAcC,CAAO;SAAG,QAAQC;QAAY,CAAC;QAAG;OAAQ;MACzG,SAASC,GAAc;OAIrB,MAAM,IAAIrC,EAAYC,GAASoC,CAAG;MACpC;KACF,GAIMC,KAAU,GAAoB,MAClCC,EAAad,GAAQxB,GAASkC,GAAS,KAAA,GAAWK,EAAI,MAAM,GAQxDC,KAAY,GAAoB,MAAoB;MACxD,IAAI,CAACC,EAAkBF,EAAI,MAAM,GAC/B,MAAM,IAAIxC,EAAYC,GAAS,IAAI0C,EAAyBH,EAAI,MAAM,GAAGA,EAAI,MAAM;MAErF,IAAIA,EAAI,WAAA,KACN,OAAO;OACL,OAAO,CAAC;OACR,MAAM;OACN,YAAY;OACZ,aAAa;OACb,cAAc;OACd,OAAO;MACT;MAEF,IAAI,CAACI,EAAQJ,CAAG,GACd,MAAM,IAAIxC,EACRC,GACA,IAAI0C,EACFH,EAAI,QACJ,KAAA,GACA,oCAAoCF,EAAOE,GAAKvC,CAAO,CACzD,GACAuC,EAAI,MACN;MAGF,IAAIK;MACJ,IAAI;OACF,IAAOC,EAAgBN,EAAI,MAAMA,EAAI,QAAQF,EAAOE,GAAKvC,CAAO,CAAC;MACnE,SAASoC,GAAc;OACrB,MAAM,IAAIrC,EAAYC,GAASoC,GAAKG,EAAI,MAAM;MAChD;MAEA,OAAO;OACL,OAAOK,EAAK;OACZ,MAAMA,EAAK;OACX,YAAYA,EAAK,WAAW,cAAc;OAC1C,aAAaA,EAAK,WAAW,gBAAgB;OAC7C,cAAcA,EAAK;OACnB,OAAO;MACT;KACF,GAEME,IAAY,MAAMjB,EAAIkB,CAAU,GAChCC,IAAQR,EAASM,EAAU,KAAKA,EAAU,OAAO,GACjDG,IAAe,CAAC,GAAGD,EAAM,KAAK;KACpC,IAAIA,EAAM,OAAO,OAAOC;KAqBxB,IAAMC,IAASF,EAAM,MAAM,SAAS,KAAKA,EAAM,MAAM,SAASD,EAAW,MAAM;KAI/E,IAHIG,MAAQ,EAAW,MAAM,cAAcF,EAAM,MAAM,SAGnDA,EAAM,SAAS,YAAY;MAC7B,IAAIG,IAAcH,EAAM;MACxB,OAAOG,IAAa;OAClB,EAAW,MAAM;OACjB,IAAMC,IAAW,MAAMvB,EAAIkB,CAAU,GAC/BM,IAAOb,EAASY,EAAS,KAAKA,EAAS,OAAO;OAEpD,IADAH,EAAQ,KAAK,GAAGI,EAAK,KAAK,GACtBA,EAAK,OAAO;OAChB,IAAcA,EAAK;MACrB;MAEA,OAAOJ;KACT;KAsBA,IAlBID,EAAM,SAAS,aAkBfC,EAAQ,UAAUD,EAAM,YAAY,OAAOC;KAE/C,IAAIC,KAAUF,EAAM,cAAc;MAChC,SAAS;OACP,EAAW,MAAM;OACjB,IAAMI,IAAW,MAAMvB,EAAIkB,CAAU,GAC/BM,IAAOb,EAASY,EAAS,KAAKA,EAAS,OAAO;OAEpD,IADAH,EAAQ,KAAK,GAAGI,EAAK,KAAK,GACtBA,EAAK,MAAM,SAASN,EAAW,MAAM,aAAa;MACxD;MAEA,OAAOE;KACT;KAGA,IAAMK,IAAY,KAAK,KAAKN,EAAM,aAAaD,EAAW,MAAM,WAAW;KAgB3E,OAfIO,KAAa,MAajB,MAPmB,QAAQ,IACzB,MAAM,KAAK,EAAE,QAAQA,IAAY,EAAE,IAAI,GAAS,MAC9CzB,EAAI0B,EAAI;MAAE,GAAGR,EAAW;MAAO,MAAMS,IAAQ;KAAE,CAAC,CAAC,CAAC,CAAC,MAAM,MAAShB,EAAST,EAAK,KAAKA,EAAK,OAAO,CAAC,CACpG,CACF,EAAA,CAGK,SAAS,MAASkB,EAAQ,KAAK,GAAGlB,EAAK,KAAK,CAAC,GAE3CkB;IACT,GAAGQ,CAAM;GACX,SAASrB,GAAc;IACrB,IAAMsB,IAAStB,aAAerC,IAAcqC,IAAM,MAK5CuB,IAAU;KACd;KACA;KACA;KACA;KACA,KAAKrB,EAAad,GAAQkC,GAAQ,SAASxB,GAASwB,GAAQ,WAAWtB,GAAKsB,GAAQ,UAAU;IAChG;IAEA,MAAME,EAAOC,EAAYH,GAAQ,WAAWtB,GAAKuB,CAAO,GAAGA,CAAO;GACpE;EACF;EAEkB,OAAOtD,EAAU;EAAO,SAASA,EAAU;CAAQ;AACvE"}

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

@@ -0,0 +1,19 @@
+import { FilterConfig, FilterData, FilterVariant } from '../../filters/composables/filterFactory';
+import { DatetimeUTCNullable } from '../../../shared/types/common';
+/**
+ * Docs: /doc/Admin-Cms-Doc/Filters.md
+ */
+export declare function useApiQueryBuilder(): {
+    resolveTimeIntervalFilter: (fromName: string, untilName: string, filterData: FilterData<any>, filterConfig: FilterConfig<any>, mandatory: boolean, exclude: boolean) => null | {
+        from: DatetimeUTCNullable;
+        until: DatetimeUTCNullable;
+    };
+    querySetLimit: (value: number) => void;
+    querySetOffset: (page: number, limit: number) => void;
+    querySetOrder: (field: string | null, desc: boolean) => void;
+    queryAddFilter: (filterVariant: FilterVariant, field: string, value: string | number | boolean) => void;
+    querySetFilters: (filterData: FilterData<any>, filterConfig: FilterConfig<any>) => void;
+    queryAdd: (key: string, value: any) => void;
+    queryBuild: () => string;
+    q: import('vue').Ref<string[], string[]>;
+};

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

@@ -0,0 +1,75 @@
+import { isArray as e, isBoolean as t, isNull as n, isNumber as r, isString as i, isUndefined as a } from "../../../shared/utils/common.js";
+import { dateModifyMinutes as o, dateTimeNow as s, dateTimeToDate as c, dateToUtc as l, getMonthInterval as u } from "../../../shared/utils/datetime.js";
+import { SortOrder as d } from "../types/SortOrder.js";
+import { TimeIntervalSpecialOptions as f } from "../../filters/composables/filterTimeIntervalTools.js";
+import { ref as p } from "vue";
+//#region src/domains/api/composables/useApiQueryBuilder.ts
+function m() {
+	let m = p([]), h = (e) => {
+		C("limit", e);
+	}, g = (e, t) => {
+		C("offset", Math.max(0, (e - 1) * t));
+	}, _ = (e, t) => {
+		!n(e) && e.length > 0 && C("order[" + e + "]", t ? d.Desc : d.Asc);
+	}, v = (e) => t(e) ? e ? "1" : "0" : e, y = (e, t, n) => {
+		i(n) && n.length === 0 || m.value.push("filter_" + e + "[" + t + "]=" + v(n));
+	}, b = (e, t) => {
+		let n = e.fields[t];
+		if (a(n)) throw Error(`useApiQueryBuilder: filter field "${t}" is not configured`);
+		return n;
+	}, x = (e, t, a, d, p, m) => {
+		let h = a[e], g = a[t];
+		if (n(h) && p && !m && (h = b(d, e).default), n(g) && p && !m && (g = b(d, t).default), i(h) && i(g)) return {
+			from: h,
+			until: g
+		};
+		let _ = s(), v = c(_);
+		switch (h) {
+			case f.CurrentMonth: return u(v, "utc", 0, !1);
+			case f.LastMonth: return u(v, "utc", -1, !1);
+			case f.Last3Months: return u(v, "utc", -2, !0);
+			default: if (r(h)) return {
+				from: l(o(h * -1, v)),
+				until: _
+			};
+		}
+		return null;
+	}, S = (o, s) => n(o) ? s.mandatory && !s.exclude && !a(s.default) ? e(s.default) ? s.default.join(",") : s.default : null : i(o) ? o.length === 0 ? s.mandatory && !s.exclude && !a(s.default) && !n(s.default) ? encodeURIComponent(e(s.default) ? s.default.join(",") : s.default) : null : encodeURIComponent(o) : e(o) ? o.length === 0 ? s.mandatory && !s.exclude && e(s.default) ? s.default.map((e) => i(e) ? encodeURIComponent(e) : e).join(",") : null : o.map((e) => i(e) ? encodeURIComponent(e) : e).join(",") : r(o) || t(o) ? o : null, C = (e, t) => {
+		m.value.push(e + "=" + t);
+	};
+	return {
+		resolveTimeIntervalFilter: x,
+		querySetLimit: h,
+		querySetOffset: g,
+		querySetOrder: _,
+		queryAddFilter: y,
+		querySetFilters: (e, t) => {
+			let r = t.general.simpleFilters;
+			for (let i in e) {
+				let o = e[i], s = t.fields[i];
+				if (a(s) || s.exclude) continue;
+				let c = s.apiName || i;
+				if (s.type === "timeInterval" && !a(s.related)) {
+					let a = x(i, s.related, e, t, s.mandatory, s.exclude);
+					if (n(a)) continue;
+					let o = b(t, s.related).apiName || s.related;
+					if (r) {
+						C(c, a.from), C(o, a.until);
+						continue;
+					}
+					a.from && y("gte", c, a.from), a.until && y("lte", o, a.until);
+					continue;
+				}
+				let l = S(o, s);
+				n(l) || (r ? C(c, l) : y(s.variant, c, l));
+			}
+		},
+		queryAdd: C,
+		queryBuild: () => "?" + m.value.join("&"),
+		q: m
+	};
+}
+//#endregion
+export { m as useApiQueryBuilder };
+
+//# sourceMappingURL=useApiQueryBuilder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useApiQueryBuilder.js","names":["useApiQueryBuilder","q","ref","querySetLimit","value","querySetOffset","page","limit","querySetOrder","isNull","field","queryAdd","desc","SortOrder","formatValue","isBoolean","queryAddFilter","isString","filterVariant","fieldConfig","filterConfig","name","isUndefined","resolveTimeIntervalFilter","fromValue","filterData","fromName","untilValue","untilName","mandatory","exclude","now","dateTimeNow","nowDate","dateTimeToDate","TimeIntervalSpecialOptions","getMonthInterval","isNumber","dateToUtc","dateModifyMinutes","getValue","config","isArray","item","key","isSimpleFilters","filterName","filterFieldValue","filterFieldConfig","data","nameRelated"],"sources":["../../../../src/domains/api/composables/useApiQueryBuilder.ts"],"sourcesContent":["import { ref } from 'vue'\nimport { isArray, isBoolean, isNull, isNumber, isString, isUndefined } from '@/shared/utils/common'\nimport type {\n  AllowedFilterValues,\n  FilterConfig,\n  FilterData,\n  FilterField,\n  FilterVariant,\n} from '@/domains/filters/composables/filterFactory'\nimport type { DatetimeUTCNullable } from '@/shared/types/common'\nimport {\n  TimeIntervalSpecialOptions,\n  type TimeIntervalToolsValue,\n} from '@/domains/filters/composables/filterTimeIntervalTools'\nimport { dateModifyMinutes, dateTimeNow, dateTimeToDate, dateToUtc, getMonthInterval } from '@/shared/utils/datetime'\nimport { SortOrder } from '@/domains/api/types/SortOrder'\n\n/**\n * Docs: /doc/Admin-Cms-Doc/Filters.md\n */\nexport function useApiQueryBuilder() {\n  const q = ref<string[]>([])\n\n  const querySetLimit = (value: number): void => {\n    queryAdd('limit', value)\n  }\n\n  const querySetOffset = (page: number, limit: number): void => {\n    queryAdd('offset', Math.max(0, (page - 1) * limit))\n  }\n\n  const querySetOrder = (field: string | null, desc: boolean): void => {\n    if (!isNull(field) && field.length > 0) queryAdd('order[' + field + ']', desc ? SortOrder.Desc : SortOrder.Asc)\n  }\n\n  const formatValue = (value: string | number | boolean): string | number => {\n    if (isBoolean(value)) {\n      return value ? '1' : '0'\n    }\n    return value\n  }\n\n  const queryAddFilter = (filterVariant: FilterVariant, field: string, value: string | number | boolean): void => {\n    if (isString(value) && value.length === 0) return\n    q.value.push('filter_' + filterVariant + '[' + field + ']=' + formatValue(value))\n  }\n\n  // `resolveTimeIntervalFilter` is returned, so any caller can pass any names: a missing one fails by name.\n  const fieldConfig = (filterConfig: FilterConfig<any>, name: string) => {\n    const field = filterConfig.fields[name]\n    if (isUndefined(field)) throw new Error(`useApiQueryBuilder: filter field \"${name}\" is not configured`)\n    return field\n  }\n\n  const resolveTimeIntervalFilter = (\n    fromName: string,\n    untilName: string,\n    filterData: FilterData<any>,\n    filterConfig: FilterConfig<any>,\n    mandatory: boolean,\n    exclude: boolean\n  ): null | {\n    from: DatetimeUTCNullable\n    until: DatetimeUTCNullable\n  } => {\n    let fromValue = filterData[fromName] as TimeIntervalToolsValue\n    let untilValue = filterData[untilName] as DatetimeUTCNullable\n    if (isNull(fromValue) && mandatory && !exclude) {\n      fromValue = fieldConfig(filterConfig, fromName).default as TimeIntervalToolsValue\n    }\n    if (isNull(untilValue) && mandatory && !exclude) {\n      untilValue = fieldConfig(filterConfig, untilName).default as DatetimeUTCNullable\n    }\n    if (isString(fromValue) && isString(untilValue)) {\n      return {\n        from: fromValue,\n        until: untilValue,\n      }\n    }\n    const now = dateTimeNow()\n    const nowDate = dateTimeToDate(now)\n    switch (fromValue) {\n      case TimeIntervalSpecialOptions.CurrentMonth: {\n        return getMonthInterval(nowDate, 'utc', 0, false)\n      }\n      case TimeIntervalSpecialOptions.LastMonth: {\n        return getMonthInterval(nowDate, 'utc', -1, false)\n      }\n      case TimeIntervalSpecialOptions.Last3Months: {\n        return getMonthInterval(nowDate, 'utc', -2, true)\n      }\n      default: {\n        if (isNumber(fromValue)) {\n          return {\n            from: dateToUtc(dateModifyMinutes(fromValue * -1, nowDate)),\n            until: now,\n          }\n        }\n      }\n    }\n    return null\n  }\n\n  const getValue = (value: AllowedFilterValues, config: FilterField): string | number | boolean | null => {\n    if (isNull(value)) {\n      if (config.mandatory && !config.exclude && !isUndefined(config.default)) {\n        return isArray(config.default) ? config.default.join(',') : config.default\n      }\n      return null\n    }\n    if (isString(value)) {\n      if (value.length === 0) {\n        if (config.mandatory && !config.exclude && !isUndefined(config.default) && !isNull(config.default)) {\n          return encodeURIComponent(isArray(config.default) ? config.default.join(',') : config.default)\n        }\n        return null\n      }\n      return encodeURIComponent(value)\n    }\n    if (isArray(value)) {\n      if (value.length === 0) {\n        if (config.mandatory && !config.exclude && isArray(config.default)) {\n          return config.default.map((item) => (isString(item) ? encodeURIComponent(item) : item)).join(',')\n        }\n        return null\n      }\n      return value.map((item) => (isString(item) ? encodeURIComponent(item) : item)).join(',')\n    }\n    if (isNumber(value) || isBoolean(value)) {\n      return value\n    }\n\n    return null\n  }\n\n  const queryAdd = (key: string, value: any): void => {\n    q.value.push(key + '=' + value)\n  }\n\n  const queryBuild = (): string => {\n    return '?' + q.value.join('&')\n  }\n\n  const querySetFilters = (filterData: FilterData<any>, filterConfig: FilterConfig<any>): void => {\n    const isSimpleFilters = filterConfig.general.simpleFilters\n    for (const filterName in filterData) {\n      const filterFieldValue = filterData[filterName] as AllowedFilterValues\n      const filterFieldConfig = filterConfig.fields[filterName]\n      if (isUndefined(filterFieldConfig) || filterFieldConfig.exclude) {\n        continue\n      }\n      const name = filterFieldConfig.apiName || filterName\n      if (filterFieldConfig.type === 'timeInterval' && !isUndefined(filterFieldConfig.related)) {\n        const data = resolveTimeIntervalFilter(\n          filterName,\n          filterFieldConfig.related,\n          filterData,\n          filterConfig,\n          filterFieldConfig.mandatory,\n          filterFieldConfig.exclude\n        )\n        if (isNull(data)) {\n          continue\n        }\n        const filterFieldConfigRelated = fieldConfig(filterConfig, filterFieldConfig.related)\n        const nameRelated = filterFieldConfigRelated.apiName || filterFieldConfig.related\n        if (isSimpleFilters) {\n          queryAdd(name, data.from)\n          queryAdd(nameRelated, data.until)\n          continue\n        }\n        if (data.from) queryAddFilter('gte', name, data.from)\n        if (data.until) {\n          queryAddFilter('lte', nameRelated, data.until)\n        }\n        continue\n      }\n      const value = getValue(filterFieldValue, filterFieldConfig)\n      if (isNull(value)) {\n        continue\n      }\n      if (isSimpleFilters) {\n        queryAdd(name, value)\n        continue\n      }\n      queryAddFilter(filterFieldConfig.variant, name, value)\n    }\n  }\n\n  return {\n    resolveTimeIntervalFilter,\n    querySetLimit,\n    querySetOffset,\n    querySetOrder,\n    queryAddFilter,\n    querySetFilters,\n    queryAdd,\n    queryBuild,\n    q,\n  }\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,87 @@
+import { UrlParams } from '../utils/apiHelper';
+import { AxiosRequestConfig, Method } from 'axios';
+import { Ref } from 'vue';
+import { AxiosClientFn } from '../utils/client';
+export type ExecuteRequestParams<B> = {
+    urlTemplate?: string;
+    urlParams?: UrlParams;
+    body?: B;
+    /** 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.
+     *
+     * For a caller that repeats a request on a timer and has reported its first failure already: a poll that
+     * asks every few seconds through an outage would otherwise write the same failure down each time. It is the
+     * caller's to say which call that is, call by call; it is not a way to make a kind of request quiet, and an
+     * instance has no such switch.
+     */
+    report?: boolean;
+};
+export type UseApiRequestParams = {
+    client: AxiosClientFn;
+    method: Method;
+    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'>;
+    /** Each call supersedes the one before it -- the autocomplete shape. */
+    cancelPrevious?: boolean;
+};
+export type UseApiRequestReturnType<R, B> = {
+    execute: (params?: ExecuteRequestParams<B>) => Promise<R>;
+    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>;
+};
+/**
+ * A request to an endpoint that always answers with a body.
+ *
+ * A response without one is the endpoint breaking its own contract, not an empty answer, so it fails
+ * like any other error rather than handing back a value the declared type does not admit. An
+ * endpoint that answers nothing is `useApiCommand`; one that may answer either is `optionalBody`.
+ *
+ * `R` excludes `null`, `undefined` and `void` on purpose: those are ways of saying "no body", and a
+ * caller saying that has chosen the wrong helper. It is also what makes the migration visible --
+ * every `useApiRequest<void, …>` in the fleet stops compiling and names itself.
+ */
+export declare function useApiRequest<R extends NonNullable<unknown>, B = never>(params: UseApiRequestParams & {
+    optionalBody?: false;
+}): UseApiRequestReturnType<R, B>;
+/**
+ * The same, for an endpoint where a body is optional and its absence is a legitimate answer. The
+ * caller narrows, which is the point -- use it only where the endpoint really is documented that way.
+ */
+export declare function useApiRequest<R extends NonNullable<unknown>, B = never>(params: UseApiRequestParams & {
+    optionalBody: true;
+}): UseApiRequestReturnType<R | undefined, B>;
+/**
+ * A request that asks the backend to do something and reads nothing back -- a delete, or a call that
+ * only starts work and answers 202. Any successful status resolves; a body, if one arrives, is
+ * ignored rather than typed.
+ */
+export declare const useApiCommand: <B = never>(params: UseApiRequestParams) => UseApiRequestReturnType<void, B>;

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

@@ -0,0 +1,62 @@
+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";
+//#region src/domains/api/composables/useApiRequest.ts
+var p = (u, p) => {
+	let { client: m, method: h, system: g, entity: _, validationSystem: v, validationEntity: y, urlTemplate: b, urlParams: x, options: S = {}, cancelPrevious: C = !1 } = u, w = l({ cancelPrevious: C });
+	return {
+		execute: async (l = {}) => {
+			let { urlTemplate: u, urlParams: C, body: T, signal: E, report: D = !0 } = l, O = e(u) ? u : b, k = e(C) ? C : x, A, j;
+			try {
+				let s = await w.run((i) => {
+					if (n(O)) throw new r(void 0, "Url template is undefined");
+					let o = O !== "" && e(k) ? a(O, k) : O, s = {
+						method: h,
+						url: o
+					};
+					!t(T) && !n(T) && (s.data = JSON.stringify(T));
+					let c = {
+						...d(S),
+						...s,
+						signal: i
+					}, l = m();
+					return A = o, l.request(c);
+				}, E);
+				if (j = s.config, !o(s.status)) throw new i(s.status);
+				return p(s, () => f(m, A, S, void 0, j));
+			} catch (e) {
+				let t = {
+					system: g,
+					entity: _,
+					validationSystem: v,
+					validationEntity: y,
+					url: f(m, A, S, e, j)
+				}, n = s(e, t);
+				throw D ? c(n, t) : n;
+			}
+		},
+		abort: w.abort,
+		loading: w.loading
+	};
+};
+function m(e) {
+	let t = e.optionalBody === !0;
+	return p(e, (e, n) => {
+		if (e.status === 204) {
+			if (t) return;
+			throw new i(e.status);
+		}
+		if (u(e)) return e.data;
+		if (!t) throw new i(e.status, void 0, "Expected a response body, url: " + n());
+	});
+}
+var h = (e) => p(e, () => void 0);
+//#endregion
+export { h as useApiCommand, m as useApiRequest };
+
+//# sourceMappingURL=useApiRequest.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useApiRequest.js","names":["createRequest","params","abortable","createAbortable","templateOverride","paramsOverride","reported","executeParams","template","isDefined","urlTemplate","resolvedParams","urlParams","url","dispatched","res","isUndefined","AnzuFatalError","requestUrl","replaceUrlParameters","axiosConfig","isNull","body","config","ownedByHelper","options","abortSignal","instance","client","signal","isValidHTTPStatus","AnzuApiResponseCodeError","interpret","requestedUrl","err","context","error","mapApiError","report","useApiRequest","optionalBody","hasBody","useApiCommand"],"sources":["../../../../src/domains/api/composables/useApiRequest.ts"],"sourcesContent":["import { AnzuApiResponseCodeError } from '@/shared/error/AnzuApiResponseCodeError'\nimport { AnzuFatalError } from '@/shared/error/AnzuFatalError'\nimport { replaceUrlParameters, type UrlParams } from '@/domains/api/utils/apiHelper'\nimport { isDefined, isNull, isUndefined } from '@/shared/utils/common'\nimport { isValidHTTPStatus } from '@/domains/api/utils/response'\nimport type { AxiosRequestConfig, Method } from 'axios'\nimport { HTTP_STATUS_NO_CONTENT } from '@/shared/statusCodes'\nimport type { Ref } from 'vue'\nimport type { AxiosClientFn } from '@/domains/api/utils/client'\nimport { mapApiError, report } from '@/domains/api/utils/apiErrors'\nimport {\n  type Abortable,\n  createAbortable,\n  hasBody,\n  ownedByHelper,\n  requestedUrl,\n} from '@/domains/api/composables/request'\n\nexport type ExecuteRequestParams<B> = {\n  urlTemplate?: string\n  urlParams?: UrlParams\n  body?: B\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   * For a caller that repeats a request on a timer and has reported its first failure already: a poll that\n   * asks every few seconds through an outage would otherwise write the same failure down each time. It is the\n   * caller's to say which call that is, call by call; it is not a way to make a kind of request quiet, and an\n   * instance has no such switch.\n   */\n  report?: boolean\n}\n\nexport type UseApiRequestParams = {\n  client: AxiosClientFn\n  method: Method\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  /** Each call supersedes the one before it -- the autocomplete shape. */\n  cancelPrevious?: boolean\n}\n\nexport type UseApiRequestReturnType<R, B> = {\n  execute: (params?: ExecuteRequestParams<B>) => Promise<R>\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\n// The url is only ever used to say which request the message is about, and a helper that failed\n// before it had one still has to be able to say something. Handed over as a function because\n// building it costs a render and the successful reading of a response does not need it.\ntype Interpret<R> = (res: { status: number; data: unknown }, url: () => string | undefined) => R\n\nconst createRequest = <R, B>(params: UseApiRequestParams, interpret: Interpret<R>): UseApiRequestReturnType<R, B> => {\n  const {\n    client,\n    method,\n    system,\n    entity,\n    validationSystem,\n    validationEntity,\n    urlTemplate,\n    urlParams,\n    options = {},\n    cancelPrevious = false,\n  } = params\n  const abortable: Abortable = createAbortable({ cancelPrevious })\n\n  const execute = async (executeParams: ExecuteRequestParams<B> = {}): Promise<R> => {\n    const {\n      urlTemplate: templateOverride,\n      urlParams: paramsOverride,\n      body,\n      signal,\n      report: reported = true,\n    } = executeParams\n\n    const template = isDefined(templateOverride) ? templateOverride : urlTemplate\n    const resolvedParams = isDefined(paramsOverride) ? paramsOverride : urlParams\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. An empty string is a different answer: that\n    // is a call whose url really is the client root, and it gets rendered as one.\n    let url: string | undefined\n    // The config axios used, kept for the failures this helper raises after reading the response:\n    // they are not axios errors and carry no config of their own, and rebuilding one describes the\n    // request as the client 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        // Inside `run`, and inside the try with it: `run` opens the generation and, with\n        // `cancelPrevious`, stops the call before this one, so a call that throws on its way to the\n        // wire still supersedes its predecessor instead of leaving it current. And a caller that\n        // forgot the template gets the same error class as every other failure rather than a bare\n        // `Error` nothing in the fleet is written to catch.\n        if (isUndefined(template)) throw new AnzuFatalError(undefined, 'Url template is undefined')\n        const requestUrl =\n          template !== '' && isDefined(resolvedParams) ? replaceUrlParameters(template, resolvedParams) : template\n\n        const axiosConfig: AxiosRequestConfig = { method, url: requestUrl }\n        // `null` omits the body, as it always has -- a caller that means to send JSON `null` wraps it.\n        if (!isNull(body) && !isUndefined(body)) axiosConfig.data = JSON.stringify(body)\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. The type says so too; this is for javascript\n        // callers and for anything typed loosely enough to slip past it.\n        const config = { ...ownedByHelper(options), ...axiosConfig, signal: abortSignal }\n        const instance = client()\n\n        // Recorded last, when nothing between here and the call can throw any more. A body that will\n        // not serialise, or a client factory that fails, is a request that never happened, and the\n        // report has to be able to say so rather than name a url nobody asked for.\n        url = requestUrl\n\n        return instance.request(config)\n      }, signal)\n\n      dispatched = res.config\n      if (!isValidHTTPStatus(res.status)) throw new AnzuApiResponseCodeError(res.status)\n\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      return interpret(res, () => requestedUrl(client, url, options, undefined, dispatched))\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\n/**\n * A request to an endpoint that always answers with a body.\n *\n * A response without one is the endpoint breaking its own contract, not an empty answer, so it fails\n * like any other error rather than handing back a value the declared type does not admit. An\n * endpoint that answers nothing is `useApiCommand`; one that may answer either is `optionalBody`.\n *\n * `R` excludes `null`, `undefined` and `void` on purpose: those are ways of saying \"no body\", and a\n * caller saying that has chosen the wrong helper. It is also what makes the migration visible --\n * every `useApiRequest<void, …>` in the fleet stops compiling and names itself.\n */\nexport function useApiRequest<R extends NonNullable<unknown>, B = never>(\n  params: UseApiRequestParams & { optionalBody?: false }\n): UseApiRequestReturnType<R, B>\n/**\n * The same, for an endpoint where a body is optional and its absence is a legitimate answer. The\n * caller narrows, which is the point -- use it only where the endpoint really is documented that way.\n */\nexport function useApiRequest<R extends NonNullable<unknown>, B = never>(\n  params: UseApiRequestParams & { optionalBody: true }\n): UseApiRequestReturnType<R | undefined, B>\nexport function useApiRequest<R extends NonNullable<unknown>, B = never>(\n  params: UseApiRequestParams & { optionalBody?: boolean }\n): UseApiRequestReturnType<R | undefined, B> {\n  const optionalBody = params.optionalBody === true\n\n  return createRequest<R | undefined, B>(params, (res, url) => {\n    // 204 is decided by status alone, before the body is looked at: it carries none by definition,\n    // so anything that arrived with one is not something to hand on. A 202 may legitimately carry a\n    // body, which is why it is not in here and falls through to `hasBody` like any other success.\n    if (res.status === HTTP_STATUS_NO_CONTENT) {\n      if (optionalBody) return undefined\n\n      throw new AnzuApiResponseCodeError(res.status)\n    }\n\n    if (hasBody(res)) return res.data as R\n    if (optionalBody) return undefined\n\n    throw new AnzuApiResponseCodeError(res.status, undefined, 'Expected a response body, url: ' + url())\n  })\n}\n\n/**\n * A request that asks the backend to do something and reads nothing back -- a delete, or a call that\n * only starts work and answers 202. Any successful status resolves; a body, if one arrives, is\n * ignored rather than typed.\n */\nexport const useApiCommand = <B = never>(params: UseApiRequestParams): UseApiRequestReturnType<void, B> =>\n  createRequest<void, B>(params, () => undefined)\n"],"mappings":";;;;;;;;;AAkFA,IAAMA,KAAuB,GAA6B,MAA2D;CACnH,IAAM,EACJ,WACA,WACA,WACA,WACA,qBACA,qBACA,gBACA,cACA,aAAU,CAAC,GACX,oBAAiB,OACfC,GACEC,IAAuBC,EAAgB,EAAE,kBAAe,CAAC;CA0E/D,OAAO;EAAE,gBAxEc,IAAyC,CAAC,MAAkB;GACjF,IAAM,EACJ,aAAaC,GACb,WAAWC,GACX,SACA,WACA,QAAQC,IAAW,OACjBC,GAEEC,IAAWC,EAAUL,CAAgB,IAAIA,IAAmBM,GAC5DC,IAAiBF,EAAUJ,CAAc,IAAIA,IAAiBO,GAIhEC,GAIAC;GAEJ,IAAI;IACF,IAAMC,IAAM,MAAMb,EAAU,KAAK,MAAgB;KAM/C,IAAIc,EAAYR,CAAQ,GAAG,MAAM,IAAIS,EAAe,KAAA,GAAW,2BAA2B;KAC1F,IAAMC,IACJV,MAAa,MAAMC,EAAUE,CAAc,IAAIQ,EAAqBX,GAAUG,CAAc,IAAIH,GAE5FY,IAAkC;MAAE;MAAQ,KAAKF;KAAW;KAElE,AAAI,CAACG,EAAOC,CAAI,KAAK,CAACN,EAAYM,CAAI,MAAG,EAAY,OAAO,KAAK,UAAUA,CAAI;KAK/E,IAAMC,IAAS;MAAE,GAAGC,EAAcC,CAAO;MAAG,GAAGL;MAAa,QAAQM;KAAY,GAC1EC,IAAWC,EAAO;KAOxB,OAFA,IAAMV,GAECS,EAAS,QAAQJ,CAAM;IAChC,GAAGM,CAAM;IAGT,IADA,IAAad,EAAI,QACb,CAACe,EAAkBf,EAAI,MAAM,GAAG,MAAM,IAAIgB,EAAyBhB,EAAI,MAAM;IAIjF,OAAOiB,EAAUjB,SAAWkB,EAAaL,GAAQf,GAAKY,GAAS,KAAA,GAAWX,CAAU,CAAC;GACvF,SAASoB,GAAc;IAGrB,IAAMC,IAAU;KACd;KACA;KACA;KACA;KACA,KAAKF,EAAaL,GAAQf,GAAKY,GAASS,GAAKpB,CAAU;IACzD,GAEMsB,IAAQC,EAAYH,GAAKC,CAAO;IAEtC,MAAM7B,IAAWgC,EAAOF,GAAOD,CAAO,IAAIC;GAC5C;EACF;EAEkB,OAAOlC,EAAU;EAAO,SAASA,EAAU;CAAQ;AACvE;AAuBA,SAAgBqC,EACd,GAC2C;CAC3C,IAAMC,IAAevC,EAAO,iBAAiB;CAE7C,OAAOD,EAAgCC,IAAS,GAAK,MAAQ;EAI3D,IAAIc,EAAI,WAAA,KAAmC;GACzC,IAAIyB,GAAc;GAElB,MAAM,IAAIT,EAAyBhB,EAAI,MAAM;EAC/C;EAEA,IAAI0B,EAAQ1B,CAAG,GAAG,OAAOA,EAAI;EAC7B,IAAI,IAEJ,MAAM,IAAIgB,EAAyBhB,EAAI,QAAQ,KAAA,GAAW,oCAAoCF,EAAI,CAAC;CACrG,CAAC;AACH;AAOA,IAAa6B,KAA4B,MACvC1C,EAAuBC,SAAc,KAAA,CAAS"}

package/dist/domains/api/types/ApiResponse.d.ts

@@ -0,0 +1,4 @@
+export interface ApiInfiniteResponseList<T> {
+    hasNextPage: boolean;
+    data: T;
+}

package/dist/domains/api/types/SortOrder.d.ts

@@ -0,0 +1,5 @@
+export declare const SortOrder: {
+    readonly Asc: "asc";
+    readonly Desc: "desc";
+};
+export type SortOrderType = (typeof SortOrder)[keyof typeof SortOrder];

package/dist/domains/api/types/SortOrder.js

@@ -0,0 +1,9 @@
+//#region src/domains/api/types/SortOrder.ts
+var e = {
+	Asc: "asc",
+	Desc: "desc"
+};
+//#endregion
+export { e as SortOrder };
+
+//# sourceMappingURL=SortOrder.js.map

package/dist/domains/api/types/SortOrder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SortOrder.js","names":["SortOrder"],"sources":["../../../../src/domains/api/types/SortOrder.ts"],"sourcesContent":["export const SortOrder = {\n  Asc: 'asc',\n  Desc: 'desc',\n} as const\nexport type SortOrderType = (typeof SortOrder)[keyof typeof SortOrder]\n"],"mappings":";AAAA,IAAaA,IAAY;CACvB,KAAK;CACL,MAAM;AACR"}

package/dist/domains/api/utils/apiErrors.d.ts

@@ -0,0 +1,88 @@
+import { AnzuError } from '../../../shared/error/AnzuError';
+export type ApiErrorContext = {
+    system: string;
+    entity: string;
+    /** The url actually requested, parameters substituted and query included -- not the template. */
+    url?: string;
+    /**
+     * The status the backend answered with, when it answered at all. Absent for a transport failure,
+     * where there is no response.
+     *
+     * It is here so an application can decide what is worth writing down without the call sites having
+     * to: a 404 that a caller probes for, for instance. Those used to be silenced per call, which made
+     * whether a failure was recorded depend on which call made it. The switch is the application's now,
+     * and this is what it needs to use it.
+     *
+     * Two statuses are not the application's to decide, and the library keeps them: 401 and 403. They
+     * are not an endpoint failing its contract, they are the session -- nobody is logged in, or this
+     * user may not -- and every admin in the fleet already branches on them and acts. Everything else
+     * reaches the logger and is filtered here, on this field.
+     */
+    status?: number;
+    /**
+     * The i18n scope a field-level validation failure is reported under, when it is not the same as
+     * the backend above.
+     *
+     * `AnzuApiValidationError` turns the server's field names into `<system>.<entity>.model.<field>`
+     * translation keys. For a component shared by nine backends those two are different questions:
+     * *which* backend failed -- which is what the report needs -- and *whose labels* name its fields,
+     * which for a shared form is always the library's own `common.*`. Left unset, the two stay one
+     * value, exactly as before.
+     */
+    validationSystem?: string;
+    validationEntity?: string;
+};
+export type ApiErrorLogger = (error: Error, context: ApiErrorContext) => void;
+/**
+ * What the user probe calls itself in the error context.
+ *
+ * A 404 here is an answer, not a failure -- it is how a system says "no account of yours". The
+ * default logger skips it; an app's own logger still receives it, so it filters on this together
+ * with the status rather than on the url, which would also silence a real detail read of the same
+ * path. The validation scope stays the user's, so a field error would still name a real label.
+ * Defined here, not beside the probe, so the default logger can know it without an import cycle.
+ */
+export declare const USER_PROBE_ENTITY = "anzuUserProbe";
+/** What reporting does until an application says otherwise; exported so a test can put it back. */
+export declare const defaultApiErrorLogger: ApiErrorLogger;
+/**
+ * Replaces the logger the api helpers report unexpected failures through, or turns reporting off
+ * with `null`.
+ *
+ * It is one switch for the whole family rather than a flag on each instance, which is what it
+ * replaces: whether a failure was written down used to depend on which helper made the call and how
+ * that instance happened to be constructed.
+ *
+ * An application that wants these where it can see them passes its own:
+ * `setApiErrorLogger((e, ctx) => Sentry.captureException(e, { extra: ctx }))`.
+ */
+export declare const setApiErrorLogger: (fn: ApiErrorLogger | null) => void;
+/**
+ * The HTTP status the backend answered with, read off whichever class carries it: the axios response
+ * of an `AnzuApiAxiosError`, or the `code` of an `AnzuApiResponseCodeError` (a response axios let
+ * through). `undefined` when nothing answered -- a timeout, a network failure, a cancel.
+ */
+export declare const apiErrorStatus: (error: unknown) => number | undefined;
+/**
+ * Whether `report` hands this error, once mapped, to the logger: not a timeout, a 401 or a 403, nor
+ * anything while reporting is off. For a caller that reports only the first failure of a series: a
+ * failure dropped here has told nobody, and the series begins with the first one that was written.
+ * What the application's own logger does with it is the application's.
+ */
+export declare const apiErrorIsReported: (error: unknown) => boolean;
+/**
+ * Reports an error once, after it has been mapped, and hands it back so the caller can throw it.
+ *
+ * After, not during: an error the helper raised itself -- a body that never arrived, a status it
+ * refuses -- is already an `Anzu*` class by the time it reaches the mapping, so a logger placed
+ * inside the mapping would never see the two cases it exists for.
+ */
+export declare const report: <E>(error: E, context: ApiErrorContext) => E;
+/**
+ * Turns whatever axios rejected with into one of the Anzu error classes.
+ *
+ * There used to be a copy of this inside each helper. The order of the checks is what decides which
+ * class a failure becomes, so four copies were four chances for the same failure to arrive under
+ * different names depending on which helper made the call.
+ */
+export declare const mapApiError: (err: unknown, context: ApiErrorContext) => AnzuError;

package/dist/domains/api/utils/apiErrors.js

@@ -0,0 +1,45 @@
+import { isAnzuError as e } from "../../../shared/error/AnzuError.js";
+import { AnzuFatalError as t } from "../../../shared/error/AnzuFatalError.js";
+import "../../../shared/statusCodes.js";
+import { AnzuApiForbiddenError as n, axiosErrorResponseIsForbidden as r } from "../../../shared/error/AnzuApiForbiddenError.js";
+import { AnzuApiValidationError as i, axiosErrorResponseHasValidationData as a } from "../../../shared/error/AnzuApiValidationError.js";
+import { AnzuApiResponseCodeError as o } from "../../../shared/error/AnzuApiResponseCodeError.js";
+import { AnzuApiForbiddenOperationError as s, axiosErrorResponseHasForbiddenOperationData as c } from "../../../shared/error/AnzuApiForbiddenOperationError.js";
+import { AnzuApiDependencyExistsError as l, axiosErrorResponseHasDependencyExistsData as u } from "../../../shared/error/AnzuApiDependencyExistsError.js";
+import { AnzuApiTimeoutError as d, axiosErrorIsTimeout as f } from "../../../shared/error/AnzuApiTimeoutError.js";
+import { AnzuApiAxiosError as p } from "../../../shared/error/AnzuApiAxiosError.js";
+import { AnzuApiCancelledError as m, axiosErrorIsCancelled as h } from "../../../shared/error/AnzuApiCancelledError.js";
+import { SessionExpiredError as g } from "../../../shared/error/SessionExpiredError.js";
+import { isInCauseChain as _ } from "../../../shared/error/isInCauseChain.js";
+import v from "axios";
+//#region src/domains/api/utils/apiErrors.ts
+var y = "anzuUserProbe", b = (e, t) => {
+	(t.status !== 404 || t.entity !== "anzuUserProbe") && console.error("Api error: " + (t.url ?? ""), e);
+}, x = b, S = (e) => {
+	x = e;
+}, C = [
+	p,
+	t,
+	o
+], w = (e) => {
+	if (e instanceof o) return e.code;
+	if (e instanceof p) return e.cause.response?.status;
+}, T = (e) => {
+	let t = w(e);
+	return t === 401 || t === 403 || _(e, (e) => e instanceof g) ? !1 : x !== null && C.some((t) => e instanceof t);
+}, E = (e, t) => {
+	if (x !== null && T(e)) try {
+		x(e, {
+			...t,
+			status: w(e)
+		});
+	} catch {}
+	return e;
+}, D = (o, g) => {
+	let { system: _, entity: y } = g, b = g.validationSystem ?? _, x = g.validationEntity ?? y, S = o, C = o;
+	return e(o) ? o : h(o) ? new m(S) : r(C) ? new n(C, g.url) : a(C) ? new i(C, b, x, S) : u(C) ? new l(C, b, x, S) : c(C) ? new s(C, S) : f(S) ? new d(S) : v.isAxiosError(o) ? new p(C) : new t(S);
+};
+//#endregion
+export { y as USER_PROBE_ENTITY, T as apiErrorIsReported, w as apiErrorStatus, b as defaultApiErrorLogger, D as mapApiError, E as report, S as setApiErrorLogger };
+
+//# sourceMappingURL=apiErrors.js.map