@arki/event-sourcing 0.1.0 → 0.1.1

package/dist/dot.d.ts

@@ -37,9 +37,20 @@
  * load — that is intentional: the adapter only makes sense in a DOT app.
  */
 import type { EventStore, MessageBus } from '@event-driven-io/emmett';
-import type { DotPip } from '@arki/dot/pip';
+import type { EmptyShape, Pip } from '@arki/dot/pip';
 import type { CommandHandlerRegistration } from './command.js';
 import type { PostgreSQLProjectionInput } from './event-sourcing-features.js';
+/**
+ * Stable error codes thrown by the event-sourcing pip. Exported so consumers
+ * and coding agents can match against them — never parse the message.
+ *
+ * @see packages/dot/docs/principles.md — principle 1.3 ("errors are part
+ * of the API") and principle 4 ("agent-discoverable everywhere").
+ */
+export declare const EVENT_SOURCING_PIP_ERROR_CODES: {
+    /** boot was called without a configured event-store URL. */
+    readonly dbUrlNotConfigured: "EVENT_SOURCING_PIP_E001";
+};
 /**
  * Options for the event-sourcing DOT adapter.
  */
@@ -64,11 +75,6 @@ export type EventSourcingDotOptions = {
      * `process.env`. If none are set, `boot` throws.
      */
     readonly dbUrl?: string;
-    /**
-     * Pip name override. Defaults to `'event-sourcing'`. Use this only
-     * when composing multiple event-sourcing scopes inside the same app.
-     */
-    readonly name?: string;
 };
 /** Services published by the event-sourcing adapter. */
 export type EventSourcingServices = {
@@ -83,8 +89,8 @@ export type EventSourcingServices = {
 /**
  * Build a DOT pip that opens the event store, wires command handlers
  * into an in-memory message bus, and publishes both as services. The
- * kernel calls `dispose` in reverse-topological order to release the
+ * kernel calls `dispose` in reverse declaration order to release the
  * underlying PG pool.
  */
-export declare function eventSourcing(options: EventSourcingDotOptions): DotPip<EventSourcingServices>;
+export declare function eventSourcing(options: EventSourcingDotOptions): Pip<EmptyShape, EventSourcingServices>;
 //# sourceMappingURL=dot.d.ts.map

package/dist/dot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dot.d.ts","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEtE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAG9E;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC3D;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;IACjE;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,qBAAqB,GAAG;IAClC,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC,CAAC;AAgBF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CA8B7F"}
+{"version":3,"file":"dot.d.ts","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEtE,OAAO,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAG9E;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B;IACzC,4DAA4D;;CAEpD,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC3D;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;IACjE;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,qBAAqB,GAAG;IAClC,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC,CAAC;AAgBF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,uBAAuB,GAAG,GAAG,CAAC,UAAU,EAAE,qBAAqB,CAAC,CA2CtG"}

package/dist/dot.js

@@ -36,8 +36,19 @@
  * Importing this adapter without `@arki/dot` installed will fail at module
  * load — that is intentional: the adapter only makes sense in a DOT app.
  */
-import { defineDotPip } from '@arki/dot/pip';
+import { pip, DotPipError } from '@arki/dot/pip';
 import { EVENT_STORE_URL_VARIANTS, eventSourcingFeatures } from './event-sourcing-features.js';
+/**
+ * Stable error codes thrown by the event-sourcing pip. Exported so consumers
+ * and coding agents can match against them — never parse the message.
+ *
+ * @see packages/dot/docs/principles.md — principle 1.3 ("errors are part
+ * of the API") and principle 4 ("agent-discoverable everywhere").
+ */
+export const EVENT_SOURCING_PIP_ERROR_CODES = {
+    /** boot was called without a configured event-store URL. */
+    dbUrlNotConfigured: 'EVENT_SOURCING_PIP_E001',
+};
 /**
  * Resolve the event-store connection URL from explicit options first, then
  * from the recognised env vars in priority order. Returns `undefined` when
@@ -56,29 +67,40 @@ function resolveDbUrl(explicit) {
 /**
  * Build a DOT pip that opens the event store, wires command handlers
  * into an in-memory message bus, and publishes both as services. The
- * kernel calls `dispose` in reverse-topological order to release the
+ * kernel calls `dispose` in reverse declaration order to release the
  * underlying PG pool.
  */
 export function eventSourcing(options) {
-    const name = options.name ?? 'event-sourcing';
     const commandHandlers = options.commandHandlers ?? [];
     // Captured at boot so dispose can call it without re-reading services
     // (dispose is allowed to run even when services failed to publish).
     let closeStore;
-    return defineDotPip({
-        name,
+    return pip({
+        name: 'event-sourcing',
         version: '0.1.0',
-        provides: ['event-store', 'message-bus'],
         configure(ctx) {
             ctx.registerService('eventStore', 'event-store');
             ctx.registerService('messageBus', 'message-bus');
+            ctx.declareProvides('event-store', 'message-bus');
         },
         boot() {
+            // Validate at the pip boundary so the DOT lifecycle gets a coded
+            // error. `eventSourcingFeatures.initEventSourcing` still throws raw
+            // `Error` for non-DOT consumers (its public contract is unchanged);
+            // the check here makes sure we never reach it without a URL.
             const dbUrl = resolveDbUrl(options.dbUrl);
+            if (dbUrl === undefined) {
+                throw new DotPipError({
+                    code: EVENT_SOURCING_PIP_ERROR_CODES.dbUrlNotConfigured,
+                    message: '[event-sourcing] Event Store database URL is not configured.',
+                    remediation: `Pass options.dbUrl to eventSourcing(...) or set one of ${EVENT_STORE_URL_VARIANTS.join(', ')} in the environment before booting the app.`,
+                    docsUrl: 'https://arki.dev/dot/errors/event-sourcing-pip-e001',
+                });
+            }
             const { eventStore, close } = eventSourcingFeatures.initEventSourcing(options.projections, dbUrl);
             closeStore = close;
             const messageBus = eventSourcingFeatures.initMessageBus(eventStore, [...commandHandlers]);
-            return { services: { eventStore, messageBus } };
+            return { eventStore, messageBus };
         },
         async dispose() {
             if (closeStore !== undefined) {

package/dist/dot.js.map

@@ -1 +1 @@
-{"version":3,"file":"dot.js","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAI7C,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AA4C/F;;;;GAIG;AACH,SAAS,YAAY,CAAC,QAA4B;IAChD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC;IAC/D,KAAK,MAAM,IAAI,IAAI,wBAAwB,EAAE,CAAC;QAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;YAAE,OAAO,KAAK,CAAC;IACxD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgC;IAC5D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,gBAAgB,CAAC;IAC9C,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC;IAEtD,sEAAsE;IACtE,oEAAoE;IACpE,IAAI,UAA6C,CAAC;IAElD,OAAO,YAAY,CAAwB;QACzC,IAAI;QACJ,OAAO,EAAE,OAAO;QAChB,QAAQ,EAAE,CAAC,aAAa,EAAE,aAAa,CAAC;QACxC,SAAS,CAAC,GAAG;YACX,GAAG,CAAC,eAAe,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;YACjD,GAAG,CAAC,eAAe,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;QACnD,CAAC;QACD,IAAI;YACF,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC1C,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,qBAAqB,CAAC,iBAAiB,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;YAClG,UAAU,GAAG,KAAK,CAAC;YACnB,MAAM,UAAU,GAAG,qBAAqB,CAAC,cAAc,CAAC,UAAU,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;YAC1F,OAAO,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,EAAE,CAAC;QAClD,CAAC;QACD,KAAK,CAAC,OAAO;YACX,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,UAAU,EAAE,CAAC;gBACnB,UAAU,GAAG,SAAS,CAAC;YACzB,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"dot.js","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAKH,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAIjD,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAE/F;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,4DAA4D;IAC5D,kBAAkB,EAAE,yBAAyB;CACrC,CAAC;AAuCX;;;;GAIG;AACH,SAAS,YAAY,CAAC,QAA4B;IAChD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC;IAC/D,KAAK,MAAM,IAAI,IAAI,wBAAwB,EAAE,CAAC;QAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;YAAE,OAAO,KAAK,CAAC;IACxD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgC;IAC5D,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC;IAEtD,sEAAsE;IACtE,oEAAoE;IACpE,IAAI,UAA6C,CAAC;IAElD,OAAO,GAAG,CAAC;QACT,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,OAAO;QAChB,SAAS,CAAC,GAAG;YACX,GAAG,CAAC,eAAe,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;YACjD,GAAG,CAAC,eAAe,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;YACjD,GAAG,CAAC,eAAe,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;QACpD,CAAC;QACD,IAAI;YACF,iEAAiE;YACjE,oEAAoE;YACpE,oEAAoE;YACpE,6DAA6D;YAC7D,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC1C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,IAAI,WAAW,CAAC;oBACpB,IAAI,EAAE,8BAA8B,CAAC,kBAAkB;oBACvD,OAAO,EAAE,8DAA8D;oBACvE,WAAW,EAAE,0DAA0D,wBAAwB,CAAC,IAAI,CAClG,IAAI,CACL,6CAA6C;oBAC9C,OAAO,EAAE,qDAAqD;iBAC/D,CAAC,CAAC;YACL,CAAC;YACD,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,qBAAqB,CAAC,iBAAiB,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;YAClG,UAAU,GAAG,KAAK,CAAC;YACnB,MAAM,UAAU,GAAG,qBAAqB,CAAC,cAAc,CAAC,UAAU,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;YAC1F,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;QACpC,CAAC;QACD,KAAK,CAAC,OAAO;YACX,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,UAAU,EAAE,CAAC;gBACnB,UAAU,GAAG,SAAS,CAAC;YACzB,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arki/event-sourcing",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Event sourcing primitives — event store, message bus, projections, process managers — built on Emmett for ARKI.",
   "license": "MIT",
   "repository": {
@@ -87,7 +87,7 @@
     "drizzle-orm": "1.0.0-rc.1"
   },
   "peerDependencies": {
-    "@arki/dot": "^0.1.0"
+    "@arki/dot": "^0.1.1"
   },
   "peerDependenciesMeta": {
     "@arki/dot": {

package/dist/package.json

@@ -1,5 +0,0 @@
-{
-  "name": "dist",
-  "version": "0.0.0",
-  "private": true
-}