@supersoniks/concorde 4.9.9 → 4.9.92

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;
   };
 }
 
@@ -167,6 +185,148 @@ type TriggerPublisherBinding = {
   triggerInvalidateHandler: (() => void) | null;
 };
 
+type OperationBinding = {
+  run: () => Promise<unknown>;
+};
+
+/**
+ * Handle interne des décorateurs API.
+ *
+ * Le WeakMap cible l'instance connectée, pas la valeur de payload : une
+ * opération peut donc être relancée avant son premier résultat et reste
+ * indépendante d'une affectation manuelle de la propriété décorée.
+ */
+class ApiOperationController {
+  private readonly bindings = new WeakMap<object, Set<OperationBinding>>();
+
+  bind(component: object, run: () => Promise<unknown>): () => void {
+    const binding: OperationBinding = { run };
+    let componentBindings = this.bindings.get(component);
+    if (!componentBindings) {
+      componentBindings = new Set();
+      this.bindings.set(component, componentBindings);
+    }
+    componentBindings.add(binding);
+
+    return () => {
+      const currentBindings = this.bindings.get(component);
+      if (!currentBindings) return;
+      currentBindings.delete(binding);
+      if (currentBindings.size === 0) {
+        this.bindings.delete(component);
+      }
+    };
+  }
+
+  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);
+  }
+}
+
+type ApiPropertyDecorator<T, Host extends object> = <K extends string>(
+  target: Host & {
+    [P in K]?: ApiResult<T> | null | undefined;
+  },
+  propertyKey: K,
+) => void;
+
+export type GetDecoratorHandle<T, Host extends object = object> =
+  ApiPropertyDecorator<T, Host> & {
+    /**
+     * Relance le GET pour cette instance connectée.
+     *
+     * 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): Promise<ApiResult<T> | undefined>;
+  };
+
+export type ApiSendDecoratorHandle<T, Host extends object = object> =
+  ApiPropertyDecorator<T, Host> & {
+    /**
+     * 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): Promise<ApiResult<T> | undefined>;
+  };
+
+export type ApiMethodActionOptions = {
+  /**
+   * Moment du déclenchement par rapport à la méthode.
+   * `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: unknown[]) => unknown;
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value !== null &&
+    (typeof value === "object" || typeof value === "function") &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}
+
+function createApiMethodActionDecorator(
+  action: (component: object) => Promise<unknown>,
+  options?: ApiMethodActionOptions,
+): MethodDecorator {
+  const when = options?.when ?? "after";
+
+  return (_target, _propertyKey, descriptor) => {
+    const original = descriptor.value as ApiMethod | undefined;
+    if (!original) return;
+
+    const wrapped = function (this: object, ...args: unknown[]) {
+      if (when === "before") {
+        return action(this).then(() => original.apply(this, args));
+      }
+
+      const result = original.apply(this, args);
+      if (isPromiseLike(result)) {
+        return result.then((value) => {
+          return action(this).then(() => value);
+        });
+      }
+
+      return action(this).then(() => result);
+    };
+    descriptor.value = wrapped as unknown as typeof descriptor.value;
+  };
+}
+
+export function refetch<T, Host extends object = object>(
+  handle: GetDecoratorHandle<T, Host>,
+  options?: ApiMethodActionOptions,
+): MethodDecorator {
+  return createApiMethodActionDecorator(
+    (component) => handle.refetch(component as Host),
+    options,
+  );
+}
+
+export function send<T, Host extends object = object>(
+  handle: ApiSendDecoratorHandle<T, Host>,
+  options?: ApiMethodActionOptions,
+): MethodDecorator {
+  return createApiMethodActionDecorator(
+    (component) => handle.send(component as Host),
+    options,
+  );
+}
+
 type RefetchScheduleState = {
   refetchTimeoutId: ReturnType<typeof setTimeout> | null;
   refetchEveryMs: number;
@@ -175,6 +335,7 @@ type RefetchScheduleState = {
 type ApiGetState = TriggerPublisherBinding &
   RefetchScheduleState & {
     cleanupWatchers: Array<() => void>;
+    cleanupOperation: (() => void) | null;
     requestGeneration: number;
     configPublisher: DataProvider | null;
     configMutationHandler: (() => void) | null;
@@ -202,8 +363,12 @@ function detachConfigPublisher(state: ApiGetState): void {
  * `PublisherManager` sur le chemin résolu (même syntaxe dynamique que `@subscribe`).
  * Toute mutation interne du publisher (`onInternalMutation`) relance le GET.
  *
- * **Options** (`GetOptions`) : `triggerKey` — `PublisherManager.get(...).invalidate()` relance le GET ;
- * `refetchEveryMs` — polling automatique.
+ * Le décorateur retourné expose `refetch(component)` pour relancer le GET d'une
+ * instance connectée. Pour déclencher le refetch depuis un autre composant,
+ * utiliser `triggerKey` puis `PublisherManager.get(...).invalidate()`.
+ *
+ * **Options** (`GetOptions`) : `triggerKey` — signal de refetch externe ;
+ * `refetchEveryMs` — polling automatique (0 ou absent = désactivé).
  *
  * @example
  * @get(new Endpoint<User, { userId: string }>("users/${userId}"))
@@ -216,58 +381,48 @@ function detachConfigPublisher(state: ApiGetState): void {
  * payload?: ApiResult<Thing>;
  *
  * @example
+ * const usersGet = get(new Endpoint<User[]>("users"));
+ * @usersGet
+ * payload?: ApiResult<User[]>;
+ *
+ * refresh() {
+ *   await usersGet.refetch(this);
+ * }
+ *
+ * @example
  * @get(usersEndpoint, { triggerKey: refreshUsersKey })
  * payload?: ApiResult<User[]>;
  * // PublisherManager.get("users.refresh").invalidate() → refetch
  */
 export function get<T, Ue = any>(
   endpoint: Endpoint<T, Ue>,
-): <K extends string>(
-  target: DataProviderKeyHost<Ue> & {
-    [P in K]?: ApiResult<T> | null | undefined;
-  },
-  propertyKey: K,
-) => void;
+): GetDecoratorHandle<T, DataProviderKeyHost<Ue>>;
 export function get<T, Ue = any, Uk = any>(
   endpoint: Endpoint<T, Ue>,
   configurationKey: DataProviderKey<APIConfiguration, Uk>,
-): <K extends string>(
-  target: DataProviderKeyHost<Ue> &
-    DataProviderKeyHost<Uk> & {
-      [P in K]?: ApiResult<T> | null | undefined;
-    },
-  propertyKey: K,
-) => void;
+): GetDecoratorHandle<
+  T,
+  DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>
+>;
 export function get<T, Ue = any, Uk = any>(
   endpoint: Endpoint<T, Ue>,
   options: GetOptions,
-): <K extends string>(
-  target: DataProviderKeyHost<Ue> & {
-    [P in K]?: ApiResult<T> | null | undefined;
-  },
-  propertyKey: K,
-) => void;
+): GetDecoratorHandle<T, DataProviderKeyHost<Ue>>;
 export function get<T, Ue = any, Uk = any, Ut = any>(
   endpoint: Endpoint<T, Ue>,
   configurationKey: DataProviderKey<APIConfiguration, Uk>,
   options: GetOptions,
-): <K extends string>(
-  target: DataProviderKeyHost<Ue> &
-    DataProviderKeyHost<Uk> & {
-      [P in K]?: ApiResult<T> | null | undefined;
-    },
-  propertyKey: K,
-) => void;
+): GetDecoratorHandle<
+  T,
+  DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>
+>;
 export function get<T, Ue = any, Uk = any, _Ut = any>(
   endpoint: Endpoint<T, Ue>,
   configurationKeyOrOptions?:
     | DataProviderKey<APIConfiguration, Uk>
     | GetOptions,
   maybeOptions?: GetOptions,
-): <K extends string>(
-  target: object & { [P in K]?: ApiResult<T> | null | undefined },
-  propertyKey: K,
-) => void {
+): GetDecoratorHandle<T, object> {
   const pathTemplate = endpoint.path;
   const configurationKey = isGetOptions(configurationKeyOrOptions)
     ? undefined
@@ -297,8 +452,9 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
   const isDynamicPath = endpointDynamicDependencies.length > 0;
   const usesPublisherConfig = Boolean(configurationKeyPath);
   const refetchEveryMs = options?.refetchEveryMs ?? 0;
+  const operationController = new ApiOperationController();
 
-  return function (target: object, propertyKey: string) {
+  const decorator = function (target: object, propertyKey: string) {
     if (!target) return;
     setSubscribable(target);
     const stateKey = `__get_state_${propertyKey}`;
@@ -309,6 +465,7 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
       if (!state) {
         state = {
           cleanupWatchers: [],
+          cleanupOperation: null,
           requestGeneration: 0,
           configPublisher: null,
           configMutationHandler: null,
@@ -321,6 +478,8 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
         comp[stateKey] = state;
       }
 
+      state.cleanupOperation?.();
+      state.cleanupOperation = null;
       state.cleanupWatchers.forEach((cleanup) => cleanup());
       state.cleanupWatchers = [];
       state.requestGeneration++;
@@ -332,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) {
@@ -355,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);
@@ -364,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();
@@ -372,20 +534,25 @@ 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,
+      );
 
       const rebindTriggerPublisher = () => {
         detachTriggerPublisher(state);
@@ -400,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;
@@ -423,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;
@@ -433,7 +600,7 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
         rebindTriggerPublisher();
         rebindPublisherConfig();
         if (!usesPublisherConfig) {
-          scheduleFetch();
+          scheduleFetchAndIgnoreErrors();
         }
       };
 
@@ -458,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),
@@ -476,6 +643,8 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
       const comp = component as Record<string, unknown>;
       const state = comp[stateKey] as ApiGetState | undefined;
       if (!state) return;
+      state.cleanupOperation?.();
+      state.cleanupOperation = null;
       detachConfigPublisher(state);
       detachTriggerPublisher(state);
       clearRefetch(state);
@@ -484,27 +653,38 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
       state.requestGeneration++;
       comp[propertyKey] = undefined;
     });
