@supersoniks/concorde 4.9.92 → 4.9.94

package/src/core/decorators/api.ts

@@ -228,36 +228,72 @@ class ApiOperationController {
   }
 }
 
-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.
-     *
+type ApiHandlerMethod<T> = (this: object, payload?: ApiResult<T>) => void;
+
+export interface GetDecoratorHandle<T, Host extends object = object> {
+  (
+    target: object,
+    propertyKey: string | symbol,
+    descriptor: TypedPropertyDescriptor<ApiHandlerMethod<T>>,
+  ): void;
+  <K extends string>(
+    target: Host & {
+      [P in K]?: ApiResult<T> | null | undefined;
+    },
+    propertyKey: K,
+  ): void;
+  /**
+   * 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>;
-  };
+   * 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.
-     *
+type ApiResultHandler<T> = (
+  component: object,
+  payload: ApiResult<T> | undefined,
+) => void;
+
+type GetDecoratorHandleInternals<
+  T,
+  Host extends object = object,
+> = GetDecoratorHandle<T, Host> & {
+  registerResultHandler(target: object, handler: ApiResultHandler<T>): void;
+};
+
+type ApiSendDecoratorHandleInternals<
+  T,
+  Host extends object = object,
+> = ApiSendDecoratorHandle<T, Host> & {
+  registerResultHandler(target: object, handler: ApiResultHandler<T>): void;
+};
+
+let nextApiHandlerPropertyId = 0;
+
+export interface ApiSendDecoratorHandle<T, Host extends object = object> {
+  (
+    target: object,
+    propertyKey: string | symbol,
+    descriptor: TypedPropertyDescriptor<ApiHandlerMethod<T>>,
+  ): void;
+  <K extends string>(
+    target: Host & {
+      [P in K]?: ApiResult<T> | null | undefined;
+    },
+    propertyKey: K,
+  ): void;
+  /**
+   * 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>;
-  };
+   * La Promise est résolue après la fin de l'opération.
+   */
+  send(component: Host): Promise<ApiResult<T> | undefined>;
+}
 
 export type ApiMethodActionOptions = {
   /**
@@ -352,7 +388,7 @@ function detachConfigPublisher(state: ApiGetState): void {
 
 /**
  * Décorateur **`@get`** : charge des données via `API.getDetailed` et assigne un
- * `ApiResult<T>` (`request`, `response`, `result` typé `T`) ou `null`.
+ * `ApiResult<T>` (`request`, `response`, `result` typé `T`) ou `undefined`.
  * Le path est un `Endpoint<T, Ue>` ; les placeholders `${nomPropriété}` sont résolus sur l'instance (`Ue` contraint l’hôte).
  *
  * **Scoped (défaut)** : `HTML.getApiConfiguration(host)` avec `host` = l’élément connecté
@@ -374,6 +410,9 @@ function detachConfigPublisher(state: ApiGetState): void {
  * @get(new Endpoint<User, { userId: string }>("users/${userId}"))
  * payload?: ApiResult<User>;
  *
+ * @get(new Endpoint<User[]>("users"))
+ * onUsers(payload?: ApiResult<User[]>) {}
+ *
  * @example
  * const apiConf = new DataProviderKey<APIConfiguration>("myApiConf");
  * PublisherManager.get("myApiConf").set({ serviceURL: "...", token: null, ... });
@@ -400,10 +439,7 @@ export function get<T, Ue = any>(
 export function get<T, Ue = any, Uk = any>(
   endpoint: Endpoint<T, Ue>,
   configurationKey: DataProviderKey<APIConfiguration, Uk>,
-): GetDecoratorHandle<
-  T,
-  DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>
->;
+): GetDecoratorHandle<T, DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>>;
 export function get<T, Ue = any, Uk = any>(
   endpoint: Endpoint<T, Ue>,
   options: GetOptions,
@@ -412,15 +448,11 @@ export function get<T, Ue = any, Uk = any, Ut = any>(
   endpoint: Endpoint<T, Ue>,
   configurationKey: DataProviderKey<APIConfiguration, Uk>,
   options: GetOptions,
-): GetDecoratorHandle<
-  T,
-  DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>
->;
+): 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,
+    DataProviderKey<APIConfiguration, Uk> | GetOptions,
   maybeOptions?: GetOptions,
 ): GetDecoratorHandle<T, object> {
   const pathTemplate = endpoint.path;
@@ -453,9 +485,33 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
   const usesPublisherConfig = Boolean(configurationKeyPath);
   const refetchEveryMs = options?.refetchEveryMs ?? 0;
   const operationController = new ApiOperationController();
-
-  const decorator = function (target: object, propertyKey: string) {
+  const resultHandlers = new WeakMap<object, Set<ApiResultHandler<T>>>();
+  const decoratedTargets = new WeakSet<object>();
+  const operationPropertyKeys = new WeakMap<object, Set<string>>();
+  let handlerPropertyKey: string | undefined;
+
+  const decorator = function (
+    target: object,
+    propertyKey: string,
+    descriptor?: PropertyDescriptor,
+  ) {
+    if (descriptor) {
+      const handler = descriptor.value as ApiHandlerMethod<T> | undefined;
+      if (!handler) return;
+
+      (decorator as GetDecoratorHandleInternals<T>).registerResultHandler(
+        target,
+        (component, payload) => handler.call(component, payload),
+      );
+      return;
+    }
     if (!target) return;
+    if (decoratedTargets.has(target)) {
+      operationPropertyKeys.get(target)?.add(propertyKey);
+      return;
+    }
+    decoratedTargets.add(target);
+    operationPropertyKeys.set(target, new Set([propertyKey]));
     setSubscribable(target);
     const stateKey = `__get_state_${propertyKey}`;
 
@@ -495,12 +551,18 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
         }, state.refetchEveryMs);
       };
 
+      const assignPayload = (payload: ApiResult<T> | undefined) => {
+        operationPropertyKeys.get(target)?.forEach((key) => {
+          comp[key] = payload;
+        });
+      };
+
       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;
+          assignPayload(undefined);
           scheduleRefetch();
           return undefined;
         }
@@ -512,7 +574,7 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
             pathOptions,
           );
           if (!configRes.ready || !configRes.path) {
-            comp[propertyKey] = undefined;
+            assignPayload(undefined);
             scheduleRefetch();
             return undefined;
           }
@@ -540,8 +602,13 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
         const api = new API(config);
         const payload = await api.getDetailed<T>(resolution.path);
         if (generation !== state.requestGeneration) return payload;
-        comp[propertyKey] = payload;
+        operationPropertyKeys.get(target)?.forEach((key) => {
+          comp[key] = payload;
+        });
         scheduleRefetch();
+        resultHandlers
+          .get(target)
+          ?.forEach((handler) => handler(component, payload));
         return payload;
       };
 
@@ -582,12 +649,12 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
           pathOptions,
         );
         if (!configRes.ready || !configRes.path) {
-          comp[propertyKey] = undefined;
+          assignPayload(undefined);
           return;
         }
         const publisher = getPublisherFromPath(configRes.path);
         if (!publisher) {
-          comp[propertyKey] = undefined;
+          assignPayload(undefined);
           return;
         }
         const mutationHandler = scheduleFetchAndIgnoreErrors;
@@ -651,9 +718,11 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
       state.cleanupWatchers.forEach((cleanup) => cleanup());
       state.cleanupWatchers = [];
       state.requestGeneration++;
-      comp[propertyKey] = undefined;
+      operationPropertyKeys.get(target)?.forEach((key) => {
+        comp[key] = undefined;
+      });
     });
-  } as GetDecoratorHandle<T, object>;
+  } as GetDecoratorHandleInternals<T>;
 
   decorator.refetch = (component: object) => {
     return operationController.run(component) as Promise<
@@ -661,6 +730,20 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
     >;
   };
 
+  decorator.registerResultHandler = (target, handler) => {
+    let handlers = resultHandlers.get(target);
+    if (!handlers) {
+      handlers = new Set();
+      resultHandlers.set(target, handlers);
+    }
+    handlers.add(handler);
+
+    if (!decoratedTargets.has(target)) {
+      handlerPropertyKey ??= `__get_handler_${nextApiHandlerPropertyId++}`;
+      decorator(target, handlerPropertyKey);
+    }
+  };
+
   return decorator;
 }
 
@@ -754,22 +837,21 @@ function readBodyFromPublisher(publisher: DataProvider | null): unknown {
 
 type ApiSendMethod = "POST" | "PUT" | "PATCH";
 
-type ApiSendDetailedCaller = (
+type ApiSendDetailedCaller<T> = (
   api: API,
   path: string,
   body: unknown,
-) => Promise<ApiResult<unknown> | undefined>;
+) => Promise<ApiResult<T> | undefined>;
 
 function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
   method: ApiSendMethod,
-  callDetailed: ApiSendDetailedCaller,
+  callDetailed: ApiSendDetailedCaller<T>,
 ) {
   return function (
     endpoint: Endpoint<T, Ue>,
     bodyKey: DataProviderKey<B>,
     configurationKeyOrOptions?:
-      | DataProviderKey<APIConfiguration, Uk>
-      | ApiSendOptions<Ut>,
+      DataProviderKey<APIConfiguration, Uk> | ApiSendOptions<Ut>,
     maybeOptions?: ApiSendOptions<Ut>,
   ): ApiSendDecoratorHandle<T, object> {
     const pathTemplate = endpoint.path;
@@ -809,9 +891,33 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
     };
     const stateKeyPrefix = `__${method.toLowerCase()}_state_`;
     const operationController = new ApiOperationController();
-
-    const decorator = function (target: object, propertyKey: string) {
+    const resultHandlers = new WeakMap<object, Set<ApiResultHandler<T>>>();
+    const decoratedTargets = new WeakSet<object>();
+    const operationPropertyKeys = new WeakMap<object, Set<string>>();
+    let handlerPropertyKey: string | undefined;
+
+    const decorator = function (
+      target: object,
+      propertyKey: string,
+      descriptor?: PropertyDescriptor,
+    ) {
+      if (descriptor) {
+        const handler = descriptor.value as ApiHandlerMethod<T> | undefined;
+        if (!handler) return;
+
+        (decorator as ApiSendDecoratorHandleInternals<T>).registerResultHandler(
+          target,
+          (component, payload) => handler.call(component, payload),
+        );
+        return;
+      }
       if (!target) return;
+      if (decoratedTargets.has(target)) {
+        operationPropertyKeys.get(target)?.add(propertyKey);
+        return;
+      }
+      decoratedTargets.add(target);
+      operationPropertyKeys.set(target, new Set([propertyKey]));
       setSubscribable(target);
       const stateKey = `${stateKeyPrefix}${propertyKey}`;
 
@@ -857,12 +963,18 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
           }, state.refetchEveryMs);
         };
 
-        const runSend = async (): Promise<ApiResult<unknown> | undefined> => {
+        const assignPayload = (payload: ApiResult<T> | undefined) => {
+          operationPropertyKeys.get(target)?.forEach((key) => {
+            comp[key] = payload;
+          });
+        };
+
+        const runSend = async (): Promise<ApiResult<T> | undefined> => {
           const resolution = isDynamicPath
             ? resolveDynamicPath(component, pathTemplate, pathOptions)
             : { ready: true, path: pathTemplate };
           if (!resolution.ready || !resolution.path) {
-            comp[propertyKey] = undefined;
+            assignPayload(undefined);
             scheduleRefetch();
             return undefined;
           }
@@ -873,7 +985,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
             pathOptions,
           );
           if (!bodyResolution.ready || !bodyResolution.path) {
-            comp[propertyKey] = undefined;
+            assignPayload(undefined);
             scheduleRefetch();
             return undefined;
           }
@@ -896,7 +1008,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
               pathOptions,
             );
             if (!configRes.ready || !configRes.path) {
-              comp[propertyKey] = undefined;
+              assignPayload(undefined);
               scheduleRefetch();
               return undefined;
             }
@@ -924,10 +1036,23 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
 
           const generation = ++state.requestGeneration;
           const api = new API(config);
-          const payload = await callDetailed(api, resolution.path, body);
+          let payload: ApiResult<T> | undefined;
+          try {
+            payload = await callDetailed(api, resolution.path, body);
+          } catch (error) {
+            if (generation === state.requestGeneration) {
+              resultHandlers
+                .get(target)
+                ?.forEach((handler) => handler(component, undefined));
+            }
+            throw error;
+          }
           if (generation !== state.requestGeneration) return payload;
-          comp[propertyKey] = payload;
+          assignPayload(payload);
           scheduleRefetch();
+          resultHandlers
+            .get(target)
+            ?.forEach((handler) => handler(component, payload));
           return payload;
         };
 
@@ -989,12 +1114,12 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
             pathOptions,
           );
           if (!configRes.ready || !configRes.path) {
-            comp[propertyKey] = undefined;
+            assignPayload(undefined);
             return;
           }
           const publisher = getPublisherFromPath(configRes.path);
           if (!publisher) {
-            comp[propertyKey] = undefined;
+            assignPayload(undefined);
             return;
           }
           const mutationHandler = scheduleSendAndIgnoreErrors;
@@ -1067,9 +1192,11 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
         state.cleanupWatchers.forEach((cleanup) => cleanup());
         state.cleanupWatchers = [];
         state.requestGeneration++;
-        comp[propertyKey] = undefined;
+        operationPropertyKeys.get(target)?.forEach((key) => {
+          comp[key] = undefined;
+        });
       });
-    } as ApiSendDecoratorHandle<T, object>;
+    } as ApiSendDecoratorHandleInternals<T>;
 
     decorator.send = (component: object) => {
       return operationController.run(component) as Promise<
@@ -1077,6 +1204,20 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
       >;
     };
 
+    decorator.registerResultHandler = (target, handler) => {
+      let handlers = resultHandlers.get(target);
+      if (!handlers) {
+        handlers = new Set();
+        resultHandlers.set(target, handlers);
+      }
+      handlers.add(handler);
+
+      if (!decoratedTargets.has(target)) {
+        handlerPropertyKey ??= `__${method.toLowerCase()}_handler_${nextApiHandlerPropertyId++}`;
+        decorator(target, handlerPropertyKey);
+      }
+    };
+
     return decorator;
   };
 }
@@ -1107,10 +1248,7 @@ export function post<T, B, Ue = any, Uk = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
   configurationKey: DataProviderKey<APIConfiguration, Uk>,
-): ApiSendDecoratorHandle<
-  T,
-  DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>
->;
+): ApiSendDecoratorHandle<T, DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>>;
 export function post<T, B, Ue = any, Uk = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
@@ -1121,16 +1259,12 @@ export function post<T, B, Ue = any, Uk = any, Ut = any>(
   bodyKey: DataProviderKey<B>,
   configurationKey: DataProviderKey<APIConfiguration, Uk>,
   options: PostOptions<Ut>,
-): ApiSendDecoratorHandle<
-  T,
-  DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>
->;
+): ApiSendDecoratorHandle<T, DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>>;
 export function post<T, B, Ue = any, Uk = any, Ut = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
   configurationKeyOrOptions?:
-    | DataProviderKey<APIConfiguration, Uk>
-    | PostOptions<Ut>,
+    DataProviderKey<APIConfiguration, Uk> | PostOptions<Ut>,
   maybeOptions?: PostOptions<Ut>,
 ): ApiSendDecoratorHandle<T, object> {
   return createApiSendDecorator<T, B, Ue, Uk, Ut>("POST", (api, path, body) =>
@@ -1147,10 +1281,7 @@ export function put<T, B, Ue = any, Uk = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
   configurationKey: DataProviderKey<APIConfiguration, Uk>,
-): ApiSendDecoratorHandle<
-  T,
-  DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>
->;
+): ApiSendDecoratorHandle<T, DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>>;
 export function put<T, B, Ue = any, Uk = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
@@ -1161,16 +1292,12 @@ export function put<T, B, Ue = any, Uk = any, Ut = any>(
   bodyKey: DataProviderKey<B>,
   configurationKey: DataProviderKey<APIConfiguration, Uk>,
   options: PutOptions<Ut>,
-): ApiSendDecoratorHandle<
-  T,
-  DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>
->;
+): ApiSendDecoratorHandle<T, DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>>;
 export function put<T, B, Ue = any, Uk = any, Ut = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
   configurationKeyOrOptions?:
-    | DataProviderKey<APIConfiguration, Uk>
-    | PutOptions<Ut>,
+    DataProviderKey<APIConfiguration, Uk> | PutOptions<Ut>,
   maybeOptions?: PutOptions<Ut>,
 ): ApiSendDecoratorHandle<T, object> {
   return createApiSendDecorator<T, B, Ue, Uk, Ut>("PUT", (api, path, body) =>
@@ -1187,10 +1314,7 @@ export function patch<T, B, Ue = any, Uk = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
   configurationKey: DataProviderKey<APIConfiguration, Uk>,
-): ApiSendDecoratorHandle<
-  T,
-  DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>
->;
+): ApiSendDecoratorHandle<T, DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>>;
 export function patch<T, B, Ue = any, Uk = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
@@ -1201,16 +1325,12 @@ export function patch<T, B, Ue = any, Uk = any, Ut = any>(
   bodyKey: DataProviderKey<B>,
   configurationKey: DataProviderKey<APIConfiguration, Uk>,
   options: PatchOptions<Ut>,
-): ApiSendDecoratorHandle<
-  T,
-  DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>
->;
+): ApiSendDecoratorHandle<T, DataProviderKeyHost<Ue> & DataProviderKeyHost<Uk>>;
 export function patch<T, B, Ue = any, Uk = any, Ut = any>(
   endpoint: Endpoint<T, Ue>,
   bodyKey: DataProviderKey<B>,
   configurationKeyOrOptions?:
-    | DataProviderKey<APIConfiguration, Uk>
-    | PatchOptions<Ut>,
+    DataProviderKey<APIConfiguration, Uk> | PatchOptions<Ut>,
   maybeOptions?: PatchOptions<Ut>,
 ): ApiSendDecoratorHandle<T, object> {
   return createApiSendDecorator<T, B, Ue, Uk, Ut>("PATCH", (api, path, body) =>

package/src/core/decorators/subscriber/derive.ts

@@ -0,0 +1,95 @@
+import type {
+  DataProviderKey,
+  DataProviderKeyHost,
+} from "../../utils/dataProviderKey";
+import {
+  derive as deriveFn,
+  type DeriveHandle,
+} from "../../utils/derive";
+
+export type DeriveDecoratorOptions<
+  I extends Record<string, unknown>,
+  O,
+  V = Record<string, unknown>,
+> = {
+  from: { [K in keyof I]: DataProviderKey<I[K]> };
+  to: DataProviderKey<O>;
+  /** Expression JSONata (string) ou fonction TS. */
+  expr?: string;
+  fn?: (inputs: I, vars: V) => O | Promise<O>;
+  variables?: DataProviderKey<V>;
+};
+
+const HANDLES = new WeakMap<object, DeriveHandle[]>();
+
+/**
+ * Décorateur optionnel aligné `@handle` : lance un `derive` au `connectedCallback`
+ * et l’arrête au `disconnectedCallback`.
+ *
+ * @example
+ * ```ts
+ * @derive({
+ *   from: { s: sessionsKey },
+ *   to: palmaresKey,
+ *   variables: formKey,
+ *   fn: (i, v) => i.s.slice(0, Number(v.top) || 5),
+ * })
+ * class MyWidget extends LitElement {}
+ * ```
+ */
+export function deriveDecorator<
+  I extends Record<string, unknown>,
+  O,
+  V = Record<string, unknown>,
+>(options: DeriveDecoratorOptions<I, O, V>) {
+  return function <T extends DataProviderKeyHost<object>>(
+    ctor: new (...args: any[]) => T,
+  ): void {
+    const proto = ctor.prototype as T & {
+      connectedCallback?: () => void;
+      disconnectedCallback?: () => void;
+    };
+    const connected = proto.connectedCallback;
+    const disconnected = proto.disconnectedCallback;
+
+    proto.connectedCallback = function (this: T) {
+      connected?.call(this);
+      const compute =
+        options.fn ??
+        (async (inputs: I, vars: V) => {
+          if (!options.expr) {
+            throw new Error("@derive : fournir `expr` ou `fn`.");
+          }
+          const { compileJsonata } = await import(
+            "../../utils/jsonataRuntime"
+          );
+          const expr = compileJsonata(options.expr);
+          return expr.evaluate({}, {
+            ...(vars as Record<string, unknown>),
+            ...inputs,
+          }) as O;
+        });
+      const handle = deriveFn({
+        inputs: options.from,
+        output: options.to,
+        variables: options.variables,
+        compute,
+      });
+      const list = HANDLES.get(this) ?? [];
+      list.push(handle);
+      HANDLES.set(this, list);
+    };
+
+    proto.disconnectedCallback = function (this: T) {
+      const list = HANDLES.get(this);
+      if (list) {
+        for (const h of list) h.stop();
+        HANDLES.delete(this);
+      }
+      disconnected?.call(this);
+    };
+  };
+}
+
+/** Alias public — éviter le conflit de nom avec la primitive `derive`. */
+export { deriveDecorator as derive };