@anzusystems/common-admin 2.0.0-rc.5 → 2.0.0-rc.7

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

@@ -1 +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"}
+{"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 full url including the query, already built by the caller.\n   * `urlParams` are substituted into the path only. A placeholder in the query\n   * is sent as is. Put the value in the query or pass it via `options.params`.\n   */\n  urlTemplate?: string\n  urlParams?: UrlParams\n  options?: Omit<AxiosRequestConfig, 'method' | 'url' | 'data' | 'signal'>\n  cancelPrevious?: boolean\n  /**\n   * Defaults to `GET`.\n   * Other verbs exist because a filter too big for a url goes out\n   * as a POST, and a mutation can answer with the changed list.\n   */\n  method?: 'GET' | 'POST' | 'PUT' | 'PATCH'\n  /**\n   * Defaults to `'envelope'`, the fleet norm.\n   * The reader refuses an undeclared shape, so a forgotten `'array'` fails on the first run.\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 * Fetches a list from an endpoint whose query the caller already built, without pagination.\n * Replaces `useApiRequest<ApiResponseList<T[]>>` reads, which never checked that `data`\n * is an array. `useApiFetchList` needs pagination and filter config these calls lack.\n * `shape` is declared, and the reader refuses the other shape, so a wrong declaration fails loudly.\n * Writes no metadata. Use `useApiFetchList` for user-driven paging and `useApiFetchListBatch` to read all pages.\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` once a url exists. It stays undefined\n    // before that, so a failure before dispatch reports no url.\n    let url: string | undefined\n    let dispatched: AxiosRequestConfig | undefined\n\n    try {\n      const res = await abortable.run((abortSignal) => {\n        // Derived inside `run` because `run` opens the generation and, with `cancelPrevious`, stops the previous call.\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. To send JSON `null`, the caller wraps it.\n        const sendsBody = !isNull(body) && !isUndefined(body)\n\n        // `method` defaults to GET, so a body without `method: 'POST'` would silently send a GET without its filter.\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 the helper-owned keys, so a caller cannot override method, url, body or signal.\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, after anything that can throw. `JSON.stringify` fails on a circular\n        // body, which would otherwise be reported as a request to a url never called.\n        url = requestUrl\n\n        return instance.request(config)\n      }, signal)\n\n      dispatched = res.config\n      // The url the report names, so the message and context agree when an interceptor rewrote the request.\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. Unlike a caller-cleared\n   * `finally` flag, it does not dip when `cancelPrevious` supersedes a call.\n   * It covers only this helper's work. Keep your own flag if it also spans follow-up fetches or mapping.\n   * It belongs to the instance. A factory that builds one per call cannot\n   * expose `loading`, `abort` or `cancelPrevious`, so hoist the instance first.\n   */\n  loading: Ref<boolean>\n}\n"],"mappings":";;;;;;;;;;AA6DA,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;CA4EpD,OAAO;EAAE,gBA1Ec,IAAmC,CAAC,MAAoB;GAC7E,IAAM,EAAE,aAAaC,GAAqB,WAAWC,GAAmB,SAAM,cAAWC,GAIrFC,GACAC;GAEJ,IAAI;IACF,IAAMC,IAAM,MAAMP,EAAU,KAAK,MAAgB;KAE/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;KAGpD,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,GAGnGI,IAA6B;MACjC,GAAGC,EAAcC,CAAO;MACxB;MACA,KAAKJ;MACL,QAAQK;KACV;KACA,AAAIX,MAAW,EAAO,OAAO,KAAK,UAAUE,CAAI;KAEhD,IAAMU,IAAWC,EAAO;KAMxB,OAFA,IAAMP,GAECM,EAAS,QAAQJ,CAAM;IAChC,GAAGM,CAAM;IAET,IAAapB,EAAI;IAEjB,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

@@ -13,7 +13,6 @@ export type UseApiFetchListParams = {
     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;
 };