+  } as GetDecoratorHandle<T, object>;
+
+  decorator.refetch = (component: object) => {
+    return operationController.run(component) as Promise<
+      ApiResult<T> | undefined
+    >;
   };
+
+  return decorator;
 }
 
 export type GetOptions<Uk = any> = DynamicPathOptions & {
-  /** Intervalle de refetch automatique (ms). 0 ou absent = pas de polling. */
+  /** Intervalle de refetch automatique (ms). 0 ou absent = désactivé. */
   refetchEveryMs?: number;
-  /** Publisher dont `invalidate()` relance le GET. */
+  /** Publisher-signal dont `invalidate()` relance le GET. */
   triggerKey?: DataProviderKey<unknown, Uk>;
 };
 
 export type ApiSendOptions<Uk = any> = DynamicPathOptions & {
-  /** Intervalle de renvoi automatique (ms). 0 ou absent = pas de polling. */
+  /**
+   * Intervalle de renvoi automatique (ms).
+   * 0 ou absent = désactivé ; attention aux effets de bord de l'opération.
+   */
   refetchEveryMs?: number;
-  /** Ne pas envoyer si le body publisher est null/undefined (défaut: true). */
+  /** Ignore l'envoi si le body vaut null/undefined (défaut : true). */
   skipIfBodyMissing?: boolean;
   /**
-   * Relancer l'envoi quand le body publisher mute (défaut: true).
-   * `false` : le body est lu au moment de l'envoi ; déclencher via `triggerKey.invalidate()`.
+   * Relance l'envoi quand le body publisher mute (défaut : true).
+   * `false` : le body est lu au moment de `send()` ou `triggerKey.invalidate()`.
    */
   autoPostOnBodyMutation?: boolean;
-  /** Publisher dont `invalidate()` relance l'envoi (relit le body courant). */
+  /** Publisher-signal dont `invalidate()` relance l'envoi avec le body courant. */
   triggerKey?: DataProviderKey<unknown, Uk>;
 };
 
