@lazyapps/command-processor 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Oliver Sturm
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @lazyapps/command-processor
+
+Transport-agnostic command validation and aggregate execution engine. Core of the write side in the LazyApps CQRS architecture.
+
+## Installation
+
+```bash
+pnpm add @lazyapps/command-processor
+```
+
+## Part of LazyApps
+
+This package is part of the [LazyApps](https://github.com/oliversturm/lazyapps-libs) event-sourcing and CQRS framework.

package/commandRecorder.js

@@ -0,0 +1,71 @@
+import { createWriteStream, fsyncSync } from 'fs';
+import { getLogger } from '@lazyapps/logger';
+
+const initLog = getLogger('CP/CmdRec', 'INIT');
+
+export const createCommandRecorder = (filePath) => {
+  initLog.info(`Setting up command recording to ${filePath}`);
+
+  const writeStream = createWriteStream(filePath, {
+    flags: 'a',
+    encoding: 'utf8',
+    // Set to false to ensure we control when data is flushed
+    autoClose: false,
+  });
+
+  // Handle stream errors
+  writeStream.on('error', (error) => {
+    initLog.error(`Error writing to command record file: ${error}`);
+  });
+
+  const recordCommand = (commandRecord) => {
+    return new Promise((resolve, reject) => {
+      const log = getLogger('CP/CmdRec', commandRecord.correlationId);
+      writeStream.write(JSON.stringify(commandRecord) + '\n', (error) => {
+        if (error) {
+          log.error(
+            `Failed to record command ${commandRecord.command}: ${error}`,
+          );
+          reject(error);
+          return;
+        }
+
+        // Force flush to disk
+        try {
+          writeStream.fd && fsyncSync(writeStream.fd);
+          log.debug(`Recorded command ${commandRecord.command}.`);
+          resolve(commandRecord);
+        } catch (error) {
+          log.error(
+            `Failed to flush command ${commandRecord.command}: ${error}`,
+          );
+          reject(error);
+        }
+      });
+    });
+  };
+
+  // Add cleanup method
+  const close = () => {
+    return new Promise((resolve, reject) => {
+      // Ensure final flush before closing
+      try {
+        writeStream.fd && fsyncSync(writeStream.fd);
+      } catch (error) {
+        initLog.error(`Error flushing final data: ${error}`);
+      }
+
+      writeStream.end((error) => {
+        if (error) {
+          initLog.error(`Error closing command record file: ${error}`);
+          reject(error);
+        } else {
+          initLog.info('Command recorder closed');
+          resolve();
+        }
+      });
+    });
+  };
+
+  return { recordCommand, close };
+};

package/context.js

@@ -0,0 +1,25 @@
+export const initializeContext = (
+  correlationConfig,
+  { aggregateStore, eventStore, eventBus, aggregates },
+  handleCommand,
+  handleAdminCommand,
+) =>
+  Promise.all([aggregateStore(aggregates), eventStore()])
+    .then(([aggregateStore, eventStore]) => ({
+      aggregates,
+      aggregateStore,
+      eventStore,
+      handleCommand,
+      handleAdminCommand,
+      correlationConfig,
+    }))
+    .then((context) =>
+      eventBus().then((eventBus) => ({ ...context, eventBus })),
+    )
+    // We run a full replay on startup, to get all aggregates
+    // up and running. Not a great idea for production.
+    .then((context) =>
+      context.eventStore
+        .replay('INIT' /*correlationId*/)(context)
+        .then(() => context),
+    );

package/handleAdminCommand.js

@@ -0,0 +1,33 @@
+import { getLogger } from '@lazyapps/logger';
+
+export const handleAdminCommand =
+  (skipAuthCheck = false) =>
+  (context, command, params, auth, correlationId) => {
+    const log = getLogger('CP/AdHandler', correlationId);
+    // Not very flexible this check, but we'll live with it for now
+    if (!skipAuthCheck && (!auth || !auth.admin)) {
+      log.error(`Unauthorized ${auth}`);
+      return Promise.reject(new Error(`Unauthorized ${auth}`));
+    }
+
+    if (command !== 'setReplayState') {
+      log.error(`Invalid admin command ${command}`);
+      return Promise.reject(new Error(`Invalid admin command ${command}`));
+    }
+
+    if (!params || typeof params.state !== 'boolean') {
+      log.error(`Invalid replay state ${params.state}`);
+      return Promise.reject(new Error(`Invalid replay state ${params.state}`));
+    }
+
+    const { eventBus } = context;
+    if (!eventBus) {
+      log.error(`Event bus not found`);
+      return Promise.reject(new Error(`Event bus not found`));
+    }
+
+    // Trying to remember why, but this call is synchronous
+    return new Promise((resolve) => {
+      resolve(eventBus.publishReplayState(correlationId)(params.state));
+    });
+  };

package/handleCommand.js

@@ -0,0 +1,61 @@
+import { getLogger } from '@lazyapps/logger';
+
+// We can receive an external timestamp, in case that gives
+// better accuracy. If we don't receive one here, we'll
+// record our own as soon as we can.
+export const handleCommand = (
+  aggregateStore,
+  eventStore,
+  eventBus,
+  command,
+  aggregateName,
+  aggregateId,
+  payload,
+  commandHandler,
+  auth,
+  timestamp = null,
+  correlationId,
+  commandRecorder = null,
+) =>
+  Promise.resolve(timestamp || Date.now())
+    .then((timestamp) => {
+      // If command recording is enabled, record the command first
+      if (commandRecorder) {
+        return commandRecorder
+          .recordCommand({
+            command,
+            aggregateName,
+            aggregateId,
+            payload,
+            auth,
+            timestamp,
+            correlationId,
+          })
+          .then(() => timestamp);
+      }
+      return timestamp;
+    })
+    .then((timestamp) =>
+      Promise.resolve(
+        aggregateStore.getAggregateState(aggregateName, aggregateId),
+      )
+        .then((aggregateState) => commandHandler(aggregateState, payload, auth))
+        .then((eventMixin) => {
+          if (!eventMixin.type)
+            throw new Error(
+              `[${correlationId}] Event created for command ${command} on aggregate ${aggregateName}(${aggregateId}) has no 'type'`,
+            );
+          const event = {
+            ...eventMixin,
+            timestamp,
+            aggregateName,
+            aggregateId,
+          };
+          const log = getLogger('CP/Handler', correlationId);
+          log.debug(`Event generated: ${JSON.stringify(event)}`);
+          return event;
+        })
+        .then(eventStore.addEvent(correlationId))
+        .then(aggregateStore.applyAggregateProjection(correlationId))
+        .then(eventBus.publishEvent(correlationId)),
+    );

package/index.js

@@ -0,0 +1,19 @@
+import { initializeContext } from './context.js';
+import { handleCommand } from './handleCommand.js';
+import { createCommandRecorder } from './commandRecorder.js';
+import { handleAdminCommand } from './handleAdminCommand.js';
+
+export const startCommandProcessor = (correlationConfig, config) => {
+  const commandRecorder = config.commandRecording?.enabled
+    ? createCommandRecorder(config.commandRecording.filePath)
+    : null;
+
+  return initializeContext(
+    correlationConfig,
+    config,
+    (...args) => handleCommand(...args, commandRecorder),
+    config.commandRecording
+      ? handleAdminCommand(config.commandRecording.skipAuthCheck)
+      : null,
+  ).then((context) => config.receiver(context));
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@lazyapps/command-processor",
+  "version": "0.1.0",
+  "description": "Transport-agnostic command validation and aggregate execution engine for LazyApps",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "*.js"
+  ],
+  "keywords": [
+    "event-sourcing",
+    "cqrs",
+    "lazyapps",
+    "command-processing",
+    "aggregates"
+  ],
+  "author": "Oliver Sturm",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oliversturm/lazyapps-libs.git",
+    "directory": "packages/command-processor"
+  },
+  "bugs": {
+    "url": "https://github.com/oliversturm/lazyapps-libs/issues"
+  },
+  "homepage": "https://github.com/oliversturm/lazyapps-libs/tree/main/packages/command-processor#readme",
+  "engines": {
+    "node": ">=18.20.3 || >=20.18.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.46.0",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "nanoid": "^5.0.7",
+    "@lazyapps/aggregatestore-inmemory": "^0.1.0",
+    "@lazyapps/eventbus-mqemitter-redis": "^0.1.0",
+    "@lazyapps/eventstore-mongodb": "^0.1.0",
+    "@lazyapps/logger": "^0.1.0"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "vitest"
+  }
+}

package/validation.js

@@ -0,0 +1,13 @@
+export class ValidationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+export class AuthorizationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}