@dotpress/events 0.0.0-stage → 2.0.0-alpha.0

package/dist/transport-BtNR1ucF.d.ts

@@ -0,0 +1,273 @@
+import { z } from 'zod';
+
+/**
+ * Logger of the bus and the workers. A Dotpress or Pino logger fits;
+ * `eventsPlugin` uses the logger of the request.
+ */
+interface EventsLogger {
+    debug?(data: object, message: string): void;
+    info(data: object, message: string): void;
+    warn(data: object, message: string): void;
+    error(data: object, message: string): void;
+}
+
+/**
+ * Names of the transports, besides `default`, declared by module
+ * augmentation so that typos are type errors:
+ *
+ * ```ts
+ * declare module '@dotpress/events' {
+ *   interface EventTransports {
+ *     edge: true
+ *   }
+ * }
+ * ```
+ */
+interface EventTransports {
+}
+/** Name of a transport: `default`, or a name of `EventTransports`. */
+type TransportName = 'default' | Extract<keyof EventTransports, string>;
+/** Event created by `defineEvent()`. */
+interface EventDefinition<S extends z.ZodType = z.ZodType> {
+    readonly name: string;
+    readonly schema: S;
+    /** Transport of its listeners; undefined for `default`. */
+    readonly transport: TransportName | undefined;
+}
+/** Payload accepted by `emit()` for an event. */
+type EventInput<E> = E extends EventDefinition<infer S> ? z.input<S> : never;
+/** Payload received by the listeners of an event. */
+type EventPayload<E> = E extends EventDefinition<infer S> ? z.output<S> : never;
+/** Context of a listener call. */
+interface ListenerContext<TPayload = unknown> {
+    /** Payload, validated by the schema of the event. */
+    readonly payload: TPayload;
+    /** Name of the event. */
+    readonly event: string;
+    /** Name of the listener. */
+    readonly listener: string;
+    /**
+     * Identifier of the message, the same for every attempt and when the
+     * emission is repeated: use it to ignore duplicates.
+     */
+    readonly id: string;
+    /** Identifier of the emission, shared by the messages of its listeners. */
+    readonly emissionId: string;
+    /** Attempt number, from 1. */
+    readonly attempt: number;
+    readonly emittedAt: Date;
+    /** Metadata of the emission (request ID…). */
+    readonly metadata: Readonly<Record<string, string>>;
+    readonly logger: EventsLogger;
+}
+/** Function of a listener. Throw to have the message retried. */
+type ListenerHandler<TPayload = unknown> = (context: ListenerContext<TPayload>) => unknown;
+/** Module loaded by `load()`: the handler is its default export. */
+interface ListenerModule<TPayload = unknown> {
+    default: ListenerHandler<TPayload>;
+}
+/** Options of `defineListener()`. */
+type ListenerOptions<TPayload> = {
+    /**
+     * Unique name: letters, digits, `.`, `_`, `:` and `-`. It identifies the
+     * listener in messages: renaming it orphans messages still in queues.
+     */
+    name: string;
+    /** Transport of this listener; defaults to the one of the event. */
+    transport?: TransportName | undefined;
+} & ({
+    handle: ListenerHandler<TPayload>;
+    load?: never;
+} | {
+    /**
+     * Loads the module of the handler on first use, so that the code
+     * emitting events does not load the code of the listeners:
+     * `load: () => import('./listeners/send-welcome-mail.js')`.
+     */
+    load: () => Promise<ListenerModule<TPayload>>;
+    handle?: never;
+});
+/** Listener created by `defineListener()`. */
+interface ListenerDefinition<S extends z.ZodType = z.ZodType> {
+    readonly name: string;
+    readonly event: EventDefinition<S>;
+    /** Transport of this listener, if it differs from the one of its event. */
+    readonly transport: TransportName | undefined;
+}
+/**
+ * Defines an event: a fact that listeners react to, with the schema of its
+ * payload.
+ *
+ * ```ts
+ * export const userCreated = defineEvent({
+ *   name: 'user.created',
+ *   schema: z.object({ userId: z.string() }),
+ * })
+ * ```
+ */
+declare const defineEvent: <S extends z.ZodType>(options: {
+    /** Unique name: letters, digits, `.`, `_`, `:` and `-`. */
+    name: string;
+    /**
+     * Schema of the payload. Payloads travel as JSON: describe JSON values
+     * (dates as strings, or coerced on the way in).
+     */
+    schema: S;
+    /** Transport of the listeners. Defaults to `default`. */
+    transport?: TransportName | undefined;
+}) => EventDefinition<S>;
+/**
+ * Defines a listener of an event. Its handler runs in a worker, once per
+ * emission, and is retried when it throws.
+ *
+ * ```ts
+ * export const sendWelcomeMail = defineListener(userCreated, {
+ *   name: 'send-welcome-mail',
+ *   load: () => import('./listeners/send-welcome-mail.js'),
+ * })
+ * ```
+ */
+declare const defineListener: <S extends z.ZodType>(event: EventDefinition<S>, options: ListenerOptions<z.output<S>>) => ListenerDefinition<S>;
+
+/**
+ * Message sent to a transport: one per listener of an emission. It travels
+ * as JSON.
+ */
+interface Envelope {
+    /** Version of the format. */
+    readonly v: 1;
+    /** Identifier of the message, stable across retries and emissions. */
+    readonly id: string;
+    /** Identifier of the emission, shared by its messages. */
+    readonly emissionId: string;
+    readonly event: string;
+    readonly listener: string;
+    /** Payload, as JSON. */
+    readonly payload: unknown;
+    /** ISO date of the emission. */
+    readonly emittedAt: string;
+    readonly metadata: Readonly<Record<string, string>>;
+}
+/**
+ * Envelope of a received message (an object, or its JSON), or a reason
+ * why it is not one.
+ */
+declare const parseEnvelope: (message: unknown) => {
+    envelope: Envelope;
+} | {
+    problem: string;
+};
+
+/** Why a message can never be handled: retrying would not help. */
+type DeadReason = 
+/** Not an envelope, or an envelope of another version. */
+'invalid-envelope'
+/** No listener of this name in this worker (not deployed here?). */
+ | 'unknown-listener'
+/** The payload does not match the schema of the event. */
+ | 'invalid-payload';
+/** Result of `worker.handle()`, translated by each transport. */
+type HandleResult = {
+    readonly status: 'success';
+}
+/** The listener failed: retry the message. */
+ | {
+    readonly status: 'retry';
+    readonly error: unknown;
+}
+/** The message can never be handled: do not retry it. */
+ | {
+    readonly status: 'dead';
+    readonly reason: DeadReason;
+    readonly error: unknown;
+};
+/** Details of a failure, for `onFailure`. */
+interface FailureInfo {
+    /** Envelope of the message; undefined when it is not an envelope. */
+    readonly envelope: Envelope | undefined;
+    readonly reason: 'listener-error' | DeadReason;
+    readonly attempt: number;
+    /**
+     * Whether the message will not be retried: a dead message, or the last
+     * attempt (with `maxAttempts`).
+     */
+    readonly final: boolean;
+}
+/** Called for every failure: logs, alerts… */
+type FailureHook = (error: unknown, info: FailureInfo) => void | Promise<void>;
+/** Options of `createWorker()`. */
+interface WorkerOptions {
+    /** Listeners run by this worker. */
+    listeners: readonly ListenerDefinition[];
+    logger?: EventsLogger | undefined;
+    /** Called for every failure. Its own errors are logged and ignored. */
+    onFailure?: FailureHook | undefined;
+    /**
+     * Attempts before the transport gives up (its retry limit, like the
+     * `maxReceiveCount` of an SQS queue), to report the last one as `final`.
+     */
+    maxAttempts?: number | undefined;
+}
+/** Runs the listeners of received messages. */
+interface Worker {
+    /** Names of its listeners. */
+    readonly listeners: readonly string[];
+    /**
+     * Handles a received message (an envelope, or its JSON). Never throws:
+     * the result tells the transport what to do with the message.
+     */
+    handle(message: unknown, options?: {
+        attempt?: number | undefined;
+    }): Promise<HandleResult>;
+}
+/**
+ * Creates a worker: it runs the listeners of the messages it receives from
+ * a transport (Lambda handler, queue consumer, `startWorker()`…).
+ *
+ * ```ts
+ * const worker = createWorker({ listeners: [sendWelcomeMail, geocodeUser] })
+ * export const handler = createSqsHandler(worker)
+ * ```
+ */
+declare const createWorker: (options: WorkerOptions) => Worker;
+
+/** Options of `transport.send()`. */
+interface SendOptions {
+    /** Delay before delivery, in seconds. */
+    readonly delay: number | undefined;
+}
+/**
+ * Sends messages to a queue. Implemented by each transport (SQS, BullMQ,
+ * Cloudflare Queues…); throw a `PartialSendError` when only some messages
+ * failed.
+ */
+interface Transport {
+    /** Kind of transport, for logs: `sqs`, `memory`… */
+    readonly kind: string;
+    send(envelopes: readonly Envelope[], options: SendOptions): Promise<void>;
+    /**
+     * In-process transports only (`sync`, `memory`): receives the worker
+     * that runs the listeners routed to this transport.
+     */
+    bind?(worker: Worker): void;
+    /** Attempts of an in-process transport, for `FailureInfo.final`. */
+    readonly maxAttempts?: number;
+}
+/** Options of `source.consume()`. */
+interface ConsumeOptions {
+    /** Aborted to stop: finish the messages in progress, then resolve. */
+    readonly signal: AbortSignal;
+    readonly logger: EventsLogger;
+}
+/**
+ * Reads messages from a queue and hands them to a worker, until stopped:
+ * the long-running side of a transport (SQS polling, BullMQ worker…).
+ */
+interface Source {
+    /** Kind of source, for logs. */
+    readonly kind: string;
+    consume(worker: Worker, options: ConsumeOptions): Promise<void>;
+}
+
+export { createWorker as n, defineEvent as o, defineListener as p, parseEnvelope as q };
+export type { ConsumeOptions as C, DeadReason as D, EventsLogger as E, FailureHook as F, HandleResult as H, ListenerContext as L, Source as S, Transport as T, Worker as W, Envelope as a, EventDefinition as b, EventInput as c, EventPayload as d, EventTransports as e, FailureInfo as f, ListenerDefinition as g, ListenerHandler as h, ListenerModule as i, ListenerOptions as j, SendOptions as k, TransportName as l, WorkerOptions as m };

