@toa.io/atomicity 1.0.0-alpha.283 → 1.0.0-alpha.286

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/atomicity",
-  "version": "1.0.0-alpha.283",
+  "version": "1.0.0-alpha.286",
   "type": "module",
   "description": "Toa Atomicity Connector",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -18,13 +18,13 @@
   },
   "dependencies": {
     "@sesamecare-oss/redlock": "1.4.0",
-    "@toa.io/core": "1.0.0-alpha.283",
+    "@toa.io/core": "1.0.0-alpha.286",
     "ioredis": "6.0.0",
     "n-and-i": "0.3.2",
-    "openspan": "1.0.0-alpha.277"
+    "openspan": "1.0.0-alpha.286"
   },
   "scripts": {
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
-  "gitHead": "2f52b023bed0ccb2ecdb2b82fe59fbe38bf282e1"
+  "gitHead": "81f3d0688f17668b902be336d1749cc715edcdb6"
 }

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
@@ -42,7 +62,7 @@ Uses [redlock](https://github.com/sesamecare/redlock). The key is written to eve
 majority holding it is the lock, so a minority can be lost or failed over without invalidating one.
 Against a single address there is no majority to lose: a restart that drops the key, or a failover
 to a replica that has not received it, can leave two holders. Entity writes do not rest on either —
-they have `_version`.
+they have `VERSION`.
 
 The routine is given an `AbortSignal` and a context. Extension can fail while the routine runs, and
 the signal is how it says so:
@@ -72,8 +92,8 @@ Requires Redis.
 ```yaml
 # context.toa.yaml
 atomicity:
-  redis: redis://redis.example.com    # one address, or an odd number of them
-  interval: 5000                      # how often a replica registers, milliseconds
+  redis: redis://redis.example.com # one address, or an odd number of them
+  interval: 5000 # how often a replica registers, milliseconds
 ```
 
 Several addresses are **independent servers**, not the nodes of a cluster. The lock is taken on a

package/src/atom.js

@@ -5,7 +5,7 @@ import { Connector } from '@toa.io/core'
  * What one group of replicas decides together, in one place: which of them owns what, what they
  * have spent between them, and which of them holds a name while it works.
  *
- * @implements {toa.core.atomicity.Atom}
+ * @implements {import('@toa.io/core/types').atomicity.Atom}
  */
 export class Atom extends Connector {
   #connection
@@ -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
 
@@ -24,7 +27,7 @@ export class Atom extends Connector {
   /** the loop's own logger, carrying the group every line belongs to */
   #console
 
-  constructor (connection, name, interval) {
+  constructor(connection, name, interval) {
     super()
 
     this.#connection = connection
@@ -47,7 +50,7 @@ export class Atom extends Connector {
    * @param total {number}
    * @returns {number[] | null} null while this replica owns nothing
    */
-  slots (total) {
+  slots(total) {
     const assignment = this.#assignment
 
     if (assignment === null) return null
@@ -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
@@ -69,7 +95,7 @@ export class Atom extends Connector {
    * @param {number[]} deltas
    * @returns {Promise<number[]>}
    */
-  async meter (keys, deltas) {
+  async meter(keys, deltas) {
     const meter = this.#connection.meter
 
     if (meter === undefined)
@@ -86,7 +112,7 @@ export class Atom extends Connector {
    * @param {() => Promise<any>} routine
    * @returns {Promise<any>}
    */
-  async lock (keys, routine) {
+  async lock(keys, routine) {
     const redlock = this.#connection.redlock
 
     if (redlock === undefined)
@@ -102,13 +128,13 @@ export class Atom extends Connector {
    *
    * @private
    */
-  #keys (kind, keys) {
+  #keys(kind, keys) {
     if (typeof keys === 'string') keys = [keys]
 
     return keys.map((key) => `${ATOM}:${this.#name}:${kind}:${key}`)
   }
 
-  async open () {
+  async open() {
     const redis = this.#connection.redis
 
     // without a Redis nothing can be owned exclusively, so nothing is claimed at all
@@ -118,7 +144,7 @@ export class Atom extends Connector {
     this.#discovering = this.#discover(redis)
   }
 
-  async close () {
+  async close() {
     this.#assignment = null
 
     this.#abort?.abort()
@@ -134,7 +160,7 @@ export class Atom extends Connector {
    *
    * @private
    */
-  async #discover (redis) {
+  async #discover(redis) {
     const { discover } = await import('n-and-i')
 
     const loop = discover({
@@ -146,13 +172,26 @@ 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
+    }
   }
 }
 
-function override () {
+function override() {
   const value = Number(process.env.TOA_ATOMICITY_INTERVAL)
 
   return Number.isNaN(value) || value <= 0 ? undefined : value

package/src/connection.js

@@ -26,12 +26,14 @@ export class Connection extends Connector {
   /** @type {import('ioredis').Redis[]} */
   #clients = []
 
-  async open () {
+  async open() {
     const urls = resolve()
 
     if (urls.length === 0) {
-      console.warn('Atomicity is not configured, so nothing is owned and nothing is metered. ' +
-        'Set TOA_ATOMICITY_REDIS.')
+      console.warn(
+        'Atomicity is not configured, so nothing is owned and nothing is metered. ' +
+          'Set TOA_ATOMICITY_REDIS.'
+      )
 
       return
     }
@@ -56,8 +58,11 @@ export class Connection extends Connector {
     for (const client of this.#clients)
       // ioredis leaves `message` empty on a refused connection, where the code is the whole story
       client.on('error', (error) =>
-        console.warn('Atomicity is unreachable, so nothing is owned',
-          { host: client.options.host, error: error.code ?? error.message }))
+        console.warn('Atomicity is unreachable, so nothing is owned', {
+          host: client.options.host,
+          error: error.code ?? error.message
+        })
+      )
 
     this.redis = this.#clients[0]
 
@@ -75,7 +80,7 @@ export class Connection extends Connector {
     console.info('Atomicity connecting to redis', { nodes: this.#clients.length })
   }
 
-  async close () {
+  async close() {
     for (const client of this.#clients) client.disconnect()
 
     // a closed connection holds nothing: it is opened again with whatever is configured then,
@@ -89,7 +94,7 @@ export class Connection extends Connector {
 
 const OPTIONS = { enableReadyCheck: true }
 
-function resolve () {
+function resolve() {
   const value = process.env[VARIABLE]
 
   // an empty value is atomicity turned off, where an absent one in development is the
@@ -108,4 +113,8 @@ export const connection = () => (instance ??= new Connection())
 export const reset = () => (instance = undefined)
 
 export const VARIABLE = 'TOA_ATOMICITY_REDIS'
-const DEV = 'redis://localhost'
+/**
+ * Toa's own development stack is not on the conventional ports: the applications built on
+ * Toa are, and they share the machine. See CONTRIBUTING.md.
+ */
+const DEV = 'redis://localhost:31040'

package/src/factory.js

@@ -9,7 +9,7 @@ export class Factory {
    * @param {string} group
    * @param {object} [options]
    */
-  atom (group, options = {}) {
+  atom(group, options = {}) {
     return atom(group, options)
   }
 }
@@ -22,7 +22,7 @@ const atoms = new Map()
  * time in a group that has one replica, and every replica of that group would then be told it
  * owns half of what it does.
  */
-function atom (group, options) {
+function atom(group, options) {
   let atom = atoms.get(group)
 
   if (atom === undefined) {

package/src/meter.js

@@ -15,7 +15,7 @@
 export class Meter {
   #redis
 
-  constructor (redis) {
+  constructor(redis) {
     this.#redis = redis
 
     redis.defineCommand(COMMAND, { lua: SCRIPT })
@@ -28,7 +28,7 @@ export class Meter {
    * @param {number[]} deltas
    * @returns {Promise<number[]>}
    */
-  async meter (keys, deltas) {
+  async meter(keys, deltas) {
     if (keys.length <= CHUNK) return this.#call(keys, deltas)
 
     // arguments are spread into the call, so a batch is split rather than risking the
@@ -36,13 +36,15 @@ export class Meter {
     const debts = []
 
     for (let i = 0; i < keys.length; i += CHUNK)
-      debts.push(...await this.#call(keys.slice(i, i + CHUNK), deltas.slice(i, i + CHUNK)))
+      debts.push(
+        ...(await this.#call(keys.slice(i, i + CHUNK), deltas.slice(i, i + CHUNK)))
+      )
 
     return debts
   }
 
   /** @private */
-  async #call (keys, deltas) {
+  async #call(keys, deltas) {
     // `defineCommand` extends the client at runtime
     return this.#redis[COMMAND](keys.length, ...keys, ...deltas)
   }

package/CHANGELOG.md

@@ -1,89 +0,0 @@
-# Change Log
-
-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.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
-
-* **atomicity:** nest every key under atom:<group>:<kind> ([348f39f](https://github.com/toa-io/toa/commit/348f39f72d805a24dd4fdbaa83aede47fe95b894))
-
-
-# [1.0.0-alpha.278](https://github.com/toa-io/toa/compare/v1.0.0-alpha.277...v1.0.0-alpha.278) (2026-09-03)
-
-**Note:** Version bump only for package @toa.io/atomicity
-
-
-
-
-
-# [1.0.0-alpha.277](https://github.com/toa-io/toa/compare/v1.0.0-alpha.276...v1.0.0-alpha.277) (2026-09-03)
-
-**Note:** Version bump only for package @toa.io/atomicity
-
-
-
-
-
-# [1.0.0-alpha.273](https://github.com/toa-io/toa/compare/v1.0.0-alpha.272...v1.0.0-alpha.273) (2026-09-02)
-
-**Note:** Version bump only for package @toa.io/atomicity
-
-
-
-
-
-# [1.0.0-alpha.272](https://github.com/toa-io/toa/compare/v1.0.0-alpha.271...v1.0.0-alpha.272) (2026-09-01)
-
-
-### Bug Fixes
-
-* **atomicity:** honour a cluster, and let it be unreachable ([c475d66](https://github.com/toa-io/toa/commit/c475d663ddf7329d86da517ccceee4cb03280e95))
-* **atomicity:** stop swallowing faults from the discovery loop ([449f79a](https://github.com/toa-io/toa/commit/449f79a011611f2e14ad5a325a9f7f7161433060))
-
-
-* feat(atomicity)!: take a quorum of independent servers ([862562f](https://github.com/toa-io/toa/commit/862562f24d77ec00127dbbd88d43802b208c643b))
-* refactor(atomicity)!: take one Redis, not a cluster ([b0a4770](https://github.com/toa-io/toa/commit/b0a4770dff5dfe8fee4b9ae637a4dd297454fcd4))
-* refactor(atomicity)!: take the lock manager from the stash ([4fd91eb](https://github.com/toa-io/toa/commit/4fd91eb2fdb68f7b87aaf16d182794bbc567ba57))
-* refactor(atomicity)!: make the connector a family, not a partitioner ([06fd63a](https://github.com/toa-io/toa/commit/06fd63ad6296b724ef83afccf4e4e25d0bcaf080))
-* refactor(atomicity)!: rename the connector and free it of the outbox ([21f1a41](https://github.com/toa-io/toa/commit/21f1a41aceafcfd35c7620014062fe46b54afa95))
-
-
-### Features
-
-* **atomicity:** make the interval a setting, and stop repeating n-and-i ([5c3a6d1](https://github.com/toa-io/toa/commit/5c3a6d1533751a21b7eb7d9c737f1a270bf5a5ae))
-* **atomicity:** meter what the group has spent ([bb1118a](https://github.com/toa-io/toa/commit/bb1118aa60bfeb43d3212f2495b7797445f003c3))
-
-
-### BREAKING CHANGES
-
-* `atomicity.redis` accepts a list again, of independent servers rather
-than cluster nodes, and refuses an even number of them.
-
-Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
-* `atomicity.redis` is a string. A list is refused at export.
-
-Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
-* `context.stash.lock` is gone; lock through `context.atom` instead.
-A stash pointer resolving to several addresses now uses the first.
-
-Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
-* `Factory.partition(group)` is `Factory.atom(group)`, and the
-`Partition` it returned is an `Atom`. `slots(total)` is unchanged.
-
-Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
-* `@toa.io/partitions.redis` is now `@toa.io/atomicity`, and its
-`lanes(total)` is `slots(total)`. Redis is declared as `atomicity` in the context
-rather than `outbox.redis`, and read from `TOA_ATOMICITY_REDIS`.
-`TOA_OUTBOX_PARTITION_INTERVAL` is `TOA_ATOMICITY_INTERVAL`.
-
-Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>