@l-etabli/events 0.5.0 → 0.6.1

package/src/createNewEvent.ts

@@ -1,87 +1,155 @@
-import type { DefaultContext, EventId, GenericEvent, UserId } from "./types.ts";
+import type {
+  EventDefinitions,
+  InferEventsFromDefinitions,
+} from "./eventDefinitions.ts";
+import type { Actor, DefaultContext, EventId, GenericEvent } from "./types.ts";
 
 type MakeCreateNewEventOptions = {
   getNow?: () => Date;
   generateId?: () => EventId;
 };
 
-type ContextParam<
+type MakeCreateNewEventFromDefinitionsOptions<
+  Definitions extends EventDefinitions,
+> = MakeCreateNewEventOptions & {
+  eventDefinitions: Definitions;
+};
+
+type DeclaredContextForEvent<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+  Topic extends Event["topic"],
+> = Exclude<Extract<Event, { topic: Topic }>["context"], undefined>;
+
+type ContextParamForEvent<
   Event extends GenericEvent<string, unknown, DefaultContext>,
   Topic extends Event["topic"],
-> = Extract<Event, { topic: Topic }>["context"] extends undefined
+> = [DeclaredContextForEvent<Event, Topic>] extends [never]
   ? { context?: undefined }
-  : { context: Extract<Event, { topic: Topic }>["context"] };
+  : { context: DeclaredContextForEvent<Event, Topic> };
+
+type BaseCreateNewEventParams = {
+  triggeredByActor: Actor;
+  id?: EventId;
+  occurredAt?: Date;
+  flowId?: string;
+  causedByEventId?: EventId;
+};
 
 type CreateNewEventParams<
   Event extends GenericEvent<string, unknown, DefaultContext>,
   Topic extends Event["topic"],
-> = {
+> = BaseCreateNewEventParams & {
   topic: Topic;
   payload: Extract<Event, { topic: Topic }>["payload"];
-  triggeredByUserId: UserId;
-  id?: EventId;
-  occurredAt?: Date;
   priority?: number;
-} & ContextParam<Event, Topic>;
+} & ContextParamForEvent<Event, Topic>;
+
+type PayloadFromDefinitions<
+  Definitions extends EventDefinitions,
+  Topic extends keyof Definitions & string,
+> = Definitions[Topic] extends {
+  _payload?: infer Payload;
+}
+  ? Payload
+  : never;
+
+type DeclaredContextFromDefinitions<
+  Definitions extends EventDefinitions,
+  Topic extends keyof Definitions & string,
+> = Exclude<
+  Definitions[Topic] extends { _context?: infer Context } ? Context : never,
+  undefined
+>;
+
+type ContextParamFromDefinitions<
+  Definitions extends EventDefinitions,
+  Topic extends keyof Definitions & string,
+> = [DeclaredContextFromDefinitions<Definitions, Topic>] extends [never]
+  ? { context?: undefined }
+  : { context: DeclaredContextFromDefinitions<Definitions, Topic> };
+
+type CreateNewEventParamsFromDefinitions<
+  Definitions extends EventDefinitions,
+  Topic extends keyof Definitions & string,
+> = BaseCreateNewEventParams & {
+  topic: Topic;
+  payload: PayloadFromDefinitions<Definitions, Topic>;
+} & ContextParamFromDefinitions<Definitions, Topic>;
 
 /**
  * Creates a typed event creator factory for your event union.
  * Provides type-safe event creation where topic constrains payload type.
- *
- * @param options.getNow - Function to get current time (default: `() => new Date()`)
- * @param options.generateId - Function to generate event IDs (default: `() => crypto.randomUUID()`)
- *
- * @example
- * ```typescript
- * type MyEvents =
- *   | GenericEvent<"UserCreated", { email: string }>
- *   | GenericEvent<"OrderPlaced", { orderId: string }>;
- *
- * // Standalone usage:
- * const createEvent = makeCreateNewEvent<MyEvents>();
- *
- * // Or get it from createInMemoryEventBus (recommended):
- * const { eventBus, createEvent } = createInMemoryEventBus<MyEvents>(withUow);
- *
- * // Type-safe: payload must match topic
- * createEvent({ topic: "UserCreated", payload: { email: "a@b.com" }, triggeredByUserId: "u1" }); // OK
- * createEvent({ topic: "UserCreated", payload: { orderId: "123" }, triggeredByUserId: "u1" }); // Error!
- *
- * // For testing, inject deterministic functions:
- * const createEvent = makeCreateNewEvent<MyEvents>({
- *   getNow: () => new Date("2024-01-01"),
- *   generateId: () => "test-id",
- * });
- * ```
  */
