tapeworm 0.5.0 → 0.6.0

package/scripts/postbuild.js

@@ -0,0 +1,27 @@
+// Append CJS backward-compatibility shim to compiled ESM output.
+//
+// Without this, `require('tapeworm')` returns `{ default: EventStore, ... }`
+// instead of the EventStore constructor directly. The shim restores the
+// legacy behavior: `const EventStore = require('tapeworm')` works, and
+// named exports like `require('tapeworm').Commit` remain accessible because
+// EventStore already carries them as own properties (set in event_store.ts).
+//
+// This runs as a postbuild step so the source stays pure ESM (no
+// `module.exports` that would conflict with Vite/vitest).
+
+const fs = require("fs");
+const path = require("path");
+
+const file = path.join(__dirname, "..", "dist", "index.js");
+const src = fs.readFileSync(file, "utf8");
+
+const shim = [
+  "",
+  "// CJS backward compat — added by scripts/postbuild.js",
+  "module.exports = exports.default;",
+  "Object.assign(module.exports, exports);",
+  "module.exports.default = exports.default;",
+  "",
+].join("\n");
+
+fs.writeFileSync(file, src + shim);

package/src/dispatch/dispatch_service.ts

@@ -0,0 +1,14 @@
+import type { ICommit, NodeCallback } from "../types";
+
+interface IDispatchService {
+  dispatch(_commit: ICommit, _callback?: NodeCallback<void>): void;
+}
+
+/** Abstract template — subclasses must override dispatch. */
+var DispatchService = function () {} as unknown as new () => IDispatchService;
+
+DispatchService.prototype.dispatch = function (_commit: ICommit, _callback?: NodeCallback<void>) {
+  // body...
+};
+
+export default DispatchService;

package/src/event.ts

@@ -0,0 +1,24 @@
+import type { IBaseEvent } from "./types";
+
+interface IEvent extends IBaseEvent {
+  payload: Record<string, unknown>;
+  timestamp: Date;
+  metadata: Record<string, unknown>;
+  revision: number | null;
+}
+
+var Event = function (this: IEvent, id: string, type: string, payload: Record<string, unknown>, metadata?: Record<string, unknown>) {
+  this.id = id;
+  this.type = type;
+  this.payload = payload;
+  this.timestamp = new Date();
+  this.metadata = metadata || {};
+  this.revision = null; //filled by eventstore on append
+} as unknown as new (
+  id: string,
+  type: string,
+  payload: Record<string, unknown>,
+  metadata?: Record<string, unknown>
+) => IEvent;
+
+export default Event;

package/src/event_store.ts

