effect-distributed-lock 0.0.1 → 0.0.3

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Ethan Niser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -1,15 +1,157 @@
 # effect-distributed-lock
 
-To install dependencies:
+*WARNING: This is still in active development, likely has bugs and is subject to change.*
+
+A distributed mutex library for [Effect](https://effect.website/) with pluggable backends.
+
+## Features
+
+- **Scope-based resource management** — locks are automatically released when the scope closes
+- **Automatic TTL refresh** — keeps locks alive while held, prevents deadlocks if holder crashes
+- **Pluggable backends** — ships with Redis, easy to implement others (etcd, DynamoDB, etc.)
+- **Configurable retry policies** — control polling interval, TTL, and backing failure retry behavior
+- **Type-safe errors** — tagged errors for precise error handling
+
+## Installation
 
 ```bash
-bun install
+npm install effect-distributed-lock effect
+# or
+bun add effect-distributed-lock effect
+
+# For Redis backing (optional)
+npm install ioredis
 ```
 
-To run:
+## Quick Start
 
-```bash
-bun run index.ts
+```typescript
+import { Effect } from "effect";
+import Redis from "ioredis";
+import { DistributedMutex, RedisBacking } from "effect-distributed-lock";
+
+const redis = new Redis(process.env.REDIS_URL);
+const RedisLayer = RedisBacking.layer(redis);
+
+const program = Effect.gen(function* () {
+  const mutex = yield* DistributedMutex.make("my-resource", {
+    ttl: "10 seconds",
+    refreshInterval: "3 seconds",
+    acquireRetryInterval: "500 millis",
+    backingFailureRetryPolicy: Schedule.exponential("100 millis")),
+  });
+
+  // Lock is held while effect runs, released automatically after
+  yield* mutex.withLock(doExclusiveWork);
+});
+
+program.pipe(Effect.provide(RedisLayer), Effect.runPromise);
 ```
 
-This project was created using `bun init` in bun v1.2.12. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
+## API
+
+### Creating a Mutex
+
+```typescript
+const mutex = yield* DistributedMutex.make(key, config);
+```
+
+| Config Option          | Type               | Default      | Description                                         |
+| ---------------------- | ------------------ | ------------ | --------------------------------------------------- |
+| `ttl`                  | `DurationInput`    | `30 seconds` | Lock TTL (auto-releases if holder crashes)          |
+| `refreshInterval`      | `DurationInput`    | `ttl / 3`    | How often to refresh TTL while holding              |
+| `acquireRetryInterval` | `DurationInput`    | `100ms`      | Polling interval when waiting to acquire            |
+| `backingFailureRetryPolicy`   | `Schedule<void>`   | `100ms`      | Retry schedule for backing store failures           |
+
+### Using the Mutex
+
+#### `withLock` — Acquire, run, release
+
+The simplest and recommended way. Acquires the lock (waiting indefinitely if needed), runs your effect, and releases when done:
+
+```typescript
+yield* mutex.withLock(myEffect);
+```
+
+#### `withLockIfAvailable` — Non-blocking acquire
+
+Tries to acquire immediately without waiting. Returns `Option.some(result)` if successful, `Option.none()` if lock is held:
+
+```typescript
+const result = yield* mutex.withLockIfAvailable(myEffect);
+if (Option.isSome(result)) {
+  console.log("Got the lock!", result.value);
+} else {
+  console.log("Lock was busy, skipping");
+}
+```
+
+#### `acquire` / `tryAcquire` — Manual scope control
+
+For advanced use cases where you need explicit control over the lock lifecycle:
+
+```typescript
+yield* Effect.scoped(
+  Effect.gen(function* () {
+    const keepAliveFiber = yield* mutex.acquire; // Lock held until scope closes
+    yield* doWork;
+    // Lock automatically released + keepalive fiber interrupted here
+  })
+);
+```
+
+Both `acquire` and `tryAcquire` return the keepalive fiber that refreshes the lock TTL. Errors related to the keep alive (losing the lock or backing store failure) are propagated to the fiber.
+
+#### `isLocked` — Check lock status
+
+```typescript
+const locked = yield* mutex.isLocked;
+```
+
+## Error Handling
+
+All errors are tagged for precise handling with `Effect.catchTag`:
+
+```typescript
+yield* mutex.withLock(myEffect).pipe(
+  Effect.catchTag("LockLostError", (e) =>
+    Effect.log(`Lock was lost while held: ${e.key}`)
+  ),
+  Effect.catchTag("MutexBackingError", (e) =>
+    Effect.log(`Redis error: ${e.message}`)
+  )
+);
+```
+
+| Error               | Description                                          |
+| ------------------- | ---------------------------------------------------- |
+| `LockLostError`     | Lock TTL expired while we thought we held it         |
+| `MutexBackingError` | Error from the backing store (Redis connection, etc) |
+
+## Custom Backends
+
+Implement the `DistributedMutexBacking` interface to use a different store:
+
+```typescript
+import { Duration, Layer } from "effect";
+import { DistributedMutex } from "effect-distributed-lock";
+
+const MyCustomBacking = Layer.succeed(DistributedMutex.DistributedMutexBacking, {
+  tryAcquire: (key, holderId, ttl: Duration.Duration) => /* ... */,
+  release: (key, holderId) => /* ... */,
+  refresh: (key, holderId, ttl: Duration.Duration) => /* ... */,
+  isLocked: (key) => /* ... */,
+  getHolder: (key) => /* ... */,
+});
+```
+
+## How It Works
+
+1. **Acquire**: Atomically sets the lock key if not exists (Redis: `SET key value NX PX ttl`)
+2. **Keepalive**: A background fiber refreshes the TTL periodically while the lock is held
+3. **Release**: Atomically deletes the key only if we're still the holder (Lua script for atomicity)
+4. **Crash safety**: If the holder crashes, the TTL expires and another process can acquire
+
+## License
+
+MIT

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "effect-distributed-lock",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "A distributed mutex library for Effect with pluggable backends",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ethanniser/effect-distributed-lock.git"
+  },
+  "homepage": "https://github.com/ethanniser/effect-distributed-lock",
+  "bugs": {
+    "url": "https://github.com/ethanniser/effect-distributed-lock/issues"
+  },
   "type": "module",
   "scripts": {
     "build": "tsc",

package/src/DistributedMutex.ts

@@ -1,7 +1,14 @@
-import { Context, Duration, Effect, Option, Schedule, Scope } from "effect";
 import {
-  AcquireTimeoutError,
-  BackingError,
+  Context,
+  Duration,
+  Effect,
+  Fiber,
+  Option,
+  Schedule,
+  Scope,
+} from "effect";
+import {
+  MutexBackingError,
   LockLostError,
   NotYetAcquiredError,
 } from "./Errors.js";
@@ -22,8 +29,8 @@ export interface DistributedMutexBacking {
   readonly tryAcquire: (
     key: string,
     holderId: string,
-    ttlMs: number
-  ) => Effect.Effect<boolean, BackingError>;
+    ttl: Duration.Duration
+  ) => Effect.Effect<boolean, MutexBackingError>;
 
   /**
    * Release the lock. Only succeeds if we are the current holder.
@@ -32,7 +39,7 @@ export interface DistributedMutexBacking {
   readonly release: (
     key: string,
     holderId: string
-  ) => Effect.Effect<boolean, BackingError>;
+  ) => Effect.Effect<boolean, MutexBackingError>;
 
   /**
    * Refresh the TTL on a lock we hold.
@@ -41,20 +48,20 @@ export interface DistributedMutexBacking {
   readonly refresh: (
     key: string,
     holderId: string,
-    ttlMs: number
-  ) => Effect.Effect<boolean, BackingError>;
+    ttl: Duration.Duration
+  ) => Effect.Effect<boolean, MutexBackingError>;
 
   /**
    * Check if the lock is currently held (by anyone).
    */
-  readonly isLocked: (key: string) => Effect.Effect<boolean, BackingError>;
+  readonly isLocked: (key: string) => Effect.Effect<boolean, MutexBackingError>;
 
   /**
    * Get the current holder ID, if any.
    */
   readonly getHolder: (
     key: string
-  ) => Effect.Effect<Option.Option<string>, BackingError>;
+  ) => Effect.Effect<Option.Option<string>, MutexBackingError>;
 }
 
 export const DistributedMutexBacking =
@@ -84,17 +91,23 @@ export interface DistributedMutexConfig {
    * How often to poll when waiting to acquire the lock.
    * @default 100ms
    */
-  readonly retryInterval?: Duration.DurationInput;
+  readonly acquireRetryInterval?: Duration.DurationInput;
 
   /**
-   * Maximum time to wait when acquiring the lock.
-   * If not set, will wait forever.
+   * How often to retry when a failure occurs.
+   * This could happen when:
+   * - Trying to acquire the lock
+   * - Refreshing the TTL
+   * - Releasing the lock
    */
-  readonly acquireTimeout?: Duration.DurationInput;
+  readonly backingFailureRetryPolicy?: Schedule.Schedule<void>;
 }
 
 const DEFAULT_TTL = Duration.seconds(30);
-const DEFAULT_RETRY_INTERVAL = Duration.millis(100);
+const DEFAULT_ACQUIRE_RETRY_INTERVAL = Duration.millis(100);
+const DEFAULT_FAILURE_RETRY_POLICY = Schedule.spaced(
+  DEFAULT_ACQUIRE_RETRY_INTERVAL
+).pipe(Schedule.asVoid);
 
 // =============================================================================
 // Distributed Mutex Interface
@@ -116,11 +129,7 @@ export interface DistributedMutex {
    */
   readonly withLock: <A, E, R>(
     effect: Effect.Effect<A, E, R>
-  ) => Effect.Effect<
-    A,
-    E | AcquireTimeoutError | LockLostError | BackingError,
-    R
-  >;
+  ) => Effect.Effect<A, E | LockLostError | MutexBackingError, R>;
 
   /**
    * Try to acquire the lock immediately without waiting.
@@ -129,16 +138,23 @@ export interface DistributedMutex {
    */
   readonly withLockIfAvailable: <A, E, R>(
     effect: Effect.Effect<A, E, R>
-  ) => Effect.Effect<Option.Option<A>, E | LockLostError | BackingError, R>;
+  ) => Effect.Effect<
+    Option.Option<A>,
+    E | LockLostError | MutexBackingError,
+    R
+  >;
 
   /**
    * Acquire the lock, waiting if necessary.
    * The lock is held until the scope is closed.
    * The lock TTL is refreshed automatically while held.
+   *
+   * @returns The fiber that refreshes the lock hold. Its lifetime is tied to the scope.
+   * When the scope closes, the fiber is interrupted and the lock is released.
    */
   readonly acquire: Effect.Effect<
-    void,
-    AcquireTimeoutError | LockLostError | BackingError,
+    Fiber.Fiber<void, LockLostError | MutexBackingError>,
+    LockLostError | MutexBackingError,
     Scope.Scope
   >;
 
@@ -146,23 +162,55 @@ export interface DistributedMutex {
    * Try to acquire immediately without waiting.
    * Returns Some(void) if acquired (lock held until scope closes),
    * None if lock was not available.
+   *
+   * @returns The fiber that refreshes the lock hold. Its lifetime is tied to the scope.
+   * When the scope closes, the fiber is interrupted and the lock is released.
    */
   readonly tryAcquire: Effect.Effect<
-    Option.Option<void>,
-    LockLostError | BackingError,
+    Option.Option<Fiber.Fiber<void, LockLostError | MutexBackingError>>,
+    LockLostError | MutexBackingError,
     Scope.Scope
   >;
 
   /**
    * Check if the lock is currently held.
    */
-  readonly isLocked: Effect.Effect<boolean, BackingError>;
+  readonly isLocked: Effect.Effect<boolean, MutexBackingError>;
 }
 
 // =============================================================================
 // Factory
 // =============================================================================
 
+type FullyResolvedConfig = {
+  ttl: Duration.Duration;
+  refreshInterval: Duration.Duration;
+  acquireRetryInterval: Duration.Duration;
+  backingFailureRetryPolicy: Schedule.Schedule<void>;
+};
+
+function fullyResolveConfig(
+  config: DistributedMutexConfig
+): FullyResolvedConfig {
+  const ttl = config.ttl ? Duration.decode(config.ttl) : DEFAULT_TTL;
+  const refreshInterval = config.refreshInterval
+    ? Duration.decode(config.refreshInterval)
+    : Duration.millis(Duration.toMillis(ttl) / 3);
+  const acquireRetryInterval = config.acquireRetryInterval
+    ? Duration.decode(config.acquireRetryInterval)
+    : DEFAULT_ACQUIRE_RETRY_INTERVAL;
+  const backingFailureRetryPolicy = config.backingFailureRetryPolicy
+    ? config.backingFailureRetryPolicy
+    : DEFAULT_FAILURE_RETRY_POLICY;
+
+  return {
+    ttl,
+    refreshInterval,
+    acquireRetryInterval,
+    backingFailureRetryPolicy,
+  };
+}
+
 /**
  * Create a distributed mutex for the given key.
  */
@@ -177,121 +225,125 @@ export const make = (
     const holderId = crypto.randomUUID();
 
     // Resolve config with defaults
-    const ttl = config.ttl ? Duration.decode(config.ttl) : DEFAULT_TTL;
-    const ttlMs = Duration.toMillis(ttl);
-    const refreshInterval = config.refreshInterval
-      ? Duration.decode(config.refreshInterval)
-      : Duration.millis(ttlMs / 3);
-    const retryInterval = config.retryInterval
-      ? Duration.decode(config.retryInterval)
-      : DEFAULT_RETRY_INTERVAL;
-    const acquireTimeout = config.acquireTimeout
-      ? Option.some(Duration.decode(config.acquireTimeout))
-      : Option.none<Duration.Duration>();
+    const {
+      ttl,
+      refreshInterval,
+      acquireRetryInterval,
+      backingFailureRetryPolicy,
+    } = fullyResolveConfig(config);
+
+    const withMutexBackingErrorRetry = <A, E extends { _tag: string }, R>(
+      effect: Effect.Effect<A, E | MutexBackingError, R>
+    ) =>
+      effect.pipe(
+        Effect.retry({
+          while: (e) => e._tag === "MutexBackingError",
+          schedule: backingFailureRetryPolicy,
+        })
+      );
 
     // Keep the lock alive by refreshing TTL periodically.
     // This effect runs forever until interrupted (when scope closes).
     const keepAlive = Effect.repeat(
       Effect.gen(function* () {
-        const refreshed = yield* backing.refresh(key, holderId, ttlMs);
+        const refreshed = yield* backing
+          .refresh(key, holderId, ttl)
+          .pipe(withMutexBackingErrorRetry);
+
         if (!refreshed) {
           return yield* new LockLostError({ key });
         }
       }),
       Schedule.spaced(refreshInterval)
-    );
+    ).pipe(Effect.asVoid);
 
     // Try to acquire immediately, returns Option
     const tryAcquire: Effect.Effect<
-      Option.Option<void>,
-      LockLostError | BackingError,
+      Option.Option<Fiber.Fiber<void, LockLostError | MutexBackingError>>,
+      MutexBackingError,
       Scope.Scope
     > = Effect.gen(function* () {
-      const acquired = yield* backing.tryAcquire(key, holderId, ttlMs);
+      const acquired = yield* backing
+        .tryAcquire(key, holderId, ttl)
+        .pipe(withMutexBackingErrorRetry);
       if (!acquired) {
         return Option.none();
       }
 
       // Start keepalive fiber, tied to this scope
-      yield* Effect.forkScoped(keepAlive);
+      const keepAliveFiber = yield* Effect.forkScoped(keepAlive);
 
       // Add finalizer to release lock when scope closes
       yield* Effect.addFinalizer(() =>
-        backing.release(key, holderId).pipe(Effect.ignore)
+        backing
+          .release(key, holderId)
+          .pipe(withMutexBackingErrorRetry, Effect.ignore)
       );
 
-      return Option.some(undefined as void);
+      return Option.some(keepAliveFiber);
     });
 
     // Acquire with retry/timeout, returns void when acquired
     const acquire: Effect.Effect<
-      void,
-      AcquireTimeoutError | LockLostError | BackingError,
+      Fiber.Fiber<void, LockLostError | MutexBackingError>,
+      MutexBackingError,
       Scope.Scope
-    > = Effect.gen(function* () {
-      // Build retry schedule with optional timeout
-      const schedule = Option.match(acquireTimeout, {
-        onNone: () => Schedule.spaced(retryInterval),
-        onSome: (timeout) =>
-          Schedule.spaced(retryInterval).pipe(Schedule.upTo(timeout)),
-      });
-
+    > =
       // Retry until we acquire the lock
-      yield* Effect.retry(
-        Effect.gen(function* () {
-          const maybeAcquired = yield* tryAcquire;
-          if (Option.isNone(maybeAcquired)) {
-            return yield* new NotYetAcquiredError();
-          }
+      Effect.gen(function* () {
+        const maybeAcquired = yield* tryAcquire;
+        if (Option.isNone(maybeAcquired)) {
+          return yield* new NotYetAcquiredError();
+        }
+        return maybeAcquired.value;
+      }).pipe(
+        Effect.retry({
+          while: (e) => e._tag === "NotYetAcquiredError",
+          schedule: Schedule.spaced(acquireRetryInterval),
         }),
-        schedule
-      ).pipe(
-        Effect.catchTag(
-          "NotYetAcquiredError",
-          () =>
-            new AcquireTimeoutError({
-              key,
-              timeoutMs: Option.match(acquireTimeout, {
-                onNone: () => -1,
-                onSome: Duration.toMillis,
-              }),
-            })
+        Effect.catchTag("NotYetAcquiredError", () =>
+          Effect.dieMessage(
+            "Invariant violated: `acquire` should never return `NotYetAcquiredError " +
+              "since it should be caught by the retry which should retry forever until the lock is acquired"
+          )
         )
       );
