@xdelivered/emberflow 0.2.0

package/dist/src/nodes/flow-control.js

@@ -0,0 +1,270 @@
+import { getByPath } from '../engine/index.js';
+const CONDITIONAL_OPS = new Set([
+    'eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'contains', 'exists', 'truthy',
+]);
+/**
+ * Only numbers and non-empty numeric strings take part in numeric coercion —
+ * Number(null), Number(''), and Number([]) are all 0, which would make
+ * `eq 0` match null/''/[] and `gt -1` match null.
+ */
+function asComparableNumber(v) {
+    if (typeof v === 'number')
+        return v;
+    if (typeof v === 'string' && v.trim() !== '')
+        return Number(v);
+    return NaN;
+}
+/** eq/neq base: strict equality, plus numeric-looking equality (`Number()` on both sides). */
+function looksEqual(input, comparand) {
+    if (input === comparand)
+        return true;
+    const a = asComparableNumber(input);
+    const b = asComparableNumber(comparand);
+    return !Number.isNaN(a) && !Number.isNaN(b) && a === b;
+}
+function numericMatch(op, input, comparand) {
+    const a = asComparableNumber(input);
+    const b = asComparableNumber(comparand);
+    if (Number.isNaN(a) || Number.isNaN(b))
+        return false;
+    switch (op) {
+        case 'gt': return a > b;
+        case 'gte': return a >= b;
+        case 'lt': return a < b;
+        case 'lte': return a <= b;
+    }
+}
+function ruleMatches(op, input, comparand) {
+    switch (op) {
+        case 'eq': return looksEqual(input, comparand);
+        case 'neq': return !looksEqual(input, comparand);
+        case 'gt':
+        case 'gte':
+        case 'lt':
+        case 'lte':
+            return numericMatch(op, input, comparand);
+        case 'contains':
+            if (typeof input === 'string')
+                return input.includes(String(comparand));
+            if (Array.isArray(input))
+                return input.includes(comparand);
+            return false;
+        case 'exists':
+            return input !== undefined && input !== null;
+        case 'truthy':
+            return Boolean(input);
+        default:
+            return false;
+    }
+}
+/**
+ * Flow-control nodes. Route reads a field from its input object and emits
+ * `$branch`; the executor then skips downstream nodes hanging off untaken
+ * branch handles (edge.sourceHandle = branch name).
+ */
+export function registerFlowControlNodes(registry) {
+    registry.register({
+        type: 'Input',
+        label: 'Input',
+        description: 'Entry point — emits the payload the run was invoked with (falling back to configured defaults).',
+        simpleDescription: 'Starts the run with its input data',
+        category: 'input',
+        traceKind: 'compute',
+        tags: ['entry'],
+        configSchema: {
+            fields: [
+                { name: 'fields', type: 'array' },
+                { name: 'defaults', type: 'object' },
+            ],
+        },
+        // Dynamic — the emitted shape depends on the configured fields.
+        outputSchema: { fields: [] },
+    }, async (ctx) => {
+        const merged = {
+            ...(ctx.config.defaults ?? {}),
+            ...ctx.runInput,
+        };
+        const declared = Array.isArray(ctx.config.fields)
+            ? ctx.config.fields
+            : [];
+        const missing = declared
+            .filter((f) => f.required && merged[f.name] === undefined)
+            .map((f) => f.name);
+        if (missing.length) {
+            throw new Error(`Missing required input field(s): ${missing.join(', ')}`);
+        }
+        const summary = JSON.stringify(merged);
+        // Full JSON, untruncated: the log UI renders parseable payloads as
+        // collapsible highlighted blocks — a sliced tail breaks the parse and
+        // regresses to a wall of escaped text.
+        ctx.log('info', `Run input: ${summary}`);
+        return merged;
+    });
+    registry.register({
+        type: 'Environment',
+        label: 'Environment',
+        description: 'Reports the environment this run targets. Emits `environment` (the run\'s target environment name, e.g. "prod"; "local" when the run carries none) and `isProd` (a convenience boolean, true only when environment === "prod"). PORT NOTE: the name comes from the run\'s target environment threaded through node ctx (ctx.environment) — it is undefined for browser/in-tab runs, which report "local". `isProd` exists so the common case (branch on "is this production?") is a one-field Conditional; branch on `environment` directly for finer-grained routing.',
+        simpleDescription: 'Reports which environment this run targets, so steps can branch on it.',
+        category: 'logic',
+        traceKind: 'compute',
+        tags: ['branching'],
+        // No inputs — the environment is read from the run context.
+        inputSchema: { fields: [] },
+        outputSchema: {
+            fields: [
+                { name: 'environment', type: 'string' },
+                { name: 'isProd', type: 'boolean' },
+            ],
+        },
+    }, async (ctx) => {
+        const environment = ctx.environment ?? 'local';
+        const isProd = environment === 'prod';
+        ctx.log('info', `Environment: ${environment} (isProd=${isProd})`);
+        return { environment, isProd };
+    });
+    registry.register({
+        type: 'Route',
+        label: 'Route',
+        description: 'Branches the flow on a field of its input. Edges leaving a named branch handle only run when that branch matches.',
+        simpleDescription: 'Sends the data down a different path based on one value',
+        category: 'logic',
+        traceKind: 'compute',
+        tags: ['branching'],
+        inputSchema: {
+            fields: [{ name: 'value', type: 'object', required: true }],
+        },
+        configSchema: {
+            fields: [
+                { name: 'field', type: 'string', required: true },
+                { name: 'branches', type: 'array', required: true },
+                { name: 'fallback', type: 'string' },
+            ],
+        },
+        outputSchema: {
+            fields: [{ name: '$branch', type: 'string' }],
+        },
+    }, async (ctx) => {
+        const value = (ctx.input.value ?? {});
+        const field = String(ctx.config.field ?? '');
+        const branches = Array.isArray(ctx.config.branches)
+            ? ctx.config.branches.map(String)
+            : [];
+        const raw = getByPath(value, field);
+        const candidate = String(raw);
+        let branch = branches.includes(candidate) ? candidate : undefined;
+        if (branch === undefined && typeof ctx.config.fallback === 'string' && ctx.config.fallback) {
+            branch = ctx.config.fallback;
+        }
+        if (branch === undefined) {
+            throw new Error(`Route: "${field}" resolved to "${candidate}", which matches no branch and no fallback is set`);
+        }
+        ctx.log('info', `Routing ${field}=${candidate} → branch "${branch}"`);
+        return { ...value, $branch: branch };
+    });
+    registry.register({
+        type: 'Conditional',
+        label: 'Conditional',
+        description: 'Branches the flow on an ordered set of rules evaluated against its input. The first matching rule wins; edges leaving a named branch handle only run when that branch matches.',
+        simpleDescription: 'Chooses a path based on the data',
+        category: 'logic',
+        traceKind: 'compute',
+        tags: ['branching'],
+        inputSchema: {
+            fields: [{ name: 'value', type: 'object', required: true }],
+        },
+        configSchema: {
+            fields: [
+                { name: 'branches', type: 'array', required: true },
+                { name: 'fallback', type: 'string' },
+            ],
+        },
+        outputSchema: {
+            fields: [{ name: '$branch', type: 'string' }],
+        },
+    }, async (ctx) => {
+        const value = ctx.input.value;
+        const rules = Array.isArray(ctx.config.branches) ? ctx.config.branches : [];
+        let branch;
+        for (const raw of rules) {
+            const rule = (raw !== null && typeof raw === 'object' ? raw : {});
+            const name = typeof rule.name === 'string' && rule.name ? rule.name : undefined;
+            const op = typeof rule.op === 'string' ? rule.op : undefined;
+            if (!name || !op || !CONDITIONAL_OPS.has(op)) {
+                ctx.log('warn', `Conditional: skipping malformed rule ${JSON.stringify(raw)}`);
+                continue;
+            }
+            if (ruleMatches(op, value, rule.value)) {
+                branch = name;
+                break;
+            }
+        }
+        if (branch === undefined && typeof ctx.config.fallback === 'string' && ctx.config.fallback) {
+            branch = ctx.config.fallback;
+        }
+        if (branch === undefined) {
+            throw new Error('Conditional: no rule matched and no fallback is set');
+        }
+        ctx.log('info', `Conditional matched → branch "${branch}"`);
+        return { value, $branch: branch };
+    });
+    registry.register({
+        type: 'Merge',
+        label: 'Merge',
+        description: 'Coalesces converging branch arms into one value: emits `value` = the first of its mapped inputs that is neither undefined nor null, in inputMap declaration order. PORT NOTE: the engine leaves an inputMap field undefined when its source node was skipped (an untaken branch arm), so wiring one input per arm makes `value` resolve to whichever arm actually ran. Use it as the join point after a Conditional whose arms each produce the same downstream value from a DIFFERENT node.',
+        simpleDescription: 'Joins branch paths — passes on whichever arm produced a value.',
+        category: 'logic',
+        traceKind: 'compute',
+        tags: ['branching'],
+        // Free-form: the converging arm values are supplied via inputMap, one
+        // field per arm; declaration order sets coalesce priority.
+        inputSchema: { fields: [] },
+        outputSchema: {
+            fields: [{ name: 'value', type: 'object' }],
+        },
+    }, async (ctx) => {
+        const entries = Object.entries(ctx.input);
+        const chosen = entries.find(([, v]) => v !== undefined && v !== null);
+        if (!chosen) {
+            ctx.log('warn', 'Merge: no incoming arm produced a value');
+            return { value: undefined };
+        }
+        ctx.log('info', `Merge: passing on value from "${chosen[0]}"`);
+        return { value: chosen[1] };
+    });
+    registry.register({
+        type: 'Subflow',
+        label: 'Subflow',
+        description: 'Runs another workflow to completion with the mapped input, then emits that child run\'s collected output.',
+        simpleDescription: 'Runs another workflow and uses its result',
+        category: 'logic',
+        traceKind: 'compute',
+        tags: ['subflow'],
+        // Free-form input: whatever is mapped onto this node becomes the child
+        // run's invocation payload (like an Input node's run input).
+        inputSchema: { fields: [] },
+        configSchema: {
+            fields: [{ name: 'workflowId', type: 'string', required: true }],
+        },
+        // Dynamic — the emitted shape is the child flow's Result output.
+        outputSchema: { fields: [] },
+    }, async (ctx) => {
+        const workflowId = String(ctx.config.workflowId ?? '');
+        if (!workflowId)
+            throw new Error('Subflow: no workflowId configured');
+        if (!ctx.runSubflow) {
+            throw new Error('subflows need a host that can look up workflows');
+        }
+        ctx.log('info', `Running subflow "${workflowId}"`);
+        const result = await ctx.runSubflow(workflowId, ctx.input);
+        if (result.status === 'failed') {
+            throw new Error(result.error ?? 'subflow failed');
+        }
+        const output = result.output;
+        // Spread a plain object so downstream nodes can map its fields directly;
+        // wrap anything else under `output`.
+        if (output !== null && typeof output === 'object' && !Array.isArray(output)) {
+            return { ...output };
+        }
+        return { output };
+    });
+}

