@zukhruf/lease 0.0.0-stage → 0.3.17

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ezzabuzaid
+
+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,3 +1,92 @@
-# Temporary Holding Version
+# @zukhruf/lease
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A lease gives one holder the right to act for a subject, for example a key of a mutex or the leadership of an election. The holder must know when it lost that right. This package gives the holder a signal that aborts when another holder may have the right. `@zukhruf/mutex`, `@zukhruf/single-flight`, and `@zukhruf/election` give out their leases with it.
+
+The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
+
+## A lease is a signal
+
+A holder gets a `Lease`. A lease has one property: `signal`, an `AbortSignal`.
+
+- The signal aborts one time, with a `LeaseLostError`, when another holder may have the right.
+- The signal never aborts when the holder releases the lease.
+
+The holder stops its work when the signal aborts. Give the signal to each call that takes a signal, and check it before each write:
+
+```ts
+import type { Lease } from '@zukhruf/lease';
+
+async function copyRows(lease: Lease, batches: Row[][]) {
+  for (const batch of batches) {
+    lease.signal.throwIfAborted();
+    await fetch('https://warehouse.example/rows', {
+      method: 'POST',
+      body: JSON.stringify(batch),
+      signal: lease.signal,
+    });
+  }
+}
+```
+
+## Tell a lost lease from other errors
+
+The reason of the signal is a `LeaseLostError`. Its `subject` names what the lease gave the right to. Its `cause`, when there is one, is what the issuer saw: for example, the error of a coordinator that refused the claim.
+
+```ts
+import { LeaseLostError } from '@zukhruf/lease';
+
+try {
+  await copyRows(lease, batches);
+} catch (error) {
+  if (error instanceof LeaseLostError) {
+    console.log(`Another holder may have ${error.subject} now.`, error.cause);
+  }
+  throw error;
+}
+```
+
+A catch with `instanceof LeaseLostError` works for the leases of each package that uses this package, because they all give the same class.
+
+## Give out a lease
+
+An issuer makes one `LeaseController` for each lease. It keeps the controller, and it gives the holder only the signal. `AbortController` and `AbortSignal` use the same split: only the code that has the controller can abort the signal.
+
+```ts
+import { type Lease, LeaseController } from '@zukhruf/lease';
+
+const controller = new LeaseController('orders');
+const lease: Lease = { signal: controller.signal };
+
+// The coordinator refused the claim, so another holder may have it:
+controller.lose(new Error('The coordinator refused the claim.'));
+
+// The holder released the lease:
+controller.end();
+```
+
+- `lose(cause?)` aborts the signal with `new LeaseLostError(subject, { cause })`. When you give no cause, the error has no `cause` property.
+- A lease is lost one time. A second `lose` keeps the reason of the first.
+- `end()` never aborts the signal. After `end()`, `lose` does nothing: the holder gave the right up, so it cannot lose it. A loss that the issuer sees late, after the release, does not reach the holder.
+- `end()` can be called again. It keeps the reason of an earlier loss.
+
+## A lease lasts for a session, not for a time
+
+In many systems, a lease ends after a time unless the holder renews it. A lease of zukhruf has no timer. It ends when the holder releases it, or when the holder's process stops: the operating system then frees the claim of that process. It is lost when the issuer decides that another holder may have the right, for example when a coordinator refuses the claim after a failover. Thus this package has no timer and no renew.
+
+## A lease warns the holder. It does not protect a resource
+
+A holder can stop for some time, for example in a long garbage collection, and then write. In that time, the issuer can see the loss and give the right to another holder. The holder writes before it checks its signal. Thus the signal is a warning, not a protection.
+
+To protect a resource, use a fencing token. The resource keeps the highest token that it accepted, and it refuses a write with a lower token. Fencing tokens are in [`@zukhruf/fencing`](../fencing). A lease and a fencing token are two concepts: some systems use a lease with no token, and others use a token with no lease. See [ADR 0001](./docs/adr/0001-a-lease-is-its-own-package-apart-from-fencing.md).
+
+## The same concepts in other systems
+
+| This package                         | Other systems                                                                                                                                                                                    |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Lease                                | Lease: Gray and Cheriton, "Leases: An Efficient Fault-Tolerant Mechanism for Distributed File Cache Consistency" (1989); Kubernetes `coordination.k8s.io/v1` `Lease`; etcd `concurrency.Session` |
+| `lease.signal` aborts                | etcd `Session.Done()` closes its channel; Go `ctx.Done()` closes                                                                                                                                 |
+| `LeaseLostError`                     | Hazelcast `LockOwnershipLostException`; Go `context.Cause(ctx)`                                                                                                                                  |
+| `LeaseController` and `Lease`        | Web `AbortController` and `AbortSignal`; Go `context.WithCancelCause`, which returns the context and its cancel function                                                                         |
+| `lose(cause)` keeps the first reason | Go `cancel(cause)`: a second call does nothing; `AbortController.abort(reason)`: a second call does nothing                                                                                      |
+
+The leases of Gray and Cheriton, Kubernetes, and etcd last for a time, and the holder renews them. The leases of zukhruf last for a session.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { Lease } from './lease.ts';
+export { LeaseController } from './lease-controller.ts';
+export { LeaseLostError } from './lease-lost-error.ts';
+//# 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,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { LeaseController } from "./lease-controller.js";
+export { LeaseLostError } from "./lease-lost-error.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":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/lease-controller.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The issuer's side of one lease. The issuer keeps the controller and gives
+ * the holder only `signal`, as an `AbortController` keeps its abort and
+ * gives out its `AbortSignal`.
+ */
+export declare class LeaseController {
+    #private;
+    constructor(subject: string);
+    get signal(): AbortSignal;
+    /**
+     * Another holder may have the right now. Aborts `signal` with a
+     * `LeaseLostError` that carries `cause`, when one is given. A lease is lost
+     * at most once, and never after it ended: a released right is not this
+     * holder's to lose.
+     */
+    lose(cause?: unknown): void;
+    /** The holder released the lease. `signal` keeps its state, and a later `lose` does nothing. */
+    end(): void;
+}
+//# sourceMappingURL=lease-controller.d.ts.map