@@ -24,10 +23,8 @@ export type FetchListParams = {
     /** 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.
+     * `false`: a failure of this call is still thrown but not sent to the api error logger.
+     * For a caller that polls a list and has already reported its first failure. It is set per call, not per instance.
      */
     report?: boolean;
 };
@@ -37,24 +34,11 @@ 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.
+     * True while this instance has a request in flight. Unlike a caller-cleared
+     * `finally` flag, it does not dip when `cancelPrevious` supersedes a call.
+     * It covers only this helper's work. Keep your own flag if it also spans follow-up fetches or mapping.
+     * It belongs to the instance. A factory that builds one per call cannot
+     * expose `loading`, `abort` or `cancelPrevious`, so hoist the instance first.
      */
     loading: Ref<boolean>;
 };

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

@@ -1 +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"}
+{"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  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 call is still thrown but not sent to the api error logger.\n   * For a caller that polls a list and has already reported its first failure. It is set per call, not per instance.\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 a url exists. It stays undefined before\n    // that, because a call that never reached the wire requested no url.\n    let url: string | undefined\n    // The config axios used, kept for failures raised after reading the response. Those carry\n    // no config, and a rebuild would describe the request as the client would send it now.\n    let dispatched: AxiosRequestConfig | undefined\n\n    // Set by `run`, not read before it. `run` opens the new\n    // generation, so an earlier value belongs to the previous call.\n    let generation = 0\n    let ownSignal: AbortSignal | undefined\n    const writePagination = (next: Partial<Pagination>) => {\n      // Check both a newer generation and this call's own abort. Aborting does not stop a response already arriving.\n      // The generation belongs to the instance, so one instance must serve one list.\n      // Concurrent calls writing to different refs would leave the older ref unwritten.\n      if (abortable.generation() !== generation) return\n      if (ownSignal?.aborted === true) return\n      // Read the caller's signal directly, not the relay. `run` drops the relay once the response arrives\n      // and this write happens after, so an abort in between would otherwise still write pagination.\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 url is derived inside `run`, which opens the generation and, with\n        // `cancelPrevious`, stops the previous call. If building it threw before `run`,\n        // the previous call would stay current and write pagination for a replaced query.\n        // Inside the try so these failures raise the same error class as others.\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 before the call can throw. A failing\n        // client factory means no request happened, so no url is reported.\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 names, so the message and context agree when an interceptor rewrote the request.\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. The metadata must be reset, or it keeps describing the previous query.\n      if (res.status === HTTP_STATUS_NO_CONTENT) {\n        // The current pagination mode decides what to clear. A counted list\n        // keeps `hasNextPage` as `null`, an infinite one gets `false`.\n        // Writing `null` for both switched infinite lists to counted mode. `ASubjectSelect` then autoloaded\n        // the same 204 again, and `ADatatablePagination` offered 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 write when the response named a paging mode. Otherwise a lone\n      // `currentViewCount` would be stale metadata for an earlier query.\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 shared by both, as in the batch.\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. Unlike a caller-cleared\n   * `finally` flag, it does not dip when `cancelPrevious` supersedes a call.\n   * It covers only this helper's work. Keep your own flag if it also spans follow-up fetches or mapping.\n   * It belongs to the instance. A factory that builds one per call cannot\n   * expose `loading`, `abort` or `cancelPrevious`, so hoist the instance first.\n   */\n  loading: Ref<boolean>\n}\n"],"mappings":";;;;;;;;;;;;AA2CA,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;CA2GpD,OAAO;EAAE,gBAxGP,GACA,GACA,GACA,IAA+B,CAAC,MACf;GACjB,IAAM,EACJ,aAAaC,GACb,WAAWC,GACX,kBAAe,IACf,WACA,QAAQC,IAAW,OACjBC,GAIAC,GAGAC,GAIAC,IAAa,GACbC,GACEC,KAAmB,MAA8B;IAIrD,AAAIV,EAAU,WAAW,MAAMQ,KAC3BC,GAAW,YAAY,MAGvBE,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;KAMZ,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;IAEjB,IAAMkB,UAAeC,EAAaJ,GAAQtB,GAAKwB,GAAS,KAAA,GAAWvB,CAAU;IAC7E,IAAI,CAAC0B,EAAkBpB,EAAI,MAAM,GAAG,MAAM,IAAIqB,EAAyBrB,EAAI,MAAM;IAGjF,IAAIA,EAAI,WAAA,KAON,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;IAK3D,OAFIM,EAAK,SAAS,aAAW3B,EAAgB;KAAE,GAAG2B,EAAK;KAAY,kBAAkBA,EAAK,MAAM;IAAO,CAAC,GAEjGA,EAAK;GACd,SAASE,GAAc;IAErB,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

