@zudojs/events 0.0.1

package/dist/eventTypes/eventDefinition.type.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Core event primitives for Zudojs.
+ *
+ * Events are immutable messages that describe something that
+ * happened inside the application or framework.
+ *
+ * This module intentionally contains no dispatching logic.
+ */
+import type { EventId as BaseEventId, CorrelationId as BaseCorrelationId } from "@zudojs/constants";
+/**
+ * Unique identifier for an event instance.
+ * Re-exported from @zudojs/constants for type safety.
+ */
+export type EventId = BaseEventId;
+/**
+ * Event type identifier.
+ *
+ * Examples:
+ *
+ * "user.created"
+ * "module.loaded"
+ * "runtime.started"
+ */
+export type EventType = string;
+/**
+ * Event timestamp.
+ */
+export type EventTimestamp = Date;
+/**
+ * Event source identifier.
+ *
+ * Identifies the subsystem that produced the event.
+ */
+export type EventSource = string;
+/**
+ * Correlation identifier.
+ *
+ * Useful for connecting multiple events belonging to the
+ * same operation/request/workflow.
+ * Re-exported from @zudojs/constants for type safety.
+ */
+export type EventCorrelationId = BaseCorrelationId;
+/**
+ * Causation identifier.
+ *
+ * Identifies the event or operation that caused this event.
+ */
+export type EventCausationId = string;
+/**
+ * Generic event payload.
+ */
+export type EventPayload = unknown;
+/**
+ * Base event contract.
+ *
+ * Every Zudojs event must contain a type, unique identifier,
+ * timestamp, and payload.
+ */
+export interface Event<TPayload = EventPayload> {
+    /**
+     * Unique event identifier.
+     */
+    readonly id: EventId;
+    /**
+     * Event type.
+     */
+    readonly type: EventType;
+    /**
+     * Event payload.
+     */
+    readonly payload: TPayload;
+    /**
+     * Time at which the event was created.
+     */
+    readonly timestamp: EventTimestamp;
+    /**
+     * Optional source subsystem.
+     */
+    readonly source?: EventSource;
+    /**
+     * Optional correlation identifier.
+     */
+    readonly correlationId?: EventCorrelationId;
+    /**
+     * Optional causation identifier.
+     */
+    readonly causationId?: EventCausationId;
+    /**
+     * Optional event metadata.
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Input used to create an event.
+ */
+export interface EventInput<TPayload = EventPayload> {
+    /**
+     * Optional event identifier.
+     */
+    readonly id?: EventId;
+    /**
+     * Event type.
+     */
+    readonly type: EventType;
+    /**
+     * Event payload.
+     */
+    readonly payload: TPayload;
+    /**
+     * Optional timestamp.
+     */
+    readonly timestamp?: EventTimestamp | number;
+    /**
+     * Optional source subsystem.
+     */
+    readonly source?: EventSource;
+    /**
+     * Optional correlation identifier.
+     */
+    readonly correlationId?: EventCorrelationId;
+    /**
+     * Optional causation identifier.
+     */
+    readonly causationId?: EventCausationId;
+    /**
+     * Optional event metadata.
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Typed event definition.
+ *
+ * Allows a specific event type to declare its payload.
+ */
+export interface EventDefinition<TType extends EventType = EventType, TPayload = EventPayload> {
+    readonly type: TType;
+    readonly create: (payload: TPayload, options?: Omit<EventInput<TPayload>, "type" | "payload">) => Event<TPayload>;
+}
+/**
+ * Determines whether an unknown value satisfies the Event
+ * contract.
+ */
+export declare function isEvent(value: unknown): value is Event;
+/**
+ * Creates a unique event identifier.
+ * Returns a branded EventId type from @zudojs/constants.
+ */
+export declare function createEventId(): EventId;
+/**
+ * Creates an immutable event.
+ */
+export declare function createEvent<TPayload = EventPayload>(input: EventInput<TPayload>): Event<TPayload>;
+/**
+ * Creates a typed event definition.
+ */
+export declare function defineEvent<TType extends EventType, TPayload>(type: TType): EventDefinition<TType, TPayload>;
+/**
+ * Creates a copy of an event with modified metadata.
+ *
+ * The original event remains immutable.
+ */
+export declare function withEventMetadata<TPayload>(event: Event<TPayload>, metadata: Readonly<Record<string, unknown>>): Event<TPayload>;
+/**
+ * Creates a derived event while preserving correlation
+ * information from the original event.
+ */
+export declare function createDerivedEvent<TPayload>(sourceEvent: Event, input: EventInput<TPayload>): Event<TPayload>;
+/**
+ * Returns the event type.
+ */
+export declare function getEventType<TPayload>(event: Event<TPayload>): EventType;
+/**
+ * Returns the event payload.
+ */
+export declare function getEventPayload<TPayload>(event: Event<TPayload>): TPayload;
+/**
+ * Returns a human-readable event description.
+ */
+export declare function describeEvent(event: Event): string;
+//# sourceMappingURL=eventDefinition.type.d.ts.map

package/dist/eventTypes/eventDefinition.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventDefinition.type.d.ts","sourceRoot":"","sources":["../../src/eventTypes/eventDefinition.type.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,OAAO,IAAI,WAAW,EACtB,aAAa,IAAI,iBAAiB,EACnC,MAAM,mBAAmB,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,WAAW,CAAC;AAElC;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC;AAElC;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEtC;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,WAAW,KAAK,CAAC,QAAQ,GAAG,YAAY;IAC5C;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAExC;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,QAAQ,GAAG,YAAY;IACjD;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC;IAE7C;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAExC;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAC9B,KAAK,SAAS,SAAS,GAAG,SAAS,EACnC,QAAQ,GAAG,YAAY;IAEvB,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAErB,QAAQ,CAAC,MAAM,EAAE,CACf,OAAO,EAAE,QAAQ,EACjB,OAAO,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,KACrD,KAAK,CAAC,QAAQ,CAAC,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAatD;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAIvC;AAsCD;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,GAAG,YAAY,EACjD,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,GAC1B,KAAK,CAAC,QAAQ,CAAC,CAwBjB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,SAAS,SAAS,EAAE,QAAQ,EAC3D,IAAI,EAAE,KAAK,GACV,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,CAqBlC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EACxC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,EACtB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC1C,KAAK,CAAC,QAAQ,CAAC,CASjB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EACzC,WAAW,EAAE,KAAK,EAClB,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,GAC1B,KAAK,CAAC,QAAQ,CAAC,CAWjB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,SAAS,CAExE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAE1E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAElD"}

package/dist/eventTypes/eventDefinition.type.js

@@ -0,0 +1,140 @@
+/**
+ * Core event primitives for Zudojs.
+ *
+ * Events are immutable messages that describe something that
+ * happened inside the application or framework.
+ *
+ * This module intentionally contains no dispatching logic.
+ */
+/**
+ * Determines whether an unknown value satisfies the Event
+ * contract.
+ */
+export function isEvent(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.id === "string" &&
+        typeof candidate.type === "string" &&
+        candidate.timestamp instanceof Date &&
+        "payload" in candidate);
+}
+/**
+ * Creates a unique event identifier.
+ * Returns a branded EventId type from @zudojs/constants.
+ */
+export function createEventId() {
+    const uuid = crypto.randomUUID();
+    return `event:${uuid}`;
+}
+/**
+ * Normalizes an event timestamp.
+ */
+function normalizeTimestamp(timestamp) {
+    if (timestamp instanceof Date) {
+        return new Date(timestamp.getTime());
+    }
+    if (typeof timestamp === "number") {
+        const date = new Date(timestamp);
+        if (Number.isNaN(date.getTime())) {
+            throw new TypeError("Invalid event timestamp.");
+        }
+        return date;
+    }
+    return new Date();
+}
+/**
+ * Freezes event metadata.
+ */
+function normalizeMetadata(metadata) {
+    if (metadata === undefined) {
+        return undefined;
+    }
+    return Object.freeze({
+        ...metadata,
+    });
+}
+/**
+ * Creates an immutable event.
+ */
+export function createEvent(input) {
+    if (typeof input.type !== "string" || input.type.trim().length === 0) {
+        throw new TypeError("Event type must be a non-empty string.");
+    }
+    const event = {
+        id: input.id ?? createEventId(),
+        type: input.type,
+        payload: input.payload,
+        timestamp: normalizeTimestamp(input.timestamp),
+        source: input.source,
+        correlationId: input.correlationId,
+        causationId: input.causationId,
+        metadata: normalizeMetadata(input.metadata),
+    };
+    return Object.freeze(event);
+}
+/**
+ * Creates a typed event definition.
+ */
+export function defineEvent(type) {
+    if (type.trim().length === 0) {
+        throw new TypeError("Event type must be a non-empty string.");
+    }
+    return Object.freeze({
+        type,
+        create(payload, options = {}) {
+            return createEvent({
+                ...options,
+                type,
+                payload,
+            });
+        },
+    });
+}
+/**
+ * Creates a copy of an event with modified metadata.
+ *
+ * The original event remains immutable.
+ */
+export function withEventMetadata(event, metadata) {
+    return createEvent({
+        ...event,
+        metadata: {
+            ...(event.metadata ?? {}),
+            ...metadata,
+        },
+    });
+}
+/**
+ * Creates a derived event while preserving correlation
+ * information from the original event.
+ */
+export function createDerivedEvent(sourceEvent, input) {
+    return createEvent({
+        ...input,
+        correlationId: input.correlationId ??
+            sourceEvent.correlationId ??
+            sourceEvent.id,
+        causationId: input.causationId ?? sourceEvent.id,
+    });
+}
+/**
+ * Returns the event type.
+ */
+export function getEventType(event) {
+    return event.type;
+}
+/**
+ * Returns the event payload.
+ */
+export function getEventPayload(event) {
+    return event.payload;
+}
+/**
+ * Returns a human-readable event description.
+ */
+export function describeEvent(event) {
+    return `${event.type} (${event.id})`;
+}
+//# sourceMappingURL=eventDefinition.type.js.map

package/dist/eventTypes/eventDefinition.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventDefinition.type.js","sourceRoot":"","sources":["../../src/eventTypes/eventDefinition.type.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuKH;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,SAAS,GAAG,KAAgC,CAAC;IAEnD,OAAO,CACL,OAAO,SAAS,CAAC,EAAE,KAAK,QAAQ;QAChC,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ;QAClC,SAAS,CAAC,SAAS,YAAY,IAAI;QACnC,SAAS,IAAI,SAAS,CACvB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;IAEjC,OAAO,SAAS,IAAI,EAAa,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,SAAS,kBAAkB,CAAC,SAAkC;IAC5D,IAAI,SAAS,YAAY,IAAI,EAAE,CAAC;QAC9B,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC;QAEjC,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,SAAS,CAAC,0BAA0B,CAAC,CAAC;QAClD,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,IAAI,IAAI,EAAE,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,SAAS,iBAAiB,CACxB,QAAgC;IAEhC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,QAAQ;KACZ,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CACzB,KAA2B;IAE3B,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,SAAS,CAAC,wCAAwC,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,KAAK,GAAoB;QAC7B,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,aAAa,EAAE;QAE/B,IAAI,EAAE,KAAK,CAAC,IAAI;QAEhB,OAAO,EAAE,KAAK,CAAC,OAAO;QAEtB,SAAS,EAAE,kBAAkB,CAAC,KAAK,CAAC,SAAS,CAAC;QAE9C,MAAM,EAAE,KAAK,CAAC,MAAM;QAEpB,aAAa,EAAE,KAAK,CAAC,aAAa;QAElC,WAAW,EAAE,KAAK,CAAC,WAAW;QAE9B,QAAQ,EAAE,iBAAiB,CAAC,KAAK,CAAC,QAAQ,CAAC;KAC5C,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CACzB,IAAW;IAEX,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,SAAS,CAAC,wCAAwC,CAAC,CAAC;IAChE,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI;QAEJ,MAAM,CACJ,OAAiB,EACjB,OAAO,GAAmD,EAAE;YAE5D,OAAO,WAAW,CAAC;gBACjB,GAAG,OAAO;gBAEV,IAAI;gBAEJ,OAAO;aACR,CAAC,CAAC;QACL,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAsB,EACtB,QAA2C;IAE3C,OAAO,WAAW,CAAC;QACjB,GAAG,KAAK;QAER,QAAQ,EAAE;YACR,GAAG,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;YACzB,GAAG,QAAQ;SACZ;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,WAAkB,EAClB,KAA2B;IAE3B,OAAO,WAAW,CAAC;QACjB,GAAG,KAAK;QAER,aAAa,EACX,KAAK,CAAC,aAAa;YACnB,WAAW,CAAC,aAAa;YACxB,WAAW,CAAC,EAAmC;QAElD,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,WAAW,CAAC,EAAE;KACjD,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAW,KAAsB;IAC3D,OAAO,KAAK,CAAC,IAAI,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAW,KAAsB;IAC9D,OAAO,KAAK,CAAC,OAAO,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,KAAY;IACxC,OAAO,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,EAAE,GAAG,CAAC;AACvC,CAAC"}

package/dist/eventTypes/eventPayload.type.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Event payload primitives for Zudojs.
+ *
+ * Payloads contain the application data carried by an event.
+ * This module provides type-safe payload contracts and helpers
+ * without coupling payloads to the event bus.
+ */
+/**
+ * A generic event payload.
+ */
+export type EventPayload = unknown;
+/**
+ * A structured event payload.
+ */
+export type ObjectEventPayload = Readonly<Record<string, unknown>>;
+/**
+ * Primitive values that can safely be used as payload data.
+ */
+export type PrimitiveEventPayload = string | number | boolean | bigint | symbol | null | undefined;
+/**
+ * JSON-compatible event payload value.
+ */
+export type JsonEventPayload = string | number | boolean | null | JsonEventPayload[] | {
+    readonly [key: string]: JsonEventPayload;
+};
+/**
+ * Payload type map used by strongly typed event systems.
+ */
+export type EventPayloadMap = Record<string, unknown>;
+/**
+ * Extracts the payload associated with an event type.
+ */
+export type PayloadOf<TMap extends EventPayloadMap, TType extends keyof TMap> = TMap[TType];
+/**
+ * Creates a payload map from event definitions.
+ */
+export type PayloadMap<TTypes extends string, TPayload> = {
+    readonly [TType in TTypes]: TPayload;
+};
+/**
+ * Event payload factory.
+ */
+export type EventPayloadFactory<TPayload = EventPayload, TInput = TPayload> = (input: TInput) => TPayload;
+/**
+ * Options used when creating a payload.
+ */
+export interface EventPayloadOptions {
+    /**
+     * Whether the payload should be frozen recursively.
+     *
+     * Defaults to false.
+     */
+    readonly deepFreeze?: boolean;
+    /**
+     * Whether undefined values should be removed from
+     * object payloads.
+     *
+     * Defaults to false.
+     */
+    readonly stripUndefined?: boolean;
+}
+/**
+ * Determines whether a value is a primitive payload.
+ */
+export declare function isPrimitiveEventPayload(value: unknown): value is PrimitiveEventPayload;
+/**
+ * Determines whether a value is a structured object payload.
+ */
+export declare function isObjectEventPayload(value: unknown): value is ObjectEventPayload;
+/**
+ * Determines whether a value can be represented as a JSON
+ * event payload.
+ */
+export declare function isJsonEventPayload(value: unknown): value is JsonEventPayload;
+/**
+ * Creates a payload object from an input object.
+ */
+export declare function createEventPayload<TPayload extends EventPayload>(payload: TPayload, options?: EventPayloadOptions): TPayload;
+/**
+ * Creates a structured object payload.
+ */
+export declare function createObjectEventPayload<const TPayload extends ObjectEventPayload>(payload: TPayload, options?: EventPayloadOptions): TPayload;
+/**
+ * Creates a JSON-compatible event payload.
+ */
+export declare function createJsonEventPayload<const TPayload extends JsonEventPayload>(payload: TPayload, options?: EventPayloadOptions): TPayload;
+/**
+ * Clones a payload using structuredClone when available.
+ *
+ * Falls back to returning the original payload when cloning
+ * is not possible.
+ */
+export declare function cloneEventPayload<TPayload extends EventPayload>(payload: TPayload): TPayload;
+/**
+ * Deeply freezes an event payload.
+ */
+export declare function deepFreeze<T>(value: T): T;
+/**
+ * Removes undefined properties from an object payload.
+ */
+export declare function stripUndefinedValues<T extends ObjectEventPayload>(payload: T): T;
+/**
+ * Merges two object payloads.
+ *
+ * Values from the second payload override values from the
+ * first payload.
+ */
+export declare function mergeEventPayloads<TFirst extends ObjectEventPayload, TSecond extends ObjectEventPayload>(first: TFirst, second: TSecond): TFirst & TSecond;
+/**
+ * Creates a payload factory that always returns the supplied
+ * static payload.
+ */
+export declare function staticPayload<TPayload>(payload: TPayload): EventPayloadFactory<TPayload, void>;
+/**
+ * Creates a payload factory from a transformation function.
+ */
+export declare function definePayloadFactory<TInput, TPayload>(factory: EventPayloadFactory<TPayload, TInput>): EventPayloadFactory<TPayload, TInput>;
+/**
+ * Validates a payload using a custom predicate.
+ */
+export declare function validateEventPayload<TPayload>(payload: unknown, validator: (payload: unknown) => payload is TPayload): TPayload;
+/**
+ * Returns a human-readable payload type.
+ */
+export declare function describeEventPayload(payload: unknown): string;
+//# sourceMappingURL=eventPayload.type.d.ts.map

package/dist/eventTypes/eventPayload.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventPayload.type.d.ts","sourceRoot":"","sources":["../../src/eventTypes/eventPayload.type.ts"],"names":[],"mappings":"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"}

package/dist/eventTypes/eventPayload.type.js

@@ -0,0 +1,167 @@
+/**
+ * Event payload primitives for Zudojs.
+ *
+ * Payloads contain the application data carried by an event.
+ * This module provides type-safe payload contracts and helpers
+ * without coupling payloads to the event bus.
+ */
+/**
+ * Determines whether a value is a primitive payload.
+ */
+export function isPrimitiveEventPayload(value) {
+    return (value === null ||
+        value === undefined ||
+        (typeof value !== "object" && typeof value !== "function"));
+}
+/**
+ * Determines whether a value is a structured object payload.
+ */
+export function isObjectEventPayload(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Determines whether a value can be represented as a JSON
+ * event payload.
+ */
+export function isJsonEventPayload(value) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean") {
+        return true;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value);
+    }
+    if (Array.isArray(value)) {
+        return value.every((item) => isJsonEventPayload(item));
+    }
+    if (typeof value === "object") {
+        return Object.values(value).every((item) => isJsonEventPayload(item));
+    }
+    return false;
+}
+/**
+ * Creates a payload object from an input object.
+ */
+export function createEventPayload(payload, options = {}) {
+    let result = payload;
+    if (options.stripUndefined && isObjectEventPayload(result)) {
+        result = stripUndefinedValues(result);
+    }
+    if (options.deepFreeze) {
+        result = deepFreeze(result);
+    }
+    return result;
+}
+/**
+ * Creates a structured object payload.
+ */
+export function createObjectEventPayload(payload, options = {}) {
+    return createEventPayload(payload, options);
+}
+/**
+ * Creates a JSON-compatible event payload.
+ */
+export function createJsonEventPayload(payload, options = {}) {
+    if (!isJsonEventPayload(payload)) {
+        throw new TypeError("Event payload must contain only JSON-compatible values.");
+    }
+    return createEventPayload(payload, options);
+}
+/**
+ * Clones a payload using structuredClone when available.
+ *
+ * Falls back to returning the original payload when cloning
+ * is not possible.
+ */
+export function cloneEventPayload(payload) {
+    if (typeof structuredClone === "function") {
+        try {
+            return structuredClone(payload);
+        }
+        catch {
+            // Fall through to the original payload.
+        }
+    }
+    return payload;
+}
+/**
+ * Deeply freezes an event payload.
+ */
+export function deepFreeze(value) {
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    if (Object.isFrozen(value)) {
+        return value;
+    }
+    const object = value;
+    for (const key of Reflect.ownKeys(object)) {
+        const child = object[key];
+        if (child !== null &&
+            typeof child === "object" &&
+            !Object.isFrozen(child)) {
+            deepFreeze(child);
+        }
+    }
+    return Object.freeze(value);
+}
+/**
+ * Removes undefined properties from an object payload.
+ */
+export function stripUndefinedValues(payload) {
+    const result = {};
+    for (const [key, value] of Object.entries(payload)) {
+        if (value !== undefined) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Merges two object payloads.
+ *
+ * Values from the second payload override values from the
+ * first payload.
+ */
+export function mergeEventPayloads(first, second) {
+    return {
+        ...first,
+        ...second,
+    };
+}
+/**
+ * Creates a payload factory that always returns the supplied
+ * static payload.
+ */
+export function staticPayload(payload) {
+    return () => payload;
+}
+/**
+ * Creates a payload factory from a transformation function.
+ */
+export function definePayloadFactory(factory) {
+    return factory;
+}
+/**
+ * Validates a payload using a custom predicate.
+ */
+export function validateEventPayload(payload, validator) {
+    if (!validator(payload)) {
+        throw new TypeError("Event payload validation failed.");
+    }
+    return payload;
+}
+/**
+ * Returns a human-readable payload type.
+ */
+export function describeEventPayload(payload) {
+    if (payload === null) {
+        return "null";
+    }
+    if (Array.isArray(payload)) {
+        return "array";
+    }
+    return typeof payload;
+}
+//# sourceMappingURL=eventPayload.type.js.map

package/dist/eventTypes/eventPayload.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventPayload.type.js","sourceRoot":"","sources":["../../src/eventTypes/eventPayload.type.ts"],"names":[],"mappings":"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"}