@@ -591,10 +771,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
       | DataProviderKey<APIConfiguration, Uk>
       | ApiSendOptions<Ut>,
     maybeOptions?: ApiSendOptions<Ut>,
-  ): <K extends string>(
-    target: object & { [P in K]?: ApiResult<T> | null | undefined },
-    propertyKey: K,
-  ) => void {
+  ): ApiSendDecoratorHandle<T, object> {
     const pathTemplate = endpoint.path;
     const bodyKeyPath = bodyKey.path;
     const configurationKey = isApiSendOptions(configurationKeyOrOptions)
@@ -631,8 +808,9 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
       skipEmptyPlaceholder: options?.skipEmptyPlaceholder,
     };
     const stateKeyPrefix = `__${method.toLowerCase()}_state_`;
+    const operationController = new ApiOperationController();
 
-    return function (target: object, propertyKey: string) {
+    const decorator = function (target: object, propertyKey: string) {
       if (!target) return;
       setSubscribable(target);
       const stateKey = `${stateKeyPrefix}${propertyKey}`;
@@ -643,6 +821,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
         if (!state) {
           state = {
             cleanupWatchers: [],
+            cleanupOperation: null,
             requestGeneration: 0,
             configPublisher: null,
             configMutationHandler: null,
@@ -659,6 +838,8 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
           comp[stateKey] = state;
         }
 
+        state.cleanupOperation?.();
+        state.cleanupOperation = null;
         state.cleanupWatchers.forEach((cleanup) => cleanup());
         state.cleanupWatchers = [];
         state.requestGeneration++;
@@ -672,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(
@@ -694,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);
@@ -704,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;
@@ -717,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);
@@ -727,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();
@@ -735,21 +919,26 @@ 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,
+        );
 
         const rebindBodyPublisher = () => {
           detachBodyPublisher(state);
@@ -766,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;
@@ -785,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;
@@ -808,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;
@@ -819,7 +1008,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
           rebindTriggerPublisher();
           rebindPublisherConfig();
           if (state.autoPostOnBodyMutation) {
-            scheduleSend();
+            scheduleSendAndIgnoreErrors();
           }
         };
 
@@ -848,7 +1037,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
                   getDynamicWatchKeys.hooked,
                   component,
                   dependency,
-                  () => scheduleSend(),
+                  scheduleSendAndIgnoreErrors,
                 );
                 state.cleanupWatchers.push(unsubscribe);
               }
