Events API

Generated public TypeScript reference for @relkit/events.

Common APIs

• defineEvent
• defineEventFunction

For configuration and examples, read events, domains, organization.

For a complete workflow, follow react to order events.

Public imports

• @relkit/events — 44 exports
• @relkit/events/effect — 39 exports

All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API’s inline sample, a maintained repository usage, or the shared module walkthrough.

client-errors.ts

EventClientValidationError (class)

Other expected client validation failure.

Example

new EventClientValidationError({ message: "Invalid event options" });

Signature

declare class EventClientValidationError

Source

EventDependencyError (class)

Publication attempted without a declared event dependency.

Example

new EventDependencyError("orders.created");

Signature

declare class EventDependencyError {
  constructor(eventId: string);
}

Source

code (property)

Signature

readonly code: "RELKIT_EVENT_DEPENDENCY_UNDECLARED"

Source

EventOperationCancelledError (class)

Publication cancelled through its AbortSignal.

Example

new EventOperationCancelledError();

Signature

declare class EventOperationCancelledError {
  constructor();
}

Source

code (property)

Signature

readonly code: "ABORT_ERR"

Source

EventOperationTimeoutError (class)

Publication exceeded its absolute deadline.

Example

new EventOperationTimeoutError();

Signature

declare class EventOperationTimeoutError {
  constructor();
}

Source

code (property)

Signature

readonly code: "ETIMEDOUT"

Source

EventPayloadValidationError (class)

Payload rejected by its Standard Schema validator.

Example

new EventPayloadValidationError([{ message: "Required" }]);

Signature

declare class EventPayloadValidationError { constructor(readonly issues: readonly StandardIssue[]) }

Source

code (property)

Signature

readonly code: "RELKIT_EVENT_PAYLOAD_VALIDATION"

Source

EventPayloadValidationFailure (class)

Tagged payload failure used by Effect clients before Promise adaptation.

Example

new EventPayloadValidationFailure([{ message: "Required" }]);

Signature

declare class EventPayloadValidationFailure {
  constructor(issues: readonly StandardIssue[]);
}

Source

issues (property)

Signature

readonly issues: ReadonlyArray<StandardIssue>

Source

EventProfileError (class)

Requested provider profile is missing.

Example

new EventProfileError("default");

Signature

declare class EventProfileError {
  constructor(profile: string);
}

Source

code (property)

Signature

readonly code: "RELKIT_EVENT_PROFILE_UNKNOWN"

Source

EventProviderError (class)

Selected provider cannot publish events.

Example

new EventProviderError();

Signature

declare class EventProviderError {
  constructor();
}

Source

code (property)

Signature

readonly code: "RELKIT_EVENT_PROVIDER_UNAVAILABLE"

Source

client-operation.ts

EventWorkFailed (class)

Typed failure returned by the work callback.

Example

new EventWorkFailed({ cause: new Error("Provider failed") });

Signature

declare class EventWorkFailed

Source

runAbortable

Promise compatibility adapter for abortable event work.

Throws

The established cancellation, timeout, or provider error.

Example

await runAbortable(new AbortController().signal, undefined, async () => 1);

Signature

declare const runAbortable: <A>(
  signal: AbortSignal,
  deadlineMs: number | undefined,
  work: () => Promise<A>,
) => Promise<A>;

Source

runAbortableEffect

Runs callback work with an owned abort listener and deadline timer.

Example

Effect.runPromise(runAbortableEffect(new AbortController().signal, undefined, async () => 1));

Signature

declare const runAbortableEffect: <A>(
  signal: AbortSignal,
  deadlineMs: number | undefined,
  work: (effectSignal: AbortSignal) => Promise<A>,
) => Effect.Effect<
  A,
  | EventClientValidationError
  | EventDependencyError
  | EventOperationCancelledError
  | EventOperationTimeoutError
  | EventPayloadValidationFailure
  | EventWorkFailed,
  never
>;

Source

client-provider.ts

notify

Invokes an edge hook without allowing telemetry failure to replace publication.

Example

notify(onObservedEdge, edge);

Signature

declare const notify: <T>(
  hook: ((value: T) => void) | undefined,
  value: T,
  enabled?: boolean,
) => void;

Source

notifyEffect

Effect implementation of best-effort edge notification.

Example

Effect.runSync(notifyEffect(onObservedEdge, edge));

Signature

declare const notifyEffect: <T>(
  hook: ((value: T) => void) | undefined,
  value: T,
  enabled?: boolean | undefined,
) => Effect.Effect<void, never, never>;

Source

resolveProvider

Synchronous provider resolution adapter.

Throws

EventProfileError, EventProviderError, or a resolver error.

Example

resolveProvider(provider, "default", undefined);

Signature

declare const resolveProvider: (
  source: unknown,
  profile: string,
  resolveProfile: ((profile: string) => unknown) | undefined,
) => EventProvider;

Source

resolveProviderEffect

Resolves a provider for a named profile.

Example

Effect.runSync(resolveProviderEffect(provider, "default", undefined));

Signature

declare const resolveProviderEffect: (
  source: unknown,
  profile: string,
  resolveProfile: ((profile: string) => unknown) | undefined,
) => Effect.Effect<
  EventProvider,
  EventClientValidationError | EventProfileError | EventProviderError,
  never
