@supersoniks/concorde 4.2.1 → 4.4.0

package/src/core/decorators/api.ts

@@ -0,0 +1,244 @@
+import type {
+  DataProviderKey,
+  DataProviderKeyHost,
+} from "../utils/dataProviderKey";
+import { Endpoint } from "../utils/endpoint";
+import HTML, {
+  SearchableDomElement,
+} from "@supersoniks/concorde/core/utils/HTML";
+import API, {
+  APIConfiguration,
+  type ApiGetResult,
+} from "@supersoniks/concorde/core/utils/api";
+import DataProvider from "../utils/PublisherProxy";
+import { ConnectedComponent, setSubscribable } from "./subscriber/common";
+import {
+  extractDynamicDependencies,
+  resolveDynamicPath,
+} from "./subscriber/dynamicPath";
+import {
+  getDynamicWatchKeys,
+  registerDynamicPropertyWatcher,
+} from "./subscriber/dynamicPropertyWatch";
+import { getPublisherFromPath } from "./subscriber/publisherPath";
+
+function asSearchableHost(component: unknown): SearchableDomElement | null {
+  if (component instanceof HTMLElement || component instanceof ShadowRoot) {
+    return component;
+  }
+  return null;
+}
+
+function readApiConfigurationFromPublisher(
+  publisher: DataProvider | null,
+): APIConfiguration | null {
+  if (!publisher || typeof publisher.get !== "function") return null;
+  const raw = publisher.get();
+  if (!raw || typeof raw !== "object") return null;
+  if (!("serviceURL" in (raw as object))) return null;
+  return raw as APIConfiguration;
+}
+
+function resolveScopedConfiguration(
+  component: unknown,
+): APIConfiguration | null {
+  const host = asSearchableHost(component);
+  if (!host) return null;
+  return HTML.getApiConfiguration(host);
+}
+
+type ApiGetState = {
+  cleanupWatchers: Array<() => void>;
+  requestGeneration: number;
+  configPublisher: DataProvider | null;
+  configMutationHandler: (() => void) | null;
+};
+
+function detachConfigPublisher(state: ApiGetState): void {
+  if (state.configPublisher && state.configMutationHandler) {
+    state.configPublisher.offInternalMutation(state.configMutationHandler);
+  }
+  state.configPublisher = null;
+  state.configMutationHandler = null;
+}
+
+/**
+ * Décorateur **`@get`** : charge des données via `API.getDetailed` et assigne un
+ * `ApiGetResult<T>` (`request`, `response`, `result` typé `T`) ou `null`.
+ * 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é
+ * (`HTMLElement` / `ShadowRoot`). Sans hôte DOM valide, la propriété reste inchangée jusqu’à connexion.
+ *
+ * **Deuxième paramètre** : `DataProviderKey<APIConfiguration>` — la config est lue via
+ * `PublisherManager` sur le chemin résolu (même syntaxe dynamique que `@subscribe`).
+ * Toute mutation interne du publisher (`onInternalMutation`) relance le GET.
+ *
+ * @example
+ * @get(new Endpoint<User, { userId: string }>("users/${userId}"))
+ * payload?: ApiGetResult<User>;
+ *
+ * @example
+ * const apiConf = new DataProviderKey<APIConfiguration>("myApiConf");
+ * PublisherManager.get("myApiConf").set({ serviceURL: "...", token: null, ... });
+ * @get(new Endpoint<Thing, { id: string }>("things/${id}"), apiConf)
+ * payload?: ApiGetResult<Thing>;
+ */
+export function get<T, Ue = any>(
+  endpoint: Endpoint<T, Ue>,
+): <K extends string>(
+  target: DataProviderKeyHost<Ue> & {
+    [P in K]?: ApiGetResult<T> | null | undefined;
+  },
+  propertyKey: K,
+) => void;
+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]?: ApiGetResult<T> | null | undefined;
+    },
+  propertyKey: K,
+) => void;
+export function get<T, Ue = any, Uk = any>(
+  endpoint: Endpoint<T, Ue>,
+  configurationKey?: DataProviderKey<APIConfiguration, Uk>,
+): <K extends string>(
+  target: object & { [P in K]?: ApiGetResult<T> | null | undefined },
+  propertyKey: K,
+) => void {
+  const pathTemplate = endpoint.path;
+  const configurationKeyPath = configurationKey?.path;
+  const endpointDynamicDependencies = extractDynamicDependencies(pathTemplate);
+  const configKeyDynamicDependencies = configurationKeyPath
+    ? extractDynamicDependencies(configurationKeyPath)
+    : [];
+  const mergedDynamicDependencies = [
+    ...new Set([
+      ...endpointDynamicDependencies,
+      ...configKeyDynamicDependencies,
+    ]),
+  ];
+  const isDynamicPath = endpointDynamicDependencies.length > 0;
+  const usesPublisherConfig = Boolean(configurationKeyPath);
+
+  return function (target: object, propertyKey: string) {
+    if (!target) return;
+    setSubscribable(target);
+    const stateKey = `__get_state_${propertyKey}`;
+
+    (target as ConnectedComponent).__onConnected__((component) => {
+      const comp = component as Record<string, unknown>;
+      let state = comp[stateKey] as ApiGetState | undefined;
+      if (!state) {
+        state = {
+          cleanupWatchers: [],
+          requestGeneration: 0,
+          configPublisher: null,
+          configMutationHandler: null,
+        };
+        comp[stateKey] = state;
+      }
+
+      state.cleanupWatchers.forEach((cleanup) => cleanup());
+      state.cleanupWatchers = [];
+      state.requestGeneration++;
+
+      const runFetch = () => {
+        const resolution = isDynamicPath
+          ? resolveDynamicPath(component, pathTemplate)
+          : { ready: true, path: pathTemplate };
+        if (!resolution.ready || !resolution.path) {
+          comp[propertyKey] = undefined;
+          return;
+        }
+        let config: APIConfiguration | null = null;
+        if (usesPublisherConfig && configurationKeyPath) {
+          const configRes = resolveDynamicPath(component, configurationKeyPath);
+          if (!configRes.ready || !configRes.path) {
+            comp[propertyKey] = undefined;
+            return;
+          }
+          const configPublisher = getPublisherFromPath(configRes.path);
+          config = readApiConfigurationFromPublisher(configPublisher);
+        } else {
+          config = resolveScopedConfiguration(component);
+        }
+        if (!config) {
+          comp[propertyKey] = undefined;
+          return;
+        }
+        const generation = ++state.requestGeneration;
+        const api = new API(config);
+        void api
+          .getDetailed<T>(resolution.path)
+          .then((payload?: ApiGetResult<T>) => {
+            if (generation !== state.requestGeneration) return;
+            comp[propertyKey] = payload;
+          });
+      };
+
+      const rebindPublisherConfig = () => {
+        if (!usesPublisherConfig || !configurationKeyPath) return;
+        detachConfigPublisher(state);
+        const configRes = resolveDynamicPath(component, configurationKeyPath);
+        if (!configRes.ready || !configRes.path) {
+          comp[propertyKey] = undefined;
+          return;
+        }
+        const publisher = getPublisherFromPath(configRes.path);
+        if (!publisher) {
+          comp[propertyKey] = undefined;
+          return;
+        }
+        const mutationHandler = () => {
+          runFetch();
+        };
+        publisher.onInternalMutation(mutationHandler);
+        state.configPublisher = publisher;
+        state.configMutationHandler = mutationHandler;
+      };
+
+      if (usesPublisherConfig) {
+        for (const dependency of mergedDynamicDependencies) {
+          const unsubscribe = registerDynamicPropertyWatcher(
+            getDynamicWatchKeys.watcherStore,
+            getDynamicWatchKeys.hooked,
+            component,
+            dependency,
+            () => rebindPublisherConfig(),
+          );
+          state.cleanupWatchers.push(unsubscribe);
+        }
+        rebindPublisherConfig();
+      } else {
+        if (isDynamicPath) {
+          for (const dependency of endpointDynamicDependencies) {
+            const unsubscribe = registerDynamicPropertyWatcher(
+              getDynamicWatchKeys.watcherStore,
+              getDynamicWatchKeys.hooked,
+              component,
+              dependency,
+              () => runFetch(),
+            );
+            state.cleanupWatchers.push(unsubscribe);
+          }
+        }
+        runFetch();
+      }
+    });
+
+    (target as ConnectedComponent).__onDisconnected__((component) => {
+      const comp = component as Record<string, unknown>;
+      const state = comp[stateKey] as ApiGetState | undefined;
+      if (!state) return;
+      detachConfigPublisher(state);
+      state.cleanupWatchers.forEach((cleanup) => cleanup());
+      state.cleanupWatchers = [];
+      state.requestGeneration++;
+      comp[propertyKey] = undefined;
+    });
+  };
+}

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

