@lssm/lib.bus 0.0.0-canary-20251217052941 → 0.0.0-canary-20251217060433

package/dist/auditableBus.d.ts

@@ -0,0 +1,116 @@
+import { EventBus } from "./eventBus.js";
+import { EventMetadata } from "./metadata.js";
+import { EventEnvelope, EventKey, EventSpec } from "@lssm/lib.contracts";
+import { AnySchemaModel } from "@lssm/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;
+  eventName: string;
+  eventVersion: number;
+  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 {
+  eventName?: 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?: (eventName: 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 };

package/dist/eventBus.d.ts

@@ -0,0 +1,21 @@
+import { EventEnvelope, EventKey, EventSpec } from "@lssm/lib.contracts";
+import { AnySchemaModel } from "@lssm/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 };

package/dist/filtering.d.ts

@@ -0,0 +1,82 @@
+import { EventBus } from "./eventBus.js";
+import { AuditableEventEnvelope } from "./auditableBus.js";
+import { EventKey, EventSpec } from "@lssm/lib.contracts";
+import { AnySchemaModel } from "@lssm/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?: number;
+  /** 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 };

package/dist/inMemoryBus.d.ts

@@ -0,0 +1,16 @@
+import { EventBus } from "./eventBus.js";
+import { EventKey } from "@lssm/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 };

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/metadata.d.ts

@@ -0,0 +1,81 @@
+//#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 };

package/dist/subscriber.d.ts

@@ -0,0 +1,12 @@
+import { EventBus } from "./eventBus.js";
+import { EventSpec } from "@lssm/lib.contracts";
+import { AnySchemaModel } from "@lssm/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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/lib.bus",
-  "version": "0.0.0-canary-20251217052941",
+  "version": "0.0.0-canary-20251217060433",
   "scripts": {
     "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
     "publish:pkg:canary": "bun publish:pkg --tag canary",
@@ -14,15 +14,15 @@
     "lint:check": "eslint src"
   },
   "devDependencies": {
-    "@lssm/tool.tsdown": "0.0.0-canary-20251217052941",
-    "@lssm/tool.typescript": "0.0.0-canary-20251217052941",
+    "@lssm/tool.tsdown": "0.0.0-canary-20251217060433",
+    "@lssm/tool.typescript": "0.0.0-canary-20251217060433",
     "@types/express": "^5.0.3",
     "tsdown": "^0.17.4",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@lssm/lib.schema": "0.0.0-canary-20251217052941",
-    "@lssm/lib.contracts": "0.0.0-canary-20251217052941"
+    "@lssm/lib.schema": "0.0.0-canary-20251217060433",
+    "@lssm/lib.contracts": "0.0.0-canary-20251217060433"
   },
   "peerDependencies": {
     "elysia": "^1.4.19",
@@ -38,13 +38,13 @@
     "README.md"
   ],
   "exports": {
-    ".": "./src/index.ts",
-    "./auditableBus": "./src/auditableBus.ts",
-    "./eventBus": "./src/eventBus.ts",
-    "./filtering": "./src/filtering.ts",
-    "./inMemoryBus": "./src/inMemoryBus.ts",
-    "./metadata": "./src/metadata.ts",
-    "./subscriber": "./src/subscriber.ts",
+    ".": "./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": {