>;

Source

resolveValue

Resolves a fixed or lazy correlation ID.

Example

resolveValue(() => "correlation-1");

Signature

declare const resolveValue: (value: EventClientOptions["correlationId"]) => string | undefined;

Source

resolveValueEffect

Effect implementation of lazy correlation ID resolution.

Example

Effect.runSync(resolveValueEffect(() => "correlation-1"));

Signature

declare const resolveValueEffect: (
  value: string | (() => string | undefined) | undefined,
) => Effect.Effect<string | undefined, EventClientValidationError, never>;

Source

client-publish.ts

EventPublisher (class)

Substitutable provider boundary for Effect event publication.

Example

Effect.provide(publishEventEffect(setup, payload), eventPublisherLayer(provider));

Signature

declare class EventPublisher

Source

eventPublisherLayer

Adapts a Promise provider into a typed Effect service layer.

Example

eventPublisherLayer(provider);

Signature

declare const eventPublisherLayer: (provider: EventProvider) => Layer.Layer<EventPublisher>;

Source

publishEventEffect

Publishes one event through a supplied provider service.

Example

Effect.runPromise(
  publishEventEffect(setup, payload).pipe(Effect.provide(eventPublisherLayer(provider))),
);

Signature

declare const publishEventEffect: <
  Id extends string,
  Version extends number,
  PayloadSchema extends StandardSchemaV1,
>(
  setup: EventPublishSetup<Id, Version, PayloadSchema>,
  payload: InferInput<PayloadSchema>,
  request?: EventPublishOptions,
) => Effect.Effect<
  EventPublishResult<Id, Version, InferOutput<PayloadSchema>>,
  EventPublishFailure,
  EventPublisher
>;

Source

client-publish.types.ts

EventProvider

Signature

declare const EventProvider: EventProvider;

Source

EventPublishFailure (type alias)

Typed failures of an Effect event publication.

Example

Effect.catchTag(publishEventEffect(setup, payload), "EventPayloadValidationFailure", handle);

Signature

type EventPublishFailure =
  | EventClientValidationError
  | EventDependencyError
  | EventOperationCancelledError
  | EventOperationTimeoutError
  | EventPayloadValidationFailure
  | EventWorkFailed;

Source

EventPublishOptions

Signature

declare const EventPublishOptions: EventPublishOptions;

Source

EventPublishResult

Signature

declare const EventPublishResult: EventPublishResult<Id, Version, Payload>;

Source

EventPublishSetup (interface)

Validated state captured by a generated event client.

Example

const setup: EventPublishSetup<"orders.created", 1, typeof schema> = validated;

Signature

export interface EventPublishSetup<
  Id extends string,
  Version extends number,
  PayloadSchema extends StandardSchemaV1,
> {
  readonly options: EventClientOptions<Id, Version, PayloadSchema>;
  readonly ownerId: string;
  readonly eventId: Id;
  readonly version: Version;
  readonly profile: string;
  readonly declared: boolean;
}

Source

EventPublisherService (interface)

Provider operation supplied to an Effect publication.

Example

const publisher: EventPublisherService = { publish: () => Effect.succeed(reply) };

Signature

export interface EventPublisherService {
  /** Publishes a validated payload.
   * @param payload - Decoded payload.
   * @param options - Validated request options.
   * @param context - Cancellation and trace context.
   * @returns Provider metadata or EventWorkFailed.
   * @example yield* publisher.publish(payload, {}, context)
   */
  readonly publish: (
    payload: unknown,
    options: EventPublishOptions,
    context: EventOperationContext,
  ) => Effect.Effect<EventProviderResult, EventWorkFailed>;
}

Source

InferInput

Signature

declare const InferInput: InferInput<S>;

Source

InferOutput

Signature

declare const InferOutput: InferOutput<S>;

Source

StandardSchemaV1

Signature

declare const StandardSchemaV1: StandardSchemaV1<TInput, TOutput>;

Source

client-record.ts

isRecord

Checks a value for a plain record shape.

Example

isRecord({ key: "value" });

Signature

declare const isRecord: (value: unknown) => value is Record<string, unknown>;

Source

isRecordEffect

Effect implementation of the client record predicate.

Example

Effect.runSync(isRecordEffect({ key: "value" }));

Signature

declare const isRecordEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

client-result.ts

EventIdentity (class)

Substitutable time and identifier boundary for event envelopes.

Example

Effect.provide(
  normalizeResultEffect(reply, payload, {}, context, undefined, "orders.created", 1),
  EventIdentityLive,
);

Signature

declare class EventIdentity

Source

EventIdentityLive

Default wall clock and random UUID source.

Example

Effect.provide(
  normalizeResultEffect(reply, payload, {}, context, undefined, "orders.created", 1),
  EventIdentityLive,
);

Signature

declare const EventIdentityLive: Layer.Layer<EventIdentity, never, never>;

Source

normalizeResult

Synchronous compatibility adapter for provider result normalization.

Throws

TypeError when provider metadata cannot be normalized.

Example

normalizeResult(reply, input, {}, context, undefined, "orders.created", 1);