@@ -12,7 +12,6 @@ export type UseApiFetchListBatchParams = {
     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;
 };
@@ -31,27 +30,11 @@ 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.
+     * True while this instance is working. For a batch it covers the whole walk, including gaps between pages.
+     * Unlike a hand-rolled ref cleared in `finally`, it does not drop when `cancelPrevious` supersedes a call.
+     * It covers only this helper. Keep your own flag if it also spans follow-up work such as a cached fetch or mapping.
+     * It is only reachable if you hold the instance. A factory that creates
+     * one per call cannot expose `loading`, `abort` or `cancelPrevious`.
      */
     loading: Ref<boolean>;
 };

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

@@ -1 +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":"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"}
+{"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  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 failing page to the catch that reports it.\n * The catch unwraps it before mapping, so callers see the same error classes as from other helpers.\n */\nclass PageFailure extends Error {\n  readonly pageUrl: string\n  readonly failure: unknown\n  /**\n   * The config axios used, set when the page answered but this helper refused\n   * the response. Transport failures do not need it, axios keeps 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` because `run` opens the generation and, with `cancelPrevious`,\n        // stops the previous call. A throw before it would leave the predecessor running.\n        // Inside the try so the failure raises the same error class as others.\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 never ends the walk and causes unbounded requests. Fail it as a caller error.\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, so a factory that answers\n        // differently per call cannot split pages across backends.\n        const instance = client()\n\n        const { pagination } = usePagination(sortBy, sortDesc ? SortOrder.Desc : SortOrder.Asc, {\n          rowsPerPage: batchSize,\n        })\n\n        // Each page carries its own url so a failure can name the page. 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 while the page is known. The counted branch dispatches all\n            // pages before any answers, so a shared variable would name the wrong page.\n            throw new PageFailure(pageUrl, err)\n          }\n        }\n\n        // The url the report names for this page, so the message and\n        // context agree when an interceptor rewrote the request.\n        const asSent = (res: AxiosResponse, pageUrl: string) =>\n          requestedUrl(client, pageUrl, options, undefined, res.config)\n\n        // Every page is checked the same way. A 2xx with no body breaks the contract on any page.\n        // The 204 branch is defensive. These backends return empty lists as 200 with a body.\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 short first page is read as the server's real page size (a capped `limit`), so later\n        // offsets use it. Done before the branch so both counted and infinite walks use it.\n        // If the server instead dropped rows after applying `limit`, this would repeat rows at boundaries.\n        // No such dropping was found, and repeated rows are visible while missing ones are not.\n        // When capped, pages are walked one at a time, so a wrong guess\n        // costs single requests 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 said nothing about further pages, so the first page is all there is.\n        if (first.mode !== 'counted') return results\n\n        // Two cases where `totalCount` cannot be divided into a page count. `bigTable` (on by default) makes\n        // `totalCount` a look-ahead of `offset + limit + 1`, not a total. Dividing it gives 2 pages, so a\n        // 5000-row batch would stop at 200. Or the page size was guessed and the server already contradicted it.\n        // In both cases walk pages sequentially until a page is shorter than requested. That is the end-of-data signal.\n        // Stop early when the rows already reach `totalCount`. The repository corrects\n        // `totalCount` to the real total only when a page comes back shorter than its\n        // limit. A capped server reports the look-ahead instead and does not match.\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        // The count is known, so the remaining pages are requested in parallel.\n        const pageCount = Math.ceil(first.totalCount / pagination.value.rowsPerPage)\n        if (pageCount <= 1) return results\n\n        // Read each page as it arrives, not after all settle. Otherwise a broken\n        // body goes unnoticed while a sibling hangs, and the call never ends.\n        // Rejecting here reaches `run`, which aborts 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 page adds nothing. The other pages are kept, since all were sent 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 reports a url, and it reports its own. The base url is never\n      // requested. A failure before dispatch (missing template, unrenderable filter\n      // config) belongs to no page. Every failure after dispatch is 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. For a batch it covers the whole walk, including gaps between pages.\n   * Unlike a hand-rolled ref cleared in `finally`, it does not drop when `cancelPrevious` supersedes a call.\n   * It covers only this helper. Keep your own flag if it also spans follow-up work such as a cached fetch or mapping.\n   * It is only reachable if you hold the instance. A factory that creates\n   * one per call cannot expose `loading`, `abort` or `cancelPrevious`.\n   */\n  loading: Ref<boolean>\n}\n"],"mappings":"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"}

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

