@supersoniks/concorde 4.9.91 → 4.9.92

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersoniks/concorde",
-  "version": "4.9.91",
+  "version": "4.9.92",
   "license": "MIT",
   "type": "module",
   "main": "",

package/src/core/decorators/api.post.spec.ts

@@ -95,14 +95,14 @@ describe("post", () => {
     vi.mocked(API.prototype.postDetailed).mockClear();
 
     pub.set({ value: "second" });
-    localPost.send(el);
-    await flushSendFrames();
+    const payload = await localPost.send(el);
 
     expect(API.prototype.postDetailed).toHaveBeenCalledTimes(1);
     expect(API.prototype.postDetailed).toHaveBeenCalledWith(
       "items/local-send",
       { value: "second" },
     );
+    expect(payload?.result).toEqual({ ok: true });
   });
 
   it("peut décorer une méthode avec send après sa résolution", async () => {

package/src/core/decorators/api.spec.ts

@@ -209,16 +209,18 @@ describe("get", () => {
     const el = document.createElement(tag) as InstanceType<typeof C>;
     document.body.appendChild(el);
 
-    localGet.refetch(el);
-    await flushGetFrames();
+    const firstRefetch = localGet.refetch(el);
+    expect(firstRefetch).toBeInstanceOf(Promise);
+    const firstPayload = await firstRefetch;
     expect(API.prototype.getDetailed).toHaveBeenCalledTimes(1);
+    expect(firstPayload?.result).toEqual({ id: "loaded" });
 
     vi.mocked(API.prototype.getDetailed).mockClear();
     el.payload = mockPayload({ id: "manual" });
-    localGet.refetch(el);
-    await flushGetFrames();
+    const secondPayload = await localGet.refetch(el);
 
     expect(API.prototype.getDetailed).toHaveBeenCalledTimes(1);
+    expect(secondPayload?.result).toEqual({ id: "loaded" });
     expect(el.payload?.result).toEqual({ id: "loaded" });
   });
 
@@ -246,8 +248,7 @@ describe("get", () => {
     vi.mocked(API.prototype.getDetailed).mockClear();
 
     el.remove();
-    localGet.refetch(el);
-    await flushGetFrames();
+    await localGet.refetch(el);
 
     expect(API.prototype.getDetailed).not.toHaveBeenCalled();
   });
@@ -289,6 +290,46 @@ describe("get", () => {
     expect(API.prototype.getDetailed).toHaveBeenCalledWith("rows/84");
   });
 
+  it("attend le refetch avant la méthode avec when before", async () => {
+    const pubId = "getSpecMethodRefetchBefore";
+    PublisherManager.get(pubId).set(staticConfig);
+    const confKey = new DataProviderKey<APIConfiguration>(pubId);
+    const localGet = get(
+      new Endpoint<{ id: string }>("items/before"),
+      confKey,
+    );
+    const events: string[] = [];
+    const tag = "test-api-get-method-refetch-before";
+
+    class C extends HTMLElement {
+      @localGet
+      payload: ApiResult<{ id: string }> | null = null;
+
+      @refetch(localGet, { when: "before" })
+      reload() {
+        events.push("method");
+      }
+    }
+    if (!customElements.get(tag)) {
+      customElements.define(tag, C);
+    }
+
+    const el = document.createElement(tag) as InstanceType<typeof C>;
+    document.body.appendChild(el);
+    await flushGetFrames();
+    vi.mocked(API.prototype.getDetailed).mockClear();
+    events.length = 0;
+    vi.mocked(API.prototype.getDetailed).mockImplementation(async () => {
+      events.push("request");
+      return mockPayload({ id: "loaded" }) as never;
+    });
+
+    await el.reload();
+
+    expect(events).toEqual(["request", "method"]);
+    expect(API.prototype.getDetailed).toHaveBeenCalledWith("items/before");
+  });
+
   it("refetch automatique avec refetchEveryMs", async () => {
     vi.useFakeTimers();
     const itemEp = new Endpoint<{ id: string }>("items/1");

package/src/core/decorators/api.ts

@@ -83,14 +83,32 @@ function isLitHost(component: unknown): component is LitHost {
  * `rebindAll`, etc.) en un seul appel par frame — même principe que
  * `dynamicPropertyWatch.ts` (`scheduleObservedPropertyChanges`).
  */
-function createAnimationFrameCoalescedRunner(run: () => void): () => void {
+function createAnimationFrameCoalescedRunner<T>(
+  run: () => Promise<T>,
+): () => Promise<T> {
   let frameId: number | null = null;
+  let pending: Array<{
+    resolve: (value: T) => void;
+    reject: (reason: unknown) => void;
+  }> = [];
+
   return () => {
-    if (frameId !== null) return;
+    const promise = new Promise<T>((resolve, reject) => {
+      pending.push({ resolve, reject });
+    });
+
+    if (frameId !== null) return promise;
     frameId = requestAnimationFrame(() => {
       frameId = null;
-      run();
+      const current = pending;
+      pending = [];
+      void run().then(
+        (value) => current.forEach(({ resolve }) => resolve(value)),
+        (reason) => current.forEach(({ reject }) => reject(reason)),
+      );
     });
+
+    return promise;
   };
 }
 
@@ -168,8 +186,7 @@ type TriggerPublisherBinding = {
 };
 
 type OperationBinding = {
-  component: object;
-  run: () => void;
+  run: () => Promise<unknown>;
 };
 
 /**
@@ -182,8 +199,8 @@ type OperationBinding = {
 class ApiOperationController {
   private readonly bindings = new WeakMap<object, Set<OperationBinding>>();
 
-  bind(component: object, run: () => void): () => void {
-    const binding: OperationBinding = { component, run };
+  bind(component: object, run: () => Promise<unknown>): () => void {
+    const binding: OperationBinding = { run };
     let componentBindings = this.bindings.get(component);
     if (!componentBindings) {
       componentBindings = new Set();
@@ -201,8 +218,13 @@ class ApiOperationController {
     };
   }
 
-  run(component: object): void {
-    this.bindings.get(component)?.forEach(({ run }) => run());
+  run(component: object): Promise<unknown> {
+    const runs = [...(this.bindings.get(component) ?? [])].map(({ run }) =>
+      run(),
+    );
+    if (runs.length === 0) return Promise.resolve(undefined);
+    if (runs.length === 1) return runs[0];
+    return Promise.all(runs).then(() => undefined);
   }
 }
 
@@ -220,8 +242,10 @@ export type GetDecoratorHandle<T, Host extends object = object> =
      *
      * Le handle peut être conservé :
      * `const usersGet = get(new Endpoint<User[]>("users"))`.
+     *
+     * La Promise est résolue après la fin du GET.
      */
-    refetch(component: Host): void;
+    refetch(component: Host): Promise<ApiResult<T> | undefined>;
   };
 
 export type ApiSendDecoratorHandle<T, Host extends object = object> =
@@ -230,19 +254,22 @@ export type ApiSendDecoratorHandle<T, Host extends object = object> =
      * Relance l'opération d'écriture avec le body courant.
      *
      * Disponible avec `post`, `put` et `patch`.
+     * La Promise est résolue après la fin de l'opération.
      */
-    send(component: Host): void;
+    send(component: Host): Promise<ApiResult<T> | undefined>;
   };
 
 export type ApiMethodActionOptions = {
   /**
    * Moment du déclenchement par rapport à la méthode.
-   * `after` est la valeur par défaut ; avec une Promise, l'action attend sa résolution.
+   * `after` est la valeur par défaut ; l'action attend la résolution d'une
+   * Promise retournée par la méthode.
+   * Avec `before`, l'action est terminée avant l'appel de la méthode.
    */
   when?: "before" | "after";
 };
 
-type ApiMethod = (this: object, ...args: any[]) => unknown;
+type ApiMethod = (this: object, ...args: unknown[]) => unknown;
 
 function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
   return (
@@ -253,7 +280,7 @@ function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
 }
 
 function createApiMethodActionDecorator(
-  action: (component: object) => void,
+  action: (component: object) => Promise<unknown>,
   options?: ApiMethodActionOptions,
 ): MethodDecorator {
   const when = options?.when ?? "after";
@@ -262,22 +289,19 @@ function createApiMethodActionDecorator(
     const original = descriptor.value as ApiMethod | undefined;
     if (!original) return;
 
-    const wrapped = function (this: object, ...args: any[]) {
+    const wrapped = function (this: object, ...args: unknown[]) {
       if (when === "before") {
-        action(this);
-        return original.apply(this, args);
+        return action(this).then(() => original.apply(this, args));
       }
 
       const result = original.apply(this, args);
       if (isPromiseLike(result)) {
         return result.then((value) => {
-          action(this);
-          return value;
+          return action(this).then(() => value);
         });
       }
 
-      action(this);
-      return result;
+      return action(this).then(() => result);
     };
     descriptor.value = wrapped as unknown as typeof descriptor.value;
   };
@@ -362,7 +386,7 @@ function detachConfigPublisher(state: ApiGetState): void {
  * payload?: ApiResult<User[]>;
  *
  * refresh() {
- *   usersGet.refetch(this);
+ *   await usersGet.refetch(this);
  * }
  *
  * @example
@@ -467,18 +491,18 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
         if (!state.refetchEveryMs || state.refetchEveryMs <= 0) return;
         state.refetchTimeoutId = setTimeout(() => {
           state.refetchTimeoutId = null;
-          runFetch();
+          void runFetch().catch(() => {});
         }, state.refetchEveryMs);
       };
 
-      const runFetch = () => {
+      const runFetch = async (): Promise<ApiResult<T> | undefined> => {
         const resolution = isDynamicPath
           ? resolveDynamicPath(component, pathTemplate, pathOptions)
           : { ready: true, path: pathTemplate };
         if (!resolution.ready || !resolution.path) {
           comp[propertyKey] = undefined;
           scheduleRefetch();
-          return;
+          return undefined;
         }
         let config: APIConfiguration | null = null;
         if (usesPublisherConfig && configurationKeyPath) {
@@ -490,7 +514,7 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
           if (!configRes.ready || !configRes.path) {
             comp[propertyKey] = undefined;
             scheduleRefetch();
-            return;
+            return undefined;
           }
           const configPublisher = getPublisherFromPath(configRes.path);
           config = readApiConfigurationFromPublisher(configPublisher);
@@ -499,7 +523,10 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
         }
         if (!isScopedConfigurationReady(config)) {
           if (!usesPublisherConfig && !state.scopeWatchCleanup) {
-            const scopeWatch = watchScopedConfiguration(component, runFetch);
+            const scopeWatch = watchScopedConfiguration(
+              component,
+              scheduleFetchAndIgnoreErrors,
+            );
             state.scopeWatchCleanup = scopeWatch;
             state.cleanupWatchers.push(() => {
               scopeWatch();
@@ -507,20 +534,21 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
             });
           }
           scheduleRefetch();
-          return;
+          return undefined;
         }
         const generation = ++state.requestGeneration;
         const api = new API(config);
-        void api
-          .getDetailed<T>(resolution.path)
-          .then((payload?: ApiResult<T>) => {
-            if (generation !== state.requestGeneration) return;
-            comp[propertyKey] = payload;
-            scheduleRefetch();
-          });
+        const payload = await api.getDetailed<T>(resolution.path);
+        if (generation !== state.requestGeneration) return payload;
+        comp[propertyKey] = payload;
+        scheduleRefetch();
+        return payload;
       };
 
       const scheduleFetch = createAnimationFrameCoalescedRunner(runFetch);
+      const scheduleFetchAndIgnoreErrors = () => {
+        void scheduleFetch().catch(() => {});
+      };
       state.cleanupOperation = operationController.bind(
         component,
         scheduleFetch,
@@ -539,7 +567,7 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
         }
         const publisher = getPublisherFromPath(triggerResolution.path);
         if (!publisher) return;
-        const invalidateHandler = () => scheduleFetch();
+        const invalidateHandler = scheduleFetchAndIgnoreErrors;
         publisher.onInvalidate(invalidateHandler);
         state.triggerPublisher = publisher;
         state.triggerInvalidateHandler = invalidateHandler;
@@ -562,7 +590,7 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
           comp[propertyKey] = undefined;
           return;
         }
-        const mutationHandler = () => scheduleFetch();
+        const mutationHandler = scheduleFetchAndIgnoreErrors;
         publisher.onInternalMutation(mutationHandler);
         state.configPublisher = publisher;
         state.configMutationHandler = mutationHandler;
@@ -572,7 +600,7 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
         rebindTriggerPublisher();
         rebindPublisherConfig();
         if (!usesPublisherConfig) {
-          scheduleFetch();
+          scheduleFetchAndIgnoreErrors();
         }
       };
 
@@ -597,13 +625,13 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
                 getDynamicWatchKeys.hooked,
                 component,
                 dependency,
-                () => scheduleFetch(),
+                scheduleFetchAndIgnoreErrors,
               );
               state.cleanupWatchers.push(unsubscribe);
             }
           }
           rebindTriggerPublisher();
-          runFetch();
+          void runFetch().catch(() => {});
         };
         state.cleanupWatchers.push(
           scheduleAfterHostReady(component, startScopedFetch),
@@ -628,7 +656,9 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
   } as GetDecoratorHandle<T, object>;
 
   decorator.refetch = (component: object) => {
-    operationController.run(component);
+    return operationController.run(component) as Promise<
+      ApiResult<T> | undefined
+    >;
   };
 
   return decorator;