package/dist/src/nodes/index.d.ts

@@ -0,0 +1,3 @@
+import type { NodeRegistry } from '../engine/index.js';
+/** All built-in nodes: login examples, Open-Meteo weather, anomaly-detection API, EV charging demo, HTTP Response, requireAuth. */
+export declare function createDefaultRegistry(delayMs?: number): NodeRegistry;

package/dist/src/nodes/index.js

@@ -0,0 +1,20 @@
+import { createLoginRegistry } from './login.js';
+import { registerWeatherNodes } from './weather.js';
+import { registerAnomalyNodes } from './anomaly.js';
+import { registerFlowControlNodes } from './flow-control.js';
+import { registerLoopNodes } from './loops.js';
+import { registerPradarNodesModule } from './pradar/index.js';
+import { registerResponseNodes } from './response.js';
+import { registerRequireAuthNode } from './requireAuth.js';
+/** All built-in nodes: login examples, Open-Meteo weather, anomaly-detection API, EV charging demo, HTTP Response, requireAuth. */
+export function createDefaultRegistry(delayMs) {
+    const registry = createLoginRegistry(delayMs);
+    registerWeatherNodes(registry);
+    registerAnomalyNodes(registry);
+    registerFlowControlNodes(registry);
+    registerLoopNodes(registry);
+    registerPradarNodesModule(registry);
+    registerResponseNodes(registry);
+    registerRequireAuthNode(registry);
+    return registry;
+}

