@alt-javascript/camel-lite-component-cron 1.0.2

package/README.md

@@ -0,0 +1,62 @@
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What
+
+Cron-scheduled exchange trigger via [`node-cron`](https://www.npmjs.com/package/node-cron). Fires at the times defined by a standard 5- or 6-field cron expression. The schedule is validated at endpoint construction — an invalid expression throws a `CamelError` before the context starts.
+
+## Install
+
+```sh
+npm install camel-lite-component-cron
+```
+
+## URI Syntax
+
+```
+cron:name?schedule=<cron-expression>[&timezone=UTC]
+```
+
+URL-encode spaces in the cron expression as `+`.
+
+| Parameter  | Default | Description |
+|------------|---------|-------------|
+| `schedule` | *(required)* | 5-field (`* * * * *`) or 6-field (`* * * * * *`) cron expression with spaces encoded as `+`. Validated by `node-cron` at construction. |
+| `timezone` | `UTC`   | IANA timezone name (e.g. `America/New_York`). |
+
+### Headers Set on Each Exchange
+
+| Header               | Type     | Description |
+|----------------------|----------|-------------|
+| `CamelCronName`      | `string` | The cron name from the URI. |
+| `CamelCronFiredTime` | `Date`   | Timestamp of the scheduled firing. |
+
+## Usage
+
+```js
+import { CamelContext } from 'camel-lite-core';
+import { CronComponent } from 'camel-lite-component-cron';
+import { DirectComponent } from 'camel-lite-component-direct';
+
+const context = new CamelContext();
+context.addComponent('cron', new CronComponent());
+context.addComponent('direct', new DirectComponent());
+
+context.addRoutes({
+  configure(ctx) {
+    // Fires at midnight UTC every day
+    ctx.from('cron:midnight?schedule=0+0+0+*+*+*')
+      .to('direct:dailyJob');
+
+    ctx.from('direct:dailyJob')
+      .process(exchange => {
+        console.log('Daily job triggered at', exchange.in.getHeader('CamelCronFiredTime'));
+      });
+  }
+});
+
+await context.start();
+```
+
+## See Also
+
+[camel-lite — root README](../../README.md)

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@alt-javascript/camel-lite-component-cron",
+  "version": "1.0.2",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "dependencies": {
+    "@alt-javascript/common": "^3.0.7",
+    "@alt-javascript/config": "^3.0.7",
+    "@alt-javascript/logger": "^3.0.7",
+    "node-cron": "^4.0.0",
+    "@alt-javascript/camel-lite-core": "1.0.2"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "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",
+    "cron",
+    "scheduler",
+    "timer",
+    "component"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/src/CronComponent.js

@@ -0,0 +1,11 @@
+import { Component } from '@alt-javascript/camel-lite-core';
+import CronEndpoint from './CronEndpoint.js';
+
+class CronComponent extends Component {
+  createEndpoint(uri, remaining, parameters, context) {
+    return new CronEndpoint(uri, remaining, parameters, context);
+  }
+}
+
+export { CronComponent };
+export default CronComponent;

package/src/CronConsumer.js

@@ -0,0 +1,59 @@
+import { Consumer, Exchange } from '@alt-javascript/camel-lite-core';
+import { schedule as cronSchedule } from 'node-cron';
+import { LoggerFactory } from '@alt-javascript/logger';
+
+const log = LoggerFactory.getLogger('@alt-javascript/camel-lite/CronConsumer');
+
+class CronConsumer extends Consumer {
+  #uri;
+  #name;
+  #schedule;
+  #timezone;
+  #context;
+  #pipeline;
+  #task = null;
+
+  constructor(uri, name, schedule, timezone, context, pipeline) {
+    super();
+    this.#uri = uri;
+    this.#name = name;
+    this.#schedule = schedule;
+    this.#timezone = timezone;
+    this.#context = context;
+    this.#pipeline = pipeline;
+  }
+
+  get uri() { return this.#uri; }
+
+  async start() {
+    this.#context.registerConsumer(this.#uri, this);
+    log.info(`Cron consumer started: ${this.#uri} schedule='${this.#schedule}' tz='${this.#timezone}'`);
+
+    this.#task = cronSchedule(this.#schedule, async () => {
+      const exchange = new Exchange();
+      exchange.in.setHeader('CamelCronName', this.#name);
+      exchange.in.setHeader('CamelCronFiredTime', new Date());
+      exchange.in.body = null;
+
+      log.debug(`Cron ${this.#name} fired`);
+
+      try {
+        await this.#pipeline.run(exchange);
+      } catch (err) {
+        log.error(`Cron ${this.#name} error: ${err.message}`);
+      }
+    }, { timezone: this.#timezone });
+  }
+
+  async stop() {
+    if (this.#task) {
+      this.#task.stop();
+      this.#task = null;
+    }
+    this.#context.registerConsumer(this.#uri, null);
+    log.info(`Cron consumer stopped: ${this.#uri}`);
+  }
+}
+
+export { CronConsumer };
+export default CronConsumer;

package/src/CronEndpoint.js

@@ -0,0 +1,46 @@
+import { Endpoint, CamelError } from '@alt-javascript/camel-lite-core';
+import { validate } from 'node-cron';
+import CronConsumer from './CronConsumer.js';
+
+class CronEndpoint extends Endpoint {
+  #uri;
+  #name;
+  #schedule;
+  #timezone;
+  #context;
+
+  constructor(uri, remaining, parameters, context) {
+    super();
+    this.#uri = uri;
+    this.#name = remaining || 'cron';
+    this.#context = context;
+
+    const params = parameters instanceof URLSearchParams
+      ? parameters
+      : new URLSearchParams(typeof parameters === 'string' ? parameters : '');
+
+    const schedule = params.get('schedule');
+    if (!schedule) {
+      throw new CamelError(`cron: URI missing required 'schedule' parameter: ${uri}`);
+    }
+    // node-cron uses + as space in URI query — decode it
+    const decoded = decodeURIComponent(schedule.replace(/\+/g, ' '));
+    if (!validate(decoded)) {
+      throw new CamelError(`cron: invalid cron expression '${decoded}' in URI: ${uri}`);
+    }
+    this.#schedule = decoded;
+    this.#timezone = params.get('timezone') ?? 'UTC';
+  }
+
+  get uri() { return this.#uri; }
+  get name() { return this.#name; }
+  get schedule() { return this.#schedule; }
+  get timezone() { return this.#timezone; }
+
+  createConsumer(pipeline) {
+    return new CronConsumer(this.#uri, this.#name, this.#schedule, this.#timezone, this.#context, pipeline);
+  }
+}
+
+export { CronEndpoint };
+export default CronEndpoint;

package/src/index.js

@@ -0,0 +1,3 @@
+export { CronComponent } from './CronComponent.js';
+export { CronEndpoint } from './CronEndpoint.js';
+export { CronConsumer } from './CronConsumer.js';

package/test/cron.test.js

@@ -0,0 +1,111 @@
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { CamelContext, CamelError } from '@alt-javascript/camel-lite-core';
+import { CronComponent, CronEndpoint } from '../src/index.js';
+
+// ---------------------------------------------------------------------------
+// Unit: endpoint parameter parsing
+// ---------------------------------------------------------------------------
+
+describe('CronEndpoint: parameter parsing', () => {
+  function makeEndpoint(query) {
+    const params = new URLSearchParams(query);
+    // remaining = 'job', uri fabricated
+    return new CronEndpoint('cron:job?' + query, 'job', params, null);
+  }
+
+  it('parses a valid 5-field schedule', () => {
+    const ep = makeEndpoint('schedule=* * * * *');
+    assert.equal(ep.schedule, '* * * * *');
+  });
+
+  it('parses a valid 6-field schedule', () => {
+    const ep = makeEndpoint('schedule=* * * * * *');
+    assert.equal(ep.schedule, '* * * * * *');
+  });
+
+  it('decodes + as space in schedule (URL encoding)', () => {
+    const ep = makeEndpoint('schedule=*+*+*+*+*+*');
+    assert.equal(ep.schedule, '* * * * * *');
+  });
+
+  it('defaults timezone to UTC', () => {
+    const ep = makeEndpoint('schedule=* * * * *');
+    assert.equal(ep.timezone, 'UTC');
+  });
+
+  it('parses custom timezone', () => {
+    const ep = makeEndpoint('schedule=* * * * *&timezone=America/New_York');
+    assert.equal(ep.timezone, 'America/New_York');
+  });
+
+  it('name comes from remaining path segment', () => {
+    const params = new URLSearchParams('schedule=* * * * *');
+    const ep = new CronEndpoint('cron:myJob?schedule=* * * * *', 'myJob', params, null);
+    assert.equal(ep.name, 'myJob');
+  });
+
+  it('throws CamelError when schedule is missing', () => {
+    assert.throws(() => makeEndpoint(''), /missing required.*schedule/i);
+  });
+
+  it('throws CamelError for an invalid cron expression', () => {
+    assert.throws(() => makeEndpoint('schedule=not-valid'), /invalid cron expression/i);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Integration: fires exchanges on a fast schedule
+// ---------------------------------------------------------------------------
+
+describe('CronConsumer: fires exchanges', () => {
+  it('fires on every-second schedule and headers are set', async () => {
+    const ctx = new CamelContext();
+    ctx.addComponent('cron', new CronComponent());
+
+    const fired = [];
+    const { RouteBuilder } = await import('@alt-javascript/camel-lite-core');
+    const builder = new RouteBuilder();
+    // every-second cron (6-field with seconds support)
+    builder.from('cron:job?schedule=* * * * * *').process(ex => {
+      fired.push({
+        name: ex.in.getHeader('CamelCronName'),
+        time: ex.in.getHeader('CamelCronFiredTime'),
+        body: ex.in.body,
+      });
+    });
+    ctx.addRoutes(builder);
+    await ctx.start();
+
+    // Wait 2.5 seconds — should see at least 2 fires
+    await new Promise(r => setTimeout(r, 2500));
+    await ctx.stop();
+
+    assert.ok(fired.length >= 2, `expected >= 2 fires, got ${fired.length}`);
+    assert.equal(fired[0].name, 'job');
+    assert.ok(fired[0].time instanceof Date);
+    assert.equal(fired[0].body, null);
+  });
+
+  it('stop() prevents further fires', async () => {
+    const ctx = new CamelContext();
+    ctx.addComponent('cron', new CronComponent());
+
+    let fired = 0;
+    const { RouteBuilder } = await import('@alt-javascript/camel-lite-core');
+    const builder = new RouteBuilder();
+    builder.from('cron:stopper?schedule=* * * * * *').process(() => { fired++; });
+    ctx.addRoutes(builder);
+    await ctx.start();
+
+    // Let it fire at least once
+    await new Promise(r => setTimeout(r, 1200));
+    await ctx.stop();
+    const countAtStop = fired;
+
+    // Wait another second — should not fire more
+    await new Promise(r => setTimeout(r, 1200));
+    assert.equal(fired, countAtStop, 'cron should not fire after stop');
+    assert.ok(fired >= 1, 'should have fired at least once');
+  });
+});