@@ -823,18 +853,18 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
           if (!state.refetchEveryMs || state.refetchEveryMs <= 0) return;
           state.refetchTimeoutId = setTimeout(() => {
             state.refetchTimeoutId = null;
-            runSend();
+            void runSend().catch(() => {});
           }, state.refetchEveryMs);
         };
 
-        const runSend = () => {
+        const runSend = async (): Promise<ApiResult<unknown> | undefined> => {
           const resolution = isDynamicPath
             ? resolveDynamicPath(component, pathTemplate, pathOptions)
             : { ready: true, path: pathTemplate };
           if (!resolution.ready || !resolution.path) {
             comp[propertyKey] = undefined;
             scheduleRefetch();
-            return;
+            return undefined;
           }
 
           const bodyResolution = resolveDynamicPath(
@@ -845,7 +875,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
           if (!bodyResolution.ready || !bodyResolution.path) {
             comp[propertyKey] = undefined;
             scheduleRefetch();
-            return;
+            return undefined;
           }
 
           const bodyPublisher = getPublisherFromPath(bodyResolution.path);
@@ -855,7 +885,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
             (body === null || body === undefined)
           ) {
             scheduleRefetch();
-            return;
+            return undefined;
           }
 
           let config: APIConfiguration | null = null;
@@ -868,7 +898,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
             if (!configRes.ready || !configRes.path) {
               comp[propertyKey] = undefined;
               scheduleRefetch();
-              return;
+              return undefined;
             }
             const configPublisher = getPublisherFromPath(configRes.path);
             config = readApiConfigurationFromPublisher(configPublisher);
@@ -878,7 +908,10 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
 
           if (!isScopedConfigurationReady(config)) {
             if (!usesPublisherConfig && !state.scopeWatchCleanup) {
-              const scopeWatch = watchScopedConfiguration(component, runSend);
+              const scopeWatch = watchScopedConfiguration(
+                component,
+                scheduleSendAndIgnoreErrors,
+              );
               state.scopeWatchCleanup = scopeWatch;
               state.cleanupWatchers.push(() => {
                 scopeWatch();
@@ -886,21 +919,22 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
               });
             }
             scheduleRefetch();
-            return;
+            return undefined;
           }
 
           const generation = ++state.requestGeneration;
           const api = new API(config);
-          void callDetailed(api, resolution.path, body).then(
-            (payload?: ApiResult<unknown>) => {
-              if (generation !== state.requestGeneration) return;
-              comp[propertyKey] = payload;
-              scheduleRefetch();
-            },
-          );
+          const payload = await callDetailed(api, resolution.path, body);
+          if (generation !== state.requestGeneration) return payload;
+          comp[propertyKey] = payload;
+          scheduleRefetch();
+          return payload;
         };
 
         const scheduleSend = createAnimationFrameCoalescedRunner(runSend);
+        const scheduleSendAndIgnoreErrors = () => {
+          void scheduleSend().catch(() => {});
+        };
         state.cleanupOperation = operationController.bind(
           component,
           scheduleSend,
@@ -921,7 +955,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
           }
           const publisher = getPublisherFromPath(bodyResolution.path);
           if (!publisher) return;
-          const mutationHandler = () => scheduleSend();
+          const mutationHandler = scheduleSendAndIgnoreErrors;
           publisher.onInternalMutation(mutationHandler);
           state.bodyPublisher = publisher;
           state.bodyMutationHandler = mutationHandler;
@@ -940,7 +974,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
           }
           const publisher = getPublisherFromPath(triggerResolution.path);
           if (!publisher) return;