package/dist/src/nodes/login.d.ts

@@ -0,0 +1,7 @@
+import { NodeRegistry } from '../engine/index.js';
+/**
+ * Build a NodeRegistry populated with the five login example nodes.
+ * `delayMs` is injected into every implementation via `await sleep(delayMs)`
+ * so tests can run with no delay by passing `0`.
+ */
+export declare function createLoginRegistry(delayMs?: number): NodeRegistry;

package/dist/src/nodes/login.js

@@ -0,0 +1,158 @@
+import { NodeRegistry } from '../engine/index.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Strip the `user-` prefix from a userId to get the username part. */
+function usernamePart(userId) {
+    return userId.startsWith('user-') ? userId.slice('user-'.length) : userId;
+}
+/**
+ * Build a NodeRegistry populated with the five login example nodes.
+ * `delayMs` is injected into every implementation via `await sleep(delayMs)`
+ * so tests can run with no delay by passing `0`.
+ */
+export function createLoginRegistry(delayMs = 300) {
+    const registry = new NodeRegistry();
+    registry.register({
+        type: 'ValidateCredentials',
+        label: 'Validate Credentials',
+        description: 'Validates a username and password.',
+        category: 'auth',
+        traceKind: 'compute',
+        inputSchema: {
+            fields: [
+                { name: 'username', type: 'string', required: true },
+                { name: 'password', type: 'string', required: true },
+            ],
+        },
+        outputSchema: {
+            fields: [
+                { name: 'userId', type: 'string' },
+                { name: 'username', type: 'string' },
+            ],
+        },
+    }, async (ctx) => {
+        await sleep(delayMs);
+        const username = String(ctx.input.username ?? '');
+        const password = String(ctx.input.password ?? '');
+        if (password.length < 4) {
+            throw new Error('Password too short');
+        }
+        ctx.log('info', `Credentials accepted for ${username}`);
+        return { userId: `user-${username}`, username };
+    });
+    registry.register({
+        type: 'FetchUser',
+        label: 'Fetch User',
+        description: 'Fetches a user record derived from a userId.',
+        category: 'data',
+        traceKind: 'compute',
+        inputSchema: {
+            fields: [{ name: 'userId', type: 'string', required: true }],
+        },
+        outputSchema: {
+            fields: [
+                { name: 'id', type: 'string' },
+                { name: 'name', type: 'string' },
+                { name: 'plan', type: 'enum', enumValues: ['free', 'pro'] },
+                { name: 'isNew', type: 'boolean' },
+            ],
+        },
+    }, async (ctx) => {
+        await sleep(delayMs);
+        const userId = String(ctx.input.userId ?? '');
+        const name = usernamePart(userId);
+        const plan = name.includes('pro') ? 'pro' : 'free';
+        const isNew = name.startsWith('new');
+        ctx.log('info', `Fetched user ${name}: plan=${plan}, isNew=${isNew}`);
+        return { id: userId, name, plan, isNew };
+    });
+    registry.register({
+        type: 'CheckPlan',
+        label: 'Check Plan',
+        description: 'Resolves the feature set for a user plan.',
+        category: 'logic',
+        traceKind: 'compute',
+        inputSchema: {
+            fields: [{ name: 'user', type: 'object', required: true }],
+        },
+        outputSchema: {
+            fields: [
+                { name: 'plan', type: 'enum', enumValues: ['free', 'pro'] },
+                { name: 'features', type: 'array' },
+            ],
+        },
+    }, async (ctx) => {
+        await sleep(delayMs);
+        const user = (ctx.input.user ?? {});
+        const plan = user.plan ?? 'free';
+        const features = plan === 'pro' ? ['sso', 'audit-log', 'priority-support'] : ['basic'];
+        ctx.log('info', `Plan ${plan} resolves to features: ${features.join(', ')}`);
+        return { plan, features };
+    });
+    registry.register({
+        type: 'WelcomeUser',
+        label: 'Welcome User',
+        description: 'Greets a freshly created user by name.',
+        category: 'auth',
+        traceKind: 'compute',
+        inputSchema: {
+            fields: [{ name: 'user', type: 'object', required: true }],
+        },
+        outputSchema: {
+            fields: [
+                { name: 'message', type: 'string' },
+                { name: 'userId', type: 'string' },
+            ],
+        },
+    }, async (ctx) => {
+        await sleep(delayMs);
+        const user = (ctx.input.user ?? {});
+        const message = `Welcome aboard, ${user.name}!`;
+        ctx.log('info', message);
+        return { message, userId: user.id };
+    });
+    registry.register({
+        type: 'IssueToken',
+        label: 'Issue Token',
+        description: 'Issues an access token for a userId.',
+        category: 'auth',
+        traceKind: 'compute',
+        inputSchema: {
+            fields: [
+                { name: 'userId', type: 'string', required: true },
+                { name: 'plan', type: 'enum', enumValues: ['free', 'pro'] },
+            ],
+        },
+        outputSchema: {
+            fields: [
+                { name: 'token', type: 'string' },
+                { name: 'issuedTo', type: 'string' },
+                { name: 'plan', type: 'string' },
+            ],
+        },
+    }, async (ctx) => {
+        await sleep(delayMs);
+        const userId = String(ctx.input.userId ?? '');
+        const plan = String(ctx.input.plan ?? 'free');
+        ctx.log('info', `Token issued for plan=${plan}`);
+        return { token: `tok_${userId}`, issuedTo: userId, plan };
+    });
+    registry.register({
+        type: 'Result',
+        label: 'Result',
+        description: 'Terminal node that passes its input through and displays it on the canvas.',
+        category: 'output',
+        traceKind: 'compute',
+        tags: ['display'],
+        inputSchema: {
+            fields: [{ name: 'data', type: 'object' }],
+        },
+        outputSchema: {
+            fields: [{ name: 'data', type: 'object' }],
+        },
+    }, async (ctx) => {
+        await sleep(delayMs);
+        ctx.log('info', 'Result collected');
+        return ctx.input;
+    });
+    return registry;
+}