@@ -1,147 +1,23 @@
-import { Objects } from "@supersoniks/concorde/utils";
-
-import DataProvider, { PublisherManager } from "../../utils/PublisherProxy";
+import type {
+  DataProviderKey,
+  DataProviderKeyHost,
+} from "../../utils/dataProviderKey";
 import { ConnectedComponent, setSubscribable } from "./common";
-
-const dynamicWatcherStore = Symbol("__bindDynamicWatcherStore__");
-const dynamicWillUpdateHookedStore = Symbol("__bindDynamicWillUpdateHooked__");
-
-function registerDynamicWatcher(
-  instance: any,
-  propertyName: string,
-  onChange: () => void
-) {
-  const key = String(propertyName);
-  ensureWillUpdateHook(instance);
-  if (!instance[dynamicWatcherStore]) {
-    Object.defineProperty(instance, dynamicWatcherStore, {
-      value: new Map<string, Set<() => void>>(),
-      enumerable: false,
-      configurable: false,
-      writable: false,
-    });
-  }
-  const watcherMap = instance[dynamicWatcherStore] as Map<
-    string,
-    Set<() => void>
-  >;
-  if (!watcherMap.has(key)) {
-    watcherMap.set(key, new Set());
-  }
-  const watchers = watcherMap.get(key)!;
-  watchers.add(onChange);
-  return () => {
-    watchers.delete(onChange);
-    if (watchers.size === 0) {
-      watcherMap.delete(key);
-    }
-  };
-}
-
-function ensureWillUpdateHook(instance: any) {
-  const proto = Object.getPrototypeOf(instance);
-  if (!proto || proto[dynamicWillUpdateHookedStore]) return;
-  const originalWillUpdate = Object.prototype.hasOwnProperty.call(
-    proto,
-    "willUpdate"
-  )
-    ? proto.willUpdate
-    : Object.getPrototypeOf(proto)?.willUpdate;
-  proto.willUpdate = function (changedProperties?: Map<unknown, unknown>) {
-    const handlers = this[dynamicWatcherStore] as
-      | Map<string, Set<() => void>>
-      | undefined;
-    if (handlers && handlers.size > 0) {
-      if (changedProperties && changedProperties.size > 0) {
-        changedProperties.forEach((_value, dependency) => {
-          const callbacks = handlers.get(String(dependency));
-          if (callbacks) {
-            callbacks.forEach((cb) => cb());
-          }
-        });
-      } else {
-        handlers.forEach((callbacks) => callbacks.forEach((cb) => cb()));
-      }
-    }
-    originalWillUpdate?.call(this, changedProperties);
-  };
-  proto[dynamicWillUpdateHookedStore] = true;
-}
-
-function extractDynamicDependencies(path: string) {
-  const patterns = [/\$\{([^}]+)\}/g, /\{\$([^}]+)\}/g];
-  const deps = new Set<string>();
-  for (const pattern of patterns) {
-    let match;
-    while ((match = pattern.exec(path)) !== null) {
-      const cleaned = cleanPlaceholder(match[1]);
-      if (!cleaned) continue;
-      const [root] = cleaned.split(".");
-      if (root) deps.add(root);
-    }
-  }
-  return Array.from(deps);
-}
-
-function cleanPlaceholder(value: string) {
-  return value.trim().replace(/^this\./, "");
-}
-
-function resolveDynamicPath(component: any, template: string) {
-  let missing = false;
-  const replaceValue = (_match: string, expression: string) => {
-    const cleaned = cleanPlaceholder(expression);
-    const resolved = getValueFromExpression(component, cleaned);
-    if (resolved === undefined || resolved === null) {
-      missing = true;
-      return "";
-    }
-    return `${resolved}`;
-  };
-  const resolvedPath = template
-    .replace(/\$\{([^}]+)\}/g, replaceValue)
-    .replace(/\{\$([^}]+)\}/g, replaceValue)
-    .trim();
-  if (missing || !resolvedPath.length) {
-    return { ready: false, path: null };
-  }
-  const segments = resolvedPath.split(".").filter(Boolean);
-  if (segments.length === 0 || !segments[0]) {
-    return { ready: false, path: null };
-  }
-  return { ready: true, path: resolvedPath };
-}
-
-function getValueFromExpression(component: any, expression: string) {
-  if (!expression) return undefined;
-  const segments = expression.split(".").filter(Boolean);
-  if (segments.length === 0) return undefined;
-  let current: unknown = component;
-  for (const segment of segments) {
-    if (
-      current === undefined ||
-      current === null ||
-      typeof current !== "object"
-    ) {
-      return undefined;
-    }
-    current = (current as Record<string, unknown>)[segment];
-  }
-  return current;
-}
-
-function getPublisherFromPath(path: string) {
-  const segments = path.split(".").filter((segment) => segment.length > 0);
-  if (segments.length === 0) return null;
-  const dataProvider = segments.shift() || "";
-  if (!dataProvider) return null;
-  let publisher = PublisherManager.get(dataProvider);
-  if (!publisher) return null;
-  publisher = Objects.traverse(publisher, segments);
-  return publisher as DataProvider | null;
-}
-
-export function bind(path: string, options?: { reflect?: boolean }) {
+import {
+  extractDynamicDependencies,
+  hasPath,
+  resolveDynamicPath,
+} from "./dynamicPath";
+import {
+  bindDynamicWatchKeys,
+  registerDynamicPropertyWatcher,
+} from "./dynamicPropertyWatch";
+import { getPublisherFromPath } from "./publisherPath";
+
+function bindImpl(
+  path: string,
+  options?: { reflect?: boolean }
+): (target: unknown, propertyKey: string) => void {
   const reflect = options?.reflect ?? false;
   const dynamicDependencies = extractDynamicDependencies(path);
   const isDynamicPath = dynamicDependencies.length > 0;
@@ -276,8 +152,10 @@ export function bind(path: string, options?: { reflect?: boolean }) {
 
       if (isDynamicPath) {
         for (const dependency of dynamicDependencies) {
-          const unsubscribe = registerDynamicWatcher(
-            component as Record<string, unknown>,
+          const unsubscribe = registerDynamicPropertyWatcher(
+            bindDynamicWatchKeys.watcherStore,
+            bindDynamicWatchKeys.hooked,
+            component,
             dependency,
             () => refreshSubscription()
           );
@@ -303,3 +181,37 @@ export function bind(path: string, options?: { reflect?: boolean }) {
   };
 }
 
+/**
+ * Bidirectional binding to a publisher path. Subscribes to changes and optionally reflects writes back.
+ * Accepts either a string path (legacy) or DataProviderKey&lt;T&gt; for type-safe binding.
+ * Supports dynamic paths: use placeholders like "users.${userIndex}" in the path or DataProviderKey.
+ *
+ * @example
+ * // String path (legacy):
+ * @bind("demoData.firstName")
+ * @state()
+ * firstName = "";
+ *
+ * @example
+ * // DataProviderKey with type validation:
+ * const dataKey = new DataProviderKey<Data>("data");
+ * @bind(dataKey.count, { reflect: true })
+ * @state()
+ * count: number = 0;
+ */
+export function bind(path: string, options?: { reflect?: boolean }): (target: unknown, propertyKey: string) => void;
+export function bind<T, U = any>(
+  key: DataProviderKey<T, U>,
+  options?: { reflect?: boolean },
+): <K extends string>(
+  target: DataProviderKeyHost<U> & { [P in K]?: T | null | undefined },
+  propertyKey: K,
+) => void;
+export function bind(
+  pathOrKey: string | DataProviderKey<unknown, unknown>,
+  options?: { reflect?: boolean },
+): (target: unknown, propertyKey: string) => void {
+  const path = hasPath(pathOrKey) ? pathOrKey.path : pathOrKey;
+  return bindImpl(path, options);
+}
+

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

@@ -0,0 +1,77 @@
+/** Lit / décorateurs : chemins publisher avec `${prop}` ou `{$prop}`. */
+
+export function cleanPlaceholder(value: string): string {
+  return value.trim().replace(/^this\./, "");
+}
+
+export function getValueFromExpression(
+  component: unknown,
+  expression: string,
+): unknown {
+  if (!expression) return undefined;
+  const segments = expression.split(".").filter(Boolean);
+  if (segments.length === 0) return undefined;
+  let current: unknown = component;
+  for (const segment of segments) {
+    if (
+      current === undefined ||
+      current === null ||
+      typeof current !== "object"
+    ) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+export function resolveDynamicPath(
+  component: unknown,
+  template: string,
+): { ready: boolean; path: string | null } {
+  let missing = false;
+  const replaceValue = (_match: string, expression: string) => {
+    const cleaned = cleanPlaceholder(expression);
+    const resolved = getValueFromExpression(component, cleaned);
+    if (resolved === undefined || resolved === null) {
+      missing = true;
+      return "";
+    }
+    return `${resolved}`;
+  };
+  const resolvedPath = template
+    .replace(/\$\{([^}]+)\}/g, replaceValue)
+    .replace(/\{\$([^}]+)\}/g, replaceValue)
+    .trim();
+  if (missing || !resolvedPath.length) {
+    return { ready: false, path: null };
+  }
+  const segments = resolvedPath.split(".").filter(Boolean);
+  if (segments.length === 0 || !segments[0]) {
+    return { ready: false, path: null };
+  }
+  return { ready: true, path: resolvedPath };
+}
+
+export function extractDynamicDependencies(path: string): string[] {
+  const patterns = [/\$\{([^}]+)\}/g, /\{\$([^}]+)\}/g];
+  const deps = new Set<string>();
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(path)) !== null) {
+      const cleaned = (match[1] || "").trim().replace(/^this\./, "");
+      if (!cleaned) continue;
+      const [root] = cleaned.split(".");
+      if (root) deps.add(root);
+    }
+  }
+  return Array.from(deps);
+}
+export function hasPath(obj: unknown): obj is { path: string } {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    "path" in obj &&
+    typeof (obj as { path: unknown }).path === "string"
+  );
+}

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