@@ -856,7 +1045,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
             rebindBodyPublisher();
             rebindTriggerPublisher();
             if (state.autoPostOnBodyMutation) {
-              scheduleSend();
+              scheduleSendAndIgnoreErrors();
             }
           };
           state.cleanupWatchers.push(
@@ -869,6 +1058,8 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
         const comp = component as Record<string, unknown>;
         const state = comp[stateKey] as ApiSendState | undefined;
         if (!state) return;
+        state.cleanupOperation?.();
+        state.cleanupOperation = null;
         detachConfigPublisher(state);
         detachBodyPublisher(state);
         detachTriggerPublisher(state);
@@ -878,7 +1069,15 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
         state.requestGeneration++;
         comp[propertyKey] = undefined;
       });
+    } as ApiSendDecoratorHandle<T, object>;
+
+    decorator.send = (component: object) => {
+      return operationController.run(component) as Promise<
+        ApiResult<T> | undefined
+      >;
     };
+
+    return decorator;
   };
 }
 
@@ -886,54 +1085,46 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
  * Décorateur **`@post`** : envoie des données via `API.postDetailed` et assigne un
  * `ApiResult<T>` (`request`, `response`, `result` typé `T`).
  *
- * Le body est lu depuis un `DataProviderKey` (mutations et assignations relancent le POST).
+ * Le body est lu depuis un `DataProviderKey`. Par défaut, une mutation du body
+ * relance le POST ; `send(component)` permet de le relancer explicitement.
  *
  * @example
  * @post(new Endpoint<SyncResult, { sessionId: string }>("sessions/${sessionId}/sync"), syncRequestKey)
  * payload?: ApiResult<SyncResult>;
