@toa.io/atomicity 1.0.0-alpha.282 → 1.0.0-alpha.284

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.0.0-alpha.284](https://github.com/toa-io/toa/compare/v1.0.0-alpha.283...v1.0.0-alpha.284) (2026-09-05)
+
+### Features
+
+* **atomicity:** a replica can be told what it owns, not only ask ([f7b56b9](https://github.com/toa-io/toa/commit/f7b56b99cc43313f3f855df658a80fdc0659689e))
+
+
+# [1.0.0-alpha.283](https://github.com/toa-io/toa/compare/v1.0.0-alpha.282...v1.0.0-alpha.283) (2026-09-04)
+
+**Note:** Version bump only for package @toa.io/atomicity
+
+
+
+
+
 # [1.0.0-alpha.282](https://github.com/toa-io/toa/compare/v1.0.0-alpha.281...v1.0.0-alpha.282) (2026-09-03)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/atomicity",
-  "version": "1.0.0-alpha.282",
+  "version": "1.0.0-alpha.284",
   "type": "module",
   "description": "Toa Atomicity Connector",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "@sesamecare-oss/redlock": "1.4.0",
-    "@toa.io/core": "1.0.0-alpha.282",
+    "@toa.io/core": "1.0.0-alpha.284",
     "ioredis": "6.0.0",
     "n-and-i": "0.3.2",
     "openspan": "1.0.0-alpha.277"
@@ -26,5 +26,5 @@
   "scripts": {
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
-  "gitHead": "4007c814725dd015d3bbebb9a28e28a247645c4f"
+  "gitHead": "006755556879e91e8d68fa86753aa3b475bdf4bf"
 }

package/readme.md

@@ -18,6 +18,26 @@ Returns `null` while this replica owns nothing — at startup, during a rollout,
 
 Uses [n-and-i](https://github.com/temich/nandi).
 
+### Being told
+
+`slots` answers whoever asks. A consumer that asks rarely — once an hour, say — samples one
+moment, and a rollout passing through that moment costs it the whole hour. `onassigned` tells it
+instead.
+
+```javascript
+const off = atom.onassigned((assignment) => { … }) // { i, n } — or null, owning nothing
+```
+
+Called with the assignment this replica holds, and again whenever it changes: one arrived, was
+lost, or the group resized. A change and not a heartbeat — a group that stays as it is never
+calls back. It is called once as it is added, with the assignment as it stands, so a listener
+arriving after the group settled is not left waiting for something that has already happened.
+
+The answer removes the listener. A listener that raises ends the loop it was told through, and
+that loop is what keeps this replica registered — so this replica owns nothing from that moment,
+`slots` answers `null`, and it stands down. What to do about the exception is the runtime's;
+nothing here catches it.
+
 ## Metering
 
 Debt the group has run up under each key, in milliseconds. A call adds its own deltas and answers

package/src/atom.js

@@ -15,6 +15,9 @@ export class Atom extends Connector {
   /** @type {{ i: number, n: number } | null} */
   #assignment = null
 
+  /** @type {Set<(assignment: { i: number, n: number } | null) => void>} */
+  #listeners = new Set()
+
   /** @type {AbortController} */
   #abort
 
@@ -60,6 +63,29 @@ export class Atom extends Connector {
     return owned
   }
 
+  /**
+   * Calls `listener` with the assignment this replica holds, and again whenever it changes —
+   * one arrived, was lost, or the group resized. Answers with what removes the listener again.
+   *
+   * A change and not a heartbeat: a group that stays as it is never calls back. It is called
+   * once as it is added, with the claim as it stands, so that a listener arriving after the
+   * group settled is not left waiting for something that has already happened.
+   *
+   * This is what `slots` cannot say. Reading answers a consumer that asks often, where a stale
+   * answer costs one cycle; a consumer that asks rarely needs to be told, or it samples the
+   * one moment a rollout was passing through and stands down for a whole cycle.
+   *
+   * @param listener {(assignment: { i: number, n: number } | null) => void}
+   * @returns {() => void}
+   */
+  onassigned (listener) {
+    this.#listeners.add(listener)
+
+    listener(this.#assignment)
+
+    return () => this.#listeners.delete(listener)
+  }
+
   /**
    * Debt the group has run up under each key, in milliseconds: every call adds its own deltas
    * and reads back where the group stands, so a replica reports only what it has spent and
@@ -146,9 +172,22 @@ export class Atom extends Connector {
       console: this.#console
     })
 
-    // the loop yields when ownership changes, which is exactly when work has to be handed over
-    for await (const { i, n } of loop)
-      this.#assignment = i === null ? null : { i, n }
+    try {
+      // the loop yields when ownership changes, which is exactly when work has to be handed over
+      for await (const { i, n } of loop) {
+        this.#assignment = i === null ? null : { i, n }
+
+        for (const listener of this.#listeners) listener(this.#assignment)
+      }
+    } finally {
+      /*
+       * The loop is what keeps this replica registered, so once it has ended — because it was
+       * aborted, or because a listener raised through it — this replica owns nothing. Left as
+       * it was, the last assignment would answer `slots` for as long as the process ran, and
+       * a claim nothing supports is what the whole of this exists to prevent.
+       */
+      this.#assignment = null
+    }
   }
 }