@anzusystems/common-admin 1.47.0-beta.dev-1789897769 → 1.47.0-beta.dev-1789936376

package/dist/labs.d.ts

@@ -1156,9 +1156,11 @@ declare type FetchItemsMinimalType = (pagination: Ref<Pagination>, filterData: F
 
 declare type FetchItemsMinimalType_2 = (pagination: Ref<Pagination>, filterData: FilterData, filterConfig: FilterConfig) => Promise<any[]>;
 
-export declare type FetchItemsParams = {
+export declare type FetchItemsParams<B = never> = {
     urlTemplate?: string;
     urlParams?: UrlParams;
+    /** `null` omits the body, as everywhere in this family. */
+    body?: B;
     /** Stops this one call, leaving the instance's other calls alone. */
     signal?: AbortSignal;
 };
@@ -1296,6 +1298,9 @@ export declare const isLogType: (value: unknown) => value is LogTypeType;
 /** Whether `router.push({ hash })` would leave the hash intact — see `buildFilterHash`. */
 export declare const isRouterSafeHash: (hash: string) => boolean;
 
+/** Which of the two shapes a list arrives in. */
+export declare type ItemsShape = 'envelope' | 'array';
+
 declare const JOB_RESOURCE_USER_DATA_DELETE = "jobUserDataDelete";
 
 declare interface JobBase<T extends JobBaseResource = JobBaseResource> extends AnzuUserAndTimeTrackingAware {
@@ -2581,16 +2586,28 @@ export declare type UseApiFetchByIdsReturnType<T> = {
     /**
      * 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
+     * It is here so a caller does not have to keep its own: the hand-rolled version is a ref cleared in
+     * a `finally`, and that `finally` belongs to whichever call ended -- including one that
      * `cancelPrevious` just superseded, which turns the spinner off while the call the user is waiting
      * for is still running. This one never dips between a superseded call and the one that replaced it.
+     *
+     * Two things to know before replacing a hand-rolled flag with it.
+     *
+     * It covers what this helper does and nothing the caller does afterwards. A flag that also spans a
+     * follow-up cached fetch, a mapping pass or a second endpoint is not the same flag, and swapping it
+     * for this one turns the spinner off too early. Keep your own where it means more than "this helper
+     * is working".
+     *
+     * It belongs to the instance, so it is only reachable if you hold the instance. A factory that
+     * builds one per call and hands back the promise alone -- `const { execute } = useX()` inside the
+     * function that calls it -- cannot expose `loading`, `abort` or `cancelPrevious` at all. Hoist the
+     * instance to where the caller lives first.
      */
     loading: Ref<boolean>;
 };
 
 /**
- * A list read from an endpoint the caller has already written the query for, with no pagination.
+ * 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
@@ -2603,10 +2620,18 @@ export declare type UseApiFetchByIdsReturnType<T> = {
  * not the user's to change. So this is that helper with the pagination taken out: same core, same
  * error mapping, same list-body check, and it answers with the items rather than the envelope.
  *
+ * Read is the usual case, not the only one: a filter too big for a url goes out as a POST, and a
+ * mutation can answer with the list it just changed. The helper is about what comes back.
+ *
+ * Which shape it comes back in is declared, not guessed. `shape` picks the reader and the reader
+ * refuses the other shape, the way `optionalBody` makes a caller declare a body instead of leaving
+ * the helper to accept whatever turns up. A wrong declaration therefore fails loudly on the first
+ * run, which is what makes having a default safe at all.
+ *
  * It writes no metadata. An endpoint whose paging the user drives is `useApiFetchList`; a list read
  * page by page to the end is `useApiFetchListBatch`.
  */
-export declare const useApiFetchItems: <T>(params: UseApiFetchItemsParams) => UseApiFetchItemsReturnType<T>;
+export declare const useApiFetchItems: <T, B = never>(params: UseApiFetchItemsParams) => UseApiFetchItemsReturnType<T, B>;
 
 export declare type UseApiFetchItemsParams = {
     client: AxiosClientFn;
@@ -2625,18 +2650,45 @@ export declare type UseApiFetchItemsParams = {
     /** Anything axios takes except what this helper decides: the method, the url, the body and the signal. */
     options?: Omit<AxiosRequestConfig, 'method' | 'url' | 'data' | 'signal'>;
     cancelPrevious?: boolean;
+    /**
+     * Default `GET`, which is what 17 of the fleet's list reads and every existing caller here use.
+     *
+     * The others are here because a list is not only ever the answer to a read: a filter too big for a
+     * url goes out as a POST, and a mutation can answer with the list it just changed -- a swap, a
+     * shift, an upsert-all. What this helper is about is the answer, not the verb.
+     */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH';
+    /**
+     * Default `'envelope'`, because that is the fleet's norm and the exception is what gets declared.
+     *
+     * Leaving it out cannot go wrong quietly: the reader refuses the shape that was not declared, so a
+     * forgotten `'array'` fails on the first run rather than handing back something that is not a list.
+     */
+    shape?: ItemsShape;
 };
 
-export declare type UseApiFetchItemsReturnType<T> = {
-    execute: (params?: FetchItemsParams) => Promise<T[]>;
+export declare 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
+     * It is here so a caller does not have to keep its own: the hand-rolled version is a ref cleared in
+     * a `finally`, and that `finally` belongs to whichever call ended -- including one that
      * `cancelPrevious` just superseded, which turns the spinner off while the call the user is waiting
      * for is still running. This one never dips between a superseded call and the one that replaced it.
+     *
+     * Two things to know before replacing a hand-rolled flag with it.
+     *
+     * It covers what this helper does and nothing the caller does afterwards. A flag that also spans a
+     * follow-up cached fetch, a mapping pass or a second endpoint is not the same flag, and swapping it
+     * for this one turns the spinner off too early. Keep your own where it means more than "this helper
+     * is working".
+     *
+     * It belongs to the instance, so it is only reachable if you hold the instance. A factory that
+     * builds one per call and hands back the promise alone -- `const { execute } = useX()` inside the
+     * function that calls it -- cannot expose `loading`, `abort` or `cancelPrevious` at all. Hoist the
+     * instance to where the caller lives first.
      */
     loading: Ref<boolean>;
 };
@@ -2660,12 +2712,27 @@ export declare type UseApiFetchListBatchReturnType<T> = {
     execute: (filterData: FilterData<any>, filterConfig: FilterConfig<any>, params?: FetchListBatchParams) => Promise<T[]>;
     abort: () => void;
     /**
-     * True while this instance has a request in flight, false once the last one settles.
+     * True while this instance is working, false once it stops.
+     *
+     * Here that is the whole walk, not one request: a batch reads every page, and the flag stays up
+     * across the gaps between them and across the reading of each answer.
      *
-     * It is here so a caller does not have to keep its own: the hand-rolled version is a ref cleared
-     * in a `finally`, and that `finally` belongs to whichever call ended -- including one that
+     * It is here so a caller does not have to keep its own: the hand-rolled version is a ref cleared in
+     * a `finally`, and that `finally` belongs to whichever call ended -- including one that
      * `cancelPrevious` just superseded, which turns the spinner off while the call the user is waiting
      * for is still running. This one never dips between a superseded call and the one that replaced it.
+     *
+     * Two things to know before replacing a hand-rolled flag with it.
+     *
+     * It covers what this helper does and nothing the caller does afterwards. A flag that also spans a
+     * follow-up cached fetch, a mapping pass or a second endpoint is not the same flag, and swapping it
+     * for this one turns the spinner off too early. Keep your own where it means more than "this helper
+     * is working".
+     *
+     * It belongs to the instance, so it is only reachable if you hold the instance. A factory that
+     * builds one per call and hands back the promise alone -- `const { execute } = useX()` inside the
+     * function that calls it -- cannot expose `loading`, `abort` or `cancelPrevious` at all. Hoist the
+     * instance to where the caller lives first.
      */
     loading: Ref<boolean>;
 };
@@ -2687,10 +2754,22 @@ export declare type UseApiFetchListReturnType<T> = {
     /**
      * 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
+     * It is here so a caller does not have to keep its own: the hand-rolled version is a ref cleared in
+     * a `finally`, and that `finally` belongs to whichever call ended -- including one that
      * `cancelPrevious` just superseded, which turns the spinner off while the call the user is waiting
      * for is still running. This one never dips between a superseded call and the one that replaced it.
+     *
+     * Two things to know before replacing a hand-rolled flag with it.
+     *
+     * It covers what this helper does and nothing the caller does afterwards. A flag that also spans a
+     * follow-up cached fetch, a mapping pass or a second endpoint is not the same flag, and swapping it
+     * for this one turns the spinner off too early. Keep your own where it means more than "this helper
+     * is working".
+     *
+     * It belongs to the instance, so it is only reachable if you hold the instance. A factory that
+     * builds one per call and hands back the promise alone -- `const { execute } = useX()` inside the
+     * function that calls it -- cannot expose `loading`, `abort` or `cancelPrevious` at all. Hoist the
+     * instance to where the caller lives first.
      */
     loading: Ref<boolean>;
 };
@@ -2755,10 +2834,22 @@ export declare type UseApiRequestReturnType<R, B> = {
     /**
      * 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
+     * It is here so a caller does not have to keep its own: the hand-rolled version is a ref cleared in
+     * a `finally`, and that `finally` belongs to whichever call ended -- including one that
      * `cancelPrevious` just superseded, which turns the spinner off while the call the user is waiting
      * for is still running. This one never dips between a superseded call and the one that replaced it.
+     *
+     * Two things to know before replacing a hand-rolled flag with it.
+     *
+     * It covers what this helper does and nothing the caller does afterwards. A flag that also spans a
+     * follow-up cached fetch, a mapping pass or a second endpoint is not the same flag, and swapping it
+     * for this one turns the spinner off too early. Keep your own where it means more than "this helper
+     * is working".
+     *
+     * It belongs to the instance, so it is only reachable if you hold the instance. A factory that
+     * builds one per call and hands back the promise alone -- `const { execute } = useX()` inside the
+     * function that calls it -- cannot expose `loading`, `abort` or `cancelPrevious` at all. Hoist the
+     * instance to where the caller lives first.
      */
     loading: Ref<boolean>;
 };