@contractspec/lib.bus 0.0.0-canary-20260113162409

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaman Ventures, SASU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# @contractspec/lib.bus
+
+Website: https://contractspec.io/
+
+
+A lightweight, type-safe event bus for in-memory and distributed event handling.
+
+## Purpose
+
+To decouple components and services by allowing them to communicate via typed events. This library provides the core `EventBus` interface and implementations for local (in-memory) and potentially remote communication.
+
+## Installation
+
+```bash
+npm install @contractspec/lib.bus
+# or
+bun add @contractspec/lib.bus
+```
+
+## Key Concepts
+
+- **EventBus Interface**: A standard contract for `publish` and `subscribe`.
+- **Type Safety**: leveraging `@contractspec/lib.contracts` event definitions for payload validation.
+- **Decoupling**: Producers and consumers don't need to know about each other.
+
+## Exports
+
+- `EventBus`: The core interface.
+- `InMemoryEventBus`: A simple, synchronous/asynchronous in-memory implementation.
+- `NoOpEventBus`: A placeholder implementation for testing or disabling events.
+
+## Usage
+
+```tsx
+import { InMemoryEventBus } from '@contractspec/lib.bus';
+
+// 1. Create the bus
+const bus = new InMemoryEventBus();
+
+// 2. Subscribe to an event
+const unsubscribe = bus.subscribe('user.created', async (payload) => {
+  console.log('New user:', payload.userId);
+});
+
+// 3. Publish an event
+await bus.publish('user.created', { userId: '123', email: 'test@example.com' });
+
+// 4. Cleanup
+unsubscribe();
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/dist/auditableBus.d.ts

@@ -0,0 +1,117 @@
+import { EventBus } from "./eventBus.js";
+import { EventMetadata } from "./metadata.js";
+import { EventEnvelope, EventKey, EventSpec } from "@contractspec/lib.contracts";
+import { AnySchemaModel } from "@contractspec/lib.schema";
+
+//#region src/auditableBus.d.ts
+
+/**
+ * Extended event envelope with metadata for auditing.
+ */
+interface AuditableEventEnvelope<T = unknown> extends EventEnvelope<T> {
+  metadata?: EventMetadata;
+}
+/**
+ * Audit record for persisting event history.
+ */
+interface AuditRecord {
+  id: string;
+  eventKey: string;
+  eventVersion: string;
+  payload: unknown;
+  metadata?: EventMetadata;
+  occurredAt: string;
+  traceId?: string;
+  recordedAt: Date;
+}
+/**
+ * Audit storage adapter interface.
+ */
+interface AuditStorage {
+  /** Store an audit record */
+  store(record: AuditRecord): Promise<void>;
+  /** Query audit records */
+  query?(options: AuditQueryOptions): Promise<AuditRecord[]>;
+}
+/**
+ * Options for querying audit records.
+ */
+interface AuditQueryOptions {
+  eventKey?: string;
+  actorId?: string;
+  targetId?: string;
+  orgId?: string;
+  traceId?: string;
+  from?: Date;
+  to?: Date;
+  limit?: number;
+  offset?: number;
+}
+/**
+ * Options for creating an auditable event bus.
+ */
+interface AuditableEventBusOptions {
+  /** Underlying event bus for publishing */
+  bus: EventBus;
+  /** Audit storage adapter */
+  storage?: AuditStorage;
+  /** Default metadata to include with all events */
+  defaultMetadata?: EventMetadata;
+  /** Filter function to decide which events to audit */
+  shouldAudit?: (eventKey: string, envelope: AuditableEventEnvelope) => boolean;
+  /** Transform function for audit records */
+  transformAuditRecord?: (record: AuditRecord) => AuditRecord;
+}
+/**
+ * AuditableEventBus wraps an EventBus to automatically record events for audit trail.
+ */
+declare class AuditableEventBus implements EventBus {
+  private readonly bus;
+  private readonly storage?;
+  private readonly defaultMetadata;
+  private readonly shouldAudit;
+  private readonly transformAuditRecord?;
+  constructor(options: AuditableEventBusOptions);
+  /**
+   * Publish an event and optionally record it for audit.
+   */
+  publish(topic: EventKey, bytes: Uint8Array): Promise<void>;
+  /**
+   * Subscribe to events from the underlying bus.
+   */
+  subscribe(topic: EventKey | string, handler: (bytes: Uint8Array) => Promise<void>): Promise<() => Promise<void>>;
+  /**
+   * Query audit records (if storage supports it).
+   */
+  queryAudit(options: AuditQueryOptions): Promise<AuditRecord[]>;
+}
+/**
+ * Create an auditable publisher that includes metadata.
+ */
+declare function makeAuditablePublisher<T extends AnySchemaModel>(bus: AuditableEventBus | EventBus, spec: EventSpec<T>, defaultMetadata?: EventMetadata): (payload: T, options?: {
+  traceId?: string;
+  metadata?: EventMetadata;
+}) => Promise<void>;
+/**
+ * In-memory audit storage for development/testing.
+ */
+declare class InMemoryAuditStorage implements AuditStorage {
+  private records;
+  store(record: AuditRecord): Promise<void>;
+  query(options: AuditQueryOptions): Promise<AuditRecord[]>;
+  /**
+   * Get all records (for testing).
+   */
+  getAll(): AuditRecord[];
+  /**
+   * Clear all records (for testing).
+   */
+  clear(): void;
+}
+/**
+ * Create an auditable event bus with in-memory storage.
+ */
+declare function createAuditableEventBus(bus: EventBus, options?: Omit<AuditableEventBusOptions, 'bus'>): AuditableEventBus;
+//#endregion
+export { AuditQueryOptions, AuditRecord, AuditStorage, AuditableEventBus, AuditableEventBusOptions, AuditableEventEnvelope, InMemoryAuditStorage, createAuditableEventBus, makeAuditablePublisher };
+//# sourceMappingURL=auditableBus.d.ts.map

package/dist/auditableBus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auditableBus.d.ts","names":[],"sources":["../src/auditableBus.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAcA;AAA2E,UAA1D,sBAA0D,CAAA,IAAA,OAAA,CAAA,SAAd,aAAc,CAAA,CAAA,CAAA,CAAA;EAC9D,QAAA,CAAA,EAAA,aAAA;;;AAMb;AAcA;AAEgB,UAhBC,WAAA,CAgBD;EAAc,EAAA,EAAA,MAAA;EAEZ,QAAA,EAAA,MAAA;EAA4B,YAAA,EAAA,MAAA;EAAR,OAAA,EAAA,OAAA;EAAO,QAAA,CAAA,EAbhC,aAagC;EAM5B,UAAA,EAAA,MAAA;EAeA,OAAA,CAAA,EAAA,MAAA;EAEV,UAAA,EAjCO,IAiCP;;;;;AAQ2C,UAnCjC,YAAA,CAmCiC;EAAW;EAMhD,KAAA,CAAA,MAAA,EAvCG,WAuCe,CAAA,EAvCD,OAuCC,CAAA,IAAA,CAAA;EAUR;EAWA,KAAA,EAAA,OAAA,EA1DL,iBA0DK,CAAA,EA1De,OA0Df,CA1DuB,WA0DvB,EAAA,CAAA;;;;;AA0Ca,UA9FnB,iBAAA,CA8FmB;EACjB,QAAA,CAAA,EAAA,MAAA;EAAd,OAAA,CAAA,EAAA,MAAA;EAOuB,QAAA,CAAA,EAAA,MAAA;EAA4B,KAAA,CAAA,EAAA,MAAA;EAAR,OAAA,CAAA,EAAA,MAAA;EAvEN,IAAA,CAAA,EAzBjC,IAyBiC;EAAQ,EAAA,CAAA,EAxB3C,IAwB2C;EAkFlC,KAAA,CAAA,EAAA,MAAA;EAAiC,MAAA,CAAA,EAAA,MAAA;;;;;AAG7B,UArGH,wBAAA,CAqGG;EAGP;EACgC,GAAA,EAvGtC,QAuGsC;EAAe;EAAA,OAAA,CAAA,EArGhD,YAqGgD;EAwB/C;EAGS,eAAA,CAAA,EA9HF,aA8HE;EAAc;EAIb,WAAA,CAAA,EAAA,CAAA,QAAA,EAAA,MAAA,EAAA,QAAA,EAhIsB,sBAgItB,EAAA,GAAA,OAAA;EAA4B;EAAR,oBAAA,CAAA,EAAA,CAAA,MAAA,EA9HT,WA8HS,EAAA,GA9HO,WA8HP;;;;AAiE3C;AACO,cA1LM,iBAAA,YAA6B,QA0LnC,CAAA;EACU,iBAAA,GAAA;EAAL,iBAAA,OAAA;EACT,iBAAA,eAAA;EAAiB,iBAAA,WAAA;;uBAlLG;;;;iBAWA,iBAAiB,aAAa;;;;mBAyC1C,oCACU,eAAe,gBAC/B,cAAc;;;;sBAOS,oBAAoB,QAAQ;;;;;iBAWxC,iCAAiC,qBAC1C,oBAAoB,gBACnB,UAAU,sBACE,0BAGP;;aACgC;MAAe;;;;cAwB/C,oBAAA,YAAgC;;gBAGvB,cAAc;iBAIb,oBAAoB,QAAQ;;;;YAkDvC;;;;;;;;;iBAeI,uBAAA,MACT,oBACK,KAAK,mCACd"}

package/dist/auditableBus.js

@@ -0,0 +1,137 @@
+import { decodeEvent, encodeEvent } from "./eventBus.js";
+import { eventKey } from "@contractspec/lib.contracts";
+
+//#region src/auditableBus.ts
+/**
+* AuditableEventBus wraps an EventBus to automatically record events for audit trail.
+*/
+var AuditableEventBus = class {
+	bus;
+	storage;
+	defaultMetadata;
+	shouldAudit;
+	transformAuditRecord;
+	constructor(options) {
+		this.bus = options.bus;
+		this.storage = options.storage;
+		this.defaultMetadata = options.defaultMetadata ?? {};
+		this.shouldAudit = options.shouldAudit ?? (() => true);
+		this.transformAuditRecord = options.transformAuditRecord;
+	}
+	/**
+	* Publish an event and optionally record it for audit.
+	*/
+	async publish(topic, bytes) {
+		await this.bus.publish(topic, bytes);
+		if (this.storage) try {
+			const envelope = decodeEvent(bytes);
+			if (this.shouldAudit(envelope.key, envelope)) {
+				let record = {
+					id: crypto.randomUUID(),
+					eventKey: envelope.key,
+					eventVersion: envelope.version,
+					payload: envelope.payload,
+					metadata: {
+						...this.defaultMetadata,
+						...envelope.metadata
+					},
+					occurredAt: envelope.occurredAt,
+					traceId: envelope.traceId,
+					recordedAt: /* @__PURE__ */ new Date()
+				};
+				if (this.transformAuditRecord) record = this.transformAuditRecord(record);
+				await this.storage.store(record);
+			}
+		} catch (error) {
+			console.error("Failed to record audit:", error);
+		}
+	}
+	/**
+	* Subscribe to events from the underlying bus.
+	*/
+	async subscribe(topic, handler) {
+		return this.bus.subscribe(topic, handler);
+	}
+	/**
+	* Query audit records (if storage supports it).
+	*/
+	async queryAudit(options) {
+		if (!this.storage?.query) throw new Error("Audit storage does not support querying");
+		return this.storage.query(options);
+	}
+};
+/**
+* Create an auditable publisher that includes metadata.
+*/
+function makeAuditablePublisher(bus, spec, defaultMetadata) {
+	return async (payload, options) => {
+		const envelope = {
+			id: crypto.randomUUID(),
+			occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+			key: spec.meta.key,
+			version: spec.meta.version,
+			payload,
+			traceId: options?.traceId,
+			metadata: {
+				...defaultMetadata,
+				...options?.metadata
+			}
+		};
+		await bus.publish(eventKey(spec.meta.key, spec.meta.version), encodeEvent(envelope));
+	};
+}
+/**
+* In-memory audit storage for development/testing.
+*/
+var InMemoryAuditStorage = class {
+	records = [];
+	async store(record) {
+		this.records.push(record);
+	}
+	async query(options) {
+		let results = [...this.records];
+		if (options.eventKey) results = results.filter((r) => r.eventKey === options.eventKey);
+		if (options.actorId) results = results.filter((r) => r.metadata?.actorId === options.actorId);
+		if (options.targetId) results = results.filter((r) => r.metadata?.targetId === options.targetId);
+		if (options.orgId) results = results.filter((r) => r.metadata?.orgId === options.orgId);
+		if (options.traceId) results = results.filter((r) => r.traceId === options.traceId);
+		if (options.from) {
+			const from = options.from;
+			results = results.filter((r) => new Date(r.occurredAt) >= from);
+		}
+		if (options.to) {
+			const to = options.to;
+			results = results.filter((r) => new Date(r.occurredAt) <= to);
+		}
+		results.sort((a, b) => new Date(b.occurredAt).getTime() - new Date(a.occurredAt).getTime());
+		const offset = options.offset ?? 0;
+		const limit = options.limit ?? 100;
+		return results.slice(offset, offset + limit);
+	}
+	/**
+	* Get all records (for testing).
+	*/
+	getAll() {
+		return [...this.records];
+	}
+	/**
+	* Clear all records (for testing).
+	*/
+	clear() {
+		this.records = [];
+	}
+};
+/**
+* Create an auditable event bus with in-memory storage.
+*/
+function createAuditableEventBus(bus, options) {
+	return new AuditableEventBus({
+		bus,
+		storage: options?.storage ?? new InMemoryAuditStorage(),
+		...options
+	});
+}
+
+//#endregion
+export { AuditableEventBus, InMemoryAuditStorage, createAuditableEventBus, makeAuditablePublisher };
+//# sourceMappingURL=auditableBus.js.map

package/dist/auditableBus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auditableBus.js","names":[],"sources":["../src/auditableBus.ts"],"sourcesContent":["import {\n  type EventEnvelope,\n  type EventKey,\n  eventKey,\n  type EventSpec,\n} from '@contractspec/lib.contracts';\nimport type { AnySchemaModel } from '@contractspec/lib.schema';\nimport type { EventBus } from './eventBus';\nimport { encodeEvent, decodeEvent } from './eventBus';\nimport type { EventMetadata } from './metadata';\n\n/**\n * Extended event envelope with metadata for auditing.\n */\nexport interface AuditableEventEnvelope<T = unknown> extends EventEnvelope<T> {\n  metadata?: EventMetadata;\n}\n\n/**\n * Audit record for persisting event history.\n */\nexport interface AuditRecord {\n  id: string;\n  eventKey: string;\n  eventVersion: string;\n  payload: unknown;\n  metadata?: EventMetadata;\n  occurredAt: string;\n  traceId?: string;\n  recordedAt: Date;\n}\n\n/**\n * Audit storage adapter interface.\n */\nexport interface AuditStorage {\n  /** Store an audit record */\n  store(record: AuditRecord): Promise<void>;\n  /** Query audit records */\n  query?(options: AuditQueryOptions): Promise<AuditRecord[]>;\n}\n\n/**\n * Options for querying audit records.\n */\nexport interface AuditQueryOptions {\n  eventKey?: string;\n  actorId?: string;\n  targetId?: string;\n  orgId?: string;\n  traceId?: string;\n  from?: Date;\n  to?: Date;\n  limit?: number;\n  offset?: number;\n}\n\n/**\n * Options for creating an auditable event bus.\n */\nexport interface AuditableEventBusOptions {\n  /** Underlying event bus for publishing */\n  bus: EventBus;\n  /** Audit storage adapter */\n  storage?: AuditStorage;\n  /** Default metadata to include with all events */\n  defaultMetadata?: EventMetadata;\n  /** Filter function to decide which events to audit */\n  shouldAudit?: (eventKey: string, envelope: AuditableEventEnvelope) => boolean;\n  /** Transform function for audit records */\n  transformAuditRecord?: (record: AuditRecord) => AuditRecord;\n}\n\n/**\n * AuditableEventBus wraps an EventBus to automatically record events for audit trail.\n */\nexport class AuditableEventBus implements EventBus {\n  private readonly bus: EventBus;\n  private readonly storage?: AuditStorage;\n  private readonly defaultMetadata: EventMetadata;\n  private readonly shouldAudit: (\n    eventKey: string,\n    envelope: AuditableEventEnvelope\n  ) => boolean;\n  private readonly transformAuditRecord?: (record: AuditRecord) => AuditRecord;\n\n  constructor(options: AuditableEventBusOptions) {\n    this.bus = options.bus;\n    this.storage = options.storage;\n    this.defaultMetadata = options.defaultMetadata ?? {};\n    this.shouldAudit = options.shouldAudit ?? (() => true);\n    this.transformAuditRecord = options.transformAuditRecord;\n  }\n\n  /**\n   * Publish an event and optionally record it for audit.\n   */\n  async publish(topic: EventKey, bytes: Uint8Array): Promise<void> {\n    // Publish to underlying bus first\n    await this.bus.publish(topic, bytes);\n\n    // Record for audit if storage is configured\n    if (this.storage) {\n      try {\n        const envelope = decodeEvent<unknown>(bytes) as AuditableEventEnvelope;\n\n        if (this.shouldAudit(envelope.key, envelope)) {\n          let record: AuditRecord = {\n            id: crypto.randomUUID(),\n            eventKey: envelope.key,\n            eventVersion: envelope.version,\n            payload: envelope.payload,\n            metadata: {\n              ...this.defaultMetadata,\n              ...envelope.metadata,\n            },\n            occurredAt: envelope.occurredAt,\n            traceId: envelope.traceId,\n            recordedAt: new Date(),\n          };\n\n          if (this.transformAuditRecord) {\n            record = this.transformAuditRecord(record);\n          }\n\n          await this.storage.store(record);\n        }\n      } catch (error) {\n        // Log but don't fail publishing if audit fails\n        console.error('Failed to record audit:', error);\n      }\n    }\n  }\n\n  /**\n   * Subscribe to events from the underlying bus.\n   */\n  async subscribe(\n    topic: EventKey | string,\n    handler: (bytes: Uint8Array) => Promise<void>\n  ): Promise<() => Promise<void>> {\n    return this.bus.subscribe(topic, handler);\n  }\n\n  /**\n   * Query audit records (if storage supports it).\n   */\n  async queryAudit(options: AuditQueryOptions): Promise<AuditRecord[]> {\n    if (!this.storage?.query) {\n      throw new Error('Audit storage does not support querying');\n    }\n    return this.storage.query(options);\n  }\n}\n\n/**\n * Create an auditable publisher that includes metadata.\n */\nexport function makeAuditablePublisher<T extends AnySchemaModel>(\n  bus: AuditableEventBus | EventBus,\n  spec: EventSpec<T>,\n  defaultMetadata?: EventMetadata\n) {\n  return async (\n    payload: T,\n    options?: { traceId?: string; metadata?: EventMetadata }\n  ) => {\n    const envelope: AuditableEventEnvelope<T> = {\n      id: crypto.randomUUID(),\n      occurredAt: new Date().toISOString(),\n      key: spec.meta.key,\n      version: spec.meta.version,\n      payload,\n      traceId: options?.traceId,\n      metadata: {\n        ...defaultMetadata,\n        ...options?.metadata,\n      },\n    };\n    await bus.publish(\n      eventKey(spec.meta.key, spec.meta.version),\n      encodeEvent(envelope)\n    );\n  };\n}\n\n/**\n * In-memory audit storage for development/testing.\n */\nexport class InMemoryAuditStorage implements AuditStorage {\n  private records: AuditRecord[] = [];\n\n  async store(record: AuditRecord): Promise<void> {\n    this.records.push(record);\n  }\n\n  async query(options: AuditQueryOptions): Promise<AuditRecord[]> {\n    let results = [...this.records];\n\n    if (options.eventKey) {\n      results = results.filter((r) => r.eventKey === options.eventKey);\n    }\n\n    if (options.actorId) {\n      results = results.filter((r) => r.metadata?.actorId === options.actorId);\n    }\n\n    if (options.targetId) {\n      results = results.filter(\n        (r) => r.metadata?.targetId === options.targetId\n      );\n    }\n\n    if (options.orgId) {\n      results = results.filter((r) => r.metadata?.orgId === options.orgId);\n    }\n\n    if (options.traceId) {\n      results = results.filter((r) => r.traceId === options.traceId);\n    }\n\n    if (options.from) {\n      const from = options.from;\n      results = results.filter((r) => new Date(r.occurredAt) >= from);\n    }\n\n    if (options.to) {\n      const to = options.to;\n      results = results.filter((r) => new Date(r.occurredAt) <= to);\n    }\n\n    // Sort by occurredAt descending\n    results.sort(\n      (a, b) =>\n        new Date(b.occurredAt).getTime() - new Date(a.occurredAt).getTime()\n    );\n\n    // Apply pagination\n    const offset = options.offset ?? 0;\n    const limit = options.limit ?? 100;\n    return results.slice(offset, offset + limit);\n  }\n\n  /**\n   * Get all records (for testing).\n   */\n  getAll(): AuditRecord[] {\n    return [...this.records];\n  }\n\n  /**\n   * Clear all records (for testing).\n   */\n  clear(): void {\n    this.records = [];\n  }\n}\n\n/**\n * Create an auditable event bus with in-memory storage.\n */\nexport function createAuditableEventBus(\n  bus: EventBus,\n  options?: Omit<AuditableEventBusOptions, 'bus'>\n): AuditableEventBus {\n  return new AuditableEventBus({\n    bus,\n    storage: options?.storage ?? new InMemoryAuditStorage(),\n    ...options,\n  });\n}\n"],"mappings":"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"}

package/dist/eventBus.d.ts

@@ -0,0 +1,22 @@
+import { EventEnvelope, EventKey, EventSpec } from "@contractspec/lib.contracts";
+import { AnySchemaModel } from "@contractspec/lib.schema";
+
+//#region src/eventBus.d.ts
+interface EventBus {
+  publish: (topic: EventKey, bytes: Uint8Array) => Promise<void>;
+  subscribe: (topic: EventKey | string,
+  // allow wildcard if your broker supports it
+  handler: (bytes: Uint8Array) => Promise<void>) => Promise<() => Promise<void>>;
+}
+/** Helper to encode a typed event envelope into JSON string */
+declare function encodeEvent<T>(envelope: EventEnvelope<T>): Uint8Array;
+/** Helper to decode JSON string into a typed event envelope */
+declare function decodeEvent<T>(data: Uint8Array): EventEnvelope<T>;
+/**
+ * Create a typed publisher function for a given event spec.
+ * It ensures payload conformance at compile time and builds the correct topic.
+ */
+declare function makePublisher<T extends AnySchemaModel>(bus: EventBus, spec: EventSpec<T>): (payload: T, traceId?: string) => Promise<void>;
+//#endregion
+export { EventBus, decodeEvent, encodeEvent, makePublisher };
+//# sourceMappingURL=eventBus.d.ts.map

package/dist/eventBus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventBus.d.ts","names":[],"sources":["../src/eventBus.ts"],"sourcesContent":[],"mappings":";;;;UAQiB,QAAA;mBACE,iBAAiB,eAAe;EADlC,SAAA,EAAQ,CAAA,KAAA,EAGd,QAHc,GAAA,MAAA;EAAA;EACN,OAAA,EAAA,CAAA,KAAA,EAGE,UAHF,EAAA,GAGiB,OAHjB,CAAA,IAAA,CAAA,EAAA,GAIZ,OAJY,CAAA,GAAA,GAIE,OAJF,CAAA,IAAA,CAAA,CAAA;;;AAER,iBAMK,WANL,CAAA,CAAA,CAAA,CAAA,QAAA,EAM8B,aAN9B,CAM4C,CAN5C,CAAA,CAAA,EAMiD,UANjD;;AACyB,iBAUpB,WAVoB,CAAA,CAAA,CAAA,CAAA,IAAA,EAUC,UAVD,CAAA,EAUc,aAVd,CAU4B,CAV5B,CAAA;;;;AAKpC;AAAuD,iBAavC,aAbuC,CAAA,UAaf,cAbe,CAAA,CAAA,GAAA,EAchD,QAdgD,EAAA,IAAA,EAe/C,SAf+C,CAerC,CAfqC,CAAA,CAAA,EAAA,CAAA,OAAA,EAiB9B,CAjB8B,EAAA,OAAA,CAAA,EAAA,MAAA,EAAA,GAiBX,OAjBW,CAAA,IAAA,CAAA"}

package/dist/eventBus.js

@@ -0,0 +1,32 @@
+import { eventKey } from "@contractspec/lib.contracts";
+
+//#region src/eventBus.ts
+/** Helper to encode a typed event envelope into JSON string */
+function encodeEvent(envelope) {
+	return new TextEncoder().encode(JSON.stringify(envelope));
+}
+/** Helper to decode JSON string into a typed event envelope */
+function decodeEvent(data) {
+	return JSON.parse(new TextDecoder().decode(data));
+}
+/**
+* Create a typed publisher function for a given event spec.
+* It ensures payload conformance at compile time and builds the correct topic.
+*/
+function makePublisher(bus, spec) {
+	return async (payload, traceId) => {
+		const envelope = {
+			id: crypto.randomUUID(),
+			occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+			key: spec.meta.key,
+			version: spec.meta.version,
+			payload,
+			traceId
+		};
+		await bus.publish(eventKey(spec.meta.key, spec.meta.version), encodeEvent(envelope));
+	};
+}
+
+//#endregion
+export { decodeEvent, encodeEvent, makePublisher };
+//# sourceMappingURL=eventBus.js.map

package/dist/eventBus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventBus.js","names":[],"sources":["../src/eventBus.ts"],"sourcesContent":["import {\n  type EventEnvelope,\n  type EventKey,\n  eventKey,\n  type EventSpec,\n} from '@contractspec/lib.contracts';\nimport type { AnySchemaModel } from '@contractspec/lib.schema';\n\nexport interface EventBus {\n  publish: (topic: EventKey, bytes: Uint8Array) => Promise<void>;\n  subscribe: (\n    topic: EventKey | string, // allow wildcard if your broker supports it\n    handler: (bytes: Uint8Array) => Promise<void>\n  ) => Promise<() => Promise<void>>; // returns unsubscribe\n}\n\n/** Helper to encode a typed event envelope into JSON string */\nexport function encodeEvent<T>(envelope: EventEnvelope<T>): Uint8Array {\n  return new TextEncoder().encode(JSON.stringify(envelope));\n}\n\n/** Helper to decode JSON string into a typed event envelope */\nexport function decodeEvent<T>(data: Uint8Array): EventEnvelope<T> {\n  return JSON.parse(new TextDecoder().decode(data)) as EventEnvelope<T>;\n}\n\n/**\n * Create a typed publisher function for a given event spec.\n * It ensures payload conformance at compile time and builds the correct topic.\n */\nexport function makePublisher<T extends AnySchemaModel>(\n  bus: EventBus,\n  spec: EventSpec<T>\n) {\n  return async (payload: T, traceId?: string) => {\n    const envelope: EventEnvelope<T> = {\n      id: crypto.randomUUID(),\n      occurredAt: new Date().toISOString(),\n      key: spec.meta.key,\n      version: spec.meta.version,\n      payload,\n      traceId,\n    };\n    await bus.publish(\n      eventKey(spec.meta.key, spec.meta.version),\n      encodeEvent(envelope)\n    );\n  };\n}\n"],"mappings":";;;;AAiBA,SAAgB,YAAe,UAAwC;AACrE,QAAO,IAAI,aAAa,CAAC,OAAO,KAAK,UAAU,SAAS,CAAC;;;AAI3D,SAAgB,YAAe,MAAoC;AACjE,QAAO,KAAK,MAAM,IAAI,aAAa,CAAC,OAAO,KAAK,CAAC;;;;;;AAOnD,SAAgB,cACd,KACA,MACA;AACA,QAAO,OAAO,SAAY,YAAqB;EAC7C,MAAM,WAA6B;GACjC,IAAI,OAAO,YAAY;GACvB,6BAAY,IAAI,MAAM,EAAC,aAAa;GACpC,KAAK,KAAK,KAAK;GACf,SAAS,KAAK,KAAK;GACnB;GACA;GACD;AACD,QAAM,IAAI,QACR,SAAS,KAAK,KAAK,KAAK,KAAK,KAAK,QAAQ,EAC1C,YAAY,SAAS,CACtB"}

package/dist/filtering.d.ts

@@ -0,0 +1,83 @@
+import { EventBus } from "./eventBus.js";
+import { AuditableEventEnvelope } from "./auditableBus.js";
+import { EventKey, EventSpec } from "@contractspec/lib.contracts";
+import { AnySchemaModel } from "@contractspec/lib.schema";
+
+//#region src/filtering.d.ts
+
+/**
+ * Event filter configuration.
+ */
+interface EventFilter {
+  /** Filter by event name pattern (supports * wildcard) */
+  eventName?: string;
+  /** Filter by domain prefix */
+  domain?: string;
+  /** Filter by version */
+  version?: string;
+  /** Filter by actor ID */
+  actorId?: string;
+  /** Filter by organization ID */
+  orgId?: string;
+  /** Filter by custom tags */
+  tags?: Record<string, string>;
+  /** Custom predicate function */
+  predicate?: (envelope: AuditableEventEnvelope) => boolean;
+}
+/**
+ * Check if an event matches a filter.
+ */
+declare function matchesFilter(envelope: AuditableEventEnvelope, filter: EventFilter): boolean;
+/**
+ * Create a filtered subscriber that only receives matching events.
+ */
+declare function createFilteredSubscriber(bus: EventBus, filter: EventFilter, handler: (envelope: AuditableEventEnvelope) => Promise<void>): (topic: EventKey | string) => Promise<() => Promise<void>>;
+/**
+ * Domain-specific event bus that filters by domain prefix.
+ */
+declare class DomainEventBus {
+  private readonly bus;
+  private readonly domain;
+  constructor(bus: EventBus, domain: string);
+  /**
+   * Publish a domain event.
+   */
+  publish<T extends AnySchemaModel>(spec: EventSpec<T>, payload: T, metadata?: AuditableEventEnvelope['metadata']): Promise<void>;
+  /**
+   * Subscribe to all domain events.
+   */
+  subscribeAll(handler: (envelope: AuditableEventEnvelope) => Promise<void>): Promise<() => Promise<void>>;
+  /**
+   * Subscribe with filter.
+   */
+  subscribeFiltered(filter: Omit<EventFilter, 'domain'>, handler: (envelope: AuditableEventEnvelope) => Promise<void>): Promise<() => Promise<void>>;
+}
+/**
+ * Create a domain-scoped event bus.
+ */
+declare function createDomainBus(bus: EventBus, domain: string): DomainEventBus;
+/**
+ * Event router that routes events to different handlers based on filters.
+ */
+declare class EventRouter {
+  private routes;
+  /**
+   * Add a route.
+   */
+  route(filter: EventFilter, handler: (envelope: AuditableEventEnvelope) => Promise<void>): this;
+  /**
+   * Route an event to matching handlers.
+   */
+  dispatch(envelope: AuditableEventEnvelope): Promise<void>;
+  /**
+   * Create a subscriber that routes events.
+   */
+  createSubscriber(bus: EventBus): (topic: EventKey | string) => Promise<() => Promise<void>>;
+}
+/**
+ * Create an event router.
+ */
+declare function createEventRouter(): EventRouter;
+//#endregion
+export { DomainEventBus, EventFilter, EventRouter, createDomainBus, createEventRouter, createFilteredSubscriber, matchesFilter };
+//# sourceMappingURL=filtering.d.ts.map

package/dist/filtering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filtering.d.ts","names":[],"sources":["../src/filtering.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAUA;AAoBgB,UApBC,WAAA,CAoBY;EAyDb;EACT,SAAA,CAAA,EAAA,MAAA;EACG;EACY,MAAA,CAAA,EAAA,MAAA;EAA2B;EAE1B,OAAA,CAAA,EAAA,MAAA;EAAiB;EAAA,OAAA,CAAA,EAAA,MAAA;EAAA;EAc3B,KAAA,CAAA,EAAA,MAAA;EAEa;EAOA,IAAA,CAAA,EA7FjB,MA6FiB,CAAA,MAAA,EAAA,MAAA,CAAA;EACN;EAAV,SAAA,CAAA,EAAA,CAAA,QAAA,EA5Fe,sBA4Ff,EAAA,GAAA,OAAA;;;;;AA0ByC,iBAhHnC,aAAA,CAgHmC,QAAA,EA/GvC,sBA+GuC,EAAA,MAAA,EA9GzC,WA8GyC,CAAA,EAAA,OAAA;;;;AAavC,iBApEI,wBAAA,CAoEJ,GAAA,EAnEL,QAmEK,EAAA,MAAA,EAlEF,WAkEE,EAAA,OAAA,EAAA,CAAA,QAAA,EAjEU,sBAiEV,EAAA,GAjEqC,OAiErC,CAAA,IAAA,CAAA,CAAA,EAAA,CAAA,KAAA,EA/DW,QA+DX,GAAA,MAAA,EAAA,GA/D4B,OA+D5B,CAAA,GAAA,GA/D4B,OA+D5B,CAAA,IAAA,CAAA,CAAA;;;;AAEP,cAnDQ,cAAA,CAmDR;EAAO,iBAAA,GAAA;EAmBI,iBAAA,MAAe;EAOlB,WAAA,CAAA,GAAW,EA3EE,QA2EF,EAAA,MAAA,EAAA,MAAA;EAUZ;;;EAUe,OAAA,CAAA,UAxFD,cAwFC,CAAA,CAAA,IAAA,EAvFjB,SAuFiB,CAvFP,CAuFO,CAAA,EAAA,OAAA,EAtFd,CAsFc,EAAA,QAAA,CAAA,EArFZ,sBAqFY,CAAA,UAAA,CAAA,CAAA,EApFtB,OAoFsB,CAAA,IAAA,CAAA;EAAyB;;;EAaH,YAAA,CAAA,OAAA,EAAA,CAAA,QAAA,EA1EzB,sBA0EyB,EAAA,GA1EE,OA0EF,CAAA,IAAA,CAAA,CAAA,EAzE5C,OAyE4C,CAAA,GAAA,GAzE9B,OAyE8B,CAAA,IAAA,CAAA,CAAA;EAAd;;AAanC;4BA1EY,KAAK,4CACO,2BAA2B,gBAC9C,cAAc;;;;;iBAmBH,eAAA,MAAqB,2BAA2B;;;;cAOnD,WAAA;;;;;gBAUD,iCACY,2BAA2B;;;;qBASxB,yBAAyB;;;;wBAY3C,mBACI,sBAAsB,cAAc;;;;;iBAajC,iBAAA,CAAA,GAAqB"}

package/dist/filtering.js

@@ -0,0 +1,134 @@
+import { decodeEvent } from "./eventBus.js";
+import { satisfies } from "compare-versions";
+
+//#region src/filtering.ts
+/**
+* Check if an event matches a filter.
+*/
+function matchesFilter(envelope, filter) {
+	if (filter.eventName) {
+		const pattern = filter.eventName.replace(/\*/g, ".*");
+		if (!(/* @__PURE__ */ new RegExp(`^${pattern}$`)).test(envelope.key)) return false;
+	}
+	if (filter.domain) {
+		if (!envelope.key.startsWith(filter.domain + ".")) return false;
+	}
+	if (filter.version) {
+		if (!envelope.version || !satisfies(envelope.version, filter.version)) return false;
+	}
+	if (filter.actorId && envelope.metadata?.actorId !== filter.actorId) return false;
+	if (filter.orgId && envelope.metadata?.orgId !== filter.orgId) return false;
+	if (filter.tags) {
+		const eventTags = envelope.metadata?.tags ?? {};
+		for (const [key, value] of Object.entries(filter.tags)) if (eventTags[key] !== value) return false;
+	}
+	if (filter.predicate && !filter.predicate(envelope)) return false;
+	return true;
+}
+/**
+* Create a filtered subscriber that only receives matching events.
+*/
+function createFilteredSubscriber(bus, filter, handler) {
+	return async (topic) => {
+		return bus.subscribe(topic, async (bytes) => {
+			const envelope = decodeEvent(bytes);
+			if (matchesFilter(envelope, filter)) await handler(envelope);
+		});
+	};
+}
+/**
+* Domain-specific event bus that filters by domain prefix.
+*/
+var DomainEventBus = class {
+	constructor(bus, domain) {
+		this.bus = bus;
+		this.domain = domain;
+	}
+	/**
+	* Publish a domain event.
+	*/
+	async publish(spec, payload, metadata) {
+		const eventName = spec.meta.key.startsWith(this.domain + ".") ? spec.meta.key : `${this.domain}.${spec.meta.key}`;
+		const envelope = {
+			id: crypto.randomUUID(),
+			occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+			key: eventName,
+			version: spec.meta.version,
+			payload,
+			metadata
+		};
+		const bytes = new TextEncoder().encode(JSON.stringify(envelope));
+		await this.bus.publish(`${eventName}.v${spec.meta.version}`, bytes);
+	}
+	/**
+	* Subscribe to all domain events.
+	*/
+	async subscribeAll(handler) {
+		return this.bus.subscribe(`${this.domain}.*`, async (bytes) => {
+			await handler(decodeEvent(bytes));
+		});
+	}
+	/**
+	* Subscribe with filter.
+	*/
+	async subscribeFiltered(filter, handler) {
+		const fullFilter = {
+			...filter,
+			domain: this.domain
+		};
+		return this.bus.subscribe(`${this.domain}.*`, async (bytes) => {
+			const envelope = decodeEvent(bytes);
+			if (matchesFilter(envelope, fullFilter)) await handler(envelope);
+		});
+	}
+};
+/**
+* Create a domain-scoped event bus.
+*/
+function createDomainBus(bus, domain) {
+	return new DomainEventBus(bus, domain);
+}
+/**
+* Event router that routes events to different handlers based on filters.
+*/
+var EventRouter = class {
+	routes = [];
+	/**
+	* Add a route.
+	*/
+	route(filter, handler) {
+		this.routes.push({
+			filter,
+			handler
+		});
+		return this;
+	}
+	/**
+	* Route an event to matching handlers.
+	*/
+	async dispatch(envelope) {
+		const matchingRoutes = this.routes.filter((r) => matchesFilter(envelope, r.filter));
+		await Promise.all(matchingRoutes.map((r) => r.handler(envelope)));
+	}
+	/**
+	* Create a subscriber that routes events.
+	*/
+	createSubscriber(bus) {
+		return async (topic) => {
+			return bus.subscribe(topic, async (bytes) => {
+				const envelope = decodeEvent(bytes);
+				await this.dispatch(envelope);
+			});
+		};
+	}
+};
+/**
+* Create an event router.
+*/
+function createEventRouter() {
+	return new EventRouter();
+}
+
+//#endregion
+export { DomainEventBus, EventRouter, createDomainBus, createEventRouter, createFilteredSubscriber, matchesFilter };
+//# sourceMappingURL=filtering.js.map

package/dist/filtering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filtering.js","names":[],"sources":["../src/filtering.ts"],"sourcesContent":["import type { EventKey, EventSpec } from '@contractspec/lib.contracts';\nimport type { AnySchemaModel } from '@contractspec/lib.schema';\nimport type { EventBus } from './eventBus';\nimport { decodeEvent } from './eventBus';\nimport type { AuditableEventEnvelope } from './auditableBus';\nimport { satisfies } from 'compare-versions';\n\n/**\n * Event filter configuration.\n */\nexport interface EventFilter {\n  /** Filter by event name pattern (supports * wildcard) */\n  eventName?: string;\n  /** Filter by domain prefix */\n  domain?: string;\n  /** Filter by version */\n  version?: string;\n  /** Filter by actor ID */\n  actorId?: string;\n  /** Filter by organization ID */\n  orgId?: string;\n  /** Filter by custom tags */\n  tags?: Record<string, string>;\n  /** Custom predicate function */\n  predicate?: (envelope: AuditableEventEnvelope) => boolean;\n}\n\n/**\n * Check if an event matches a filter.\n */\nexport function matchesFilter(\n  envelope: AuditableEventEnvelope,\n  filter: EventFilter\n): boolean {\n  // Check event name pattern\n  if (filter.eventName) {\n    const pattern = filter.eventName.replace(/\\*/g, '.*');\n    const regex = new RegExp(`^${pattern}$`);\n    if (!regex.test(envelope.key)) {\n      return false;\n    }\n  }\n\n  // Check domain prefix\n  if (filter.domain) {\n    if (!envelope.key.startsWith(filter.domain + '.')) {\n      return false;\n    }\n  }\n\n  // Check version\n  if (filter.version) {\n    if (!envelope.version || !satisfies(envelope.version, filter.version)) {\n      return false;\n    }\n  }\n\n  // Check metadata fields\n  if (filter.actorId && envelope.metadata?.actorId !== filter.actorId) {\n    return false;\n  }\n\n  if (filter.orgId && envelope.metadata?.orgId !== filter.orgId) {\n    return false;\n  }\n\n  // Check tags\n  if (filter.tags) {\n    const eventTags = envelope.metadata?.tags ?? {};\n    for (const [key, value] of Object.entries(filter.tags)) {\n      if (eventTags[key] !== value) {\n        return false;\n      }\n    }\n  }\n\n  // Custom predicate\n  if (filter.predicate && !filter.predicate(envelope)) {\n    return false;\n  }\n\n  return true;\n}\n\n/**\n * Create a filtered subscriber that only receives matching events.\n */\nexport function createFilteredSubscriber(\n  bus: EventBus,\n  filter: EventFilter,\n  handler: (envelope: AuditableEventEnvelope) => Promise<void>\n) {\n  return async (topic: EventKey | string) => {\n    return bus.subscribe(topic, async (bytes) => {\n      const envelope = decodeEvent<unknown>(bytes) as AuditableEventEnvelope;\n\n      if (matchesFilter(envelope, filter)) {\n        await handler(envelope);\n      }\n    });\n  };\n}\n\n/**\n * Domain-specific event bus that filters by domain prefix.\n */\nexport class DomainEventBus {\n  constructor(\n    private readonly bus: EventBus,\n    private readonly domain: string\n  ) {}\n\n  /**\n   * Publish a domain event.\n   */\n  async publish<T extends AnySchemaModel>(\n    spec: EventSpec<T>,\n    payload: T,\n    metadata?: AuditableEventEnvelope['metadata']\n  ): Promise<void> {\n    // Ensure event name starts with domain\n    const eventName = spec.meta.key.startsWith(this.domain + '.')\n      ? spec.meta.key\n      : `${this.domain}.${spec.meta.key}`;\n\n    const envelope: AuditableEventEnvelope<T> = {\n      id: crypto.randomUUID(),\n      occurredAt: new Date().toISOString(),\n      key: eventName,\n      version: spec.meta.version,\n      payload,\n      metadata,\n    };\n\n    const bytes = new TextEncoder().encode(JSON.stringify(envelope));\n    await this.bus.publish(`${eventName}.v${spec.meta.version}`, bytes);\n  }\n\n  /**\n   * Subscribe to all domain events.\n   */\n  async subscribeAll(\n    handler: (envelope: AuditableEventEnvelope) => Promise<void>\n  ): Promise<() => Promise<void>> {\n    // Subscribe to wildcard pattern if supported\n    return this.bus.subscribe(`${this.domain}.*`, async (bytes) => {\n      const envelope = decodeEvent<unknown>(bytes) as AuditableEventEnvelope;\n      await handler(envelope);\n    });\n  }\n\n  /**\n   * Subscribe with filter.\n   */\n  async subscribeFiltered(\n    filter: Omit<EventFilter, 'domain'>,\n    handler: (envelope: AuditableEventEnvelope) => Promise<void>\n  ): Promise<() => Promise<void>> {\n    const fullFilter: EventFilter = {\n      ...filter,\n      domain: this.domain,\n    };\n\n    return this.bus.subscribe(`${this.domain}.*`, async (bytes) => {\n      const envelope = decodeEvent<unknown>(bytes) as AuditableEventEnvelope;\n\n      if (matchesFilter(envelope, fullFilter)) {\n        await handler(envelope);\n      }\n    });\n  }\n}\n\n/**\n * Create a domain-scoped event bus.\n */\nexport function createDomainBus(bus: EventBus, domain: string): DomainEventBus {\n  return new DomainEventBus(bus, domain);\n}\n\n/**\n * Event router that routes events to different handlers based on filters.\n */\nexport class EventRouter {\n  private routes: {\n    filter: EventFilter;\n    handler: (envelope: AuditableEventEnvelope) => Promise<void>;\n  }[] = [];\n\n  /**\n   * Add a route.\n   */\n  route(\n    filter: EventFilter,\n    handler: (envelope: AuditableEventEnvelope) => Promise<void>\n  ): this {\n    this.routes.push({ filter, handler });\n    return this;\n  }\n\n  /**\n   * Route an event to matching handlers.\n   */\n  async dispatch(envelope: AuditableEventEnvelope): Promise<void> {\n    const matchingRoutes = this.routes.filter((r) =>\n      matchesFilter(envelope, r.filter)\n    );\n\n    await Promise.all(matchingRoutes.map((r) => r.handler(envelope)));\n  }\n\n  /**\n   * Create a subscriber that routes events.\n   */\n  createSubscriber(\n    bus: EventBus\n  ): (topic: EventKey | string) => Promise<() => Promise<void>> {\n    return async (topic: EventKey | string) => {\n      return bus.subscribe(topic, async (bytes) => {\n        const envelope = decodeEvent<unknown>(bytes) as AuditableEventEnvelope;\n        await this.dispatch(envelope);\n      });\n    };\n  }\n}\n\n/**\n * Create an event router.\n */\nexport function createEventRouter(): EventRouter {\n  return new EventRouter();\n}\n"],"mappings":"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"}

package/dist/inMemoryBus.d.ts

@@ -0,0 +1,17 @@
+import { EventBus } from "./eventBus.js";
+import { EventKey } from "@contractspec/lib.contracts";
+
+//#region src/inMemoryBus.d.ts
+
+/**
+ * In-memory bus for dev/test. Not for production scale.
+ * Subscribers receive events synchronously in the order they were published.
+ */
+declare class InMemoryBus implements EventBus {
+  private listeners;
+  publish(topic: EventKey, payload: Uint8Array): Promise<void>;
+  subscribe(topic: string | RegExp, handler: (payload: Uint8Array) => Promise<void>): Promise<() => Promise<void>>;
+}
+//#endregion
+export { InMemoryBus };
+//# sourceMappingURL=inMemoryBus.d.ts.map

package/dist/inMemoryBus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inMemoryBus.d.ts","names":[],"sources":["../src/inMemoryBus.ts"],"sourcesContent":[],"mappings":";;;;;;;AAOA;;AAM0C,cAN7B,WAAA,YAAuB,QAMM,CAAA;EAAa,QAAA,SAAA;EAOnC,OAAA,CAAA,KAAA,EAPG,QAOH,EAAA,OAAA,EAPsB,UAOtB,CAAA,EAPmC,OAOnC,CAAA,IAAA,CAAA;EACG,SAAA,CAAA,KAAA,EAAA,MAAA,GADH,MACG,EAAA,OAAA,EAAA,CAAA,OAAA,EAAA,UAAA,EAAA,GAAe,OAAf,CAAA,IAAA,CAAA,CAAA,EAClB,OADkB,CAAA,GAAA,GACJ,OADI,CAAA,IAAA,CAAA,CAAA"}

package/dist/inMemoryBus.js

@@ -0,0 +1,29 @@
+//#region src/inMemoryBus.ts
+/**
+* In-memory bus for dev/test. Not for production scale.
+* Subscribers receive events synchronously in the order they were published.
+*/
+var InMemoryBus = class {
+	listeners = /* @__PURE__ */ new Map();
+	async publish(topic, payload) {
+		const handlers = this.listeners.get(topic);
+		if (!handlers) return;
+		await Promise.all([...handlers].map((h) => h(payload)));
+	}
+	async subscribe(topic, handler) {
+		const topicStr = String(topic);
+		let set = this.listeners.get(topicStr);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.listeners.set(topicStr, set);
+		}
+		set.add(handler);
+		return async () => {
+			set?.delete(handler);
+		};
+	}
+};
+
+//#endregion
+export { InMemoryBus };
+//# sourceMappingURL=inMemoryBus.js.map

package/dist/inMemoryBus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inMemoryBus.js","names":[],"sources":["../src/inMemoryBus.ts"],"sourcesContent":["import type { EventKey } from '@contractspec/lib.contracts';\nimport type { EventBus } from './eventBus';\n\n/**\n * In-memory bus for dev/test. Not for production scale.\n * Subscribers receive events synchronously in the order they were published.\n */\nexport class InMemoryBus implements EventBus {\n  private listeners = new Map<\n    string,\n    Set<(payload: Uint8Array) => Promise<void>>\n  >();\n\n  async publish(topic: EventKey, payload: Uint8Array): Promise<void> {\n    const handlers = this.listeners.get(topic);\n    if (!handlers) return;\n    await Promise.all([...handlers].map((h) => h(payload)));\n  }\n\n  async subscribe(\n    topic: string | RegExp,\n    handler: (payload: Uint8Array) => Promise<void>\n  ): Promise<() => Promise<void>> {\n    const topicStr = String(topic);\n    let set = this.listeners.get(topicStr);\n    if (!set) {\n      set = new Set();\n      this.listeners.set(topicStr, set);\n    }\n    set.add(handler);\n    return async () => {\n      set?.delete(handler);\n    };\n  }\n}\n"],"mappings":";;;;;AAOA,IAAa,cAAb,MAA6C;CAC3C,AAAQ,4BAAY,IAAI,KAGrB;CAEH,MAAM,QAAQ,OAAiB,SAAoC;EACjE,MAAM,WAAW,KAAK,UAAU,IAAI,MAAM;AAC1C,MAAI,CAAC,SAAU;AACf,QAAM,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC,KAAK,MAAM,EAAE,QAAQ,CAAC,CAAC;;CAGzD,MAAM,UACJ,OACA,SAC8B;EAC9B,MAAM,WAAW,OAAO,MAAM;EAC9B,IAAI,MAAM,KAAK,UAAU,IAAI,SAAS;AACtC,MAAI,CAAC,KAAK;AACR,yBAAM,IAAI,KAAK;AACf,QAAK,UAAU,IAAI,UAAU,IAAI;;AAEnC,MAAI,IAAI,QAAQ;AAChB,SAAO,YAAY;AACjB,QAAK,OAAO,QAAQ"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { EventBus, decodeEvent, encodeEvent, makePublisher } from "./eventBus.js";
+import { EventMetadata, MetadataContext, createMetadataContext, createMetadataFromContext, mergeMetadata } from "./metadata.js";
+import { AuditQueryOptions, AuditRecord, AuditStorage, AuditableEventBus, AuditableEventBusOptions, AuditableEventEnvelope, InMemoryAuditStorage, createAuditableEventBus, makeAuditablePublisher } from "./auditableBus.js";
+import { DomainEventBus, EventFilter, EventRouter, createDomainBus, createEventRouter, createFilteredSubscriber, matchesFilter } from "./filtering.js";
+import { InMemoryBus } from "./inMemoryBus.js";
+import { subscribeEvent } from "./subscriber.js";
+export { AuditQueryOptions, AuditRecord, AuditStorage, AuditableEventBus, AuditableEventBusOptions, AuditableEventEnvelope, DomainEventBus, EventBus, EventFilter, EventMetadata, EventRouter, InMemoryAuditStorage, InMemoryBus, MetadataContext, createAuditableEventBus, createDomainBus, createEventRouter, createFilteredSubscriber, createMetadataContext, createMetadataFromContext, decodeEvent, encodeEvent, makeAuditablePublisher, makePublisher, matchesFilter, mergeMetadata, subscribeEvent };

package/dist/index.js

@@ -0,0 +1,8 @@
+import { decodeEvent, encodeEvent, makePublisher } from "./eventBus.js";
+import { AuditableEventBus, InMemoryAuditStorage, createAuditableEventBus, makeAuditablePublisher } from "./auditableBus.js";
+import { DomainEventBus, EventRouter, createDomainBus, createEventRouter, createFilteredSubscriber, matchesFilter } from "./filtering.js";
+import { InMemoryBus } from "./inMemoryBus.js";
+import { subscribeEvent } from "./subscriber.js";
+import { MetadataContext, createMetadataContext, createMetadataFromContext, mergeMetadata } from "./metadata.js";
+
+export { AuditableEventBus, DomainEventBus, EventRouter, InMemoryAuditStorage, InMemoryBus, MetadataContext, createAuditableEventBus, createDomainBus, createEventRouter, createFilteredSubscriber, createMetadataContext, createMetadataFromContext, decodeEvent, encodeEvent, makeAuditablePublisher, makePublisher, matchesFilter, mergeMetadata, subscribeEvent };

package/dist/metadata.d.ts

@@ -0,0 +1,82 @@
+//#region src/metadata.d.ts
+/**
+ * Event metadata that enriches events with contextual information.
+ */
+interface EventMetadata {
+  /** ID of the actor (user) who triggered the event */
+  actorId?: string;
+  /** Type of actor (user, system, service) */
+  actorType?: 'user' | 'system' | 'service';
+  /** Target resource ID */
+  targetId?: string;
+  /** Target resource type */
+  targetType?: string;
+  /** Organization context */
+  orgId?: string;
+  /** Tenant context (if different from org) */
+  tenantId?: string;
+  /** Distributed trace ID */
+  traceId?: string;
+  /** Parent span ID */
+  spanId?: string;
+  /** Client IP address */
+  clientIp?: string;
+  /** Client user agent */
+  userAgent?: string;
+  /** Session ID */
+  sessionId?: string;
+  /** Request ID */
+  requestId?: string;
+  /** Source service name */
+  source?: string;
+  /** Correlation ID for related events */
+  correlationId?: string;
+  /** Custom tags for filtering/routing */
+  tags?: Record<string, string>;
+}
+/**
+ * Create metadata from request context.
+ */
+declare function createMetadataFromContext(context: {
+  userId?: string;
+  orgId?: string;
+  sessionId?: string;
+  requestId?: string;
+  traceId?: string;
+  clientIp?: string;
+  userAgent?: string;
+}): EventMetadata;
+/**
+ * Merge metadata with overrides.
+ */
+declare function mergeMetadata(base: EventMetadata, overrides: Partial<EventMetadata>): EventMetadata;
+/**
+ * Create a metadata context that can be passed through operations.
+ */
+declare class MetadataContext {
+  private metadata;
+  constructor(initial?: EventMetadata);
+  /**
+   * Get the current metadata.
+   */
+  get(): EventMetadata;
+  /**
+   * Set a metadata value.
+   */
+  set<K extends keyof EventMetadata>(key: K, value: EventMetadata[K]): this;
+  /**
+   * Add a tag.
+   */
+  tag(key: string, value: string): this;
+  /**
+   * Create a child context with the same trace.
+   */
+  child(overrides?: Partial<EventMetadata>): MetadataContext;
+}
+/**
+ * Create a new metadata context.
+ */
+declare function createMetadataContext(initial?: EventMetadata): MetadataContext;
+//#endregion
+export { EventMetadata, MetadataContext, createMetadataContext, createMetadataFromContext, mergeMetadata };
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","names":[],"sources":["../src/metadata.ts"],"sourcesContent":[],"mappings":";;AAGA;AAoCA;AAyBgB,UA7DC,aAAA,CA6DY;EACrB;EACa,OAAA,CAAA,EAAA,MAAA;EAAR;EACV,SAAA,CAAA,EAAA,MAAA,GAAA,QAAA,GAAA,SAAA;EAAa;EAcH,QAAA,CAAA,EAAA,MAAA;EAGU;EAUd,UAAA,CAAA,EAAA,MAAA;EAOa;EAAoB,KAAA,CAAA,EAAA,MAAA;EAAU;EAAc,QAAA,CAAA,EAAA,MAAA;EAgBvC;EAAR,OAAA,CAAA,EAAA,MAAA;EAA8B;EAAe,MAAA,CAAA,EAAA,MAAA;EAahD;;;;;;;;;;;;;SAjGP;;;;;iBAMO,yBAAA;;;;;;;;IAQZ;;;;iBAiBY,aAAA,OACR,0BACK,QAAQ,iBAClB;;;;cAcU,eAAA;;wBAGU;;;;SAUd;;;;sBAOa,oBAAoB,UAAU,cAAc;;;;;;;;oBAgB/C,QAAQ,iBAAsB;;;;;iBAajC,qBAAA,WACJ,gBACT"}

package/dist/metadata.js

@@ -0,0 +1,82 @@
+//#region src/metadata.ts
+/**
+* Create metadata from request context.
+*/
+function createMetadataFromContext(context) {
+	return {
+		actorId: context.userId,
+		actorType: context.userId ? "user" : "system",
+		orgId: context.orgId,
+		tenantId: context.orgId,
+		sessionId: context.sessionId,
+		requestId: context.requestId,
+		traceId: context.traceId || crypto.randomUUID(),
+		clientIp: context.clientIp,
+		userAgent: context.userAgent
+	};
+}
+/**
+* Merge metadata with overrides.
+*/
+function mergeMetadata(base, overrides) {
+	return {
+		...base,
+		...overrides,
+		tags: {
+			...base.tags,
+			...overrides.tags
+		}
+	};
+}
+/**
+* Create a metadata context that can be passed through operations.
+*/
+var MetadataContext = class MetadataContext {
+	metadata;
+	constructor(initial = {}) {
+		this.metadata = { ...initial };
+		if (!this.metadata.traceId) this.metadata.traceId = crypto.randomUUID();
+	}
+	/**
+	* Get the current metadata.
+	*/
+	get() {
+		return { ...this.metadata };
+	}
+	/**
+	* Set a metadata value.
+	*/
+	set(key, value) {
+		this.metadata[key] = value;
+		return this;
+	}
+	/**
+	* Add a tag.
+	*/
+	tag(key, value) {
+		this.metadata.tags = {
+			...this.metadata.tags,
+			[key]: value
+		};
+		return this;
+	}
+	/**
+	* Create a child context with the same trace.
+	*/
+	child(overrides = {}) {
+		return new MetadataContext(mergeMetadata(this.metadata, {
+			...overrides,
+			spanId: crypto.randomUUID()
+		}));
+	}
+};
+/**
+* Create a new metadata context.
+*/
+function createMetadataContext(initial) {
+	return new MetadataContext(initial);
+}
+
+//#endregion
+export { MetadataContext, createMetadataContext, createMetadataFromContext, mergeMetadata };
+//# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","names":[],"sources":["../src/metadata.ts"],"sourcesContent":["/**\n * Event metadata that enriches events with contextual information.\n */\nexport interface EventMetadata {\n  /** ID of the actor (user) who triggered the event */\n  actorId?: string;\n  /** Type of actor (user, system, service) */\n  actorType?: 'user' | 'system' | 'service';\n  /** Target resource ID */\n  targetId?: string;\n  /** Target resource type */\n  targetType?: string;\n  /** Organization context */\n  orgId?: string;\n  /** Tenant context (if different from org) */\n  tenantId?: string;\n  /** Distributed trace ID */\n  traceId?: string;\n  /** Parent span ID */\n  spanId?: string;\n  /** Client IP address */\n  clientIp?: string;\n  /** Client user agent */\n  userAgent?: string;\n  /** Session ID */\n  sessionId?: string;\n  /** Request ID */\n  requestId?: string;\n  /** Source service name */\n  source?: string;\n  /** Correlation ID for related events */\n  correlationId?: string;\n  /** Custom tags for filtering/routing */\n  tags?: Record<string, string>;\n}\n\n/**\n * Create metadata from request context.\n */\nexport function createMetadataFromContext(context: {\n  userId?: string;\n  orgId?: string;\n  sessionId?: string;\n  requestId?: string;\n  traceId?: string;\n  clientIp?: string;\n  userAgent?: string;\n}): EventMetadata {\n  return {\n    actorId: context.userId,\n    actorType: context.userId ? 'user' : 'system',\n    orgId: context.orgId,\n    tenantId: context.orgId,\n    sessionId: context.sessionId,\n    requestId: context.requestId,\n    traceId: context.traceId || crypto.randomUUID(),\n    clientIp: context.clientIp,\n    userAgent: context.userAgent,\n  };\n}\n\n/**\n * Merge metadata with overrides.\n */\nexport function mergeMetadata(\n  base: EventMetadata,\n  overrides: Partial<EventMetadata>\n): EventMetadata {\n  return {\n    ...base,\n    ...overrides,\n    tags: {\n      ...base.tags,\n      ...overrides.tags,\n    },\n  };\n}\n\n/**\n * Create a metadata context that can be passed through operations.\n */\nexport class MetadataContext {\n  private metadata: EventMetadata;\n\n  constructor(initial: EventMetadata = {}) {\n    this.metadata = { ...initial };\n    if (!this.metadata.traceId) {\n      this.metadata.traceId = crypto.randomUUID();\n    }\n  }\n\n  /**\n   * Get the current metadata.\n   */\n  get(): EventMetadata {\n    return { ...this.metadata };\n  }\n\n  /**\n   * Set a metadata value.\n   */\n  set<K extends keyof EventMetadata>(key: K, value: EventMetadata[K]): this {\n    this.metadata[key] = value;\n    return this;\n  }\n\n  /**\n   * Add a tag.\n   */\n  tag(key: string, value: string): this {\n    this.metadata.tags = { ...this.metadata.tags, [key]: value };\n    return this;\n  }\n\n  /**\n   * Create a child context with the same trace.\n   */\n  child(overrides: Partial<EventMetadata> = {}): MetadataContext {\n    return new MetadataContext(\n      mergeMetadata(this.metadata, {\n        ...overrides,\n        spanId: crypto.randomUUID(),\n      })\n    );\n  }\n}\n\n/**\n * Create a new metadata context.\n */\nexport function createMetadataContext(\n  initial?: EventMetadata\n): MetadataContext {\n  return new MetadataContext(initial);\n}\n"],"mappings":";;;;AAuCA,SAAgB,0BAA0B,SAQxB;AAChB,QAAO;EACL,SAAS,QAAQ;EACjB,WAAW,QAAQ,SAAS,SAAS;EACrC,OAAO,QAAQ;EACf,UAAU,QAAQ;EAClB,WAAW,QAAQ;EACnB,WAAW,QAAQ;EACnB,SAAS,QAAQ,WAAW,OAAO,YAAY;EAC/C,UAAU,QAAQ;EAClB,WAAW,QAAQ;EACpB;;;;;AAMH,SAAgB,cACd,MACA,WACe;AACf,QAAO;EACL,GAAG;EACH,GAAG;EACH,MAAM;GACJ,GAAG,KAAK;GACR,GAAG,UAAU;GACd;EACF;;;;;AAMH,IAAa,kBAAb,MAAa,gBAAgB;CAC3B,AAAQ;CAER,YAAY,UAAyB,EAAE,EAAE;AACvC,OAAK,WAAW,EAAE,GAAG,SAAS;AAC9B,MAAI,CAAC,KAAK,SAAS,QACjB,MAAK,SAAS,UAAU,OAAO,YAAY;;;;;CAO/C,MAAqB;AACnB,SAAO,EAAE,GAAG,KAAK,UAAU;;;;;CAM7B,IAAmC,KAAQ,OAA+B;AACxE,OAAK,SAAS,OAAO;AACrB,SAAO;;;;;CAMT,IAAI,KAAa,OAAqB;AACpC,OAAK,SAAS,OAAO;GAAE,GAAG,KAAK,SAAS;IAAO,MAAM;GAAO;AAC5D,SAAO;;;;;CAMT,MAAM,YAAoC,EAAE,EAAmB;AAC7D,SAAO,IAAI,gBACT,cAAc,KAAK,UAAU;GAC3B,GAAG;GACH,QAAQ,OAAO,YAAY;GAC5B,CAAC,CACH;;;;;;AAOL,SAAgB,sBACd,SACiB;AACjB,QAAO,IAAI,gBAAgB,QAAQ"}

package/dist/subscriber.d.ts

@@ -0,0 +1,13 @@
+import { EventBus } from "./eventBus.js";
+import { EventSpec } from "@contractspec/lib.contracts";
+import { AnySchemaModel } from "@contractspec/lib.schema";
+
+//#region src/subscriber.d.ts
+/** Typed subscription using your EventSpec */
+declare function subscribeEvent<T extends AnySchemaModel>(bus: EventBus, spec: EventSpec<T>, handler: (payload: T, ctx: {
+  traceId?: string;
+  deliveryId?: string;
+}) => Promise<void>): Promise<() => Promise<void>>;
+//#endregion
+export { subscribeEvent };
+//# sourceMappingURL=subscriber.d.ts.map

package/dist/subscriber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriber.d.ts","names":[],"sources":["../src/subscriber.ts"],"sourcesContent":[],"mappings":";;;;;;iBAKsB,yBAAyB,qBACxC,gBACC,UAAU,uBAEL;EAJS,OAAA,CAAA,EAAA,MAAA;EAAyB,UAAA,CAAA,EAAA,MAAA;CACxC,EAAA,GAKA,OALA,CAAA,IAAA,CAAA,CAAA,EAKa,OALb,CAAA,GAAA,GAKa,OALb,CAAA,IAAA,CAAA,CAAA"}

package/dist/subscriber.js

@@ -0,0 +1,19 @@
+import { decodeEvent } from "./eventBus.js";
+
+//#region src/subscriber.ts
+/** Typed subscription using your EventSpec */
+async function subscribeEvent(bus, spec, handler) {
+	const topic = `${spec.meta.key}.v${spec.meta.version}`;
+	return bus.subscribe(topic, async (u8) => {
+		const env = decodeEvent(u8);
+		if (env.key !== spec.meta.key || env.version !== spec.meta.version) return;
+		await handler(env.payload, {
+			traceId: env.traceId,
+			deliveryId: env.id
+		});
+	});
+}
+
+//#endregion
+export { subscribeEvent };
+//# sourceMappingURL=subscriber.js.map

package/dist/subscriber.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriber.js","names":[],"sources":["../src/subscriber.ts"],"sourcesContent":["import { decodeEvent, type EventBus } from './eventBus';\nimport type { EventSpec } from '@contractspec/lib.contracts';\nimport type { AnySchemaModel } from '@contractspec/lib.schema';\n\n/** Typed subscription using your EventSpec */\nexport async function subscribeEvent<T extends AnySchemaModel>(\n  bus: EventBus,\n  spec: EventSpec<T>,\n  handler: (\n    payload: T,\n    ctx: { traceId?: string; deliveryId?: string }\n  ) => Promise<void>\n) {\n  const topic = `${spec.meta.key}.v${spec.meta.version}`;\n  return bus.subscribe(topic, async (u8) => {\n    const env = decodeEvent<T>(u8);\n    if (env.key !== spec.meta.key || env.version !== spec.meta.version) return;\n    await handler(env.payload, { traceId: env.traceId, deliveryId: env.id });\n  });\n}\n"],"mappings":";;;;AAKA,eAAsB,eACpB,KACA,MACA,SAIA;CACA,MAAM,QAAQ,GAAG,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK;AAC7C,QAAO,IAAI,UAAU,OAAO,OAAO,OAAO;EACxC,MAAM,MAAM,YAAe,GAAG;AAC9B,MAAI,IAAI,QAAQ,KAAK,KAAK,OAAO,IAAI,YAAY,KAAK,KAAK,QAAS;AACpE,QAAM,QAAQ,IAAI,SAAS;GAAE,SAAS,IAAI;GAAS,YAAY,IAAI;GAAI,CAAC;GACxE"}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@contractspec/lib.bus",
+  "version": "0.0.0-canary-20260113162409",
+  "description": "Event bus and messaging primitives",
+  "keywords": [
+    "contractspec",
+    "events",
+    "messaging",
+    "pubsub",
+    "typescript"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "0.0.0-canary-20260113162409",
+    "@contractspec/tool.typescript": "0.0.0-canary-20260113162409",
+    "@types/express": "^5.0.3",
+    "tsdown": "^0.19.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@contractspec/lib.schema": "0.0.0-canary-20260113162409",
+    "@contractspec/lib.contracts": "0.0.0-canary-20260113162409",
+    "compare-versions": "^6.1.1"
+  },
+  "peerDependencies": {
+    "elysia": "^1.4.21",
+    "express": "^5.2.1",
+    "next": "16.1.1"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./auditableBus": "./dist/auditableBus.js",
+    "./eventBus": "./dist/eventBus.js",
+    "./filtering": "./dist/filtering.js",
+    "./inMemoryBus": "./dist/inMemoryBus.js",
+    "./metadata": "./dist/metadata.js",
+    "./subscriber": "./dist/subscriber.js",
+    "./*": "./*"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./auditableBus": "./dist/auditableBus.js",
+      "./eventBus": "./dist/eventBus.js",
+      "./filtering": "./dist/filtering.js",
+      "./inMemoryBus": "./dist/inMemoryBus.js",
+      "./metadata": "./dist/metadata.js",
+      "./subscriber": "./dist/subscriber.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/libs/bus"
+  },
+  "homepage": "https://contractspec.io"
+}