@edgelock/client

Edge-native distributed lock client for JavaScript runtimes (Node.js, Bun, Deno, Cloudflare Workers, Vercel, Netlify, Fly.io).

Installation

npm install @edgelock/client
# or
yarn add @edgelock/client
# or
bun add @edgelock/client

Usage

import { EdgeLock } from "@edgelock/client";

// Configure the client with your API key
EdgeLock.configure({ apiKey: process.env.EDGELOCK_KEY! });

async function processPayment(orderId: string) {
  // Acquire a lock with a 60-second TTL
  const lock = await EdgeLock.acquire("payment-processing", { ttl: 60 });

  // If the lock couldn't be acquired, exit
  if (!lock) {
    throw new Error("Could not obtain lock");
  }

  try {
    // Do your critical work here
    await processPayment(orderId);
  } finally {
    // Always release the lock when done
    await lock.release();
  }
}

API Reference

Configuration

EdgeLock.configure({
  apiKey: string;       // Required: Your EdgeLock API key
  baseUrl?: string;     // Optional: Custom API URL (default: https://api.edgelock.dev)
});

Lock Acquisition

const lock = await EdgeLock.acquire(
  key: string,           // The lock key to acquire
  options?: {
    ttl?: number;        // Time-to-live in seconds (1-86400)
    timeout?: number;    // Max time to wait in ms before giving up
    signal?: AbortSignal; // AbortSignal to cancel the request
  }
);

// Returns a Lock object or null if acquisition failed

Lock Operations

// Lock properties
lock.key: string         // The lock key
lock.lockId: string      // Unique ID for this lock
lock.expiresAt: number   // Unix timestamp (ms) when lock expires

// Release the lock
await lock.release(): Promise<boolean>

// Extend the lock with a new TTL
await lock.extend(ttl: number): Promise<void>

Status Check

import { status } from "@edgelock/client";

const result = await status(key: string);
// Returns:
// {
//   locked: boolean,
//   lockId: string | null,
//   expiresAt: number | null
// }

Error Handling

import { EdgeLockError } from "@edgelock/client";

try {
  const lock = await EdgeLock.acquire("my-key");
  // ...
} catch (error) {
  if (error instanceof EdgeLockError) {
    console.error(
      `EdgeLock error: ${error.message}, code: ${error.code}, status: ${error.status}`
    );
  } else {
    console.error("Unexpected error:", error);
  }
}

Error codes: LOCKED, INVALID_TTL, INVALID_BODY, NOT_FOUND, UNKNOWN_KEY, UNAUTHORIZED, INTERNAL_ERROR

License

MIT