Signature

declare const normalizeResult: <Id extends string, Version extends number, Payload>(
  value: EventProviderResult | undefined,
  payload: Payload,
  options: EventPublishOptions,
  context: EventOperationContext,
  now: (() => Date) | undefined,
  eventId: Id,
  version: Version,
) => EventPublishResult<Id, Version, Payload>;

Source

normalizeResultEffect

Builds the accepted event envelope from provider metadata.

Example

Effect.runSync(normalizeResultEffect(reply, input, {}, context, undefined, "orders.created", 1));

Signature

declare const normalizeResultEffect: <Id extends string, Version extends number, Payload>(
  value: EventProviderResult | undefined,
  payload: Payload,
  options: EventPublishOptions,
  context: EventOperationContext,
  now: (() => Date) | undefined,
  eventId: Id,
  version: Version,
) => Effect.Effect<EventPublishResult<Id, Version, Payload>, EventClientValidationError>;

Source

client-result.types.ts

Substitutable clock and identifier source for event envelopes.

Example

const identity: EventIdentityService = { now: () => new Date(0), nextId: () => "event-1" };

EventIdentityService (interface)

Substitutable clock and identifier source for event envelopes.

Example

const identity: EventIdentityService = { now: () => new Date(0), nextId: () => "event-1" };

Signature

export interface EventIdentityService {
  /** Reads the current wall-clock time.
   * @returns The current date.
   * @example identity.now()
   */
  readonly now: () => Date;
  /** Generates a unique event instance ID.
   * @returns An opaque instance ID.
   * @example identity.nextId()
   */
  readonly nextId: () => string;
}

Source

EventOperationContext

Signature

declare const EventOperationContext: EventOperationContext;

Source

EventProviderResult

Signature

declare const EventProviderResult: EventProviderResult<Id, Version, Payload>;

Source

EventPublishOptions

Signature

declare const EventPublishOptions: EventPublishOptions;

Source

EventPublishResult

Signature

declare const EventPublishResult: EventPublishResult<Id, Version, Payload>;

Source

client-utils.ts

EventClientValidationError

Signature

declare const EventClientValidationError: typeof EventClientValidationError;

Source

EventDependencyError

Signature

declare const EventDependencyError: typeof EventDependencyError;

Source

EventOperationCancelledError

Signature

declare const EventOperationCancelledError: typeof EventOperationCancelledError;

Source

EventOperationTimeoutError

Signature

declare const EventOperationTimeoutError: typeof EventOperationTimeoutError;

Source

EventPayloadValidationError

Signature

declare const EventPayloadValidationError: typeof EventPayloadValidationError;

Source

EventProfileError

Signature

declare const EventProfileError: typeof EventProfileError;

Source

EventProviderError

Signature

declare const EventProviderError: typeof EventProviderError;

Source

assertOptionalText

Signature

declare const assertOptionalText: (value: unknown, name: string) => void;

Source

assertOptionalTextEffect

Signature

declare const assertOptionalTextEffect: (
  value: unknown,
  name: string,
) => Effect<void, EventClientValidationError, never>;

Source

assertVersion

Signature

declare const assertVersion: (value: unknown) => asserts value is number;

Source

assertVersionEffect

Signature

declare const assertVersionEffect: (
  value: unknown,
) => Effect<number, EventClientValidationError, never>;

Source

normalizeAttributesEffect

Signature

declare const normalizeAttributesEffect: (
  value: unknown,
) => Effect<Readonly<Record<string, EventAttributeValue>>, EventClientValidationError, never>;

Source

normalizeOptions

Signature

declare const normalizeOptions: (value: unknown) => EventPublishOptions;

Source

normalizeOptionsEffect

Signature

declare const normalizeOptionsEffect: (
  value: unknown,
) => Effect<EventPublishOptions, EventClientValidationError, never>;

Source

normalizeResult

Signature

declare const normalizeResult: <Id extends string, Version extends number, Payload>(
  value: EventProviderResult | undefined,
  payload: Payload,
  options: EventPublishOptions,
  context: EventOperationContext,
  now: (() => Date) | undefined,
  eventId: Id,
  version: Version,
) => EventPublishResult<Id, Version, Payload>;

Source

normalizeResultEffect

Signature

declare const normalizeResultEffect: <Id extends string, Version extends number, Payload>(
  value: EventProviderResult | undefined,
  payload: Payload,
  options: EventPublishOptions,
  context: EventOperationContext,
  now: (() => Date) | undefined,
  eventId: Id,
  version: Version,
) => Effect<EventPublishResult<Id, Version, Payload>, EventClientValidationError>;

Source

notify

Signature

declare const notify: <T>(
  hook: ((value: T) => void) | undefined,
  value: T,
  enabled?: boolean,
) => void;

Source

notifyEffect

Signature

declare const notifyEffect: <T>(
  hook: ((value: T) => void) | undefined,
  value: T,
  enabled?: boolean | undefined,
) => Effect<void, never, never>;

Source

parsePayload

Signature

declare const parsePayload: (
  schema: StandardSchemaV1 | undefined,
  payload: unknown,
) => Promise<unknown>;

Source

parsePayloadEffect

Signature

