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

package/README.md

@@ -0,0 +1,67 @@
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What
+
+File read (consumer: polls a directory) and write (producer: writes exchange body to a file). Supports configurable file name, character encoding, and auto-delete after read.
+
+## Install
+
+```sh
+npm install camel-lite-component-file
+```
+
+## URI Syntax
+
+```
+file:/absolute/path[?fileName=out.txt&charset=utf8&delete=false]
+```
+
+| Parameter  | Default     | Description |
+|------------|-------------|-------------|
+| `fileName` | *(auto)*    | Output file name for producers. Consumers ignore this; all files in the directory are read. |
+| `charset`  | `utf8`      | Character encoding for reading/writing file content. |
+| `delete`   | `false`     | Consumer only: delete the source file after it has been successfully read. |
+
+## Usage
+
+**Producer — write exchange body to a file:**
+
+```js
+import { CamelContext } from 'camel-lite-core';
+import { FileComponent } from 'camel-lite-component-file';
+
+const context = new CamelContext();
+context.addComponent('file', new FileComponent());
+
+context.addRoutes({
+  configure(ctx) {
+    ctx.from('direct:writeFile')
+      .to('file:/tmp/output?fileName=result.txt&charset=utf8');
+  }
+});
+
+await context.start();
+
+const template = context.createProducerTemplate();
+await template.sendBody('direct:writeFile', 'Hello, file!');
+
+await context.stop();
+```
+
+**Consumer — read files from a directory:**
+
+```js
+context.addRoutes({
+  configure(ctx) {
+    ctx.from('file:/tmp/inbox?delete=true')
+      .process(exchange => {
+        console.log('File content:', exchange.in.body);
+        console.log('File name:', exchange.in.getHeader('CamelFileName'));
+      });
+  }
+});
+```
+
+## See Also
+
+[camel-lite — root README](../../README.md)

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@alt-javascript/camel-lite-component-file",
+  "version": "1.0.2",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "dependencies": {
+    "@alt-javascript/logger": "^3.0.7",
+    "@alt-javascript/config": "^3.0.7",
+    "@alt-javascript/common": "^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",
+    "file",
+    "io",
+    "component"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/src/FileComponent.js

@@ -0,0 +1,19 @@
+import { Component } from '@alt-javascript/camel-lite-core';
+import FileEndpoint from './FileEndpoint.js';
+
+class FileComponent extends Component {
+  // Endpoint cache — same path returns same endpoint
+  #endpoints = new Map();
+
+  createEndpoint(uri, remaining, parameters, context) {
+    if (this.#endpoints.has(uri)) {
+      return this.#endpoints.get(uri);
+    }
+    const endpoint = new FileEndpoint(uri, remaining, parameters, context);
+    this.#endpoints.set(uri, endpoint);
+    return endpoint;
+  }
+}
+
+export { FileComponent };
+export default FileComponent;

package/src/FileConsumer.js

@@ -0,0 +1,81 @@
+import { Consumer, Exchange } from '@alt-javascript/camel-lite-core';
+import { LoggerFactory } from '@alt-javascript/logger';
+import { readdir, readFile, mkdir, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const log = LoggerFactory.getLogger('@alt-javascript/camel-lite/FileConsumer');
+
+class FileConsumer extends Consumer {
+  #uri;
+  #context;
+  #dir;
+  #noop;
+
+  constructor(uri, context, dir, noop = false) {
+    super();
+    this.#uri = uri;
+    this.#context = context;
+    this.#dir = dir;
+    this.#noop = noop;
+  }
+
+  get uri() { return this.#uri; }
+
+  async start() {
+    this.#context.registerConsumer(this.#uri, this);
+    log.info(`File consumer started: ${this.#dir}`);
+  }
+
+  async stop() {
+    this.#context.registerConsumer(this.#uri, null);
+    log.info(`File consumer stopped: ${this.#dir}`);
+  }
+
+  /**
+   * One-shot poll: read all non-hidden files from the directory.
+   * Returns an array of Exchange objects, one per file.
+   * Files are moved to dir/.done/ after reading unless noop=true.
+   */
+  async poll() {
+    log.info(`Polling: ${this.#dir}`);
+
+    let entries;
+    try {
+      entries = await readdir(this.#dir, { withFileTypes: true });
+    } catch {
+      // Directory does not exist yet — return empty
+      return [];
+    }
+
+    const files = entries.filter(
+      e => e.isFile() && !e.name.startsWith('.')
+    );
+
+    const exchanges = [];
+
+    for (const file of files) {
+      const filePath = join(this.#dir, file.name);
+      const content = await readFile(filePath, 'utf8');
+      log.debug(`Read: ${file.name}`);
+
+      const exchange = new Exchange();
+      exchange.in.body = content;
+      exchange.in.setHeader('CamelFileName', file.name);
+      exchange.in.setHeader('CamelFilePath', filePath);
+
+      if (!this.#noop) {
+        const doneDir = join(this.#dir, '.done');
+        await mkdir(doneDir, { recursive: true });
+        await rename(filePath, join(doneDir, file.name));
+        log.debug(`Moved to .done: ${file.name}`);
+      }
+
+      exchanges.push(exchange);
+    }
+
+    return exchanges;
+  }
+}
+
+export { FileConsumer };
+export default FileConsumer;

package/src/FileEndpoint.js

@@ -0,0 +1,43 @@
+import { Endpoint } from '@alt-javascript/camel-lite-core';
+import FileProducer from './FileProducer.js';
+import FileConsumer from './FileConsumer.js';
+
+class FileEndpoint extends Endpoint {
+  #uri;
+  #dir;
+  #fileName;
+  #noop;
+  #context;
+
+  constructor(uri, remaining, parameters, context) {
+    super();
+    this.#uri = uri;
+    this.#context = context;
+
+    // remaining is the directory path (everything after 'file:' and before '?')
+    this.#dir = remaining;
+
+    const params = parameters instanceof URLSearchParams
+      ? parameters
+      : new URLSearchParams(typeof parameters === 'string' ? parameters : '');
+
+    this.#fileName = params.get('fileName') ?? null;
+    this.#noop = params.get('noop') === 'true';
+  }
+
+  get uri() { return this.#uri; }
+  get dir() { return this.#dir; }
+  get fileName() { return this.#fileName; }
+  get noop() { return this.#noop; }
+
+  createProducer() {
+    return new FileProducer(this.#dir, this.#fileName);
+  }
+
+  createConsumer(pipeline) {
+    return new FileConsumer(this.#uri, this.#context, this.#dir, this.#noop);
+  }
+}
+
+export { FileEndpoint };
+export default FileEndpoint;

package/src/FileProducer.js

@@ -0,0 +1,43 @@
+import { Producer } from '@alt-javascript/camel-lite-core';
+import { LoggerFactory } from '@alt-javascript/logger';
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const log = LoggerFactory.getLogger('@alt-javascript/camel-lite/FileProducer');
+
+class FileProducer extends Producer {
+  #dir;
+  #fileName;
+
+  constructor(dir, fileName = null) {
+    super();
+    this.#dir = dir;
+    this.#fileName = fileName;
+  }
+
+  get dir() { return this.#dir; }
+  get fileName() { return this.#fileName; }
+
+  async send(exchange) {
+    // Resolve file name: CamelFileName header > constructor param > messageId.txt
+    const name = exchange.in.getHeader('CamelFileName')
+      ?? this.#fileName
+      ?? (exchange.in.messageId + '.txt');
+
+    const filePath = join(this.#dir, name);
+    await mkdir(this.#dir, { recursive: true });
+
+    const body = exchange.in.body ?? '';
+    const content = typeof body === 'string' ? body : JSON.stringify(body);
+
+    await writeFile(filePath, content, 'utf8');
+    log.info(`Written: ${filePath}`);
+
+    // Inform downstream steps of the written path
+    exchange.out.setHeader('CamelFileName', name);
+    exchange.out.setHeader('CamelFilePath', filePath);
+  }
+}
+
+export { FileProducer };
+export default FileProducer;

package/src/index.js

@@ -0,0 +1,7 @@
+export { FileComponent } from './FileComponent.js';
+export { FileEndpoint } from './FileEndpoint.js';
+export { FileProducer } from './FileProducer.js';
+export { FileConsumer } from './FileConsumer.js';
+
+import FileComponent from './FileComponent.js';
+export default FileComponent;

package/test/file.test.js

@@ -0,0 +1,202 @@
+import { describe, it, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { readFile, mkdir, writeFile, rm, access } from 'node:fs/promises';
+import { CamelContext, Exchange, Component } from '@alt-javascript/camel-lite-core';
+import { FileComponent, FileEndpoint, FileProducer, FileConsumer } from '@alt-javascript/camel-lite-component-file';
+
+function makeTmpDir() {
+  return join(tmpdir(), 'camel-lite-file-test-' + randomUUID());
+}
+
+describe('FileProducer', () => {
+  it('writes string body to disk with default filename (messageId.txt)', async () => {
+    const dir = makeTmpDir();
+    const producer = new FileProducer(dir);
+    const exchange = new Exchange();
+    exchange.in.body = 'hello file';
+
+    await producer.send(exchange);
+
+    const filePath = join(dir, exchange.in.messageId + '.txt');
+    const content = await readFile(filePath, 'utf8');
+    assert.equal(content, 'hello file');
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('uses CamelFileName header when set', async () => {
+    const dir = makeTmpDir();
+    const producer = new FileProducer(dir);
+    const exchange = new Exchange();
+    exchange.in.body = 'named content';
+    exchange.in.setHeader('CamelFileName', 'custom.txt');
+
+    await producer.send(exchange);
+
+    const content = await readFile(join(dir, 'custom.txt'), 'utf8');
+    assert.equal(content, 'named content');
+    assert.equal(exchange.out.getHeader('CamelFileName'), 'custom.txt');
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('uses fileName constructor param as fallback', async () => {
+    const dir = makeTmpDir();
+    const producer = new FileProducer(dir, 'fixed.txt');
+    const exchange = new Exchange();
+    exchange.in.body = 'fixed name';
+
+    await producer.send(exchange);
+
+    const content = await readFile(join(dir, 'fixed.txt'), 'utf8');
+    assert.equal(content, 'fixed name');
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('serialises non-string body as JSON', async () => {
+    const dir = makeTmpDir();
+    const producer = new FileProducer(dir, 'data.json');
+    const exchange = new Exchange();
+    exchange.in.body = { key: 'value', n: 42 };
+
+    await producer.send(exchange);
+
+    const content = await readFile(join(dir, 'data.json'), 'utf8');
+    assert.deepEqual(JSON.parse(content), { key: 'value', n: 42 });
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('creates directory if it does not exist', async () => {
+    const dir = join(makeTmpDir(), 'nested', 'path');
+    const producer = new FileProducer(dir, 'out.txt');
+    const exchange = new Exchange();
+    exchange.in.body = 'nested';
+
+    await producer.send(exchange);
+
+    const content = await readFile(join(dir, 'out.txt'), 'utf8');
+    assert.equal(content, 'nested');
+    await rm(join(dir, '..', '..'), { recursive: true, force: true });
+  });
+});
+
+describe('FileConsumer', () => {
+  it('poll() returns one exchange per file with correct body', async () => {
+    const dir = makeTmpDir();
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'a.txt'), 'body-a', 'utf8');
+    await writeFile(join(dir, 'b.txt'), 'body-b', 'utf8');
+    await writeFile(join(dir, 'c.txt'), 'body-c', 'utf8');
+
+    const ctx = new CamelContext();
+    const consumer = new FileConsumer('file:' + dir, ctx, dir, true); // noop=true
+    await consumer.start();
+
+    const exchanges = await consumer.poll();
+    assert.equal(exchanges.length, 3);
+    const bodies = exchanges.map(e => e.in.body).sort();
+    assert.deepEqual(bodies, ['body-a', 'body-b', 'body-c']);
+    exchanges.forEach(e => {
+      assert.ok(e.in.getHeader('CamelFileName'), 'CamelFileName header set');
+      assert.ok(e.in.getHeader('CamelFilePath'), 'CamelFilePath header set');
+    });
+
+    await consumer.stop();
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('poll() moves files to .done/ by default (noop=false)', async () => {
+    const dir = makeTmpDir();
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'move.txt'), 'content', 'utf8');
+
+    const ctx = new CamelContext();
+    const consumer = new FileConsumer('file:' + dir, ctx, dir, false);
+    await consumer.start();
+
+    const exchanges = await consumer.poll();
+    assert.equal(exchanges.length, 1);
+
+    // Original file should be gone
+    await assert.rejects(() => access(join(dir, 'move.txt')));
+    // File should be in .done/
+    const doneContent = await readFile(join(dir, '.done', 'move.txt'), 'utf8');
+    assert.equal(doneContent, 'content');
+
+    await consumer.stop();
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('poll() noop=true: files remain in place', async () => {
+    const dir = makeTmpDir();
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'stay.txt'), 'stays', 'utf8');
+
+    const ctx = new CamelContext();
+    const consumer = new FileConsumer('file:' + dir, ctx, dir, true);
+    await consumer.start();
+
+    await consumer.poll();
+
+    // File should still be there
+    const content = await readFile(join(dir, 'stay.txt'), 'utf8');
+    assert.equal(content, 'stays');
+
+    await consumer.stop();
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('poll() on empty dir returns []', async () => {
+    const dir = makeTmpDir();
+    await mkdir(dir, { recursive: true });
+
+    const ctx = new CamelContext();
+    const consumer = new FileConsumer('file:' + dir, ctx, dir, true);
+    await consumer.start();
+
+    const exchanges = await consumer.poll();
+    assert.equal(exchanges.length, 0);
+
+    await consumer.stop();
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('poll() on non-existent dir returns []', async () => {
+    const dir = makeTmpDir(); // not created
+    const ctx = new CamelContext();
+    const consumer = new FileConsumer('file:' + dir, ctx, dir, true);
+    await consumer.start();
+
+    const exchanges = await consumer.poll();
+    assert.equal(exchanges.length, 0);
+
+    await consumer.stop();
+  });
+});
+
+describe('cross-package import integration', () => {
+  it('FileComponent is a subclass of Component', () => {
+    assert.ok(new FileComponent() instanceof Component);
+  });
+
+  it('FileComponent.createEndpoint returns FileEndpoint', () => {
+    const ctx = new CamelContext();
+    const comp = new FileComponent();
+    const ep = comp.createEndpoint('file:/tmp/test', '/tmp/test', new URLSearchParams(), ctx);
+    assert.ok(ep instanceof FileEndpoint);
+    assert.equal(ep.dir, '/tmp/test');
+  });
+
+  it('FileEndpoint.createProducer returns FileProducer', () => {
+    const ctx = new CamelContext();
+    const ep = new FileEndpoint('file:/tmp', '/tmp', new URLSearchParams(), ctx);
+    assert.ok(ep.createProducer() instanceof FileProducer);
+  });
+
+  it('FileEndpoint.createConsumer returns FileConsumer', () => {
+    const ctx = new CamelContext();
+    const ep = new FileEndpoint('file:/tmp', '/tmp', new URLSearchParams(), ctx);
+    assert.ok(ep.createConsumer(null) instanceof FileConsumer);
+  });
+});