@elysiumjs/moirai 0.0.0-stage → 0.1.0

package/dist/stores.d.ts

@@ -0,0 +1,155 @@
+/**
+ * What an idempotency store keeps of an action call: its response, replayed when the key comes
+ * back with the same request.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface IdempotencyRecord {
+    key: string;
+    action: string;
+    /** The fingerprint of the input (see `requestHash`). */
+    requestHash: string;
+    /** The JSON-safe response of the action. */
+    response: unknown;
+    createdAt: Date;
+}
+/**
+ * Where idempotent actions keep their responses. `put` runs in the action's unit of work, and
+ * throws {@link IdempotencyConflictError} when another call stored the key first.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface IdempotencyStore {
+    get(key: string): Promise<IdempotencyRecord | undefined>;
+    put(record: IdempotencyRecord): Promise<void>;
+}
+/**
+ * Serializes the actions that share a key (`serializeBy`): `lock` waits for the other holders,
+ * and the lock lasts until the unit of work ends, or until the returned release runs.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface ActionLock {
+    lock(key: string): Promise<(() => void) | void>;
+}
+/**
+ * A side effect an action asks for. It is written to the outbox in the action's unit of work,
+ * so it happens if and only if the action commits.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface OutboxEffect {
+    /** The kind, which picks the `@Outbox.handle()` handler. */
+    kind: string;
+    /** The JSON-safe payload given to the handler. */
+    payload: unknown;
+    /** When the effect may run. Defaults to now. */
+    availableAt?: Date;
+}
+/**
+ * A row of the outbox.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface OutboxRow {
+    id: string;
+    kind: string;
+    payload: unknown;
+    createdAt: Date;
+    availableAt: Date;
+    attempts: number;
+    lastError: string | null;
+    dispatchedAt: Date | null;
+    deadAt: Date | null;
+}
+/**
+ * Narrows the rows a relay claims. Both fields must match when both are set; an empty list
+ * matches nothing.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface OutboxClaimFilter {
+    kinds?: readonly string[];
+    ids?: readonly string[];
+}
+/**
+ * Claims due outbox rows for one relay.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface OutboxClaim extends OutboxClaimFilter {
+    now: Date;
+    /** The claimed rows become due again at this date, when the relay dies before marking them. */
+    leaseUntil: Date;
+    limit: number;
+}
+/**
+ * Where the outbox rows live. `claimDue` takes the rows that are neither dispatched nor dead and
+ * whose `availableAt` has passed, oldest first, and moves their `availableAt` to `leaseUntil` in
+ * the same statement, so that other relays leave them alone while this one handles them. Each
+ * row is then handled and marked in a transaction of its own.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface OutboxStore {
+    insert(rows: readonly OutboxRow[]): Promise<void>;
+    claimDue(claim: OutboxClaim): Promise<readonly OutboxRow[]>;
+    markDispatched(id: string, dispatchedAt: Date): Promise<void>;
+    markFailed(id: string, update: {
+        attempts: number;
+        lastError: string;
+        availableAt: Date;
+    }): Promise<void>;
+    markDead(id: string, update: {
+        attempts: number;
+        lastError: string;
+        deadAt: Date;
+    }): Promise<void>;
+}
+/**
+ * Where consumers remember the messages they processed. `record` answers `true` when the pair of
+ * the message and the consumer is new.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface InboxStore {
+    record(messageId: string, consumer: string): Promise<boolean>;
+}
+/**
+ * Keeps idempotency records in memory, for tests and single-process apps.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class MemoryIdempotencyStore implements IdempotencyStore {
+    #private;
+    get(key: string): Promise<IdempotencyRecord | undefined>;
+    put(record: IdempotencyRecord): Promise<void>;
+}
+/**
+ * Serializes actions in the process, one holder per key at a time.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class MemoryActionLock implements ActionLock {
+    #private;
+    lock(key: string): Promise<() => void>;
+}
+/**
+ * Keeps outbox rows in memory, for tests and single-process apps.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class MemoryOutboxStore implements OutboxStore {
+    #private;
+    /** Every row, for assertions. */
+    get rows(): OutboxRow[];
+    insert(rows: readonly OutboxRow[]): Promise<void>;
+    claimDue(claim: OutboxClaim): Promise<readonly OutboxRow[]>;
+    markDispatched(id: string, dispatchedAt: Date): Promise<void>;
+    markFailed(id: string, update: {
+        attempts: number;
+        lastError: string;
+        availableAt: Date;
+    }): Promise<void>;
+    markDead(id: string, update: {
+        attempts: number;
+        lastError: string;
+        deadAt: Date;
+    }): Promise<void>;
+}
+/**
+ * Keeps inbox records in memory, for tests and single-process apps.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class MemoryInboxStore implements InboxStore {
+    #private;
+    record(messageId: string, consumer: string): Promise<boolean>;
+}

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@elysiumjs/moirai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "description": "Actions, queries, idempotency, outbox, inbox and domain events for the Elysium.js framework.",
+  "private": false,
+  "author": {
+    "name": "Axel Nana",
+    "email": "axel.nana@workbud.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/na2axl/elysiumjs.git",
+    "directory": "@elysiumjs/moirai"
+  },
+  "homepage": "https://github.com/na2axl/elysiumjs/tree/main/@elysiumjs/moirai#readme",
+  "bugs": {
+    "url": "https://github.com/na2axl/elysiumjs/issues"
+  },
+  "scripts": {
+    "format": "prettier --write \"./src/**/*.ts\"",
+    "clean": "rimraf dist",
+    "build:js": "bun build ./src/index.ts ./src/heracles.ts --outdir ./dist --target browser --packages external --splitting --root ./src --minify-syntax --minify-whitespace",
+    "build:ts": "tsc",
+    "build": "bun run clean && bun run build:js && bun run build:ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage"
+  },
+  "keywords": [
+    "elysium",
+    "framework",
+    "typescript",
+    "cqrs",
+    "commands",
+    "idempotency",
+    "outbox"
+  ],
+  "type": "module",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./heracles": {
+      "types": "./dist/heracles.d.ts",
+      "import": "./dist/heracles.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "./dist/heracles.js",
+    "./src/heracles.ts"
+  ],
+  "dependencies": {
+    "typebox": "^1.3.0"
+  },
+  "devDependencies": {
+    "@elysiumjs/core": "0.11.0",
+    "@elysiumjs/heracles": "0.8.0",
+    "@elysiumjs/mnemosyne": "0.4.0",
+    "@elysiumjs/redis": "0.1.0",
+    "elysia": "^2.0.0-rc.1"
+  },
+  "peerDependencies": {
+    "@elysiumjs/core": "^0.11.0",
+    "@elysiumjs/heracles": "^0.8.0",
+    "@elysiumjs/mnemosyne": "^0.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@elysiumjs/heracles": {
+      "optional": true
+    }
+  }
+}