-          const invalidateHandler = () => scheduleSend();
+          const invalidateHandler = scheduleSendAndIgnoreErrors;
           publisher.onInvalidate(invalidateHandler);
           state.triggerPublisher = publisher;
           state.triggerInvalidateHandler = invalidateHandler;
@@ -963,7 +997,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
             comp[propertyKey] = undefined;
             return;
           }
-          const mutationHandler = () => scheduleSend();
+          const mutationHandler = scheduleSendAndIgnoreErrors;
           publisher.onInternalMutation(mutationHandler);
           state.configPublisher = publisher;
           state.configMutationHandler = mutationHandler;
@@ -974,7 +1008,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
           rebindTriggerPublisher();
           rebindPublisherConfig();
           if (state.autoPostOnBodyMutation) {
-            scheduleSend();
+            scheduleSendAndIgnoreErrors();
           }
         };
 
@@ -1003,7 +1037,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
                   getDynamicWatchKeys.hooked,
                   component,
                   dependency,
-                  () => scheduleSend(),
+                  scheduleSendAndIgnoreErrors,
                 );
                 state.cleanupWatchers.push(unsubscribe);
               }
@@ -1011,7 +1045,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
             rebindBodyPublisher();
             rebindTriggerPublisher();
             if (state.autoPostOnBodyMutation) {
-              scheduleSend();
+              scheduleSendAndIgnoreErrors();
             }
           };
           state.cleanupWatchers.push(
@@ -1038,7 +1072,9 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
     } as ApiSendDecoratorHandle<T, object>;
 
     decorator.send = (component: object) => {
-      operationController.run(component);
+      return operationController.run(component) as Promise<
+        ApiResult<T> | undefined
+      >;
     };
 
     return decorator;
