@lazyapps/readmodels 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/readmodels
+
+Event projection and query resolution engine. Core of the read side in the LazyApps CQRS architecture, projecting events into queryable read models.
+
+## Installation
+
+```bash
+pnpm add @lazyapps/readmodels
+```
+
+## Part of LazyApps
+
+This package is part of the [LazyApps](https://github.com/oliversturm/lazyapps-libs) event-sourcing and CQRS framework.

package/changeNotification.js

@@ -0,0 +1,60 @@
+import Queue from 'promise-queue';
+
+import { getLogger } from '@lazyapps/logger';
+
+const createChangeNotificationHandler =
+  (changeNotificationSender) => (correlationId) => {
+    const queue = new Queue(1, Infinity);
+
+    const log = getLogger('RM/Chng', correlationId);
+
+    return {
+      sendChangeNotification: (changeInfo) =>
+        queue.add(() =>
+          new Promise((resolve) => {
+            log.debug(
+              `Sending change notification ${JSON.stringify(changeInfo)}'`,
+            );
+            resolve();
+          })
+            .then(
+              changeNotificationSender.sendChangeNotification(
+                correlationId,
+                changeInfo,
+              ),
+            )
+            .catch((err) => {
+              log.error(
+                `Can't send change notification ${JSON.stringify(
+                  changeInfo,
+                )}: ${err}`,
+              );
+            }),
+        ),
+      createChangeInfo: (
+        endpointName,
+        readModelName,
+        resolverName,
+        changeKind,
+        details,
+      ) => {
+        // I used to check these kinds specifically, but that seems
+        // counter-productive. These kinds might be handled on a
+        // client using standard mechanisms, but it's perfectly fine
+        // to pass any custom name as the changeKind and handle
+        // the details field accordingly.
+        //
+        // if (!['all', 'addRow', 'updateRow', 'deleteRow'].includes(changeKind))
+        //   throw new Error(`Invalid changeKind ${changeKind}`);
+        return {
+          endpointName,
+          readModelName,
+          resolverName,
+          changeKind,
+          details,
+        };
+      },
+    };
+  };
+
+export { createChangeNotificationHandler };

package/commands.js

@@ -0,0 +1,21 @@
+import { getLogger } from '@lazyapps/logger';
+
+const createCommandHandler =
+  ({ commandSender }) =>
+  (correlationId) => {
+    const log = getLogger('RM/Cmd', correlationId);
+    return {
+      // accept the command parameters and then return a promise generator
+      // which will be evaluated lazily depending on replay state
+      execute: (cmd) => () =>
+        new Promise((resolve) => {
+          log.debug(`Executing command ${JSON.stringify(cmd)}`);
+          resolve();
+        })
+          .then(() => commandSender.sendCommand(correlationId, cmd))
+          .catch((err) => {
+            log.error(`Can't execute command ${JSON.stringify(cmd)}: ${err}`);
+          }),
+    };
+  };
+export { createCommandHandler };

package/context.js

@@ -0,0 +1,37 @@
+import { createProjectionHandler } from './projections.js';
+import { createSideEffectsHandler } from './sideEffects.js';
+import { createChangeNotificationHandler } from './changeNotification.js';
+import { createCommandHandler } from './commands.js';
+
+export const initializeContext = (
+  correlationConfig,
+  { readModels, storage, eventBus, changeNotificationSender, commandSender },
+) =>
+  storage()
+    .then((storage) => ({ storage, readModels, correlationConfig }))
+    .then((context) =>
+      context.storage
+        .readLastProjectedEventTimestamps(readModels)
+        .then(() => context),
+    )
+    .then((context) => ({
+      ...context,
+      commands: createCommandHandler({ commandSender }),
+    }))
+    .then((context) =>
+      createSideEffectsHandler().then((sideEffects) => ({
+        ...context,
+        sideEffects,
+      })),
+    )
+    .then((context) => ({
+      ...context,
+      changeNotification: createChangeNotificationHandler(
+        changeNotificationSender,
+      ),
+    }))
+    .then((context) => ({
+      ...context,
+      projectionHandler: createProjectionHandler(context),
+    }))
+    .then((context) => eventBus(context).then(() => context));

package/index.js

@@ -0,0 +1,6 @@
+import { initializeContext } from './context.js';
+
+export const startReadModels = (correlationConfig, config) =>
+  initializeContext(correlationConfig, config).then((context) =>
+    config.listener(context),
+  );

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@lazyapps/readmodels",
+  "version": "0.1.0",
+  "description": "Event projection and query resolution engine for LazyApps",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "*.js"
+  ],
+  "keywords": [
+    "event-sourcing",
+    "cqrs",
+    "lazyapps",
+    "read-models",
+    "projections"
+  ],
+  "author": "Oliver Sturm",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oliversturm/lazyapps-libs.git",
+    "directory": "packages/readmodels"
+  },
+  "bugs": {
+    "url": "https://github.com/oliversturm/lazyapps-libs/issues"
+  },
+  "homepage": "https://github.com/oliversturm/lazyapps-libs/tree/main/packages/readmodels#readme",
+  "engines": {
+    "node": ">=18.20.3 || >=20.18.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.46.0",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "lodash": "^4.17.21",
+    "promise-queue": "^2.2.5",
+    "@lazyapps/logger": "^0.1.0"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "vitest"
+  }
+}

package/projections.js