-    });
 
     // Convenience: acquire lock, run effect, release when done
     const withLock = <A, E, R>(
       effect: Effect.Effect<A, E, R>
-    ): Effect.Effect<
-      A,
-      E | AcquireTimeoutError | LockLostError | BackingError,
-      R
-    > =>
+    ): Effect.Effect<A, E | LockLostError | MutexBackingError, R> =>
       Effect.scoped(
         Effect.gen(function* () {
-          yield* acquire;
-          return yield* effect;
+          const keepAliveFiber = yield* acquire;
+          const taskFiber = yield* Effect.fork(effect);
+          return yield* Fiber.join(Fiber.zipLeft(taskFiber, keepAliveFiber));
         })
       );
 
     // Convenience: try to acquire, run effect if successful
     const withLockIfAvailable = <A, E, R>(
       effect: Effect.Effect<A, E, R>
-    ): Effect.Effect<Option.Option<A>, E | LockLostError | BackingError, R> =>
+    ): Effect.Effect<
+      Option.Option<A>,
+      E | LockLostError | MutexBackingError,
+      R
+    > =>
       Effect.scoped(
         Effect.gen(function* () {
           const maybeAcquired = yield* tryAcquire;
           if (Option.isNone(maybeAcquired)) {
-            return Option.none<A>();
+            return Option.none();
           }
-          const result = yield* effect;
-          return Option.some(result);
+          const keepAliveFiber = maybeAcquired.value;
+          const taskFiber = yield* Effect.fork(effect.pipe(Effect.asSome));
+          return yield* Fiber.join(Fiber.zipLeft(taskFiber, keepAliveFiber));
         })
       );
 