@@ -1061,7 +1097,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
  * @save
  * payload?: ApiResult<User>;
  * // Dans un handler du composant :
- * save.send(this);
+ * await save.send(this);
  */
 export function post<T, B, Ue = any>(
   endpoint: Endpoint<T, Ue>,

package/src/docs/_decorators/get.md

@@ -37,15 +37,20 @@ const usersGet = get(new Endpoint<User[]>("users"));
 @state()
 payload?: ApiResult<User[]>;
 
-refresh() {
-  usersGet.refetch(this);
+async refresh() {
+  const payload = await usersGet.refetch(this);
+  console.log(payload?.result);
 }
 ```
 
+`refetch(component)` returns a `Promise<ApiResult<T> | undefined>` that resolves
+after the GET has completed.
+
 ### From a method decorator
 
 The refetch can decorate a local method. The default is `after`; if the
-method returns a Promise, the GET waits for its resolution.
+method returns a Promise, the GET waits for its resolution. The decorated method
+call also waits for the refetch to complete.
 
 ```typescript
 import { refetch } from "@supersoniks/concorde/decorators";
@@ -56,12 +61,12 @@ async reload() {
 }
 ```
 
-Use `{ when: "before" }` when the GET must be scheduled before the method:
+Use `{ when: "before" }` when the GET must complete before the method runs:
 
 ```typescript
 @refetch(usersGet, { when: "before" })
 reloadBefore() {
-  // The refetch is scheduled before this method runs.
+  // The refetch has completed before this method runs.
 }
 ```
 
@@ -76,6 +81,7 @@ configuration key is provided.
 - `skipEmptyPlaceholder`: blocks the GET when `${prop}` is `""`.
 - `refetchEveryMs`: automatically runs the GET again after this interval
   (milliseconds). Omit the option, or use `0`, to disable polling.
+- `triggerKey`: a publisher whose `invalidate()` runs the GET again.
 
 With a configuration key, use:
 
@@ -88,6 +94,7 @@ With a configuration key, use:
 - when the component connects and configuration is available;
 - when a property used in `${...}` changes;
 - when a configuration publisher changes;
+- when the `triggerKey` publisher is invalidated;
 - after each response when `refetchEveryMs` is set.
 
 See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for

package/src/docs/_decorators/patch.md

@@ -19,11 +19,15 @@ payload?: ApiResult<User>;
 To run the operation again from the component:
 
 ```typescript
-savePatch() {
-  patchUser.send(this);
+async savePatch() {
+  await patchUser.send(this);
 }
 ```
 
+`send(component)` returns a Promise resolved after the PATCH completes. See
+[@post](#docs/_decorators/post.md/post) for the method-decorator form and the
+`when: "before"` option.
+
 The PATCH is also sent automatically when the body mutates, unless
 `autoPostOnBodyMutation: false` is set. The available options are described in
 [@post](#docs/_decorators/post.md/post):
@@ -32,6 +36,7 @@ The PATCH is also sent automatically when the body mutates, unless
 - `skipIfBodyMissing`
 - `refetchEveryMs`
 - `skipEmptyPlaceholder`
+- `triggerKey`
 
 Pass explicit API configuration as the third argument:
 

package/src/docs/_decorators/post.md

@@ -32,18 +32,21 @@ Keep the decorator to access `send(component)`. The body is read again when the
 operation runs.
 
 ```typescript
-saveAgain() {
-  createUser.send(this);
+async saveAgain() {
+  const payload = await createUser.send(this);
+  console.log(payload?.result);
 }
 ```
 
-`send()` is useful for “Save” or “Retry” buttons. It can repeat an operation
-with side effects.
+`send()` returns a `Promise<ApiResult<T> | undefined>` that resolves after the
+operation completes. It is useful for “Save” or “Retry” buttons and can repeat
+an operation with side effects.
 
 ### From a method decorator
 
 The send action can decorate a local method. It runs after the method by
-default and waits for an eventual Promise to resolve:
+default, waits for an eventual Promise to resolve, and the decorated method
+call waits for the send to complete:
 
 ```typescript
 import { send } from "@supersoniks/concorde/decorators";
@@ -54,12 +57,12 @@ async save() {
 }
 ```
 
-Use `{ when: "before" }` when the body must be sent before the method runs:
+Use `{ when: "before" }` when the send must complete before the method runs:
 
 ```typescript
 @send(createUser, { when: "before" })
 saveBefore() {
-  // The POST is scheduled before this method runs.
+  // The POST has completed before this method runs.
 }
 ```
 
@@ -80,6 +83,7 @@ is provided.
   repeating the operation is intended.
 - `skipEmptyPlaceholder`: block the request when a `${...}` placeholder is
   `""`.
+- `triggerKey`: a publisher whose `invalidate()` sends the POST again.
 
 With a configuration key:
 
@@ -96,6 +100,7 @@ dynamic path details.
 - after a body mutation, unless `autoPostOnBodyMutation: false`;
 - when a property used in `${...}` changes;
 - when a configuration publisher changes;
+- when the `triggerKey` publisher is invalidated;
 - when `send()` is called;
 - after each response when `refetchEveryMs` is set.