+ *
+ * @example
+ * const save = post(new Endpoint<User>("users"), userRequestKey);
+ * @save
+ * payload?: ApiResult<User>;
+ * // Dans un handler du composant :
+ * await save.send(this);
  */
 export function post<T, B, Ue = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
-): <K extends string>(
-  target: DataProviderKeyHost<Ue> & {
-    [P in K]?: ApiResult<T> | null | undefined;
-  },
-  propertyKey: K,
-) => void;
+): ApiSendDecoratorHandle<T, DataProviderKeyHost<Ue>>;
 export function post<T, B, Ue = any, Uk = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
   configurationKey: DataProviderKey<APIConfiguration, Uk>,
-): <K extends string>(
-  target: DataProviderKeyHost<Ue> &
-    DataProviderKeyHost<Uk> & {
-      [P in K]?: ApiResult<T> | null | undefined;
-    },
-  propertyKey: K,
-) => void;
+): ApiSendDecoratorHandle<
+  T,
+  DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>
+>;
 export function post<T, B, Ue = any, Uk = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
   options: PostOptions<Uk>,
-): <K extends string>(
-  target: DataProviderKeyHost<Ue> & {
-    [P in K]?: ApiResult<T> | null | undefined;
-  },
-  propertyKey: K,
-) => void;
+): ApiSendDecoratorHandle<T, DataProviderKeyHost<Ue>>;
 export function post<T, B, Ue = any, Uk = any, Ut = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
   configurationKey: DataProviderKey<APIConfiguration, Uk>,
   options: PostOptions<Ut>,
-): <K extends string>(
-  target: DataProviderKeyHost<Ue> &
-    DataProviderKeyHost<Uk> & {
-      [P in K]?: ApiResult<T> | null | undefined;
-    },
-  propertyKey: K,
-) => void;
+): ApiSendDecoratorHandle<
+  T,
+  DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>
+>;
 export function post<T, B, Ue = any, Uk = any, Ut = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
@@ -941,58 +1132,39 @@ export function post<T, B, Ue = any, Uk = any, Ut = any>(
     | DataProviderKey<APIConfiguration, Uk>
     | PostOptions<Ut>,
   maybeOptions?: PostOptions<Ut>,
-): <K extends string>(
-  target: object & { [P in K]?: ApiResult<T> | null | undefined },
-  propertyKey: K,
-) => void {
+): ApiSendDecoratorHandle<T, object> {
   return createApiSendDecorator<T, B, Ue, Uk, Ut>("POST", (api, path, body) =>
     api.postDetailed<T, B>(path, body as B),
   )(endpoint, bodyKey, configurationKeyOrOptions, maybeOptions);
 }
 
-/** `@put` — même modèle que `@post` via `API.putDetailed`. */
+/** `@put` — même modèle que `@post`, via `API.putDetailed` et `send()`. */
 export function put<T, B, Ue = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
-): <K extends string>(
-  target: DataProviderKeyHost<Ue> & {
-    [P in K]?: ApiResult<T> | null | undefined;
-  },
-  propertyKey: K,
-) => void;
+): ApiSendDecoratorHandle<T, DataProviderKeyHost<Ue>>;
 export function put<T, B, Ue = any, Uk = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
   configurationKey: DataProviderKey<APIConfiguration, Uk>,
-): <K extends string>(
-  target: DataProviderKeyHost<Ue> &
-    DataProviderKeyHost<Uk> & {
-      [P in K]?: ApiResult<T> | null | undefined;
-    },
-  propertyKey: K,
-) => void;
+): ApiSendDecoratorHandle<
+  T,
+  DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>
+>;
 export function put<T, B, Ue = any, Uk = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
   options: PutOptions<Uk>,
