@holo-js/events 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,267 @@
+import { QueueJobDefinition, QueueJsonValue } from '@holo-js/queue';
+
+type EventDelayValue = number | Date;
+declare function normalizeOptionalString(value: string | undefined, label: string): string | undefined;
+declare function normalizeOptionalBoolean(value: boolean | undefined, label: string): boolean | undefined;
+declare function normalizeOptionalDelay(value: EventDelayValue | undefined): EventDelayValue | undefined;
+declare function toPosixPath(value: string): string;
+declare function deriveEventNameFromSourcePath(sourcePath: string): string;
+declare function isReadonlyArray(value: unknown): value is readonly unknown[];
+declare function hasEventDefinitionMarker(value: unknown): boolean;
+declare function hasListenerDefinitionMarker(value: unknown): boolean;
+interface EventDefinition<TPayload = unknown, TName extends string | undefined = string | undefined> {
+    readonly name?: TName;
+    readonly __payloadType?: TPayload;
+}
+interface RegisteredEvent<TPayload = unknown, TName extends string = string> {
+    readonly name: TName;
+    readonly sourcePath?: string;
+    readonly definition: EventDefinition<TPayload, TName>;
+}
+interface EventEnvelope<TName extends string = string, TPayload = unknown> {
+    readonly name: TName;
+    readonly payload: TPayload;
+    readonly occurredAt: number;
+}
+interface HoloEventRegistry {
+}
+interface HoloListenerRegistry {
+}
+type KnownEventName = Extract<keyof HoloEventRegistry, string>;
+type ResolveRegisteredEventDefinition<TEventName extends string> = TEventName extends KnownEventName ? Extract<HoloEventRegistry[TEventName], EventDefinition> extends never ? EventDefinition<unknown, TEventName> : Extract<HoloEventRegistry[TEventName], EventDefinition> : EventDefinition<unknown, TEventName>;
+type EventPayloadFor<TEventName extends string> = ResolveRegisteredEventDefinition<TEventName> extends EventDefinition<infer TPayload, string | undefined> ? TPayload : unknown;
+type ExportedEventDefinition<TValue> = Extract<TValue, EventDefinition> extends never ? EventDefinition : Extract<TValue, EventDefinition>;
+type EventReference = string | EventDefinition<unknown, string | undefined>;
+type EventReferenceInput = EventReference | readonly EventReference[];
+type NormalizeEventReferenceInput<TInput extends EventReferenceInput> = TInput extends readonly EventReference[] ? TInput : readonly [TInput];
+type EventEnvelopeFor<TReference> = TReference extends EventDefinition<infer TPayload, infer TName> ? EventEnvelope<Extract<TName, string> extends never ? string : Extract<TName, string>, TPayload> : TReference extends string ? EventEnvelope<TReference, EventPayloadFor<TReference>> : never;
+type ListenerHandledEvent<TInput extends EventReferenceInput> = EventEnvelopeFor<NormalizeEventReferenceInput<TInput>[number]>;
+interface ListenerDefinition<TInput extends EventReferenceInput = EventReferenceInput, TResult = unknown> {
+    readonly name?: string;
+    readonly listensTo: NormalizeEventReferenceInput<TInput>;
+    readonly queue?: boolean;
+    readonly connection?: string;
+    readonly queueName?: string;
+    readonly delay?: EventDelayValue;
+    readonly afterCommit?: boolean;
+    handle(event: ListenerHandledEvent<TInput>): TResult | Promise<TResult>;
+}
+interface RegisteredListener<TInput extends EventReferenceInput = EventReferenceInput, TResult = unknown> {
+    readonly id: string;
+    readonly sourcePath?: string;
+    readonly eventNames: readonly string[];
+    readonly definition: ListenerDefinition<TInput, TResult>;
+}
+interface EventDispatchResult {
+    readonly eventName: string;
+    readonly occurredAt: number;
+    readonly deferred: boolean;
+    readonly syncListeners: number;
+    readonly queuedListeners: number;
+}
+interface RegisterEventOptions {
+    readonly name?: string;
+    readonly sourcePath?: string;
+    readonly replaceExisting?: boolean;
+}
+interface RegisterListenerOptions {
+    readonly id?: string;
+    readonly sourcePath?: string;
+    readonly replaceExisting?: boolean;
+}
+interface EventPendingDispatch<TPayload = unknown> extends PromiseLike<EventDispatchResult> {
+    afterCommit(): EventPendingDispatch<TPayload>;
+    onConnection(name: string): EventPendingDispatch<TPayload>;
+    onQueue(name: string): EventPendingDispatch<TPayload>;
+    delay(value: EventDelayValue): EventPendingDispatch<TPayload>;
+    dispatch(): Promise<EventDispatchResult>;
+    then<TResult1 = EventDispatchResult, TResult2 = never>(onfulfilled?: ((value: EventDispatchResult) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): Promise<EventDispatchResult | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<EventDispatchResult>;
+}
+interface EventQueuedListenerDispatch {
+    readonly listenerId: string;
+    readonly event: EventEnvelope;
+    readonly connection?: string;
+    readonly queueName?: string;
+    readonly delay?: EventDelayValue;
+}
+interface EventDeferredDispatchContext {
+    readonly eventName: string;
+    readonly afterCommit: boolean;
+}
+interface EventRuntimeHooks {
+    dispatchQueuedListener?(dispatch: EventQueuedListenerDispatch): void | Promise<void>;
+    defer?(callback: () => Promise<void>, context: EventDeferredDispatchContext): boolean;
+}
+interface EventRuntimeBinding {
+    readonly hooks: Readonly<EventRuntimeHooks>;
+}
+interface EventFacade {
+    dispatch<TEventName extends KnownEventName>(event: TEventName, payload: EventPayloadFor<TEventName>): EventPendingDispatch<EventPayloadFor<TEventName>>;
+    dispatch<TPayload, TName extends string | undefined = string | undefined>(event: EventDefinition<TPayload, TName>, payload: TPayload): EventPendingDispatch<TPayload>;
+    dispatch<TPayload = unknown>(event: string, payload: TPayload): EventPendingDispatch<TPayload>;
+}
+declare function isEventDefinition(value: unknown): value is EventDefinition;
+declare function normalizeEventDefinition<TEvent extends EventDefinition>(event: TEvent): TEvent;
+declare function defineEvent<TPayload, TName extends string | undefined = string | undefined>(event: EventDefinition<TPayload, TName>): EventDefinition<TPayload, TName>;
+declare function normalizeListensTo<TInput extends EventReferenceInput>(input: TInput): NormalizeEventReferenceInput<TInput>;
+declare function isListenerDefinition(value: unknown): value is ListenerDefinition;
+declare function normalizeListenerDefinition<TInput extends EventReferenceInput, TListener extends ListenerDefinition<TInput>>(listener: TListener): TListener;
+declare function defineListener<TInput extends EventReferenceInput, TListener extends ListenerDefinition<TInput>>(listener: TListener): TListener;
+declare const eventInternals: {
+    hasEventDefinitionMarker: typeof hasEventDefinitionMarker;
+    hasListenerDefinitionMarker: typeof hasListenerDefinitionMarker;
+    isReadonlyArray: typeof isReadonlyArray;
+    deriveEventNameFromSourcePath: typeof deriveEventNameFromSourcePath;
+    normalizeEventDefinition: typeof normalizeEventDefinition;
+    normalizeOptionalBoolean: typeof normalizeOptionalBoolean;
+    normalizeOptionalDelay: typeof normalizeOptionalDelay;
+    normalizeOptionalString: typeof normalizeOptionalString;
+    normalizeListensTo: typeof normalizeListensTo;
+    normalizeListenerDefinition: typeof normalizeListenerDefinition;
+    toPosixPath: typeof toPosixPath;
+};
+
+type ListenerRegistrationState = {
+    readonly listener: RegisteredListener;
+    readonly order: number;
+};
+type EventRegistryState = {
+    events: Map<string, RegisteredEvent>;
+    listeners: Map<string, ListenerRegistrationState>;
+    listenersByEvent: Map<string, ListenerRegistrationState[]>;
+    nextListenerOrder: number;
+};
+declare function getEventRegistryState(): EventRegistryState;
+declare function deriveListenerIdFromSourcePath(sourcePath: string): string;
+declare function resolveRegisteredEventName(definition: EventDefinition, options?: RegisterEventOptions): string;
+declare function resolveRegisteredListenerId(definition: ListenerDefinition, options?: RegisterListenerOptions): string;
+declare function resolveListenerEventNames(definition: ListenerDefinition, state: EventRegistryState): readonly string[];
+declare function registerEvent<TPayload, TName extends string = string>(definition: EventDefinition<TPayload, TName>, options?: RegisterEventOptions): RegisteredEvent<TPayload, TName>;
+declare function registerEvents(definitions: ReadonlyArray<{
+    readonly definition: EventDefinition;
+    readonly options?: RegisterEventOptions;
+}>): readonly RegisteredEvent[];
+declare function getRegisteredEvent(name: string): RegisteredEvent | undefined;
+declare function listRegisteredEvents(): readonly RegisteredEvent[];
+declare function unregisterEvent(name: string): boolean;
+declare function registerListener<TInput extends EventReference | readonly EventReference[], TResult>(definition: ListenerDefinition<TInput, TResult>, options?: RegisterListenerOptions): RegisteredListener<TInput, TResult>;
+declare function registerListeners(definitions: ReadonlyArray<{
+    readonly definition: ListenerDefinition;
+    readonly options?: RegisterListenerOptions;
+}>): readonly RegisteredListener[];
+declare function getRegisteredListener(id: string): RegisteredListener | undefined;
+declare function listRegisteredListeners(): readonly RegisteredListener[];
+/**
+ * Listener order for an event is deterministic and follows listener registration order.
+ */
+declare function listRegisteredListenersForEvent(eventName: string): readonly RegisteredListener[];
+declare function unregisterListener(id: string): boolean;
+declare function resetEventRegistry(): void;
+declare function resetListenerRegistry(): void;
+declare function resetEventsRegistry(): void;
+declare const eventRegistryInternals: {
+    deriveListenerIdFromSourcePath: typeof deriveListenerIdFromSourcePath;
+    getEventRegistryState: typeof getEventRegistryState;
+    resolveListenerEventNames: typeof resolveListenerEventNames;
+    resolveRegisteredEventName: typeof resolveRegisteredEventName;
+    resolveRegisteredListenerId: typeof resolveRegisteredListenerId;
+};
+
+declare function deferEventDispatchToDatabaseCommit(callback: () => Promise<void>, _context: EventDeferredDispatchContext): boolean;
+
+declare const EVENTS_INVOKE_LISTENER_JOB = "holo.events.invoke-listener";
+type EventsInvokeListenerPayload = Readonly<Record<string, QueueJsonValue>> & Readonly<{
+    readonly listenerId: string;
+    readonly eventName: string;
+    readonly occurredAt: number;
+    readonly payload: QueueJsonValue;
+}>;
+declare module '@holo-js/queue' {
+    interface HoloQueueJobRegistry {
+        'holo.events.invoke-listener': QueueJobDefinition<EventsInvokeListenerPayload, void>;
+    }
+}
+declare function createQueuedListenerEventEnvelope(payload: EventsInvokeListenerPayload): EventEnvelope<string, QueueJsonValue>;
+declare function requireQueuedListener(listenerId: string): RegisteredListener;
+declare function assertQueuedListenerMatchesEvent(listener: RegisteredListener, eventName: string): void;
+declare function runQueuedListenerInvocation(payload: EventsInvokeListenerPayload): Promise<void>;
+declare function ensureEventsQueueJobRegistered(): void;
+declare const eventQueueInternals: {
+    assertQueuedListenerMatchesEvent: typeof assertQueuedListenerMatchesEvent;
+    createQueuedListenerEventEnvelope: typeof createQueuedListenerEventEnvelope;
+    requireQueuedListener: typeof requireQueuedListener;
+};
+
+type PendingOptions = {
+    readonly afterCommit?: true;
+    readonly connection?: string;
+    readonly queueName?: string;
+    readonly delay?: EventDelayValue;
+};
+type EventPayloadValidationState = {
+    readonly seen: Set<unknown>;
+};
+type RuntimeState = {
+    hooks: EventRuntimeHooks;
+};
+type ListenerExecutionGroups = {
+    readonly immediateSyncListeners: readonly RegisteredListener[];
+    readonly immediateQueuedListeners: readonly RegisteredListener[];
+    readonly deferredSyncListeners: readonly RegisteredListener[];
+    readonly deferredQueuedListeners: readonly RegisteredListener[];
+};
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+declare function assertEventJsonValue(value: unknown, path: string, state: EventPayloadValidationState): void;
+declare function validateQueuedEventPayload<TPayload>(payload: TPayload): void;
+declare function getRuntimeState(): RuntimeState;
+declare function createRuntimeBinding(state: RuntimeState): EventRuntimeBinding;
+declare function normalizeEventName(name: string): string;
+declare function resolveDispatchedEventName<TPayload>(event: string | EventDefinition<TPayload, string | undefined>): string;
+declare function requireRegisteredEvent(name: string): RegisteredEvent;
+declare function createEventEnvelope<TPayload>(eventName: string, payload: TPayload, occurredAt?: number): EventEnvelope<string, TPayload>;
+declare function splitRegisteredListeners(listeners: readonly RegisteredListener[]): {
+    readonly syncListeners: readonly RegisteredListener[];
+    readonly queuedListeners: readonly RegisteredListener[];
+};
+declare function executeSyncListeners<TPayload>(listeners: readonly RegisteredListener[], event: EventEnvelope<string, TPayload>): Promise<number>;
+declare function executeListenerGroups<TPayload>(syncListeners: readonly RegisteredListener[], queuedListeners: readonly RegisteredListener[], event: EventEnvelope<string, TPayload>, options: PendingOptions): Promise<{
+    readonly syncCount: number;
+    readonly queuedCount: number;
+}>;
+declare function executeListener<TPayload>(listener: RegisteredListener, event: EventEnvelope<string, TPayload>): Promise<void>;
+declare function createQueuedListenerDispatch(listener: RegisteredListener, event: EventEnvelope, options: PendingOptions): EventQueuedListenerDispatch;
+declare function dispatchQueuedListeners<TPayload>(listeners: readonly RegisteredListener[], event: EventEnvelope<string, TPayload>, options: PendingOptions): Promise<number>;
+declare function splitListenersForExecution(listeners: readonly RegisteredListener[], forceAfterCommit: boolean): ListenerExecutionGroups;
+declare function scheduleDeferredDispatch(callback: () => Promise<void>, eventName: string): boolean;
+declare function executeDispatch<TPayload>(event: string | EventDefinition<TPayload, string | undefined>, payload: TPayload, options?: PendingOptions): Promise<EventDispatchResult>;
+declare function configureEventsRuntime(hooks?: EventRuntimeHooks): void;
+declare function getEventsRuntime(): EventRuntimeBinding;
+declare function resetEventsRuntime(): void;
+declare function dispatchEvent<TEventName extends Extract<keyof HoloEventRegistry, string>>(event: TEventName, payload: EventPayloadFor<TEventName>): EventPendingDispatch<EventPayloadFor<TEventName>>;
+declare function dispatchEvent<TPayload, TName extends string | undefined = string | undefined>(event: EventDefinition<TPayload, TName>, payload: TPayload): EventPendingDispatch<TPayload>;
+declare function dispatchEvent<TPayload = unknown>(event: string, payload: TPayload): EventPendingDispatch<TPayload>;
+declare const Event: EventFacade;
+declare const eventRuntimeInternals: {
+    assertEventJsonValue: typeof assertEventJsonValue;
+    createEventEnvelope: typeof createEventEnvelope;
+    createQueuedListenerDispatch: typeof createQueuedListenerDispatch;
+    createRuntimeBinding: typeof createRuntimeBinding;
+    dispatchQueuedListeners: typeof dispatchQueuedListeners;
+    executeListenerGroups: typeof executeListenerGroups;
+    executeDispatch: typeof executeDispatch;
+    executeListener: typeof executeListener;
+    executeSyncListeners: typeof executeSyncListeners;
+    getRuntimeState: typeof getRuntimeState;
+    isPlainObject: typeof isPlainObject;
+    normalizeEventName: typeof normalizeEventName;
+    requireRegisteredEvent: typeof requireRegisteredEvent;
+    resolveDispatchedEventName: typeof resolveDispatchedEventName;
+    scheduleDeferredDispatch: typeof scheduleDeferredDispatch;
+    splitRegisteredListeners: typeof splitRegisteredListeners;
+    splitListenersForExecution: typeof splitListenersForExecution;
+    validateQueuedEventPayload: typeof validateQueuedEventPayload;
+};
+
+export { EVENTS_INVOKE_LISTENER_JOB, Event, type EventDeferredDispatchContext, type EventDefinition, type EventDelayValue, type EventDispatchResult, type EventEnvelope, type EventEnvelopeFor, type EventFacade, type EventPayloadFor, type EventPendingDispatch, type EventQueuedListenerDispatch, type EventReference, type EventReferenceInput, type EventRuntimeBinding, type EventRuntimeHooks, type EventsInvokeListenerPayload, type ExportedEventDefinition, type HoloEventRegistry, type HoloListenerRegistry, type ListenerDefinition, type ListenerHandledEvent, type RegisterEventOptions, type RegisterListenerOptions, type RegisteredEvent, type RegisteredListener, configureEventsRuntime, deferEventDispatchToDatabaseCommit, defineEvent, defineListener, dispatchEvent, ensureEventsQueueJobRegistered, eventInternals, eventQueueInternals, eventRegistryInternals, eventRuntimeInternals, getEventsRuntime, getRegisteredEvent, getRegisteredListener, isEventDefinition, isListenerDefinition, listRegisteredEvents, listRegisteredListeners, listRegisteredListenersForEvent, normalizeEventDefinition, normalizeListenerDefinition, registerEvent, registerEvents, registerListener, registerListeners, resetEventRegistry, resetEventsRegistry, resetEventsRuntime, resetListenerRegistry, runQueuedListenerInvocation, unregisterEvent, unregisterListener };

package/dist/index.mjs

@@ -0,0 +1,812 @@
+// src/contracts.ts
+var HOLO_EVENT_DEFINITION_MARKER = /* @__PURE__ */ Symbol.for("holo-js.events.definition");
+var HOLO_LISTENER_DEFINITION_MARKER = /* @__PURE__ */ Symbol.for("holo-js.events.listener");
+function normalizeOptionalString(value, label) {
+  if (typeof value === "undefined") {
+    return void 0;
+  }
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`[Holo Events] ${label} must be a non-empty string when provided.`);
+  }
+  return normalized;
+}
+function normalizeOptionalBoolean(value, label) {
+  if (typeof value === "undefined") {
+    return void 0;
+  }
+  if (typeof value !== "boolean") {
+    throw new Error(`[Holo Events] ${label} must be a boolean when provided.`);
+  }
+  return value;
+}
+function normalizeOptionalDelay(value) {
+  if (typeof value === "undefined") {
+    return void 0;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new TypeError("[Holo Events] Listener delay must be a finite number greater than or equal to 0.");
+    }
+    return value;
+  }
+  if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+    throw new TypeError("[Holo Events] Listener delay dates must be valid Date instances.");
+  }
+  return value;
+}
+function toPosixPath(value) {
+  return value.replaceAll("\\", "/");
+}
+function deriveEventNameFromSourcePath(sourcePath) {
+  const normalized = toPosixPath(sourcePath).replace(/\.[^.]+$/, "");
+  const eventRootIndex = normalized.lastIndexOf("/events/");
+  const relevant = eventRootIndex >= 0 ? normalized.slice(eventRootIndex + "/events/".length) : normalized;
+  const derived = relevant.split("/").map((part) => part.trim()).filter(Boolean).join(".");
+  if (!derived) {
+    throw new Error("[Holo Events] Derived event names require a non-empty source path.");
+  }
+  return derived;
+}
+function isReadonlyArray(value) {
+  return Array.isArray(value);
+}
+function hasEventDefinitionMarker(value) {
+  return !!value && typeof value === "object" && HOLO_EVENT_DEFINITION_MARKER in value;
+}
+function hasListenerDefinitionMarker(value) {
+  return !!value && typeof value === "object" && HOLO_LISTENER_DEFINITION_MARKER in value;
+}
+function isEventDefinition(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeEventDefinition(event) {
+  if (!isEventDefinition(event)) {
+    throw new Error("[Holo Events] Events must be plain objects.");
+  }
+  return {
+    ...event,
+    ...typeof event.name === "undefined" ? {} : { name: normalizeOptionalString(event.name, "Event name") }
+  };
+}
+function defineEvent(event) {
+  const normalized = { ...normalizeEventDefinition(event) };
+  Object.defineProperty(normalized, HOLO_EVENT_DEFINITION_MARKER, {
+    value: true,
+    enumerable: false
+  });
+  return Object.freeze(normalized);
+}
+function normalizeEventReference(value, index) {
+  if (typeof value === "string") {
+    const normalized = value.trim();
+    if (!normalized) {
+      throw new Error(`[Holo Events] Listener event reference at index ${index} must be a non-empty string.`);
+    }
+    return normalized;
+  }
+  if (!isEventDefinition(value)) {
+    throw new Error(`[Holo Events] Listener event reference at index ${index} must be an event definition or string.`);
+  }
+  return Object.freeze(normalizeEventDefinition(value));
+}
+function normalizeListensTo(input) {
+  const entries = isReadonlyArray(input) ? input : [input];
+  if (entries.length === 0) {
+    throw new Error("[Holo Events] Listeners must listen to at least one event.");
+  }
+  return Object.freeze(entries.map((entry, index) => normalizeEventReference(entry, index)));
+}
+function isListenerDefinition(value) {
+  return value !== null && typeof value === "object" && "listensTo" in value && "handle" in value && typeof value.handle === "function";
+}
+function normalizeListenerDefinition(listener) {
+  if (!isListenerDefinition(listener)) {
+    throw new Error('[Holo Events] Listeners must define "listensTo" and a "handle" function.');
+  }
+  const queue = normalizeOptionalBoolean(listener.queue, "Listener queue");
+  const connection = normalizeOptionalString(listener.connection, "Listener connection");
+  const queueName = normalizeOptionalString(listener.queueName, "Listener queue name");
+  const delay = normalizeOptionalDelay(listener.delay);
+  const afterCommit = normalizeOptionalBoolean(listener.afterCommit, "Listener afterCommit");
+  if (queue !== true && (connection || queueName || typeof delay !== "undefined")) {
+    throw new Error("[Holo Events] Listener queue metadata requires queue: true.");
+  }
+  return {
+    ...listener,
+    ...typeof listener.name === "undefined" ? {} : { name: normalizeOptionalString(listener.name, "Listener name") },
+    listensTo: normalizeListensTo(listener.listensTo),
+    ...typeof queue === "undefined" ? {} : { queue },
+    ...typeof connection === "undefined" ? {} : { connection },
+    ...typeof queueName === "undefined" ? {} : { queueName },
+    ...typeof delay === "undefined" ? {} : { delay },
+    ...typeof afterCommit === "undefined" ? {} : { afterCommit }
+  };
+}
+function defineListener(listener) {
+  const normalized = normalizeListenerDefinition(listener);
+  if (isReadonlyArray(normalized.listensTo)) {
+    Object.freeze(normalized.listensTo);
+  }
+  const tagged = {
+    ...normalized
+  };
+  Object.defineProperty(tagged, HOLO_LISTENER_DEFINITION_MARKER, {
+    value: true,
+    enumerable: false
+  });
+  return Object.freeze(tagged);
+}
+var eventInternals = {
+  hasEventDefinitionMarker,
+  hasListenerDefinitionMarker,
+  isReadonlyArray,
+  deriveEventNameFromSourcePath,
+  normalizeEventDefinition,
+  normalizeOptionalBoolean,
+  normalizeOptionalDelay,
+  normalizeOptionalString,
+  normalizeListensTo,
+  normalizeListenerDefinition,
+  toPosixPath
+};
+
+// src/registry.ts
+function getEventRegistryState() {
+  const runtime = globalThis;
+  runtime.__holoEventRegistry__ ??= {
+    events: /* @__PURE__ */ new Map(),
+    listeners: /* @__PURE__ */ new Map(),
+    listenersByEvent: /* @__PURE__ */ new Map(),
+    nextListenerOrder: 0
+  };
+  return runtime.__holoEventRegistry__;
+}
+function deriveListenerIdFromSourcePath(sourcePath) {
+  const normalized = eventInternals.toPosixPath(sourcePath).replace(/\.[^.]+$/, "");
+  const listenerRootIndex = normalized.lastIndexOf("/listeners/");
+  const relevant = listenerRootIndex >= 0 ? normalized.slice(listenerRootIndex + "/listeners/".length) : normalized;
+  const derived = relevant.split("/").map((part) => part.trim()).filter(Boolean).join(".");
+  if (!derived) {
+    throw new Error("[Holo Events] Derived listener identifiers require a non-empty source path.");
+  }
+  return derived;
+}
+function resolveRegisteredEventName(definition, options = {}) {
+  const explicitOption = options.name?.trim();
+  if (explicitOption) {
+    return explicitOption;
+  }
+  const explicitDefinition = definition.name?.trim();
+  if (explicitDefinition) {
+    return explicitDefinition;
+  }
+  const sourcePath = options.sourcePath?.trim();
+  if (sourcePath) {
+    return eventInternals.deriveEventNameFromSourcePath(sourcePath);
+  }
+  throw new Error("[Holo Events] Registered events require an explicit name or a sourcePath-derived name.");
+}
+function resolveRegisteredListenerId(definition, options = {}) {
+  const explicitOption = options.id?.trim();
+  if (explicitOption) {
+    return explicitOption;
+  }
+  const explicitDefinition = definition.name?.trim();
+  if (explicitDefinition) {
+    return explicitDefinition;
+  }
+  const sourcePath = options.sourcePath?.trim();
+  if (sourcePath) {
+    return deriveListenerIdFromSourcePath(sourcePath);
+  }
+  throw new Error("[Holo Events] Registered listeners require an explicit id, listener name, or a sourcePath-derived id.");
+}
+function resolveListenerEventName(reference) {
+  if (typeof reference === "string") {
+    return reference;
+  }
+  const explicitName = reference.name?.trim();
+  if (explicitName) {
+    return explicitName;
+  }
+  throw new Error("[Holo Events] Listener event references must resolve to explicit event names before registration.");
+}
+function resolveListenerEventNames(definition, state) {
+  const names = [...new Set(definition.listensTo.map(resolveListenerEventName))];
+  for (const name of names) {
+    if (!state.events.has(name)) {
+      throw new Error(`[Holo Events] Listener target event "${name}" is not registered.`);
+    }
+  }
+  return Object.freeze(names);
+}
+function removeListenerFromIndexes(state, entry) {
+  for (const eventName of entry.listener.eventNames) {
+    const indexed = state.listenersByEvent.get(eventName);
+    if (!indexed) {
+      continue;
+    }
+    const filtered = indexed.filter((candidate) => candidate.listener.id !== entry.listener.id);
+    if (filtered.length === 0) {
+      state.listenersByEvent.delete(eventName);
+      continue;
+    }
+    state.listenersByEvent.set(eventName, filtered);
+  }
+}
+function insertListenerIntoIndexes(state, entry) {
+  for (const eventName of entry.listener.eventNames) {
+    const indexed = state.listenersByEvent.get(eventName) ?? [];
+    state.listenersByEvent.set(eventName, [...indexed, entry].sort((left, right) => left.order - right.order));
+  }
+}
+function registerEvent(definition, options = {}) {
+  if (!isEventDefinition(definition)) {
+    throw new Error("[Holo Events] Events must be plain objects.");
+  }
+  const normalizedDefinition = normalizeEventDefinition(definition);
+  const name = resolveRegisteredEventName(normalizedDefinition, options);
+  const state = getEventRegistryState();
+  if (state.events.has(name) && options.replaceExisting !== true) {
+    throw new Error(`[Holo Events] Event "${name}" is already registered.`);
+  }
+  const entry = Object.freeze({
+    name,
+    ...options.sourcePath ? { sourcePath: options.sourcePath } : {},
+    definition: Object.freeze({
+      ...normalizedDefinition,
+      name
+    })
+  });
+  state.events.set(name, entry);
+  return entry;
+}
+function registerEvents(definitions) {
+  return Object.freeze(definitions.map((entry) => {
+    return registerEvent(entry.definition, entry.options);
+  }));
+}
+function getRegisteredEvent(name) {
+  return getEventRegistryState().events.get(name);
+}
+function listRegisteredEvents() {
+  return Object.freeze([...getEventRegistryState().events.values()].sort((left, right) => left.name.localeCompare(right.name)));
+}
+function unregisterEvent(name) {
+  const state = getEventRegistryState();
+  const listeners = state.listenersByEvent.get(name);
+  if (listeners && listeners.length > 0) {
+    throw new Error(`[Holo Events] Event "${name}" cannot be unregistered while listeners are registered for it.`);
+  }
+  return state.events.delete(name);
+}
+function registerListener(definition, options = {}) {
+  if (!isListenerDefinition(definition)) {
+    throw new Error('[Holo Events] Listeners must define "listensTo" and a "handle" function.');
+  }
+  const normalizedDefinition = normalizeListenerDefinition(definition);
+  const id = resolveRegisteredListenerId(normalizedDefinition, options);
+  const state = getEventRegistryState();
+  if (state.listeners.has(id) && options.replaceExisting !== true) {
+    throw new Error(`[Holo Events] Listener "${id}" is already registered.`);
+  }
+  const eventNames = resolveListenerEventNames(normalizedDefinition, state);
+  const existing = state.listeners.get(id);
+  if (existing) {
+    removeListenerFromIndexes(state, existing);
+  }
+  const listener = Object.freeze({
+    id,
+    ...options.sourcePath ? { sourcePath: options.sourcePath } : {},
+    eventNames,
+    definition: Object.freeze({
+      ...normalizedDefinition,
+      ...typeof normalizedDefinition.name === "undefined" ? {} : { name: normalizedDefinition.name }
+    })
+  });
+  const registration = {
+    listener,
+    order: state.nextListenerOrder
+  };
+  state.nextListenerOrder += 1;
+  state.listeners.set(id, registration);
+  insertListenerIntoIndexes(state, registration);
+  return listener;
+}
+function registerListeners(definitions) {
+  return Object.freeze(definitions.map((entry) => {
+    return registerListener(entry.definition, entry.options);
+  }));
+}
+function getRegisteredListener(id) {
+  return getEventRegistryState().listeners.get(id)?.listener;
+}
+function listRegisteredListeners() {
+  return Object.freeze(
+    [...getEventRegistryState().listeners.values()].sort((left, right) => left.listener.id.localeCompare(right.listener.id)).map((entry) => entry.listener)
+  );
+}
+function listRegisteredListenersForEvent(eventName) {
+  const indexed = getEventRegistryState().listenersByEvent.get(eventName) ?? [];
+  return Object.freeze(indexed.map((entry) => entry.listener));
+}
+function unregisterListener(id) {
+  const state = getEventRegistryState();
+  const existing = state.listeners.get(id);
+  if (!existing) {
+    return false;
+  }
+  removeListenerFromIndexes(state, existing);
+  return state.listeners.delete(id);
+}
+function resetEventRegistry() {
+  const state = getEventRegistryState();
+  state.events.clear();
+  state.listeners.clear();
+  state.listenersByEvent.clear();
+  state.nextListenerOrder = 0;
+}
+function resetListenerRegistry() {
+  const state = getEventRegistryState();
+  state.listeners.clear();
+  state.listenersByEvent.clear();
+  state.nextListenerOrder = 0;
+}
+function resetEventsRegistry() {
+  resetEventRegistry();
+}
+var eventRegistryInternals = {
+  deriveListenerIdFromSourcePath,
+  getEventRegistryState,
+  resolveListenerEventNames,
+  resolveRegisteredEventName,
+  resolveRegisteredListenerId
+};
+
+// src/db.ts
+import { connectionAsyncContext } from "@holo-js/db";
+function deferEventDispatchToDatabaseCommit(callback, _context) {
+  const active = connectionAsyncContext.getActive()?.connection;
+  if (!active || active.getScope().kind === "root") {
+    return false;
+  }
+  active.afterCommit(callback);
+  return true;
+}
+
+// src/queue.ts
+import {
+  defineJob,
+  dispatch as dispatchQueueJob,
+  getRegisteredQueueJob,
+  registerQueueJob
+} from "@holo-js/queue";
+var EVENTS_INVOKE_LISTENER_JOB = "holo.events.invoke-listener";
+function createQueuedListenerEventEnvelope(payload) {
+  return Object.freeze({
+    name: payload.eventName,
+    payload: payload.payload,
+    occurredAt: payload.occurredAt
+  });
+}
+function requireQueuedListener(listenerId) {
+  const listener = getRegisteredListener(listenerId);
+  if (!listener) {
+    throw new Error(`[Holo Events] Queued listener "${listenerId}" is not registered.`);
+  }
+  return listener;
+}
+function assertQueuedListenerMatchesEvent(listener, eventName) {
+  if (!listener.eventNames.includes(eventName)) {
+    throw new Error(
+      `[Holo Events] Queued listener "${listener.id}" is not registered for event "${eventName}".`
+    );
+  }
+}
+async function runQueuedListenerInvocation(payload) {
+  const listener = requireQueuedListener(payload.listenerId);
+  assertQueuedListenerMatchesEvent(listener, payload.eventName);
+  await listener.definition.handle(createQueuedListenerEventEnvelope(payload));
+}
+function ensureEventsQueueJobRegistered() {
+  if (getRegisteredQueueJob(EVENTS_INVOKE_LISTENER_JOB)) {
+    return;
+  }
+  registerQueueJob(defineJob({
+    async handle(payload) {
+      await runQueuedListenerInvocation(payload);
+    }
+  }), {
+    name: EVENTS_INVOKE_LISTENER_JOB
+  });
+}
+async function dispatchQueuedListenerViaQueue(dispatch) {
+  ensureEventsQueueJobRegistered();
+  let pending = dispatchQueueJob(EVENTS_INVOKE_LISTENER_JOB, {
+    listenerId: dispatch.listenerId,
+    eventName: dispatch.event.name,
+    occurredAt: dispatch.event.occurredAt,
+    payload: dispatch.event.payload
+  });
+  if (typeof dispatch.connection !== "undefined") {
+    pending = pending.onConnection(dispatch.connection);
+  }
+  if (typeof dispatch.queueName !== "undefined") {
+    pending = pending.onQueue(dispatch.queueName);
+  }
+  if (typeof dispatch.delay !== "undefined") {
+    pending = pending.delay(dispatch.delay);
+  }
+  await pending.dispatch();
+}
+var eventQueueInternals = {
+  assertQueuedListenerMatchesEvent,
+  createQueuedListenerEventEnvelope,
+  requireQueuedListener
+};
+
+// src/runtime.ts
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function assertEventJsonValue(value, path, state) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`[Holo Events] Event payload at "${path}" must be JSON-serializable for queued listeners.`);
+    }
+    return;
+  }
+  if (typeof value === "undefined" || typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") {
+    throw new TypeError(`[Holo Events] Event payload at "${path}" must be JSON-serializable for queued listeners.`);
+  }
+  if (Array.isArray(value)) {
+    if (state.seen.has(value)) {
+      throw new TypeError(`[Holo Events] Event payload at "${path}" contains a circular reference.`);
+    }
+    state.seen.add(value);
+    for (let index = 0; index < value.length; index += 1) {
+      assertEventJsonValue(value[index], `${path}[${index}]`, state);
+    }
+    state.seen.delete(value);
+    return;
+  }
+  if (!isPlainObject(value)) {
+    throw new TypeError(`[Holo Events] Event payload at "${path}" must be a plain JSON object, array, or primitive for queued listeners.`);
+  }
+  if (state.seen.has(value)) {
+    throw new TypeError(`[Holo Events] Event payload at "${path}" contains a circular reference.`);
+  }
+  state.seen.add(value);
+  for (const [key, nested] of Object.entries(value)) {
+    assertEventJsonValue(nested, `${path}.${key}`, state);
+  }
+  state.seen.delete(value);
+}
+function validateQueuedEventPayload(payload) {
+  assertEventJsonValue(payload, "payload", { seen: /* @__PURE__ */ new Set() });
+}
+function getRuntimeState() {
+  const runtime = globalThis;
+  runtime.__holoEventsRuntime__ ??= {
+    hooks: {}
+  };
+  return runtime.__holoEventsRuntime__;
+}
+function createRuntimeBinding(state) {
+  return Object.freeze({
+    hooks: Object.freeze({
+      ...state.hooks
+    })
+  });
+}
+function normalizeEventName(name) {
+  const normalized = name.trim();
+  if (!normalized) {
+    throw new Error("[Holo Events] Event names must be non-empty strings.");
+  }
+  return normalized;
+}
+function resolveDispatchedEventName(event) {
+  if (typeof event === "string") {
+    return normalizeEventName(event);
+  }
+  if (!isEventDefinition(event)) {
+    throw new Error("[Holo Events] Events must be plain objects.");
+  }
+  const explicitName = event.name?.trim();
+  if (!explicitName) {
+    throw new Error("[Holo Events] Dispatching an event definition requires an explicit event name.");
+  }
+  return explicitName;
+}
+function requireRegisteredEvent(name) {
+  const registered = getRegisteredEvent(name);
+  if (!registered) {
+    throw new Error(`[Holo Events] Event "${name}" is not registered.`);
+  }
+  return registered;
+}
+function createEventEnvelope(eventName, payload, occurredAt = Date.now()) {
+  return Object.freeze({
+    name: eventName,
+    payload,
+    occurredAt
+  });
+}
+function splitRegisteredListeners(listeners) {
+  const syncListeners = [];
+  const queuedListeners = [];
+  for (const listener of listeners) {
+    if (listener.definition.queue === true) {
+      queuedListeners.push(listener);
+      continue;
+    }
+    syncListeners.push(listener);
+  }
+  return Object.freeze({
+    syncListeners: Object.freeze(syncListeners),
+    queuedListeners: Object.freeze(queuedListeners)
+  });
+}
+async function executeSyncListeners(listeners, event) {
+  for (const listener of listeners) {
+    await executeListener(listener, event);
+  }
+  return listeners.length;
+}
+async function executeListenerGroups(syncListeners, queuedListeners, event, options) {
+  const syncCount = await executeSyncListeners(syncListeners, event);
+  const queuedCount = await dispatchQueuedListeners(queuedListeners, event, options);
+  return Object.freeze({
+    syncCount,
+    queuedCount
+  });
+}
+async function executeListener(listener, event) {
+  await listener.definition.handle(event);
+}
+function createQueuedListenerDispatch(listener, event, options) {
+  return Object.freeze({
+    listenerId: listener.id,
+    event,
+    ...typeof (options.connection ?? listener.definition.connection) === "undefined" ? {} : { connection: options.connection ?? listener.definition.connection },
+    ...typeof (options.queueName ?? listener.definition.queueName) === "undefined" ? {} : { queueName: options.queueName ?? listener.definition.queueName },
+    ...typeof (options.delay ?? listener.definition.delay) === "undefined" ? {} : { delay: options.delay ?? listener.definition.delay }
+  });
+}
+async function dispatchQueuedListeners(listeners, event, options) {
+  if (listeners.length === 0) {
+    return 0;
+  }
+  validateQueuedEventPayload(event.payload);
+  const dispatcher = getRuntimeState().hooks.dispatchQueuedListener ?? dispatchQueuedListenerViaQueue;
+  for (const listener of listeners) {
+    await dispatcher(createQueuedListenerDispatch(listener, event, options));
+  }
+  return listeners.length;
+}
+function splitListenersForExecution(listeners, forceAfterCommit) {
+  const immediateSyncListeners = [];
+  const immediateQueuedListeners = [];
+  const deferredSyncListeners = [];
+  const deferredQueuedListeners = [];
+  for (const listener of listeners) {
+    const shouldDefer = forceAfterCommit || listener.definition.afterCommit === true;
+    if (shouldDefer) {
+      if (listener.definition.queue === true) {
+        deferredQueuedListeners.push(listener);
+        continue;
+      }
+      deferredSyncListeners.push(listener);
+      continue;
+    }
+    if (listener.definition.queue === true) {
+      immediateQueuedListeners.push(listener);
+      continue;
+    }
+    immediateSyncListeners.push(listener);
+  }
+  return Object.freeze({
+    immediateSyncListeners: Object.freeze(immediateSyncListeners),
+    immediateQueuedListeners: Object.freeze(immediateQueuedListeners),
+    deferredSyncListeners: Object.freeze(deferredSyncListeners),
+    deferredQueuedListeners: Object.freeze(deferredQueuedListeners)
+  });
+}
+function scheduleDeferredDispatch(callback, eventName) {
+  const defer = getRuntimeState().hooks.defer ?? deferEventDispatchToDatabaseCommit;
+  return defer(callback, {
+    eventName,
+    afterCommit: true
+  });
+}
+async function executeDispatch(event, payload, options = {}) {
+  const eventName = resolveDispatchedEventName(event);
+  requireRegisteredEvent(eventName);
+  const envelope = createEventEnvelope(eventName, payload);
+  const listeners = listRegisteredListenersForEvent(eventName);
+  const groups = splitListenersForExecution(listeners, options.afterCommit === true);
+  if (options.afterCommit) {
+    const scheduled = scheduleDeferredDispatch(async () => {
+      await executeListenerGroups(
+        [...groups.immediateSyncListeners, ...groups.deferredSyncListeners],
+        [...groups.immediateQueuedListeners, ...groups.deferredQueuedListeners],
+        envelope,
+        options
+      );
+    }, eventName);
+    if (scheduled) {
+      return Object.freeze({
+        eventName,
+        occurredAt: envelope.occurredAt,
+        deferred: true,
+        syncListeners: groups.immediateSyncListeners.length + groups.deferredSyncListeners.length,
+        queuedListeners: groups.immediateQueuedListeners.length + groups.deferredQueuedListeners.length
+      });
+    }
+  }
+  const immediate = await executeListenerGroups(
+    groups.immediateSyncListeners,
+    groups.immediateQueuedListeners,
+    envelope,
+    options
+  );
+  let deferred = false;
+  if (groups.deferredSyncListeners.length > 0 || groups.deferredQueuedListeners.length > 0) {
+    const scheduled = scheduleDeferredDispatch(async () => {
+      await executeListenerGroups(
+        groups.deferredSyncListeners,
+        groups.deferredQueuedListeners,
+        envelope,
+        options
+      );
+    }, eventName);
+    if (scheduled) {
+      deferred = true;
+    } else {
+      await executeListenerGroups(
+        groups.deferredSyncListeners,
+        groups.deferredQueuedListeners,
+        envelope,
+        options
+      );
+    }
+  }
+  return Object.freeze({
+    eventName,
+    occurredAt: envelope.occurredAt,
+    deferred,
+    syncListeners: immediate.syncCount + groups.deferredSyncListeners.length,
+    queuedListeners: immediate.queuedCount + groups.deferredQueuedListeners.length
+  });
+}
+var PendingEventDispatch = class _PendingEventDispatch {
+  constructor(event, payload, options = {}) {
+    this.event = event;
+    this.payload = payload;
+    this.options = options;
+  }
+  options;
+  executionPromise;
+  afterCommit() {
+    return new _PendingEventDispatch(this.event, this.payload, {
+      ...this.options,
+      afterCommit: true
+    });
+  }
+  onConnection(name) {
+    return new _PendingEventDispatch(this.event, this.payload, {
+      ...this.options,
+      connection: eventInternals.normalizeOptionalString(name, "Dispatch connection")
+    });
+  }
+  onQueue(name) {
+    return new _PendingEventDispatch(this.event, this.payload, {
+      ...this.options,
+      queueName: eventInternals.normalizeOptionalString(name, "Dispatch queue name")
+    });
+  }
+  delay(value) {
+    eventInternals.normalizeOptionalDelay(value);
+    return new _PendingEventDispatch(this.event, this.payload, {
+      ...this.options,
+      delay: value
+    });
+  }
+  async dispatch() {
+    return this.execute();
+  }
+  then(onfulfilled, onrejected) {
+    return this.execute().then(onfulfilled, onrejected);
+  }
+  catch(onrejected) {
+    return this.execute().catch(onrejected);
+  }
+  finally(onfinally) {
+    return this.execute().finally(onfinally ?? void 0);
+  }
+  execute() {
+    this.executionPromise ??= executeDispatch(this.event, this.payload, this.options);
+    return this.executionPromise;
+  }
+};
+function configureEventsRuntime(hooks = {}) {
+  getRuntimeState().hooks = {
+    ...hooks
+  };
+}
+function getEventsRuntime() {
+  return createRuntimeBinding(getRuntimeState());
+}
+function resetEventsRuntime() {
+  getRuntimeState().hooks = {};
+}
+function dispatchEvent(event, payload) {
+  return new PendingEventDispatch(event, payload);
+}
+var Event = {
+  dispatch: dispatchEvent
+};
+var eventRuntimeInternals = {
+  assertEventJsonValue,
+  createEventEnvelope,
+  createQueuedListenerDispatch,
+  createRuntimeBinding,
+  dispatchQueuedListeners,
+  executeListenerGroups,
+  executeDispatch,
+  executeListener,
+  executeSyncListeners,
+  getRuntimeState,
+  isPlainObject,
+  normalizeEventName,
+  requireRegisteredEvent,
+  resolveDispatchedEventName,
+  scheduleDeferredDispatch,
+  splitRegisteredListeners,
+  splitListenersForExecution,
+  validateQueuedEventPayload
+};
+export {
+  EVENTS_INVOKE_LISTENER_JOB,
+  Event,
+  configureEventsRuntime,
+  deferEventDispatchToDatabaseCommit,
+  defineEvent,
+  defineListener,
+  dispatchEvent,
+  ensureEventsQueueJobRegistered,
+  eventInternals,
+  eventQueueInternals,
+  eventRegistryInternals,
+  eventRuntimeInternals,
+  getEventsRuntime,
+  getRegisteredEvent,
+  getRegisteredListener,
+  isEventDefinition,
+  isListenerDefinition,
+  listRegisteredEvents,
+  listRegisteredListeners,
+  listRegisteredListenersForEvent,
+  normalizeEventDefinition,
+  normalizeListenerDefinition,
+  registerEvent,
+  registerEvents,
+  registerListener,
+  registerListeners,
+  resetEventRegistry,
+  resetEventsRegistry,
+  resetEventsRuntime,
+  resetListenerRegistry,
+  runQueuedListenerInvocation,
+  unregisterEvent,
+  unregisterListener
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@holo-js/events",
+  "version": "0.1.0",
+  "description": "Holo-JS Framework - event contracts and runtime surface",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "stub": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest --run"
+  },
+  "dependencies": {
+    "@holo-js/db": "workspace:*",
+    "@holo-js/queue": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "tsup": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}