@@ -0,0 +1,82 @@
+import Promise from "bluebird";
+import Event from "./event";
+import Partition from "./event_store_partition";
+import EventStream from "./event_stream";
+import Commit from "./persistence/commit";
+import ConcurrencyError from "./persistence/concurrency_error";
+import DuplicateCommitError from "./persistence/duplicate_commit_error";
+import InMemoryPersistenceStore from "./persistence/inmemory/inmemory_persistence";
+import type { DispatchHandler, IPersistencePartition, IPersistenceProvider, NodeCallback } from "./types";
+
+type PartitionInstance = InstanceType<typeof Partition>;
+
+var _PENDING: Record<string, never> = {};
+
+interface IEventStore {
+  _store: IPersistenceProvider;
+  _dispatchService?: DispatchHandler;
+  _partitions: Record<string, PartitionInstance | typeof _PENDING>;
+  openPartition(partitionId?: string, callback?: NodeCallback<PartitionInstance>): Promise<PartitionInstance>;
+}
+
+var EventStore = function (this: IEventStore, persistenceStore?: IPersistenceProvider, dispatchService?: DispatchHandler) {
+  this._store = persistenceStore || new InMemoryPersistenceStore();
+  this._dispatchService = dispatchService;
+  this._partitions = {};
+} as unknown as {
+  new (persistenceStore?: IPersistenceProvider, dispatchService?: DispatchHandler): IEventStore;
+  Event: typeof Event;
+  EventStream: typeof EventStream;
+  EventStorePartition: typeof Partition;
+  Commit: typeof Commit;
+  ConcurrencyError: typeof ConcurrencyError;
+  DuplicateCommitError: typeof DuplicateCommitError;
+};
+
+EventStore.prototype.openPartition = function (this: IEventStore, partitionId?: string, callback?: NodeCallback<PartitionInstance>) {
+  var partition: PartitionInstance | typeof _PENDING | null = null;
+  var pid = partitionId || "master";
+  partition = this._partitions[pid];
+  var self = this;
+  if (!partition) {
+    this._partitions[pid] = _PENDING;
+    return this._store
+      .openPartition(pid)
+      .then(function (persistencePartition: IPersistencePartition) {
+        var p = new Partition(pid, persistencePartition, self._dispatchService);
+        return (self._partitions[pid] = p);
+      })
+      .nodeify(callback);
+  } else {
+    //_PENDING is set when the partition is loading, wait 5ms at a time to see if it has been loaded
+    if (this._partitions[pid] === _PENDING) {
+      var promise = new Promise<PartitionInstance>(function (resolve) {
+        var resolver = function () {
+          var partition = self._partitions[pid];
+          if (partition === _PENDING) {
+            setTimeout(resolver, 5);
+          } else {
+            resolve(partition as PartitionInstance);
+          }
+        };
+        resolver();
+      });
+      return promise.nodeify(callback);
+    } else {
+      return Promise.resolve(this._partitions[pid] as PartitionInstance).nodeify(callback);
+    }
+  }
+};
+
+EventStore.Event = Event;
+EventStore.EventStream = EventStream;
+EventStore.EventStorePartition = Partition;
+EventStore.Commit = Commit;
+EventStore.ConcurrencyError = ConcurrencyError;
+EventStore.DuplicateCommitError = DuplicateCommitError;
+
+export default EventStore;
+
+// Named exports for destructured imports: import EventStore, { Event, Commit } from 'tapeworm'
+export { Event, EventStream, Commit, ConcurrencyError, DuplicateCommitError };
+export { Partition as EventStorePartition };

package/src/event_store_partition.ts

