nucleus-core-ts 0.9.827 → 0.9.828

package/dist/nucleus.config.d.ts

@@ -27,7 +27,16 @@ export declare const config: {
         readonly './proxy': "./src/Client/Proxy/index.ts";
     };
     /** Additional directories to transpile (dependencies of transpileOnly entries) */
-    readonly transpileDirs: readonly ["./src/Client/PubSub"];
+    /**
+     * Directories the FRONTEND imports at runtime.
+     *
+     * `fe/` is transpiled file by file, not bundled, so an import it makes has to
+     * exist under `dist/` at the same relative path. A panel that reads a cron
+     * expression shares that reader with the engine — one implementation, two
+     * callers — and without the folder here the published bundle asks for a file
+     * that was never shipped, which fails the CONSUMER's build, not ours.
+     */
+    readonly transpileDirs: readonly ["./src/Client/PubSub", "./src/Services/Integrations"];
     /** Build Configuration */
     readonly build: {
         readonly outDir: "dist";

package/dist/src/Services/Integrations/bindings.js

@@ -0,0 +1,248 @@
+/**
+ * Endpoints that need values from somewhere else.
+ *
+ * Plenty of APIs expose a list and a detail, and the detail is only reachable per
+ * item: `/company` gives you the companies, `/company-organization/{companyName}`
+ * gives you the people in one of them, and there is no endpoint that gives you
+ * all the people. Importing that shape means calling the second endpoint once per
+ * record of the first.
+ *
+ * A binding says where one parameter's value comes from — a fixed value, another
+ * endpoint's records, or a column of one of OUR tables. This module works out the
+ * order those calls have to happen in, refuses arrangements that cannot terminate,
+ * and expands the bindings into the concrete parameter sets to call with.
+ *
+ * Pure throughout: nothing here fetches or queries. The caller supplies whatever
+ * the parents produced.
+ */ import { getByPath } from './mapping';
+/**
+ * Ceiling on the calls one endpoint may fan out into.
+ *
+ * Two bindings over 500 parents each is 250.000 requests at somebody else's API —
+ * an accident, not an intent. Hitting this stops the run with an explanation
+ * rather than starting a stampede.
+ */ export const MAX_FANOUT_COMBINATIONS = 5000;
+// ── path tokens ─────────────────────────────────────────────────────────────
+/**
+ * Parameter names a path needs, in either convention: `{brace}` (OpenAPI) or
+ * `:colon` (nucleus and Express). Duplicates collapse — the same token twice is
+ * still one value.
+ */ export function pathTokens(path) {
+    const found = new Set();
+    const re = /\{([a-zA-Z_][\w-]*)\}|:([a-zA-Z_]\w*)/g;
+    let m = re.exec(path);
+    while(m !== null){
+        const name = m[1] ?? m[2];
+        if (name) found.add(name);
+        m = re.exec(path);
+    }
+    return [
+        ...found
+    ];
+}
+/**
+ * Substitutes token values into a path.
+ *
+ * Reports which tokens were left unfilled instead of sending the literal
+ * `{employeeNo}` to the far side — that produced a bare HTTP 400 with no clue
+ * which parameter was missing.
+ *
+ * `used` names the value keys consumed as path tokens so the caller does not also
+ * append them to the query string.
+ */ export function resolvePath(rawPath, values) {
+    const missing = new Set();
+    const used = new Set();
+    const path = rawPath.replace(/\{([a-zA-Z_][\w-]*)\}|:([a-zA-Z_]\w*)/g, (_full, brace, colon)=>{
+        const key = brace ?? colon;
+        const v = values[key];
+        if (v == null || v === '') {
+            missing.add(key);
+            return brace ? `{${key}}` : `:${key}`;
+        }
+        used.add(key);
+        return encodeURIComponent(String(v));
+    });
+    return {
+        path,
+        missing: [
+            ...missing
+        ],
+        used
+    };
+}
+/**
+ * Orders the endpoints so every parent is fetched before its children.
+ *
+ * A cycle is refused rather than broken arbitrarily: A needing B needing A has no
+ * correct starting point, and picking one would produce an import whose contents
+ * depend on which endpoint happened to be first in the list.
+ *
+ * The returned chain names the cycle in the order it was walked, so an operator
+ * can see which binding to remove.
+ */ export function planFetchOrder(endpoints, roots) {
+    const byId = new Map(endpoints.map((e)=>[
+            e.id,
+            e
+        ]));
+    const order = [];
+    const settled = new Set();
+    const onPath = [];
+    const onPathSet = new Set();
+    /** Returns the failure that stopped the walk, or null when the branch is fine. */ const visit = (id, requiredBy)=>{
+        if (settled.has(id)) return null;
+        if (onPathSet.has(id)) {
+            return {
+                ok: false,
+                reason: 'cycle',
+                chain: [
+                    ...onPath.slice(onPath.indexOf(id)),
+                    id
+                ]
+            };
+        }
+        const node = byId.get(id);
+        if (!node) {
+            return {
+                ok: false,
+                reason: 'unknown_endpoint',
+                missing: id,
+                requiredBy: requiredBy ?? id
+            };
+        }
+        onPath.push(id);
+        onPathSet.add(id);
+        for (const binding of node.paramBindings ?? []){
+            if (binding.from !== 'endpoint') continue;
+            const failure = visit(binding.endpointId, id);
+            if (failure) return failure;
+        }
+        onPath.pop();
+        onPathSet.delete(id);
+        settled.add(id);
+        order.push(id);
+        return null;
+    };
+    for (const id of roots ?? endpoints.map((e)=>e.id)){
+        const failure = visit(id, null);
+        if (failure) return failure;
+    }
+    return {
+        ok: true,
+        order
+    };
+}
+/**
+ * Turns bindings into the concrete parameter sets to call an endpoint with.
+ *
+ * One `endpoint` binding over 40 parents means 40 calls. Two independent bindings
+ * multiply, which is why {@link MAX_FANOUT_COMBINATIONS} exists.
+ *
+ * An endpoint with no bindings yields exactly one call with no parameters — the
+ * ordinary case, expressed as the degenerate fan-out rather than a special path.
+ *
+ * A binding whose source produced NOTHING yields no calls at all. That is not an
+ * error: a company with no employees is a real answer, and inventing a call with
+ * an empty parameter would ask the far side something meaningless.
+ */ export function expandBindings(bindings, sources, limit = MAX_FANOUT_COMBINATIONS) {
+    if (!bindings || bindings.length === 0) return {
+        ok: true,
+        calls: [
+            {
+                values: {}
+            }
+        ]
+    };
+    /** Candidate values for each binding, paired with the parent they came from. */ const axes = [];
+    for (const binding of bindings){
+        if (binding.from === 'static') {
+            axes.push({
+                param: binding.param,
+                options: [
+                    {
+                        value: binding.value
+                    }
+                ]
+            });
+            continue;
+        }
+        if (binding.from === 'endpoint') {
+            const records = sources.parents?.[binding.endpointId] ?? [];
+            const options = records.map((record)=>({
+                    value: getByPath(record, binding.field),
+                    parent: record
+                })).filter((o)=>o.value != null && o.value !== '');
+            axes.push({
+                param: binding.param,
+                options
+            });
+            continue;
+        }
+        const values = sources.entityValues?.[`${binding.entity}.${binding.field}`] ?? [];
+        axes.push({
+            param: binding.param,
+            options: values.filter((v)=>v != null && v !== '').map((value)=>({
+                    value
+                }))
+        });
+    }
+    // Any axis with no options means there is nothing to call for.
+    if (axes.some((a)=>a.options.length === 0)) return {
+        ok: true,
+        calls: []
+    };
+    const combinations = axes.reduce((n, a)=>n * a.options.length, 1);
+    if (combinations > limit) {
+        return {
+            ok: false,
+            reason: 'too_many',
+            combinations,
+            limit
+        };
+    }
+    let calls = [
+        {
+            values: {}
+        }
+    ];
+    for (const axis of axes){
+        const next = [];
+        for (const call of calls){
+            for (const option of axis.options){
+                next.push({
+                    values: {
+                        ...call.values,
+                        [axis.param]: option.value
+                    },
+                    // The LAST parent wins when several axes carry one; a mapping reads
+                    // `__parent`, singular, and the fan-out axis is the meaningful one.
+                    parent: option.parent ?? call.parent
+                });
+            }
+        }
+        calls = next;
+    }
+    return {
+        ok: true,
+        calls
+    };
+}
+/**
+ * Endpoint ids this endpoint needs fetched first. Used to decide which parents to
+ * keep in memory while a run walks the plan.
+ */ export function parentEndpointIds(bindings) {
+    const ids = new Set();
+    for (const b of bindings ?? [])if (b.from === 'endpoint') ids.add(b.endpointId);
+    return [
+        ...ids
+    ];
+}
+/**
+ * `entity.field` pairs this endpoint reads from our own tables, so the caller can
+ * fetch each column once rather than per binding.
+ */ export function entityValueKeys(bindings) {
+    const keys = new Set();
+    for (const b of bindings ?? [])if (b.from === 'entity') keys.add(`${b.entity}.${b.field}`);
+    return [
+        ...keys
+    ];
+}