@b9g/cache-redis 0.1.0

package/README.md

@@ -0,0 +1,195 @@
+# @b9g/cache-redis
+
+Redis cache adapter for Shovel's universal cache system.
+
+## Features
+
+- **HTTP-aware caching**: Stores complete HTTP responses with headers and status codes
+- **TTL support**: Configurable time-to-live for cache entries
+- **Size limits**: Configurable maximum entry size to prevent memory issues
+- **Connection pooling**: Uses the official Redis client with connection management
+- **Error resilience**: Graceful handling of Redis connection issues
+
+## Installation
+
+```bash
+bun install @b9g/cache-redis
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import {CustomCacheStorage} from "@b9g/cache";
+import {createRedisFactory} from "@b9g/cache-redis";
+
+// Create cache storage with Redis backend
+const cacheStorage = new CustomCacheStorage(createRedisFactory({
+  redis: {
+    url: "redis://localhost:6379"
+  },
+  defaultTTL: 3600, // 1 hour
+  prefix: "myapp"
+}));
+
+// Use the cache
+const cache = await cacheStorage.open("pages");
+await cache.put(request, response);
+const cached = await cache.match(request);
+```
+
+### With Platform Integration
+
+```typescript
+import {CustomCacheStorage} from "@b9g/cache";
+import {createRedisFactory} from "@b9g/cache-redis";
+
+// In your platform configuration
+const platform = createBunPlatform({
+  cache: {
+    factory: createRedisFactory({
+      redis: {
+        url: process.env.REDIS_URL || "redis://localhost:6379",
+        password: process.env.REDIS_PASSWORD
+      },
+      defaultTTL: 3600,
+      maxEntrySize: 5 * 1024 * 1024 // 5MB max per entry
+    })
+  }
+});
+```
+
+## Configuration Options
+
+### RedisCacheOptions
+
+- `redis?: RedisClientOptions` - Redis connection configuration
+- `prefix?: string` - Key prefix for Redis keys (default: "cache")
+- `defaultTTL?: number` - Default TTL in seconds (0 = no expiration)
+- `maxEntrySize?: number` - Maximum cache entry size in bytes (default: 10MB)
+
+### Redis Connection Options
+
+The `redis` option accepts all standard Redis client options:
+
+```typescript
+{
+  redis: {
+    url: "redis://localhost:6379",
+    password: "your-password",
+    database: 0,
+    connectTimeout: 10000,
+    lazyConnect: true
+  }
+}
+```
+
+## Environment Variables
+
+Common Redis configuration via environment variables:
+
+- `REDIS_URL` - Complete Redis connection URL
+- `REDIS_HOST` - Redis hostname
+- `REDIS_PORT` - Redis port
+- `REDIS_PASSWORD` - Redis password
+- `REDIS_DB` - Redis database number
+
+## Performance Considerations
+
+### Entry Size Limits
+
+Large responses are automatically rejected to prevent memory issues:
+
+```typescript
+const cache = new RedisCache("large-files", {
+  maxEntrySize: 1024 * 1024 // 1MB limit
+});
+```
+
+### TTL Configuration
+
+Configure TTL based on your caching strategy:
+
+```typescript
+// Short-lived API responses
+const apiCache = new RedisCache("api", {
+  defaultTTL: 300 // 5 minutes
+});
+
+// Long-lived static assets
+const staticCache = new RedisCache("static", {
+  defaultTTL: 86400 // 24 hours
+});
+
+// Permanent cache (manual invalidation)
+const permanentCache = new RedisCache("permanent", {
+  defaultTTL: 0 // No expiration
+});
+```
+
+### Connection Pooling
+
+The Redis client automatically manages connection pooling. For high-traffic applications, consider tuning connection settings:
+
+```typescript
+{
+  redis: {
+    socket: {
+      connectTimeout: 10000,
+      keepAlive: true,
+      noDelay: true
+    },
+    isolationPoolOptions: {
+      min: 2,
+      max: 10
+    }
+  }
+}
+```
+
+## Error Handling
+
+The Redis cache gracefully handles connection issues:
+
+- Failed connections return `undefined` for cache misses
+- Connection errors are logged but don't crash the application
+- Automatic reconnection when Redis becomes available
+
+## Cache Statistics
+
+Get insights into cache performance:
+
+```typescript
+const cache = new RedisCache("my-cache");
+const stats = await cache.getStats();
+
+console.log({
+  connected: stats.connected,
+  keyCount: stats.keyCount,
+  totalSize: stats.totalSize,
+  prefix: stats.prefix
+});
+```
+
+## Cleanup
+
+Properly dispose of cache instances:
+
+```typescript
+// Dispose single cache
+await cache.dispose();
+
+// Dispose entire cache storage
+await cacheStorage.dispose();
+```
+
+## Shovel Integration
+
+This cache adapter is designed to work seamlessly with Shovel's cache-first architecture:
+
+- **Platform agnostic**: Works with any Shovel platform (Bun, Node.js, Cloudflare)
+- **HTTP-aware**: Preserves response headers and status codes
+- **ServiceWorker compatible**: Implements the standard Cache API interface
+
+For more information about Shovel's caching system, see the [@b9g/cache](../cache) documentation.

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@b9g/cache-redis",
+  "version": "0.1.0",
+  "description": "Redis cache adapter for Shovel cache system",
+  "keywords": [
+    "cache",
+    "redis",
+    "shovel",
+    "metaframework",
+    "cache-adapter"
+  ],
+  "author": "Shovel Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/b9g/shovel.git",
+    "directory": "packages/cache-redis"
+  },
+  "dependencies": {
+    "redis": "^4.6.10"
+  },
+  "devDependencies": {
+    "@b9g/libuild": "^0.1.10"
+  },
+  "peerDependencies": {
+    "@b9g/cache": "workspace:*"
+  },
+  "type": "module",
+  "types": "src/index.d.ts",
+  "files": [
+    "README.md",
+    "src/"
+  ],
+  "main": "src/index.cjs",
+  "module": "src/index.js",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./src/index.cjs"
+    },
+    "./factory": {
+      "types": "./src/factory.d.ts",
+      "import": "./src/factory.js",
+      "require": "./src/factory.cjs"
+    },
+    "./factory.js": {
+      "types": "./src/factory.d.ts",
+      "import": "./src/factory.js",
+      "require": "./src/factory.cjs"
+    },
+    "./index": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./src/index.cjs"
+    },
+    "./index.js": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./src/index.cjs"
+    },
+    "./redis-cache": {
+      "types": "./src/redis-cache.d.ts",
+      "import": "./src/redis-cache.js",
+      "require": "./src/redis-cache.cjs"
+    },
+    "./redis-cache.js": {
+      "types": "./src/redis-cache.d.ts",
+      "import": "./src/redis-cache.js",
+      "require": "./src/redis-cache.cjs"
+    },
+    "./package.json": "./package.json"
+  }
+}

