@supersoniks/concorde 4.9.93 → 4.9.95

package/src/core/utils/derive.ts

@@ -0,0 +1,357 @@
+import {
+  DataProviderKey,
+  resolveStaticPublisherPath,
+  type PublisherPathInput,
+} from "@supersoniks/concorde/core/utils/dataProviderKey";
+import {
+  PublisherManager,
+  type DataProvider,
+} from "@supersoniks/concorde/core/utils/PublisherProxy";
+import Objects from "@supersoniks/concorde/core/utils/Objects";
+
+export type DeriveStatus = "loading" | "ready" | "error" | "empty";
+
+export type DeriveState = {
+  status: DeriveStatus;
+  error?: string | null;
+};
+
+export type DeriveCompute<I extends Record<string, unknown>, O, V> = (
+  inputs: I,
+  vars: V,
+) => O | Promise<O>;
+
+export type DeriveOptions<
+  I extends Record<string, unknown>,
+  O,
+  V = Record<string, unknown>,
+> = {
+  inputs: { [K in keyof I]: DataProviderKey<I[K]> | string };
+  compute: DeriveCompute<I, O, V>;
+  output: DataProviderKey<O> | string;
+  /** formDataProvider (ou autre DP) servant de variables `$top`, `$season`, … */
+  variables?: DataProviderKey<V> | string;
+  debounceMs?: number;
+  isEmpty?: (value: O) => boolean;
+  /** Taille max d’un tableau d’entrée (warn au-delà). Défaut 10_000. */
+  maxInputItems?: number;
+};
+
+export type DeriveHandle = {
+  stop: () => void;
+  /** Force un recalcul immédiat (sans debounce). */
+  recompute: () => void;
+};
+
+const DEFAULT_DEBOUNCE_MS = 50;
+const DEFAULT_MAX_INPUT_ITEMS = 10_000;
+const SLOW_EVAL_MS = 100;
+
+/** Graphe derivation : outputPath → set(inputRootIds) pour détection de cycles. */
+const deriveEdges = new Map<string, Set<string>>();
+
+function pathOf(input: PublisherPathInput): string {
+  return resolveStaticPublisherPath(input);
+}
+
+function rootOf(path: string): string {
+  return path.split(".")[0] ?? path;
+}
+
+function resolvePublisher(path: string): DataProvider {
+  const parts = path.split(".");
+  const root = parts.shift()!;
+  let pub: DataProvider = PublisherManager.get(root);
+  if (parts.length) {
+    pub = Objects.traverse(pub, parts) as DataProvider;
+  }
+  return pub;
+}
+
+function defaultIsEmpty(value: unknown): boolean {
+  if (value == null) return true;
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === "object") return Object.keys(value as object).length === 0;
+  if (typeof value === "string") return value.length === 0;
+  return false;
+}
+
+function countItems(value: unknown): number {
+  if (Array.isArray(value)) return value.length;
+  return 0;
+}
+
+/**
+ * Détecte un cycle si `output` chevauche une entrée, ou si une chaîne de
+ * dérivations (output → inputs) revient sur elle-même.
+ */
+function assertNoCycle(outputPath: string, inputPaths: string[]): void {
+  for (const inputPath of inputPaths) {
+    if (
+      inputPath === outputPath ||
+      outputPath.startsWith(inputPath + ".") ||
+      inputPath.startsWith(outputPath + ".")
+    ) {
+      throw new Error(
+        `[derive] Cycle détecté : la sortie "${outputPath}" chevauche l'entrée "${inputPath}".`,
+      );
+    }
+  }
+
+  const outputRoot = rootOf(outputPath);
+  const deps = new Map<string, Set<string>>();
+  for (const [out, inputs] of deriveEdges) {
+    deps.set(rootOf(out), new Set(inputs));
+  }
+  deps.set(outputRoot, new Set(inputPaths.map(rootOf)));
+
+  const stack = new Set<string>();
+  const visit = (node: string): boolean => {
+    if (stack.has(node)) return true;
+    stack.add(node);
+    for (const d of deps.get(node) ?? []) {
+      if (visit(d)) return true;
+    }
+    stack.delete(node);
+    return false;
+  };
+
+  if (visit(outputRoot)) {
+    throw new Error(
+      `[derive] Cycle détecté (chaîne) : la sortie "${outputPath}" dépend indirectement d'elle-même.`,
+    );
+  }
+}
+
+function registerEdges(outputPath: string, inputPaths: string[]): void {
+  deriveEdges.set(
+    outputPath,
+    new Set(inputPaths.map((p) => rootOf(p))),
+  );
+}
+
+function unregisterEdges(outputPath: string): void {
+  deriveEdges.delete(outputPath);
+}
+
+/**
+ * État de dérivation publié sur `{outputRoot}/_state_` pour `sonic-states`.
+ */
+export function deriveStateKey(output: PublisherPathInput): string {
+  return `${rootOf(pathOf(output))}/_state_`;
+}
+
+function publishState(outputPath: string, state: DeriveState): void {
+  const statePath = deriveStateKey(outputPath);
+  PublisherManager.get(statePath).set(state);
+}
+
+/**
+ * Primitive de données dérivées en lecture seule.
+ *
+ * Observe les DataProviders d’entrée (+ variables optionnelles), recalcule avec
+ * debounce, annule les résultats périmés (génération), publie sur `output`.
+ */
+export function derive<
+  I extends Record<string, unknown>,
+  O,
+  V = Record<string, unknown>,
+>(options: DeriveOptions<I, O, V>): DeriveHandle;
+export function derive<
+  I extends Record<string, unknown>,
+  O,
+  V = Record<string, unknown>,
+>(
+  inputs: { [K in keyof I]: DataProviderKey<I[K]> | string },
+  compute: DeriveCompute<I, O, V>,
+  output: DataProviderKey<O> | string,
+  variables?: DataProviderKey<V> | string,
+): DeriveHandle;
+export function derive<
+  I extends Record<string, unknown>,
+  O,
+  V = Record<string, unknown>,
+>(
+  inputsOrOptions:
+    | DeriveOptions<I, O, V>
+    | { [K in keyof I]: DataProviderKey<I[K]> | string },
+  compute?: DeriveCompute<I, O, V>,
+  output?: DataProviderKey<O> | string,
+  variables?: DataProviderKey<V> | string,
+): DeriveHandle {
+  const opts: DeriveOptions<I, O, V> =
+    typeof (inputsOrOptions as DeriveOptions<I, O, V>).compute === "function"
+      ? (inputsOrOptions as DeriveOptions<I, O, V>)
+      : {
+          inputs: inputsOrOptions as {
+            [K in keyof I]: DataProviderKey<I[K]> | string;
+          },
+          compute: compute!,
+          output: output!,
+          variables,
+        };
+
+  const debounceMs = opts.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  const maxItems = opts.maxInputItems ?? DEFAULT_MAX_INPUT_ITEMS;
+  const isEmpty = opts.isEmpty ?? defaultIsEmpty;
+
+  const outputPath = pathOf(opts.output);
+  const inputEntries = Object.entries(opts.inputs).map(([alias, key]) => ({
+    alias,
+    path: pathOf(key as PublisherPathInput),
+  }));
+  const inputPaths = inputEntries.map((e) => e.path);
+  const variablesPath = opts.variables
+    ? pathOf(opts.variables as PublisherPathInput)
+    : null;
+
+  assertNoCycle(outputPath, inputPaths);
+  registerEdges(outputPath, inputPaths);
+
+  const outputPub = resolvePublisher(outputPath);
+  let lastValue: O | undefined;
+  let writing = false;
+  let generation = 0;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let stopped = false;
+  let lastMemoKey = "";
+
+  const setOutput = (value: O) => {
+    writing = true;
+    lastValue = value;
+    outputPub.set(value as never);
+    writing = false;
+  };
+
+  const onExternalWrite = () => {
+    if (writing || stopped) return;
+    if (typeof console !== "undefined" && console.warn) {
+      console.warn(
+        `[derive] Écriture ignorée sur la sortie readonly "${outputPath}".`,
+      );
+    }
+    if (lastValue !== undefined) {
+      writing = true;
+      outputPub.set(lastValue as never);
+      writing = false;
+    }
+  };
+  outputPub.onAssign(onExternalWrite, false);
+
+  const collectInputs = (): I => {
+    const result = {} as I;
+    for (const { alias, path } of inputEntries) {
+      const value = resolvePublisher(path).get();
+      const n = countItems(value);
+      if (n > maxItems && typeof console !== "undefined" && console.warn) {
+        console.warn(
+          `[derive] Entrée "${path}" : ${n} éléments (> ${maxItems}). Agrégation lourde — envisager un plafond côté fetch.`,
+        );
+      }
+      (result as Record<string, unknown>)[alias] = value;
+    }
+    return result;
+  };
+
+  const collectVars = (): V => {
+    if (!variablesPath) return {} as V;
+    return (resolvePublisher(variablesPath).get() ?? {}) as V;
+  };
+
+  const run = async () => {
+    if (stopped) return;
+    const gen = ++generation;
+    publishState(outputPath, { status: "loading", error: null });
+
+    const inputs = collectInputs();
+    const vars = collectVars();
+    const memoKey = JSON.stringify({ inputs, vars });
+    if (memoKey === lastMemoKey && lastValue !== undefined) {
+      publishState(outputPath, {
+        status: isEmpty(lastValue) ? "empty" : "ready",
+        error: null,
+      });
+      return;
+    }
+
+    const t0 =
+      typeof performance !== "undefined" ? performance.now() : Date.now();
+    try {
+      const result = await Promise.resolve(opts.compute(inputs, vars));
+      if (stopped || gen !== generation) return;
+
+      const elapsed =
+        (typeof performance !== "undefined" ? performance.now() : Date.now()) -
+        t0;
+      if (elapsed > SLOW_EVAL_MS && typeof console !== "undefined" && console.warn) {
+        console.warn(
+          `[derive] Évaluation longue (${Math.round(elapsed)} ms) → "${outputPath}".`,
+        );
+      }
+
+      lastMemoKey = memoKey;
+      setOutput(result);
+      publishState(outputPath, {
+        status: isEmpty(result) ? "empty" : "ready",
+        error: null,
+      });
+    } catch (err) {
+      if (stopped || gen !== generation) return;
+      const message = err instanceof Error ? err.message : String(err);
+      if (typeof console !== "undefined" && console.error) {
+        console.error(`[derive] Erreur sur "${outputPath}" :`, message);
+      }
+      publishState(outputPath, { status: "error", error: message });
+    }
+  };
+
+  const schedule = () => {
+    if (stopped) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      void run();
+    }, debounceMs);
+  };
+
+  const listeners: Array<{
+    pub: DataProvider;
+    handler: () => void;
+  }> = [];
+
+  /**
+   * Écoute les mutations profondes : les champs form (`name="top"`) écrivent sur
+   * un sous-proxy (`form.top.set`), qui ne déclenche pas `onAssign` sur la racine.
+   * `onInternalMutation` remonte bien parent ← enfant.
+   */
+  const watch = (path: string) => {
+    const pub = resolvePublisher(path);
+    const handler = () => schedule();
+    pub.onInternalMutation(handler);
+    listeners.push({ pub, handler });
+  };
+
+  for (const { path } of inputEntries) watch(path);
+  if (variablesPath) watch(variablesPath);
+
+  // Premier calcul (onInternalMutation a déjà appelé schedule à l’abonnement,
+  // mais on force un passage après init complète).
+  schedule();
+
+  return {
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      if (timer) clearTimeout(timer);
+      for (const { pub, handler } of listeners) {
+        pub.offInternalMutation(handler);
+      }
+      outputPub.offAssign(onExternalWrite);
+      unregisterEdges(outputPath);
+    },
+    recompute() {
+      lastMemoKey = "";
+      void run();
+    },
+  };
+}

