@lazyapps/express 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/express
+
+Express HTTP bindings for LazyApps. Provides HTTP command receiver endpoints, read model query endpoints, and change notification listener functionality.
+
+## Installation
+
+```bash
+pnpm add @lazyapps/express
+```
+
+## Part of LazyApps
+
+This package is part of the [LazyApps](https://github.com/oliversturm/lazyapps-libs) event-sourcing and CQRS framework.

package/command-receiver/admin-handler.js

@@ -0,0 +1,32 @@
+import { getLogger } from '@lazyapps/logger';
+
+export const adminHandler = (context) => (req, res) => {
+  const { correlationId } = req.body;
+  const log = getLogger('EX/CP/AdHandler', correlationId);
+
+  const { command } = req.params;
+  const handler = context.handleAdminCommand;
+  if (!handler) {
+    log.error(`Invalid admin command ${command}`);
+    res.sendStatus(400).send('Invalid admin command');
+    return;
+  }
+
+  log.debug(
+    `Admin command ${command} with params ${JSON.stringify(req.body.params)}`,
+  );
+  return handler(
+    context,
+    command,
+    req.body.params,
+    req.auth,
+    req.body.correlationId,
+  )
+    .then(() => {
+      res.sendStatus(200);
+    })
+    .catch((err) => {
+      log.error(`Error: ${err}`);
+      res.sendStatus(500);
+    });
+};

package/command-receiver/command-api-handler.js

@@ -0,0 +1,78 @@
+import { getLogger } from '@lazyapps/logger';
+
+export const createApiHandler =
+  ({ aggregateStore, eventStore, eventBus, aggregates, handleCommand }) =>
+  (req, res) => {
+    // Record timestamp as early as possible
+    const reqTimestamp = Date.now();
+
+    const { command, aggregateName, aggregateId, payload, correlationId } =
+      req.body;
+    const log = getLogger('EX/CP/Handler', correlationId);
+    log.debug(
+      `Command received: ${JSON.stringify({
+        command,
+        aggregateName,
+        aggregateId,
+        payload,
+      })}`,
+    );
+    const auth = req.auth;
+    if (!command || !aggregateName || !aggregateId) {
+      res.status(400).send('Missing field');
+      return;
+    }
+
+    const aggregate = aggregates[aggregateName];
+    if (!aggregate) {
+      res.status(400).send('Invalid aggregate name');
+      return;
+    }
+
+    const commandHandler = aggregate.commands && aggregate.commands[command];
+    if (!commandHandler) {
+      res.status(400).send('Invalid command name');
+      return;
+    }
+
+    return handleCommand(
+      aggregateStore,
+      eventStore,
+      eventBus,
+      command,
+      aggregateName,
+      aggregateId,
+      payload,
+      commandHandler,
+      auth,
+      reqTimestamp,
+      correlationId,
+    )
+      .then(() => {
+        res.sendStatus(200);
+      })
+      .catch((err) => {
+        if (err.name === 'ValidationError') {
+          log.error(`Validation error while handling command ${command} for aggregate ${aggregateName}(${aggregateId}) with payload:
+
+          ${JSON.stringify(payload)}
+                
+          ${err}`);
+          res.sendStatus(400);
+        } else if (err.name === 'AuthorizationError') {
+          log.error(`Unauthorized while handling command ${command} for aggregate ${aggregateName}(${aggregateId}) with payload:
+
+          ${JSON.stringify(payload)}
+                
+          ${err}`);
+          res.sendStatus(403);
+        } else {
+          log.error(`Unknown error handling command ${command} for aggregate ${aggregateName}(${aggregateId}) with payload:
+
+${JSON.stringify(payload)}
+      
+${err}`);
+          res.sendStatus(500);
+        }
+      });
+  };

package/command-receiver/index.js

@@ -0,0 +1,17 @@
+import { createApiHandler } from './command-api-handler.js';
+import { runExpress } from '../runExpress.js';
+import { getLogger } from '@lazyapps/logger';
+import { adminHandler } from './admin-handler.js';
+
+const log = getLogger('EX/CP/HTTP', 'INIT');
+
+const installHandlers = (context, app) => {
+  const processCommand = createApiHandler(context);
+  app.post('/api/command', processCommand);
+
+  // an admin post route for /api/admin/<command>
+  app.post('/api/admin/:command', adminHandler(context));
+};
+
+export const express = (externalConfig) =>
+  runExpress({ log, installHandlers, ...externalConfig });

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@lazyapps/express",
+  "version": "0.1.0",
+  "description": "Express HTTP bindings for LazyApps command receiver, read model queries, and change notification listener",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./command-receiver": "./command-receiver/index.js",
+    "./command-receiver/index.js": "./command-receiver/index.js",
+    "./readmodels": "./readmodels/index.js",
+    "./readmodels/index.js": "./readmodels/index.js"
+  },
+  "files": [
+    "*.js",
+    "command-receiver/",
+    "readmodels/"
+  ],
+  "keywords": [
+    "event-sourcing",
+    "cqrs",
+    "lazyapps",
+    "express",
+    "http"
+  ],
+  "author": "Oliver Sturm",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oliversturm/lazyapps-libs.git",
+    "directory": "packages/express"
+  },
+  "bugs": {
+    "url": "https://github.com/oliversturm/lazyapps-libs/issues"
+  },
+  "homepage": "https://github.com/oliversturm/lazyapps-libs/tree/main/packages/express#readme",
+  "engines": {
+    "node": ">=18.20.3 || >=20.18.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.46.0",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "body-parser": "^1.20.2",
+    "cookie-parser": "^1.4.6",
+    "cors": "^2.8.5",
+    "express": "^4.18.2",
+    "express-jwt": "^8.4.1",
+    "morgan": "^1.10.0",
+    "nanoid": "^5.0.7",
+    "@lazyapps/logger": "^0.1.0"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "vitest"
+  }
+}

