@requence/event-sourcing 0.0.1 → 1.0.0

package/src/utilityTypes.d.ts

@@ -0,0 +1,110 @@
+import type z from 'zod/v4'
+
+export type Prettify<T> = {
+  [K in keyof T]: T[K]
+} & {}
+
+interface Stream {
+  stream: string
+}
+
+interface StreamEvents extends Stream {
+  events: string[]
+}
+
+interface StreamId extends Stream {
+  id: string
+}
+
+interface StreamIdEvents extends StreamEvents {
+  id: string
+}
+
+export type BaseInputEvent<Type extends string = string, Payload = unknown> = {
+  type: Type
+  payload: Payload
+  metadata?: Record<string, unknown>
+  causationId?: string
+  correlationId?: string
+  actorId?: string
+  schemaVersion: number
+}
+
+type LatestEvent<
+  Event extends EventTemplate,
+  LatestVersion = Max<Event['version']>,
+  Schema = Event extends { version: LatestVersion } ? Event['schema'] : never,
+> = LatestVersion extends number
+  ? BaseOutputEvent<Event['type'], LatestVersion, z.output<Schema>>
+  : never
+
+export type AllEvents<Event extends EventTemplate> = {
+  [E in Event as E['type']]: LatestEvent<E>
+}[Event['type']]
+
+export type BaseOutputEvent<
+  Type extends string = string,
+  Version extends number = number,
+  Payload = unknown,
+> = {
+  position: number
+  type: Type
+  schemaVersion: Version
+  payload: Payload
+  metadata?: Record<string, any>
+  causationId?: string | null
+  actorId?: string | null
+  correlationId?: string | null
+  streamId: string
+  streamType: string
+  streamVersion: number
+  createdAt: Date
+}
+
+export type EventTemplate = { type: string; schema: z.ZodType; version: number }
+export type OutputEvent<Event extends EventTemplate> = Prettify<
+  {
+    [K in Event as K['version']]: BaseOutputEvent<
+      K['type'],
+      K['version'],
+      z.output<K['schema']>
+    >
+  }[Event['version']]
+>
+
+export type OutputEvents<Event extends EventTemplate> = Prettify<
+  {
+    [E in Event as E['type']]: OutputEvent<E>
+  }[Event['type']]
+>
+
+export type Max<N extends number, A extends any[] = []> = [N] extends [
+  Partial<A>['length'],
+]
+  ? A['length']
+  : Max<N, [0, ...A]>
+
+export type EventHandlers<Events extends EventTemplate, Helpers = never> = {
+  [K in Events as `on${K['type']}`]?: (
+    ...args: [Helpers] extends [never]
+      ? [event: OutputEvent<K>]
+      : [event: OutputEvent<K>, helpers: Helpers]
+  ) => MaybePromise<void>
+}
+
+export type AfterEffectHandlers<
+  Events extends EventTemplate,
+  Helpers = never,
+> = {
+  [K in Events as `after${K['type']}`]?: (
+    ...args: [Helpers] extends [never]
+      ? [event: OutputEvent<K>]
+      : [event: OutputEvent<K>, helpers: Helpers]
+  ) => MaybePromise<void>
+}
+
+export type Merge<A, B> = Prettify<Omit<A, keyof B> & B>
+export type Keys<T> = {
+  [K in keyof T]: T[K] extends true ? K : never
+}[keyof T]
+export type MaybePromise<T> = T | Promise<T>

package/src/utils.ts

@@ -0,0 +1,43 @@
+import type { MaybePromise } from './utilityTypes.js'
+
+export async function normalizeArray<T>(
+  result: MaybePromise<void | T | T[]> | Iterable<T> | AsyncIterable<T>,
+  onItem?: (item: T) => void,
+): Promise<T[]> {
+  const awaited = (await result) as any
+
+  // If it's explicitly void/undefined, normalize to empty array
+  if (typeof awaited === 'undefined') {
+    return []
+  }
+
+  // Async iterable
+  if (typeof awaited[Symbol.asyncIterator] === 'function') {
+    const out: T[] = []
+    for await (const item of awaited as AsyncIterable<T>) {
+      out.push(item)
+      onItem?.(item)
+    }
+    return out
+  }
+
+  // Sync iterable (this also covers arrays)
+  if (typeof awaited[Symbol.iterator] === 'function') {
+    return Array.from(awaited as Iterable<T>)
+  }
+
+  // Plain single value
+  return [awaited as T]
+}
+
+export async function awaitAll(getPromise: () => Promise<any>) {
+  let currentPromise = getPromise()
+  while (true) {
+    await currentPromise
+    const nextPromise = getPromise()
+    if (nextPromise === currentPromise) {
+      break
+    }
+    currentPromise = nextPromise
+  }
+}

package/src/wrappedEventBuilder.ts