-
 export type CreateNewEvent<
   Event extends GenericEvent<string, unknown, DefaultContext>,
 > = <Topic extends Event["topic"]>(
   params: CreateNewEventParams<Event, Topic>,
 ) => Extract<Event, { topic: Topic }>;
 
-export const makeCreateNewEvent = <
+/**
+ * Creates a typed event creator factory directly from event definitions.
+ * Priority is injected from the canonical topic definition.
+ */
+export type CreateNewEventFromDefinitions<
+  Definitions extends EventDefinitions,
+> = <Topic extends keyof Definitions & string>(
+  params: CreateNewEventParamsFromDefinitions<Definitions, Topic>,
+) => Extract<InferEventsFromDefinitions<Definitions>, { topic: Topic }>;
+
+export function makeCreateNewEvent<
   Event extends GenericEvent<string, unknown, DefaultContext>,
+>(options?: MakeCreateNewEventOptions): CreateNewEvent<Event>;
+export function makeCreateNewEvent<Definitions extends EventDefinitions>(
+  options: MakeCreateNewEventFromDefinitionsOptions<Definitions>,
+): CreateNewEventFromDefinitions<Definitions>;
+export function makeCreateNewEvent<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+  Definitions extends EventDefinitions,
 >(
-  options: MakeCreateNewEventOptions = {},
-): CreateNewEvent<Event> => {
+  options:
+    | MakeCreateNewEventOptions
+    | MakeCreateNewEventFromDefinitionsOptions<Definitions> = {},
+): CreateNewEvent<Event> | CreateNewEventFromDefinitions<Definitions> {
   const getNow = options.getNow ?? (() => new Date());
   const generateId =
     options.generateId ?? (() => crypto.randomUUID() as EventId);
+  const eventDefinitions =
+    "eventDefinitions" in options ? options.eventDefinitions : undefined;
+
+  return ((params: {
+    topic: string;
+    payload: unknown;
+    triggeredByActor: Actor;
+    id?: EventId;
+    occurredAt?: Date;
+    flowId?: string;
+    causedByEventId?: EventId;
+    context?: DefaultContext;
+    priority?: number;
+  }) => {
+    const definitionPriority = eventDefinitions?.[params.topic]?.priority;
+    const priority =
+      definitionPriority ??
+      ("priority" in params
+        ? (params.priority as number | undefined)
+        : undefined);
 
-  return <Topic extends Event["topic"]>(
-    params: CreateNewEventParams<Event, Topic>,
-  ): Extract<Event, { topic: Topic }> =>
-    ({
+    return {
       id: params.id ?? generateId(),
       topic: params.topic,
       payload: params.payload,
-      triggeredByUserId: params.triggeredByUserId,
+      triggeredByActor: params.triggeredByActor,
       occurredAt: params.occurredAt ?? getNow(),
       status: "never-published",
       publications: [],
-      priority: params.priority,
-      context: params.context,
-    }) as unknown as Extract<Event, { topic: Topic }>;
-};
+      ...(priority !== undefined ? { priority } : {}),
+      ...(params.context !== undefined ? { context: params.context } : {}),
+      ...(params.flowId !== undefined ? { flowId: params.flowId } : {}),
+      ...(params.causedByEventId !== undefined
+        ? { causedByEventId: params.causedByEventId }
+        : {}),
+    };
+  }) as unknown as
+    | CreateNewEvent<Event>
+    | CreateNewEventFromDefinitions<Definitions>;
+}

package/src/eventDefinitions.ts