package/readmodels/index.js

@@ -0,0 +1,28 @@
+import { getLogger } from '@lazyapps/logger';
+import { createApiHandler } from './query.js';
+import { runExpress } from '../runExpress.js';
+
+const log = getLogger('EX/RM/HTTP', 'INIT');
+
+const installHandlers = (context, app) => {
+  const executeQuery = createApiHandler(context);
+  for (const readModelName in context.readModels) {
+    const readModel = context.readModels[readModelName];
+    if (readModel.resolvers) {
+      for (const resolverName in readModel.resolvers) {
+        const resolver = readModel.resolvers[resolverName];
+        const handler = executeQuery(
+          readModelName,
+          readModel,
+          resolverName,
+          resolver,
+        );
+        app.post(`/query/${readModelName}/${resolverName}`, handler);
+        app.get(`/query/${readModelName}/${resolverName}`, handler);
+      }
+    }
+  }
+};
+
+export const express = (externalConfig) =>
+  runExpress({ log, installHandlers, ...externalConfig });

package/readmodels/query.js

@@ -0,0 +1,33 @@
+import { getLogger } from '@lazyapps/logger';
+
+export const createApiHandler =
+  (context) =>
+  (readModelName, readModel, resolverName, resolver) =>
+  (req, res) => {
+    const log = getLogger('RM/Query', req.body.correlationId);
+
+    log.debug(
+      `Query received for ${readModelName}/${resolverName} with args ${JSON.stringify(
+        req.body,
+      )}`,
+    );
+    return Promise.resolve(
+      resolver(
+        context.storage.perRequest(req.body.correlationId),
+        req.body,
+        req.auth,
+        req.body.correlationId,
+      ),
+    )
+      .then((result) => {
+        res.status(200).json(result);
+      })
+      .catch((err) => {
+        log.error(
+          `An error occurred handling query for ${readModelName}/${resolverName} with args ${JSON.stringify(
+            req.body,
+          )}: ${err}`,
+        );
+        res.sendStatus(500);
+      });
+  };

package/runExpress.js

@@ -0,0 +1,120 @@
+import expressApp from 'express';
+import bodyParser from 'body-parser';
+import morgan from 'morgan';
+import cors from 'cors';
+import cookieParser from 'cookie-parser';
+import { expressjwt } from 'express-jwt';
+import { getLogger, getStream } from '@lazyapps/logger';
+import { nanoid } from 'nanoid';
+
+const correlationId = (correlationConfig) => (req, res, next) => {
+  // check where a correlation Id might already exist
+  const existingId = req.body.correlationId || req.headers['x-correlation-id'];
+
+  // since we want to use it in code, make sure the body
+  // now has an id in any case
+  req.body.correlationId =
+    existingId || `${correlationConfig?.serviceId || 'UNK'}-${nanoid()}`;
+
+  // also in the result, not needed right now but can't hurt
+  // for debugging
+  res.setHeader('X-Correlation-ID', req.body.correlationId);
+  next();
+};
+
+morgan.token('correlation-id', function (req) {
+  return req.body.correlationId;
+});
+
+export const runExpress =
+  ({
+    log,
+    port,
+    interfaceIp,
+    installHandlers,
+    jwtSecret,
+    authCookieName,
+    credentialsRequired,
+    customizeExpress = () => {},
+  }) =>
+  (context) => {
+    return new Promise((resolve, reject) => {
+      const app = expressApp();
+      app.use(cors());
+      app.use(bodyParser.json());
+      app.use(correlationId(context.correlationConfig));
+      app.use(
+        morgan(
+          '[:correlation-id] :method :url :status :response-time ms - :res[content-length]',
+          { stream: getStream(log.debugBare) },
+        ),
+      );
+      app.use(cookieParser());
+
+      if (jwtSecret) {
+        app.use(
+          expressjwt({
+            secret: jwtSecret,
+            algorithms: ['HS256'],
+            credentialsRequired: credentialsRequired || false,
+            getToken: (req) => {
+              const tokenLog = getLogger('Tokens/GetT', req.body.correlationId);
+              if (
+                req.headers.authorization &&
+                req.headers.authorization.split(' ')[0] === 'Bearer'
+              ) {
+                tokenLog.debug('Using Authorization header');
+                return req.headers.authorization.split(' ')[1];
+              }
+              if (authCookieName) {
+                const token = req.cookies[authCookieName || 'access_token'];
+                if (token) {
+                  tokenLog.debug('Using cookie');
+                  return token;
+                }
+              }
+              tokenLog.debug('No token found');
+              return null;
+            },
+          }),
+        );
+      }
+
+      installHandlers(context, app);
+
+      customizeExpress(context, app);
+
+      // Handle JWT authentication errors
+      app.use((err, req, res, next) => {
+        if (err.name === 'UnauthorizedError') {
+          res.clearCookie(authCookieName || 'access_token', {
+            httpOnly: true,
+            sameSite: 'strict',
+          });
+          res.status(401).json({
+            error: 'Token expired or invalid',
+            code: 'token_expired',
+          });
+        } else {
+          next(err);
+        }
+      });
+
+      const server = app.listen(port, interfaceIp || '0.0.0.0');
+
+      server.on('error', (err) => {
+        log.error(`Server error: ${err}`);
+        reject(err);
+      });
+
+      server.on('listening', () => {
+        const addr = server.address();
+        log.info(
+          `Server listening on ${addr.address}:${addr.port}, ${
+            jwtSecret ? 'with JWT' : 'without JWT'
+          }`,
+        );
+        resolve(server);
+      });
+    });
+  };