-    const isLocked: Effect.Effect<boolean, BackingError> =
-      backing.isLocked(key);
+    const isLocked: Effect.Effect<boolean, MutexBackingError> = backing
+      .isLocked(key)
+      .pipe(withMutexBackingErrorRetry);
 
     return {
       key,

package/src/Errors.ts

@@ -1,29 +1,5 @@
 import { Data } from "effect";
 
-/**
- * Base error for all distributed mutex errors
- */
-export class DistributedMutexError extends Data.TaggedError(
-  "DistributedMutexError"
-)<{
-  readonly message: string;
-  readonly cause?: unknown;
-}> {}
-
-/**
- * Failed to acquire the lock within the timeout period
- */
-export class AcquireTimeoutError extends Data.TaggedError(
-  "AcquireTimeoutError"
-)<{
-  readonly key: string;
-  readonly timeoutMs: number;
-}> {
-  get message() {
-    return `Failed to acquire lock "${this.key}" within ${this.timeoutMs}ms`;
-  }
-}
-
 /**
  * The lock was lost (TTL expired while we thought we held it)
  */
@@ -38,7 +14,7 @@ export class LockLostError extends Data.TaggedError("LockLostError")<{
 /**
  * Error from the backing store (Redis, etc.)
  */
-export class BackingError extends Data.TaggedError("BackingError")<{
+export class MutexBackingError extends Data.TaggedError("MutexBackingError")<{
   readonly operation: string;
   readonly cause: unknown;
 }> {

package/src/RedisBacking.ts

@@ -1,7 +1,7 @@
-import { Effect, Layer, Option } from "effect";
-import type { Redis } from "ioredis";
+import { Duration, Effect, Layer, Option } from "effect";
+import { Redis } from "ioredis";
 import { DistributedMutexBacking } from "./DistributedMutex.js";
-import { BackingError } from "./Errors.js";
+import { MutexBackingError } from "./Errors.js";
 
 /**
  * Lua script for atomic lock acquisition.
@@ -70,8 +70,8 @@ export const layer = (
   const tryAcquire = (
     key: string,
     holderId: string,
-    ttlMs: number
-  ): Effect.Effect<boolean, BackingError> =>
+    ttl: Duration.Duration
+  ): Effect.Effect<boolean, MutexBackingError> =>
     Effect.tryPromise({
       try: async () => {
         const result = await redis.eval(
@@ -79,17 +79,18 @@ export const layer = (
           1,
           prefixKey(key),
           holderId,
-          ttlMs.toString()
+          Duration.toMillis(ttl).toString()
         );
         return result === 1;
       },
-      catch: (cause) => new BackingError({ operation: "tryAcquire", cause }),
+      catch: (cause) =>
+        new MutexBackingError({ operation: "tryAcquire", cause }),
     });
 
   const release = (
     key: string,
     holderId: string
-  ): Effect.Effect<boolean, BackingError> =>
+  ): Effect.Effect<boolean, MutexBackingError> =>
     Effect.tryPromise({
       try: async () => {
         const result = await redis.eval(
@@ -100,14 +101,14 @@ export const layer = (
         );
         return result === 1;
       },
-      catch: (cause) => new BackingError({ operation: "release", cause }),
+      catch: (cause) => new MutexBackingError({ operation: "release", cause }),
     });
 
   const refresh = (
     key: string,
     holderId: string,
-    ttlMs: number
-  ): Effect.Effect<boolean, BackingError> =>
+    ttl: Duration.Duration
+  ): Effect.Effect<boolean, MutexBackingError> =>
     Effect.tryPromise({
       try: async () => {
         const result = await redis.eval(
@@ -115,31 +116,32 @@ export const layer = (
           1,
           prefixKey(key),
           holderId,
-          ttlMs.toString()
+          Duration.toMillis(ttl).toString()
         );
         return result === 1;
       },
-      catch: (cause) => new BackingError({ operation: "refresh", cause }),
+      catch: (cause) => new MutexBackingError({ operation: "refresh", cause }),
     });
 
-  const isLocked = (key: string): Effect.Effect<boolean, BackingError> =>
+  const isLocked = (key: string): Effect.Effect<boolean, MutexBackingError> =>
     Effect.tryPromise({
       try: async () => {
         const exists = await redis.exists(prefixKey(key));
         return exists === 1;
       },
-      catch: (cause) => new BackingError({ operation: "isLocked", cause }),
+      catch: (cause) => new MutexBackingError({ operation: "isLocked", cause }),
     });
 
   const getHolder = (
     key: string
-  ): Effect.Effect<Option.Option<string>, BackingError> =>
+  ): Effect.Effect<Option.Option<string>, MutexBackingError> =>
     Effect.tryPromise({
       try: async () => {
         const holder = await redis.get(prefixKey(key));
         return holder ? Option.some(holder) : Option.none();
       },
-      catch: (cause) => new BackingError({ operation: "getHolder", cause }),
+      catch: (cause) =>
+        new MutexBackingError({ operation: "getHolder", cause }),
     });
 
   return Layer.succeed(DistributedMutexBacking, {
@@ -150,119 +152,3 @@ export const layer = (
     getHolder,
   });
 };
-
-/**
- * Create a Redis backing from a connection URL.
- * This creates and manages the Redis connection lifecycle.
- */
-export const layerFromUrl = (
-  url: string,
-  keyPrefix = "dmutex:"
-): Layer.Layer<DistributedMutexBacking, BackingError> =>
-  Layer.scoped(
-    DistributedMutexBacking,
-    Effect.gen(function* () {
-      // Dynamic import to avoid requiring ioredis at module load time
-      const { default: Redis } = yield* Effect.tryPromise({
-        try: () => import("ioredis"),
-        catch: (cause) =>
-          new BackingError({
-            operation: "import",
-            cause: `Failed to import ioredis: ${cause}`,
-          }),
-      });
-
-      const redis = new Redis(url);
-
-      // Ensure cleanup on scope close
-      yield* Effect.addFinalizer(() =>
-        Effect.promise(() => redis.quit().catch(() => {}))
-      );
-
-      const prefixKey = (key: string) => `${keyPrefix}${key}`;
-
-      const tryAcquire = (
-        key: string,
-        holderId: string,
-        ttlMs: number
-      ): Effect.Effect<boolean, BackingError> =>
-        Effect.tryPromise({
-          try: async () => {
-            const result = await redis.eval(
-              ACQUIRE_SCRIPT,
-              1,
-              prefixKey(key),
-              holderId,
-              ttlMs.toString()
-            );
-            return result === 1;
-          },
-          catch: (cause) =>
-            new BackingError({ operation: "tryAcquire", cause }),
-        });
-
-      const release = (
-        key: string,
-        holderId: string
-      ): Effect.Effect<boolean, BackingError> =>
-        Effect.tryPromise({
-          try: async () => {
-            const result = await redis.eval(
-              RELEASE_SCRIPT,
-              1,
-              prefixKey(key),
-              holderId
-            );
-            return result === 1;
-          },
-          catch: (cause) => new BackingError({ operation: "release", cause }),
-        });
-
-      const refresh = (
-        key: string,
-        holderId: string,
-        ttlMs: number
-      ): Effect.Effect<boolean, BackingError> =>
-        Effect.tryPromise({
-          try: async () => {
-            const result = await redis.eval(
-              REFRESH_SCRIPT,
-              1,
-              prefixKey(key),
-              holderId,
-              ttlMs.toString()
-            );
-            return result === 1;
-          },
-          catch: (cause) => new BackingError({ operation: "refresh", cause }),
-        });
-
-      const isLocked = (key: string): Effect.Effect<boolean, BackingError> =>
-        Effect.tryPromise({
-          try: async () => {
-            const exists = await redis.exists(prefixKey(key));
-            return exists === 1;
-          },
-          catch: (cause) => new BackingError({ operation: "isLocked", cause }),
-        });
-
-      const getHolder = (
-        key: string
-      ): Effect.Effect<Option.Option<string>, BackingError> =>
-        Effect.tryPromise({
-          try: async () => {
-            const holder = await redis.get(prefixKey(key));
-            return holder ? Option.some(holder) : Option.none();
-          },
-          catch: (cause) => new BackingError({ operation: "getHolder", cause }),
-        });
-
-      return {
-        tryAcquire,
-        release,
-        refresh,
-        isLocked,
-        getHolder,
-      } satisfies DistributedMutexBacking;
-    })
-  );

package/src/index.ts

@@ -5,7 +5,7 @@
  *
  * @example
  * ```ts
- * import { DistributedMutex, makeRedisBackingLayer } from "effect-distributed-lock";
+ * import { DistributedMutex, RedisBacking } from "effect-distributed-lock";
  * import { Effect } from "effect";
  * import Redis from "ioredis";
  *
@@ -28,7 +28,7 @@
  * });
  *
  * program.pipe(
- *   Effect.provide(makeRedisBackingLayer(redis)),
+ *   Effect.provide(RedisBacking.layer(redis)),
  *   Effect.runPromise
  * );
  * ```
@@ -39,12 +39,7 @@
 // Core module (namespace with types and functions)
 export * as DistributedMutex from "./DistributedMutex.js";
 // Errors
-export {
-  AcquireTimeoutError,
-  BackingError,
-  DistributedMutexError,
-  LockLostError,
-} from "./Errors.js";
+export { MutexBackingError, LockLostError } from "./Errors.js";
 
 // Redis backing
 export * as RedisBacking from "./RedisBacking.js";

package/tsconfig.json

@@ -3,13 +3,13 @@
     // Environment setup & latest features
     "lib": ["ESNext"],
     "target": "ESNext",
-    "module": "ESNext",
+    "module": "NodeNext",
     "moduleDetection": "force",
     "jsx": "react-jsx",
     "allowJs": true,
 
     // Bundler mode
-    "moduleResolution": "bundler",
+    "moduleResolution": "nodenext",
     "verbatimModuleSyntax": true,
 
     // Build output