@elysiumjs/redis 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# @elysiumjs/redis
+
+## 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
+
+- [#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.
+
+- [#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.
+
+- [#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.
+
+### Patch Changes
+
+- 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,36 @@
-# Temporary Holding Version
+# @elysiumjs/redis
 
-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.
+Redis connections for [Elysium.js](https://github.com/na2axl/elysiumjs), as global services named `redis.connection.{name}`.
+
+## Installation
+
+```bash
+bun add @elysiumjs/redis
+```
+
+## Usage
+
+```ts
+import { Application } from '@elysiumjs/core';
+import { Redis, RedisModule } from '@elysiumjs/redis';
+import { runtime as bunRuntime } from '@elysiumjs/runtime-bun';
+
+@Application.register({
+	runtime: bunRuntime,
+	modules: [
+		RedisModule.with({
+			default: 'cache',
+			connections: { cache: { url: process.env.REDIS_URL! } }
+		})
+	]
+})
+class App extends Application {}
+
+const client = Redis.getConnection('cache');
+```
+
+Clients are created on first use with `Bun.RedisClient`. Pass `client: (url, options) => ...` in the module config to use another client.
+
+## License
+
+Apache-2.0

package/dist/adapters/bun.d.ts

@@ -0,0 +1,6 @@
+import type { RedisClientFactory } from '../connection';
+/**
+ * Creates a connection with Bun's built-in Redis client, the default client of `RedisModule`.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare const bunRedis: RedisClientFactory;

package/dist/adapters/ioredis.d.ts

@@ -0,0 +1,37 @@
+import type { RedisClientFactory } from '../connection';
+/**
+ * The parts of an ioredis client the adapter uses. An `ioredis` `Redis` instance fits it.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface IoredisLike {
+    readonly status: string;
+    call(command: string, ...args: string[]): Promise<unknown>;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<unknown>;
+    del(...keys: string[]): Promise<number>;
+    expire(key: string, seconds: number): Promise<number>;
+    subscribe(...channels: string[]): Promise<unknown>;
+    unsubscribe(...channels: string[]): Promise<unknown>;
+    on(event: string, listener: (...args: any[]) => void): unknown;
+    off(event: string, listener: (...args: any[]) => void): unknown;
+    duplicate(): IoredisLike;
+    connect(): Promise<void>;
+    quit(): Promise<unknown>;
+}
+/**
+ * Plugs an ioredis client into the Redis port, for Node.js. Pass a function that creates the
+ * client; the module passes each connection's URL and options to it. Create it with
+ * `lazyConnect: true` so that it connects on `connect()`.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param create Creates an ioredis client.
+ * @example
+ * ```ts
+ * import IORedis from 'ioredis';
+ *
+ * RedisModule.with({
+ * 	client: ioredis((url, options) => new IORedis(url, { ...options, lazyConnect: true })),
+ * 	connections: { default: { url: process.env.REDIS_URL! } }
+ * });
+ * ```
+ */
+export declare const ioredis: (create: (url: string, options: Record<string, unknown>) => IoredisLike) => RedisClientFactory;

package/dist/adapters/upstash.d.ts

@@ -0,0 +1,27 @@
+import type { RedisClientFactory } from '../connection';
+/**
+ * Options of {@link upstash}.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type UpstashOptions = {
+    /** The REST URL of the database. Defaults to the connection URL. */
+    url?: string;
+    /** The REST token of the database. */
+    token: string;
+    /** The `fetch` to send commands with. Defaults to the global one. */
+    fetch?: typeof fetch;
+};
+/**
+ * Plugs Upstash Redis into the Redis port over its REST API, for Cloudflare Workers and other
+ * runtimes without TCP sockets. Every command is one HTTP request; pub/sub is not supported.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param options The REST token, and the REST URL when the connection URL is not it.
+ * @example
+ * ```ts
+ * RedisModule.with({
+ * 	client: upstash({ token: env.UPSTASH_REDIS_REST_TOKEN }),
+ * 	connections: { default: { url: env.UPSTASH_REDIS_REST_URL } }
+ * });
+ * ```
+ */
+export declare const upstash: (options: UpstashOptions) => RedisClientFactory;

package/dist/connection.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The surface of a Redis client that the Elysium packages rely on. Any Redis client can be
+ * plugged in by adapting it to this interface; everything else goes through {@link send}.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface RedisConnection {
+    /** Whether the connection is currently established. */
+    readonly connected: boolean;
+    /** Called when the connection is established. */
+    onconnect?: () => void;
+    /** Called when the connection is closed. */
+    onclose?: (error: unknown) => void;
+    /**
+     * Sends a raw command.
+     * @param command The command name, e.g. `ZADD`.
+     * @param args The arguments of the command.
+     */
+    send(command: string, args: string[]): Promise<unknown>;
+    /** Gets the value of a key, or `null` if it does not exist. */
+    get(key: string): Promise<string | null>;
+    /** Sets the value of a key. Use `send('SET', [...])` for options such as `PX` or `NX`. */
+    set(key: string, value: string): Promise<unknown>;
+    /** Deletes keys, resolving to the number of keys deleted. */
+    del(...keys: string[]): Promise<number>;
+    /** Sets the time to live of a key, resolving to `1` if it was set. */
+    expire(key: string, seconds: number): Promise<number>;
+    /** Subscribes to a pub/sub channel. */
+    subscribe(channel: string, listener: (message: string, channel: string) => void): Promise<unknown>;
+    /** Unsubscribes from a channel, or from all channels when none is given. */
+    unsubscribe(channel?: string): Promise<unknown>;
+    /** Creates a new, unconnected connection with the same configuration. */
+    duplicate(): Promise<RedisConnection>;
+    /** Establishes the connection. */
+    connect(): Promise<void>;
+    /** Closes the connection. */
+    close(): Promise<void> | void;
+}
+/**
+ * Creates the connection to a Redis server.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type RedisClientFactory = (url: string, options: Record<string, unknown>) => RedisConnection;

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+import { ElysiumError } from '@elysiumjs/core';
+/**
+ * Raised when a Redis connection cannot run a command, such as pub/sub over HTTP.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class RedisFeatureNotSupportedError extends ElysiumError {
+    constructor(adapter: string, feature: string);
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { type RedisClientFactory, type RedisConnection } from './connection';
+export { type RedisConnectionProps, type RedisModuleConfig, Redis, RedisModule } from './redis';
+export { bunRedis } from './adapters/bun';
+export { type IoredisLike, ioredis } from './adapters/ioredis';
+export { upstash, type UpstashOptions } from './adapters/upstash';
+export { RedisFeatureNotSupportedError } from './errors';
+export { RedisRateLimitStore } from './rate-limit';

package/dist/index.js

@@ -0,0 +1,2 @@
+// @bun
+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{Module,needsDefaultAlias,runAll,Service,ServiceNotFoundError}from"@elysiumjs/core";import{omit}from"radash";import{ElysiumError}from"@elysiumjs/core";class BunRedisConnection{#client;constructor(client){this.#client=client}get connected(){return this.#client.connected}set onconnect(handler){this.#client.onconnect=handler??null}set onclose(handler){this.#client.onclose=handler??null}send(command,args){return this.#client.send(command,args)}get(key){return this.#client.get(key)}set(key,value){return this.#client.set(key,value)}del(...keys){return this.#client.del(...keys)}expire(key,seconds){return this.#client.expire(key,seconds)}subscribe(channel,listener){return this.#client.subscribe(channel,listener)}unsubscribe(channel){return channel===void 0?this.#client.unsubscribe():this.#client.unsubscribe(channel)}async duplicate(){return new BunRedisConnection(await this.#client.duplicate())}connect(){return this.#client.connect()}close(){this.#client.close()}}var bunRedis=(url,options)=>{if(typeof Bun>"u")throw new ElysiumError("The default Redis client only runs on Bun: pass `client: ioredis(...)` on Node.js, or `client: upstash(...)` on Cloudflare Workers.");return new BunRedisConnection(new Bun.RedisClient(url,options))};var Redis;((Redis)=>(Redis.getConnectionName=(name)=>`redis.connection.${name}`,Redis.getConnection=(name="default")=>{let client=Service.get(Redis.getConnectionName(name));if(client===null)throw new ServiceNotFoundError(Redis.getConnectionName(name));return client},Redis.connectionExists=(name)=>Service.exists(Redis.getConnectionName(name)),Redis.getDefaultConnection=()=>Redis.getConnection("default")))(Redis||={});class RedisModule extends Module.configurable({defaults:{default:"default"},required:["connections"]}){async onDestroy(){let names=Object.keys(this.config.connections).map(Redis.getConnectionName);await runAll(names.filter((name)=>Service.isConstructed(name)).map((name)=>()=>Service.get(name)?.close()))}}RedisModule=__legacyDecorateClassTS([Module.register({services:(config)=>{let alias=needsDefaultAlias("RedisModule",config);return[...Object.entries(config.connections).map(([name,props])=>({name:Redis.getConnectionName(name),global:!0,factory:()=>(config.client??bunRedis)(props.url,omit(props,["url"]))})),...alias?[{name:Redis.getConnectionName("default"),global:!0,factory:(_config,get)=>get(Redis.getConnectionName(config.default))}]:[]]}})],RedisModule);class IoredisConnection{#client;#listeners=new Map;#onconnect;#onclose;constructor(client){this.#client=client,client.on("ready",()=>this.#onconnect?.()),client.on("end",()=>this.#onclose?.(void 0)),client.on("message",(channel,message)=>this.#listeners.get(channel)?.(message,channel))}get connected(){return this.#client.status==="ready"}set onconnect(handler){this.#onconnect=handler}set onclose(handler){this.#onclose=handler}send(command,args){return this.#client.call(command,...args)}get(key){return this.#client.get(key)}set(key,value){return this.#client.set(key,value)}del(...keys){return this.#client.del(...keys)}expire(key,seconds){return this.#client.expire(key,seconds)}async subscribe(channel,listener){return this.#listeners.set(channel,listener),this.#client.subscribe(channel)}async unsubscribe(channel){if(channel===void 0)return this.#listeners.clear(),this.#client.unsubscribe();return this.#listeners.delete(channel),this.#client.unsubscribe(channel)}async duplicate(){return new IoredisConnection(this.#client.duplicate())}async connect(){if(this.#client.status==="ready"||this.#client.status==="connecting")return;await this.#client.connect()}async close(){await this.#client.quit()}}var ioredis=(create)=>(url,options)=>new IoredisConnection(create(url,options));import{ElysiumError as ElysiumError3}from"@elysiumjs/core";import{ElysiumError as ElysiumError2}from"@elysiumjs/core";class RedisFeatureNotSupportedError extends ElysiumError2{constructor(adapter,feature){super(`The ${adapter} Redis connection does not support ${feature}.`)}}class UpstashConnection{#url;#token;#fetch;constructor(url,token,fetcher){this.#url=url.replace(/\/+$/,""),this.#token=token,this.#fetch=fetcher}connected=!0;onconnect;onclose;async send(command,args){let response=await this.#fetch(this.#url,{method:"POST",headers:{authorization:`Bearer ${this.#token}`,"content-type":"application/json"},body:JSON.stringify([command,...args])}),body=await response.json().catch(()=>({}));if(!response.ok||body.error!==void 0)throw new ElysiumError3(`Upstash answered ${response.status} to ${command}: ${body.error??"no error message"}`);return body.result??null}async get(key){return await this.send("GET",[key])}set(key,value){return this.send("SET",[key,value])}async del(...keys){return Number(await this.send("DEL",keys))}async expire(key,seconds){return Number(await this.send("EXPIRE",[key,String(seconds)]))}subscribe(){return Promise.reject(new RedisFeatureNotSupportedError("Upstash REST","pub/sub"))}unsubscribe(){return Promise.reject(new RedisFeatureNotSupportedError("Upstash REST","pub/sub"))}async duplicate(){return new UpstashConnection(this.#url,this.#token,this.#fetch)}async connect(){this.onconnect?.()}close(){this.onclose?.(void 0)}}var upstash=(options)=>(url)=>{let restUrl=options.url??url;if(!restUrl||!options.token)throw new ElysiumError3("The Upstash Redis connection needs a REST URL and a REST token. Set the connection URL (or the url option) and the token option.");return new UpstashConnection(restUrl,options.token,options.fetch??fetch)};class RedisRateLimitStore{#connection;#prefix;constructor(options={}){this.#connection=options.connection??"default",this.#prefix=options.prefix??""}async hit(key,windowMs){let redis=typeof this.#connection==="string"?Redis.getConnection(this.#connection):this.#connection,name=`${this.#prefix}${key}`,count=Number(await redis.send("INCR",[name]));if(count===1)await redis.send("PEXPIRE",[name,String(windowMs)]);let ttl=Number(await redis.send("PTTL",[name]));if(ttl<0)await redis.send("PEXPIRE",[name,String(windowMs)]),ttl=windowMs;return{count,resetAt:Date.now()+ttl}}}export{Redis,RedisFeatureNotSupportedError,RedisModule,RedisRateLimitStore,bunRedis,ioredis,upstash};

package/dist/rate-limit.d.ts

@@ -0,0 +1,26 @@
+import type { RateLimitStore } from '@elysiumjs/core';
+import type { RedisConnection } from './connection';
+/**
+ * Keeps rate limit counts in Redis, shared by every process of the app. A count is an `INCR`ed
+ * key that expires with its window.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @example
+ * ```ts
+ * @Application.register({ rateLimit: { store: new RedisRateLimitStore() } })
+ * ```
+ */
+export declare class RedisRateLimitStore implements RateLimitStore {
+    #private;
+    /**
+     * @param options The `RedisModule` connection (its name, `default` by default) or a connection,
+     * and a prefix for the keys.
+     */
+    constructor(options?: {
+        connection?: string | RedisConnection;
+        prefix?: string;
+    });
+    hit(key: string, windowMs: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+}

package/dist/redis.d.ts

@@ -0,0 +1,78 @@
+import type { RedisClientFactory, RedisConnection } from './connection';
+/**
+ * Properties used to create a new redis connection.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type RedisConnectionProps = {
+    url: string;
+} & Record<string, unknown>;
+/**
+ * Configuration of the {@link RedisModule}.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type RedisModuleConfig = {
+    /** The name of the connection that `default` resolves to. */
+    default: string;
+    /**
+     * Creates the client of a connection. Defaults to {@link bunRedis}; pass another factory
+     * to plug in any other Redis client.
+     */
+    client?: RedisClientFactory;
+    /** The connections to declare, by name. */
+    connections: Record<string, RedisConnectionProps>;
+};
+export declare namespace Redis {
+    /**
+     * Creates a service name for a redis connection.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param name The name of the connection.
+     * @returns A service name for the connection.
+     */
+    const getConnectionName: (name: string) => string;
+    /**
+     * Retrieves the client for a redis connection declared by the {@link RedisModule}.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param name The name of the connection.
+     * @returns The {@link RedisConnection} for the connection with the given name.
+     * @throws {ServiceNotFoundError} If no connection with that name is declared.
+     */
+    const getConnection: (name?: string) => RedisConnection;
+    /**
+     * Checks if a redis connection with the given name exists.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param name The name of the connection to check.
+     * @returns `true` if the connection exists, `false` otherwise.
+     */
+    const connectionExists: (name: string) => boolean;
+    /**
+     * Retrieves the default redis connection.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @returns The default redis connection.
+     */
+    const getDefaultConnection: () => RedisConnection;
+}
+declare const RedisModule_base: (abstract new () => {
+    readonly config: RedisModuleConfig;
+    onInit(): Promise<void> | void;
+    onDestroy(): Promise<void> | void;
+    onServe(_app: import("elysia").Elysia<any>): Promise<void> | void;
+}) & {
+    readonly config: string;
+    with(config: Partial<RedisModuleConfig> | (() => Partial<RedisModuleConfig> | Promise<Partial<RedisModuleConfig>>)): import("@elysiumjs/core").ConfiguredModule<RedisModuleConfig>;
+    resolveConfig(input?: Partial<RedisModuleConfig> | undefined): RedisModuleConfig;
+    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;
+};
+/**
+ * Declares redis connections as global services named `redis.connection.{name}`, plus
+ * `redis.connection.default` aliasing the configured default. Clients are created on first use.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class RedisModule extends RedisModule_base {
+    /** Closes the clients that were created. */
+    onDestroy(): Promise<void>;
+}
+export {};

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@elysiumjs/redis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "Apache-2.0",
+  "description": "Redis connections 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/redis"
+  },
+  "homepage": "https://github.com/na2axl/elysiumjs/tree/main/@elysiumjs/redis#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 bun --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"
+  },
+  "keywords": [
+    "elysium",
+    "framework",
+    "typescript",
+    "redis"
+  ],
+  "type": "module",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "@elysiumjs/core": "0.12.0"
+  },
+  "peerDependencies": {
+    "@elysiumjs/core": "^0.12.0"
+  },
+  "dependencies": {
+    "radash": "^12.1.1"
+  }
+}