@@ -0,0 +1,181 @@
+import type { z } from 'zod/v4'
+
+import type { EventValidationError } from './errors.ts'
+import type {
+  BaseInputEvent,
+  EventTemplate,
+  Max,
+  MaybePromise,
+} from './utilityTypes.js'
+
+export type WrappedEvent<E extends EventTemplate = EventTemplate> = {
+  withCausationId(causationId: string | null | undefined): WrappedEvent<E>
+  withDefaultCausationId(
+    causationId: string | null | undefined,
+  ): WrappedEvent<E>
+  withCorrelationId(correlationId: string | null | undefined): WrappedEvent<E>
+  withDefaultCorrelationId(
+    correlationId: string | null | undefined,
+  ): WrappedEvent<E>
+  withActorId(actorId: string | null | undefined): WrappedEvent<E>
+  withDefaultActorId(actorId: string | null | undefined): WrappedEvent<E>
+  withMetadata(
+    metadata: Record<string, any> | null | undefined,
+  ): WrappedEvent<E>
+  withDefaultMetadata(
+    metadata: Record<string, any> | null | undefined,
+  ): WrappedEvent<E>
+  withAdditionalMetadata(
+    metadata: Record<string, any> | null | undefined,
+  ): WrappedEvent<E>
+  onValidationError(
+    errorHandler: (error: EventValidationError) => MaybePromise<void>,
+  ): WrappedEvent<E>
+  readonly type: string
+}
+
+const eventInternalsSymbol = Symbol.for('event-internals')
+
+function getInternals(event: WrappedEvent) {
+  return (event as any)[eventInternalsSymbol] as {
+    event: Omit<BaseInputEvent, 'schemaVersion'>
+    errorHandler?: (error: EventValidationError) => MaybePromise<void>
+  }
+}
+
+export function unwrapEvent<E extends EventTemplate = EventTemplate>(
+  event: WrappedEvent<E>,
+) {
+  return getInternals(event).event as {
+    [K in E as K['type']]: Omit<
+      BaseInputEvent<K['type'], z.output<K['schema']>>,
+      'schemaVersion'
+    >
+  }[E['type']]
+}
+
+export async function handleEventError(
+  event: WrappedEvent,
+  error: EventValidationError,
+) {
+  await getInternals(event).errorHandler?.(error)
+}
+
+type LatestSchema<
+  Event extends EventTemplate,
+  LatestVersion = Max<Event['version']>,
+  Schema = Event extends { version: LatestVersion } ? Event['schema'] : never,
+> = LatestVersion extends number ? z.input<Schema> : never
+
+type EventMap<T extends EventTemplate> = {
+  [K in T as K['type']]: LatestSchema<K>
+}
+
+export type WrappedEventBuilder<Event extends EventTemplate> = {
+  <
+    Type extends Event['type'],
+    LatestVersion = Max<
+      Event extends { type: Type } ? Event['version'] : never
+    >,
+    Schema = Event extends { type: Type; version: LatestVersion }
+      ? Event['schema']
+      : never,
+  >(
+    ...args: z.input<Schema> extends null
+      ? [type: Type, payload?: null]
+      : [type: Type, payload: z.input<Schema>]
+  ): WrappedEvent
+  $inferPayload: EventMap<Event>
+}
+
+export function wrappedEventBuilder(
+  type: string,
+  payload: unknown,
+): WrappedEvent
+export function wrappedEventBuilder(event: BaseInputEvent): WrappedEvent
+export function wrappedEventBuilder(
+  type: string | BaseInputEvent,
+  payload?: unknown,
+): WrappedEvent {
+  let errorHandler: (error: EventValidationError) => MaybePromise<void>
+  const event: Omit<BaseInputEvent, 'schemaVersion'> =
+    typeof type === 'string'
+      ? {
+          type,
+          payload: payload ?? null,
+        }
+      : type
+
+  return {
+    withCausationId(causationId) {
+      if (causationId) {
+        event.causationId = causationId
+      }
+      return this
+    },
+    withDefaultCausationId(causationId) {
+      if (causationId && !event.causationId) {
+        event.causationId = causationId
+      }
+      return this
+    },
+    withCorrelationId(correlationId) {
+      if (correlationId) {
+        event.correlationId = correlationId
+      }
+      return this
+    },
+    withDefaultCorrelationId(correlationId) {
+      if (correlationId && !event.correlationId) {
+        event.correlationId = correlationId
+      }
+      return this
+    },
+    withActorId(actorId) {
+      if (actorId) {
+        event.actorId = actorId
+      }
+      return this
+    },
+    withDefaultActorId(actorId) {
+      if (actorId && !event.actorId) {
+        event.actorId = actorId
+      }
+      return this
+    },
+    withMetadata(metadata) {
+      if (metadata) {
+        event.metadata = metadata
+      }
+      return this
+    },
+    withDefaultMetadata(metadata) {
+      if (metadata && !event.metadata) {
+        event.metadata = metadata
+      }
+      return this
+    },
+    withAdditionalMetadata(metadata) {
+      if (!metadata) {
+        return this
+      }
+      if (!event.metadata) {
+        event.metadata = metadata
+      } else {
+        event.metadata = Object.assign(event.metadata, metadata)
+      }
+
+      return this
+    },
+    onValidationError(handler) {
+      errorHandler = handler
+      return this
+    },
+
+    get [eventInternalsSymbol]() {
+      return { event, errorHandler }
+    },
+
+    type,
+  } as WrappedEvent
+}