declare const parsePayloadEffect: (
  schema: StandardSchemaV1<unknown, unknown> | undefined,
  payload: unknown,
) => Effect<unknown, EventClientValidationError | EventPayloadValidationFailure, never>;

Source

resolveProvider

Signature

declare const resolveProvider: (
  source: unknown,
  profile: string,
  resolveProfile: ((profile: string) => unknown) | undefined,
) => EventProvider;

Source

resolveProviderEffect

Signature

declare const resolveProviderEffect: (
  source: unknown,
  profile: string,
  resolveProfile: ((profile: string) => unknown) | undefined,
) => Effect<
  EventProvider,
  EventClientValidationError | EventProfileError | EventProviderError,
  never
>;

Source

resolveValue

Signature

declare const resolveValue: (value: EventClientOptions["correlationId"]) => string | undefined;

Source

resolveValueEffect

Signature

declare const resolveValueEffect: (
  value: string | (() => string | undefined) | undefined,
) => Effect<string | undefined, EventClientValidationError, never>;

Source

client-validation.ts

assertOptionalText

Synchronous optional text assertion.

Throws

TypeError for empty or non-text input.

Example

assertOptionalText("key", "key");

Signature

declare const assertOptionalText: (value: unknown, name: string) => void;

Source

assertOptionalTextEffect

Requires optional text to be non-empty when present.

Example

Effect.runSync(assertOptionalTextEffect("key", "key"));

Signature

declare const assertOptionalTextEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<void, EventClientValidationError, never>;

Source

assertVersion

Synchronous positive version assertion.

Throws

TypeError for an invalid version.

Example

assertVersion(1);

Signature

declare const assertVersion: (value: unknown) => asserts value is number;

Source

assertVersionEffect

Requires a positive safe event version.

Example

Effect.runSync(assertVersionEffect(1));

Signature

declare const assertVersionEffect: (
  value: unknown,
) => Effect.Effect<number, EventClientValidationError, never>;

Source

normalizeAttributesEffect

Normalizes and sorts bounded event attributes.

Example

Effect.runSync(normalizeAttributesEffect({ source: "checkout" }));

Signature

declare const normalizeAttributesEffect: (
  value: unknown,
) => Effect.Effect<
  Readonly<Record<string, EventAttributeValue>>,
  EventClientValidationError,
  never
>;

Source

normalizeOptions

Synchronous adapter for request option normalization.

Throws

TypeError for malformed options.

Example

normalizeOptions({ key: "order-1" });

Signature

declare const normalizeOptions: (value: unknown) => EventPublishOptions;

Source

normalizeOptionsEffect

Validates and freezes publisher request options.

Example

Effect.runSync(normalizeOptionsEffect({ key: "order-1" }));

Signature

declare const normalizeOptionsEffect: (
  value: unknown,
) => Effect.Effect<EventPublishOptions, EventClientValidationError, never>;

Source

parsePayload

Promise adapter for payload validation.

Throws

EventPayloadValidationError or EventClientValidationError.

Example

await parsePayload(schema, payload);

Signature

declare const parsePayload: (
  schema: StandardSchemaV1 | undefined,
  payload: unknown,
) => Promise<unknown>;

Source

parsePayloadEffect

Validates a publication payload with its Standard Schema contract.

Example

await Effect.runPromise(parsePayloadEffect(schema, payload));

Signature

declare const parsePayloadEffect: (
  schema: StandardSchemaV1<unknown, unknown> | undefined,
  payload: unknown,
) => Effect.Effect<unknown, EventClientValidationError | EventPayloadValidationFailure, never>;

Source

client.ts

EventAttributeValue

Signature

declare const EventAttributeValue: EventAttributeValue;

Source

EventClient

Signature

declare const EventClient: EventClient<Input, Id, Version, Payload>;

Source

EventClientOptions

Signature

declare const EventClientOptions: EventClientOptions<Id, Version, PayloadSchema>;

Source

EventDeclaredEdge

Signature

declare const EventDeclaredEdge: EventDeclaredEdge;

Source

EventDependencyError

Signature

declare const EventDependencyError: typeof EventDependencyError;

Source

EventInvocationBridge

Signature

declare const EventInvocationBridge: EventInvocationBridge;

Source

EventInvocationBridgeOptions

Signature

declare const EventInvocationBridgeOptions: EventInvocationBridgeOptions;

Source

EventObservedEdge

Signature

declare const EventObservedEdge: EventObservedEdge;

Source

EventOperationCancelledError

Signature

declare const EventOperationCancelledError: typeof EventOperationCancelledError;

Source

EventOperationContext

Signature

declare const EventOperationContext: EventOperationContext;

Source

EventOperationTimeoutError

Signature

declare const EventOperationTimeoutError: typeof EventOperationTimeoutError;

Source

EventPayloadValidationError

Signature

declare const EventPayloadValidationError: typeof EventPayloadValidationError;

Source

EventProfileError

Signature

declare const EventProfileError: typeof EventProfileError;

Source

EventProvider

Signature

declare const EventProvider: EventProvider;

Source

EventProviderError

Signature

declare const EventProviderError: typeof EventProviderError;

Source

EventProviderResult

Signature