package/src/core/utils/jsonataHelpers.ts

@@ -0,0 +1,100 @@
+import type { Expression } from "jsonata";
+import Format from "@supersoniks/concorde/core/utils/Format";
+
+export type ChartDataset = {
+  label?: string;
+  data: number[];
+};
+
+export type ChartShape = {
+  labels: string[];
+  datasets: ChartDataset[];
+};
+
+/**
+ * Enregistre les helpers whitelistés sur une expression JSONata compilée.
+ * Pas de DOM, pas de réseau, pas d’eval.
+ */
+export function registerJsonataHelpers(expression: Expression): void {
+  expression.registerFunction("ucFirst", (value: unknown) =>
+    Format.ucFirst(String(value ?? "")),
+  );
+
+  expression.registerFunction(
+    "currency",
+    (value: unknown, locale = "fr-FR", currency = "EUR") => {
+      const n = Number(value);
+      if (Number.isNaN(n)) return String(value ?? "");
+      return new Intl.NumberFormat(String(locale), {
+        style: "currency",
+        currency: String(currency),
+      }).format(n);
+    },
+  );
+
+  expression.registerFunction(
+    "percent",
+    (value: unknown, locale = "fr-FR", digits = 0) => {
+      const n = Number(value);
+      if (Number.isNaN(n)) return String(value ?? "");
+      return new Intl.NumberFormat(String(locale), {
+        style: "percent",
+        maximumFractionDigits: Number(digits) || 0,
+      }).format(n);
+    },
+  );
+
+  expression.registerFunction(
+    "date",
+    (value: unknown, locale = "fr-FR", optionsJson?: string) => {
+      const d = value instanceof Date ? value : new Date(String(value));
+      if (Number.isNaN(d.getTime())) return String(value ?? "");
+      let options: Intl.DateTimeFormatOptions = {
+        dateStyle: "medium",
+      };
+      if (optionsJson) {
+        try {
+          options = JSON.parse(
+            String(optionsJson),
+          ) as Intl.DateTimeFormatOptions;
+        } catch {
+          /* keep default */
+        }
+      }
+      return new Intl.DateTimeFormat(String(locale), options).format(d);
+    },
+  );
+
+  /**
+   * Convertit un tableau d’objets `{ label, value }` (ou clés custom) en forme chart.
+   * Usage : `$toChart(items, 'titre', 'ca')`
+   */
+  expression.registerFunction(
+    "toChart",
+    (
+      items: unknown,
+      labelKey = "label",
+      valueKey = "value",
+      datasetLabel = "",
+    ): ChartShape => {
+      const rows = Array.isArray(items) ? items : [];
+      const labels: string[] = [];
+      const data: number[] = [];
+      for (const row of rows) {
+        if (!row || typeof row !== "object") continue;
+        const rec = row as Record<string, unknown>;
+        labels.push(String(rec[String(labelKey)] ?? ""));
+        data.push(Number(rec[String(valueKey)] ?? 0));
+      }
+      return {
+        labels,
+        datasets: [
+          {
+            label: String(datasetLabel || ""),
+            data,
+          },
+        ],
+      };
+    },
+  );
+}

