effect-distributed-lock 0.0.10 → 0.0.11

package/README.md

@@ -111,7 +111,11 @@ yield* Effect.scoped(
 );
 ```
 
-Both `take` and `tryTake` return the keepalive fiber that refreshes the permit TTL. Errors from the keepalive (losing permits or backing store failure) are propagated through the fiber.
+Both `take` and `tryTake` return the keepalive fiber that refreshes the permit TTL.
+
+⚠️ **CRITICAL**: Errors from the keepalive fiber (losing permits or backing store failure) mean **the lock is effectively lost**. You **must** join this fiber at some point in your program to detect these failures. If the keepalive fiber errors and you don't join it, your program will continue running without holding the lock, potentially leading to race conditions or data corruption.
+
+**It is highly recommended to use `withPermits` or `withPermitsIfAvailable` instead**, which automatically manage the keepalive fiber lifecycle and propagate errors for you. Only use `take`/`tryTake` if you need explicit scope control and understand the responsibility of managing the keepalive fiber.
 
 ### Acquire Options
 

package/dist/Backing.d.ts

@@ -0,0 +1,54 @@
+import { Context, Duration, Effect, Stream } from "effect";
+declare const SemaphoreBackingError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SemaphoreBackingError";
+} & Readonly<A>;
+/**
+ * Error from the backing store (Redis, etc.)
+ */
+export declare class SemaphoreBackingError extends SemaphoreBackingError_base<{
+    readonly operation: string;
+    readonly cause: unknown;
+}> {
+    get message(): string;
+}
+/**
+ * Low-level backing store interface for distributed semaphore operations.
+ */
+export interface DistributedSemaphoreBacking {
+    /**
+     * Try to acquire `permits` from a semaphore with the given `limit`.
+     *
+     * @returns `true` if acquired, `false` if not enough permits available.
+     */
+    readonly tryAcquire: (key: string, holderId: string, ttl: Duration.Duration, limit: number, permits: number) => Effect.Effect<boolean, SemaphoreBackingError>;
+    /**
+     * Release `permits` held by the given holder.
+     *
+     * @returns The number of permits actually released.
+     */
+    readonly release: (key: string, holderId: string, permits: number) => Effect.Effect<number, SemaphoreBackingError>;
+    /**
+     * Refresh the TTL on permits held by this holder.
+     *
+     * @returns `true` if refreshed, `false` if permits were lost (e.g., expired).
+     */
+    readonly refresh: (key: string, holderId: string, ttl: Duration.Duration, limit: number, permits: number) => Effect.Effect<boolean, SemaphoreBackingError>;
+    /**
+     * Get the number of permits currently held (in use).
+     */
+    readonly getCount: (key: string, ttl: Duration.Duration) => Effect.Effect<number, SemaphoreBackingError>;
+    /**
+     * Optional: Stream of notifications when permits MAY be available.
+     *
+     * If provided, the semaphore layer uses this in addition to polling. The stream emits a signal whenever permits are released.
+     *
+     * Notes:
+     * - Multiple waiters may race for permits after a notification
+     * - The semaphore still calls `tryAcquire` after each notification
+     * - Implementations should handle reconnection internally (hence why the stream does not have an error type)
+     */
+    readonly onPermitsReleased?: (key: string) => Stream.Stream<void>;
+}
+export declare const DistributedSemaphoreBacking: Context.Tag<DistributedSemaphoreBacking, DistributedSemaphoreBacking>;
+export {};
+//# sourceMappingURL=Backing.d.ts.map

package/dist/Backing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Backing.d.ts","sourceRoot":"","sources":["../src/Backing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAQ,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;;;;AAMjE;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,2BAEzC;IACA,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB,CAAC;IACA,IAAI,OAAO,WAEV;CACF;AAMD;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,CACnB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,QAAQ,CAAC,QAAQ,EACtB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,KACZ,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC;IAEnD;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAChB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,KACZ,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IAElD;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAChB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,QAAQ,CAAC,QAAQ,EACtB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,KACZ,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC;IAEnD;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,CACjB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,QAAQ,CAAC,QAAQ,KACnB,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IAElD;;;;;;;;;OASG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CACnE;AAED,eAAO,MAAM,2BAA2B,uEAGrC,CAAC"}

package/dist/Backing.js

@@ -0,0 +1,14 @@
+import { Context, Data, Duration, Effect, Stream } from "effect";
+// =============================================================================
+// Errors
+// =============================================================================
+/**
+ * Error from the backing store (Redis, etc.)
+ */
+export class SemaphoreBackingError extends Data.TaggedError("SemaphoreBackingError") {
+    get message() {
+        return `Backing store error during "${this.operation}": ${this.cause}`;
+    }
+}
+export const DistributedSemaphoreBacking = Context.GenericTag("@effect-distributed-lock/DistributedSemaphoreBacking");
+//# sourceMappingURL=Backing.js.map

package/dist/Backing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Backing.js","sourceRoot":"","sources":["../src/Backing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEjE,gFAAgF;AAChF,SAAS;AACT,gFAAgF;AAEhF;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,IAAI,CAAC,WAAW,CACzD,uBAAuB,CAIvB;IACA,IAAI,OAAO;QACT,OAAO,+BAA+B,IAAI,CAAC,SAAS,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACzE,CAAC;CACF;AAoED,MAAM,CAAC,MAAM,2BAA2B,GACtC,OAAO,CAAC,UAAU,CAChB,sDAAsD,CACvD,CAAC"}

package/dist/DistributedSemaphore.d.ts

@@ -0,0 +1,162 @@
+import { Duration, Effect, Fiber, Option, Schedule, Scope } from "effect";
+import { DistributedSemaphoreBacking, SemaphoreBackingError } from "./Backing.js";
+import { LockLostError, LockNotAcquiredError } from "./Errors.js";
+export interface DistributedSemaphoreConfig {
+    /**
+     * Maximum number of permits available.
+     * This is the total capacity of the semaphore.
+     * @default 1 (mutex behavior)
+     */
+    readonly limit?: number;
+    /**
+     * TTL for held permits. If the holder crashes, permits auto-release after this.
+     * @default 30 seconds
+     */
+    readonly ttl?: Duration.DurationInput;
+    /**
+     * How often to refresh the TTL while holding permits.
+     * Should be less than TTL to avoid losing the permits.
+     * @default 1/3 of TTL
+     */
+    readonly refreshInterval?: Duration.DurationInput;
+    /**
+     * How often to poll when waiting to acquire permits.
+     * @default Schedule.spaced(Duration.millis(100))
+     */
+    readonly acquireRetryPolicy?: Schedule.Schedule<unknown>;
+    /**
+     * Retry policy when a backing failure occurs.
+     * This could happen when:
+     * - Trying to acquire permits
+     * - Refreshing the TTL
+     * - Releasing permits
+     * @default Schedule.recurs(3)
+     */
+    readonly backingFailureRetryPolicy?: Schedule.Schedule<unknown>;
+}
+/**
+ * Options for acquire operations (take, tryTake, withPermits, etc.)
+ */
+export interface AcquireOptions {
+    /**
+     * Unique identifier for this permit holder.
+     *
+     * By default, a random UUID is generated per-acquire. Override this if you need:
+     * - Predictable identifiers for debugging/observability
+     * - Cross-process lock handoff (acquire in one process, release in another)
+     *
+     * ⚠️ **Warning**: Must be unique across concurrent holders, otherwise locks with the same
+     * identifier may be treated as the same holder.
+     *
+     * @default crypto.randomUUID()
+     */
+    readonly identifier?: string;
+    /**
+     * If true, assumes the permits were already acquired externally with the given identifier.
+     * Instead of acquiring, uses refresh to verify ownership.
+     *
+     * **Requires `identifier` to be provided.**
+     *
+     * This is useful for cross-process lock handoff:
+     * 1. Process A acquires permits with a known identifier
+     * 2. Process A passes the identifier to Process B (via message queue, etc.)
+     * 3. Process B calls take/withPermits with `{ identifier, acquiredExternally: true }`
+     * 4. Process B now owns the permits (refreshing and releasing)
+     *
+     * ⚠️ **Unsafe**: If the identifier is wrong or the lock expired, this will fail immediately.
+     *
+     * @default false
+     */
+    readonly acquiredExternally?: boolean;
+}
+/**
+ * A distributed semaphore that can be used across multiple processes/services.
+ *
+ * Similar to Effect's built-in Semaphore, but distributed across processes
+ * using a backing store like Redis.
+ *
+ * A semaphore manages a pool of permits. Tasks can acquire one or more permits,
+ * and must release them when done. If not enough permits are available, tasks
+ * wait until permits are released.
+ *
+ * @example
+ * ```ts
+ * // Create a semaphore that allows 5 concurrent operations
+ * const sem = yield* DistributedSemaphore.make("my-resource", { limit: 5 });
+ *
+ * // Acquire 2 permits, run effect, then release
+ * yield* sem.withPermits(2)(myEffect);
+ *
+ * // Create a mutex (limit=1) for exclusive access
+ * const mutex = yield* DistributedSemaphore.make("my-lock", { limit: 1 });
+ * yield* mutex.withPermits(1)(criticalSection);
+ * ```
+ */
+export interface DistributedSemaphore {
+    /**
+     * The key identifying this semaphore in the backing store.
+     */
+    readonly key: string;
+    /**
+     * The maximum number of permits available.
+     */
+    readonly limit: number;
+    /**
+     * Run an effect with the specified number of permits.
+     * Acquires the permits, runs the effect, then releases.
+     * If not enough permits are available, waits until they are.
+     *
+     * The permit TTL is refreshed automatically while the effect runs.
+     */
+    readonly withPermits: (permits: number, options?: AcquireOptions) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | LockLostError | SemaphoreBackingError | LockNotAcquiredError, R>;
+    /**
+     * Run an effect only if the specified permits are immediately available.
+     * Returns Some(result) if permits were acquired and effect ran,
+     * None if permits were not available.
+     */
+    readonly withPermitsIfAvailable: (permits: number, options?: AcquireOptions) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<Option.Option<A>, E | LockLostError | SemaphoreBackingError, R>;
+    /**
+     * Acquire the specified number of permits, waiting if necessary.
+     * The permits are held until the scope is closed.
+     * The permit TTL is refreshed automatically while held.
+     *
+     * @returns The fiber that refreshes the permit hold. Its lifetime is tied to the scope.
+     * When the scope closes, the fiber is interrupted and permits are released.
+     */
+    readonly take: (permits: number, options?: AcquireOptions) => Effect.Effect<Fiber.Fiber<never, LockLostError | SemaphoreBackingError>, LockLostError | SemaphoreBackingError | LockNotAcquiredError, Scope.Scope>;
+    /**
+     * Try to acquire permits immediately without waiting.
+     * Returns Some(fiber) if acquired (permits held until scope closes),
+     * None if permits were not available.
+     *
+     * @returns The fiber that refreshes the permit hold. Its lifetime is tied to the scope.
+     * When the scope closes, the fiber is interrupted and permits are released.
+     */
+    readonly tryTake: (permits: number, options?: AcquireOptions) => Effect.Effect<Option.Option<Fiber.Fiber<never, LockLostError | SemaphoreBackingError>>, LockLostError | SemaphoreBackingError, Scope.Scope>;
+    /**
+     * Get the current number of active permits (for debugging/introspection).
+     * Note: This is eventually consistent due to TTL-based expiration.
+     */
+    readonly currentCount: Effect.Effect<number, SemaphoreBackingError>;
+}
+/**
+ * Create a distributed semaphore for the given key.
+ *
+ * @param key - Unique identifier for this semaphore in the backing store
+ * @param config - Configuration options
+ *
+ * @example
+ * ```ts
+ * // Create a semaphore that allows 5 concurrent operations
+ * const sem = yield* DistributedSemaphore.make("my-resource", { limit: 5 });
+ *
+ * // Use withPermits to run an effect with acquired permits
+ * yield* sem.withPermits(2)(Effect.log("I have 2 permits"));
+ *
+ * // Use withPermitsIfAvailable to try without waiting
+ * const result = yield* sem.withPermitsIfAvailable(1)(Effect.succeed(42));
+ * // result: Option<number>
+ * ```
+ */
+export declare const make: (key: string, config?: DistributedSemaphoreConfig) => Effect.Effect<DistributedSemaphore, never, DistributedSemaphoreBacking>;
+//# sourceMappingURL=DistributedSemaphore.d.ts.map

package/dist/DistributedSemaphore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DistributedSemaphore.d.ts","sourceRoot":"","sources":["../src/DistributedSemaphore.ts"],"names":[],"mappings":"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"}

package/dist/DistributedSemaphore.js

@@ -0,0 +1,163 @@
+import { Deferred, Duration, Effect, Fiber, Function, Option, Schedule, Scope, Stream, } from "effect";
+import { DistributedSemaphoreBacking, SemaphoreBackingError, } from "./Backing.js";
+import { LockLostError, LockNotAcquiredError } from "./Errors.js";
+const DEFAULT_LIMIT = 1;
+const DEFAULT_TTL = Duration.seconds(30);
+const DEFAULT_ACQUIRE_RETRY_POLICY = Schedule.spaced(Duration.millis(100));
+const DEFAULT_FAILURE_RETRY_POLICY = Schedule.recurs(3);
+function fullyResolveConfig(config) {
+    const limit = config.limit ?? DEFAULT_LIMIT;
+    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 acquireRetryPolicy = config.acquireRetryPolicy
+        ? config.acquireRetryPolicy
+        : DEFAULT_ACQUIRE_RETRY_POLICY;
+    const backingFailureRetryPolicy = config.backingFailureRetryPolicy
+        ? config.backingFailureRetryPolicy
+        : DEFAULT_FAILURE_RETRY_POLICY;
+    return {
+        limit,
+        ttl,
+        refreshInterval,
+        acquireRetryPolicy,
+        backingFailureRetryPolicy,
+    };
+}
+/**
+ * Create a distributed semaphore for the given key.
+ *
+ * @param key - Unique identifier for this semaphore in the backing store
+ * @param config - Configuration options
+ *
+ * @example
+ * ```ts
+ * // Create a semaphore that allows 5 concurrent operations
+ * const sem = yield* DistributedSemaphore.make("my-resource", { limit: 5 });
+ *
+ * // Use withPermits to run an effect with acquired permits
+ * yield* sem.withPermits(2)(Effect.log("I have 2 permits"));
+ *
+ * // Use withPermitsIfAvailable to try without waiting
+ * const result = yield* sem.withPermitsIfAvailable(1)(Effect.succeed(42));
+ * // result: Option<number>
+ * ```
+ */
+export const make = (key, config = {}) => Effect.gen(function* () {
+    const backing = yield* DistributedSemaphoreBacking;
+    // Resolve config with defaults
+    const { limit, ttl, refreshInterval, acquireRetryPolicy, backingFailureRetryPolicy, } = fullyResolveConfig(config);
+    const withBackingErrorRetry = (effect) => effect.pipe(Effect.retry({
+        while: (e) => e._tag === "SemaphoreBackingError",
+        schedule: backingFailureRetryPolicy,
+    }));
+    // Keep the permits alive by refreshing TTL periodically.
+    // This effect runs forever until interrupted (when scope closes).
+    const keepAlive = (identifier, permits) => Effect.repeat(Effect.gen(function* () {
+        const refreshed = yield* backing
+            .refresh(key, identifier, ttl, limit, permits)
+            .pipe(withBackingErrorRetry);
+        if (!refreshed) {
+            return yield* new LockLostError({ key });
+        }
+    }), Schedule.spaced(refreshInterval)).pipe(Effect.andThen(Effect.dieMessage("Invariant violated: `keepAlive` should never return a value")));
+    // Try to acquire permits immediately, returns Option
+    const tryTake = (permits, options) => Effect.gen(function* () {
+        // Generate identifier per-acquire if not provided
+        const identifier = options?.identifier ?? crypto.randomUUID();
+        const acquiredExternally = options?.acquiredExternally ?? false;
+        // If acquiredExternally, use refresh to verify ownership instead of acquire
+        const acquired = acquiredExternally
+            ? yield* backing
+                .refresh(key, identifier, ttl, limit, permits)
+                .pipe(withBackingErrorRetry)
+            : yield* backing
+                .tryAcquire(key, identifier, ttl, limit, permits)
+                .pipe(withBackingErrorRetry);
+        if (!acquired) {
+            return Option.none();
+        }
+        // Start keepalive fiber, tied to this scope
+        const keepAliveFiber = yield* Effect.forkScoped(keepAlive(identifier, permits));
+        // Add finalizer to release permits when scope closes
+        yield* Effect.addFinalizer(() => backing
+            .release(key, identifier, permits)
+            .pipe(withBackingErrorRetry, Effect.ignore));
+        return Option.some(keepAliveFiber);
+    });
+    // Acquire permits with retry, returns fiber when acquired
+    const take = (permits, options) => Effect.gen(function* () {
+        // Generate identifier once for all retry attempts (outside the retry loop)
+        const identifier = options?.identifier ?? crypto.randomUUID();
+        const resolvedOptions = {
+            identifier,
+            acquiredExternally: options?.acquiredExternally,
+        };
+        // We use a semaphore to ensure that only one acquire attempt is made at a time.
+        // With `withPermitsIfAvailable`, if both the poll-based and push-based attempts "trigger" at the same time,
+        // one will succeed and the other will simple be a no-op.
+        const acquireSemaphore = yield* Effect.makeSemaphore(1);
+        const pushBasedAcquireEnabled = backing.onPermitsReleased
+            ? true
+            : false;
+        const pollBasedAcquire = Effect.gen(function* () {
+            const maybeAcquired = yield* tryTake(permits, resolvedOptions).pipe(
+            // only apply the semaphore if push-based acquire is supported
+            pushBasedAcquireEnabled
+                ? Function.compose(acquireSemaphore.withPermitsIfAvailable(1), Effect.map(Option.flatten))
+                : Function.identity);
+            if (Option.isNone(maybeAcquired)) {
+                return yield* new LockNotAcquiredError({ key });
+            }
+            return maybeAcquired.value;
+        }).pipe(Effect.retry({
+            while: (e) => e._tag === "LockNotAcquiredError" && !resolvedOptions.acquiredExternally,
+            schedule: acquireRetryPolicy,
+        }));
+        if (!pushBasedAcquireEnabled) {
+            return yield* pollBasedAcquire;
+        }
+        // Push-based acquire: run both poll-based and push-based acquire in parallel, and return the first one to complete
+        const pushBasedAcquire = Effect.gen(function* () {
+            if (!backing.onPermitsReleased) {
+                // SAFETY: We know that onPermitsReleased is provided because we checked it above
+                return yield* Effect.dieMessage("Invariant violated: `onPermitsReleased` is not provided when it was expected");
+            }
+            return yield* backing.onPermitsReleased(key).pipe(Stream.runFoldWhileEffect(Option.none(), Option.isNone, // keep folding while we haven't acquired
+            () => tryTake(permits, resolvedOptions).pipe(acquireSemaphore.withPermitsIfAvailable(1), Effect.map(Option.flatten))), Effect.flatMap(Option.match({
+                onSome: Effect.succeed,
+                onNone: () => Effect.dieMessage("Invariant violated: the stream should never return `None`")
+            })));
+        });
+        // first to succeed (acquire permits) wins
+        return yield* Effect.race(pollBasedAcquire, pushBasedAcquire);
+    });
+    // Convenience: acquire permits, run effect, release when done
+    const withPermits = (permits, options) => (effect) => Effect.scoped(Effect.gen(function* () {
+        const keepAliveFiber = yield* take(permits, options);
+        return yield* Effect.raceFirst(effect, Fiber.join(keepAliveFiber));
+    }));
+    // Convenience: try to acquire permits, run effect if successful
+    const withPermitsIfAvailable = (permits, options) => (effect) => Effect.scoped(Effect.gen(function* () {
+        const maybeAcquired = yield* tryTake(permits, options);
+        if (Option.isNone(maybeAcquired)) {
+            return Option.none();
+        }
+        const keepAliveFiber = maybeAcquired.value;
+        return yield* Effect.raceFirst(effect.pipe(Effect.asSome), Fiber.join(keepAliveFiber));
+    }));
+    const currentCount = backing
+        .getCount(key, ttl)
+        .pipe(withBackingErrorRetry);
+    return {
+        key,
+        limit,
+        withPermits,
+        withPermitsIfAvailable,
+        take,
+        tryTake,
+        currentCount,
+    };
+});
+//# sourceMappingURL=DistributedSemaphore.js.map

package/dist/DistributedSemaphore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DistributedSemaphore.js","sourceRoot":"","sources":["../src/DistributedSemaphore.ts"],"names":[],"mappings":"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"}

package/dist/Errors.d.ts

@@ -0,0 +1,24 @@
+declare const LockLostError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "LockLostError";
+} & Readonly<A>;
+/**
+ * The permits were lost (TTL expired while we thought we held them)
+ */
+export declare class LockLostError extends LockLostError_base<{
+    readonly key: string;
+}> {
+    get message(): string;
+}
+declare const LockNotAcquiredError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "LockNotAcquiredError";
+} & Readonly<A>;
+/**
+ * The lock failed to be acquired. This occurs when the lock is not aquired within the provided schedule.
+ */
+export declare class LockNotAcquiredError extends LockNotAcquiredError_base<{
+    readonly key: string;
+}> {
+    get message(): string;
+}
+export {};
+//# sourceMappingURL=Errors.d.ts.map

package/dist/Errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Errors.d.ts","sourceRoot":"","sources":["../src/Errors.ts"],"names":[],"mappings":";;;AAEA;;GAEG;AACH,qBAAa,aAAc,SAAQ,mBAAkC;IACnE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB,CAAC;IACA,IAAI,OAAO,WAEV;CACF;;;;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,0BAExC;IACA,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB,CAAC;IACA,IAAI,OAAO,WAEV;CACF"}

package/dist/Errors.js

@@ -0,0 +1,18 @@
+import { Data } from "effect";
+/**
+ * The permits were lost (TTL expired while we thought we held them)
+ */
+export class LockLostError extends Data.TaggedError("LockLostError") {
+    get message() {
+        return `Permits for "${this.key}" were lost (TTL expired or taken by another holder)`;
+    }
+}
+/**
+ * The lock failed to be acquired. This occurs when the lock is not aquired within the provided schedule.
+ */
+export class LockNotAcquiredError extends Data.TaggedError("LockNotAcquiredError") {
+    get message() {
+        return `Lock for "${this.key}" was not acquired`;
+    }
+}
+//# sourceMappingURL=Errors.js.map

package/dist/Errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Errors.js","sourceRoot":"","sources":["../src/Errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAE9B;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,IAAI,CAAC,WAAW,CAAC,eAAe,CAEjE;IACA,IAAI,OAAO;QACT,OAAO,gBAAgB,IAAI,CAAC,GAAG,sDAAsD,CAAC;IACxF,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,IAAI,CAAC,WAAW,CACxD,sBAAsB,CAGtB;IACA,IAAI,OAAO;QACT,OAAO,aAAa,IAAI,CAAC,GAAG,oBAAoB,CAAC;IACnD,CAAC;CACF"}

package/dist/RedisBacking.d.ts

@@ -0,0 +1,40 @@
+import { Layer, Schedule } from "effect";
+import { Redis } from "ioredis";
+import { DistributedSemaphoreBacking } from "./Backing.js";
+export interface RedisBackingOptions {
+    /**
+     * Prefix for all keys in Redis.
+     * @default "semaphore:"
+     */
+    readonly keyPrefix?: string;
+    /**
+     * Enable push-based acquisition using Redis pub/sub.
+     *
+     * When enabled, waiters subscribe to a channel and get notified immediately
+     * when permits are released, instead of polling. This reduces latency and
+     * load on Redis.
+     *
+     * Requires an additional Redis connection per waiting semaphore.
+     *
+     * @default true
+     */
+    readonly pushBasedAcquireEnabled?: boolean;
+    /**
+     * How often to retry the stream of notifications when permits are released.
+     * @default Schedule.forever
+     */
+    readonly pushStreamRetrySchedule?: Schedule.Schedule<unknown>;
+}
+/**
+ * Create a Redis-backed distributed semaphore backing layer.
+ *
+ * **Important:** This implementation is for single-instance Redis only.
+ * It does not implement the Redlock algorithm and should not be used with
+ * Redis Cluster or Redis Sentinel for distributed locking guarantees.
+ * For multi-instance Redis, consider implementing a Redlock-based backing.
+ *
+ * @param redis - An ioredis client instance (single instance, not cluster)
+ * @param options - Configuration options
+ */
+export declare const layer: (redis: Redis, options?: RedisBackingOptions) => Layer.Layer<DistributedSemaphoreBacking>;
+//# sourceMappingURL=RedisBacking.d.ts.map

package/dist/RedisBacking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisBacking.d.ts","sourceRoot":"","sources":["../src/RedisBacking.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,EAAE,QAAQ,EAAU,MAAM,QAAQ,CAAC;AACnE,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EACL,2BAA2B,EAE5B,MAAM,cAAc,CAAC;AAsJtB,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAE3C;;;OAGG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAChB,OAAO,KAAK,EACZ,UAAS,mBAAwB,KAChC,KAAK,CAAC,KAAK,CAAC,2BAA2B,CAyJzC,CAAC"}

package/dist/RedisBacking.js

@@ -0,0 +1,233 @@
+import { Duration, Effect, Layer, Schedule, Stream } from "effect";
+import { Redis } from "ioredis";
+import { DistributedSemaphoreBacking, SemaphoreBackingError, } from "./Backing.js";
+/**
+ * Lua script for atomic semaphore acquisition.
+ *
+ * Uses a sorted set where:
+ * - Each member is `holderId_permitIndex` (e.g., "abc123_0", "abc123_1")
+ * - Score is the acquisition timestamp
+ * - Expired entries are removed before checking capacity
+ *
+ * Arguments:
+ * - KEYS[1]: the semaphore key
+ * - ARGV[1]: limit (max permits)
+ * - ARGV[2]: permits to acquire
+ * - ARGV[3]: holderId
+ * - ARGV[4]: ttlMs (lock timeout in ms)
+ * - ARGV[5]: now (current timestamp in ms)
+ *
+ * Returns 1 if acquired, 0 if not enough permits available.
+ */
+const ACQUIRE_SCRIPT = `
+local key = KEYS[1]
+local limit = tonumber(ARGV[1])
+local permits = tonumber(ARGV[2])
+local holderId = ARGV[3]
+local ttlMs = tonumber(ARGV[4])
+local now = tonumber(ARGV[5])
+local expiredTimestamp = now - ttlMs
+
+-- Remove expired entries
+redis.call('zremrangebyscore', key, '-inf', expiredTimestamp)
+
+-- Check if there's room for the requested permits
+if (redis.call('zcard', key) + permits) <= limit then
+  -- Add all permits with current timestamp
+  local args = {}
+  for i = 0, permits - 1 do
+    table.insert(args, now)
+    table.insert(args, holderId .. '_' .. i)
+  end
+  redis.call('zadd', key, unpack(args))
+  redis.call('pexpire', key, ttlMs)
+  return 1
+else
+  return 0
+end
+`;
+/**
+ * Lua script for atomic release.
+ *
+ * Removes all permits held by this holder and optionally publishes a notification.
+ *
+ * Arguments:
+ * - KEYS[1]: the semaphore key
+ * - KEYS[2]: the release notification channel
+ * - ARGV[1]: permits to release
+ * - ARGV[2]: holderId
+ * - ARGV[3]: shouldPublish (1 = publish, 0 = don't publish)
+ *
+ * Returns the number of permits released.
+ */
+const RELEASE_SCRIPT = `
+local key = KEYS[1]
+local channel = KEYS[2]
+local permits = tonumber(ARGV[1])
+local holderId = ARGV[2]
+local shouldPublish = tonumber(ARGV[3]) == 1
+local args = {}
+
+for i = 0, permits - 1 do
+  table.insert(args, holderId .. '_' .. i)
+end
+
+local released = redis.call('zrem', key, unpack(args))
+
+-- Notify waiters that permits may be available
+if released > 0 and shouldPublish then
+  redis.call('publish', channel, released)
+end
+
+return released
+`;
+/**
+ * Lua script for atomic TTL refresh.
+ *
+ * Updates the timestamp (score) for all permits held by this holder.
+ * Returns 0 if the holder doesn't have any permits (lock was lost).
+ *
+ * Arguments:
+ * - KEYS[1]: the semaphore key
+ * - ARGV[1]: limit (for consistency, though not strictly needed for refresh)
+ * - ARGV[2]: permits
+ * - ARGV[3]: holderId
+ * - ARGV[4]: ttlMs
+ * - ARGV[5]: now
+ *
+ * Returns 1 if refreshed, 0 if permits were lost.
+ */
+const REFRESH_SCRIPT = `
+local key = KEYS[1]
+local limit = tonumber(ARGV[1])
+local permits = tonumber(ARGV[2])
+local holderId = ARGV[3]
+local ttlMs = tonumber(ARGV[4])
+local now = tonumber(ARGV[5])
+local expiredTimestamp = now - ttlMs
+
+-- Remove expired entries
+redis.call('zremrangebyscore', key, '-inf', expiredTimestamp)
+
+-- Check if we still hold the first permit (indicator that we still own it)
+if redis.call('zscore', key, holderId .. '_0') then
+  -- Update all permits with new timestamp
+  local args = {}
+  for i = 0, permits - 1 do
+    table.insert(args, now)
+    table.insert(args, holderId .. '_' .. i)
+  end
+  redis.call('zadd', key, unpack(args))
+  redis.call('pexpire', key, ttlMs)
+  return 1
+else
+  return 0
+end
+`;
+/**
+ * Lua script to get the current count of active permits.
+ *
+ * Arguments:
+ * - KEYS[1]: the semaphore key
+ * - ARGV[1]: ttlMs
+ * - ARGV[2]: now
+ *
+ * Returns the number of active (non-expired) permits.
+ */
+const GET_COUNT_SCRIPT = `
+local key = KEYS[1]
+local ttlMs = tonumber(ARGV[1])
+local now = tonumber(ARGV[2])
+local expiredTimestamp = now - ttlMs
+
+-- Remove expired entries
+redis.call('zremrangebyscore', key, '-inf', expiredTimestamp)
+
+return redis.call('zcard', key)
+`;
+/**
+ * Create a Redis-backed distributed semaphore backing layer.
+ *
+ * **Important:** This implementation is for single-instance Redis only.
+ * It does not implement the Redlock algorithm and should not be used with
+ * Redis Cluster or Redis Sentinel for distributed locking guarantees.
+ * For multi-instance Redis, consider implementing a Redlock-based backing.
+ *
+ * @param redis - An ioredis client instance (single instance, not cluster)
+ * @param options - Configuration options
+ */
+export const layer = (redis, options = {}) => {
+    const keyPrefix = options.keyPrefix ?? "semaphore:";
+    const pushBasedAcquireEnabled = options.pushBasedAcquireEnabled ?? true;
+    const pushStreamRetrySchedule = options.pushStreamRetrySchedule ?? Schedule.forever;
+    const prefixKey = (key) => `${keyPrefix}${key}`;
+    const releaseChannel = (key) => `${keyPrefix}${key}:released`;
+    const tryAcquire = (key, holderId, ttl, limit, permits) => Effect.tryPromise({
+        try: async () => {
+            const now = Date.now();
+            const result = await redis.eval(ACQUIRE_SCRIPT, 1, prefixKey(key), limit.toString(), permits.toString(), holderId, Duration.toMillis(ttl).toString(), now.toString());
+            return result === 1;
+        },
+        catch: (cause) => new SemaphoreBackingError({ operation: "tryAcquire", cause }),
+    });
+    const release = (key, holderId, permits) => Effect.tryPromise({
+        try: async () => {
+            const result = await redis.eval(RELEASE_SCRIPT, 2, prefixKey(key), releaseChannel(key), permits.toString(), holderId, pushBasedAcquireEnabled ? "1" : "0");
+            return result;
+        },
+        catch: (cause) => new SemaphoreBackingError({ operation: "release", cause }),
+    });
+    const refresh = (key, holderId, ttl, limit, permits) => Effect.tryPromise({
+        try: async () => {
+            const now = Date.now();
+            const result = await redis.eval(REFRESH_SCRIPT, 1, prefixKey(key), limit.toString(), permits.toString(), holderId, Duration.toMillis(ttl).toString(), now.toString());
+            return result === 1;
+        },
+        catch: (cause) => new SemaphoreBackingError({ operation: "refresh", cause }),
+    });
+    const getCount = (key, ttl) => Effect.tryPromise({
+        try: async () => {
+            const now = Date.now();
+            const result = await redis.eval(GET_COUNT_SCRIPT, 1, prefixKey(key), Duration.toMillis(ttl).toString(), now.toString());
+            return result;
+        },
+        catch: (cause) => new SemaphoreBackingError({ operation: "getCount", cause }),
+    });
+    // Stream that emits when permits are released on a given key.
+    // Uses Redis pub/sub with a dedicated subscriber connection.
+    const onPermitsReleased = (key) => Stream.asyncPush((emit) => {
+        const channel = releaseChannel(key);
+        return Effect.acquireRelease(Effect.gen(function* () {
+            // Create a dedicated subscriber connection
+            const subscriber = redis.duplicate();
+            // Set up message handler before subscribing
+            const messageHandler = (ch, _message) => {
+                if (ch === channel) {
+                    emit.single(void 0);
+                }
+            };
+            subscriber.on("message", messageHandler);
+            // Subscribe to the channel
+            yield* Effect.tryPromise({
+                try: () => subscriber.subscribe(channel),
+                catch: (cause) => new SemaphoreBackingError({ operation: "subscribe", cause }),
+            });
+            return { subscriber, messageHandler };
+        }), ({ subscriber, messageHandler }) => Effect.promise(async () => {
+            subscriber.off("message", messageHandler);
+            await subscriber.unsubscribe(channel);
+            subscriber.disconnect();
+        }));
+    }).pipe(Stream.retry(pushStreamRetrySchedule), 
+    // If we continue to error, and the schedule has completed,
+    // just return a stream that will never emit
+    Stream.catchTag("SemaphoreBackingError", () => Stream.never));
+    return Layer.succeed(DistributedSemaphoreBacking, {
+        tryAcquire,
+        release,
+        refresh,
+        getCount,
+        onPermitsReleased: pushBasedAcquireEnabled ? onPermitsReleased : undefined,
+    });
+};
+//# sourceMappingURL=RedisBacking.js.map

package/dist/RedisBacking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisBacking.js","sourceRoot":"","sources":["../src/RedisBacking.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Effect Distributed Semaphore
+ *
+ * A distributed semaphore library for Effect with pluggable backends.
+ * Implements a multi-semaphore that can be used to implement:
+ * - Mutex (limit=1, permits=1)
+ * - Semaphore (limit=N, permits=1)
+ * - Multi-semaphore (limit=N, permits=M)
+ *
+ * @example
+ * ```ts
+ * import { DistributedSemaphore, RedisBacking } from "effect-distributed-lock";
+ * import { Effect } from "effect";
+ * import Redis from "ioredis";
+ *
+ * const redis = new Redis(process.env.REDIS_URL);
+ *
+ * const program = Effect.gen(function* () {
+ *   // Create a semaphore that allows 5 concurrent operations
+ *   const sem = yield* DistributedSemaphore.make("my-resource", {
+ *     limit: 5,
+ *     ttl: "30 seconds",
+ *   });
+ *
+ *   // Acquire 2 permits, run effect, release when done
+ *   yield* sem.withPermits(2)(
+ *     Effect.gen(function* () {
+ *       // Only 2 of the 5 slots are used
+ *       yield* doSomethingLimited();
+ *     })
+ *   );
+ *
+ *   // For mutex behavior, use limit=1 and withPermits(1)
+ *   const mutex = yield* DistributedSemaphore.make("my-lock", { limit: 1 });
+ *   yield* mutex.withPermits(1)(criticalSection);
+ * });
+ *
+ * program.pipe(
+ *   Effect.provide(RedisBacking.layer(redis)),
+ *   Effect.runPromise
+ * );
+ * ```
+ *
+ * @module
+ */
+export * as Backing from "./Backing.js";
+export { DistributedSemaphoreBacking, SemaphoreBackingError, } from "./Backing.js";
+export * as DistributedSemaphore from "./DistributedSemaphore.js";
+export { LockLostError } from "./Errors.js";
+export * as RedisBacking from "./RedisBacking.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAGH,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AACxC,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAGtB,OAAO,KAAK,oBAAoB,MAAM,2BAA2B,CAAC;AAGlE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,55 @@
+/**
+ * Effect Distributed Semaphore
+ *
+ * A distributed semaphore library for Effect with pluggable backends.
+ * Implements a multi-semaphore that can be used to implement:
+ * - Mutex (limit=1, permits=1)
+ * - Semaphore (limit=N, permits=1)
+ * - Multi-semaphore (limit=N, permits=M)
+ *
+ * @example
+ * ```ts
+ * import { DistributedSemaphore, RedisBacking } from "effect-distributed-lock";
+ * import { Effect } from "effect";
+ * import Redis from "ioredis";
+ *
+ * const redis = new Redis(process.env.REDIS_URL);
+ *
+ * const program = Effect.gen(function* () {
+ *   // Create a semaphore that allows 5 concurrent operations
+ *   const sem = yield* DistributedSemaphore.make("my-resource", {
+ *     limit: 5,
+ *     ttl: "30 seconds",
+ *   });
+ *
+ *   // Acquire 2 permits, run effect, release when done
+ *   yield* sem.withPermits(2)(
+ *     Effect.gen(function* () {
+ *       // Only 2 of the 5 slots are used
+ *       yield* doSomethingLimited();
+ *     })
+ *   );
+ *
+ *   // For mutex behavior, use limit=1 and withPermits(1)
+ *   const mutex = yield* DistributedSemaphore.make("my-lock", { limit: 1 });
+ *   yield* mutex.withPermits(1)(criticalSection);
+ * });
+ *
+ * program.pipe(
+ *   Effect.provide(RedisBacking.layer(redis)),
+ *   Effect.runPromise
+ * );
+ * ```
+ *
+ * @module
+ */
+// Backing interface
+export * as Backing from "./Backing.js";
+export { DistributedSemaphoreBacking, SemaphoreBackingError, } from "./Backing.js";
+// Core module (namespace with types and functions)
+export * as DistributedSemaphore from "./DistributedSemaphore.js";
+// Errors
+export { LockLostError } from "./Errors.js";
+// Redis backing
+export * as RedisBacking from "./RedisBacking.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,oBAAoB;AACpB,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AACxC,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAEtB,mDAAmD;AACnD,OAAO,KAAK,oBAAoB,MAAM,2BAA2B,CAAC;AAElE,SAAS;AACT,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,gBAAgB;AAChB,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-distributed-lock",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "A distributed semaphore library for Effect with pluggable backends",
   "license": "MIT",
   "repository": {

package/bun.lock

@@ -1,64 +0,0 @@
-{
-  "lockfileVersion": 1,
-  "workspaces": {
-    "": {
-      "name": "effect-distributed-lock",
-      "dependencies": {
-        "effect": "^3.19.13",
-      },
-      "devDependencies": {
-        "@types/bun": "latest",
-        "ioredis": "^5.4.1",
-      },
-      "peerDependencies": {
-        "effect": "^3.0.0",
-        "ioredis": "^5.0.0",
-        "typescript": "^5",
-      },
-      "optionalPeers": [
-        "ioredis",
-      ],
-    },
-  },
-  "packages": {
-    "@ioredis/commands": ["@ioredis/commands@1.4.0", "", {}, "sha512-aFT2yemJJo+TZCmieA7qnYGQooOS7QfNmYrzGtsYd3g9j5iDP8AimYYAesf79ohjbLG12XxC4nG5DyEnC88AsQ=="],
-
-    "@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
-
-    "@types/bun": ["@types/bun@1.3.5", "", { "dependencies": { "bun-types": "1.3.5" } }, "sha512-RnygCqNrd3srIPEWBd5LFeUYG7plCoH2Yw9WaZGyNmdTEei+gWaHqydbaIRkIkcbXwhBT94q78QljxN0Sk838w=="],
-
-    "@types/node": ["@types/node@25.0.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA=="],
-
-    "bun-types": ["bun-types@1.3.5", "", { "dependencies": { "@types/node": "*" } }, "sha512-inmAYe2PFLs0SUbFOWSVD24sg1jFlMPxOjOSSCYqUgn4Hsc3rDc7dFvfVYjFPNHtov6kgUeulV4SxbuIV/stPw=="],
-
-    "cluster-key-slot": ["cluster-key-slot@1.1.2", "", {}, "sha512-RMr0FhtfXemyinomL4hrWcYJxmX6deFdCxpJzhDttxgO1+bcCnkk+9drydLVDmAMG7NE6aN/fl4F7ucU/90gAA=="],
-
-    "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
-
-    "denque": ["denque@2.1.0", "", {}, "sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw=="],
-
-    "effect": ["effect@3.19.13", "", { "dependencies": { "@standard-schema/spec": "^1.0.0", "fast-check": "^3.23.1" } }, "sha512-8MZ783YuHRwHZX2Mmm+bpGxq+7XPd88sWwYAz2Ysry80sEKpftDZXs2Hg9ZyjESi1IBTNHF0oDKe0zJRkUlyew=="],
-
-    "fast-check": ["fast-check@3.23.2", "", { "dependencies": { "pure-rand": "^6.1.0" } }, "sha512-h5+1OzzfCC3Ef7VbtKdcv7zsstUQwUDlYpUTvjeUsJAssPgLn7QzbboPtL5ro04Mq0rPOsMzl7q5hIbRs2wD1A=="],
-
-    "ioredis": ["ioredis@5.8.2", "", { "dependencies": { "@ioredis/commands": "1.4.0", "cluster-key-slot": "^1.1.0", "debug": "^4.3.4", "denque": "^2.1.0", "lodash.defaults": "^4.2.0", "lodash.isarguments": "^3.1.0", "redis-errors": "^1.2.0", "redis-parser": "^3.0.0", "standard-as-callback": "^2.1.0" } }, "sha512-C6uC+kleiIMmjViJINWk80sOQw5lEzse1ZmvD+S/s8p8CWapftSaC+kocGTx6xrbrJ4WmYQGC08ffHLr6ToR6Q=="],
-
-    "lodash.defaults": ["lodash.defaults@4.2.0", "", {}, "sha512-qjxPLHd3r5DnsdGacqOMU6pb/avJzdh9tFX2ymgoZE27BmjXrNy/y4LoaiTeAb+O3gL8AfpJGtqfX/ae2leYYQ=="],
-
-    "lodash.isarguments": ["lodash.isarguments@3.1.0", "", {}, "sha512-chi4NHZlZqZD18a0imDHnZPrDeBbTtVN7GXMwuGdRH9qotxAjYs3aVLKc7zNOG9eddR5Ksd8rvFEBc9SsggPpg=="],
-
-    "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
-
-    "pure-rand": ["pure-rand@6.1.0", "", {}, "sha512-bVWawvoZoBYpp6yIoQtQXHZjmz35RSVHnUOTefl8Vcjr8snTPY1wnpSPMWekcFwbxI6gtmT7rSYPFvz71ldiOA=="],
-
-    "redis-errors": ["redis-errors@1.2.0", "", {}, "sha512-1qny3OExCf0UvUV/5wpYKf2YwPcOqXzkwKKSmKHiE6ZMQs5heeE/c8eXK+PNllPvmjgAbfnsbpkGZWy8cBpn9w=="],
-
-    "redis-parser": ["redis-parser@3.0.0", "", { "dependencies": { "redis-errors": "^1.0.0" } }, "sha512-DJnGAeenTdpMEH6uAJRK/uiyEIH9WVsUmoLwzudwGJUwZPp80PDBWPHXSAGNPwNvIXAbe7MSUB1zQFugFml66A=="],
-
-    "standard-as-callback": ["standard-as-callback@2.1.0", "", {}, "sha512-qoRRSyROncaz1z0mvYqIE4lCd9p2R90i6GxW3uZv5ucSu8tU7B5HXUP1gG8pVZsYNVaXjk8ClXHPttLyxAL48A=="],
-
-    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
-
-    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
-  }
-}

package/examples/kitchen-sink.ts

@@ -1,119 +0,0 @@
-/**
- * Example usage of the distributed semaphore library.
- *
- * Run with: bun run example.ts
- * Requires REDIS_URL environment variable.
- */
-import { Effect, Console, Duration, Option } from "effect";
-import Redis from "ioredis";
-import { DistributedSemaphore, RedisBacking } from "../src/index.ts";
-
-// Create Redis client
-const redis = new Redis(process.env.REDIS_URL ?? "redis://localhost:6379");
-
-// Create the Redis backing layer
-const RedisLayer = RedisBacking.layer(redis, {
-  keyPrefix: "example:",
-});
-
-// Example 1: Using withPermits for a critical section (mutex behavior)
-const example1 = Effect.gen(function* () {
-  yield* Console.log("=== Example 1: Mutex with withPermits(1) ===");
-
-  const mutex = yield* DistributedSemaphore.make("my-resource", {
-    limit: 1, // Acts as a mutex
-    ttl: Duration.seconds(10),
-  });
-
-  yield* mutex.withPermits(1)(
-    Effect.gen(function* () {
-      yield* Console.log("Lock acquired! Doing critical work...");
-      yield* Effect.sleep(2000);
-      yield* Console.log("Critical work done!");
-    })
-  );
-
-  yield* Console.log("Lock released automatically");
-});
-
-// Example 2: Using withPermitsIfAvailable (non-blocking)
-const example2 = Effect.gen(function* () {
-  yield* Console.log("\n=== Example 2: withPermitsIfAvailable ===");
-
-  const mutex = yield* DistributedSemaphore.make("another-resource", {
-    limit: 1,
-    ttl: Duration.seconds(10),
-  });
-
-  const result = yield* mutex.withPermitsIfAvailable(1)(
-    Effect.gen(function* () {
-      yield* Console.log("Got the lock without waiting!");
-      return "success";
-    })
-  );
-
-  if (Option.isSome(result)) {
-    yield* Console.log(`Result: ${result.value}`);
-  } else {
-    yield* Console.log("Could not acquire lock immediately");
-  }
-});
-
-// Example 3: Semaphore with multiple permits
-const example3 = Effect.gen(function* () {
-  yield* Console.log("\n=== Example 3: Semaphore with limit=5 ===");
-
-  const sem = yield* DistributedSemaphore.make("pool-resource", {
-    limit: 5, // Allow 5 concurrent operations
-    ttl: Duration.seconds(10),
-  });
-
-  // Acquire 2 permits out of 5
-  yield* sem.withPermits(2)(
-    Effect.gen(function* () {
-      yield* Console.log("Acquired 2 permits (3 still available)");
-      const count = yield* sem.currentCount;
-      yield* Console.log(`Current active permits: ${count}`);
-      yield* Effect.sleep(1000);
-    })
-  );
-
-  yield* Console.log("Released 2 permits");
-});
-
-// Example 4: Manual scope management with take()
-const example4 = Effect.gen(function* () {
-  yield* Console.log("\n=== Example 4: Manual acquire with Scope ===");
-
-  const mutex = yield* DistributedSemaphore.make("manual-resource", {
-    limit: 1,
-    ttl: Duration.seconds(10),
-  });
-
-  // Using Effect.scoped to manage the lock lifecycle
-  yield* Effect.scoped(
-    Effect.gen(function* () {
-      yield* mutex.take(1);
-      yield* Console.log("Permit acquired via take(1)");
-      yield* Effect.sleep(1000);
-      yield* Console.log("About to exit scope...");
-      // Permits are automatically released when scope closes
-    })
-  );
-
-  yield* Console.log("Scope closed, permit released");
-});
-
-// Run all examples
-const main = Effect.gen(function* () {
-  yield* example1;
-  yield* example2;
-  yield* example3;
-  yield* example4;
-  yield* Console.log("\n✓ All examples completed!");
-}).pipe(
-  Effect.ensuring(Effect.promise(() => redis.quit())),
-  Effect.provide(RedisLayer)
-);
-
-Effect.runPromise(main).catch(console.error);

package/examples/push.ts

@@ -1,109 +0,0 @@
-/**
- * Demonstrates concurrent effects competing for a distributed lock.
- *
- * This example runs two scenarios:
- * 1. With push-based acquisition DISABLED (polling only)
- * 2. With push-based acquisition ENABLED (pub/sub notifications)
- *
- * You'll see how push-based acquisition is faster because waiters are
- * notified immediately when permits are released, rather than polling.
- *
- * Run with: bun run examples/push.ts
- * Requires REDIS_URL environment variable or local Redis at localhost:6379.
- */
-import { Console, Duration, Effect, Schedule } from "effect";
-import Redis from "ioredis";
-import { DistributedSemaphore, RedisBacking } from "../src/index.ts";
-
-const redis = new Redis(process.env.REDIS_URL ?? "redis://localhost:6379");
-
-// Helper to create a task that competes for the lock
-const makeTask = (
-  id: number,
-  mutex: DistributedSemaphore.DistributedSemaphore
-) =>
-  Effect.gen(function* () {
-    yield* Console.log(`[Task ${id}] Starting, waiting for lock...`);
-    const startWait = Date.now();
-
-    yield* mutex.withPermits(1)(
-      Effect.gen(function* () {
-        const waitTime = Date.now() - startWait;
-        yield* Console.log(
-          `[Task ${id}] 🔒 Lock acquired! (waited ${waitTime}ms)`
-        );
-
-        // Simulate some work
-        yield* Effect.sleep(Duration.millis(200));
-
-        yield* Console.log(`[Task ${id}] 🔓 Releasing lock...`);
-      })
-    );
-
-    yield* Console.log(`[Task ${id}] Done`);
-  });
-
-// Run a scenario with the given configuration
-const runScenario = (name: string, pushEnabled: boolean) =>
-  Effect.gen(function* () {
-    yield* Console.log(`\n${"=".repeat(60)}`);
-    yield* Console.log(`${name}`);
-    yield* Console.log(`Push-based acquisition: ${pushEnabled ? "ON" : "OFF"}`);
-    yield* Console.log(`${"=".repeat(60)}\n`);
-
-    const startTime = Date.now();
-
-    // Create mutex with a unique key per scenario to avoid interference
-    const mutex = yield* DistributedSemaphore.make(
-      `concurrent-example-${pushEnabled ? "push" : "poll"}`,
-      {
-        acquireRetryPolicy: Schedule.spaced(Duration.millis(500)),
-        limit: 1, // Mutex - only one holder at a time
-      }
-    );
-
-    // Run 3 tasks concurrently, all competing for the same lock
-    yield* Effect.all(
-      [makeTask(1, mutex), makeTask(2, mutex), makeTask(3, mutex)],
-      { concurrency: 3 }
-    );
-
-    const totalTime = Date.now() - startTime;
-    yield* Console.log(`\n⏱️  Total time: ${totalTime}ms\n`);
-  });
-
-// Run both scenarios
-const main = Effect.gen(function* () {
-  yield* Console.log("🚀 Distributed Lock Concurrency Demo");
-  yield* Console.log(
-    "Showing 3 concurrent tasks competing for a mutex (limit=1)"
-  );
-
-  // Run WITHOUT push (polling only)
-  const RedisLayerNoPush = RedisBacking.layer(redis, {
-    keyPrefix: "concurrent-demo:",
-    pushBasedAcquireEnabled: false,
-  });
-  yield* runScenario("Scenario 1: Polling Only", false).pipe(
-    Effect.provide(RedisLayerNoPush)
-  );
-
-  // Run WITH push (pub/sub notifications)
-  const RedisLayerWithPush = RedisBacking.layer(redis, {
-    keyPrefix: "concurrent-demo:",
-    pushBasedAcquireEnabled: true,
-  });
-  yield* runScenario("Scenario 2: Push-Based (Pub/Sub)", true).pipe(
-    Effect.provide(RedisLayerWithPush)
-  );
-
-  yield* Console.log("✅ Demo complete!");
-  yield* Console.log(
-    "Notice how push-based acquisition completes faster because"
-  );
-  yield* Console.log(
-    "waiters are notified immediately instead of waiting for the next poll.\n"
-  );
-}).pipe(Effect.ensuring(Effect.promise(() => redis.quit())));
-
-Effect.runPromise(main).catch(console.error);

package/tsconfig.json

@@ -1,35 +0,0 @@
-{
-  "compilerOptions": {
-    // Environment setup & latest features
-    "lib": ["ESNext"],
-    "target": "ESNext",
-    "module": "NodeNext",
-    "moduleDetection": "force",
-    "jsx": "react-jsx",
-    "allowJs": true,
-
-    // Bundler mode
-    "moduleResolution": "nodenext",
-    "verbatimModuleSyntax": true,
-
-    // Build output
-    "rootDir": "src",
-    "outDir": "dist",
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-
-    // Best practices
-    "strict": true,
-    "skipLibCheck": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedIndexedAccess": true,
-
-    // Some stricter flags (disabled by default)
-    "noUnusedLocals": false,
-    "noUnusedParameters": false,
-    "noPropertyAccessFromIndexSignature": false
-  },
-  "include": ["src"],
-  "exclude": ["node_modules", "dist"]
-}