declare const EventProviderResult: EventProviderResult<Id, Version, Payload>;

Source

EventPublishOptions

Signature

declare const EventPublishOptions: EventPublishOptions;

Source

EventPublishResult

Signature

declare const EventPublishResult: EventPublishResult<Id, Version, Payload>;

Source

createEventClient

Creates a Promise publisher from a validated event contract.

Throws

TypeError for malformed client configuration, or a provider profile error.

Example

createEventClient({
  ownerId: "orders.create",
  eventId: "orders.created",
  version: 1,
  source: provider,
});

Signature

declare const createEventClient: <
  const Id extends string,
  const Version extends number,
  const PayloadSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: EventClientOptions<Id, Version, PayloadSchema>,
) => EventClient<InferInput<PayloadSchema>, Id, Version, InferOutput<PayloadSchema>>;

Source

createEventClientEffect

Creates an Effect-backed event publisher with typed configuration failures.

Example

Effect.runSync(
  createEventClientEffect({
    ownerId: "orders.create",
    eventId: "orders.created",
    version: 1,
    source: provider,
  }),
);

Signature

declare const createEventClientEffect: <
  const Id extends string,
  const Version extends number,
  const PayloadSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: EventClientOptions<Id, Version, PayloadSchema>,
) => Effect.Effect<
  EventClient<InferInput<PayloadSchema>, Id, Version, InferOutput<PayloadSchema>>,
  EventClientValidationError | EventProfileError | EventProviderError
>;

Source

client.types.ts

EventAttributeValue

Signature

declare const EventAttributeValue: EventAttributeValue;

Source

EventClient (interface)

Promise compatibility interface exposed to application handlers.

Example

await client.publish({ orderId: "one" });

Signature

export interface EventClient<
  Input = unknown,
  Id extends string = string,
  Version extends number = number,
  Payload = Input,
> {
  /** Publishes a payload and returns the accepted envelope.
   * @param payload - Event payload to decode.
   * @param options - Optional key and attributes.
   * @returns A Promise of the accepted envelope or a rejected domain error.
   * @example await client.publish(payload, { key: "order-1" })
   */
  readonly publish: (
    payload: Input,
    options?: EventPublishOptions,
  ) => Promise<EventPublishResult<Id, Version, Payload>>;
}

Source

EventClientOptions (interface)

Dependencies and policy for a generated event publisher. Provider selection occurs once when the client is created.

Example

const options: EventClientOptions = {
  ownerId: "orders.create",
  eventId: "orders.created",
  version: 1,
  source: provider,
};

Signature

export interface EventClientOptions<
  Id extends string = string,
  Version extends number = number,
  PayloadSchema extends StandardSchemaV1 = StandardSchemaV1,
> {
  readonly ownerId: string;
  readonly eventId: Id;
  readonly version: Version;
  readonly source: unknown;
  readonly payloadSchema?: PayloadSchema;
  readonly profile?: string;
  readonly resolveProfile?: (profile: string) => unknown;
  readonly bridge?: EventInvocationBridge;
  readonly signal?: () => AbortSignal;
  readonly deadline?: () => number | undefined;
  readonly correlationId?: string | (() => string | undefined);
  readonly now?: () => Date;
  readonly declared?: boolean;
  readonly onDeclaredEdge?: (edge: EventDeclaredEdge) => void;
  readonly onObservedEdge?: (edge: EventObservedEdge) => void;
}

Source

EventDeclaredEdge (interface)

Static graph edge for a declared publication dependency.

Example

const edge: EventDeclaredEdge = {
  kind: "publishes-event",
  from: "orders.create",
  to: "orders.created",
};

Signature

export interface EventDeclaredEdge {
  readonly kind: "publishes-event";
  readonly from: string;
  readonly to: string;
}

Source

EventInvocationBridge (interface)

Optional invocation bridge that owns a publication span.

Example

await bridge.run(() => provider.publish(payload, {}, context));

Signature

export interface EventInvocationBridge {
  /** Runs publication within the invocation context.
   * @param operation - Publication callback.
   * @param options - Producer span metadata.
   * @returns The operation result or rejection.
   * @example await bridge.run(() => Promise.resolve(1))
   */
  readonly run: <A>(
    operation: () => MaybePromise<A>,
    options?: EventInvocationBridgeOptions,
  ) => Promise<A>;
}

Source

EventInvocationBridgeOptions (interface)

Trace bridge metadata for a producer operation.

Example

const name = options.name;

Signature

export interface EventInvocationBridgeOptions {
  readonly name?: string;
  readonly attributes?: Readonly<Record<string, unknown>>;
  readonly signal?: AbortSignal;
  readonly kind?: "producer";
  readonly input?: unknown;
}

Source

EventObservedEdge (interface)

Runtime graph edge for an attempted publication.

Example

const edge: EventObservedEdge = {
  relationship: "publishes-event",
  from: "orders.create",
  to: "orders.created",
};

Signature

export interface EventObservedEdge {
  readonly relationship: "publishes-event";
  readonly from: string;
  readonly to: string;
}

Source

EventOperationContext (interface)

Context passed to the selected event provider for one publication. The signal remains valid until the publication settles.

Example

const id = context.eventId;

