hexok 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,31 @@
+# hexok
+
+Hexo Kit — a TypeScript kit for writing a clean-architecture backend as ordinary classes: Entity, Port, Adapter, UseCase, Event, Interceptor.
+
+**Docs:** https://crobinson42.github.io/hexok/
+
+## Install
+
+```bash
+npm i hexok
+```
+
+Import from a layer. There is no root barrel.
+
+```ts
+import { Entity } from 'hexok/domain'
+import { ExternalUseCase } from 'hexok/app'
+import { App } from 'hexok/runtime'
+import { App as TestApp, InMemoryRepository } from 'hexok/testing'
+```
+
+| Import | What it is |
+| --- | --- |
+| `hexok/core` | `Result`, Standard Schema V1, `ErrorMap`, `CodedError` |
+| `hexok/domain` | `Entity`, `Port`, `EventCatalog`, `DomainEvent` |
+| `hexok/app` | `ExternalUseCase`, `InternalUseCase`, `EventUseCase`, `EventChannel` |
+| `hexok/infra` | `Mapper`, `Adapter.of` |
+| `hexok/runtime` | `App.from`, interceptors, local client, HTTP |
+| `hexok/testing` | `App.test`, in-memory adapters |
+
+Full API: https://crobinson42.github.io/hexok/

package/package.json

