@elysiumjs/runtime-workers 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,142 @@
+# @elysiumjs/runtime-workers
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [[`651a755`](https://github.com/na2axl/elysiumjs/commit/651a7557173ce2c6155bcfa8d90cf388ac419821)]:
+  - @elysiumjs/core@0.12.0
+
+## 0.1.0
+
+### Minor Changes
+
+- [#8](https://github.com/na2axl/elysiumjs/pull/8) [`6bc48fe`](https://github.com/na2axl/elysiumjs/commit/6bc48febd51f7090c582e73f349eaeff7261241c) Thanks [@na2axl](https://github.com/na2axl)! - `Application.build()` builds the root Elysia app without listening, for hosts that own the server (Cloudflare Workers) and for ahead-of-time compilation with `elysia/plugin/aot`. Modules are registered but boot on the first request (once, shared by concurrent requests), so building runs no `onInit` work. A boot failure fails the requests.
+
+  HTTP and websocket controllers in the server scope, and middlewares, are now built on their first request instead of when the app is built. `serve` still boots every module before listening.
+
+  `@elysiumjs/runtime-workers` gets a `check:aot` script, run in CI: it compiles a sample app with the AOT plugin for workerd, checks that the bundle holds no `new Function` or `eval`, and serves a validated route and the OpenAPI document under Node.js with code generation from strings disallowed.
+
+- [#5](https://github.com/na2axl/elysiumjs/pull/5) [`557a3ca`](https://github.com/na2axl/elysiumjs/commit/557a3cab7af8053a8bab9944e492e5022d91aa82) Thanks [@na2axl](https://github.com/na2axl)! - Core runs outside Bun. Environment variables, timers, the HTTP server, process exit and shutdown signals now come from a `Runtime` set with the new `runtime` option of `@Application.register()` or with `Runtime.use()`. Runtimes ship as packages, each exporting `runtime`: `@elysiumjs/runtime-bun`, `@elysiumjs/runtime-node` and `@elysiumjs/runtime-workers` (which also exports `createRuntime({ env })`).
+
+  Breaking: an application needs a runtime (add `runtime` from `@elysiumjs/runtime-bun`), and `Redis` and `RedisModule` moved from core to the new `@elysiumjs/redis` package, which also accepts a `client` factory for runtimes without `Bun.RedisClient`.
+
+  Console colours are plain ANSI codes instead of `Bun.color`, `node:readline` is loaded only when a prompt runs, and core's dist is built for the `node` target so `node:` imports keep their prefix. `check:runtime` scripts in core and runtime-workers fail when their bundles touch the `Bun` global.
+
+  `create-elysium` gets a runtime step: it installs the chosen runtime package and sets it in the generated app. Bun is selectable today; Node.js and Cloudflare Workers are listed as coming later.
+
+- [#20](https://github.com/na2axl/elysiumjs/pull/20) [`1738567`](https://github.com/na2axl/elysiumjs/commit/17385674c14991f0ddb27eb6ee967afbcebcc307) Thanks [@na2axl](https://github.com/na2axl)! - Scheduled fan-out, dead letters and one consumer per queue.
+
+  - `@Scheduler.job(cron, { args })` dispatches a job on a cron with fixed arguments.
+  - A class that extends `Scheduler` and is marked with `@Scheduler.register({ cron, job })` dispatches one job per case its `fanOut(tick)` returns, with arguments typed against the job and a dispatch id made of the scheduler, the case key and the tick. Schedulers are services, so they inject what they read.
+  - `ScheduleRunner` runs the schedules on Bun and Node.js (the `heracles:schedule` command), and `Scheduler.jobsFor()` / `Scheduler.dispatch()` serve the cron triggers of Workers.
+  - `@Once()` of `@elysiumjs/moirai/heracles` runs a job once per dispatch id, in a unit of work with an inbox record.
+  - `HeraclesWorkersModule.with({ deadLetterQueue, onDead })` keeps the jobs that failed their last retry: sent to a dead letter queue with their failure, and handed to a hook.
+  - Cron triggers dispatch at the trigger's time.
+  - A named queue of a Worker has one consumer: two throw `DuplicateQueueConsumerError` when the Worker is created.
+
+- [#13](https://github.com/na2axl/elysiumjs/pull/13) [`1ea417e`](https://github.com/na2axl/elysiumjs/commit/1ea417e3583250bc2f975d795f398b7ff736115d) Thanks [@na2axl](https://github.com/na2axl)! - Hardening of the runtimes, the container and the CLI, checked by a conformance suite that runs on Bun, Node.js and workerd.
+
+  Breaking changes:
+
+  - `Runtime` gains the required `argv()`, `write(stream, text)` and `terminal()` members: core reaches the host's arguments, output streams and terminal only through the runtime. Custom runtimes must implement them.
+  - The third parameter of `InteractsWithConsole.write` is now `'stdout' | 'stderr'`.
+  - The WebSocket options are narrowed to `idleTimeout`, `maxPayloadLength` and `perMessageDeflate`, and the `bun` WebSocket types are replaced by `ElysiumWebSocket`.
+  - Redis connections are `RedisConnection`s, a port any Redis client can implement, instead of `Bun.RedisClient`.
+  - `styx create @scope/name` creates the project in `name/`, and refuses project and module names with upper-case letters.
+  - Queue handlers no longer reject the batch: after the handlers ran, each message is acked or retried on its own. `@Workers.queue(name, { each: true })` receives one message at a time, so a failure retries only that message.
+
+  Fixes:
+
+  - Request-scoped services are destroyed when the request ends, also on failure, and an async `onInit` is awaited. A second dispose of a request scope waits for the one in progress, so a Worker's `waitUntil` covers an async `onDestroy`.
+  - A failed module or service `onInit` no longer breaks later requests: the boot is retried, and the module's event listeners are unwired.
+  - `@elysiumjs/runtime-node` serves through `node:http`, keeping the Host header authoritative.
+  - `styx create` validates names before creating files, ships `.gitignore`, declares the dependencies of created projects and imports their default controllers.
+
+- [#14](https://github.com/na2axl/elysiumjs/pull/14) [`0956186`](https://github.com/na2axl/elysiumjs/commit/0956186db0ca5a83c0a6636aeb2a4c81a0033de4) Thanks [@na2axl](https://github.com/na2axl)! - The request pipeline: problem details, exception filters, interceptors, typed configuration, HTTP security options and an HTTP test client, checked on Bun, Node.js, workerd and AOT-compiled Workers.
+
+  Breaking changes:
+
+  - Error responses are RFC 9457 problem details (`application/problem+json`). Request validation errors answer 422 with an `errors` list of JSON pointers (`problems.validationStatus: 400` keeps 400). Server errors only show their message and stack in development. Thrown statuses (`c.status(...)`) are sent as they are.
+  - Client errors (4xx) are no longer reported to `onError`, the `elysium:error` event or the trace.
+  - `Runtime.serve` may return a handle with `close()`, which the application calls on shutdown.
+  - Request bodies are limited to 1 MiB by default (`http.bodyLimit`), also when chunked.
+  - The environment schema is validated when the app is built or run, with every error reported at once, instead of in the constructor.
+
+  Features:
+
+  - `DomainError`, with `status`, `type`, `title`, `detail` and extensions, and shortcuts such as `DomainError.notFound()`.
+  - Exception filters (`@Catch()`, `filters` on routes, controllers, modules and the app) and interceptors (`interceptors` on the same levels), with `TimingInterceptor`, `TransformInterceptor` and mnemosyne's `CacheInterceptor`.
+  - Typed configuration: `Secret` values, module `envSchema`s merged into the app's, `InvalidEnvironmentError`.
+  - `http` options: CORS, security headers, body limits and trusted proxies (`ctx.ip`). Runtimes report the client address through `clientAddress`.
+  - `createTestingHttpApp` and `createHttpClient` send requests to an app in memory, with `expectStatus()`.
+
+  Fixes:
+
+  - App-level `onRequest` middlewares run in the request scope.
+  - On Workers, the request scope of a streamed response is disposed when the body ends, not when `fetch` returns.
+  - `KeyvWorkersKV.clear()` stays within an operation budget (`maxOperations`).
+  - The Node.js bridge treats a destroyed socket as a client abort.
+  - Heracles performance metrics report through the Redis port (`connection` or `client`), not a Bun client.
+  - `styx routes:generate` names anonymous default controllers after their file; `styx create` pins `@elysiumjs/*` packages to the versions it was released with; invalid names are reported as Elysium errors.
+
+- [#15](https://github.com/na2axl/elysiumjs/pull/15) [`fbcc7da`](https://github.com/na2axl/elysiumjs/commit/fbcc7dad127db29da42e7a4a5c2124966731cd88) Thanks [@na2axl](https://github.com/na2axl)! - Resources, queries, units of work and rate limits.
+
+  Breaking:
+
+  - A route with a `response` schema serializes its handler result through it: fields the schema does not declare are dropped, a `Date` becomes an ISO string (`YYYY-MM-DD` for `format: 'date'`), and an object with `toJSON()` becomes what it returns. Set `serialize: false` on a route to send the result as it is.
+
+  Added:
+
+  - `Resource.hidden(schema)` marks a field that never reaches responses nor the OpenAPI document. `Resource.serialize()` and `Resource.project()` are exported for use outside routes.
+  - Sparse fieldsets: `?fields=id,title` keeps only those fields of an object, of each item of an array, or of each item of a `data` array. An unknown or hidden field answers a 400 problem.
+  - Rate limits with `@RateLimit({ window, max, key?, store?, name? })` on routes and controllers (`@RateLimit(false)` turns one off), and a default limit and store in the app's `rateLimit` option, with fixed windows. Responses carry `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy`; a client over the limit gets a 429 problem with `Retry-After`. Counts are kept by a `RateLimitStore`: `MemoryRateLimitStore` (core), `RedisRateLimitStore` (`@elysiumjs/redis`) or `WorkersRateLimitStore` over a Cloudflare rate limiting binding (`@elysiumjs/runtime-workers`), which only decides whether a hit is over the limit, so its responses carry no `RateLimit-Reset`.
+  - `ModelResource(model, { hidden, pick, omit, extend })` (`@elysiumjs/mnemosyne`) builds a response schema from a model.
+  - `Query.define(model, spec)` declares the filters (`filter[field][op]=value`), sorts, page size and cursor a list accepts; `Query.schema()` gives its query schema, `Query.parse()` turns a request query into a `ParsedQuery` and answers a 400 problem with a pointer per mistake, and `Query.page()` / `Query.pageSchema()` build cursor pages (`{ data, nextCursor }`).
+  - `DrizzleRepository.list(query)` and `count(query)` run a `ParsedQuery` with keyset pagination (`@elysiumjs/mnemosyne-drizzle`), and `compileQuery()` gives its `where` and `orderBy`.
+  - Units of work: `UnitOfWork.run()` and the `@Transactional()` method decorator run work in one transaction, and `UnitOfWork.afterCommit()` / `afterRollback()` defer work, such as sending a message, until the outermost transaction has ended. `transactional` routes open a unit of work too.
+
+- [#16](https://github.com/na2axl/elysiumjs/pull/16) [`ac96e55`](https://github.com/na2axl/elysiumjs/commit/ac96e55874b0ffe350b287c4278cd85afecb7576) Thanks [@na2axl](https://github.com/na2axl)! - Redis, databases, logs, jobs and builds on Bun, Node.js and Cloudflare Workers.
+
+  Breaking:
+
+  - The level shortcuts of `InteractsWithConsole` (`info`, `success`, `warning`, `error` and `debug`) write a tag (`[I]`, `[S]`, `[W]`, `[E]` and `[D]`, in color) before the message, which `InteractsWithConsole.useTags()` changes. `trace()` writes to stderr.
+  - Outside Bun, a Drizzle connection needs a `driver`. Without one, the `connection` and `client` props are a Bun SQL connection, which is only available on Bun; elsewhere the connection throws `MissingDriverError`, which names the drivers.
+
+  Added:
+
+  - Redis adapters (`@elysiumjs/redis`): `ioredis(create)` plugs an ioredis client into the Redis port on Node.js, and `upstash({ token, url?, fetch? })` talks to Upstash over its REST API, for Workers (no pub/sub). `bunRedis` explains which adapter to use when it runs outside Bun.
+  - Drizzle drivers (`@elysiumjs/mnemosyne-drizzle`): a `DrizzleDriver` port set with the `driver` prop of a connection, and drivers on subpaths so that only the chosen database client is imported: `/bun-sql` (`bunSql()`), `/postgres-js` (`postgresJs()`), `/node-postgres` (`nodePostgres()`) and `/hyperdrive` (`hyperdrive({ binding, driver })`, a client per Worker invocation over a Cloudflare Hyperdrive binding). `DrizzleModule` closes connections through their driver, and `migration:run` runs on any driver.
+  - `InteractsWithConsole.write()` and `Runtime.write()` take the level of the line (`OutputLevel`), which the level shortcuts pass. On Cloudflare Workers, a line is written with the console method of its level, so Workers Logs keep it.
+  - `JsonConsoleLogger` (`@elysiumjs/hermes`): JSON lines through the console of the runtime (warnings and errors on stderr), with levels, error serialization and `child()`. `HermesModule.with({ transport: 'console' | 'pino' })` picks it, and it is the default on Workers. `RequestLogInterceptor` writes one structured line per request: method, route, status, duration, client address and request id.
+  - Scheduled jobs (`@elysiumjs/heracles`): `@Schedule(cron, { timezone, args })` on a job class, a five-field cron parser (`Cron`, with lists, ranges, steps and names), and a `Scheduler` that dispatches the jobs on time on Bun and Node.js, taking a Redis lock per tick when a Redis connection is set. The `heracles:schedule` command runs it.
+  - `@elysiumjs/heracles-workers`: `CloudflareQueueTransport` sends jobs to a Cloudflare Queue (dispatch delays become `delaySeconds`), and `HeraclesWorkersModule` consumes them in the Worker's `queue` handler (ack on success, retry with a delay up to the job's retries) and dispatches the `@Schedule()` jobs whose expression is the cron of a trigger.
+  - Queue handlers (`@elysiumjs/runtime-workers`) can settle a message themselves with `ack()` or `retry({ delaySeconds })`; the messages they leave are acked when no handler failed on them.
+  - `styx build --target node` (`@elysiumjs/hephaestus`) bundles the app into one ES module for Node.js, with decorator metadata emitted at build time, run with `node dist/server.js serve`. `styx build --target workers` runs from the CLI, resolves packages to their browser entry, and leaves Node.js modules imported by bare names to workerd (`nodejs_compat`).
+  - `styx create` (`@elysiumjs/styx`) takes `--runtime bun|node|workers`, `--database`, `--cache` and `--package-manager bun|npm|pnpm`. Each runtime gets its entry, tsconfig types, scripts and drivers: postgres.js and ioredis on Node.js; Hyperdrive, Upstash, console logs and a `wrangler.jsonc` on Workers.
+
+- [#12](https://github.com/na2axl/elysiumjs/pull/12) [`98a16aa`](https://github.com/na2axl/elysiumjs/commit/98a16aae889d46f7a9fb5573188f4cbe3629dd3b) Thanks [@na2axl](https://github.com/na2axl)! - `createWorker(app)` from `@elysiumjs/runtime-workers` builds an application and returns the handlers a Cloudflare Worker exports: `fetch` serves the routes, `queue` hands each batch to the service methods marked `@Workers.queue(name)`, and `scheduled` calls the methods marked `@Workers.cron(expression)`. Each invocation runs with its own env and execution context: `Workers.env()`, `Workers.context()` and `Workers.binding(name)` read them, and `WorkersModule` provides them, and the bindings it lists, as request-scoped services injected with `@Workers.inject(name)`. `KeyvWorkersKV` stores mnemosyne caches in a KV namespace. `bun run check:wrangler` runs a sample Worker in `wrangler dev`.
+
+  `MnemosyneModule` takes other Keyv stores in `cache.stores`, read with `Cache.store(name)`.
+
+  `styx build --target workers` (Hephaestus `hephaestus:build --target workers`, `WorkersBuilder`) bundles a Worker with its routes compiled ahead of time and refuses a bundle that generates code at runtime.
+
+  In core, `Application.boot()` initialises the modules once, for hosts that handle more than requests; `Kernel.serviceClasses(node)` lists the service classes of a module; console output falls back to `console` where the host has no output streams; and a singleton depending on a request-scoped service throws `ScopeMismatchError` even when it is built outside a request.
+
+### Patch Changes
+
+- [#7](https://github.com/na2axl/elysiumjs/pull/7) [`e9c3d98`](https://github.com/na2axl/elysiumjs/commit/e9c3d98dd2714b69100215f7c8a80046da463148) Thanks [@na2axl](https://github.com/na2axl)! - Elysium runs on Elysia 2 (`elysia@^2.0.0-rc.1`), with TypeBox 1 (`typebox`), `@elysia/openapi` and `@elysia/opentelemetry`.
+
+  Breaking:
+
+  - `TSchema` and `Static` are re-exported from `typebox` instead of `@sinclair/typebox`; `Value` comes from `typebox/value` and `Value.Errors()` returns an array.
+  - `Application.onError()` receives a `ServerError` (exported from core). Elysia now names its errors in kebab case; the default error response keeps the upper snake case names (`VALIDATION`, `NOT_FOUND`, `UNKNOWN` for other errors).
+  - `AppHttpContext` is a plain interface with `decorator`, `store` and `derive` records (Elysia 2 renamed `resolve` to `derive`).
+  - Websocket controllers install Elysia's `websocket()` capability themselves.
+
+  A module or controller `onRequest` middleware that answers now stops the request: Elysia 2 ignores values returned from a transform hook, so the response is thrown as a status and sent as is, without going through `onError`.
+
+  `mnemosyne` builds date columns with `t.Codec` (TypeBox 1 dropped `Transform`). `argus` traces every route of the app it is installed on and ends each span once, keeping the error status when the request failed.
+
+- Updated dependencies [[`6bc48fe`](https://github.com/na2axl/elysiumjs/commit/6bc48febd51f7090c582e73f349eaeff7261241c), [`e9c3d98`](https://github.com/na2axl/elysiumjs/commit/e9c3d98dd2714b69100215f7c8a80046da463148), [`557a3ca`](https://github.com/na2axl/elysiumjs/commit/557a3cab7af8053a8bab9944e492e5022d91aa82), [`ccc3f5b`](https://github.com/na2axl/elysiumjs/commit/ccc3f5bb904d1bf52d8c72ebf7ea8d10f617a8c4), [`6789879`](https://github.com/na2axl/elysiumjs/commit/678987976ecfd46b534b65276e0de3f448977562), [`87299fd`](https://github.com/na2axl/elysiumjs/commit/87299fd9da82d1a408ced1891c0c3d42991444e5), [`bee66bd`](https://github.com/na2axl/elysiumjs/commit/bee66bdc874b8f23fea356f7d3adf7555a48ca64), [`0057b67`](https://github.com/na2axl/elysiumjs/commit/0057b67df0e3abecab8a9accff6b55a6a64c21df), [`632d77b`](https://github.com/na2axl/elysiumjs/commit/632d77b561fc43ade605fb69b06ac1b9b9a2ffc4), [`1ea417e`](https://github.com/na2axl/elysiumjs/commit/1ea417e3583250bc2f975d795f398b7ff736115d), [`0956186`](https://github.com/na2axl/elysiumjs/commit/0956186db0ca5a83c0a6636aeb2a4c81a0033de4), [`fbcc7da`](https://github.com/na2axl/elysiumjs/commit/fbcc7dad127db29da42e7a4a5c2124966731cd88), [`ac96e55`](https://github.com/na2axl/elysiumjs/commit/ac96e55874b0ffe350b287c4278cd85afecb7576), [`98a16aa`](https://github.com/na2axl/elysiumjs/commit/98a16aae889d46f7a9fb5573188f4cbe3629dd3b)]:
+  - @elysiumjs/core@0.11.0

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# @elysiumjs/runtime-workers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cloudflare Workers runtime and adapter for [Elysium.js](https://github.com/na2axl/elysiumjs).
+
+## Installation
+
+```bash
+bun add @elysiumjs/runtime-workers
+```
+
+## Usage
+
+```ts
+import { Application } from '@elysiumjs/core';
+import { runtime } from '@elysiumjs/runtime-workers';
+
+@Application.register({ runtime, modules: [] })
+class App extends Application {}
+```
+
+The package exports `runtime`; rename it at import if you like: `import { runtime as workersRuntime } from '@elysiumjs/runtime-workers'`.
+
+Environment variables come from `process.env`, which workerd fills from the Worker's vars and secrets with the `nodejs_compat` flag; use `createRuntime({ env })` to pass others. The host owns the server and the isolate: `serve` throws (export the app's `fetch` from the Worker), and exit and signals do nothing. `bun run check:runtime` checks that the bundle never touches the `Bun` global.
+
+## The Worker entry
+
+`createWorker()` builds the app and returns the handlers a Worker module exports: `fetch` serves the routes, `queue` hands each batch to its consumers, and `scheduled` runs the cron handlers. It also returns the root Elysia `app`; export it as `app` so that the AOT plugin below compiles the routes:
+
+```ts
+import { createWorker } from '@elysiumjs/runtime-workers';
+
+import { App } from './app';
+
+const worker = await createWorker(new App());
+
+export const app = worker.app;
+
+export default worker;
+```
+
+Modules boot on the first invocation, whatever its kind, so building runs no `onInit` work.
+
+workerd binds every I/O object (a stream, a request or response body, a socket) to the request that created it. A singleton's `onInit` runs during the first invocation, so it may do I/O and keep what it read, but it must not keep the I/O object itself: a later invocation that uses it fails with "Cannot perform I/O on behalf of a different request". Open such objects per invocation, in request-scoped services.
+
+A singleton whose `onInit` calls its own app, through a service binding or a fetch to itself, deadlocks: the app holds every request until its boot has finished, and the boot waits for that response.
+
+### Bindings
+
+Each invocation runs with its own env and execution context. Read them with `Workers.env()`, `Workers.context()` and `Workers.binding(name)`, or inject them: `WorkersModule` provides the env (`workers.env`), the context (`workers.context`) and each binding it lists as global request-scoped services.
+
+```ts
+import { Service, ServiceScope } from '@elysiumjs/core';
+import { Workers, WorkersModule } from '@elysiumjs/runtime-workers';
+
+@Service.register({ scope: ServiceScope.REQUEST })
+export class JobQueue {
+	public constructor(@Workers.inject('JOBS') private readonly queue: Queue<Job>) {}
+
+	public send(job: Job) {
+		return this.queue.send(job);
+	}
+}
+
+@Application.register({
+	runtime,
+	modules: [WorkersModule.with({ bindings: ['JOBS'] }), JobsModule]
+})
+export class App extends Application {}
+```
+
+A binding belongs to the invocation, so only request-scoped services, factories and request-scoped controllers take it: a singleton that depends on one throws `ScopeMismatchError`. Outside an invocation, reading a binding throws `OutsideInvocationError`.
+
+### Queues and cron triggers
+
+Mark methods of module services with `@Workers.queue(name)` or `@Workers.cron(expression)`. Each handler runs in its module, in a request scope of its own. A queue handler receives the batch, and the whole batch is retried when it throws. A cron handler receives the scheduled controller; the expression must match the one in the wrangler config. `*` matches every queue or cron. A batch or event no handler matches throws `NoWorkersHandlerError`. A named queue has one consumer, so that each message is acked or retried by one decision: two handlers of the same queue throw `DuplicateQueueConsumerError` when the Worker is created. `*` handlers, such as observers, are not counted.
+
+```ts
+@Service.register()
+export class JobConsumer {
+	@Workers.queue('jobs')
+	public async handle(batch: MessageBatch<Job>) {
+		for (const message of batch.messages) {
+			await this.run(message.body);
+			message.ack();
+		}
+	}
+
+	@Workers.cron('*/5 * * * *')
+	public async sweep(controller: ScheduledController) {}
+}
+```
+
+With `@Workers.queue(name, { each: true })`, the handler receives one message at a time: a message it throws on is retried and the others are acked. Without `each`, the handler keeps batch semantics: it acks or retries messages itself, and the whole batch is retried when it throws.
+
+Several handlers can match one queue. A message retried for one of them is delivered again to every matching handler, including those that already handled it, so queue handlers must be idempotent.
+
+The handler types (`WorkersMessageBatch`, `WorkersScheduledController`, `WorkersKVNamespace`, ...) are structural, so the types from `@cloudflare/workers-types` or `wrangler types` fit them.
+
+### KV cache
+
+`KeyvWorkersKV` is a Keyv store over a KV namespace, for the caches of `@elysiumjs/mnemosyne`. It reads the binding from the current invocation on every call. KV is eventually consistent and expires entries after at least 60 seconds, so shorter TTLs are rounded up.
+
+```ts
+MnemosyneModule.with({
+	cache: { redis: false, stores: { kv: () => new KeyvWorkersKV({ binding: 'CACHE' }) } }
+});
+
+await Cache.store('kv').set('greeting', 'hello', 120_000);
+```
+
+`clear()` lists the keys of the namespace and deletes them, and each listed page and each deleted key is a subrequest. It stops at `maxOperations` (900 by default, under the 1000 subrequests of the paid plan; set 45 on the free plan), logs how many keys are left, and the next `clear()` goes on with them. `delete()` reads the key first, because the Keyv contract returns whether it existed; on eventually consistent KV that answer is best effort.
+
+## Compiling ahead of time
+
+Workers forbid generating code at runtime (`new Function`), which Elysia does for validators unless the app is compiled ahead of time. With `@elysiumjs/hephaestus` installed, `styx build --target workers` bundles `src/worker.ts` this way into `dist/worker.js`. Without it, bundle the entry with Elysia's AOT plugin, which evaluates it at build time:
+
+```ts
+import { aot } from 'elysia/plugin/aot/bun';
+
+await Bun.build({
+	entrypoints: ['src/worker.ts'],
+	outdir: 'dist',
+	target: 'browser',
+	format: 'esm',
+	conditions: ['workerd', 'worker', 'browser'],
+	external: ['node:*', 'cloudflare:*'],
+	plugins: [aot('src/worker.ts', { target: 'workerd' })]
+});
+```
+
+`bun run check:aot` compiles a sample app this way, checks that the bundle has no runtime code generation, and serves a validated route under Node.js with code generation from strings disallowed. `bun run check:wrangler` compiles the sample Worker in `scripts/worker` and runs it in `wrangler dev`: a route sends to a queue, the consumer and a cron handler write to the KV cache, and routes read it back.
+
+## License
+
+Apache-2.0

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+import { ElysiumError } from '@elysiumjs/core';
+/**
+ * Thrown when a binding is read outside a Worker invocation.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class OutsideInvocationError extends ElysiumError {
+    readonly what: string;
+    constructor(what: string);
+}
+/**
+ * Thrown when the Worker has no binding with the requested name.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class BindingNotFoundError extends ElysiumError {
+    readonly binding: string;
+    constructor(binding: string);
+}
+/**
+ * Thrown when a queue batch or a scheduled event reaches the Worker and no service handles it.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class NoWorkersHandlerError extends ElysiumError {
+    readonly kind: 'queue' | 'cron';
+    readonly key: string;
+    constructor(kind: 'queue' | 'cron', key: string);
+}
+/**
+ * Thrown when the Worker is created and two service methods consume the same queue. A queue has
+ * one consumer, so that every message is acked or retried by one decision; `*` handlers are not
+ * counted.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class DuplicateQueueConsumerError extends ElysiumError {
+    readonly queue: string;
+    readonly consumers: string[];
+    constructor(queue: string, consumers: string[]);
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { BindingNotFoundError, DuplicateQueueConsumerError, NoWorkersHandlerError, OutsideInvocationError } from './errors';
+export { type Invocation, runInvocation } from './invocation';
+export { KeyvWorkersKV, type KeyvWorkersKVOptions } from './kv-store';
+export { type WorkersModuleConfig, WorkersModule } from './module';
+export { WorkersRateLimitStore, type WorkersRateLimitStoreOptions } from './rate-limit';
+export { createRuntime, runtime, type WorkersRuntimeOptions } from './runtime';
+export * from './types';
+export { createWorker } from './worker';
+export { type WorkersHandlerMeta, Workers, WORKERS_CONTEXT_SERVICE, WORKERS_ENV_SERVICE } from './workers';

package/dist/index.js

@@ -0,0 +1,2 @@
+var __legacyDecorateClassTS=function(decorators,target,key,desc){var c=arguments.length,r=c<3?target:desc===null?desc=Object.getOwnPropertyDescriptor(target,key):desc,d;if(typeof Reflect==="object"&&typeof Reflect.decorate==="function")r=Reflect.decorate(decorators,target,key,desc);else for(var i=decorators.length-1;i>=0;i--)if(d=decorators[i])r=(c<3?d(r):c>3?d(target,key,r):d(target,key))||r;return c>3&&r&&Object.defineProperty(target,key,r),r};import{ElysiumError}from"@elysiumjs/core";class OutsideInvocationError extends ElysiumError{what;constructor(what){super(`${what} is only available while the Worker handles a request, a queue batch or a scheduled event.`);this.what=what}}class BindingNotFoundError extends ElysiumError{binding;constructor(binding){super(`The Worker has no binding named "${binding}". Declare it in the wrangler config.`);this.binding=binding}}class NoWorkersHandlerError extends ElysiumError{kind;key;constructor(kind,key){super(kind==="queue"?`No service consumes the queue "${key}". Add @Workers.queue('${key}') to a method of a module service.`:`No service handles the cron "${key}". Add @Workers.cron('${key}') to a method of a module service.`);this.kind=kind;this.key=key}}class DuplicateQueueConsumerError extends ElysiumError{queue;consumers;constructor(queue,consumers){super(`The queue "${queue}" has more than one consumer: ${consumers.join(", ")}. Keep one.`);this.queue=queue;this.consumers=consumers}}import{AsyncLocalStorage}from"node:async_hooks";var storage=new AsyncLocalStorage,runInvocation=(invocation,fn)=>storage.run(invocation,fn),currentInvocation=()=>storage.getStore();import{getLogger}from"@elysiumjs/core";import{Metadata,Service}from"@elysiumjs/core";var WORKERS_ENV_SERVICE="workers.env",WORKERS_CONTEXT_SERVICE="workers.context",HANDLERS=Symbol("workers:handlers"),addHandler=(kind,key,each)=>(target,method)=>{if(typeof target==="function")throw TypeError(`@Workers.${kind}() goes on an instance method, not on a static one.`);let cls=target.constructor,handlers=Metadata.getOwn(HANDLERS,cls)??[];Metadata.define(HANDLERS,[...handlers,{kind,key,method,...each?{each}:{}}],cls)},Workers;((Workers)=>(Workers.env=()=>{let invocation=currentInvocation();if(!invocation)throw new OutsideInvocationError("The Worker env");return invocation.env},Workers.context=()=>{let invocation=currentInvocation();if(!invocation)throw new OutsideInvocationError("The execution context");return invocation.ctx},Workers.binding=(name)=>{let value=Workers.env()[name];if(value===void 0)throw new BindingNotFoundError(name);return value},Workers.bindingService=(name)=>`workers.binding.${name}`,Workers.inject=(name)=>Service.inject(Workers.bindingService(name)),Workers.queue=(queue,options)=>addHandler("queue",queue,options?.each),Workers.cron=(cron)=>addHandler("cron",cron),Workers.handlersOf=(cls)=>Metadata.get(HANDLERS,cls)??[]))(Workers||={});var MIN_TTL_SECONDS=60,KV_DELETE_CHUNK=50,DEFAULT_MAX_OPERATIONS=900;class KeyvWorkersKV{namespace;#binding;#separator;#maxOperations;#listeners=new Map;constructor(options){this.#binding=options.binding,this.namespace=options.namespace,this.#separator=options.keyPrefixSeparator??"::",this.#maxOperations=Math.max(2,options.maxOperations??DEFAULT_MAX_OPERATIONS)}get opts(){return{dialect:"workers-kv",binding:this.#binding,namespace:this.namespace,keyPrefixSeparator:this.#separator}}on(event,listener){return this.#listeners.set(event,[...this.#listeners.get(event)??[],listener]),this}async get(key){let value=await this.#kv().get(this.#key(key),"text");return value===null?void 0:value}async getMany(keys){return Promise.all(keys.map((key)=>this.get(key)))}async has(key){return await this.get(key)!==void 0}async set(key,value,ttl){let options=ttl?{expirationTtl:Math.max(MIN_TTL_SECONDS,Math.ceil(ttl/1000))}:void 0;await this.#kv().put(this.#key(key),String(value),options)}async setMany(entries){await Promise.all(entries.map(({key,value,ttl})=>this.set(key,value,ttl)))}async delete(key){let existed=await this.has(key);return await this.#kv().delete(this.#key(key)),existed}async deleteMany(keys){return(await Promise.all(keys.map((key)=>this.delete(key)))).some(Boolean)}async clear(){let kv=this.#kv(),prefix=this.namespace?`${this.namespace}${this.#separator}`:void 0,budget=this.#maxOperations,names=[],cursor;do{let page=await kv.list({prefix,cursor});budget--,names.push(...page.keys.map(({name})=>name)),cursor=page.list_complete?void 0:page.cursor}while(cursor&&budget>names.length+1);let deleting=names.slice(0,Math.max(0,budget));for(let i=0;i<deleting.length;i+=KV_DELETE_CHUNK)await Promise.all(deleting.slice(i,i+KV_DELETE_CHUNK).map((name)=>kv.delete(name)));let left=names.length-deleting.length;if(left>0||cursor)getLogger().warn("KV clear() stopped at its operation budget; call it again for the rest",{binding:this.#binding,namespace:this.namespace,deleted:deleting.length,remaining:cursor?`${left} listed, more not listed`:left,maxOperations:this.#maxOperations})}#kv(){return Workers.binding(this.#binding)}#key(key){return this.namespace?`${this.namespace}${this.#separator}${key}`:key}}import{Module,ServiceScope}from"@elysiumjs/core";class WorkersModule extends Module.configurable({defaults:{bindings:[]}}){}WorkersModule=__legacyDecorateClassTS([Module.register({services:(config)=>{let perInvocation=(name,read)=>({name,global:!0,scope:ServiceScope.REQUEST,factory:read});return[perInvocation(WORKERS_ENV_SERVICE,()=>Workers.env()),perInvocation(WORKERS_CONTEXT_SERVICE,()=>Workers.context()),...config.bindings.map((name)=>perInvocation(Workers.bindingService(name),()=>Workers.binding(name)))]}})],WorkersModule);class WorkersRateLimitStore{#binding;constructor(options){this.#binding=options.binding}async hit(key){let{success}=await Workers.binding(this.#binding).limit({key});return{limited:!success}}}import{RuntimeNotSupportedError}from"@elysiumjs/core";var CONSOLE_METHODS={trace:"debug",debug:"debug",info:"info",warn:"warn",error:"error",fatal:"error"},createRuntime=(options={})=>({name:"workers",env:()=>options.env??(typeof process>"u"?{}:process.env),sleep:(ms)=>new Promise((resolve)=>setTimeout(resolve,ms)),serve(){throw new RuntimeNotSupportedError("Application.serve","workers","Export the app's fetch handler from the Worker instead.")},exit(){},argv:()=>[],write(stream,text,level){let line=text.endsWith(`
+`)?text.slice(0,-1):text;console[level?CONSOLE_METHODS[level]:stream==="stderr"?"error":"log"](line)},terminal:()=>{return},clientAddress:(request)=>request.headers.get("cf-connecting-ip")??void 0,onShutdown(){return()=>{}}}),runtime=createRuntime();import{getLogger as getLogger2,ModuleContext,Service as Service2}from"@elysiumjs/core";var collectHandlers=(app)=>app.kernel.graph.nodes.flatMap((node)=>app.kernel.serviceClasses(node).flatMap((cls)=>Workers.handlersOf(cls).map((meta)=>({...meta,node,cls})))),assertOneConsumerPerQueue=(handlers)=>{let consumers=new Map;for(let handler of handlers){if(handler.kind!=="queue"||handler.key==="*")continue;let names=consumers.get(handler.key)??[],name=`${handler.cls.name}.${String(handler.method)}`;if(!names.includes(name))names.push(name);consumers.set(handler.key,names)}for(let[queue,names]of consumers)if(names.length>1)throw new DuplicateQueueConsumerError(queue,names)},disposeAfterBody=(request,response)=>{let ctx=Workers.context(),source=response.body;if(!source||response.status===101)return ctx.waitUntil(Service2.disposeRequestScope(request)),response;let ended;ctx.waitUntil(new Promise((resolve)=>ended=resolve).then(()=>Service2.disposeRequestScope(request)));let reader=source.getReader(),body=new ReadableStream({async pull(controller){try{let{done,value}=await reader.read();if(done)controller.close(),ended();else controller.enqueue(value)}catch(error){controller.error(error),ended()}},async cancel(reason){ended(),await reader.cancel(reason)}});return new Response(body,response)},runHandler=(handler,argument)=>ModuleContext.run(handler.node,()=>Service2.runInRequestScope(async()=>{await(await Service2.resolve(handler.cls))[handler.method](argument)})),dispatch=async(handlers,kind,key,argument)=>{let matching=handlers.filter((h)=>h.kind===kind&&(h.key===key||h.key==="*"));if(matching.length===0)throw new NoWorkersHandlerError(kind,key);for(let handler of matching)await runHandler(handler,argument)},settleable=(message,settled)=>({get id(){return message.id},get timestamp(){return message.timestamp},get body(){return message.body},get attempts(){return message.attempts},ack:()=>{settled.add(message),message.ack()},retry:(options)=>{settled.add(message),message.retry(options)}}),dispatchQueue=async(handlers,batch)=>{let matching=handlers.filter((h)=>h.kind==="queue"&&(h.key===batch.queue||h.key==="*"));if(matching.length===0)throw new NoWorkersHandlerError("queue",batch.queue);let failed=new Set,settled=new Set,log=(handler,error)=>getLogger2().error("Queue handler failed",{queue:batch.queue,handler:`${handler.cls.name}.${String(handler.method)}`,error});for(let handler of matching)if(handler.each)for(let[index,message]of batch.messages.entries())try{await runHandler(handler,settleable(message,settled))}catch(error){failed.add(index),log(handler,error)}else try{await runHandler(handler,batch)}catch(error){batch.messages.forEach((_,index)=>failed.add(index)),log(handler,error)}for(let[index,message]of batch.messages.entries()){if(settled.has(message))continue;if(failed.has(index))message.retry();else message.ack()}},createWorker=async(app)=>{let elysia=await app.build(),handlers=collectHandlers(app);return assertOneConsumerPerQueue(handlers),{app:elysia,fetch:(request,env,ctx)=>runInvocation({env,ctx},async()=>{let response;try{return response=await elysia.fetch(request),disposeAfterBody(request,response)}finally{if(!response)Workers.context().waitUntil(Service2.disposeRequestScope(request))}}),queue:(batch,env,ctx)=>runInvocation({env,ctx},async()=>{await app.boot(),await dispatchQueue(handlers,batch)}),scheduled:(controller,env,ctx)=>runInvocation({env,ctx},async()=>{await app.boot(),await dispatch(handlers,"cron",controller.cron,controller)})}};export{BindingNotFoundError,DuplicateQueueConsumerError,KeyvWorkersKV,NoWorkersHandlerError,OutsideInvocationError,WORKERS_CONTEXT_SERVICE,WORKERS_ENV_SERVICE,Workers,WorkersModule,WorkersRateLimitStore,createRuntime,createWorker,runInvocation,runtime};

package/dist/invocation.d.ts

@@ -0,0 +1,19 @@
+import type { WorkersExecutionContext } from './types';
+/**
+ * What a Worker invocation (a request, a queue batch or a scheduled event) was called with.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type Invocation = {
+    /** The Worker's bindings, vars and secrets. */
+    readonly env: Record<string, unknown>;
+    /** The execution context of the invocation. */
+    readonly ctx: WorkersExecutionContext;
+};
+/**
+ * Runs `fn` as part of an invocation, so that its bindings resolve inside it.
+ * @param invocation The env and context of the invocation.
+ * @param fn The work to run.
+ */
+export declare const runInvocation: <T>(invocation: Invocation, fn: () => T) => T;
+/** The current invocation, if any. */
+export declare const currentInvocation: () => Invocation | undefined;

package/dist/kv-store.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Options of {@link KeyvWorkersKV}.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type KeyvWorkersKVOptions = {
+    /** The name of the KV namespace binding. */
+    binding: string;
+    /** The namespace prefixed to every key. Keyv sets it. */
+    namespace?: string;
+    /** The separator between the namespace and the key. Defaults to `::`. */
+    keyPrefixSeparator?: string;
+    /**
+     * The most KV operations (one per listed page, one per deleted key) one `clear()` makes, so
+     * that it stays within the subrequest limit of an invocation. Defaults to 900, under the 1000
+     * of the paid plan; set 45 on the free plan. Keys left over are logged, and the next
+     * `clear()` goes on with them.
+     */
+    maxOperations?: number;
+};
+/**
+ * A Keyv store over Workers KV, for the caches of `@elysiumjs/mnemosyne`.
+ *
+ * The KV namespace is read from the current invocation on every call, so the store holds no
+ * binding between invocations. KV is eventually consistent, and entries expire after at least
+ * 60 seconds: shorter TTLs are rounded up.
+ *
+ * @example
+ * ```ts
+ * MnemosyneModule.with({
+ * 	cache: { redis: false, stores: { kv: () => new KeyvWorkersKV({ binding: 'CACHE' }) } }
+ * });
+ * ```
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class KeyvWorkersKV {
+    #private;
+    namespace: string | undefined;
+    constructor(options: KeyvWorkersKVOptions);
+    get opts(): {
+        dialect: string;
+        binding: string;
+        namespace: string | undefined;
+        keyPrefixSeparator: string;
+    };
+    on(event: string, listener: (...args: any[]) => void): this;
+    get<Value>(key: string): Promise<Value | undefined>;
+    getMany<Value>(keys: string[]): Promise<Array<Value | undefined>>;
+    has(key: string): Promise<boolean>;
+    set(key: string, value: unknown, ttl?: number): Promise<void>;
+    setMany(entries: Array<{
+        key: string;
+        value: unknown;
+        ttl?: number;
+    }>): Promise<void>;
+    /**
+     * Deletes a key. It reads first, because the Keyv contract returns whether the key existed;
+     * on eventually consistent KV this answer is best-effort.
+     */
+    delete(key: string): Promise<boolean>;
+    deleteMany(keys: string[]): Promise<boolean>;
+    /**
+     * Deletes every key of the namespace, or every key of the KV namespace without one, within the
+     * `maxOperations` budget. When the budget runs out, the keys left are logged as a warning and
+     * stay for the next `clear()`.
+     */
+    clear(): Promise<void>;
+}

package/dist/module.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Configuration of the {@link WorkersModule}.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WorkersModuleConfig = {
+    /** The bindings to provide as services, injected with `@Workers.inject(name)`. */
+    bindings: string[];
+};
+declare const WorkersModule_base: (abstract new () => {
+    readonly config: WorkersModuleConfig;
+    onInit(): Promise<void> | void;
+    onDestroy(): Promise<void> | void;
+    onServe(_app: import("elysia").Elysia<any>): Promise<void> | void;
+}) & {
+    readonly config: string;
+    with(config: Partial<WorkersModuleConfig> | (() => Partial<WorkersModuleConfig> | Promise<Partial<WorkersModuleConfig>>)): import("@elysiumjs/core").ConfiguredModule<WorkersModuleConfig>;
+    resolveConfig(input?: Partial<WorkersModuleConfig> | undefined): WorkersModuleConfig;
+    register<TConfig_1 = any>(props?: import("@elysiumjs/core").ModuleProps<TConfig_1>): (target: import("@elysiumjs/core").ModuleClass) => void;
+    configurable<TConfig extends object>(options?: {
+        defaults?: Partial<TConfig>;
+        required?: (keyof TConfig)[];
+    }): any;
+};
+/**
+ * Provides the Worker's env (`workers.env`), the execution context (`workers.context`) and
+ * each listed binding (`workers.binding.<name>`) as global request-scoped services: they hold
+ * the values of the invocation being handled, never values kept across invocations.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class WorkersModule extends WorkersModule_base {
+}
+export {};

package/dist/rate-limit.d.ts

@@ -0,0 +1,35 @@
+import type { RateLimitStore } from '@elysiumjs/core';
+/**
+ * Options of {@link WorkersRateLimitStore}.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WorkersRateLimitStoreOptions = {
+    /** The name of the rate limiting binding, as declared in the wrangler config. */
+    binding: string;
+};
+/**
+ * Uses a Cloudflare Workers rate limiting binding (`ratelimits` in the wrangler config) as the
+ * store of a limit. The binding decides whether a hit is over the limit; its limit and period are
+ * set in the wrangler config, so set the same `max` and `window` on the limit, which the
+ * `RateLimit-Limit`, `RateLimit-Policy` and `Retry-After` headers report. The binding gives no
+ * count, so responses carry no `RateLimit-Reset`. Cloudflare counts per location, so a limit is
+ * approximate. The binding is read from the current invocation on every hit.
+ *
+ * @example
+ * ```jsonc
+ * // wrangler.jsonc
+ * { "ratelimits": [{ "name": "OTP_LIMITER", "namespace_id": "1001", "simple": { "limit": 3, "period": 60 } }] }
+ * ```
+ *
+ * ```ts
+ * @RateLimit({ window: 60_000, max: 3, store: new WorkersRateLimitStore({ binding: 'OTP_LIMITER' }) })
+ * ```
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class WorkersRateLimitStore implements RateLimitStore {
+    #private;
+    constructor(options: WorkersRateLimitStoreOptions);
+    hit(key: string): Promise<{
+        limited: boolean;
+    }>;
+}

package/dist/runtime.d.ts

@@ -0,0 +1,25 @@
+import type { Runtime } from '@elysiumjs/core';
+/**
+ * Options of {@link createRuntime}.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WorkersRuntimeOptions = {
+    /**
+     * The environment variables to expose. Defaults to `process.env`, which workerd fills from
+     * the Worker's vars and secrets with the `nodejs_compat` flag.
+     */
+    env?: Record<string, string | undefined>;
+};
+/**
+ * Creates the Elysium runtime for Cloudflare Workers. The host owns the server and the isolate's
+ * lifetime: export the app's `fetch` from the Worker instead of serving, and nothing exits or
+ * receives signals.
+ * @param options The runtime options.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare const createRuntime: (options?: WorkersRuntimeOptions) => Runtime;
+/**
+ * The Workers runtime reading `process.env`.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare const runtime: Runtime;

package/dist/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The parts of the Cloudflare Workers API the adapter uses. They are structural, so the types
+ * from `@cloudflare/workers-types` (or `wrangler types`) fit them.
+ * @module
+ */
+/** The `ctx` argument of a Worker handler. */
+export interface WorkersExecutionContext {
+    waitUntil(promise: Promise<unknown>): void;
+    passThroughOnException(): void;
+}
+/** A message of a queue batch. */
+export interface WorkersQueueMessage<Body = unknown> {
+    readonly id: string;
+    readonly timestamp: Date;
+    readonly body: Body;
+    readonly attempts: number;
+    ack(): void;
+    retry(options?: {
+        delaySeconds?: number;
+    }): void;
+}
+/** The batch a queue consumer receives. */
+export interface WorkersMessageBatch<Body = unknown> {
+    readonly queue: string;
+    readonly messages: readonly WorkersQueueMessage<Body>[];
+    ackAll(): void;
+    retryAll(options?: {
+        delaySeconds?: number;
+    }): void;
+}
+/** The controller of a scheduled (cron) event. */
+export interface WorkersScheduledController {
+    readonly scheduledTime: number;
+    readonly cron: string;
+    noRetry(): void;
+}
+/** A Workers KV namespace binding. */
+export interface WorkersKVNamespace {
+    get(key: string, type: 'text'): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+        prefix?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        keys: {
+            name: string;
+        }[];
+        list_complete: boolean;
+        cursor?: string;
+    }>;
+}
+/** A rate limiting binding. */
+export interface WorkersRateLimitBinding {
+    limit(options: {
+        key: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+}
+/** The handlers a Worker module exports. */
+export interface WorkersHandler<Env = Record<string, unknown>> {
+    fetch(request: Request, env: Env, ctx: WorkersExecutionContext): Promise<Response>;
+    queue(batch: WorkersMessageBatch, env: Env, ctx: WorkersExecutionContext): Promise<void>;
+    scheduled(controller: WorkersScheduledController, env: Env, ctx: WorkersExecutionContext): Promise<void>;
+}

package/dist/worker.d.ts

@@ -0,0 +1,31 @@
+import type { Application, Elysia } from '@elysiumjs/core';
+import type { WorkersHandler } from './types';
+/**
+ * Builds an application and returns the handlers a Cloudflare Worker module exports.
+ *
+ * - `fetch` serves the app's routes.
+ * - `queue` hands each batch to the service method marked `@Workers.queue(name)`, and to those
+ *   marked `@Workers.queue('*')`, then acks or retries each message on its own. A named queue has
+ *   one consumer: two are refused when the Worker is created.
+ * - `scheduled` calls the service methods marked `@Workers.cron(expression)`.
+ *
+ * Each invocation runs with its own env and execution context, read with `Workers.env()`,
+ * `Workers.binding(name)` or the services of `WorkersModule`. Modules boot on the first
+ * invocation, whatever its kind.
+ *
+ * The result also holds the root Elysia `app`. Export it as `app` from the Worker entry so that
+ * `elysia/plugin/aot` compiles the routes at build time.
+ *
+ * @example
+ * ```ts
+ * const worker = await createWorker(new App());
+ * export const app = worker.app;
+ * export default worker;
+ * ```
+ * @param app The application to serve.
+ * @returns The `fetch`, `queue` and `scheduled` handlers, and the root Elysia app.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare const createWorker: <Env = Record<string, unknown>>(app: Application) => Promise<WorkersHandler<Env> & {
+    readonly app: Elysia<any>;
+}>;

package/dist/workers.d.ts

@@ -0,0 +1,78 @@
+import type { WorkersExecutionContext } from './types';
+/** Name of the request-scoped service holding the Worker's env. */
+export declare const WORKERS_ENV_SERVICE = "workers.env";
+/** Name of the request-scoped service holding the invocation's execution context. */
+export declare const WORKERS_CONTEXT_SERVICE = "workers.context";
+/**
+ * A method that handles queue batches or scheduled events.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WorkersHandlerMeta = {
+    /** What the method handles. */
+    readonly kind: 'queue' | 'cron';
+    /** The queue name or the cron expression; `*` matches every queue or cron. */
+    readonly key: string;
+    /** The method name. */
+    readonly method: PropertyKey;
+    /** Queue handlers only: whether the method receives one message at a time. */
+    readonly each?: boolean;
+};
+/**
+ * Options of `@Workers.queue`.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WorkersQueueOptions = {
+    /** Receive one message at a time instead of the batch, so failures retry only that message. */
+    readonly each?: boolean;
+};
+export declare namespace Workers {
+    /**
+     * The Worker's env (bindings, vars and secrets) for the current invocation.
+     * @throws {OutsideInvocationError} Outside a request, a queue batch or a scheduled event.
+     */
+    const env: <Env = Record<string, unknown>>() => Env;
+    /**
+     * The execution context of the current invocation, for `waitUntil`.
+     * @throws {OutsideInvocationError} Outside a request, a queue batch or a scheduled event.
+     */
+    const context: () => WorkersExecutionContext;
+    /**
+     * A binding of the current invocation.
+     * @param name The binding name, as declared in the wrangler config.
+     * @throws {OutsideInvocationError} Outside a request, a queue batch or a scheduled event.
+     * @throws {BindingNotFoundError} When the Worker has no such binding.
+     */
+    const binding: <T = unknown>(name: string) => T;
+    /**
+     * The name of the service holding a binding, registered by `WorkersModule`.
+     * @param name The binding name.
+     */
+    const bindingService: (name: string) => string;
+    /**
+     * Injects a binding listed in `WorkersModule.with({ bindings })`. The binding is
+     * request-scoped, so only request-scoped services, factories and request-scoped
+     * controllers can take it.
+     * @param name The binding name.
+     */
+    const inject: (name: string) => ParameterDecorator;
+    /**
+     * Marks a method of a module service as the consumer of a queue. It receives the batch;
+     * when it throws, every message is retried. With `{ each: true }` it receives one message
+     * at a time, and only the messages it throws on are retried. After all handlers ran, the
+     * messages that no handler failed on are acked.
+     * @param queue The queue name, or `*` for every queue.
+     * @param options Set `each` to handle messages one by one.
+     */
+    const queue: (queue: string, options?: WorkersQueueOptions) => MethodDecorator;
+    /**
+     * Marks a method of a module service as the handler of a cron trigger. It receives the
+     * scheduled controller.
+     * @param cron The cron expression, exactly as in the wrangler config, or `*` for every cron.
+     */
+    const cron: (cron: string) => MethodDecorator;
+    /**
+     * The queue and cron handlers declared on a class.
+     * @param cls The class.
+     */
+    const handlersOf: (cls: object) => readonly WorkersHandlerMeta[];
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@elysiumjs/runtime-workers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "Apache-2.0",
+  "description": "Cloudflare Workers runtime and adapter for the Elysium.js framework.",
+  "private": false,
+  "author": {
+    "name": "Axel Nana",
+    "email": "axel.nana@workbud.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/na2axl/elysiumjs.git",
+    "directory": "@elysiumjs/runtime-workers"
+  },
+  "homepage": "https://github.com/na2axl/elysiumjs/tree/main/@elysiumjs/runtime-workers#readme",
+  "bugs": {
+    "url": "https://github.com/na2axl/elysiumjs/issues"
+  },
+  "scripts": {
+    "format": "prettier --write \"./src/**/*.ts\"",
+    "clean": "rimraf dist",
+    "build:js": "bun build ./src/index.ts --outdir ./dist --target browser --packages external --root ./src --minify-syntax --minify-whitespace",
+    "build:ts": "tsc",
+    "build": "bun run clean && bun run build:js && bun run build:ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "check:runtime": "bun scripts/check-runtime.ts",
+    "check:aot": "bun scripts/check-aot.ts",
+    "check:wrangler": "bun scripts/check-wrangler.ts"
+  },
+  "keywords": [
+    "elysium",
+    "framework",
+    "typescript",
+    "runtime",
+    "cloudflare",
+    "workers"
+  ],
+  "type": "module",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "@elysiumjs/core": "0.12.0",
+    "elysia": "^2.0.0-rc.1",
+    "wrangler": "4.158.0",
+    "@elysiumjs/mnemosyne": "0.5.1"
+  },
+  "peerDependencies": {
+    "@elysiumjs/core": "^0.12.0"
+  }
+}