Signature

export interface EventOperationContext {
  readonly operation: "publish";
  readonly eventId: string;
  readonly version: number;
  readonly signal: AbortSignal;
  readonly profile: string;
  readonly deadlineMs?: number;
  readonly propagation?: TracePropagation;
}

Source

EventProvider (interface)

Provider interface selected from a profile for publication.

Example

const provider: EventProvider = {
  publish: async () => ({ accepted: true, instanceId: "event-1" }),
};

Signature

export interface EventProvider {
  /** Publishes one validated payload.
   * @param payload - Decoded event payload.
   * @param options - Validated publish options.
   * @param context - Trace and cancellation context.
   * @returns Provider acceptance and metadata, or a rejected Promise.
   * @example await provider.publish(payload, {}, context)
   */
  readonly publish: (
    payload: unknown,
    options: EventPublishOptions,
    context: EventOperationContext,
  ) => MaybePromise<EventProviderResult>;
}

Source

EventProviderResult (type alias)

Provider acknowledgement and optional envelope metadata.

Example

const result: EventProviderResult = { accepted: true, instanceId: "event-1" };

Signature

type EventProviderResult<
  Id extends string = string,
  Version extends number = number,
  Payload = unknown,
> = Pick<EventPublishResult<Id, Version, Payload>, "instanceId" | "accepted"> &
  Partial<Omit<EventPublishResult<Id, Version, Payload>, "instanceId" | "accepted">>;

Source

EventPublishOptions

Signature

declare const EventPublishOptions: EventPublishOptions;

Source

EventPublishResult

Signature

declare const EventPublishResult: EventPublishResult<Id, Version, Payload>;

Source

InferInput

Signature

declare const InferInput: InferInput<S>;

Source

InferOutput

Signature

declare const InferOutput: InferOutput<S>;

Source

StandardSchemaV1

Signature

declare const StandardSchemaV1: StandardSchemaV1<TInput, TOutput>;

Source

define-event-function.ts

defineEventFunction

Defines an independent event-only consumer with inferred input and void success. Event IDs are supplied by the application’s generated EventRegistry.

Throws

TypeError for malformed options.

Example

import { defineEvent, defineEventFunction } from "@relkit/app/events";
import { z } from "@relkit/app/schema";

const orderCreated = defineEvent({
  id: "orders.created",
  input: z.object({ orderId: z.string() }),
});

// The application normally generates this declaration with `relkit check`.
declare global {
  namespace Relkit {
    interface EventRegistry {
      "orders.created": typeof orderCreated;
    }
  }
}

const receipt = defineEventFunction({
  id: "receipt.send",
  event: "orders.created",
  handler: async () => {},
});

Signature

declare const defineEventFunction: <
  const Id extends string,
  const Event extends EventName,
  const Publishes extends readonly EventName[] = readonly [],
  const Dependencies extends FunctionDependencies = {},
  const Options extends EventFunctionCallOptions<Id, Event, Publishes, Dependencies> =
    EventFunctionCallOptions<Id, Event, Publishes, Dependencies>,
>(
  options: EventFunctionCallOptions<Id, Event, Publishes, Dependencies> &
    Options &
    EventFunctionValidation<NoInfer<Options>>,
) => EventFunctionDescriptor<Id, Event, Publishes, Dependencies, ErrorListOf<Options>>;

Source

Since v0.1.0

defineEventFunctionEffect

Defines an event-only function in Effect.

Example

Effect.runSync(
  defineEventFunctionEffect({ id: "notify", event: "orders.created", handler: () => {} }),
);

Signature

declare const defineEventFunctionEffect: <
  const Id extends string,
  const Event extends EventName,
  const Publishes extends readonly EventName[] = readonly [],
  const Dependencies extends FunctionDependencies = {},
  const Options extends EventFunctionCallOptions<Id, Event, Publishes, Dependencies> =
    EventFunctionCallOptions<Id, Event, Publishes, Dependencies>,
>(
  options: EventFunctionCallOptions<Id, Event, Publishes, Dependencies> &
    Options &
    EventFunctionValidation<NoInfer<Options>>,
) => Effect.Effect<
  EventFunctionDescriptor<Id, Event, Publishes, Dependencies, ErrorListOf<Options>>,
  EventDefinitionError
>;

Source

isEventFunctionDescriptor

Checks an event-only function descriptor at a synchronous boundary.

Example

isEventFunctionDescriptor(candidate);

Signature

declare const isEventFunctionDescriptor: (value: unknown) => value is EventFunctionDescriptorAny;

Source

isEventFunctionDescriptorEffect

Checks an unknown value for a valid event-only function descriptor.

Example

Effect.runSync(isEventFunctionDescriptorEffect(candidate));

Signature

declare const isEventFunctionDescriptorEffect: (
  value: unknown,
) => Effect.Effect<boolean, never, never>;

Source

define-event-function.types.ts

ErrorDescriptorAny

Signature

declare const ErrorDescriptorAny: ErrorDescriptorAny;

Source

ErrorListOf (type alias)

Error declarations inferred from a function definition.

Example

type Errors = ErrorListOf<typeof options>;

Signature

