effect-distributed-lock 0.0.1 → 0.0.2

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,160 @@
 # effect-distributed-lock
 
-To install dependencies:
+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 & timeout** — control polling interval, acquire timeout, and TTL
+- **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: "30 seconds",
+    acquireTimeout: "10 seconds",
+  });
+
+  // Lock is held while effect runs, released automatically after
+  yield* mutex.withLock(
+    Effect.gen(function* () {
+      // Critical section - only one process can be here at a time
+      yield* doExclusiveWork();
+    })
+  );
+});
+
+program.pipe(Effect.provide(RedisLayer), Effect.runPromise);
+```
+
+## API
+
+### Creating a Mutex
+
+```typescript
+const mutex = yield* DistributedMutex.make(key, config);
 ```
 
-This project was created using `bun init` in bun v1.2.12. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
+| 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           |
+| `retryInterval`   | `DurationInput`  | `100ms`      | Polling interval when waiting to acquire         |
+| `acquireTimeout`  | `DurationInput`  | `∞`          | Max time to wait for lock (fails if exceeded)    |
+
+### Using the Mutex
+
+#### `withLock` — Acquire, run, release
+
+The simplest and recommended way. Acquires the lock, 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* () {
+    yield* mutex.acquire; // Lock held until scope closes
+    yield* doWork();
+    // Lock automatically released here
+  })
+);
+```
+
+#### `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("AcquireTimeoutError", (e) =>
+    Effect.log(`Timed out acquiring lock: ${e.key}`)
+  ),
+  Effect.catchTag("LockLostError", (e) =>
+    Effect.log(`Lock was lost while held: ${e.key}`)
+  ),
+  Effect.catchTag("BackingError", (e) =>
+    Effect.log(`Redis error: ${e.message}`)
+  )
+);
+```
+
+| Error                 | Description                                          |
+| --------------------- | ---------------------------------------------------- |
+| `AcquireTimeoutError` | Failed to acquire lock within the timeout period     |
+| `LockLostError`       | Lock TTL expired while we thought we held it         |
+| `BackingError`        | Error from the backing store (Redis connection, etc) |
+
+## Custom Backends
+
+Implement the `DistributedMutexBacking` interface to use a different store:
+
+```typescript
+import { Layer } from "effect";
+import { DistributedMutex } from "effect-distributed-lock";
+
+const MyCustomBacking = Layer.succeed(DistributedMutex.DistributedMutexBacking, {
+  tryAcquire: (key, holderId, ttlMs) => /* ... */,
+  release: (key, holderId) => /* ... */,
+  refresh: (key, holderId, ttlMs) => /* ... */,
+  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.2",
   "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/RedisBacking.ts

@@ -1,5 +1,5 @@
 import { Effect, Layer, Option } from "effect";
-import type { Redis } from "ioredis";
+import { Redis } from "ioredis";
 import { DistributedMutexBacking } from "./DistributedMutex.js";
 import { BackingError } from "./Errors.js";
 
@@ -162,16 +162,6 @@ export const layerFromUrl = (
   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

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
  * );
  * ```

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