package/dist/src/nodes/loops.d.ts

@@ -0,0 +1,11 @@
+import type { NodeRegistry } from '../engine/index.js';
+/**
+ * ForEach / Collect loop-region nodes. Iteration itself is owned by the
+ * executor (see FlowRun's loop machinery in ../engine/executor.ts) — these
+ * implementations exist so the node type is registered (canvas palette,
+ * schema-driven inspector fields, isolated single-node runs) and so an
+ * isolated run of just this node doesn't crash. In a real flow run the
+ * executor never calls these; it drives iteration itself and writes
+ * per-iteration / final output directly onto the node's run state.
+ */
+export declare function registerLoopNodes(registry: NodeRegistry): void;

package/dist/src/nodes/loops.js

@@ -0,0 +1,60 @@
+/**
+ * ForEach / Collect loop-region nodes. Iteration itself is owned by the
+ * executor (see FlowRun's loop machinery in ../engine/executor.ts) — these
+ * implementations exist so the node type is registered (canvas palette,
+ * schema-driven inspector fields, isolated single-node runs) and so an
+ * isolated run of just this node doesn't crash. In a real flow run the
+ * executor never calls these; it drives iteration itself and writes
+ * per-iteration / final output directly onto the node's run state.
+ */
+export function registerLoopNodes(registry) {
+    registry.register({
+        type: 'ForEach',
+        label: 'For Each',
+        description: 'Iterates over an array, running the downstream loop body once per item (or per batch). Paired with exactly one Collect node.',
+        simpleDescription: 'Repeats the next steps for each item in a list',
+        category: 'flow',
+        traceKind: 'compute',
+        tags: ['branching', 'loop'],
+        inputSchema: {
+            fields: [{ name: 'items', type: 'array', required: true }],
+        },
+        configSchema: {
+            fields: [
+                { name: 'batchSize', type: 'number', description: 'Items per iteration (default 1).' },
+                { name: 'maxIterations', type: 'number', description: 'Optional cap; extra iterations are truncated with a warning.' },
+            ],
+        },
+        outputSchema: {
+            fields: [
+                { name: 'item', type: 'object', description: 'Single element (batchSize 1) or a chunk array otherwise.' },
+                { name: 'index', type: 'number' },
+                { name: 'total', type: 'number' },
+            ],
+        },
+    }, 
+    // Passthrough stub only — the executor owns real iteration and never
+    // invokes this for a node of type ForEach inside a valid loop region.
+    async (ctx) => ctx.input);
+    registry.register({
+        type: 'Collect',
+        label: 'Collect',
+        description: 'Gathers each loop iteration\'s mapped value into an array once its paired ForEach finishes iterating.',
+        simpleDescription: 'Collects the results from the repeated steps into a list',
+        category: 'flow',
+        traceKind: 'compute',
+        tags: ['loop'],
+        inputSchema: {
+            fields: [{ name: 'value', type: 'object', required: false }],
+        },
+        outputSchema: {
+            fields: [
+                { name: 'items', type: 'array' },
+                { name: 'count', type: 'number' },
+            ],
+        },
+    }, 
+    // Stub — the executor overrides this with the accumulated results in a
+    // real run. Only exercised for an isolated run of this node in isolation.
+    async () => ({ items: [], count: 0 }));
+}

package/dist/src/nodes/pradar/index.d.ts

@@ -0,0 +1,7 @@
+import type { NodeRegistry } from '../../engine/index.js';
+/**
+ * EV charge scheduler nodes for the EV charging demo. Pure decision logic lives
+ * in ./logic; ./nodes wraps each function as a registry node. The vehicle /
+ * push-notification effect nodes are simulated (see their PORT NOTEs).
+ */
+export declare function registerPradarNodesModule(registry: NodeRegistry): void;

package/dist/src/nodes/pradar/index.js

@@ -0,0 +1,9 @@
+import { registerPradarNodes } from './nodes.js';
+/**
+ * EV charge scheduler nodes for the EV charging demo. Pure decision logic lives
+ * in ./logic; ./nodes wraps each function as a registry node. The vehicle /
+ * push-notification effect nodes are simulated (see their PORT NOTEs).
+ */
+export function registerPradarNodesModule(registry) {
+    registerPradarNodes(registry);
+}