type ErrorListOf<Options> = Options extends {
  readonly errors: infer Errors extends readonly ErrorDescriptorAny[];
}
  ? Errors
  : readonly [];

Source

EventFunctionCallOptions (type alias)

Handler-aware options for an event function definition.

Example

type Options = EventFunctionCallOptions<"receipt.send", "orders.created", [], {}>;

Signature

type EventFunctionCallOptions<
  Id extends string,
  Event extends EventName,
  Publishes extends readonly EventName[],
  Dependencies extends FunctionDependencies,
> = Omit<
  DefineEventFunctionOptions<Id, Event, Publishes, Dependencies, readonly ErrorDescriptorAny[]>,
  "handler"
> & {
  readonly handler: (
    input: EventInputByName<Event>,
    context: EventFunctionContext<Event, Publishes, Dependencies>,
  ) => unknown;
};

Source

EventFunctionDescriptor

Signature

declare const EventFunctionDescriptor: EventFunctionDescriptor<
  Id,
  Event,
  Publishes,
  Dependencies,
  Errors
>;

Source

EventFunctionDescriptorAny

Signature

declare const EventFunctionDescriptorAny: EventFunctionDescriptorAny;

Source

EventFunctionValidation (type alias)

Validates a handler’s result against declared errors and void success.

Example

type Validation = EventFunctionValidation<typeof options>;

Signature

type EventFunctionValidation<Options extends { readonly handler: (...args: never[]) => unknown }> =
  FunctionHandlerValidation<Awaited<ReturnType<Options["handler"]>>, void, ErrorListOf<Options>>;

Source

EventName

Signature

declare const EventName: never;

Source

FunctionDependencies

Signature

declare const FunctionDependencies: FunctionDependencies;

Source

define-event.ts

defineEvent

Defines a versioned event contract used by publishers and event functions.

Throws

TypeError when the contract is malformed.

Example

import { defineEvent } from "@relkit/app/events";
import { z } from "@relkit/app/schema";

const created = defineEvent({ id: "orders.created", input: z.object({ orderId: z.string() }) });
void created;

Signature

declare const defineEvent: <
  const Id extends string,
  const Version extends number = 1,
  const InputSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: DefineEventOptions<Id, Version, InputSchema>,
) => EventDescriptor<Id, Version, InferOutput<InputSchema>, InputSchema>;

Source

Since v0.1.0

DefineEventOptions

Signature

declare const DefineEventOptions: DefineEventOptions<Id, Version, InputSchema>;

Source

EventDescriptor

Signature

declare const EventDescriptor: EventDescriptor<Id, Version, Input, InputSchema>;

Source

EventDescriptorAny

Signature

declare const EventDescriptorAny: EventDescriptorAny;

Source

EventEnvelope

Signature

declare const EventEnvelope: EventEnvelope<Id, Version, Payload>;

Source

EventEnvelopeFor

Signature

declare const EventEnvelopeFor: EventEnvelopeFor<E>;

Source

UnknownEventEnvelope

Signature

declare const UnknownEventEnvelope: UnknownEventEnvelope;

Source

assertEventDescriptor

Requires a valid event descriptor at a synchronous boundary.

Throws

TypeError when the candidate is invalid.

Example

assertEventDescriptor(value);

Signature

declare const assertEventDescriptor: (value: unknown) => asserts value is EventDescriptorAny;

Source

assertEventDescriptorEffect

Requires a valid event descriptor in an Effect workflow.

Example

Effect.runSync(assertEventDescriptorEffect(candidate));

Signature

declare const assertEventDescriptorEffect: (
  value: unknown,
) => Effect.Effect<EventDescriptorAny, EventDefinitionError, never>;

Source

defineEventEffect

Defines an event contract in Effect with typed validation failure.

Example

Effect.runSync(defineEventEffect({ id: "orders.created", input: z.object({}) }));

Signature

declare const defineEventEffect: <
  const Id extends string,
  const Version extends number = 1,
  const InputSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: DefineEventOptions<Id, Version, InputSchema>,
) => Effect.Effect<
  EventDescriptor<Id, Version, InferOutput<InputSchema>, InputSchema>,
  EventDefinitionError
>;

Source

isEventDescriptor

Checks a candidate against the event descriptor contract.

Example

isEventDescriptor(value);

Signature

declare const isEventDescriptor: (value: unknown) => value is EventDescriptorAny;

Source

isEventDescriptorEffect

Checks whether an unknown value is a valid event descriptor.

Example

Effect.runSync(isEventDescriptorEffect(candidate));

Signature

declare const isEventDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

define-event.types.ts

DefineEventOptions (interface)

Input accepted by the event descriptor factory.

Example

const options: DefineEventOptions<"orders.created", 1, typeof schema> = {
  id: "orders.created",
  input: schema,
};

Signature

export interface DefineEventOptions<
  Id extends string,
  Version extends number,
  InputSchema extends StandardSchemaV1,
> extends DescriptorMetadata {
  readonly id: Id;
  readonly version?: Version;
  readonly input: InputSchema;
  readonly profile?: string;
  readonly sensitiveFields?: readonly string[];
  readonly handler?: never;
  readonly output?: never;
}

Source

EventDescriptor (interface)