@@ -0,0 +1,105 @@
+/**
+ * Enregistre des callbacks sur des propriétés Lit (via `willUpdate`) pour
+ * réagir aux changements de segments dynamiques `${…}` dans les chemins.
+ * Chaque décorateur utilise des clés de stockage distinctes pour éviter les collisions.
+ */
+
+type InstanceStores = Record<PropertyKey, unknown>;
+
+export function registerDynamicPropertyWatcher(
+  watcherStoreKey: PropertyKey,
+  hookedStoreKey: PropertyKey,
+  instance: object,
+  propertyName: string,
+  onChange: () => void,
+): () => void {
+  const inst = instance as InstanceStores;
+  const key = String(propertyName);
+  ensureDynamicPropertiesWillUpdate(
+    watcherStoreKey,
+    hookedStoreKey,
+    instance,
+  );
+  if (!inst[watcherStoreKey]) {
+    Object.defineProperty(inst, watcherStoreKey, {
+      value: new Map<string, Set<() => void>>(),
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    });
+  }
+  const watcherMap = inst[watcherStoreKey] as Map<string, Set<() => void>>;
+  if (!watcherMap.has(key)) {
+    watcherMap.set(key, new Set());
+  }
+  const watchers = watcherMap.get(key)!;
+  watchers.add(onChange);
+  return () => {
+    watchers.delete(onChange);
+    if (watchers.size === 0) {
+      watcherMap.delete(key);
+    }
+  };
+}
+
+export function ensureDynamicPropertiesWillUpdate(
+  watcherStoreKey: PropertyKey,
+  hookedStoreKey: PropertyKey,
+  instance: object,
+): void {
+  const proto = Object.getPrototypeOf(instance);
+  if (!proto || (proto as InstanceStores)[hookedStoreKey]) return;
+  const originalWillUpdate = Object.prototype.hasOwnProperty.call(
+    proto,
+    "willUpdate",
+  )
+    ? (proto as InstanceStores).willUpdate
+    : (Object.getPrototypeOf(proto) as InstanceStores)?.willUpdate;
+  (proto as InstanceStores).willUpdate = function (
+    changedProperties?: Map<unknown, unknown>,
+  ) {
+    const handlers = (this as InstanceStores)[watcherStoreKey] as
+      | Map<string, Set<() => void>>
+      | undefined;
+    if (handlers && handlers.size > 0) {
+      if (changedProperties && changedProperties.size > 0) {
+        changedProperties.forEach((_value, dependency) => {
+          const callbacks = handlers.get(String(dependency));
+          if (callbacks) {
+            callbacks.forEach((cb) => cb());
+          }
+        });
+      } else {
+        handlers.forEach((callbacks) => callbacks.forEach((cb) => cb()));
+      }
+    }
+    if (typeof originalWillUpdate === "function") {
+      originalWillUpdate.call(this, changedProperties);
+    }
+  };
+  (proto as InstanceStores)[hookedStoreKey] = true;
+}
+
+/** Clés utilisées par `@bind`. */
+export const bindDynamicWatchKeys = {
+  watcherStore: Symbol("__bindDynamicWatcherStore__"),
+  hooked: Symbol("__bindDynamicWillUpdateHooked__"),
+} as const;
+
+/** Clés utilisées par `@publish`. */
+export const publishDynamicWatchKeys = {
+  watcherStore: "__publishDynamicWatcherStore__",
+  hooked: "__publishDynamicWillUpdateHooked__",
+} as const;
+
+/** Clés utilisées par `@get`. */
+export const getDynamicWatchKeys = {
+  watcherStore: "__getDynamicWatcherStore__",
+  hooked: "__getDynamicWillUpdateHooked__",
+} as const;
+
+/** Clés utilisées par `@onAssign`. */
+export const onAssignDynamicWatchKeys = {
+  watcherStore: Symbol("__onAssignDynamicWatcherStore__"),
+  hooked: Symbol("__onAssignDynamicWillUpdateHooked__"),
+} as const;