package/package.json

@@ -1,6 +1,142 @@
 {
   "name": "@dotpress/events",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "2.0.0-alpha.0",
+  "description": "Typed events with listeners, delivered by interchangeable transports (SQS, Redis, Cloudflare Queues, Postgres, Pub/Sub, Service Bus)",
+  "author": "Renaud Guyon",
+  "license": "MIT",
+  "homepage": "https://dotpress.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dotpressjs/dotpress.git",
+    "directory": "packages/events"
+  },
+  "bugs": {
+    "url": "https://github.com/dotpressjs/dotpress/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "dotpress-events": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    },
+    "./aws-sqs": {
+      "types": "./dist/aws-sqs.d.ts",
+      "default": "./dist/aws-sqs.js"
+    },
+    "./bullmq": {
+      "types": "./dist/bullmq.d.ts",
+      "default": "./dist/bullmq.js"
+    },
+    "./cloudflare-queues": {
+      "types": "./dist/cloudflare-queues.d.ts",
+      "default": "./dist/cloudflare-queues.js"
+    },
+    "./pg-boss": {
+      "types": "./dist/pg-boss.d.ts",
+      "default": "./dist/pg-boss.js"
+    },
+    "./google-pubsub": {
+      "types": "./dist/google-pubsub.d.ts",
+      "default": "./dist/google-pubsub.js"
+    },
+    "./azure-service-bus": {
+      "types": "./dist/azure-service-bus.d.ts",
+      "default": "./dist/azure-service-bus.js"
+    }
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-sqs": "^3.572.0",
+    "@azure/service-bus": "^7.9.0",
+    "@dotpress/core": "^2.0.0-alpha.0",
+    "@google-cloud/pubsub": "^6.0.0",
+    "bullmq": "^6.0.0",
+    "google-auth-library": "^10.0.0 || ^11.0.0",
+    "jose": "^6.0.0",
+    "pg-boss": "^12.21.0",
+    "zod": "^4.6.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-sqs": {
+      "optional": true
+    },
+    "@azure/service-bus": {
+      "optional": true
+    },
+    "@dotpress/core": {
+      "optional": true
+    },
+    "@google-cloud/pubsub": {
+      "optional": true
+    },
+    "bullmq": {
+      "optional": true
+    },
+    "google-auth-library": {
+      "optional": true
+    },
+    "jose": {
+      "optional": true
+    },
+    "pg-boss": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@aws-sdk/client-sqs": "^3.1164.0",
+    "@azure/service-bus": "~7.10.0",
+    "@dotpress/core": "2.0.0-alpha.0",
+    "@dotpress/testing": "2.0.0-alpha.0",
+    "@google-cloud/pubsub": "~6.3.2",
+    "bullmq": "^6.7.2",
+    "google-auth-library": "~11.3.4",
+    "ioredis": "^5.11.1",
+    "jose": "~6.2.15",
+    "pg-boss": "~12.38.1",
+    "zod": "^4.6.7"
+  },
+  "keywords": [
+    "dotpress",
+    "events",
+    "listeners",
+    "queue",
+    "worker",
+    "plugin",
+    "typescript",
+    "sqs",
+    "aws",
+    "lambda",
+    "bullmq",
+    "redis",
+    "cloudflare",
+    "workers",
+    "postgres",
+    "pg-boss",
+    "pubsub",
+    "gcp",
+    "azure",
+    "service-bus"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.cli.json && tsc --noEmit -p tsconfig.test.json",
+    "lint": "eslint src test",
+    "test": "vitest run",
+    "test:watch": "vitest watch"
+  }
 }