Immutable, versioned event contract with no handler or output.

Example

const created: EventDescriptor<"orders.created", 1, { orderId: string }> = defineEvent(options);

Signature

export interface EventDescriptor<
  Id extends string,
  Version extends number,
  Input,
  InputSchema extends StandardSchemaV1 = StandardSchemaV1,
>
  extends DescriptorBase<"event", Id>, EventRef<Id, InputSchema> {
  readonly version: Version;
  readonly input: InputSchema;
  readonly profile?: string;
  readonly sensitiveFields?: readonly string[];
  readonly handler?: never;
  readonly output?: never;
  readonly __input?: Input;
}

Source

EventDescriptorAny (type alias)

Event descriptor with erased contract parameters.

Example

const registry: EventDescriptorAny[] = [created];

Signature

type EventDescriptorAny = EventDescriptor<string, number, unknown, StandardSchemaV1>;

Source

EventEnvelope (type alias)

Published event data without the provider acceptance flag.

Example

type Created = EventEnvelope<"orders.created", 1, { orderId: string }>;

Signature

type EventEnvelope<
  Id extends string = string,
  Version extends number = number,
  Payload = unknown,
> = Omit<EventPublishResult<Id, Version, Payload>, "accepted">;

Source

EventEnvelopeFor (type alias)

Resolves the envelope for a specific event descriptor.

Example

type CreatedEnvelope = EventEnvelopeFor<typeof created>;

Signature

type EventEnvelopeFor<E> =
  E extends EventDescriptor<infer Id, infer Version, infer Input, StandardSchemaV1>
    ? EventEnvelope<Id, Version, Input>
    : UnknownEventEnvelope;

Source

InferOutput

Signature

declare const InferOutput: InferOutput<S>;

Source

StandardSchemaV1

Signature

declare const StandardSchemaV1: StandardSchemaV1<TInput, TOutput>;

Source

UnknownEventEnvelope (type alias)

Event data when its contract is not known statically.

Example

const envelope: UnknownEventEnvelope = received;

Signature

type UnknownEventEnvelope = EventEnvelope<string, number, unknown>;

Source

effect.ts

EventBindingError

Signature

declare const EventBindingError: typeof EventBindingError;

Source

EventDefinitionError

Signature

declare const EventDefinitionError: typeof EventDefinitionError;

Source

EventIdentity

Signature

declare const EventIdentity: typeof EventIdentity;

Source

EventIdentityLive

Signature

declare const EventIdentityLive: Layer<EventIdentity, never, never>;

Source

EventIdentityService

Signature

declare const EventIdentityService: EventIdentityService;

Source

EventOperation

Signature

declare const EventOperation: EventOperation;

Source

EventPayloadValidationFailure

Signature

declare const EventPayloadValidationFailure: typeof EventPayloadValidationFailure;

Source

EventPublishFailure

Signature

declare const EventPublishFailure: EventPublishFailure;

Source

EventPublishSetup

Signature

declare const EventPublishSetup: EventPublishSetup<Id, Version, PayloadSchema>;

Source

EventPublisher

Signature

declare const EventPublisher: typeof EventPublisher;

Source

EventPublisherService

Signature

declare const EventPublisherService: EventPublisherService;

Source

EventTelemetry

Signature

declare const EventTelemetry: typeof EventTelemetry;

Source

EventTelemetryLive

Signature

declare const EventTelemetryLive: Layer<EventTelemetry, never, never>;

Source

EventTelemetryService

Signature

declare const EventTelemetryService: EventTelemetryService;

Source

EventWorkFailed

Signature

declare const EventWorkFailed: typeof EventWorkFailed;

Source

assertEventDescriptorEffect

Signature

declare const assertEventDescriptorEffect: (
  value: unknown,
) => Effect<EventDescriptorAny, EventDefinitionError, never>;

Source

assertOptionalTextEffect

Signature

declare const assertOptionalTextEffect: (
  value: unknown,
  name: string,
) => Effect<void, EventClientValidationError, never>;

Source

assertVersionEffect

Signature

declare const assertVersionEffect: (
  value: unknown,
) => Effect<number, EventClientValidationError, never>;

Source

bindFunctionEventsEffect

Signature

declare const bindFunctionEventsEffect: <T extends FunctionWithEvents>(
  descriptor: T,
  consumed: EventDescriptorAny | undefined,
  published: readonly EventDescriptorAny[],
) => Effect<T, EventBindingError>;

Source

createEventClientEffect

Signature

declare const createEventClientEffect: <
  const Id extends string,
  const Version extends number,
  const PayloadSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: EventClientOptions<Id, Version, PayloadSchema>,
) => Effect<
  EventClient<InferInput<PayloadSchema>, Id, Version, InferOutput<PayloadSchema>>,
  EventClientValidationError | EventProfileError | EventProviderError
>;

Source

defineEventEffect

Signature

declare const defineEventEffect: <
  const Id extends string,
  const Version extends number = 1,
  const InputSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: DefineEventOptions<Id, Version, InputSchema>,
) => Effect<
  EventDescriptor<Id, Version, InferOutput<InputSchema>, InputSchema>,
  EventDefinitionError
>;

Source

defineEventFunctionEffect

Signature