@arts-n-crafts/ts 3.13.1

package/README.md

@@ -0,0 +1,58 @@
+# @arts-and-crafts
+
+> Arts and Crafts was a reaction against the industrialization and excess of the Victorian era, and it sought to celebrate traditional craftsmanship and materials. Arts and Crafts architecture is characterized by a simple and functional design, the use of natural materials, and a focus on craftsmanship.
+
+## Why
+
+To provide structure and organization to your codebase, making it easier to understand (maintainable), test (testable), adapt (flexible), scale (scalable) and withstand failure (robust).
+
+### Simplicity
+
+The idea here is that a web application (hereafter, a system) has three types of entrypoints. The actor could be a producer making a POST request (a command), or a consumer retrieving data via a GET request (a query). The actor could also be a publisher sending a message (an event). To summarize, the entrypoints are:
+- Commands;
+- Queries, and
+- Events.
+
+### Usecases
+
+Based on the idea of a system consisting of only having to handle commands, queries and events, we can provide a clear separation of concerns. This allows us to focus on each type of entrypoint independently, making it easier to reason about and maintain the codebase.
+
+So, each entrypoint is a separate usecase. Thus, in a organized and structured system, each usecase is independent of other usecases (decoupled) and the usecase itself should contain all its required logic.
+
+### Modularity
+
+Modularity is a key principle in software development. It involves breaking down a system into smaller, independent modules that can be developed, tested, and maintained separately.
+
+Usecases belong to a specific domain. Domains are organized as separate modules, each responsible for a specific aspect of the system, often also with their own terminology and domain-specific language.
+
+Domains consist of behavior (usecases). These usecases could be part of a workflow. Workflows could cross multiple domains.
+
+### Workflows
+
+Workflows are a way to organize usecases into a sequence of steps. Each step in a workflow is a usecase. Workflows can be used to model complex business processes.
+
+### System design
+
+Event-Storming
+
+## Installation
+
+
+
+## Contributing
+
+This codebase is written in TypeScript and uses Bun as the runtime.
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run test
+```
+
+This project was created using `bun init` in bun v1.2.0. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.

package/dist/index.cjs

@@ -0,0 +1,659 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/core/utils/createCommand.ts
+function createCommand(type, aggregateId, payload, metadata = {}) {
+  return Object.freeze({
+    id: crypto.randomUUID(),
+    type,
+    aggregateId: String(aggregateId),
+    payload,
+    kind: "command",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    metadata
+  });
+}
+function createQuery(type, payload, metadata = {}) {
+  return Object.freeze({
+    id: crypto.randomUUID(),
+    type,
+    payload,
+    kind: "query",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    metadata
+  });
+}
+
+// src/core/utils/isCommand.ts
+function isCommand(candidate) {
+  if (candidate === null)
+    return false;
+  if (typeof candidate !== "object")
+    return false;
+  if (!("type" in candidate))
+    return false;
+  return "kind" in candidate && candidate.kind === "command";
+}
+
+// src/core/utils/isQuery.ts
+function isQuery(candidate) {
+  if (candidate === null)
+    return false;
+  if (typeof candidate !== "object")
+    return false;
+  if (!("type" in candidate))
+    return false;
+  return "kind" in candidate && candidate.kind === "query";
+}
+
+// src/domain/Specification/Specification.ts
+var Specification = class {
+  and(other) {
+    return new AndSpecification(this, other);
+  }
+  or(other) {
+    return new OrSpecification(this, other);
+  }
+  not() {
+    return new NotSpecification(this);
+  }
+};
+var AndSpecification = class extends Specification {
+  constructor(left, right) {
+    super();
+    this.left = left;
+    this.right = right;
+  }
+  isSatisfiedBy(entity) {
+    return this.left.isSatisfiedBy(entity) && this.right.isSatisfiedBy(entity);
+  }
+  toQuery() {
+    return {
+      type: "and",
+      nodes: [this.left.toQuery(), this.right.toQuery()]
+    };
+  }
+};
+var OrSpecification = class extends Specification {
+  constructor(left, right) {
+    super();
+    this.left = left;
+    this.right = right;
+  }
+  isSatisfiedBy(entity) {
+    return this.left.isSatisfiedBy(entity) || this.right.isSatisfiedBy(entity);
+  }
+  toQuery() {
+    return {
+      type: "or",
+      nodes: [this.left.toQuery(), this.right.toQuery()]
+    };
+  }
+};
+var NotSpecification = class extends Specification {
+  constructor(spec) {
+    super();
+    this.spec = spec;
+  }
+  isSatisfiedBy(entity) {
+    return !this.spec.isSatisfiedBy(entity);
+  }
+  toQuery() {
+    return {
+      type: "not",
+      node: this.spec.toQuery()
+    };
+  }
+};
+
+// src/domain/Specification/utils/createQueryNode.ts
+function createQueryNode(type, field, value) {
+  switch (type) {
+    case "eq":
+    case "gt":
+    case "lt":
+      return { type, field, value };
+    case "and":
+    case "or":
+      return { type, nodes: value };
+    case "not":
+      return { type, node: value };
+  }
+}
+
+// src/domain/Specification/implementations/FieldEquals.specification.ts
+var FieldEquals = class extends Specification {
+  constructor(field, value) {
+    super();
+    this.field = field;
+    this.value = value;
+  }
+  isSatisfiedBy(entity) {
+    return entity[this.field] === this.value;
+  }
+  toQuery() {
+    return createQueryNode("eq", this.field, this.value);
+  }
+};
+
+// src/utils/fail/fail.ts
+function fail(anExpression) {
+  return () => {
+    throw anExpression;
+  };
+}
+
+// src/utils/invariant/invariant.ts
+function invariant(condition, onInvalid) {
+  if (!condition)
+    onInvalid();
+}
+
+// src/domain/Specification/implementations/FieldGreaterThan.specification.ts
+var FieldGreaterThan = class extends Specification {
+  constructor(field, value) {
+    super();
+    this.field = field;
+    this.value = value;
+  }
+  isNumber(value) {
+    return typeof value === "number";
+  }
+  isSatisfiedBy(entity) {
+    const field = entity[this.field];
+    invariant(
+      this.isNumber(field),
+      fail(
+        new TypeError(`Field ${String(this.field)} is not a number`)
+      )
+    );
+    return field > this.value;
+  }
+  toQuery() {
+    return createQueryNode("gt", this.field, this.value);
+  }
+};
+function createDomainEvent(type, aggregateId, payload, metadata = {}) {
+  return Object.freeze({
+    id: crypto.randomUUID(),
+    type,
+    aggregateId,
+    payload,
+    source: "internal",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    metadata
+  });
+}
+
+// src/domain/utils/isEvent.ts
+function isEvent(event) {
+  if (typeof event !== "object")
+    return false;
+  if (event === null)
+    return false;
+  if (!("type" in event))
+    return false;
+  return "source" in event;
+}
+
+// src/domain/utils/isDomainEvent.ts
+function isDomainEvent(event) {
+  return isEvent(event) && "aggregateId" in event && event.source === "internal";
+}
+
+// src/infrastructure/CommandBus/implementations/SimpleCommandBus.ts
+var SimpleCommandBus = class {
+  handlers = /* @__PURE__ */ new Map();
+  register(aTypeOfCommand, anHandler) {
+    if (this.handlers.has(aTypeOfCommand)) {
+      throw new Error(`Handler already registered for command type: ${aTypeOfCommand}`);
+    }
+    this.handlers.set(aTypeOfCommand, anHandler);
+  }
+  async execute(aCommand) {
+    const handler = this.handlers.get(aCommand.type);
+    if (!handler) {
+      throw new Error(`No handler found for command type: ${aCommand.type}`);
+    }
+    return handler.execute(aCommand);
+  }
+};
+
+// src/infrastructure/Database/Database.ts
+var Operation = /* @__PURE__ */ ((Operation2) => {
+  Operation2["CREATE"] = "CREATE";
+  Operation2["PUT"] = "PUT";
+  Operation2["PATCH"] = "PATCH";
+  Operation2["DELETE"] = "DELETE";
+  return Operation2;
+})(Operation || {});
+
+// src/infrastructure/Database/implementations/SimpleDatabase.exceptions.ts
+var RecordNotFoundException = class extends Error {
+  constructor(id) {
+    super(`Record not found for id: ${id}`);
+  }
+};
+var DuplicateRecordException = class extends Error {
+  constructor(id) {
+    super(`Duplicate record found for id: ${id}`);
+  }
+};
+var DatabaseOfflineException = class extends Error {
+  constructor() {
+    super(`Database is offline`);
+  }
+};
+
+// src/infrastructure/Database/implementations/SimpleDatabase.ts
+var SimpleDatabase = class {
+  datasource = /* @__PURE__ */ new Map();
+  simulateOffline = false;
+  async query(tableName, specification) {
+    if (this.simulateOffline)
+      throw new DatabaseOfflineException();
+    const tableRecords = this.datasource.get(tableName) || [];
+    return tableRecords.filter((record) => specification.isSatisfiedBy(record));
+  }
+  async execute(tableName, statement) {
+    if (this.simulateOffline)
+      throw new DatabaseOfflineException();
+    if (!this.datasource.has(tableName))
+      this.datasource.set(tableName, []);
+    const table = this.datasource.get(tableName);
+    switch (statement.operation) {
+      case "CREATE" /* CREATE */: {
+        const isDuplicate = table.some((item) => item.id === statement.payload.id);
+        if (isDuplicate)
+          throw new DuplicateRecordException(statement.payload.id);
+        table.push(statement.payload);
+        break;
+      }
+      case "PUT" /* PUT */: {
+        const index = table.findIndex((item) => item.id === statement.payload.id);
+        if (index === -1)
+          throw new RecordNotFoundException(statement.payload.id);
+        table[index] = statement.payload;
+        break;
+      }
+      case "PATCH" /* PATCH */: {
+        const index = table.findIndex((item) => item.id === statement.payload.id);
+        if (index === -1)
+          throw new RecordNotFoundException(statement.payload.id);
+        table[index] = { ...table[index], ...statement.payload };
+        break;
+      }
+      case "DELETE" /* DELETE */: {
+        const index = table.findIndex((item) => item.id === statement.payload.id);
+        if (index === -1)
+          throw new RecordNotFoundException(statement.payload.id);
+        table.splice(index, 1);
+        break;
+      }
+    }
+  }
+  goOffline() {
+    this.simulateOffline = true;
+  }
+};
+
+// src/infrastructure/EventBus/implementations/SimpleEventBus.ts
+var SimpleEventBus = class {
+  handlers = /* @__PURE__ */ new Map();
+  subscribe(stream, aHandler) {
+    const handlersForType = this.handlers.get(stream) ?? [];
+    handlersForType.push(aHandler);
+    this.handlers.set(stream, handlersForType);
+  }
+  async consume(stream, anEvent) {
+    if (!this.handlers.has(stream))
+      return;
+    const handlers = this.handlers.get(stream);
+    await Promise.all(handlers.map(async (handler) => {
+      return handler.handle(anEvent);
+    }));
+  }
+  async publish(stream, anEvent) {
+    await this.consume(stream, anEvent);
+  }
+};
+function createIntegrationEvent(type, payload, metadata) {
+  return Object.freeze({
+    id: crypto.randomUUID(),
+    type,
+    payload,
+    source: "external",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    metadata: {
+      ...metadata
+    }
+  });
+}
+
+// src/infrastructure/EventBus/utils/isIntegrationEvent.ts
+function isIntegrationEvent(event) {
+  return isEvent(event) && event.source === "external";
+}
+
+// src/utils/isEqual/isEqual.ts
+function isEqual(a, b) {
+  if (a === b) {
+    return true;
+  }
+  const bothAreObjects = a && b && typeof a === "object" && typeof b === "object";
+  return Boolean(
+    bothAreObjects && Object.keys(a).length === Object.keys(b).length && Object.entries(a).every(([k, v]) => isEqual(v, b[k]))
+  );
+}
+
+// src/utils/parseAsError/parseAsError.ts
+function parseAsError(value) {
+  if (value instanceof Error)
+    return value;
+  if (typeof value === "string")
+    return new Error(value);
+  try {
+    const json = JSON.stringify(value);
+    return new Error(json ?? String(value));
+  } catch {
+    return new Error("Unknown error");
+  }
+}
+
+// src/utils/streamKey/makeStreamKey.ts
+function makeStreamKey(streamName, aggregateId) {
+  return `${streamName}#${aggregateId}`;
+}
+
+// src/infrastructure/EventStore/utils/createStoredEvent.ts
+function createStoredEvent(streamName, version, event) {
+  return Object.freeze({
+    id: event.id,
+    streamKey: makeStreamKey(streamName, event.aggregateId),
+    version,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    event
+  });
+}
+
+// src/infrastructure/EventStore/implementations/SimpleEventStore.exceptions.ts
+var MultipleAggregatesException = class extends Error {
+  constructor() {
+    super("EventStore append does not support multiple aggregates to be stored");
+  }
+};
+
+// src/infrastructure/EventStore/implementations/SimpleEventStore.ts
+var SimpleEventStore = class {
+  constructor(database, outbox) {
+    this.database = database;
+    this.outbox = outbox;
+  }
+  tableName = "event_store";
+  async load(streamName, aggregateId) {
+    const streamKey = makeStreamKey(streamName, aggregateId);
+    const specification = new FieldEquals("streamKey", streamKey);
+    const storedEvents = await this.database.query(this.tableName, specification);
+    return storedEvents.map((storedEvent) => storedEvent.event);
+  }
+  async append(streamName, events) {
+    const uniqueAggregateIds = new Set(events.map((event2) => event2.aggregateId));
+    if (uniqueAggregateIds.size > 1)
+      throw new MultipleAggregatesException();
+    const event = events[0];
+    const currentStream = await this.load(streamName, event.aggregateId);
+    const eventsToStore = events.map((event2) => createStoredEvent(streamName, currentStream.length + 1, event2));
+    await Promise.all(
+      eventsToStore.map(
+        async (payload) => this.database.execute(this.tableName, { operation: "CREATE" /* CREATE */, payload })
+      )
+    );
+    await Promise.all(events.map(async (event2) => this.outbox?.enqueue(event2)));
+  }
+};
+
+// src/infrastructure/Outbox/implementations/GenericOutboxWorker.ts
+var GenericOutboxWorker = class {
+  constructor(outbox, eventBus, stream) {
+    this.outbox = outbox;
+    this.eventBus = eventBus;
+    this.stream = stream;
+  }
+  async runOnce() {
+    const pending = await this.outbox.getPending();
+    await Promise.all(pending.map(async (entry) => {
+      try {
+        await this.eventBus.publish(this.stream, entry.event);
+        await this.outbox.markAsPublished(entry.id);
+      } catch {
+        await this.outbox.markAsFailed(entry.id);
+      }
+    }));
+  }
+  async tick() {
+    await this.runOnce();
+  }
+  start(intervalMs) {
+    setInterval(() => {
+      void this.tick().catch(console.error);
+    }, intervalMs);
+  }
+};
+
+// src/infrastructure/Outbox/implementations/InMemoryOutbox.ts
+var InMemoryOutbox = class {
+  entries = [];
+  idCounter = 0;
+  async enqueue(event) {
+    this.entries.push({
+      id: (this.idCounter++).toString(),
+      event,
+      published: false,
+      retryCount: 0
+    });
+  }
+  async getPending(limit = 100) {
+    return this.entries.filter((e) => !e.published).slice(0, limit);
+  }
+  async markAsPublished(id) {
+    const entry = this.entries.find((e) => e.id === id);
+    if (entry) {
+      entry.published = true;
+    }
+  }
+  async markAsFailed(id) {
+    const entry = this.entries.find((e) => e.id === id);
+    if (entry) {
+      entry.retryCount += 1;
+      entry.lastAttemptAt = (/* @__PURE__ */ new Date()).toISOString();
+    }
+  }
+};
+function createOutboxEntry(event) {
+  return Object.freeze({
+    id: crypto.randomUUID(),
+    event,
+    published: false,
+    retryCount: 0,
+    lastAttemptAt: void 0
+  });
+}
+
+// src/infrastructure/QueryBus/implementations/SimpleQueryBus.ts
+var SimpleQueryBus = class {
+  handlers = /* @__PURE__ */ new Map();
+  register(aTypeOfQuery, anHandler) {
+    if (this.handlers.has(aTypeOfQuery)) {
+      throw new Error(`Handler already registered for query type: ${aTypeOfQuery}`);
+    }
+    this.handlers.set(aTypeOfQuery, anHandler);
+  }
+  async execute(aQuery) {
+    const handler = this.handlers.get(aQuery.type);
+    if (!handler) {
+      throw new Error(`No handler found for query type: ${aQuery.type}`);
+    }
+    return handler.execute(aQuery);
+  }
+};
+
+// src/infrastructure/Repository/implementations/SimpleRepository.ts
+var SimpleRepository = class {
+  constructor(eventStore, streamName, evolveFn, initialState) {
+    this.eventStore = eventStore;
+    this.streamName = streamName;
+    this.evolveFn = evolveFn;
+    this.initialState = initialState;
+  }
+  async load(aggregateId) {
+    const pastEvents = await this.eventStore.load(this.streamName, aggregateId);
+    return pastEvents.reduce(this.evolveFn, this.initialState(aggregateId));
+  }
+  async store(events) {
+    await Promise.all(
+      events.map(
+        async (event) => this.eventStore.append(
+          this.streamName,
+          [event]
+        )
+      )
+    );
+  }
+};
+
+// src/infrastructure/ScenarioTest/ScenarioTest.ts
+var ScenarioTest = class {
+  constructor(streamName, eventBus, eventStore, commandBus, queryBus, repository, outboxWorker) {
+    this.streamName = streamName;
+    this.eventBus = eventBus;
+    this.eventStore = eventStore;
+    this.commandBus = commandBus;
+    this.queryBus = queryBus;
+    this.repository = repository;
+    this.outboxWorker = outboxWorker;
+  }
+  givenInput = [];
+  whenInput;
+  given(...events) {
+    this.givenInput = events;
+    return {
+      when: this.when.bind(this),
+      then: this.then.bind(this)
+    };
+  }
+  when(action) {
+    this.whenInput = action;
+    return {
+      then: this.then.bind(this)
+    };
+  }
+  async then(thenInput) {
+    const domainEvents = this.givenInput.filter(isDomainEvent);
+    const integrationEvents = this.givenInput.filter(isIntegrationEvent);
+    await Promise.all([
+      this.repository.store(domainEvents),
+      integrationEvents.map(async (event) => this.eventBus.consume(this.streamName, event))
+    ]);
+    if (!this.whenInput) {
+      throw new Error("In the ScenarioTest, the when-step cannot be empty");
+    }
+    if (isCommand(this.whenInput)) {
+      invariant(isDomainEvent(thenInput), fail(new TypeError('When "command" expects a domain event in the then-step')));
+      await this.handleCommand(this.whenInput, thenInput);
+    }
+    if (isQuery(this.whenInput)) {
+      invariant(Array.isArray(thenInput), fail(new TypeError('When "query" expects an array of expected results in the then-step')));
+      await this.handleQuery(this.whenInput, thenInput);
+    }
+    if (isDomainEvent(this.whenInput) || isIntegrationEvent(this.whenInput)) {
+      invariant(isDomainEvent(thenInput), fail(new TypeError('When "domain event" or "integration event" expects a domain event in the then-step')));
+      await this.handleEvent(this.whenInput, thenInput);
+    }
+  }
+  async handleCommand(command, outcome) {
+    await this.commandBus.execute(command);
+    const actualEvents = await this.eventStore.load(this.streamName, outcome.aggregateId);
+    const foundEvent = actualEvents.findLast(
+      (event) => isDomainEvent(event) && event.aggregateId === outcome.aggregateId && event.type === outcome.type
+    );
+    invariant(!!foundEvent, fail(new Error("ScenarioTest: event/command was not found")));
+    invariant(
+      outcome.type === foundEvent.type,
+      fail(new Error("ScenarioTest: event/command type was not equal"))
+    );
+    invariant(
+      outcome.aggregateId === foundEvent.aggregateId,
+      fail(new Error("ScenarioTest: event/command aggregate id was not equal"))
+    );
+    invariant(
+      isEqual(outcome.payload, foundEvent.payload),
+      fail(new Error("ScenarioTest: event/command payload was not equal"))
+    );
+  }
+  async handleQuery(query, expected) {
+    await this.outboxWorker.tick();
+    const actual = await this.queryBus.execute(query);
+    invariant(
+      isEqual(actual, expected),
+      fail(new Error("ScenarioTest: a different query result was returned"))
+    );
+  }
+  async handleEvent(event, outcome) {
+    await this.eventBus.publish(this.streamName, event);
+    const actualEvents = await this.eventStore.load(this.streamName, outcome.aggregateId);
+    const foundEvent = actualEvents.findLast(
+      (event2) => isEvent(event2) && event2.aggregateId === outcome.aggregateId && event2.type === outcome.type
+    );
+    invariant(!!foundEvent, fail(new Error("ScenarioTest: event was not found")));
+    invariant(isEvent(foundEvent), fail(new Error("ScenarioTest: event is not of type event")));
+    invariant(
+      outcome.type === foundEvent.type,
+      fail(new Error("ScenarioTest: event type was not equal"))
+    );
+    invariant(
+      outcome.aggregateId === foundEvent.aggregateId,
+      fail(new Error("ScenarioTest: event aggregate id was not equal"))
+    );
+    invariant(
+      isEqual(outcome.payload, foundEvent.payload),
+      fail(new Error("ScenarioTest: event payload was not equal"))
+    );
+  }
+};
+
+exports.AndSpecification = AndSpecification;
+exports.FieldEquals = FieldEquals;
+exports.FieldGreaterThan = FieldGreaterThan;
+exports.GenericOutboxWorker = GenericOutboxWorker;
+exports.InMemoryOutbox = InMemoryOutbox;
+exports.NotSpecification = NotSpecification;
+exports.Operation = Operation;
+exports.OrSpecification = OrSpecification;
+exports.ScenarioTest = ScenarioTest;
+exports.SimpleCommandBus = SimpleCommandBus;
+exports.SimpleDatabase = SimpleDatabase;
+exports.SimpleEventBus = SimpleEventBus;
+exports.SimpleEventStore = SimpleEventStore;
+exports.SimpleQueryBus = SimpleQueryBus;
+exports.SimpleRepository = SimpleRepository;
+exports.Specification = Specification;
+exports.createCommand = createCommand;
+exports.createDomainEvent = createDomainEvent;
+exports.createIntegrationEvent = createIntegrationEvent;
+exports.createOutboxEntry = createOutboxEntry;
+exports.createQuery = createQuery;
+exports.createQueryNode = createQueryNode;
+exports.createStoredEvent = createStoredEvent;
+exports.fail = fail;
+exports.invariant = invariant;
+exports.isCommand = isCommand;
+exports.isDomainEvent = isDomainEvent;
+exports.isEqual = isEqual;
+exports.isEvent = isEvent;
+exports.isIntegrationEvent = isIntegrationEvent;
+exports.isQuery = isQuery;
+exports.makeStreamKey = makeStreamKey;
+exports.parseAsError = parseAsError;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map