package/src/factory.cjs

@@ -0,0 +1,34 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/factory.ts
+var factory_exports = {};
+__export(factory_exports, {
+  createRedisFactory: () => createRedisFactory
+});
+module.exports = __toCommonJS(factory_exports);
+var import_redis_cache = require("./redis-cache.cjs");
+function createRedisFactory(options = {}) {
+  return (name) => {
+    return new import_redis_cache.RedisCache(name, options);
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createRedisFactory
+});

package/src/factory.d.ts

@@ -0,0 +1,19 @@
+import { type CacheFactory } from "@b9g/cache";
+import { type RedisCacheOptions } from "./redis-cache.js";
+/**
+ * Create a Redis cache factory for use with CustomCacheStorage
+ *
+ * Example usage:
+ * ```typescript
+ * import {CustomCacheStorage} from "@b9g/cache";
+ * import {createRedisFactory} from "@b9g/cache-redis";
+ *
+ * const cacheStorage = new CustomCacheStorage(createRedisFactory({
+ *   redis: { url: "redis://localhost:6379" },
+ *   defaultTTL: 3600 // 1 hour
+ * }));
+ *
+ * const cache = await cacheStorage.open("my-cache");
+ * ```
+ */
+export declare function createRedisFactory(options?: RedisCacheOptions): CacheFactory;

package/src/factory.js

@@ -0,0 +1,11 @@
+/// <reference types="./factory.d.ts" />
+// src/factory.ts
+import { RedisCache } from "./redis-cache.js";
+function createRedisFactory(options = {}) {
+  return (name) => {
+    return new RedisCache(name, options);
+  };
+}
+export {
+  createRedisFactory
+};

package/src/index.cjs

@@ -0,0 +1,32 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  RedisCache: () => import_redis_cache.RedisCache,
+  createRedisFactory: () => import_factory.createRedisFactory
+});
+module.exports = __toCommonJS(src_exports);
+var import_redis_cache = require("./redis-cache.cjs");
+var import_factory = require("./factory.cjs");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RedisCache,
+  createRedisFactory
+});

package/src/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @b9g/cache-redis - Redis cache adapter for Shovel
+ *
+ * Provides Redis-backed caching with HTTP-aware storage and retrieval
+ */
+export { RedisCache, type RedisCacheOptions } from "./redis-cache.js";
+export { createRedisFactory } from "./factory.js";

package/src/index.js

@@ -0,0 +1,8 @@
+/// <reference types="./index.d.ts" />
+// src/index.ts
+import { RedisCache } from "./redis-cache.js";
+import { createRedisFactory } from "./factory.js";
+export {
+  RedisCache,
+  createRedisFactory
+};