@@ -1 +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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"}
+{"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 public, so callers can pass any field names. A missing one fails with its 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

@@ -9,12 +9,9 @@ export type ExecuteRequestParams<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.
+     * `false`: a failure of this call is still thrown but not sent to the api error logger.
+     * For pollers that already reported the first failure, so an outage
+     * is not logged on every tick. It is set per call, not per instance.
      */
     report?: boolean;
 };
@@ -28,60 +25,40 @@ export type UseApiRequestParams = {
     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. */
+    /** Each call cancels the previous one, as for autocomplete. */
     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.
+     * True while this instance has a request in flight. Unlike a caller-cleared
+     * `finally` flag, it does not dip when `cancelPrevious` supersedes a call.
+     * It covers only this helper's work. Keep your own flag if it also spans follow-up fetches or mapping.
+     * It belongs to the instance. A factory that builds one per call cannot
+     * expose `loading`, `abort` or `cancelPrevious`, so hoist the instance 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.
+ * A response without a body breaks the contract and fails like any other error.
+ * Use `useApiCommand` for endpoints that answer nothing, and `optionalBody` for endpoints that may answer either.
+ * `R` excludes `null`, `undefined` and `void` on purpose, so `useApiRequest<void, …>` does not compile.
  */
 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.
+ * Same as above, for an endpoint where a missing body is a legitimate answer. The caller must narrow.
+ * Use it only where the endpoint 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.
+ * A request that reads nothing back, such as a delete or a call that starts work and answers 202.
+ * Any successful status resolves. A body, if one arrives, is ignored.
  */
 export declare const useApiCommand: <B = never>(params: UseApiRequestParams) => UseApiRequestReturnType<void, B>;

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

@@ -1 +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"}
+{"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 call is still thrown but not sent to the api error logger.\n   * For pollers that already reported the first failure, so an outage\n   * is not logged on every tick. It is set per call, not per instance.\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  options?: Omit<AxiosRequestConfig, 'method' | 'url' | 'data' | 'signal'>\n  /** Each call cancels the previous one, as for autocomplete. */\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. Unlike a caller-cleared\n   * `finally` flag, it does not dip when `cancelPrevious` supersedes a call.\n   * It covers only this helper's work. Keep your own flag if it also spans follow-up fetches or mapping.\n   * It belongs to the instance. A factory that builds one per call cannot\n   * expose `loading`, `abort` or `cancelPrevious`, so hoist the instance first.\n   */\n  loading: Ref<boolean>\n}\n\n// The url only identifies the request in error messages, and may be missing if the helper failed before\n// building it. It is a function because building it costs a render that successful reads do not need.\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    // Set in `run` once there is a url. `undefined` means the failure happened before\n    // dispatch. An empty string is a real url (the client root) and is rendered as such.\n    let url: string | undefined\n    // The config axios actually sent. Errors raised after reading the response are not axios errors and have\n    // no config. Rebuilding one would describe the request as it would be sent now, not as it was sent.\n    let dispatched: AxiosRequestConfig | undefined\n\n    try {\n      const res = await abortable.run((abortSignal) => {\n        // Throw inside `run` and its try. `run` opens the generation and, with `cancelPrevious`,\n        // stops the previous call, so a call that throws before sending still supersedes it.\n        // It also gives a missing template the same error class as other failures, not a bare `Error`.\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. To send JSON `null`, the caller wraps it.\n        if (!isNull(body) && !isUndefined(body)) axiosConfig.data = JSON.stringify(body)\n\n        // `options` goes first so a caller cannot override the method, url, body or signal.\n        // The type already forbids this. The spread order protects JavaScript and loosely typed callers.\n        const config = { ...ownedByHelper(options), ...axiosConfig, signal: abortSignal }\n        const instance = client()\n\n        // Set `url` last, when nothing before the call can throw.\n        // If serialising the body or the client factory fails, no request happened and the report must not name a url.\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 names, so the message and context agree when an interceptor rewrote the request.\n      return interpret(res, () => requestedUrl(client, url, options, undefined, dispatched))\n    } catch (err: unknown) {\n      // Built once and shared by both, as in the batch.\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 * A response without a body breaks the contract and fails like any other error.\n * Use `useApiCommand` for endpoints that answer nothing, and `optionalBody` for endpoints that may answer either.\n * `R` excludes `null`, `undefined` and `void` on purpose, so `useApiRequest<void, …>` does not compile.\n */\nexport function useApiRequest<R extends NonNullable<unknown>, B = never>(\n  params: UseApiRequestParams & { optionalBody?: false }\n): UseApiRequestReturnType<R, B>\n/**\n * Same as above, for an endpoint where a missing body is a legitimate answer. The caller must narrow.\n * Use it only where the endpoint 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, because it carries no body by definition.\n    // 202 may carry a body, so it 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 reads nothing back, such as a delete or a call that starts work and answers 202.\n * Any successful status resolves. A body, if one arrives, is ignored.\n */\nexport const useApiCommand = <B = never>(params: UseApiRequestParams): UseApiRequestReturnType<void, B> =>\n  createRequest<void, B>(params, () => undefined)\n"],"mappings":";;;;;;;;;AAgEA,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;CAkE/D,OAAO;EAAE,gBAhEc,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,GAGhEC,GAGAC;GAEJ,IAAI;IACF,IAAMC,IAAM,MAAMb,EAAU,KAAK,MAAgB;KAI/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;KAI/E,IAAMC,IAAS;MAAE,GAAGC,EAAcC,CAAO;MAAG,GAAGL;MAAa,QAAQM;KAAY,GAC1EC,IAAWC,EAAO;KAMxB,OAFA,IAAMV,GAECS,EAAS,QAAQJ,CAAM;IAChC,GAAGM,CAAM;IAGT,IADA,IAAad,EAAI,QACb,CAACe,EAAkBf,EAAI,MAAM,GAAG,MAAM,IAAIgB,EAAyBhB,EAAI,MAAM;IAGjF,OAAOiB,EAAUjB,SAAWkB,EAAaL,GAAQf,GAAKY,GAAS,KAAA,GAAWX,CAAU,CAAC;GACvF,SAASoB,GAAc;IAErB,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;AAkBA,SAAgBqC,EACd,GAC2C;CAC3C,IAAMC,IAAevC,EAAO,iBAAiB;CAE7C,OAAOD,EAAgCC,IAAS,GAAK,MAAQ;EAG3D,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;AAMA,IAAa6B,KAA4B,MACvC1C,EAAuBC,SAAc,KAAA,CAAS"}