@beignet/provider-redis 0.0.2 → 0.0.4

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @beignet/provider-redis
 
+## 0.0.4
+
+### Patch Changes
+
+- 8bcb31f: Mark package READMEs with Beignet's experimental alpha status and 0.0.x stability expectations.
+- d137044: Declare `@beignet/core` as a peer dependency with a lockstep version range in
+  every integration and provider package instead of a regular `"*"` dependency.
+  Installs now always resolve a single shared copy of core, so `instanceof`
+  checks such as `isContractError` and upload error identity keep working, and
+  mixed Beignet versions fail loudly at install time instead of at runtime.
+
+  If your package manager does not install peer dependencies automatically, add
+  `@beignet/core` to your app alongside these packages. `@beignet/nuqs` now also
+  declares `@beignet/react-query` as a peer dependency, and
+  `@beignet/provider-storage-s3` now expects you to install
+  `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner` yourself, matching
+  how other providers treat their SDKs.
+
+- 603478f: Align package documentation with the canonical route registry and AppContext conventions.
+- 1a79090: Emit Node-compatible ESM: all relative imports in published packages now carry explicit .js extensions, fixing ERR_MODULE_NOT_FOUND when running the CLI or importing package dist files under plain Node.
+- 44f1192: Move first-party provider diagnostics to package-owned `beignet.provider`
+  manifest metadata and have doctor read installed provider package manifests.
+- 2aa77ca: Add static provider metadata and provider wiring diagnostics for generated apps.
+- 89390fe: Add `createRedisProvider(options)` factory with connection robustness controls
+  and move the raw client escape hatch to a separate port.
+
+  - New config: `REDIS_CONNECT_TIMEOUT_MS` (default 5000),
+    `REDIS_MAX_RETRIES_PER_REQUEST` (default 2), and
+    `REDIS_CONNECT_MAX_ATTEMPTS` (default 3), with matching factory options
+    `connectTimeoutMs`, `maxRetriesPerRequest`, `retryStrategy`, and `db`.
+  - Startup now fails fast with a clear error when Redis is unreachable instead
+    of retrying forever. After a successful connection, reconnects use capped
+    exponential backoff (max 2s).
+  - The provider now contributes `{ cache: CachePort, redis: { client } }`.
+    `RedisCachePort` is replaced by the exported `RedisProviderPorts` interface;
+    access the raw ioredis client through `ctx.ports.redis.client` instead of
+    casting `ctx.ports.cache`.
+
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies [3160184]
+- Updated dependencies [254ef6d]
+- Updated dependencies [4cb1784]
+- Updated dependencies [8bd9085]
+  - @beignet/core@0.0.3
+
 ## 0.0.2
 
 ### Patch Changes

package/README.md

@@ -1,15 +1,19 @@
 # @beignet/provider-redis
 
+> [!CAUTION]
+> Beignet is experimental alpha software. The `0.0.x` package line is for early
+> evaluation, and APIs may change between releases while the framework settles.
+
 Redis-backed `CachePort` provider for Beignet applications.
 
 The provider installs `ctx.ports.cache` using
