@alt-javascript/camel-lite-core 1.0.2

package/README.md

@@ -0,0 +1,161 @@
+# camel-lite-core
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+
+Core framework for camel-lite — the `CamelContext`, routing DSL, `Exchange`, `Pipeline`, `ProducerTemplate`, `ConsumerTemplate`, and `RouteLoader`.
+
+## Install
+
+```bash
+npm install camel-lite-core
+```
+
+## Quick Start
+
+```javascript
+import { CamelContext, RouteBuilder, ProducerTemplate } from 'camel-lite-core';
+import { DirectComponent } from 'camel-lite-component-direct';
+
+const context = new CamelContext();
+context.addComponent('direct', new DirectComponent());
+
+const builder = new RouteBuilder();
+builder.from('direct:hello')
+  .process(ex => { ex.in.body = `Hello, ${ex.in.body}!`; });
+
+context.addRoutes(builder);
+await context.start();
+
+const pt = new ProducerTemplate(context);
+const exchange = await pt.sendBody('direct:hello', 'world');
+console.log(exchange.in.body); // Hello, world!
+
+await context.stop();
+```
+
+## RouteDefinition DSL
+
+| Method | Description |
+|---|---|
+| `process(fn\|obj)` | Run a processor — `async fn(exchange)` or `{ process(exchange) }` |
+| `to(uri)` | Send to another endpoint |
+| `filter(expr)` | Stop processing if predicate returns false |
+| `transform(expr)` | Replace body with expression result |
+| `setBody(expr)` | Set `exchange.in.body` |
+| `setHeader(name, expr)` | Set a header |
+| `setProperty(name, expr)` | Set an exchange property |
+| `removeHeader(name)` | Remove a header |
+| `choice()` | Content-based router — `.when(expr).to(uri)…​.otherwise().to(uri).end()` |
+| `split(expr)` | Split body into sub-exchanges |
+| `aggregate(expr, strategy)` | Aggregate sub-exchanges |
+| `marshal(format)` | Serialise body (default: `json`) |
+| `unmarshal(format)` | Deserialise body |
+| `convertBodyTo(type)` | Convert body type |
+| `bean(name)` | Invoke named bean from context |
+| `log(expr)` | Log expression result |
+| `stop()` | Stop processing |
+| `deadLetterChannel(uri)` | Route failed exchanges to this URI |
+| `onException(ErrorClass)` | Handle a specific exception type |
+
+## Expressions
+
+```javascript
+import { simple, js, constant } from 'camel-lite-core';
+
+simple('${body}')                    // exchange body
+simple('${header.X-Auth}')           // header value
+simple('${exchangeProperty.key}')    // exchange property
+js('exchange.in.body.toUpperCase()') // arbitrary JS via new Function()
+constant('fixed value')              // literal constant
+```
+
+**Note:** `simple()` does not support mixed literal + token strings (e.g. `'Prefix: ${body}'`). Use `js()` or a `process()` step for string building. See [ADR-006](../../docs/adr/ADR-006.md).
+
+## RouteLoader
+
+```javascript
+import { RouteLoader } from 'camel-lite-core';
+
+// From file — extension auto-detects format (.yaml/.yml/.json); unknown → content-sniff
+const builder = await RouteLoader.loadFile('routes.yaml');
+
+// From readable stream — content-sniffed (use for stdin or HTTP responses)
+const builder = await RouteLoader.loadStream(process.stdin);
+
+// From string
+const builder = RouteLoader.loadString(yamlOrJsonString);
+
+// From already-parsed object (e.g. from @alt-javascript/config at boot time)
+const builder = RouteLoader.loadObject({ route: { from: { uri: 'direct:x', steps: [] } } });
+```
+
+### YAML route format
+
+```yaml
+route:
+  id: my-route
+  from:
+    uri: direct:hello
+    steps:
+      - setBody:
+          simple: "${body}"
+      - to: log:hello
+      - choice:
+          when:
+            - simple: "${body} == 'ping'"
+              to: direct:pong
+          otherwise:
+            to: direct:default
+```
+
+## ProducerTemplate
+
+```javascript
+const pt = new ProducerTemplate(context);
+
+// InOnly — returns the exchange after completion
+const exchange = await pt.sendBody('direct:hello', 'world', { 'X-Header': 'value' });
+
+// InOut — returns the result body (exchange.out.body, fallback to exchange.in.body)
+const result = await pt.requestBody('direct:hello', 'world');
+```
+
+## ConsumerTemplate
+
+Polls from `seda:` endpoints. Direct: and other push-model endpoints are not supported.
+
+```javascript
+const ct = new ConsumerTemplate(context);
+
+const exchange = await ct.receive('seda:work', 5000);   // Exchange or null on timeout
+const body     = await ct.receiveBody('seda:work', 5000); // body or null on timeout
+```
+
+## Error Handling
+
+```javascript
+builder.from('direct:input')
+  .onException(Error)
+    .to('direct:errors')
+    .end()
+  .process(ex => { throw new Error('oops'); });
+```
+
+Configure redelivery via Pipeline options:
+
+```javascript
+import { Pipeline } from 'camel-lite-core';
+
+new Pipeline(processors, {
+  maximumRedeliveries: 3,
+  redeliveryDelay: 1000,
+  deadLetterUri: 'direct:dlq',
+});
+```
+
+## See Also
+
+- [Root README](../../README.md)
+- [ADR-007: Component factory chain](../../docs/adr/ADR-007.md)
+- [ADR-006: Expression language](../../docs/adr/ADR-006.md)
+- [ADR-011: Route loading entry points](../../docs/adr/ADR-011.md)

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@alt-javascript/camel-lite-core",
+  "version": "1.0.2",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "devDependencies": {
+    "@alt-javascript/camel-lite-component-direct": "1.0.2",
+    "@alt-javascript/camel-lite-component-seda": "1.0.2"
+  },
+  "dependencies": {
+    "@alt-javascript/common": "^3.0.7",
+    "@alt-javascript/config": "^3.0.7",
+    "@alt-javascript/logger": "^3.0.7",
+    "js-yaml": "^4.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alt-javascript/camel-lite"
+  },
+  "author": "Craig Parravicini",
+  "contributors": [
+    "Claude (Anthropic)",
+    "Apache Camel — design inspiration and pattern source"
+  ],
+  "keywords": [
+    "alt-javascript",
+    "camel",
+    "camel-lite",
+    "eai",
+    "eip",
+    "integration",
+    "core",
+    "routing",
+    "pipeline",
+    "exchange",
+    "processor"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/src/AggregationStrategies.js

@@ -0,0 +1,40 @@
+import { Exchange } from './Exchange.js';
+
+/**
+ * Built-in aggregation strategy helpers.
+ * Each factory returns a strategy function: (exchanges[]) => Exchange
+ */
+const AggregationStrategies = {
+  /**
+   * Collects exchange bodies into an array.
+   * aggregated.in.body = [body1, body2, ...]
+   */
+  collectBodies() {
+    return (exchanges) => {
+      const agg = new Exchange();
+      agg.in.body = exchanges.map(e => e.in.body);
+      return agg;
+    };
+  },
+
+  /**
+   * Returns the last exchange in the batch (latest-wins).
+   */
+  latest() {
+    return (exchanges) => exchanges[exchanges.length - 1];
+  },
+
+  /**
+   * Concatenates string bodies with a separator (default '').
+   */
+  joinBodies(separator = '') {
+    return (exchanges) => {
+      const agg = new Exchange();
+      agg.in.body = exchanges.map(e => String(e.in.body ?? '')).join(separator);
+      return agg;
+    };
+  },
+};
+
+export { AggregationStrategies };
+export default AggregationStrategies;

package/src/CamelContext.js

@@ -0,0 +1,131 @@
+import { LoggerFactory } from '@alt-javascript/logger';
+
+const log = LoggerFactory.getLogger('@alt-javascript/camel-lite/CamelContext');
+
+class CamelContext {
+  #components = new Map();
+  #routes = new Map();
+  #routeDefinitions = new Map();
+  #consumers = new Map();
+  #beans = new Map();
+  #started = false;
+  #abortController = null;
+
+  /**
+   * Register a named bean in the context.
+   * Beans are arbitrary objects (datasources, clients, configuration, etc.)
+   * that components can look up by name rather than requiring direct injection.
+   * @param {string} name
+   * @param {*} bean
+   * @returns {CamelContext} this (fluent)
+   */
+  registerBean(name, bean) {
+    this.#beans.set(name, bean);
+    return this;
+  }
+
+  /**
+   * Retrieve a named bean from the context.
+   * @param {string} name
+   * @returns {*} the bean, or undefined if not found
+   */
+  getBean(name) {
+    return this.#beans.get(name);
+  }
+
+  /**
+   * Return all registered beans as an array of [name, bean] pairs.
+   * @returns {Array<[string, *]>}
+   */
+  getBeans() {
+    return Array.from(this.#beans.entries());
+  }
+
+  addComponent(scheme, component) {
+    this.#components.set(scheme, component);
+    return this;
+  }
+
+  getComponent(scheme) {
+    return this.#components.get(scheme);
+  }
+
+  addRoutes(builder) {
+    if (typeof builder.configure === 'function') {
+      builder.configure(this);
+    }
+    for (const routeDef of builder.getRoutes()) {
+      // Eager compile (no context) — preserves existing getRoute() behaviour
+      const pipeline = routeDef.compile();
+      this.#routes.set(routeDef.fromUri, pipeline);
+      // Also store the RouteDefinition for context-aware start()
+      this.#routeDefinitions.set(routeDef.fromUri, routeDef);
+    }
+    return this;
+  }
+
+  getRoute(uri) {
+    return this.#routes.get(uri);
+  }
+
+  registerConsumer(uri, consumer) {
+    this.#consumers.set(uri, consumer);
+  }
+
+  getConsumer(uri) {
+    return this.#consumers.get(uri);
+  }
+
+  async start() {
+    this.#abortController = new AbortController();
+    const signal = this.#abortController.signal;
+
+    for (const [fromUri, routeDef] of this.#routeDefinitions) {
+      const colonIdx = fromUri.indexOf(':');
+      const scheme = colonIdx >= 0 ? fromUri.slice(0, colonIdx) : fromUri;
+      const rest = colonIdx >= 0 ? fromUri.slice(colonIdx + 1) : '';
+      const qIdx = rest.indexOf('?');
+      const remaining = qIdx >= 0 ? rest.slice(0, qIdx) : rest;
+      const params = qIdx >= 0
+        ? new URLSearchParams(rest.slice(qIdx + 1))
+        : new URLSearchParams();
+
+      const component = this.getComponent(scheme);
+      if (!component) {
+        log.warn(`No component registered for scheme: ${scheme} — route ${fromUri} will not be started`);
+        continue;
+      }
+
+      const compiledPipeline = routeDef.compile(this, { signal });
+      const endpoint = component.createEndpoint(fromUri, remaining, params, this);
+      const consumer = endpoint.createConsumer(compiledPipeline);
+      this.#consumers.set(fromUri, consumer);
+      await consumer.start();
+    }
+
+    log.info('Apache Camel Lite started');
+    this.#started = true;
+  }
+
+  async stop() {
+    // Signal abort — cancels any in-flight redelivery sleeps
+    if (this.#abortController) {
+      this.#abortController.abort();
+      this.#abortController = null;
+    }
+
+    for (const consumer of this.#consumers.values()) {
+      await consumer.stop();
+    }
+    this.#consumers.clear();
+    this.#started = false;
+    log.info('Apache Camel Lite stopped');
+  }
+
+  get started() {
+    return this.#started;
+  }
+}
+
+export { CamelContext };
+export default CamelContext;

package/src/ConsumerTemplate.js

@@ -0,0 +1,77 @@
+import { LoggerFactory } from '@alt-javascript/logger';
+
+const log = LoggerFactory.getLogger('@alt-javascript/camel-lite/ConsumerTemplate');
+
+const SUPPORTED_POLL_SCHEMES = new Set(['seda']);
+
+/**
+ * ConsumerTemplate — high-level API for polling messages from queue-based
+ * endpoints (currently seda:) registered in a running CamelContext.
+ *
+ * Only polling-capable endpoints are supported. Push-model endpoints like
+ * direct: do not expose a dequeuable queue and will throw a clear error.
+ *
+ * Usage:
+ *   const ct = new ConsumerTemplate(context);
+ *   const exchange = await ct.receive('seda:work', 3000);
+ *   const body     = await ct.receiveBody('seda:work', 3000);
+ */
+class ConsumerTemplate {
+  #context;
+
+  constructor(context) {
+    if (!context) throw new Error('ConsumerTemplate requires a CamelContext');
+    this.#context = context;
+  }
+
+  /**
+   * Poll for an exchange from the given URI.
+   * Returns the Exchange, or null if the timeout expires before a message arrives.
+   * @param {string} uri
+   * @param {number} [timeoutMs=5000]
+   * @returns {Promise<Exchange|null>}
+   */
+  async receive(uri, timeoutMs = 5000) {
+    const scheme = this.#scheme(uri);
+    if (!SUPPORTED_POLL_SCHEMES.has(scheme)) {
+      throw new Error(
+        `ConsumerTemplate does not support polling from '${scheme}:'. ` +
+        `Supported schemes: ${[...SUPPORTED_POLL_SCHEMES].join(', ')}`
+      );
+    }
+
+    log.info(`ConsumerTemplate polling from ${uri}`);
+
+    const consumer = this.#context.getConsumer(uri);
+    if (!consumer) {
+      throw new Error(`ConsumerTemplate: no consumer registered for '${uri}' — is the context started?`);
+    }
+
+    return consumer.poll(timeoutMs);
+  }
+
+  /**
+   * Poll for a message body from the given URI.
+   * Returns exchange.in.body, or null if the timeout expires.
+   * @param {string} uri
+   * @param {number} [timeoutMs=5000]
+   * @returns {Promise<*>}
+   */
+  async receiveBody(uri, timeoutMs = 5000) {
+    const exchange = await this.receive(uri, timeoutMs);
+    return exchange !== null ? exchange.in.body : null;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  #scheme(uri) {
+    const idx = uri.indexOf(':');
+    if (idx < 0) throw new Error(`ConsumerTemplate: invalid URI (no scheme): ${uri}`);
+    return uri.slice(0, idx);
+  }
+}
+
+export { ConsumerTemplate };
+export default ConsumerTemplate;

package/src/Exchange.js

@@ -0,0 +1,70 @@
+import Message from './Message.js';
+
+class Exchange {
+  #in;
+  #out;
+  #pattern;
+  #properties = new Map();
+  #exception = null;
+
+  constructor(pattern = 'InOnly') {
+    this.#pattern = pattern;
+    this.#in = new Message();
+    this.#out = new Message();
+  }
+
+  get in() {
+    return this.#in;
+  }
+
+  get out() {
+    return this.#out;
+  }
+
+  get pattern() {
+    return this.#pattern;
+  }
+
+  get properties() {
+    return this.#properties;
+  }
+
+  get exception() {
+    return this.#exception;
+  }
+
+  set exception(value) {
+    this.#exception = value;
+  }
+
+  getProperty(key) {
+    return this.#properties.get(key);
+  }
+
+  setProperty(key, value) {
+    this.#properties.set(key, value);
+  }
+
+  isFailed() {
+    return this.#exception != null;
+  }
+
+  /**
+   * Shallow clone — copies body, headers, and properties. Does NOT copy exception.
+   * Used by the splitter to create independent sub-exchanges.
+   */
+  clone() {
+    const copy = new Exchange(this.#pattern);
+    copy.in.body = this.#in.body;
+    for (const [k, v] of this.#in.headers) {
+      copy.in.setHeader(k, v);
+    }
+    for (const [k, v] of this.#properties) {
+      copy.setProperty(k, v);
+    }
+    return copy;
+  }
+}
+
+export { Exchange };
+export default Exchange;

package/src/ExpressionBuilder.js

@@ -0,0 +1,122 @@
+/**
+ * Expression builders for camel-lite EIP predicates and expressions.
+ *
+ * Three forms are supported by all EIP DSL methods (filter, transform, split, aggregate, choice):
+ *   1. Native JS function:  (exchange) => value
+ *   2. simple(template):    Camel Simple language subset — ${body}, ${header.X}, ${exchangeProperty.X}
+ *   3. js(code):            Arbitrary JS string evaluated as new Function('exchange', code)
+ *
+ * All three normalise to: (exchange) => value
+ */
+
+/**
+ * Normalise a predicate/expression to a plain function.
+ * If already a function, returned as-is.
+ * If an object with a _camelExpr flag (returned by simple/js), the compiled fn is extracted.
+ */
+export function normaliseExpression(expr) {
+  if (typeof expr === 'function') return expr;
+  if (expr && typeof expr === 'object' && typeof expr._fn === 'function') return expr._fn;
+  throw new TypeError('Expression must be a function, simple(...) or js(...) result');
+}
+
+/**
+ * Compile a Camel Simple language template string to a function.
+ *
+ * Supported tokens:
+ *   ${body}                 → exchange.in.body
+ *   ${in.body}              → exchange.in.body
+ *   ${header.X}             → exchange.in.getHeader('X')
+ *   ${headers.X}            → exchange.in.getHeader('X')
+ *   ${exchangeProperty.X}   → exchange.getProperty('X')
+ *
+ * Comparison operators (used in predicate context):
+ *   ==, !=, >, >=, <, <=
+ *   contains, not contains  → .includes() / !.includes()
+ *   regex                   → new RegExp(rhs).test(lhs)
+ *   is, is not              → instanceof (class name lookup — limited)
+ *   in, not in              → [a,b,c].includes()
+ *   null                    → null literal
+ *   empty                   → '' or null or 0 check
+ *
+ * Logical: &&, ||, and, or
+ */
+export function simple(template) {
+  const code = compileSimple(template);
+  // eslint-disable-next-line no-new-func
+  const fn = new Function('exchange', `"use strict"; return (${code});`);
+  return { _camelExpr: true, _template: template, _fn: fn };
+}
+
+/**
+ * Wrap a constant value as an expression function.
+ * The returned object is compatible with normaliseExpression().
+ *
+ * Example: constant('hello') → expression that always returns 'hello'
+ */
+export function constant(value) {
+  return { _camelExpr: true, _value: value, _fn: () => value };
+}
+
+
+export function js(code) {
+  // If the code contains newlines or multiple statements (const/let/var declarations,
+  // semicolons), compile as a function body rather than a single return expression.
+  const trimmed = code.trim();
+  const isBlock = /\n/.test(trimmed) || /^\s*(const|let|var|if|for|while|return)\b/.test(trimmed);
+  let fn;
+  if (isBlock) {
+    // Multi-statement block: wrap in a function body, last expression is returned
+    // by convention the block should end with the value to return.
+    // eslint-disable-next-line no-new-func
+    fn = new Function('exchange', `"use strict"; ${trimmed}`);
+  } else {
+    // Single expression: wrap in return(...)
+    // eslint-disable-next-line no-new-func
+    fn = new Function('exchange', `"use strict"; return (${trimmed});`);
+  }
+  return { _camelExpr: true, _code: code, _fn: fn };
+}
+
+// ---------------------------------------------------------------------------
+// Simple language compiler
+// ---------------------------------------------------------------------------
+
+function compileSimple(template) {
+  let t = template.trim();
+
+  // Replace ${body} and ${in.body}
+  t = t.replace(/\$\{(?:in\.)?body\}/g, 'exchange.in.body');
+
+  // Replace ${header.X} and ${headers.X}
+  t = t.replace(/\$\{headers?\.([^}]+)\}/g, (_, name) => `exchange.in.getHeader(${JSON.stringify(name)})`);
+
+  // Replace ${out.body}
+  t = t.replace(/\$\{out\.body\}/g, 'exchange.out.body');
+
+  // Replace ${exchangeProperty.X}
+  t = t.replace(/\$\{exchangeProperty\.([^}]+)\}/g, (_, name) => `exchange.getProperty(${JSON.stringify(name)})`);
+
+  // Replace ${null} literal
+  t = t.replace(/\$\{null\}/g, 'null');
+
+  // contains / not contains
+  t = t.replace(/\bnot contains\b/g, '%%NOT_CONTAINS%%');
+  t = t.replace(/\bcontains\s+"([^"]+)"/g, (_, v) => `.includes(${JSON.stringify(v)})`);
+  t = t.replace(/\bcontains\s+'([^']+)'/g, (_, v) => `.includes(${JSON.stringify(v)})`);
+  t = t.replace(/%%NOT_CONTAINS%%\s+"([^"]+)"/g, (_, v) => `!String(exchange.in.body).includes(${JSON.stringify(v)})`);
+
+  // regex
+  t = t.replace(/\s+regex\s+"([^"]+)"/g, (_, pattern) => ` && new RegExp(${JSON.stringify(pattern)}).test(String(exchange.in.body))`);
+
+  // Logical: 'and' / 'or' (whole word, not inside strings)
+  t = t.replace(/\band\b/g, '&&');
+  t = t.replace(/\bor\b/g, '||');
+
+  // Simple language uses == for equality (map to ===)
+  // but only if not already === or !==
+  t = t.replace(/([^!<>=])==/g, '$1===');
+  t = t.replace(/([^!<>=])!=/g, '$1!==');
+
+  return t;
+}

package/src/Message.js

@@ -0,0 +1,38 @@
+import { randomUUID } from 'node:crypto';
+
+class Message {
+  #body = null;
+  #headers = new Map();
+  #messageId;
+
+  constructor() {
+    this.#messageId = randomUUID();
+  }
+
+  get body() {
+    return this.#body;
+  }
+
+  set body(value) {
+    this.#body = value;
+  }
+
+  get headers() {
+    return this.#headers;
+  }
+
+  get messageId() {
+    return this.#messageId;
+  }
+
+  getHeader(key) {
+    return this.#headers.get(key);
+  }
+
+  setHeader(key, value) {
+    this.#headers.set(key, value);
+  }
+}
+
+export { Message };
+export default Message;