@@ -0,0 +1,270 @@
+import Promise from "bluebird";
+import _ from "lodash";
+import { v4 as uuid } from "uuid";
+import EventStream from "./event_stream";
+import type {
+  DispatchHandler,
+  IBaseEvent,
+  ICommit,
+  IPersistencePartition,
+  ISnapshot,
+  NodeCallback,
+} from "./types";
+
+type EventStreamInstance = InstanceType<typeof EventStream>;
+
+interface IEventStorePartition {
+  _partitionId: string;
+  _persistencePartition: IPersistencePartition;
+  _dispatchService?: DispatchHandler;
+  openStream(
+    streamId: string,
+    writeOnly?: boolean | NodeCallback<EventStreamInstance>,
+    callback?: NodeCallback<EventStreamInstance>,
+  ): Promise<EventStreamInstance>;
+  append(
+    commits: ICommit | ICommit[],
+    callback?: NodeCallback<unknown>,
+  ): Promise<ICommit[]>;
+  delete(
+    streamId: string,
+    deleteEvent?: Record<string, unknown>,
+  ): Promise<void>;
+  _queryStream(
+    streamId: string,
+    callback?: NodeCallback<ICommit[]>,
+  ): Promise<ICommit[]>;
+  _queryAll(callback?: NodeCallback<ICommit[]>): Promise<ICommit[]>;
+  _queryStreamWithSnapshotFallback(
+    streamId: string,
+    callback?: NodeCallback<unknown>,
+  ): Promise<unknown>;
+  _truncateStreamFrom(
+    streamId: string,
+    commitSequence: number,
+    callback?: NodeCallback<void>,
+  ): Promise<void>;
+  _applyCommitHeader(
+    commitId: string,
+    header: Record<string, unknown>,
+    callback?: NodeCallback<ICommit>,
+  ): Promise<ICommit>;
+  // Dynamically delegated methods — may or may not exist at runtime
+  storeSnapshot?: IPersistencePartition["storeSnapshot"];
+  loadSnapshot?: IPersistencePartition["loadSnapshot"];
+  queryStream?: IPersistencePartition["queryStream"];
+  queryStreamWithSnapshot?: IPersistencePartition["queryStreamWithSnapshot"];
+  removeSnapshot?: IPersistencePartition["removeSnapshot"];
+  getLatestCommit?: IPersistencePartition["getLatestCommit"];
+  querySnapshotsByMaxDateTime?: IPersistencePartition["querySnapshotsByMaxDateTime"];
+  [key: string]: unknown;
+}
+
+var EventStorePartition = function (
+  this: IEventStorePartition,
+  partitionId: string,
+  persistencePartition: IPersistencePartition,
+  dispatchService?: DispatchHandler,
+) {
+  this._partitionId = partitionId;
+  this._persistencePartition = persistencePartition;
+  this._dispatchService = dispatchService;
+
+  var self = this;
+  _.forEach(
+    [
+      "storeSnapshot",
+      "loadSnapshot",
+      "queryStream",
+      "queryStreamWithSnapshot",
+      "removeSnapshot",
+      "getLatestCommit",
+      "querySnapshotsByMaxDateTime",
+    ] as const,
+    function (what: string) {
+      // biome-ignore lint/complexity/noBannedTypes: dynamic method delegation requires generic function type
+      var pp = self._persistencePartition as unknown as Record<
+        string,
+        Function
+      >;
+      if (pp[what]) {
+        self[what] = function () {
+          return pp[what].apply(self._persistencePartition, arguments);
+        };
+      } else {
+        if (what === "queryStreamWithSnapshot") {
+          // fallback function
+          self[what] = function () {
+            return self._queryStreamWithSnapshotFallback.apply(
+              self._persistencePartition,
+              arguments as unknown as [string, NodeCallback<unknown>?],
+            );
+          };
+        }
+      }
+    },
+  );
+} as unknown as new (
+  partitionId: string,
+  persistencePartition: IPersistencePartition,
+  dispatchService?: DispatchHandler,
+) => IEventStorePartition;
+
+EventStorePartition.prototype.openStream = function (
+  this: IEventStorePartition,
+  streamId: string,
+  writeOnly?: boolean | NodeCallback<EventStreamInstance>,
+  callback?: NodeCallback<EventStreamInstance>,
+) {
+  if (typeof writeOnly === "function") {
+    callback = writeOnly;
+    writeOnly = false;
+  }
+  var stream = new EventStream(
+    this as unknown as ConstructorParameters<typeof EventStream>[0],
+    streamId,
+    writeOnly as boolean,
+  );
+  return stream._prepareStream(callback);
+};
+
+EventStorePartition.prototype.append = function (
+  this: IEventStorePartition,
+  commits: ICommit | ICommit[],
+  callback?: NodeCallback<unknown>,
+) {
+  //pre hooks
+  var self = this;
+
+  if (!_.isArray(commits)) {
+    commits = [commits];
+  }
+  return Promise.each(commits, function (commit: ICommit) {
+    return self._persistencePartition
+      .append(commit, callback as NodeCallback<ICommit>)
+      .then(function (r: ICommit) {
+        var done = function () {
+          self._persistencePartition.markAsDispatched(commit);
+        };
+        if (self._dispatchService) {
+          self._dispatchService(commit, done);
+        }
+        return r;
+      });
+  });
+  //post hooks
+};
+
+/**
+ * Delete function in tapeworm.
+ * Triggers a $stream.deleted.event, truncates the stream, and removes snapshots.
+ */
+EventStorePartition.prototype.delete = function (
+  this: IEventStorePartition,
+  streamId: string,
+  deleteEvent?: Record<string, unknown>,
+) {
+  var self = this;
+  var event = Object.assign({}, deleteEvent, {
+    id: uuid(),
+    type: "$stream.deleted.event",
+    payload: Object.assign(
+      {},
+      { dateOfDeletion: new Date() },
+      (deleteEvent && (deleteEvent.payload as Record<string, unknown>)) || {},
+    ),
+  });
+  return this._truncateStreamFrom(streamId, -1)
+    .then(function () {
+      return self.openStream(streamId, false);
+    })
+    .then(function (stream: EventStreamInstance) {
+      stream.append(event as IBaseEvent);
+      return stream.commit(uuid());
+    })
+    .then(function () {
+      // support legacy/unsupported approach
+      if (self._persistencePartition.removeSnapshot) {
+        return self._persistencePartition.removeSnapshot(streamId);
+      } else if (self._persistencePartition.removeSnapshots) {
+        return self._persistencePartition.removeSnapshots([streamId]);
+      }
+    });
+};
+
+/*** UNDOCUMENTED API ***/
+
+EventStorePartition.prototype._queryStream = function (
+  this: IEventStorePartition,
+  streamId: string,
+  callback?: NodeCallback<ICommit[]>,
+) {
+  return this._persistencePartition.queryStream(streamId, callback);
+};
+
+EventStorePartition.prototype._queryAll = function (
+  this: IEventStorePartition,
+  callback?: NodeCallback<ICommit[]>,
+) {
+  return this._persistencePartition.queryAll(callback);
+};
+
+EventStorePartition.prototype._queryStreamWithSnapshotFallback = function (
+  this: IPersistencePartition,
+  streamId: string,
+  callback?: NodeCallback<unknown>,
+) {
+  var self = this;
+  return new Promise(function (
+    resolve: (value: unknown) => void,
+    reject: (reason: Error) => void,
+  ) {
+    self.loadSnapshot?.(
+      streamId,
+      function (err: Error | null, snapshot?: ISnapshot) {
+        if (err) {
+          reject(err);
+        } else {
+          var snapshotVersion = (snapshot && snapshot.version) || -1;
+          self.queryStream(
+            streamId,
+            snapshotVersion,
+            function (_err: Error | null, res?: ICommit[]) {
+              resolve({ snapshot: snapshot, commits: res });
+            },
+          );
+        }
+      },
+    );
+  }).nodeify(callback);
+};
+
+/*** NEEDED FOR SYNCING ***/
+
+EventStorePartition.prototype._truncateStreamFrom = function (
+  this: IEventStorePartition,
+  streamId: string,
+  commitSequence: number,
+  callback?: NodeCallback<void>,
+) {
+  return this._persistencePartition.truncateStreamFrom?.(
+    streamId,
+    commitSequence,
+    callback,
+  );
+};
+
+EventStorePartition.prototype._applyCommitHeader = function (
+  this: IEventStorePartition,
+  commitId: string,
+  header: Record<string, unknown>,
+  callback?: NodeCallback<ICommit>,
+) {
+  return this._persistencePartition.applyCommitHeader?.(
+    commitId,
+    header,
+    callback,
+  );
+};
+
+export default EventStorePartition;