@@ -0,0 +1,53 @@
+import type { DefaultContext, GenericEvent } from "./types.ts";
+
+export type EventDefinition<
+  Payload,
+  Context extends DefaultContext = undefined,
+> = {
+  priority?: number;
+  _payload?: Payload;
+  _context?: Context;
+};
+
+export type EventDefinitions = Record<
+  string,
+  EventDefinition<unknown, DefaultContext>
+>;
+
+type PayloadFromDefinition<Definition> = Definition extends EventDefinition<
+  infer Payload,
+  DefaultContext
+>
+  ? Payload
+  : never;
+
+type ContextFromDefinition<Definition> = Definition extends EventDefinition<
+  unknown,
+  infer Context
+>
+  ? Context
+  : never;
+
+export type InferEventsFromDefinitions<Definitions extends EventDefinitions> = {
+  [Topic in keyof Definitions & string]: GenericEvent<
+    Topic,
+    PayloadFromDefinition<Definitions[Topic]>,
+    ContextFromDefinition<Definitions[Topic]>
+  >;
+}[keyof Definitions & string];
+
+type DefineEventOptions = {
+  priority?: number;
+};
+
+export const defineEvent = <
+  Payload,
+  Context extends DefaultContext = undefined,
+>(
+  options: DefineEventOptions = {},
+): EventDefinition<Payload, Context> =>
+  options as EventDefinition<Payload, Context>;
+
+export const defineEvents = <Definitions extends EventDefinitions>(
+  definitions: Definitions,
+): Definitions => definitions;

package/src/index.ts

@@ -1,8 +1,9 @@
 export * from "./adapters/in-memory/index.ts";
 export * from "./createEventCrawler.ts";
 export * from "./createNewEvent.ts";
+export * from "./eventDefinitions.ts";
 export type * from "./ports/EventBus.ts";
 export type * from "./ports/EventQueries.ts";
 export type * from "./ports/EventRepository.ts";
 export * from "./subscriptions.ts";
-export type * from "./types.ts";
+export * from "./types.ts";

package/src/types.ts

@@ -12,6 +12,74 @@ export type SubscriptionId = Flavor<string, "SubscriptionId">;
 /** Unique identifier for a user who triggered an event. */
 export type UserId = Flavor<string, "UserId">;
 
+/** Actor representing a user action. */
+export type UserActor<Id extends string = string> = {
+  kind: "user";
+  id: Id;
+};
+
+/** Actor representing platform or infrastructure initiated work. */
+export type SystemActor = {
+  kind: "system";
+};
+
+/** Actor representing a background worker or job. */
+export type WorkerActor<Id extends string = string> = {
+  kind: "worker";
+  id?: Id;
+};
+
+/** Actor representing an API key. */
+export type ApiKeyActor<Id extends string = string> = {
+  kind: "api-key";
+  id: Id;
+};
+
+/** Actor representing an anonymous caller. */
+export type AnonymousActor = {
+  kind: "anonymous";
+};
+
+/** JSON-serializable actor metadata persisted alongside the event. */
+export type Actor =
+  | UserActor
+  | SystemActor
+  | WorkerActor
+  | ApiKeyActor
+  | AnonymousActor;
+
+/** Creates a typed user actor. */
+export const createUserActor = <Id extends string>(id: Id): UserActor<Id> => ({
+  kind: "user",
+  id,
+});
+
+/** Creates a typed system actor. */
+export const createSystemActor = (): SystemActor => ({
+  kind: "system",
+});
+
+/** Creates a typed worker actor. */
+export const createWorkerActor = <Id extends string>(
+  id?: Id,
+): WorkerActor<Id> => ({
+  kind: "worker",
+  ...(id !== undefined ? { id } : {}),
+});
+
+/** Creates a typed API key actor. */
+export const createApiKeyActor = <Id extends string>(
+  id: Id,
+): ApiKeyActor<Id> => ({
+  kind: "api-key",
+  id,
+});
+
+/** Creates a typed anonymous actor. */
+export const createAnonymousActor = (): AnonymousActor => ({
+  kind: "anonymous",
+});
+
 /** Unique identifier for an event. */
 export type EventId = Flavor<string, "EventId">;
 
@@ -91,8 +159,12 @@ export type GenericEvent<
   status: EventStatus;
   /** History of publication attempts. */
   publications: EventPublication[];
-  /** User who triggered the action that created this event. */
-  triggeredByUserId: UserId;
+  /** Actor identifier that triggered the action that created this event. */
+  triggeredByActor: Actor;
+  /** Optional correlation identifier for a request or cross-event flow. */
+  flowId?: string;
+  /** Optional parent event identifier for cascading events. */
+  causedByEventId?: EventId;
   /** Optional priority for processing order (not yet implemented in crawler). */
   priority?: number;
   /** Optional context for filtering events (e.g., by tenant). */