package/dist/lease-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-controller.d.ts","sourceRoot":"","sources":["../src/lease-controller.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,qBAAa,eAAe;;gBAMd,OAAO,EAAE,MAAM;IAI3B,IAAI,MAAM,IAAI,WAAW,CAExB;IAED;;;;;OAKG;IACH,IAAI,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI;IAW3B,gGAAgG;IAChG,GAAG,IAAI,IAAI;CAGZ"}

package/dist/lease-controller.js

@@ -0,0 +1,35 @@
+import { LeaseLostError } from "./lease-lost-error.js";
+/**
+ * The issuer's side of one lease. The issuer keeps the controller and gives
+ * the holder only `signal`, as an `AbortController` keeps its abort and
+ * gives out its `AbortSignal`.
+ */
+export class LeaseController {
+    #subject;
+    #lost = new AbortController();
+    /** Aborts once the lease ends, by a loss or by `end()`. */
+    #ended = new AbortController();
+    constructor(subject) {
+        this.#subject = subject;
+    }
+    get signal() {
+        return this.#lost.signal;
+    }
+    /**
+     * Another holder may have the right now. Aborts `signal` with a
+     * `LeaseLostError` that carries `cause`, when one is given. A lease is lost
+     * at most once, and never after it ended: a released right is not this
+     * holder's to lose.
+     */
+    lose(cause) {
+        if (this.#ended.signal.aborted)
+            return;
+        this.#ended.abort();
+        this.#lost.abort(new LeaseLostError(this.#subject, cause === undefined ? undefined : { cause }));
+    }
+    /** The holder released the lease. `signal` keeps its state, and a later `lose` does nothing. */
+    end() {
+        this.#ended.abort();
+    }
+}
+//# sourceMappingURL=lease-controller.js.map

package/dist/lease-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-controller.js","sourceRoot":"","sources":["../src/lease-controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,OAAO,eAAe;IACjB,QAAQ,CAAS;IACjB,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;IACvC,2DAA2D;IAClD,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IAExC,YAAY,OAAe;QACzB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,KAAe;QAClB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO;QACvC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,IAAI,CAAC,KAAK,CAAC,KAAK,CACd,IAAI,cAAc,CAChB,IAAI,CAAC,QAAQ,EACb,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAC5C,CACF,CAAC;IACJ,CAAC;IAED,gGAAgG;IAChG,GAAG;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;CACF"}

package/dist/lease-lost-error.d.ts

@@ -0,0 +1,6 @@
+/** The holder may have lost the right to its subject: another holder may have it now. */
+export declare class LeaseLostError extends Error {
+    readonly subject: string;
+    constructor(subject: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=lease-lost-error.d.ts.map

package/dist/lease-lost-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-lost-error.d.ts","sourceRoot":"","sources":["../src/lease-lost-error.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAQpD"}

package/dist/lease-lost-error.js

@@ -0,0 +1,10 @@
+/** The holder may have lost the right to its subject: another holder may have it now. */
+export class LeaseLostError extends Error {
+    subject;
+    constructor(subject, options) {
+        super(`Lost the lease on ${JSON.stringify(subject)}: another holder may have it now.`, options);
+        this.name = 'LeaseLostError';
+        this.subject = subject;
+    }
+}
+//# sourceMappingURL=lease-lost-error.js.map

package/dist/lease-lost-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-lost-error.js","sourceRoot":"","sources":["../src/lease-lost-error.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,OAAO,CAAS;IAEzB,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CACH,qBAAqB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,mCAAmC,EAC/E,OAAO,CACR,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}

package/dist/lease.d.ts

@@ -0,0 +1,9 @@
+/** The holder's view of a lease: act on the subject until `signal` aborts. */
+export interface Lease {
+    /**
+     * Aborts once, with a `LeaseLostError`, when another holder may have the
+     * right. It never aborts when the holder releases the lease.
+     */
+    readonly signal: AbortSignal;
+}
+//# sourceMappingURL=lease.d.ts.map

package/dist/lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.d.ts","sourceRoot":"","sources":["../src/lease.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,WAAW,KAAK;IACpB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B"}

package/dist/lease.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=lease.js.map

package/dist/lease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.js","sourceRoot":"","sources":["../src/lease.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@zukhruf/lease",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.17",
+  "description": "A lease and its loss: the holder gets an AbortSignal that aborts once, with LeaseLostError, when another holder may have the right. The issuer keeps a LeaseController.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JanuaryLabs/zukhruf",
+    "directory": "packages/lease"
+  },
+  "bugs": {
+    "url": "https://github.com/JanuaryLabs/zukhruf/issues"
+  },
+  "homepage": "https://github.com/JanuaryLabs/zukhruf/tree/main/packages/lease#readme",
+  "keywords": [
+    "lease",
+    "lock",
+    "leader-election",
+    "abortsignal",
+    "abortcontroller",
+    "distributed"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@zukhruf/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/spec/**",
+    "!**/*.tsbuildinfo",
+    "!**/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}