-): <K extends string>(
-  target: DataProviderKeyHost<Ue> & {
-    [P in K]?: ApiResult<T> | null | undefined;
-  },
-  propertyKey: K,
-) => void;
+): ApiSendDecoratorHandle<T, DataProviderKeyHost<Ue>>;
 export function put<T, B, Ue = any, Uk = any, Ut = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
   configurationKey: DataProviderKey<APIConfiguration, Uk>,
   options: PutOptions<Ut>,
-): <K extends string>(
-  target: DataProviderKeyHost<Ue> &
-    DataProviderKeyHost<Uk> & {
-      [P in K]?: ApiResult<T> | null | undefined;
-    },
-  propertyKey: K,
-) => void;
+): ApiSendDecoratorHandle<
+  T,
+  DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>
+>;
 export function put<T, B, Ue = any, Uk = any, Ut = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
@@ -1000,58 +1172,39 @@ export function put<T, B, Ue = any, Uk = any, Ut = any>(
     | DataProviderKey<APIConfiguration, Uk>
     | PutOptions<Ut>,
   maybeOptions?: PutOptions<Ut>,
-): <K extends string>(
-  target: object & { [P in K]?: ApiResult<T> | null | undefined },
-  propertyKey: K,
-) => void {
+): ApiSendDecoratorHandle<T, object> {
   return createApiSendDecorator<T, B, Ue, Uk, Ut>("PUT", (api, path, body) =>
     api.putDetailed<T, B>(path, body as B),
   )(endpoint, bodyKey, configurationKeyOrOptions, maybeOptions);
 }
 
-/** `@patch` — même modèle que `@post` via `API.patchDetailed`. */
+/** `@patch` — même modèle que `@post`, via `API.patchDetailed` et `send()`. */
 export function patch<T, B, Ue = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
-): <K extends string>(
-  target: DataProviderKeyHost<Ue> & {
-    [P in K]?: ApiResult<T> | null | undefined;
-  },
-  propertyKey: K,
-) => void;
+): ApiSendDecoratorHandle<T, DataProviderKeyHost<Ue>>;
 export function patch<T, B, Ue = any, Uk = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
   configurationKey: DataProviderKey<APIConfiguration, Uk>,
-): <K extends string>(
-  target: DataProviderKeyHost<Ue> &
-    DataProviderKeyHost<Uk> & {
-      [P in K]?: ApiResult<T> | null | undefined;
-    },
-  propertyKey: K,
-) => void;
+): ApiSendDecoratorHandle<
+  T,
+  DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>
+>;
 export function patch<T, B, Ue = any, Uk = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
   options: PatchOptions<Uk>,
-): <K extends string>(
-  target: DataProviderKeyHost<Ue> & {
-    [P in K]?: ApiResult<T> | null | undefined;
-  },
-  propertyKey: K,
-) => void;
+): ApiSendDecoratorHandle<T, DataProviderKeyHost<Ue>>;
 export function patch<T, B, Ue = any, Uk = any, Ut = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
   configurationKey: DataProviderKey<APIConfiguration, Uk>,
   options: PatchOptions<Ut>,
-): <K extends string>(
-  target: DataProviderKeyHost<Ue> &
-    DataProviderKeyHost<Uk> & {
-      [P in K]?: ApiResult<T> | null | undefined;
-    },
-  propertyKey: K,
-) => void;
+): ApiSendDecoratorHandle<
+  T,
+  DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>
+>;
 export function patch<T, B, Ue = any, Uk = any, Ut = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
@@ -1059,10 +1212,7 @@ export function patch<T, B, Ue = any, Uk = any, Ut = any>(
     | DataProviderKey<APIConfiguration, Uk>
     | PatchOptions<Ut>,
   maybeOptions?: PatchOptions<Ut>,
-): <K extends string>(
-  target: object & { [P in K]?: ApiResult<T> | null | undefined },
-  propertyKey: K,
-) => void {
+): ApiSendDecoratorHandle<T, object> {
   return createApiSendDecorator<T, B, Ue, Uk, Ut>("PATCH", (api, path, body) =>
     api.patchDetailed<T, B>(path, body as B),
   )(endpoint, bodyKey, configurationKeyOrOptions, maybeOptions);