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

package/dist/domains/anzuUser/utils/userMetadataDiff.js.map

@@ -1 +1 @@
-{"version":3,"file":"userMetadataDiff.js","names":["USER_METADATA_FIELDS","readMetadataField","field","user","writeMetadataField","value","findMetadataDifferences","differences","records","values","system","pickPrefillSource","order","systemsNeedingWrite","systems","fields","target"],"sources":["../../../../src/domains/anzuUser/utils/userMetadataDiff.ts"],"sourcesContent":["import type { BaseUser } from '@/shared/types/AnzuUser'\n\n/**\n * The six fields the cross-system view compares.\n *\n * `email` is in the list and is also the reason the e-mail search runs twice: if a person is\n * `jozko@sme.sk` in weather and `j.mrkvicka@sme.sk` in blog, a search by e-mail finds weather and\n * blog answers nothing -- which looks exactly like \"no account here\". The second round, by the id\n * the first round found, is what turns that silence into the inconsistency it actually is.\n */\nexport const USER_METADATA_FIELDS = [\n  'email',\n  'person.firstName',\n  'person.lastName',\n  'person.fullName',\n  'avatar.color',\n  'avatar.text',\n] as const\n\nexport type UserMetadataField = (typeof USER_METADATA_FIELDS)[number]\n\nexport const readMetadataField = (user: BaseUser, field: UserMetadataField): string => {\n  switch (field) {\n    case 'email':\n      return user.email\n    case 'person.firstName':\n      return user.person.firstName\n    case 'person.lastName':\n      return user.person.lastName\n    case 'person.fullName':\n      return user.person.fullName\n    case 'avatar.color':\n      return user.avatar.color\n    case 'avatar.text':\n      return user.avatar.text\n  }\n}\n\nexport const writeMetadataField = (user: BaseUser, field: UserMetadataField, value: string): void => {\n  switch (field) {\n    case 'email':\n      user.email = value\n      break\n    case 'person.firstName':\n      user.person.firstName = value\n      break\n    case 'person.lastName':\n      user.person.lastName = value\n      break\n    case 'person.fullName':\n      user.person.fullName = value\n      break\n    case 'avatar.color':\n      user.avatar.color = value\n      break\n    case 'avatar.text':\n      user.avatar.text = value\n      break\n  }\n}\n\nexport interface MetadataDifference {\n  field: UserMetadataField\n  /** System to the value it holds, for every system that answered with a record. */\n  values: Map<string, string>\n}\n\n/**\n * Which of the six fields the systems disagree about.\n *\n * Blog is compared on `person.*` like everything else, and its own root `firstName`/`lastName`\n * columns are deliberately left out of this: those are the byline under an article, the blog's slug\n * and the public API, not back-office metadata. That blog's `person` is empty for most bloggers and\n * will therefore read as different is correct -- the back-office identity really is unset there,\n * and the first repair fills it in.\n */\nexport const findMetadataDifferences = (records: Map<string, BaseUser>): MetadataDifference[] => {\n  const differences: MetadataDifference[] = []\n  if (records.size < 2) return differences\n\n  for (const field of USER_METADATA_FIELDS) {\n    const values = new Map<string, string>()\n    for (const [system, user] of records) {\n      values.set(system, readMetadataField(user, field))\n    }\n    const distinct = new Set(values.values())\n    if (distinct.size > 1) differences.push({ field, values })\n  }\n\n  return differences\n}\n\n/**\n * Which record the repair form is pre-filled from: the first system in the configured order that\n * has one.\n *\n * Never \"whichever answered first\" -- the fan-out is parallel, so that would be a different answer\n * on every run. The order is a default rather than a hidden rule: the dialog names the source and\n * lets it be changed.\n */\nexport const pickPrefillSource = (order: string[], records: Map<string, BaseUser>): string | null => {\n  for (const system of order) {\n    if (records.has(system)) return system\n  }\n  return null\n}\n\n/** Systems whose stored value differs from the one about to be written. Nothing else is touched. */\nexport const systemsNeedingWrite = (\n  target: BaseUser,\n  records: Map<string, BaseUser>,\n  fields: readonly UserMetadataField[] = USER_METADATA_FIELDS\n): string[] => {\n  const systems: string[] = []\n  for (const [system, user] of records) {\n    const differs = fields.some((field) => readMetadataField(user, field) !== readMetadataField(target, field))\n    if (differs) systems.push(system)\n  }\n  return systems\n}\n"],"mappings":";AAUA,IAAaA,IAAuB;CAClC;CACA;CACA;CACA;CACA;CACA;AACF,GAIaC,KAAqB,GAAgB,MAAqC;CACrF,QAAQC,GAAR;EACE,KAAK,SACH,OAAOC,EAAK;EACd,KAAK,oBACH,OAAOA,EAAK,OAAO;EACrB,KAAK,mBACH,OAAOA,EAAK,OAAO;EACrB,KAAK,mBACH,OAAOA,EAAK,OAAO;EACrB,KAAK,gBACH,OAAOA,EAAK,OAAO;EACrB,KAAK,eACH,OAAOA,EAAK,OAAO;CACvB;AACF,GAEaC,KAAsB,GAAgB,GAA0B,MAAwB;CACnG,QAAQF,GAAR;EACE,KAAK;GACH,EAAK,QAAQG;GACb;EACF,KAAK;GACH,EAAK,OAAO,YAAYA;GACxB;EACF,KAAK;GACH,EAAK,OAAO,WAAWA;GACvB;EACF,KAAK;GACH,EAAK,OAAO,WAAWA;GACvB;EACF,KAAK;GACH,EAAK,OAAO,QAAQA;GACpB;EACF,KAAK,eACH,EAAK,OAAO,OAAOA;CAEvB;AACF,GAiBaC,KAA2B,MAAyD;CAC/F,IAAMC,IAAoC,CAAC;CAC3C,IAAIC,EAAQ,OAAO,GAAG,OAAOD;CAE7B,KAAK,IAAML,KAASF,GAAsB;EACxC,IAAMS,oBAAS,IAAI,IAAoB;EACvC,KAAK,IAAM,CAACC,GAAQP,MAASK,GAC3B,EAAO,IAAIE,GAAQT,EAAkBE,GAAMD,CAAK,CAAC;EAGnD,AAAI,IADiB,IAAIO,EAAO,OAAO,CACnC,CAAA,CAAS,OAAO,KAAGF,EAAY,KAAK;GAAE;GAAO;EAAO,CAAC;CAC3D;CAEA,OAAOA;AACT,GAUaI,KAAqB,GAAiB,MAAkD;CACnG,KAAK,IAAMD,KAAUE,GACnB,IAAIJ,EAAQ,IAAIE,CAAM,GAAG,OAAOA;CAElC,OAAO;AACT,GAGaG,KACX,GACA,GACA,IAAuCb,MAC1B;CACb,IAAMc,IAAoB,CAAC;CAC3B,KAAK,IAAM,CAACJ,GAAQP,MAASK,GAE3B,AADgBO,EAAO,MAAM,MAAUd,EAAkBE,GAAMD,CAAK,MAAMD,EAAkBe,GAAQd,CAAK,CACrG,KAASY,EAAQ,KAAKJ,CAAM;CAElC,OAAOI;AACT"}
+{"version":3,"file":"userMetadataDiff.js","names":["USER_METADATA_FIELDS","readMetadataField","field","user","writeMetadataField","value","findMetadataDifferences","differences","records","values","system","pickPrefillSource","order","systemsNeedingWrite","systems","fields","target"],"sources":["../../../../src/domains/anzuUser/utils/userMetadataDiff.ts"],"sourcesContent":["import type { BaseUser } from '@/shared/types/AnzuUser'\n\n/**\n * The six compared fields.\n * `email` is why e-mail search runs twice: a system with a different\n * address answers nothing. The id round reveals that as an inconsistency.\n */\nexport const USER_METADATA_FIELDS = [\n  'email',\n  'person.firstName',\n  'person.lastName',\n  'person.fullName',\n  'avatar.color',\n  'avatar.text',\n] as const\n\nexport type UserMetadataField = (typeof USER_METADATA_FIELDS)[number]\n\nexport const readMetadataField = (user: BaseUser, field: UserMetadataField): string => {\n  switch (field) {\n    case 'email':\n      return user.email\n    case 'person.firstName':\n      return user.person.firstName\n    case 'person.lastName':\n      return user.person.lastName\n    case 'person.fullName':\n      return user.person.fullName\n    case 'avatar.color':\n      return user.avatar.color\n    case 'avatar.text':\n      return user.avatar.text\n  }\n}\n\nexport const writeMetadataField = (user: BaseUser, field: UserMetadataField, value: string): void => {\n  switch (field) {\n    case 'email':\n      user.email = value\n      break\n    case 'person.firstName':\n      user.person.firstName = value\n      break\n    case 'person.lastName':\n      user.person.lastName = value\n      break\n    case 'person.fullName':\n      user.person.fullName = value\n      break\n    case 'avatar.color':\n      user.avatar.color = value\n      break\n    case 'avatar.text':\n      user.avatar.text = value\n      break\n  }\n}\n\nexport interface MetadataDifference {\n  field: UserMetadataField\n  /** System to the value it holds, for every system that answered with a record. */\n  values: Map<string, string>\n}\n\n/**\n * Blog is compared on `person.*`. Its root `firstName`/`lastName` are the public byline and are excluded.\n * Blog's empty `person` reads as different on purpose; the first repair fills it.\n */\nexport const findMetadataDifferences = (records: Map<string, BaseUser>): MetadataDifference[] => {\n  const differences: MetadataDifference[] = []\n  if (records.size < 2) return differences\n\n  for (const field of USER_METADATA_FIELDS) {\n    const values = new Map<string, string>()\n    for (const [system, user] of records) {\n      values.set(system, readMetadataField(user, field))\n    }\n    const distinct = new Set(values.values())\n    if (distinct.size > 1) differences.push({ field, values })\n  }\n\n  return differences\n}\n\n/**\n * Prefill source: the first system in configured order with a record.\n * Not the first to answer, since the fan-out is parallel. The dialog names the source and lets it be changed.\n */\nexport const pickPrefillSource = (order: string[], records: Map<string, BaseUser>): string | null => {\n  for (const system of order) {\n    if (records.has(system)) return system\n  }\n  return null\n}\n\n/** Systems whose stored value differs from the one about to be written. Nothing else is touched. */\nexport const systemsNeedingWrite = (\n  target: BaseUser,\n  records: Map<string, BaseUser>,\n  fields: readonly UserMetadataField[] = USER_METADATA_FIELDS\n): string[] => {\n  const systems: string[] = []\n  for (const [system, user] of records) {\n    const differs = fields.some((field) => readMetadataField(user, field) !== readMetadataField(target, field))\n    if (differs) systems.push(system)\n  }\n  return systems\n}\n"],"mappings":";AAOA,IAAaA,IAAuB;CAClC;CACA;CACA;CACA;CACA;CACA;AACF,GAIaC,KAAqB,GAAgB,MAAqC;CACrF,QAAQC,GAAR;EACE,KAAK,SACH,OAAOC,EAAK;EACd,KAAK,oBACH,OAAOA,EAAK,OAAO;EACrB,KAAK,mBACH,OAAOA,EAAK,OAAO;EACrB,KAAK,mBACH,OAAOA,EAAK,OAAO;EACrB,KAAK,gBACH,OAAOA,EAAK,OAAO;EACrB,KAAK,eACH,OAAOA,EAAK,OAAO;CACvB;AACF,GAEaC,KAAsB,GAAgB,GAA0B,MAAwB;CACnG,QAAQF,GAAR;EACE,KAAK;GACH,EAAK,QAAQG;GACb;EACF,KAAK;GACH,EAAK,OAAO,YAAYA;GACxB;EACF,KAAK;GACH,EAAK,OAAO,WAAWA;GACvB;EACF,KAAK;GACH,EAAK,OAAO,WAAWA;GACvB;EACF,KAAK;GACH,EAAK,OAAO,QAAQA;GACpB;EACF,KAAK,eACH,EAAK,OAAO,OAAOA;CAEvB;AACF,GAYaC,KAA2B,MAAyD;CAC/F,IAAMC,IAAoC,CAAC;CAC3C,IAAIC,EAAQ,OAAO,GAAG,OAAOD;CAE7B,KAAK,IAAML,KAASF,GAAsB;EACxC,IAAMS,oBAAS,IAAI,IAAoB;EACvC,KAAK,IAAM,CAACC,GAAQP,MAASK,GAC3B,EAAO,IAAIE,GAAQT,EAAkBE,GAAMD,CAAK,CAAC;EAGnD,AAAI,IADiB,IAAIO,EAAO,OAAO,CACnC,CAAA,CAAS,OAAO,KAAGF,EAAY,KAAK;GAAE;GAAO;EAAO,CAAC;CAC3D;CAEA,OAAOA;AACT,GAMaI,KAAqB,GAAiB,MAAkD;CACnG,KAAK,IAAMD,KAAUE,GACnB,IAAIJ,EAAQ,IAAIE,CAAM,GAAG,OAAOA;CAElC,OAAO;AACT,GAGaG,KACX,GACA,GACA,IAAuCb,MAC1B;CACb,IAAMc,IAAoB,CAAC;CAC3B,KAAK,IAAM,CAACJ,GAAQP,MAASK,GAE3B,AADgBO,EAAO,MAAM,MAAUd,EAAkBE,GAAMD,CAAK,MAAMD,EAAkBe,GAAQd,CAAK,CACrG,KAASY,EAAQ,KAAKJ,CAAM;CAElC,OAAOI;AACT"}

