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

package/README.md

@@ -0,0 +1,59 @@
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What
+
+Periodic exchange trigger with no external dependencies. Fires on a fixed interval, optionally with a startup delay and a maximum fire count.
+
+## Install
+
+```sh
+npm install camel-lite-component-timer
+```
+
+## URI Syntax
+
+```
+timer:name[?period=1000&delay=0&repeatCount=0]
+```
+
+| Parameter     | Default | Description |
+|---------------|---------|-------------|
+| `period`      | `1000`  | Interval between firings in milliseconds. |
+| `delay`       | `0`     | Delay before the first firing in milliseconds. |
+| `repeatCount` | `0`     | Number of times to fire. `0` = infinite. |
+
+### Headers Set on Each Exchange
+
+| Header                | Type     | Description |
+|-----------------------|----------|-------------|
+| `CamelTimerName`      | `string` | The timer name from the URI. |
+| `CamelTimerFiredTime` | `Date`   | Timestamp of the firing. |
+| `CamelTimerCounter`   | `number` | Fire count (1-based). |
+
+## Usage
+
+```js
+import { CamelContext } from 'camel-lite-core';
+import { TimerComponent } from 'camel-lite-component-timer';
+
+const context = new CamelContext();
+context.addComponent('timer', new TimerComponent());
+
+context.addRoutes({
+  configure(ctx) {
+    ctx.from('timer:tick?period=5000&repeatCount=3')
+      .process(exchange => {
+        const counter = exchange.in.getHeader('CamelTimerCounter');
+        const firedAt = exchange.in.getHeader('CamelTimerFiredTime');
+        console.log(`Tick #${counter} at ${firedAt.toISOString()}`);
+      });
+  }
+});
+
+await context.start();
+// Fires 3 times at 5-second intervals, then stops.
+```
+
+## See Also
+
+[camel-lite — root README](../../README.md)

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@alt-javascript/camel-lite-component-timer",
+  "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",
+    "@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",
+    "timer",
+    "scheduler",
+    "component"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/src/TimerComponent.js

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

package/src/TimerConsumer.js

@@ -0,0 +1,97 @@
+import { Consumer, Exchange } from '@alt-javascript/camel-lite-core';
+import { LoggerFactory } from '@alt-javascript/logger';
+
+const log = LoggerFactory.getLogger('@alt-javascript/camel-lite/TimerConsumer');
+
+class TimerConsumer extends Consumer {
+  #uri;
+  #name;
+  #period;
+  #delay;
+  #repeatCount;
+  #context;
+  #pipeline;
+  #counter = 0;
+  #intervalHandle = null;
+  #delayHandle = null;
+  #stopped = false;
+
+  constructor(uri, name, period, delay, repeatCount, context, pipeline) {
+    super();
+    this.#uri = uri;
+    this.#name = name;
+    this.#period = period;
+    this.#delay = delay;
+    this.#repeatCount = repeatCount;
+    this.#context = context;
+    this.#pipeline = pipeline;
+  }
+
+  get uri() { return this.#uri; }
+
+  async start() {
+    this.#stopped = false;
+    this.#counter = 0;
+    this.#context.registerConsumer(this.#uri, this);
+    log.info(`Timer consumer started: ${this.#uri} (period:${this.#period}ms delay:${this.#delay}ms repeatCount:${this.#repeatCount})`);
+
+    const fire = async () => {
+      if (this.#stopped) return;
+      this.#counter++;
+      const exchange = new Exchange();
+      exchange.in.setHeader('CamelTimerName', this.#name);
+      exchange.in.setHeader('CamelTimerFiredTime', new Date());
+      exchange.in.setHeader('CamelTimerCounter', this.#counter);
+      exchange.in.body = null;
+
+      log.debug(`Timer ${this.#name} firing (counter=${this.#counter})`);
+
+      try {
+        await this.#pipeline.run(exchange);
+      } catch (err) {
+        log.error(`Timer ${this.#name} error on fire ${this.#counter}: ${err.message}`);
+      }
+
+      if (this.#repeatCount > 0 && this.#counter >= this.#repeatCount) {
+        log.info(`Timer ${this.#name} reached repeatCount (${this.#repeatCount}), stopping`);
+        this.#clearTimers();
+      }
+    };
+
+    const startInterval = () => {
+      if (this.#stopped) return;
+      // fire immediately (Camel timer fires at t=0 before first interval)
+      fire();
+      if (this.#repeatCount !== 1) {
+        this.#intervalHandle = setInterval(fire, this.#period);
+      }
+    };
+
+    if (this.#delay > 0) {
+      this.#delayHandle = setTimeout(startInterval, this.#delay);
+    } else {
+      startInterval();
+    }
+  }
+
+  #clearTimers() {
+    if (this.#intervalHandle !== null) {
+      clearInterval(this.#intervalHandle);
+      this.#intervalHandle = null;
+    }
+    if (this.#delayHandle !== null) {
+      clearTimeout(this.#delayHandle);
+      this.#delayHandle = null;
+    }
+  }
+
+  async stop() {
+    this.#stopped = true;
+    this.#clearTimers();
+    this.#context.registerConsumer(this.#uri, null);
+    log.info(`Timer consumer stopped: ${this.#uri}`);
+  }
+}
+
+export { TimerConsumer };
+export default TimerConsumer;

package/src/TimerEndpoint.js

@@ -0,0 +1,47 @@
+import { Endpoint } from '@alt-javascript/camel-lite-core';
+import TimerConsumer from './TimerConsumer.js';
+
+class TimerEndpoint extends Endpoint {
+  #uri;
+  #name;
+  #period;
+  #delay;
+  #repeatCount;
+  #context;
+
+  constructor(uri, remaining, parameters, context) {
+    super();
+    this.#uri = uri;
+    this.#name = remaining || 'timer';
+    this.#context = context;
+
+    const params = parameters instanceof URLSearchParams
+      ? parameters
+      : new URLSearchParams(typeof parameters === 'string' ? parameters : '');
+
+    const rawPeriod = params.get('period');
+    const rawDelay = params.get('delay');
+    const rawRepeat = params.get('repeatCount');
+
+    const parsedPeriod = rawPeriod !== null ? parseInt(rawPeriod, 10) : 1000;
+    const parsedDelay = rawDelay !== null ? parseInt(rawDelay, 10) : 0;
+    const parsedRepeat = rawRepeat !== null ? parseInt(rawRepeat, 10) : 0;
+
+    this.#period = Math.max(1, Number.isNaN(parsedPeriod) ? 1000 : parsedPeriod);
+    this.#delay = Math.max(0, Number.isNaN(parsedDelay) ? 0 : parsedDelay);
+    this.#repeatCount = Math.max(0, Number.isNaN(parsedRepeat) ? 0 : parsedRepeat);
+  }
+
+  get uri() { return this.#uri; }
+  get name() { return this.#name; }
+  get period() { return this.#period; }
+  get delay() { return this.#delay; }
+  get repeatCount() { return this.#repeatCount; }
+
+  createConsumer(pipeline) {
+    return new TimerConsumer(this.#uri, this.#name, this.#period, this.#delay, this.#repeatCount, this.#context, pipeline);
+  }
+}
+
+export { TimerEndpoint };
+export default TimerEndpoint;

package/src/index.js

@@ -0,0 +1,3 @@
+export { TimerComponent } from './TimerComponent.js';
+export { TimerEndpoint } from './TimerEndpoint.js';
+export { TimerConsumer } from './TimerConsumer.js';

package/test/timer.test.js

@@ -0,0 +1,145 @@
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { CamelContext } from '@alt-javascript/camel-lite-core';
+import { TimerComponent, TimerEndpoint } from '../src/index.js';
+
+// ---------------------------------------------------------------------------
+// Unit: endpoint parameter parsing
+// ---------------------------------------------------------------------------
+
+describe('TimerEndpoint: parameter parsing', () => {
+  function makeEndpoint(query) {
+    const params = new URLSearchParams(query);
+    return new TimerEndpoint('timer:tick?' + query, 'tick', params, null);
+  }
+
+  it('defaults: period=1000 delay=0 repeatCount=0', () => {
+    const ep = makeEndpoint('');
+    assert.equal(ep.period, 1000);
+    assert.equal(ep.delay, 0);
+    assert.equal(ep.repeatCount, 0);
+  });
+
+  it('parses period', () => {
+    const ep = makeEndpoint('period=250');
+    assert.equal(ep.period, 250);
+  });
+
+  it('parses delay', () => {
+    const ep = makeEndpoint('delay=500');
+    assert.equal(ep.delay, 500);
+  });
+
+  it('parses repeatCount', () => {
+    const ep = makeEndpoint('repeatCount=5');
+    assert.equal(ep.repeatCount, 5);
+  });
+
+  it('name comes from remaining path segment', () => {
+    const ep = new TimerEndpoint('timer:myTimer', 'myTimer', new URLSearchParams(), null);
+    assert.equal(ep.name, 'myTimer');
+  });
+
+  it('clamps period to minimum 1ms', () => {
+    const ep = makeEndpoint('period=0');
+    assert.equal(ep.period, 1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Integration: fire exchanges
+// ---------------------------------------------------------------------------
+
+describe('TimerConsumer: fires exchanges', () => {
+  it('fires repeatCount exchanges then stops', async () => {
+    const ctx = new CamelContext();
+    ctx.addComponent('timer', new TimerComponent());
+
+    const fired = [];
+    const { RouteBuilder } = await import('@alt-javascript/camel-lite-core');
+    const builder = new RouteBuilder();
+    builder.from('timer:tick?period=30&repeatCount=3').process(ex => {
+      fired.push({
+        name: ex.in.getHeader('CamelTimerName'),
+        counter: ex.in.getHeader('CamelTimerCounter'),
+        time: ex.in.getHeader('CamelTimerFiredTime'),
+        body: ex.in.body,
+      });
+    });
+    ctx.addRoutes(builder);
+    await ctx.start();
+
+    // Wait for all 3 fires + margin
+    await new Promise(r => setTimeout(r, 200));
+    await ctx.stop();
+
+    assert.equal(fired.length, 3, `expected 3 fires, got ${fired.length}`);
+    assert.equal(fired[0].name, 'tick');
+    assert.equal(fired[0].counter, 1);
+    assert.equal(fired[1].counter, 2);
+    assert.equal(fired[2].counter, 3);
+    assert.equal(fired[0].body, null);
+    assert.ok(fired[0].time instanceof Date);
+  });
+
+  it('stop() cancels an infinite timer before repeatCount fires', async () => {
+    const ctx = new CamelContext();
+    ctx.addComponent('timer', new TimerComponent());
+
+    let fired = 0;
+    const { RouteBuilder } = await import('@alt-javascript/camel-lite-core');
+    const builder = new RouteBuilder();
+    builder.from('timer:stopper?period=50').process(() => { fired++; });
+    ctx.addRoutes(builder);
+    await ctx.start();
+
+    // Let it fire a few times
+    await new Promise(r => setTimeout(r, 80));
+    await ctx.stop();
+    const countAtStop = fired;
+
+    // Wait a bit more — should not fire after stop
+    await new Promise(r => setTimeout(r, 100));
+    assert.equal(fired, countAtStop, 'timer should not fire after stop');
+    assert.ok(fired >= 1, 'should have fired at least once before stop');
+  });
+
+  it('delay defers the first fire', async () => {
+    const ctx = new CamelContext();
+    ctx.addComponent('timer', new TimerComponent());
+
+    const times = [];
+    const start = Date.now();
+    const { RouteBuilder } = await import('@alt-javascript/camel-lite-core');
+    const builder = new RouteBuilder();
+    builder.from('timer:delayed?period=1000&delay=150&repeatCount=1').process(() => {
+      times.push(Date.now() - start);
+    });
+    ctx.addRoutes(builder);
+    await ctx.start();
+
+    await new Promise(r => setTimeout(r, 300));
+    await ctx.stop();
+
+    assert.equal(times.length, 1);
+    assert.ok(times[0] >= 100, `expected delay >= 100ms, got ${times[0]}ms`);
+  });
+
+  it('CamelTimerFiredTime is a Date instance', async () => {
+    const ctx = new CamelContext();
+    ctx.addComponent('timer', new TimerComponent());
+
+    let firedTime;
+    const { RouteBuilder } = await import('@alt-javascript/camel-lite-core');
+    const builder = new RouteBuilder();
+    builder.from('timer:ts?period=50&repeatCount=1').process(ex => {
+      firedTime = ex.in.getHeader('CamelTimerFiredTime');
+    });
+    ctx.addRoutes(builder);
+    await ctx.start();
+    await new Promise(r => setTimeout(r, 150));
+    await ctx.stop();
+
+    assert.ok(firedTime instanceof Date);
+  });
+});