package/src/event_stream.ts

@@ -0,0 +1,184 @@
+import Promise from "bluebird";
+import _ from "lodash";
+import Commit from "./persistence/commit";
+import type { IBaseEvent, ICommit, NodeCallback } from "./types";
+
+/** Subset of EventStorePartition that EventStream depends on. */
+interface IEventPartition {
+  _partitionId: string;
+  getLatestCommit?: (streamId: string) => Promise<ICommit | undefined>;
+  _queryStream: (streamId: string, callback?: NodeCallback<ICommit[]>) => Promise<ICommit[]>;
+  append: (commit: ICommit, callback?: NodeCallback<unknown>) => Promise<unknown>;
+}
+
+interface IEventStream {
+  _partition: IEventPartition;
+  _streamId: string;
+  _writeOnly: boolean;
+  _uncommittedEvents: IBaseEvent[];
+  _committedEvents: IBaseEvent[];
+  _version: number;
+  _isDeleted: boolean;
+  _commitSequence: number;
+  _prepareStream(callback?: NodeCallback<IEventStream>): Promise<IEventStream>;
+  getVersion(): number;
+  append(event: IBaseEvent): void;
+  hasChanges(): boolean;
+  commit(commitId: string, callback?: NodeCallback<IEventStream>): Promise<IEventStream | undefined>;
+  _clearChanges(): void;
+  revertChanges(): void;
+  _buildCommit(commitId: string, events: IBaseEvent[]): ICommit;
+  getCommittedEvents(): IBaseEvent[];
+  getUncommittedEvents(): IBaseEvent[];
+}
+
+// writeOnly - will never read entire stream from
+var EventStream = function (this: IEventStream, eventPartition: IEventPartition, streamId: string, writeOnly?: boolean) {
+  if (streamId === undefined) {
+    throw new Error("StreamId must be defined!");
+  }
+  this._partition = eventPartition;
+  this._streamId = streamId;
+  this._writeOnly = writeOnly || false;
+  this._uncommittedEvents = [];
+  this._committedEvents = [];
+  this._version = 0;
+  this._isDeleted = false;
+} as unknown as new (
+  eventPartition: IEventPartition,
+  streamId: string,
+  writeOnly?: boolean
+) => IEventStream;
+
+EventStream.prototype._prepareStream = function (this: IEventStream, callback?: NodeCallback<IEventStream>) {
+  this._committedEvents = [];
+  this._commitSequence = -1;
+  var self = this;
+  if (self._writeOnly === true && self._partition.getLatestCommit) {
+    // if stream should only be opened for appending commits, only really care about getting the correct commitSequence (from last commit)
+    return self._partition
+      .getLatestCommit(self._streamId)
+      .then(function (commit: ICommit | undefined) {
+        if (commit) {
+          self._commitSequence = commit.commitSequence;
+          var lastEvent = commit.events[commit.events.length - 1];
+          if (lastEvent && lastEvent.type === "$stream.deleted.event") {
+            self._isDeleted = true;
+          }
+          self._version = (lastEvent.version as number) + 1;
+        }
+        // if no commit is found, assume its a new stream, and keep default versions
+      })
+      .then(function () {
+        return self;
+      });
+  } else {
+    return self._partition
+      ._queryStream(self._streamId, callback as unknown as NodeCallback<ICommit[]>)
+      .then(function (commits: ICommit[]) {
+        self._version = 0;
+
+        if (!commits || commits.length === 0) {
+          commits = [];
+          self._version = -1;
+        } else {
+          if (commits[0] && commits[0].events && commits[0].events[0] && commits[0].events[0].type === "$stream.deleted.event") {
+            throw new Error("Stream is deleted");
+          }
+        }
+        var version = 0;
+        for (var i = 0; i < commits.length; i++) {
+          self._commitSequence++;
+          for (var j = 0; j < commits[i].events.length; j++) {
+            self._version++;
+            commits[i].events[j].version = version++;
+            self._committedEvents.push(commits[i].events[j]);
+          }
+        }
+      })
+      .then(function () {
+        return self;
+      });
+  }
+};
+
+EventStream.prototype.getVersion = function (this: IEventStream): number {
+  return this._version;
+};
+
+EventStream.prototype.append = function (this: IEventStream, event: IBaseEvent): void {
+  this._uncommittedEvents.push(event);
+};
+
+EventStream.prototype.hasChanges = function (this: IEventStream): boolean {
+  return this._uncommittedEvents.length > 0;
+};
+
+EventStream.prototype.commit = function (this: IEventStream, commitId: string, callback?: NodeCallback<IEventStream>) {
+  var self = this;
+
+  if (this._isDeleted) {
+    throw new Error(
+      "Stream is deleted, unable to commit: " +
+        this._uncommittedEvents.map(function (event: IBaseEvent) {
+          return event.type;
+        })
+    );
+  }
+
+  if (!this.hasChanges()) {
+    //nothing to commit
+    return Promise.resolve().nodeify(callback);
+  } else {
+    var commit = this._buildCommit(commitId, this._uncommittedEvents);
+    return this._partition.append(commit, callback as NodeCallback<unknown>).then(function () {
+      //rebuild local state
+      var events = self._uncommittedEvents;
+      self._version = (events[events.length - 1].version as number) + 1;
+      if (self._writeOnly === true) {
+        self._commitSequence++;
+        self._clearChanges();
+      } else {
+        for (var i = 0; i < events.length; i++) {
+          self._committedEvents.push(events[i]);
+        }
+        self._clearChanges();
+        self._commitSequence++;
+        return self;
+      }
+    });
+  }
+};
+
+EventStream.prototype._clearChanges = function (this: IEventStream): void {
+  this._uncommittedEvents = [];
+};
+
+EventStream.prototype.revertChanges = function (this: IEventStream): void {
+  //trunc the uncomitted events log
+  this._uncommittedEvents = [];
+};
+
+EventStream.prototype._buildCommit = function (this: IEventStream, commitId: string, events: IBaseEvent[]): ICommit {
+  var commitSequence = this._commitSequence;
+  var commit = new Commit(commitId, this._partition._partitionId, this._streamId, ++commitSequence, events);
+  var version = this._version == -1 ? 0 : this._version;
+
+  _.forEach(events, function (evt: IBaseEvent) {
+    evt.version = version++;
+  });
+  return commit;
+};
+
+EventStream.prototype.getCommittedEvents = function (this: IEventStream): IBaseEvent[] {
+  if (this._writeOnly) {
+    throw new Error("Cannot access committed events when using writeOnly mode...");
+  }
+  return this._committedEvents.slice();
+};
+
+EventStream.prototype.getUncommittedEvents = function (this: IEventStream): IBaseEvent[] {
+  return this._uncommittedEvents.slice();
+};
+
+export default EventStream;

