effect-redis 0.0.2 → 0.0.4

package/README.md

@@ -1,15 +1,180 @@
-# effect-redis
-
-To install dependencies:
-
-```bash
-bun install
-```
-
-To run:
-
-```bash
-bun run index.ts
-```
-
-This project was created using `bun init` in bun v1.2.14. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
+# Effect-Redis
+
+A lightweight wrapper around the official `redis` client that integrates seamlessly with the [Effect](https://github.com/Effect-TS/effect) ecosystem.
+
+*   Resource–safe connections (acquire / release handled for you)
+*   _Layers_ for dependency-injection
+*   Tagged error type (`RedisError`) with rich cause information
+*   Declarative, interrupt-safe `publish` / `subscribe` / `setValue` helpers
+*   Tiny surface — bring your own redis commands via the `Redis` service when you need full power
+
+---
+
+## Installation
+
+```bash
+pnpm add effect-redis redis @effect/data @effect/io
+```
+
+> The library itself is runtime-agnostic. Under Bun you will usually also have `@effect/platform-bun` around — that is **not** required by `effect-redis`.
+
+---
+
+## Quick-start
+
+```ts
+import { Effect, Layer } from "effect";
+import {
+  RedisConnectionOptionsLive,
+  RedisPubSubLive,
+  RedisPersistenceLive,
+  RedisPubSub,
+  RedisPersistence,
+} from "effect-redis";
+
+const redisLayer = RedisConnectionOptionsLive({
+  url: "redis://localhost:6379",
+}).pipe(Layer.provideMerge(RedisPubSubLive), Layer.provideMerge(RedisPersistenceLive));
+
+const program = Effect.gen(function* () {
+  /* services */
+  const pubsub  = yield* RedisPubSub;
+  const storage = yield* RedisPersistence;
+
+  /* persistence */
+  yield* storage.setValue("user:42", JSON.stringify({ name: "Ada" }));
+
+  /* pub / sub */
+  yield* pubsub.subscribe("notifications", (msg) => {
+    console.log("🔔", msg);
+  });
+
+  yield* pubsub.publish("notifications", "Hello world!");
+});
+
+Effect.runPromise(program.pipe(Effect.provide(redisLayer)));
+```
+
+---
+
+## Provided Layers & Services
+
+| Layer                                    | Service                | What you get                                  |
+| ---------------------------------------- | ---------------------- | --------------------------------------------- |
+| `RedisConnectionOptionsLive(options?)`   | —                      | Supplies connection settings downstream       |
+| `RedisLive`                              | `Redis`                | Raw access to an already connected client     |
+| `RedisPubSubLive`                        | `RedisPubSub`          | `publish / subscribe` helpers                 |
+| `RedisPersistenceLive`                   | `RedisPersistence`     | Simple `setValue` helper                      |
+
+All Layers are *scoped* — the underlying connection is opened once and **closed automatically** when the scope ends.
+
+### Error model
+
+Every operation can fail with **`RedisError`** — a tagged error enriched with the original cause:
+
+```ts
+import { Effect } from "effect";
+import { RedisPersistence, RedisError } from "effect-redis";
+
+const safe = RedisPersistence.pipe(
+  Effect.flatMap(({ setValue }) => setValue("x", "y")),
+  Effect.catchTag("RedisError", (e: RedisError) => Effect.logError(e.message))
+);
+```
+
+---
+
+## Usage patterns
+
+### 1. Pub / Sub micro-service
+
+Extracted from the repo’s own `winfut.ts` example:
+
+```ts
+import { BunRuntime } from "@effect/platform-bun";
+import { Effect, Queue, Stream, pipe } from "effect";
+import { RedisConnectionOptionsLive, RedisPubSubLive, RedisPubSub } from "effect-redis";
+
+const program = Effect.gen(function* () {
+  const q   = yield* Queue.unbounded<string>();
+  const rps = yield* RedisPubSub;
+
+  /* subscribe */
+  yield* rps.subscribe("raw", (msg) => Queue.unsafeOffer(q, msg));
+
+  /* process stream */
+  yield* pipe(
+    Stream.fromQueue(q),
+    Stream.filter((m) => m.startsWith("T:WIN")),
+    Stream.tap((m) => rps.publish("winfut", m)),
+    Stream.runDrain
+  );
+});
+
+BunRuntime.runMain(
+  Effect.provide(
+    program,
+    Layer.provide(RedisPubSubLive, RedisConnectionOptionsLive({ url: "redis://localhost:6379" }))
+  )
+);
+```
+
+### 2. Metrics aggregation
+
+See `metrics.ts` for the full blown version, the gist is:
+
+```ts
+const metricsProg = Effect.gen(function* () {
+  const rps = yield* RedisPubSub;
+  yield* rps.subscribe("winfut", handleTick);
+  // … aggregate & publish …
+});
+```
+
+### 3. Low-level commands via `Redis`
+
+The thin `Redis` service gives you the connected **node-redis client** when you need functions not wrapped by this lib:
+
+```ts
+import { Redis } from "effect-redis";
+
+const incrProg = Redis.pipe(
+  Effect.flatMap(({ use }) =>
+    use((client) => client.incr("counter"))
+  )
+);
+```
+
+---
+
+## Reference
+
+### `RedisConnectionOptionsLive(options?) → Layer`
+Creates a live Layer that exposes `RedisConnectionOptions` downstream. The `options` object is forwarded to `createClient(options)` from `redis`.
+
+### `RedisPubSub` service
+```ts
+publish(channel: string, message: string): Effect<void, RedisError>
+subscribe(channel: string, handler: (msg: string) => void): Effect<void, RedisError>
+```
+
+### `RedisPersistence` service
+```ts
+setValue(key: string, value: string): Effect<void, RedisError>
+```
+
+### `Redis` service
+```ts
+use<T>(fn: (client: RedisClient) => T | Promise<T>): Effect<T, RedisError>
+```
+Gives access to the raw `RedisClient` from `redis`. The connection is shared and stays open for the whole scope.
+
+---
+
+## Contributing / TODO
+
+*   Expose more common redis commands (get, del, etc.)
+*   Connection pooling?
+*   Add tests against `redis-mock`
+
+PRs welcome!

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "effect-redis",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Simple Effect wrapper for Redis.",
   "module": "dist/index.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
-  "files": ["dist", "README.md"],
+  "files": ["dist", "src", "README.md"],
   "scripts": {
     "build:main": "bun build --minify-syntax --minify-whitespace ./src/index.ts --outdir ./dist --target node --format esm",
     "build:types": "bun tsc --emitDeclarationOnly --outDir dist",

package/src/index.ts

@@ -0,0 +1 @@
+export * from './redis';

package/src/redis.ts

@@ -0,0 +1,190 @@
+import { Context, Data, Effect, Layer } from 'effect';
+import { createClient } from 'redis';
+
+export class RedisError extends Data.TaggedError('RedisError')<{
+  cause: unknown;
+  message: string;
+}> {}
+
+interface RedisConnectionOptionsShape {
+  options?: Parameters<typeof createClient>[0];
+}
+class RedisConnectionOptions extends Context.Tag('RedisConnectionOptions')<
+  RedisConnectionOptions,
+  RedisConnectionOptionsShape
+>() {}
+
+const RedisConnectionOptionsLive = (
+  options?: Parameters<typeof createClient>[0],
+) =>
+  Layer.succeed(
+    RedisConnectionOptions,
+    RedisConnectionOptions.of({
+      options,
+    }),
+  );
+
+interface RedisShape {
+  use: <T>(
+    fn: (client: ReturnType<typeof createClient>) => T,
+  ) => Effect.Effect<Awaited<T>, RedisError, never>;
+}
+class Redis extends Context.Tag('Redis')<Redis, RedisShape>() {}
+
+const bootstrapRedisEffect = Effect.gen(function* () {
+  const client = yield* redisClientEffect;
+  return Redis.of({
+    use: (fn) =>
+      Effect.gen(function* () {
+        const result = yield* Effect.try({
+          try: () => fn(client),
+          catch: (e) =>
+            new RedisError({
+              cause: e,
+              message: 'Synchronous error in `Redis.use`',
+            }),
+        });
+        if (result instanceof Promise) {
+          return yield* Effect.tryPromise({
+            try: () => result,
+            catch: (e) =>
+              new RedisError({
+                cause: e,
+                message: 'Asynchronous error in `Redis.use`',
+              }),
+          });
+        }
+        return result;
+      }),
+  });
+});
+
+const RedisLive = Layer.scoped(Redis, bootstrapRedisEffect);
+
+interface RedisPubSubShape {
+  publish: (
+    channel: string,
+    message: string,
+  ) => Effect.Effect<void, RedisError, never>;
+  subscribe: (
+    channel: string,
+    handler: (message: string) => void,
+  ) => Effect.Effect<void, RedisError, never>;
+}
+
+class RedisPubSub extends Context.Tag('RedisPubSub')<
+  RedisPubSub,
+  RedisPubSubShape
+>() {}
+
+interface RedisPersistenceShape {
+  setValue: (
+    key: string,
+    value: string,
+  ) => Effect.Effect<void, RedisError, never>;
+}
+
+class RedisPersistence extends Context.Tag('RedisPersistence')<
+  RedisPersistence,
+  RedisPersistenceShape
+>() {}
+
+const redisClientEffect = Effect.gen(function* () {
+  const { options } = yield* RedisConnectionOptions;
+
+  return yield* Effect.acquireRelease(
+    Effect.tryPromise({
+      try: () =>
+        createClient(options)
+          .connect()
+          .then((r) => {
+            console.log('Connected to Redis');
+            r.on('error', (e) => {
+              console.log('Redis error(on error):', e.message);
+              r.destroy();
+            });
+            r.on('end', () => {
+              console.log('Connection to Redis ended');
+            });
+            return r;
+          }),
+      catch: (e) =>
+        new RedisError({
+          cause: e,
+          message: 'Error while connecting to Redis',
+        }),
+    }),
+    (client) =>
+      Effect.sync(() => {
+        if (client.isReady) {
+          client.quit();
+        }
+      }),
+  );
+});
+
+const bootstrapRedisPersistenceEffect = Effect.gen(function* () {
+  const client = yield* redisClientEffect;
+
+  return RedisPersistence.of({
+    setValue: (key, value) =>
+      Effect.gen(function* () {
+        return yield* Effect.tryPromise({
+          try: () => client.set(key, value),
+          catch: (e) =>
+            new RedisError({
+              cause: e,
+              message: 'Error in `Redis.setValue`',
+            }),
+        });
+      }),
+  });
+});
+
+const RedisPersistenceLive = Layer.scoped(
+  RedisPersistence,
+  bootstrapRedisPersistenceEffect,
+);
+
+const bootstrapRedisPubSubEffect = Effect.gen(function* () {
+  const clientPublish = yield* redisClientEffect;
+  const clientSubscribe = yield* redisClientEffect;
+
+  return RedisPubSub.of({
+    publish: (channel, message) =>
+      Effect.gen(function* () {
+        return yield* Effect.tryPromise({
+          try: () => clientPublish.publish(channel, message),
+          catch: (e) =>
+            new RedisError({
+              cause: e,
+              message: 'Error in `Redis.publish`',
+            }),
+        });
+      }),
+    subscribe: (channel, handler) =>
+      Effect.gen(function* () {
+        return yield* Effect.tryPromise({
+          try: () => clientSubscribe.subscribe(channel, handler),
+          catch: (e) =>
+            new RedisError({
+              cause: e,
+              message: 'Error in `Redis.subscribe`',
+            }),
+        });
+      }),
+  });
+});
+
+const RedisPubSubLive = Layer.scoped(RedisPubSub, bootstrapRedisPubSubEffect);
+
+export {
+  RedisPersistence,
+  RedisPubSub,
+  RedisConnectionOptions,
+  Redis,
+  RedisPersistenceLive,
+  RedisPubSubLive,
+  RedisConnectionOptionsLive,
+  RedisLive,
+};