package/src/core/utils/jsonataRuntime.ts

@@ -0,0 +1,88 @@
+import jsonata, { type Expression } from "jsonata";
+import { registerJsonataHelpers } from "@supersoniks/concorde/core/utils/jsonataHelpers";
+
+const expressionCache = new Map<string, Expression>();
+
+const MAX_EXPRESSION_LENGTH = 8_000;
+
+/**
+ * Compile (avec cache) une expression JSONata + helpers Concorde.
+ */
+export function compileJsonata(source: string): Expression {
+  if (!source || !source.trim()) {
+    throw new Error("[sonic-jsonata] expression vide.");
+  }
+  if (source.length > MAX_EXPRESSION_LENGTH) {
+    throw new Error(
+      `[sonic-jsonata] expression trop longue (${source.length} > ${MAX_EXPRESSION_LENGTH}).`,
+    );
+  }
+  const cached = expressionCache.get(source);
+  if (cached) return cached;
+  try {
+    const expr = jsonata(source);
+    registerJsonataHelpers(expr);
+    expressionCache.set(source, expr);
+    return expr;
+  } catch (err) {
+    const message =
+      err instanceof Error
+        ? err.message
+        : typeof err === "object" && err && "message" in err
+          ? String((err as { message: unknown }).message)
+          : String(err);
+    throw new Error(`[sonic-jsonata] Syntaxe JSONata invalide : ${message}`);
+  }
+}
+
+/**
+ * Validation runtime légère (sous-ensemble JSON Schema).
+ * Vérifie `type` et `required` ; ignore le reste.
+ */
+export function validateOutputSchema(
+  value: unknown,
+  schema: Record<string, unknown> | null | undefined,
+): void {
+  if (!schema || typeof schema !== "object") return;
+
+  const type = schema.type;
+  if (typeof type === "string") {
+    const ok =
+      (type === "array" && Array.isArray(value)) ||
+      (type === "object" &&
+        value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value)) ||
+      (type === "string" && typeof value === "string") ||
+      (type === "number" && typeof value === "number") ||
+      (type === "boolean" && typeof value === "boolean") ||
+      (type === "null" && value === null);
+    if (!ok) {
+      throw new Error(
+        `[sonic-jsonata] outputSchema : type attendu "${type}", reçu ${describeType(value)}.`,
+      );
+    }
+  }
+
+  if (Array.isArray(schema.required) && value && typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    for (const key of schema.required) {
+      if (typeof key === "string" && !(key in obj)) {
+        throw new Error(
+          `[sonic-jsonata] outputSchema : propriété requise manquante "${key}".`,
+        );
+      }
+    }
+  }
+}
+
+function describeType(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+/** Vide le cache (tests). */
+export function clearJsonataCache(): void {
+  expressionCache.clear();
+}

package/src/docs/_core-concept/dataFlow.md

@@ -16,6 +16,7 @@ Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, d
 | HTTP POST (body from store) | `@post` + `Endpoint` + body `DataProviderKey` |
 | HTTP PUT / PATCH (body from store) | `@put` / `@patch` — same model as `@post` |
 | Forms | `formDataProvider` + `name` on fields |
+| Derived / aggregate (JSONata) | `derive()` or `sonic-jsonata` — [Jsonata](#core/components/functional/jsonata/jsonata.md/jsonata) |
 | Offline doc demos | `serviceURL="/docs-mock-api"` — [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) |
 
 Skill: `concorde-get-set-dp` in the package `ai/` folder.
@@ -69,6 +70,14 @@ npx @supersoniks/create-concorde-ts-starter my-app
 
 Interactive routes mirror these patterns (`/concepts/*`, `/demo/*`).
 
+## Derived data (`derive` / `sonic-jsonata`)
+
+Use when you need **client-side aggregations** (groupby, top N, chart shapes) from existing DataProviders — without inline app JS in SDUI.
+
+- Primitive: `derive({ inputs, compute, output, variables? })` from `@supersoniks/concorde/utils` (read-only output, debounce, generation, cycle detection, `{output}/_state_`).
+- SDUI adapter: [`sonic-jsonata`](#core/components/functional/jsonata/jsonata.md/jsonata) (`inputProvider` → `expression` → `outputProvider`, optional `formDataProvider`).
+- vs [`sonic-mix`](#core/components/functional/mix/mix.md/mix): mix composes bidirectionally; jsonata **computes** unidirectionally.
+
 ## Legacy integration
 
 | Topic | Page |

package/src/docs/_misc/docs-mock-api.md

@@ -16,6 +16,9 @@ TypeScript constants: `src/docs/mock-api/urls.ts` (`DOCS_MOCK_REQRES_SERVICE`, `
 |------|---------|
 | `/docs-mock-api/api/users` | `sonic-list`, `sonic-fetch`, `sonic-queue` (users) |
 | `/docs-mock-api/api/users/:id` | Single user, `docs-user` |
+| `/docs-mock-api/api/space-cats` | `sonic-jsonata` top-N demo |
+| `/docs-mock-api/api/coffee-bags` | fixtures / tests jsonata (`?roast=`) |
+| `/docs-mock-api/api/market-order` | `sonic-jsonata` totals demo |
 | `POST /docs-mock-api/api/register` | **sonic-submit** — JSON, `multipart/form-data` (`sendAsFormData`), or `application/x-www-form-urlencoded` (native `<form>`); response includes parsed `email` + `token` |
 | `POST /docs-mock-api/api/register/nested` | Wrapped body `{ data: { id, token } }` for `submit-result-key` demo |
 | `GET /docs-mock-api/api/register/echo` | Echoes query string (`method="get"` on submit) |

package/src/docs/components/docs-demo-sources.ts

@@ -81,6 +81,24 @@ export const DOCS_LIT_DEMO_REGISTRY: Record<string, DocsLitDemoConfig> = {
       { path: "src/docs/example/docs-users-list.ts", line: 15, label: "docs-users-list" },
     ],
   },
+  "docs-jsonata-space-cats-demo": {
+    sources: [
+      {
+        path: "src/docs/example/docs-jsonata-demos.ts",
+        line: 26,
+        label: "top-n",
+      },
+    ],
+  },
+  "docs-jsonata-table-totals-demo": {
+    sources: [
+      {
+        path: "src/docs/example/docs-jsonata-demos.ts",
+        line: 69,
+        label: "totals",
+      },
+    ],
+  },
   "docs-list-alternate-demo": {
     sources: [
       { path: "src/docs/example/docs-list-demos.ts", line: 51, label: "alternate" },
@@ -204,6 +222,14 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "docs-joke-search-demo": [
     { path: "src/docs/example/docs-joke-demos.ts", label: "joke demos" },
   ],
+  "docs-jsonata-space-cats-demo": [
+    { path: "src/docs/example/docs-jsonata-demos.ts", label: "jsonata demos" },
+    { path: "src/docs/mock-api/fixtures-jsonata.ts", label: "fixtures" },
+  ],
+  "docs-jsonata-table-totals-demo": [
+    { path: "src/docs/example/docs-jsonata-demos.ts", label: "jsonata demos" },
+    { path: "src/docs/mock-api/fixtures-jsonata.ts", label: "fixtures" },
+  ],
   "docs-joke-lang-demo": [
     { path: "src/docs/example/docs-joke-demos.ts", label: "joke demos" },
   ],

package/src/docs/docs.ts

@@ -15,6 +15,7 @@ import "./example/docs-joke-demos";
 import "./example/docs-queue-demos";
 import "./example/docs-toggle-demos";
 import "./example/docs-list-demos";
+import "./example/docs-jsonata-demos";
 import "./example/docs-router-demos";
 import "./example/docs-submit-demos";
 import "./example/docs-api-config-demos";