package/src/persistence/commit.ts

@@ -0,0 +1,24 @@
+import type { IBaseEvent, ICommit } from "../types";
+
+var Commit = function <TEvent extends IBaseEvent = IBaseEvent>(
+  this: ICommit<TEvent>,
+  id: string,
+  partitionId: string,
+  streamId: string,
+  commitSequence: number,
+  events: TEvent[]
+) {
+  this.id = id;
+  this.partitionId = partitionId;
+  this.streamId = streamId;
+  this.commitSequence = commitSequence;
+  this.events = events;
+} as unknown as new <TEvent extends IBaseEvent = IBaseEvent>(
+  id: string,
+  partitionId: string,
+  streamId: string,
+  commitSequence: number,
+  events: TEvent[]
+) => ICommit<TEvent>;
+
+export default Commit;

package/src/persistence/concurrency_error.ts

@@ -0,0 +1,16 @@
+import util from "node:util";
+
+interface IConcurrencyError extends Error {
+  message: string;
+}
+
+var ConcurrencyError = function (this: IConcurrencyError, message: string) {
+  Error.call(this);
+  this.message = message;
+} as unknown as new (
+  message: string
+) => IConcurrencyError;
+
+util.inherits(ConcurrencyError, Error);
+
+export default ConcurrencyError;

package/src/persistence/duplicate_commit_error.ts

@@ -0,0 +1,16 @@
+import util from "node:util";
+
+interface IDuplicateCommitError extends Error {
+  message: string;
+}
+
+var DuplicateCommitError = function (this: IDuplicateCommitError, message: string) {
+  Error.call(this);
+  this.message = message;
+} as unknown as new (
+  message: string
+) => IDuplicateCommitError;
+
+util.inherits(DuplicateCommitError, Error);
+
+export default DuplicateCommitError;