-[ioredis](https://github.com/redis/ioredis) and exposes the Redis client only
-as an escape hatch for Redis-specific features.
+[ioredis](https://github.com/redis/ioredis) and exposes the raw Redis client
+separately as `ctx.ports.redis` for Redis-specific features.
 
 ## Install
 
 ```bash
-bun add @beignet/provider-redis ioredis
+bun add @beignet/provider-redis @beignet/core ioredis
 ```
 
 ## Setup
@@ -29,7 +33,7 @@ const appPorts = definePorts({});
 export const server = await createNextServer({
   ports: appPorts,
   providers: [redisProvider],
-  createContext: ({ ports }) => ({
+  context: ({ ports }) => ({
     ports,
   }),
   routes,
@@ -42,7 +46,7 @@ Once the provider is registered, your ports will include a `cache` property:
 
 ```typescript
 // In your use case
-async function getUserProfile(ctx: AppCtx) {
+async function getUserProfile(ctx: AppContext) {
   const userId = ctx.actor.type === "user" ? ctx.actor.id : undefined;
   if (!userId) throw new Error("User actor required.");
 
@@ -76,6 +80,38 @@ The Redis provider reads configuration from environment variables with the `REDI
 |----------|----------|-------------|---------|
 | `REDIS_URL` | Yes | Redis connection URL | `redis://localhost:6379` |
 | `REDIS_DB` | No | Redis database number (default: 0) | `0` |
+| `REDIS_CONNECT_TIMEOUT_MS` | No | Initial connection timeout in milliseconds (default: 5000) | `2000` |
+| `REDIS_MAX_RETRIES_PER_REQUEST` | No | Per-command retry limit before the command rejects (default: 2) | `1` |
+| `REDIS_CONNECT_MAX_ATTEMPTS` | No | Connection attempts before startup fails (default: 3) | `5` |
+
+### Factory options
+
+Use `createRedisProvider(options)` when the app should own connection
+defaults. Matching `REDIS_*` environment variables still win when both are
+set:
+
+```typescript
+import { createRedisProvider } from "@beignet/provider-redis";
+
+const redisProvider = createRedisProvider({
+  connectTimeoutMs: 2000,
+  maxRetriesPerRequest: 1,
+  db: 1,
+  // Optional: replace the default retry strategy entirely.
+  retryStrategy: (times) => Math.min(times * 100, 1000),
+});
+```
+
+The default `redisProvider` export is `createRedisProvider()` with no options.
+
+### Connection behavior
+
+During startup the provider connects eagerly and fails fast: the initial
+`connect()` stops retrying after `REDIS_CONNECT_MAX_ATTEMPTS` attempts (or
+after `REDIS_CONNECT_TIMEOUT_MS` per attempt) and throws a clear error instead
+of hanging against an unreachable host. After a successful connection, lost
+connections are retried forever with capped exponential backoff (maximum 2
+seconds between attempts).
 
 ## Cache port API
 
@@ -130,16 +166,20 @@ const value = await ctx.ports.cache.remember(
 );
 ```
 
-### `client: Redis`
+## Escape hatch
 
-Access the underlying ioredis client for advanced operations.
+The provider also contributes `ctx.ports.redis` with the raw ioredis client
+for operations the stable cache port does not model:
 
 ```typescript
 // Use ioredis methods directly
-await ctx.ports.cache.client.expire("key", 300);
-await ctx.ports.cache.client.incr("counter");
+await ctx.ports.redis.client.expire("key", 300);
+await ctx.ports.redis.client.incr("counter");
 ```
 
+Use the stable `CachePort` for normal application behavior. Use the raw client
+only when the Redis-specific operation is intentional.
+
 ## Devtools
 
 When `@beignet/devtools` is installed before this provider, Redis cache
@@ -151,25 +191,26 @@ duration. Cached values are not recorded.
 
 ## TypeScript support
 
-To get proper type inference for the cache port, extend your ports type:
+To get proper type inference for the contributed ports, extend your ports
+type with `RedisProviderPorts`:
 
 ```typescript
-import type { RedisCachePort } from "@beignet/provider-redis";
+import type { RedisProviderPorts } from "@beignet/provider-redis";
 
 // Your base ports, if any
 const basePorts = definePorts({});
 
 // After using redisProvider, your ports will have this shape:
-type AppPorts = typeof basePorts & {
-  cache: RedisCachePort;
-};
+type AppPorts = typeof basePorts & RedisProviderPorts;
+// { cache: CachePort; redis: { client: Redis } }
 ```
 
 ## Lifecycle
 
 The Redis provider:
 
-1. **During `setup`**: Connects to Redis and returns the `cache` port
+1. **During `setup`**: Connects to Redis and returns the `cache` and `redis`
+   ports
 2. **During `stop`**: Gracefully closes the Redis connection
 
 ## Error handling
@@ -177,7 +218,8 @@ The Redis provider:
 The provider will throw errors in these cases:
 
 - Missing `REDIS_URL` environment variable
-- Failed connection to Redis server
+- Failed connection to Redis server after `REDIS_CONNECT_MAX_ATTEMPTS`
+  attempts
 
 Make sure to handle these during application startup.
 

package/dist/index.d.ts

@@ -6,6 +6,9 @@
  * Configuration:
  * - REDIS_URL: Redis connection URL (required)
  * - REDIS_DB: Redis database number (optional, default: 0)
+ * - REDIS_CONNECT_TIMEOUT_MS: Initial connection timeout in milliseconds (optional, default: 5000)
+ * - REDIS_MAX_RETRIES_PER_REQUEST: Per-command retry limit (optional, default: 2)
+ * - REDIS_CONNECT_MAX_ATTEMPTS: Connection attempts before startup fails (optional, default: 3)
  *
  * @example
  * ```ts
@@ -29,7 +32,7 @@
  * ```
  */
 import type { CachePort } from "@beignet/core/ports";
-import Redis from "ioredis";
+import { Redis } from "ioredis";
 import { z } from "zod";
 /**
  * Configuration schema for the Redis provider.
@@ -37,29 +40,102 @@ import { z } from "zod";
  */
 declare const RedisConfigSchema: z.ZodObject<{
     URL: z.ZodString;
-    DB: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    DB: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>>;
+    CONNECT_TIMEOUT_MS: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>>;
+    MAX_RETRIES_PER_REQUEST: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>>;
+    CONNECT_MAX_ATTEMPTS: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>>;
 }, z.core.$strip>;
 /**
  * Inferred configuration type for Redis provider.
  */
 export type RedisConfig = z.infer<typeof RedisConfigSchema>;
 /**
- * Extended cache port interface that includes the Redis client.
- * The Redis provider adds the underlying client for advanced operations.
+ * Options for {@link createRedisProvider}.
+ *
+ * Numeric options become schema defaults, so matching `REDIS_*` environment
+ * variables still win when both are set.
+ */
+export interface RedisProviderOptions {
+    /**
+     * Timeout for the initial connection attempt, in milliseconds.
+     *
+     * @default 5000
+     */
+    connectTimeoutMs?: number;
+    /**
+     * How many times a single command is retried before its promise rejects.
+     *
+     * @default 2
+     */
+    maxRetriesPerRequest?: number;
+    /**
+     * Custom ioredis retry strategy. Replaces the default strategy, which stops
+     * retrying after `REDIS_CONNECT_MAX_ATTEMPTS` during the initial connect and
+     * reconnects with capped exponential backoff afterwards.
+     */
+    retryStrategy?: (times: number) => number | null;
+    /**
+     * Redis database number.
+     *
+     * @default 0
+     */
+    db?: number;
+}
+/**
+ * Escape hatch for apps that need the raw ioredis client.
  */
-export interface RedisCachePort extends CachePort {
+export interface RedisEscapeHatch {
     /**
-     * The underlying Redis client instance.
-     * Use this for advanced operations not covered by the cache interface.
+     * Raw ioredis client.
+     * Use this for Redis operations the stable cache port does not model.
      */
     client: Redis;
 }
 /**
- * Redis provider that extends ports with cache capabilities.
+ * Ports contributed by the Redis provider.
+ */
+export interface RedisProviderPorts {
+    /**
+     * Beignet cache port backed by Redis.
+     */
+    cache: CachePort;
+    /**
+     * Raw ioredis client escape hatch.
+     */
+    redis: RedisEscapeHatch;
+}
+/**
+ * Create an env-backed Redis cache provider.
+ *
+ * Reads `REDIS_*` env vars, contributes `ports.cache`, and exposes
+ * `ports.redis` for raw ioredis client access.
+ *
+ * @example
+ * ```ts
+ * const provider = createRedisProvider({ connectTimeoutMs: 2000 });
+ * ```
+ */
+export declare function createRedisProvider(options?: RedisProviderOptions): import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
+    URL: z.ZodString;
+    CONNECT_MAX_ATTEMPTS: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>>;
+    DB: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>> | z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>>;
+    CONNECT_TIMEOUT_MS: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>>;
+    MAX_RETRIES_PER_REQUEST: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>>;
+}, z.core.$strip>, {
+    cache: CachePort;
+    redis: {
+        client: Redis;
+    };
+}, unknown, void>;
+/**
+ * Default env-backed Redis provider.
  *
  * Configuration via environment variables:
  * - REDIS_URL: Redis connection URL (required)
  * - REDIS_DB: Redis database number (optional)
+ * - REDIS_CONNECT_TIMEOUT_MS: Initial connection timeout in ms (optional)
+ * - REDIS_MAX_RETRIES_PER_REQUEST: Per-command retry limit (optional)
+ * - REDIS_CONNECT_MAX_ATTEMPTS: Connection attempts before startup fails (optional)
  *
  * @example
  * ```ts
@@ -72,9 +148,15 @@ export interface RedisCachePort extends CachePort {
  */
 export declare const redisProvider: import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
     URL: z.ZodString;
-    DB: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    CONNECT_MAX_ATTEMPTS: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>>;
+    DB: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>> | z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>>;
+    CONNECT_TIMEOUT_MS: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>>;
+    MAX_RETRIES_PER_REQUEST: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>>;
 }, z.core.$strip>, {
-    cache: RedisCachePort;
-}>;
+    cache: CachePort;
+    redis: {
+        client: Redis;
+    };
+}, unknown, void>;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAKrD,OAAO,KAAK,MAAM,SAAS,CAAC;AAC5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,QAAA,MAAM,iBAAiB;;;iBAYrB,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C;;;OAGG;IACH,MAAM,EAAE,KAAK,CAAC;CACf;AAMD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa;;;;;EAmPxB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAKrD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB;;;GAGG;AACH,QAAA,MAAM,iBAAiB;;;;;;iBAgCrB,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAEjD;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,MAAM,EAAE,KAAK,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB;;OAEG;IACH,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB;;;;;;;;;;;kBAoSrE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;iBAAwB,CAAC"}