@@ -0,0 +1,113 @@
+import Queue from 'promise-queue';
+import { getLogger } from '@lazyapps/logger';
+
+const collectProjections = (readModels, event) =>
+  Promise.resolve(
+    Object.keys(readModels)
+      .map((rmName) => {
+        const rm = readModels[rmName];
+        const projection = rm.projections && rm.projections[event.type];
+        if (projection) {
+          return [rmName, projection];
+        } else return null;
+      })
+      .filter((el) => !!el)
+      .filter(([, f]) => !!f),
+  );
+
+const logProjections = (log, inReplay) => (rmProjections) => {
+  if (rmProjections.length)
+    log.debug(
+      `Projecting event for read models: ${JSON.stringify(
+        rmProjections.map(([rmName]) => rmName),
+      )} (inReplay=${inReplay})`,
+    );
+  return rmProjections;
+};
+
+const updateInternalReadModelTimestamps =
+  (event, readModels) => (rmProjections) =>
+    Promise.all(
+      rmProjections.map(([rmName]) => {
+        readModels[rmName].lastProjectedEventTimestamp = event.timestamp;
+      }),
+    ).then(() => rmProjections);
+
+const updateTimestamp = (correlationId, storage, rmName, timestamp) =>
+  storage.updateLastProjectedEventTimestamps(
+    correlationId,
+    [rmName],
+    timestamp,
+  );
+
+const handleProjections =
+  (correlationId, log, context, getProjectionContext, inReplay, event) =>
+  (rmProjections) =>
+    Promise.all(
+      rmProjections.map(([rmName, f]) =>
+        f(getProjectionContext(correlationId)(rmName)(inReplay), event)
+          .then(() =>
+            updateTimestamp(
+              correlationId,
+              context.storage,
+              rmName,
+              event.timestamp,
+            ),
+          )
+          .catch((err) => {
+            log.error(
+              `Error occurred projecting event ${JSON.stringify(
+                event,
+              )} for read model ${rmName}, or during read model timestamp update: ${err}`,
+            );
+          }),
+      ),
+    );
+
+const projectEvent =
+  (context, eventQueue, getProjectionContext) => (correlationId) => {
+    const log = getLogger(`RM/ProjEv`, correlationId);
+    return (event, inReplay) =>
+      eventQueue.add(() =>
+        collectProjections(context.readModels, event)
+          .then(logProjections(log, inReplay))
+          .then(updateInternalReadModelTimestamps(event, context.readModels))
+          .then(
+            handleProjections(
+              correlationId,
+              log,
+              context,
+              getProjectionContext,
+              inReplay,
+              event,
+            ),
+          ),
+      );
+  };
+
+export const createProjectionHandler = (context) => {
+  const eventQueue = new Queue(1, Infinity);
+  const getProjectionContext = (correlationId) => (rmName) => (inReplay) => ({
+    storage: context.storage.perRequest(correlationId),
+    commands: context.commands(correlationId),
+    changeNotification: context.changeNotification(correlationId),
+    log: getLogger(`RM/${rmName}`, correlationId),
+    sideEffects: context.sideEffects.getSideEffectsHandler(
+      correlationId,
+      inReplay,
+    ),
+  });
+
+  return {
+    projectEvent: projectEvent(context, eventQueue, getProjectionContext),
+  };
+};
+
+export const testing = {
+  collectProjections,
+  logProjections,
+  updateInternalReadModelTimestamps,
+  updateTimestamp,
+  handleProjections,
+  projectEvent,
+};

package/sideEffects.js

@@ -0,0 +1,53 @@
+import Queue from 'promise-queue';
+import { getLogger } from '@lazyapps/logger';
+
+const createSideEffectsHandler = () => {
+  const queue = new Queue(1, Infinity);
+
+  const schedule =
+    (correlationId, inReplay) =>
+    (promiseGenerator, options = {}) => {
+      const defaultOptions = { name: 'unnamed', execution: 'liveOnly' };
+      const actualOptions = { ...defaultOptions, ...options };
+
+      const log = getLogger('ReadMod/Side', correlationId);
+      return (inReplay &&
+        ['replayOnly', 'always'].includes(actualOptions.execution)) ||
+        (!inReplay && ['liveOnly', 'always'].includes(actualOptions.execution))
+        ? queue.add(() =>
+            new Promise((resolve) => {
+              log.debug(
+                `Running side-effect '${actualOptions.name}' (inReplay=${inReplay}, execution=${actualOptions.execution})`,
+              );
+              resolve();
+            })
+              .then(promiseGenerator())
+              .then(
+                () =>
+                  new Promise((resolve) => {
+                    log.debug(`Side-effect '${actualOptions.name}' done`);
+                    resolve();
+                  }),
+              )
+              .catch((err) => {
+                log.error(
+                  `Can't execute side-effect '${actualOptions.name}': ${err}`,
+                );
+              }),
+          )
+        : new Promise((resolve) => {
+            log.debug(
+              `Skipping side-effect '${actualOptions.name} (inReplay=${inReplay}, execution=${actualOptions.execution})`,
+            );
+            resolve();
+          });
+    };
+
+  return Promise.resolve({
+    getSideEffectsHandler: (correlationId, inReplay) => ({
+      schedule: schedule(correlationId, inReplay),
+    }),
+  });
+};
+
+export { createSideEffectsHandler };

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;
+  }
+}