package/dist/domains/anzuUser/utils/userSystemState.d.ts

@@ -1,11 +1,6 @@
 /**
- * Four independent axes inside, one derived state outside.
- *
- * The axes are kept apart because they answer different questions and can move independently: a
- * system can be loaded and forbidden, or absent and still enabled in configuration. Collapsing
- * them into one enum early is what made the per-admin prototypes conflate "no access" with "no
- * account here" -- admin-cms's panel leaves `userExists` at null on any non-404 and offers
- * "Create" in a system the operator cannot even read.
+ * Four independent axes, one derived state.
+ * Collapsing them early conflated "no access" with "no account" and offered Create in unreadable systems.
  */
 export declare const UserSystemLoad: {
     readonly Idle: "idle";
@@ -29,11 +24,8 @@ export declare const UserSystemAccess: {
 };
 export type UserSystemAccessType = (typeof UserSystemAccess)[keyof typeof UserSystemAccess];
 /**
- * `enabled` is one of the axes and not a detail: without it the two states the cross-system view
- * shows most often -- "the account is here and on" versus "here and off" -- cannot be told apart.
- *
- * Ownership is deliberately *not* an axis. None of the six visual states below distinguishes it;
- * it decides which button is drawn, and that is the descriptor's `manage` union.
+ * `enabled` is an axis so "here and on" and "here and off" can be told apart.
+ * Ownership is not an axis; the descriptor's `manage` decides the button.
  */
 export interface UserSystemAxes {
     load: UserSystemLoadType;
@@ -54,30 +46,20 @@ export declare const UserSystemState: {
 export type UserSystemStateType = (typeof UserSystemState)[keyof typeof UserSystemState];
 export declare const emptyUserSystemAxes: () => UserSystemAxes;
 /**
- * The single closed function from axes to what is drawn. Order matters: a system switched off in
- * configuration is reported as such whatever else is known about it, and access is decided before
- * presence because a forbidden record is not an absent one.
+ * Order matters. Config-disabled wins over everything.
+ * Access is checked before presence because a forbidden record is not an absent one.
  */
 export declare const resolveUserSystemState: (axes: UserSystemAxes) => UserSystemStateType;
 /**
- * How a probe response becomes axes.
- *
- * 401 is its own case and it is not a detail. A first 401 is ambiguous -- an expired session looks
- * exactly like "no account here" -- and since the buttons are gated by this answer alone, showing
- * an expired token as "no account here" is the one confusion decision 16 forbids. The caller is
- * expected to have retried through its refresh hook before classifying; what arrives here is the
- * verdict after that retry.
- *
- * 422 deliberately has no case. A detail GET loads the record and returns it; it does not validate
- * a body. A 422 belongs to the log of writes.
+ * 401 is its own case: an expired session must not show as "no account here" (decision 16).
+ * The caller retries through its refresh hook first; this receives the verdict.
+ * 422 has no case: a detail GET does not validate. A 422 belongs to the write log.
  */
 export declare const classifyProbeStatus: (status: number | null) => Pick<UserSystemAxes, "presence" | "access">;
 /**
- * Whether the probe answered authoritatively that nobody is there.
- *
- * Creating an account is offered only when every relevant system said so. A record that could not
- * be read is not a record that does not exist, and since no admin can delete an AnzuUser, a
- * duplicate identity created on a guess cannot be taken back.
+ * Whether every relevant system answered authoritatively that the account does not exist.
+ * Account creation is offered only then. An unreadable record is not a missing one, and
+ * an AnzuUser cannot be deleted, so a duplicate created on a guess cannot be undone.
  */
 export declare const isAuthoritativelyAbsent: (axes: UserSystemAxes) => boolean;
 /** A system a bulk action may act on: it answered, the account is there, and access was granted. */

package/dist/domains/anzuUser/utils/userSystemState.js.map

@@ -1 +1 @@
-{"version":3,"file":"userSystemState.js","names":["UserSystemLoad","UserSystemPresence","UserSystemAccess","UserSystemState","emptyUserSystemAxes","resolveUserSystemState","axes","classifyProbeStatus","status","isAuthoritativelyAbsent","isActionable"],"sources":["../../../../src/domains/anzuUser/utils/userSystemState.ts"],"sourcesContent":["/**\n * Four independent axes inside, one derived state outside.\n *\n * The axes are kept apart because they answer different questions and can move independently: a\n * system can be loaded and forbidden, or absent and still enabled in configuration. Collapsing\n * them into one enum early is what made the per-admin prototypes conflate \"no access\" with \"no\n * account here\" -- admin-cms's panel leaves `userExists` at null on any non-404 and offers\n * \"Create\" in a system the operator cannot even read.\n */\nexport const UserSystemLoad = {\n  Idle: 'idle',\n  Loading: 'loading',\n  Loaded: 'loaded',\n  Error: 'error',\n} as const\nexport type UserSystemLoadType = (typeof UserSystemLoad)[keyof typeof UserSystemLoad]\n\nexport const UserSystemPresence = {\n  Present: 'present',\n  Absent: 'absent',\n  Unknown: 'unknown',\n} as const\nexport type UserSystemPresenceType = (typeof UserSystemPresence)[keyof typeof UserSystemPresence]\n\nexport const UserSystemAccess = {\n  Ok: 'ok',\n  Forbidden: 'forbidden',\n  Unauthenticated: 'unauthenticated',\n  Unavailable: 'unavailable',\n  ConfigDisabled: 'configDisabled',\n} as const\nexport type UserSystemAccessType = (typeof UserSystemAccess)[keyof typeof UserSystemAccess]\n\n/**\n * `enabled` is one of the axes and not a detail: without it the two states the cross-system view\n * shows most often -- \"the account is here and on\" versus \"here and off\" -- cannot be told apart.\n *\n * Ownership is deliberately *not* an axis. None of the six visual states below distinguishes it;\n * it decides which button is drawn, and that is the descriptor's `manage` union.\n */\nexport interface UserSystemAxes {\n  load: UserSystemLoadType\n  presence: UserSystemPresenceType\n  access: UserSystemAccessType\n  enabled: boolean | 'unknown'\n}\n\nexport const UserSystemState = {\n  /** Nothing has been asked yet, or the answer is still on its way. */\n  Loading: 'loading',\n  Enabled: 'enabled',\n  Disabled: 'disabled',\n  Absent: 'absent',\n  Forbidden: 'forbidden',\n  Unavailable: 'unavailable',\n  ConfigDisabled: 'configDisabled',\n} as const\nexport type UserSystemStateType = (typeof UserSystemState)[keyof typeof UserSystemState]\n\nexport const emptyUserSystemAxes = (): UserSystemAxes => ({\n  load: UserSystemLoad.Idle,\n  presence: UserSystemPresence.Unknown,\n  access: UserSystemAccess.Ok,\n  enabled: 'unknown',\n})\n\n/**\n * The single closed function from axes to what is drawn. Order matters: a system switched off in\n * configuration is reported as such whatever else is known about it, and access is decided before\n * presence because a forbidden record is not an absent one.\n */\nexport const resolveUserSystemState = (axes: UserSystemAxes): UserSystemStateType => {\n  if (axes.access === UserSystemAccess.ConfigDisabled) return UserSystemState.ConfigDisabled\n  if (axes.access === UserSystemAccess.Forbidden) return UserSystemState.Forbidden\n  if (axes.access === UserSystemAccess.Unauthenticated || axes.access === UserSystemAccess.Unavailable) {\n    return UserSystemState.Unavailable\n  }\n  if (axes.load === UserSystemLoad.Idle || axes.load === UserSystemLoad.Loading) return UserSystemState.Loading\n  if (axes.presence === UserSystemPresence.Absent) return UserSystemState.Absent\n  if (axes.presence === UserSystemPresence.Unknown) return UserSystemState.Unavailable\n  return axes.enabled === true ? UserSystemState.Enabled : UserSystemState.Disabled\n}\n\n/**\n * How a probe response becomes axes.\n *\n * 401 is its own case and it is not a detail. A first 401 is ambiguous -- an expired session looks\n * exactly like \"no account here\" -- and since the buttons are gated by this answer alone, showing\n * an expired token as \"no account here\" is the one confusion decision 16 forbids. The caller is\n * expected to have retried through its refresh hook before classifying; what arrives here is the\n * verdict after that retry.\n *\n * 422 deliberately has no case. A detail GET loads the record and returns it; it does not validate\n * a body. A 422 belongs to the log of writes.\n */\nexport const classifyProbeStatus = (status: number | null): Pick<UserSystemAxes, 'presence' | 'access'> => {\n  if (status === null) {\n    // A timeout, a network failure, or anything that never reached a status.\n    return { presence: UserSystemPresence.Unknown, access: UserSystemAccess.Unavailable }\n  }\n  if (status === 404) return { presence: UserSystemPresence.Absent, access: UserSystemAccess.Ok }\n  if (status === 403) return { presence: UserSystemPresence.Unknown, access: UserSystemAccess.Forbidden }\n  if (status === 401) return { presence: UserSystemPresence.Unknown, access: UserSystemAccess.Unauthenticated }\n  if (status >= 500) return { presence: UserSystemPresence.Unknown, access: UserSystemAccess.Unavailable }\n  if (status >= 200 && status < 300) return { presence: UserSystemPresence.Present, access: UserSystemAccess.Ok }\n  return { presence: UserSystemPresence.Unknown, access: UserSystemAccess.Unavailable }\n}\n\n/**\n * Whether the probe answered authoritatively that nobody is there.\n *\n * Creating an account is offered only when every relevant system said so. A record that could not\n * be read is not a record that does not exist, and since no admin can delete an AnzuUser, a\n * duplicate identity created on a guess cannot be taken back.\n */\nexport const isAuthoritativelyAbsent = (axes: UserSystemAxes): boolean =>\n  axes.load === UserSystemLoad.Loaded &&\n  axes.presence === UserSystemPresence.Absent &&\n  axes.access === UserSystemAccess.Ok\n\n/** A system a bulk action may act on: it answered, the account is there, and access was granted. */\nexport const isActionable = (axes: UserSystemAxes): boolean =>\n  axes.load === UserSystemLoad.Loaded &&\n  axes.presence === UserSystemPresence.Present &&\n  axes.access === UserSystemAccess.Ok\n"],"mappings":";AASA,IAAaA,IAAiB;CAC5B,MAAM;CACN,SAAS;CACT,QAAQ;CACR,OAAO;AACT,GAGaC,IAAqB;CAChC,SAAS;CACT,QAAQ;CACR,SAAS;AACX,GAGaC,IAAmB;CAC9B,IAAI;CACJ,WAAW;CACX,iBAAiB;CACjB,aAAa;CACb,gBAAgB;AAClB,GAiBaC,IAAkB;CAE7B,SAAS;CACT,SAAS;CACT,UAAU;CACV,QAAQ;CACR,WAAW;CACX,aAAa;CACb,gBAAgB;AAClB,GAGaC,WAA6C;CACxD,MAAMJ,EAAe;CACrB,UAAUC,EAAmB;CAC7B,QAAQC,EAAiB;CACzB,SAAS;AACX,IAOaG,KAA0B,MACjCC,EAAK,WAAWJ,EAAiB,iBAAuBC,EAAgB,iBACxEG,EAAK,WAAWJ,EAAiB,YAAkBC,EAAgB,YACnEG,EAAK,WAAWJ,EAAiB,mBAAmBI,EAAK,WAAWJ,EAAiB,cAChFC,EAAgB,cAErBG,EAAK,SAASN,EAAe,QAAQM,EAAK,SAASN,EAAe,UAAgBG,EAAgB,UAClGG,EAAK,aAAaL,EAAmB,SAAeE,EAAgB,SACpEG,EAAK,aAAaL,EAAmB,UAAgBE,EAAgB,cAClEG,EAAK,YAAY,KAAOH,EAAgB,UAAUA,EAAgB,UAe9DI,KAAuB,MAC9BC,MAAW,OAEN;CAAE,UAAUP,EAAmB;CAAS,QAAQC,EAAiB;AAAY,IAElFM,MAAW,MAAY;CAAE,UAAUP,EAAmB;CAAQ,QAAQC,EAAiB;AAAG,IAC1FM,MAAW,MAAY;CAAE,UAAUP,EAAmB;CAAS,QAAQC,EAAiB;AAAU,IAClGM,MAAW,MAAY;CAAE,UAAUP,EAAmB;CAAS,QAAQC,EAAiB;AAAgB,IACxGM,KAAU,MAAY;CAAE,UAAUP,EAAmB;CAAS,QAAQC,EAAiB;AAAY,IACnGM,KAAU,OAAOA,IAAS,MAAY;CAAE,UAAUP,EAAmB;CAAS,QAAQC,EAAiB;AAAG,IACvG;CAAE,UAAUD,EAAmB;CAAS,QAAQC,EAAiB;AAAY,GAUzEO,KAA2B,MACtCH,EAAK,SAASN,EAAe,UAC7BM,EAAK,aAAaL,EAAmB,UACrCK,EAAK,WAAWJ,EAAiB,IAGtBQ,KAAgB,MAC3BJ,EAAK,SAASN,EAAe,UAC7BM,EAAK,aAAaL,EAAmB,WACrCK,EAAK,WAAWJ,EAAiB"}
+{"version":3,"file":"userSystemState.js","names":["UserSystemLoad","UserSystemPresence","UserSystemAccess","UserSystemState","emptyUserSystemAxes","resolveUserSystemState","axes","classifyProbeStatus","status","isAuthoritativelyAbsent","isActionable"],"sources":["../../../../src/domains/anzuUser/utils/userSystemState.ts"],"sourcesContent":["/**\n * Four independent axes, one derived state.\n * Collapsing them early conflated \"no access\" with \"no account\" and offered Create in unreadable systems.\n */\nexport const UserSystemLoad = {\n  Idle: 'idle',\n  Loading: 'loading',\n  Loaded: 'loaded',\n  Error: 'error',\n} as const\nexport type UserSystemLoadType = (typeof UserSystemLoad)[keyof typeof UserSystemLoad]\n\nexport const UserSystemPresence = {\n  Present: 'present',\n  Absent: 'absent',\n  Unknown: 'unknown',\n} as const\nexport type UserSystemPresenceType = (typeof UserSystemPresence)[keyof typeof UserSystemPresence]\n\nexport const UserSystemAccess = {\n  Ok: 'ok',\n  Forbidden: 'forbidden',\n  Unauthenticated: 'unauthenticated',\n  Unavailable: 'unavailable',\n  ConfigDisabled: 'configDisabled',\n} as const\nexport type UserSystemAccessType = (typeof UserSystemAccess)[keyof typeof UserSystemAccess]\n\n/**\n * `enabled` is an axis so \"here and on\" and \"here and off\" can be told apart.\n * Ownership is not an axis; the descriptor's `manage` decides the button.\n */\nexport interface UserSystemAxes {\n  load: UserSystemLoadType\n  presence: UserSystemPresenceType\n  access: UserSystemAccessType\n  enabled: boolean | 'unknown'\n}\n\nexport const UserSystemState = {\n  /** Nothing has been asked yet, or the answer is still on its way. */\n  Loading: 'loading',\n  Enabled: 'enabled',\n  Disabled: 'disabled',\n  Absent: 'absent',\n  Forbidden: 'forbidden',\n  Unavailable: 'unavailable',\n  ConfigDisabled: 'configDisabled',\n} as const\nexport type UserSystemStateType = (typeof UserSystemState)[keyof typeof UserSystemState]\n\nexport const emptyUserSystemAxes = (): UserSystemAxes => ({\n  load: UserSystemLoad.Idle,\n  presence: UserSystemPresence.Unknown,\n  access: UserSystemAccess.Ok,\n  enabled: 'unknown',\n})\n\n/**\n * Order matters. Config-disabled wins over everything.\n * Access is checked before presence because a forbidden record is not an absent one.\n */\nexport const resolveUserSystemState = (axes: UserSystemAxes): UserSystemStateType => {\n  if (axes.access === UserSystemAccess.ConfigDisabled) return UserSystemState.ConfigDisabled\n  if (axes.access === UserSystemAccess.Forbidden) return UserSystemState.Forbidden\n  if (axes.access === UserSystemAccess.Unauthenticated || axes.access === UserSystemAccess.Unavailable) {\n    return UserSystemState.Unavailable\n  }\n  if (axes.load === UserSystemLoad.Idle || axes.load === UserSystemLoad.Loading) return UserSystemState.Loading\n  if (axes.presence === UserSystemPresence.Absent) return UserSystemState.Absent\n  if (axes.presence === UserSystemPresence.Unknown) return UserSystemState.Unavailable\n  return axes.enabled === true ? UserSystemState.Enabled : UserSystemState.Disabled\n}\n\n/**\n * 401 is its own case: an expired session must not show as \"no account here\" (decision 16).\n * The caller retries through its refresh hook first; this receives the verdict.\n * 422 has no case: a detail GET does not validate. A 422 belongs to the write log.\n */\nexport const classifyProbeStatus = (status: number | null): Pick<UserSystemAxes, 'presence' | 'access'> => {\n  if (status === null) {\n    // A timeout, a network failure, or anything that never reached a status.\n    return { presence: UserSystemPresence.Unknown, access: UserSystemAccess.Unavailable }\n  }\n  if (status === 404) return { presence: UserSystemPresence.Absent, access: UserSystemAccess.Ok }\n  if (status === 403) return { presence: UserSystemPresence.Unknown, access: UserSystemAccess.Forbidden }\n  if (status === 401) return { presence: UserSystemPresence.Unknown, access: UserSystemAccess.Unauthenticated }\n  if (status >= 500) return { presence: UserSystemPresence.Unknown, access: UserSystemAccess.Unavailable }\n  if (status >= 200 && status < 300) return { presence: UserSystemPresence.Present, access: UserSystemAccess.Ok }\n  return { presence: UserSystemPresence.Unknown, access: UserSystemAccess.Unavailable }\n}\n\n/**\n * Whether every relevant system answered authoritatively that the account does not exist.\n * Account creation is offered only then. An unreadable record is not a missing one, and\n * an AnzuUser cannot be deleted, so a duplicate created on a guess cannot be undone.\n */\nexport const isAuthoritativelyAbsent = (axes: UserSystemAxes): boolean =>\n  axes.load === UserSystemLoad.Loaded &&\n  axes.presence === UserSystemPresence.Absent &&\n  axes.access === UserSystemAccess.Ok\n\n/** A system a bulk action may act on: it answered, the account is there, and access was granted. */\nexport const isActionable = (axes: UserSystemAxes): boolean =>\n  axes.load === UserSystemLoad.Loaded &&\n  axes.presence === UserSystemPresence.Present &&\n  axes.access === UserSystemAccess.Ok\n"],"mappings":";AAIA,IAAaA,IAAiB;CAC5B,MAAM;CACN,SAAS;CACT,QAAQ;CACR,OAAO;AACT,GAGaC,IAAqB;CAChC,SAAS;CACT,QAAQ;CACR,SAAS;AACX,GAGaC,IAAmB;CAC9B,IAAI;CACJ,WAAW;CACX,iBAAiB;CACjB,aAAa;CACb,gBAAgB;AAClB,GAcaC,IAAkB;CAE7B,SAAS;CACT,SAAS;CACT,UAAU;CACV,QAAQ;CACR,WAAW;CACX,aAAa;CACb,gBAAgB;AAClB,GAGaC,WAA6C;CACxD,MAAMJ,EAAe;CACrB,UAAUC,EAAmB;CAC7B,QAAQC,EAAiB;CACzB,SAAS;AACX,IAMaG,KAA0B,MACjCC,EAAK,WAAWJ,EAAiB,iBAAuBC,EAAgB,iBACxEG,EAAK,WAAWJ,EAAiB,YAAkBC,EAAgB,YACnEG,EAAK,WAAWJ,EAAiB,mBAAmBI,EAAK,WAAWJ,EAAiB,cAChFC,EAAgB,cAErBG,EAAK,SAASN,EAAe,QAAQM,EAAK,SAASN,EAAe,UAAgBG,EAAgB,UAClGG,EAAK,aAAaL,EAAmB,SAAeE,EAAgB,SACpEG,EAAK,aAAaL,EAAmB,UAAgBE,EAAgB,cAClEG,EAAK,YAAY,KAAOH,EAAgB,UAAUA,EAAgB,UAQ9DI,KAAuB,MAC9BC,MAAW,OAEN;CAAE,UAAUP,EAAmB;CAAS,QAAQC,EAAiB;AAAY,IAElFM,MAAW,MAAY;CAAE,UAAUP,EAAmB;CAAQ,QAAQC,EAAiB;AAAG,IAC1FM,MAAW,MAAY;CAAE,UAAUP,EAAmB;CAAS,QAAQC,EAAiB;AAAU,IAClGM,MAAW,MAAY;CAAE,UAAUP,EAAmB;CAAS,QAAQC,EAAiB;AAAgB,IACxGM,KAAU,MAAY;CAAE,UAAUP,EAAmB;CAAS,QAAQC,EAAiB;AAAY,IACnGM,KAAU,OAAOA,IAAS,MAAY;CAAE,UAAUP,EAAmB;CAAS,QAAQC,EAAiB;AAAG,IACvG;CAAE,UAAUD,EAAmB;CAAS,QAAQC,EAAiB;AAAY,GAQzEO,KAA2B,MACtCH,EAAK,SAASN,EAAe,UAC7BM,EAAK,aAAaL,EAAmB,UACrCK,EAAK,WAAWJ,EAAiB,IAGtBQ,KAAgB,MAC3BJ,EAAK,SAASN,EAAe,UAC7BM,EAAK,aAAaL,EAAmB,WACrCK,EAAK,WAAWJ,EAAiB"}

package/dist/domains/anzuUser/utils/userTabs.d.ts

@@ -1,7 +1,5 @@
 /**
  * The one tab that is not a system.
- *
- * A module of its own because `<script setup>` cannot export, and both the shell and the pages that
- * read `?tab=` need to name it.
+ * Its own module because `<script setup>` cannot export, and both the shell and the pages reading `?tab=` need it.
  */
 export declare const OTHER_SYSTEMS_TAB = "__otherSystems";

package/dist/domains/anzuUser/utils/userTabs.js.map

@@ -1 +1 @@
-{"version":3,"file":"userTabs.js","names":["OTHER_SYSTEMS_TAB"],"sources":["../../../../src/domains/anzuUser/utils/userTabs.ts"],"sourcesContent":["/**\n * The one tab that is not a system.\n *\n * A module of its own because `<script setup>` cannot export, and both the shell and the pages that\n * read `?tab=` need to name it.\n */\nexport const OTHER_SYSTEMS_TAB = '__otherSystems'\n"],"mappings":";AAMA,IAAaA,IAAoB"}
+{"version":3,"file":"userTabs.js","names":["OTHER_SYSTEMS_TAB"],"sources":["../../../../src/domains/anzuUser/utils/userTabs.ts"],"sourcesContent":["/**\n * The one tab that is not a system.\n * Its own module because `<script setup>` cannot export, and both the shell and the pages reading `?tab=` need it.\n */\nexport const OTHER_SYSTEMS_TAB = '__otherSystems'\n"],"mappings":";AAIA,IAAaA,IAAoB"}

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

@@ -17,14 +17,10 @@ export interface ApiClientSetup {
     response?: ApiClientResponseInterceptor[];
 }
 /**
- * An admin's axios client: created on the first call, the same instance on every later one, with its
- * interceptors registered once -- the factories the admins wrote by hand each carried the guard, and
- * one that registered outside it stacked a copy of every interceptor per call.
- *
- * `setup` runs on that first call, not when the module loads, as the guards did: an admin's env config
- * is empty until it has loaded, and a client's interceptors come from modules in an import cycle with
- * it (the refresh interceptor calls the auth api, which goes through the client), so at load time they
- * may not be initialized yet.
+ * Returns a lazily created singleton axios client whose interceptors are registered once.
+ * Registering outside the guard stacks a copy of every interceptor per call.
+ * `setup` runs on the first call, not at module load. Env config is empty until loaded, and interceptors come from
+ * modules in an import cycle with the client (refresh calls the auth api), so they may not be initialized at load time.
  */
 export declare function defineApiClient(setup: () => ApiClientSetup): () => AxiosInstance;
 /** A `runWhen` that leaves out requests to urls starting with one of `prefixes` (the auth endpoints). */

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

@@ -1 +1 @@
-{"version":3,"file":"defineApiClient.js","names":["axios","defineApiClient","instance","isNull","setup","created","config","request","onFulfilled","onRejected","options","response","skipUrlPrefixes","prefixes","prefix"],"sources":["../../../../src/domains/api/composables/defineApiClient.ts"],"sourcesContent":["import axios, {\n  type AxiosInstance,\n  type AxiosInterceptorManager,\n  type AxiosRequestConfig,\n  type AxiosResponse,\n  type CreateAxiosDefaults,\n  type InternalAxiosRequestConfig,\n} from 'axios'\nimport { isNull } from '@/shared/utils/common'\n\n// axios's own handler types, which it does not export.\ntype RequestUse = Parameters<AxiosInterceptorManager<InternalAxiosRequestConfig>['use']>\ntype ResponseUse = Parameters<AxiosInterceptorManager<AxiosResponse>['use']>\n\nexport interface ApiClientRequestInterceptor {\n  onFulfilled?: RequestUse[0]\n  onRejected?: RequestUse[1]\n  options?: RequestUse[2]\n}\n\nexport interface ApiClientResponseInterceptor {\n  onFulfilled?: ResponseUse[0]\n  onRejected?: ResponseUse[1]\n}\n\nexport interface ApiClientSetup {\n  /** The instance's defaults; nothing is added to them. */\n  config: CreateAxiosDefaults\n  request?: ApiClientRequestInterceptor[]\n  response?: ApiClientResponseInterceptor[]\n}\n\n/**\n * An admin's axios client: created on the first call, the same instance on every later one, with its\n * interceptors registered once -- the factories the admins wrote by hand each carried the guard, and\n * one that registered outside it stacked a copy of every interceptor per call.\n *\n * `setup` runs on that first call, not when the module loads, as the guards did: an admin's env config\n * is empty until it has loaded, and a client's interceptors come from modules in an import cycle with\n * it (the refresh interceptor calls the auth api, which goes through the client), so at load time they\n * may not be initialized yet.\n */\nexport function defineApiClient(setup: () => ApiClientSetup): () => AxiosInstance {\n  let instance: AxiosInstance | null = null\n  return () => {\n    if (isNull(instance)) {\n      const { config, request = [], response = [] } = setup()\n      const created = axios.create(config)\n      for (const { onFulfilled, onRejected, options } of request) {\n        created.interceptors.request.use(onFulfilled, onRejected, options)\n      }\n      for (const { onFulfilled, onRejected } of response) {\n        created.interceptors.response.use(onFulfilled, onRejected)\n      }\n      instance = created\n    }\n    return instance\n  }\n}\n\n/** A `runWhen` that leaves out requests to urls starting with one of `prefixes` (the auth endpoints). */\nexport const skipUrlPrefixes =\n  (...prefixes: string[]) =>\n  (config: AxiosRequestConfig): boolean =>\n    !prefixes.some((prefix) => config.url?.startsWith(prefix) ?? false)\n"],"mappings":";;;AA0CA,SAAgBC,EAAgB,GAAkD;CAChF,IAAIC,IAAiC;CACrC,aAAa;EACX,IAAIC,EAAOD,CAAQ,GAAG;GACpB,IAAM,EAAE,WAAQ,aAAU,CAAC,GAAG,cAAW,CAAC,MAAME,EAAM,GAChDC,IAAUL,EAAM,OAAOM,CAAM;GACnC,KAAK,IAAM,EAAE,gBAAa,eAAY,gBAAaC,GACjD,EAAQ,aAAa,QAAQ,IAAIC,GAAaC,GAAYC,CAAO;GAEnE,KAAK,IAAM,EAAE,gBAAa,mBAAgBC,GACxC,EAAQ,aAAa,SAAS,IAAIH,GAAaC,CAAU;GAE3D,IAAWJ;EACb;EACA,OAAOH;CACT;AACF;AAGA,IAAaU,KACV,GAAGC,OACH,MACC,CAACA,EAAS,MAAM,MAAWP,EAAO,KAAK,WAAWQ,CAAM,KAAK,EAAK"}
+{"version":3,"file":"defineApiClient.js","names":["axios","defineApiClient","instance","isNull","setup","created","config","request","onFulfilled","onRejected","options","response","skipUrlPrefixes","prefixes","prefix"],"sources":["../../../../src/domains/api/composables/defineApiClient.ts"],"sourcesContent":["import axios, {\n  type AxiosInstance,\n  type AxiosInterceptorManager,\n  type AxiosRequestConfig,\n  type AxiosResponse,\n  type CreateAxiosDefaults,\n  type InternalAxiosRequestConfig,\n} from 'axios'\nimport { isNull } from '@/shared/utils/common'\n\n// axios's own handler types, which it does not export.\ntype RequestUse = Parameters<AxiosInterceptorManager<InternalAxiosRequestConfig>['use']>\ntype ResponseUse = Parameters<AxiosInterceptorManager<AxiosResponse>['use']>\n\nexport interface ApiClientRequestInterceptor {\n  onFulfilled?: RequestUse[0]\n  onRejected?: RequestUse[1]\n  options?: RequestUse[2]\n}\n\nexport interface ApiClientResponseInterceptor {\n  onFulfilled?: ResponseUse[0]\n  onRejected?: ResponseUse[1]\n}\n\nexport interface ApiClientSetup {\n  /** The instance's defaults; nothing is added to them. */\n  config: CreateAxiosDefaults\n  request?: ApiClientRequestInterceptor[]\n  response?: ApiClientResponseInterceptor[]\n}\n\n/**\n * Returns a lazily created singleton axios client whose interceptors are registered once.\n * Registering outside the guard stacks a copy of every interceptor per call.\n * `setup` runs on the first call, not at module load. Env config is empty until loaded, and interceptors come from\n * modules in an import cycle with the client (refresh calls the auth api), so they may not be initialized at load time.\n */\nexport function defineApiClient(setup: () => ApiClientSetup): () => AxiosInstance {\n  let instance: AxiosInstance | null = null\n  return () => {\n    if (isNull(instance)) {\n      const { config, request = [], response = [] } = setup()\n      const created = axios.create(config)\n      for (const { onFulfilled, onRejected, options } of request) {\n        created.interceptors.request.use(onFulfilled, onRejected, options)\n      }\n      for (const { onFulfilled, onRejected } of response) {\n        created.interceptors.response.use(onFulfilled, onRejected)\n      }\n      instance = created\n    }\n    return instance\n  }\n}\n\n/** A `runWhen` that leaves out requests to urls starting with one of `prefixes` (the auth endpoints). */\nexport const skipUrlPrefixes =\n  (...prefixes: string[]) =>\n  (config: AxiosRequestConfig): boolean =>\n    !prefixes.some((prefix) => config.url?.startsWith(prefix) ?? false)\n"],"mappings":";;;AAsCA,SAAgBC,EAAgB,GAAkD;CAChF,IAAIC,IAAiC;CACrC,aAAa;EACX,IAAIC,EAAOD,CAAQ,GAAG;GACpB,IAAM,EAAE,WAAQ,aAAU,CAAC,GAAG,cAAW,CAAC,MAAME,EAAM,GAChDC,IAAUL,EAAM,OAAOM,CAAM;GACnC,KAAK,IAAM,EAAE,gBAAa,eAAY,gBAAaC,GACjD,EAAQ,aAAa,QAAQ,IAAIC,GAAaC,GAAYC,CAAO;GAEnE,KAAK,IAAM,EAAE,gBAAa,mBAAgBC,GACxC,EAAQ,aAAa,SAAS,IAAIH,GAAaC,CAAU;GAE3D,IAAWJ;EACb;EACA,OAAOH;CACT;AACF;AAGA,IAAaU,KACV,GAAGC,OACH,MACC,CAACA,EAAS,MAAM,MAAWP,EAAO,KAAK,WAAWQ,CAAM,KAAK,EAAK"}

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

@@ -2,60 +2,31 @@ import { AxiosClientFn } from '../utils/client';
 import { AxiosRequestConfig } from 'axios';
 import { Ref } from 'vue';
 /**
- * Whether the response carries a body at all.
- *
- * `''` is not an empty document, it is what axios hands back when no bytes arrived: its adapter
- * returns `responseText`, and `transformResponse` only attempts `JSON.parse` when the string is
- * truthy, so a 204 and a body-less 200 both arrive as `''`. `0` and `false` do parse and are real
- * values -- reading them as absent is the bug this replaces.
- *
- * `null` is treated as absent too. It is distinguishable from `''` at runtime, but nothing can carry
- * it in the type: the response type excludes `null` so that a command site cannot declare itself as
- * returning one.
+ * Whether the response carries a body.
+ * axios returns `''` when no bytes arrived, so a 204 and a body-less 200
+ * both arrive as `''`. `0` and `false` are real values and count as a body.
+ * `null` is treated as absent too, because the response type excludes `null`.
  */
 export declare const hasBody: (res: {
     data: unknown;
 }) => boolean;
 /**
- * Strips what the helper decides from whatever the caller passed as `options`.
- *
- * The type says these cannot be set, but a type says nothing at runtime: `data` in particular
- * survived the spread whenever no body was passed, so a caller could put a body on a GET through
- * the back door and skip the serialisation with it.
+ * Strips the helper-owned keys from the caller's `options` at runtime.
+ * The type forbids them, but without this `data` survived the
+ * spread when no body was passed, which allowed a body on a GET.
  */
 declare const HELPER_OWNED: readonly ["method", "url", "data", "signal"];
 export declare const ownedByHelper: <T extends object>(options: T) => Omit<T, (typeof HELPER_OWNED)[number]>;
 /**
- * The url as axios will actually request it: the client's `baseURL` and default `params`, the
- * request's own `params`, and whatever `paramsSerializer` renders them.
- *
- * Built by axios itself rather than approximated: a url recorded before the call is not the one
- * that went out, and an approximation renders arrays, nested objects and dates differently from the
- * wire -- which is worse than no url, because it looks findable and is not. It is handed the same
- * config the request was given, minus what this helper owns, for the same reason: a call carrying
- * its own `paramsSerializer` or `baseURL` is asking for a url that the defaults do not produce.
- *
- * `undefined` in, `undefined` out: a call that failed before it had a url has none to report, and
- * asking axios for one would answer with the client's root -- a url that was never requested and
- * that reads like an endpoint. An empty string is different: that is a call whose url really is the
- * client root, and it gets rendered.
- *
- * Rendered from the config axios actually used whenever there is one: the one it keeps on its own
- * error, or the one it keeps on the response it did return, which covers the failures the helper
- * raises itself after reading that response. Both are the request as it went out -- merged, and past
- * any request interceptor that rewrote the url or the params -- while anything rebuilt here is a
- * reconstruction, and by the time a failure is described the factory may hand back a different
- * instance or its defaults may have moved on.
- *
- * A config that axios kept is rendered through an instance with no defaults of its own, for that
- * same reason: `getUri` merges the instance's defaults *under* the config it is given, so rendering
- * it through the caller's client would let a default added since the request appear in a url that
- * never carried it. The rebuild is the one case that does want those defaults -- there is no record
- * of the request to read them from -- so it goes through the client.
- *
- * Never throws. It runs on every failure path, inside the catch, so an exception here would replace
- * the error the caller is waiting for with one about building a diagnostic string -- and a client
- * without `getUri` (a hand-built stub, a mock) must not turn a mapped failure into a `TypeError`.
+ * The url as axios actually requests it, rendered by axios itself. An approximation
+ * renders arrays, nested objects and dates differently from the wire.
+ * `undefined` in gives `undefined` out. A call that failed before it had a url has none, and
+ * axios would answer with the client root. An empty string is a real root url and is rendered.
+ * Prefers the config axios kept on the error or response, since it reflects merging and
+ * interceptor rewrites. It is rendered through a defaults-free instance, because `getUri`
+ * merges instance defaults under the config. Only the rebuild goes through the client.
+ * Never throws. It runs inside the catch, and a client without `getUri` (a
+ * stub or mock) must not replace the original error with a `TypeError`.
  */
 export declare const requestedUrl: (client: AxiosClientFn, url: string | undefined, options?: AxiosRequestConfig, failure?: unknown, dispatched?: AxiosRequestConfig) => string | undefined;
 export type Abortable = {
@@ -65,13 +36,12 @@ export type Abortable = {
     abort: () => void;
     /** The generation a call starts in; a stale one must not write to state the caller can see. */
     generation: () => number;
-    /** Whether this instance has anything in flight. */
     loading: Ref<boolean>;
 };
 export type AbortableOptions = {
     /**
-     * Each call supersedes the one before it. The abort happens before the new call registers, so
-     * "the latest wins" holds by construction rather than by how the two calls happen to interleave.
+     * Each call supersedes the previous one. The abort happens before the new
+     * call registers, so the latest call always wins regardless of interleaving.
      */
     cancelPrevious?: boolean;
 };

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

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

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

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

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

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

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