@@ -1,16 +1,26 @@
 {
   "name": "hexok",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A TypeScript kit for writing a clean-architecture backend as ordinary classes.",
   "type": "module",
   "license": "MIT",
   "sideEffects": false,
+  "keywords": [
+    "hexagonal-architecture",
+    "clean-architecture",
+    "ports-and-adapters",
+    "typescript",
+    "ddd",
+    "entity",
+    "use-case",
+    "domain-driven-design"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/crobinson42/hexok.git",
     "directory": "packages/hexok"
   },
-  "homepage": "https://github.com/crobinson42/hexok#readme",
+  "homepage": "https://crobinson42.github.io/hexok/",
   "bugs": {
     "url": "https://github.com/crobinson42/hexok/issues"
   },

package/dist/app/api-use-case.d.ts

@@ -1,52 +0,0 @@
-import { type ErrorMap, type Result } from '../core/index.js';
-import type { AnyEventCatalog, PortToken } from '../domain/index.js';
-import type { EventChannelCtor } from './types.js';
-/**
- * Request/response application use case. Declare static `key`, `input`, `output`, `errors`, `ports`.
- *
- * ```ts
- * class CloseIncident extends ApiUseCase {
- *   static readonly key = 'incident.close'
- *   static readonly input = z.object({ id: z.string() })
- *   static readonly output = Incident.schema
- *   static readonly errors = { NOT_FOUND: { message: 'Incident not found' } } as const
- *   static readonly ports = { incidents: IncidentRepository }
- *   async execute({ input, ports, errors }: ExecuteCtx<typeof CloseIncident>) {
- *     const incident = await ports.incidents.get(input.id)
- *     if (!incident) throw errors.NOT_FOUND()
- *     return incident.toProps()
- *   }
- * }
- * ```
- */
-export declare abstract class ApiUseCase {
-    /** Discriminator for `App.from` / `isApiUseCase`. Do not override. */
-    static readonly trigger: "api";
-    /** When true, omitted from contract, HTTP RPC, and `app.local`. Still in completeness. */
-    static readonly internal?: boolean;
-    /** Dotted RPC path (`incident.close`). Must be unique among API use cases. */
-    static readonly key: string;
-    /** Request Standard Schema. Validated before `execute`. */
-    static readonly input: unknown;
-    /** Success Standard Schema. Types `execute`, `run`, and the contract. */
-    static readonly output: unknown;
-    /** Declared refusals. Keys become `errors.CODE()` factories on `ExecuteCtx`. */
-    static readonly errors: ErrorMap;
-    /** Port tokens keyed by the alias used in `execute`. Required by `App.from`. */
-    static readonly ports?: Record<string, PortToken<unknown>>;
-    /** `static publishes = [DomainEvents] as const` — without `as const`, Events widens to EventClass. */
-    static readonly publishes?: readonly AnyEventCatalog[];
-    /** `static channels = [ClientChannel] as const` — without `as const`, catalog keys widen. */
-    static readonly channels?: readonly EventChannelCtor[];
-    /** RPC middleware for this use case, after app-level `App.use`. */
-    static readonly middleware?: readonly unknown[];
-    protected constructor();
-    /** Typed `never` so subclasses may take `ExecuteCtx` (tighter `publish`). */
-    abstract execute(ctx: never): Promise<unknown>;
-    /**
-     * Same one-liner as `if (!result.ok) throw new CodedError({ code: result.code })`.
-     * For `validate` / custom Results. Entity methods throw themselves.
-     */
-    unwrap<T, E extends string>(result: Result<T, E>): T;
-}
-//# sourceMappingURL=api-use-case.d.ts.map

package/dist/app/api-use-case.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"api-use-case.d.ts","sourceRoot":"","sources":["../../src/app/api-use-case.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAAsB,UAAU;IAC9B,sEAAsE;IACtE,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAG,KAAK,CAAU;IACzC,0FAA0F;IAC1F,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnC,8EAA8E;IAC9E,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAC/B,yEAAyE;IACzE,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAChC,gFAAgF;IAChF,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAM;IACtC,gFAAgF;IAChF,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3D,sGAAsG;IACtG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACvD,6FAA6F;IAC7F,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACvD,mEAAmE;IACnE,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAEhD,SAAS;IAET,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC;IAE9C;;;OAGG;IACH,MAAM,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC;CAYrD"}

package/dist/app/api-use-case.js

@@ -1,59 +0,0 @@
-import { CodedError } from '../core/index.js';
-/**
- * Request/response application use case. Declare static `key`, `input`, `output`, `errors`, `ports`.
- *
- * ```ts
- * class CloseIncident extends ApiUseCase {
- *   static readonly key = 'incident.close'
- *   static readonly input = z.object({ id: z.string() })
- *   static readonly output = Incident.schema
- *   static readonly errors = { NOT_FOUND: { message: 'Incident not found' } } as const
- *   static readonly ports = { incidents: IncidentRepository }
- *   async execute({ input, ports, errors }: ExecuteCtx<typeof CloseIncident>) {
- *     const incident = await ports.incidents.get(input.id)
- *     if (!incident) throw errors.NOT_FOUND()
- *     return incident.toProps()
- *   }
- * }
- * ```
- */
-export class ApiUseCase {
-    /** Discriminator for `App.from` / `isApiUseCase`. Do not override. */
-    static trigger = 'api';
-    /** When true, omitted from contract, HTTP RPC, and `app.local`. Still in completeness. */
-    static internal;
-    /** Dotted RPC path (`incident.close`). Must be unique among API use cases. */
-    static key;
-    /** Request Standard Schema. Validated before `execute`. */
-    static input;
-    /** Success Standard Schema. Types `execute`, `run`, and the contract. */
-    static output;
-    /** Declared refusals. Keys become `errors.CODE()` factories on `ExecuteCtx`. */
-    static errors = {};
-    /** Port tokens keyed by the alias used in `execute`. Required by `App.from`. */
-    static ports;
-    /** `static publishes = [DomainEvents] as const` — without `as const`, Events widens to EventClass. */
-    static publishes;
-    /** `static channels = [ClientChannel] as const` — without `as const`, catalog keys widen. */
-    static channels;
-    /** RPC middleware for this use case, after app-level `App.use`. */
-    static middleware;
-    constructor() { }
-    /**
-     * Same one-liner as `if (!result.ok) throw new CodedError({ code: result.code })`.
-     * For `validate` / custom Results. Entity methods throw themselves.
-     */
-    unwrap(result) {
-        if (!result.ok) {
-            throw new CodedError({
-                code: result.code,
-                message: result.code,
-                ...(result.issues !== undefined
-                    ? { data: { issues: result.issues } }
-                    : {}),
-            });
-        }
-        return result.value;
-    }
-}
-//# sourceMappingURL=api-use-case.js.map

package/dist/app/api-use-case.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"api-use-case.js","sourceRoot":"","sources":["../../src/app/api-use-case.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA8B,MAAM,kBAAkB,CAAC;AAI1E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAgB,UAAU;IAC9B,sEAAsE;IACtE,MAAM,CAAU,OAAO,GAAG,KAAc,CAAC;IACzC,0FAA0F;IAC1F,MAAM,CAAU,QAAQ,CAAW;IACnC,8EAA8E;IAC9E,MAAM,CAAU,GAAG,CAAS;IAC5B,2DAA2D;IAC3D,MAAM,CAAU,KAAK,CAAU;IAC/B,yEAAyE;IACzE,MAAM,CAAU,MAAM,CAAU;IAChC,gFAAgF;IAChF,MAAM,CAAU,MAAM,GAAa,EAAE,CAAC;IACtC,gFAAgF;IAChF,MAAM,CAAU,KAAK,CAAsC;IAC3D,sGAAsG;IACtG,MAAM,CAAU,SAAS,CAA8B;IACvD,6FAA6F;IAC7F,MAAM,CAAU,QAAQ,CAA+B;IACvD,mEAAmE;IACnE,MAAM,CAAU,UAAU,CAAsB;IAEhD,gBAAyB,CAAC;IAK1B;;;OAGG;IACH,MAAM,CAAsB,MAAoB;QAC9C,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,MAAM,IAAI,UAAU,CAAC;gBACnB,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,OAAO,EAAE,MAAM,CAAC,IAAI;gBACpB,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS;oBAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE;oBACrC,CAAC,CAAC,EAAE,CAAC;aACR,CAAC,CAAC;QACL,CAAC;QACD,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC"}

package/dist/testing/in-memory-broker.d.ts

@@ -1,18 +0,0 @@
-import type { BrokerAdapter, BrokerConsumeCtx, Envelope } from '../domain/index.js';
-type Consumer = (envelope: Envelope, ctx: BrokerConsumeCtx) => Promise<void>;
-/**
- * In-process broker. `consume` dispatches with attempt; ack/nack are no-ops
- * besides recording. `stop()` clears consumers.
- */
-export declare class InMemoryBroker implements BrokerAdapter {
-    #private;
-    readonly kind: "broker";
-    readonly published: Envelope[];
-    attempts: number;
-    static create(): InMemoryBroker;
-    publish(envelope: Envelope): Promise<void>;
-    consume(key: string, group: string, handler: Consumer): void;
-    stop(): Promise<void>;
-}
-export {};
-//# sourceMappingURL=in-memory-broker.d.ts.map

package/dist/testing/in-memory-broker.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"in-memory-broker.d.ts","sourceRoot":"","sources":["../../src/testing/in-memory-broker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,QAAQ,EACT,MAAM,oBAAoB,CAAC;AAE5B,KAAK,QAAQ,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE7E;;;GAGG;AACH,qBAAa,cAAe,YAAW,aAAa;;IAClD,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAClC,QAAQ,CAAC,SAAS,EAAE,QAAQ,EAAE,CAAM;IAEpC,QAAQ,SAAK;IAEb,MAAM,CAAC,MAAM,IAAI,cAAc;IAIzB,OAAO,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBhD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,IAAI;IAMtD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}

package/dist/testing/in-memory-broker.js

@@ -1,42 +0,0 @@
-/**
- * In-process broker. `consume` dispatches with attempt; ack/nack are no-ops
- * besides recording. `stop()` clears consumers.
- */
-export class InMemoryBroker {
-    kind = 'broker';
-    published = [];
-    #consumers = new Map();
-    attempts = 1;
-    static create() {
-        return new InMemoryBroker();
-    }
-    async publish(envelope) {
-        this.published.push(envelope);
-        const groups = this.#consumers.get(envelope.key);
-        if (!groups)
-            return;
-        for (const consumer of groups.values()) {
-            let acked = false;
-            const ctx = {
-                attempt: this.attempts,
-                ack: async () => {
-                    acked = true;
-                },
-                nack: async () => {
-                    acked = false;
-                },
-            };
-            await consumer(envelope, ctx);
-            void acked;
-        }
-    }
-    consume(key, group, handler) {
-        const groups = this.#consumers.get(key) ?? new Map();
-        groups.set(group, handler);
-        this.#consumers.set(key, groups);
-    }
-    async stop() {
-        this.#consumers.clear();
-    }
-}
-//# sourceMappingURL=in-memory-broker.js.map

package/dist/testing/in-memory-broker.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"in-memory-broker.js","sourceRoot":"","sources":["../../src/testing/in-memory-broker.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,MAAM,OAAO,cAAc;IAChB,IAAI,GAAG,QAAiB,CAAC;IACzB,SAAS,GAAe,EAAE,CAAC;IACpC,UAAU,GAAG,IAAI,GAAG,EAAiC,CAAC;IACtD,QAAQ,GAAG,CAAC,CAAC;IAEb,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,cAAc,EAAE,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,QAAkB;QAC9B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACvC,IAAI,KAAK,GAAG,KAAK,CAAC;YAClB,MAAM,GAAG,GAAqB;gBAC5B,OAAO,EAAE,IAAI,CAAC,QAAQ;gBACtB,GAAG,EAAE,KAAK,IAAI,EAAE;oBACd,KAAK,GAAG,IAAI,CAAC;gBACf,CAAC;gBACD,IAAI,EAAE,KAAK,IAAI,EAAE;oBACf,KAAK,GAAG,KAAK,CAAC;gBAChB,CAAC;aACF,CAAC;YACF,MAAM,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;YAC9B,KAAK,KAAK,CAAC;QACb,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAW,EAAE,KAAa,EAAE,OAAiB;QACnD,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,GAAG,EAAoB,CAAC;QACvE,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC3B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;CACF"}