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

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 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)
+
+### Bug Fixes
+
+* **core:** a criteria list coerces every value in it ([37f57ee](https://github.com/toa-io/toa/commit/37f57ee8b50907a13722b7a558b881cccf105442))
+
+### Features
+
+* an operation states what it is ([b5e2f66](https://github.com/toa-io/toa/commit/b5e2f66c8bf67924e2eaaaa11f283dfb4d810981))
+* **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)
+
+### Bug Fixes
+
+* **core:** an operation returns the errors it declares, and nothing else ([1c2b819](https://github.com/toa-io/toa/commit/1c2b8193ae7fbe86bc1a25053a6044ee4dd16a4a))
+* **storages:** take `Maybe` from core, not from the deprecated package ([bcaeeb3](https://github.com/toa-io/toa/commit/bcaeeb3c76c89af34e94ff569a210d21b7e87f64))
+
+### Features
+
+* **extensions:** an extension declares what it puts on a component's context ([133bc2a](https://github.com/toa-io/toa/commit/133bc2aad1e45a2d4aa68a08a5e44ca48d3b7414))
+
+
 # [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)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/core",
-  "version": "1.0.0-alpha.282",
+  "version": "1.0.0-alpha.284",
   "type": "module",
   "description": "Toa Core",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -22,10 +22,10 @@
   },
   "dependencies": {
     "@rsql/parser": "1.6.0",
-    "@toa.io/generic": "1.0.0-alpha.282",
+    "@toa.io/generic": "1.0.0-alpha.283",
     "js-yaml": "5.4.1",
     "openspan": "1.0.0-alpha.277",
     "uuid": "14.0.2"
   },
-  "gitHead": "4007c814725dd015d3bbebb9a28e28a247645c4f"
+  "gitHead": "006755556879e91e8d68fa86753aa3b475bdf4bf"
 }

package/src/contract/reply.js

@@ -1,4 +1,3 @@
-import * as schemas from './schemas/index.js'
 import { Contract } from './contract.js'
 import { ResponseContractException } from '../exceptions.js'
 
@@ -25,21 +24,25 @@ export class Reply extends Contract {
       schema.properties.output = output
     }
 
-    if (errors !== undefined)
-      schema.properties.error = {
-        type: 'object',
-        properties: {
-          code: {
-            enum: errors
+    /*
+     * An error a caller is meant to handle is one the operation states. Where none are
+     * stated, an error is not a reply this operation makes — it is a mistake, and the
+     * contract says so rather than passing an undeclared code on to whoever called.
+     */
+    schema.properties.error = errors === undefined
+      ? false
+      : {
+          type: 'object',
+          properties: {
+            code: {
+              enum: errors
+            },
+            message: {
+              type: 'string'
+            }
           },
-          message: {
-            type: 'string'
-          }
-        },
-        required: ['code']
-      }
-    else
-      schema.properties.error = schemas.error
+          required: ['code']
+        }
 
     return schema
   }

package/src/contract/request.js

@@ -9,7 +9,7 @@ export class Request extends Contract {
   constructor (schema, definition) {
     super(schema)
 
-    for (const key of ['input', 'output', 'errors'])
+    for (const key of ['description', 'input', 'output', 'errors'])
       if (definition[key] !== undefined)
         this.discovery[key] = definition[key]
   }

package/src/outbox/outbox.js

@@ -33,6 +33,7 @@ export class Outbox extends Connector {
   #publishing = new Set()
 
   #timer
+  #off
   #pumping = false
   #closing = false
 
@@ -101,11 +102,20 @@ export class Outbox extends Connector {
 
     this.#timer = setInterval(() => this.#tick(), this.#interval)
     this.#timer.unref()
+
+    /*
+     * A lane changing hands is exactly when rows stranded in it become this replica's to
+     * publish, and the cycle would not notice for up to an interval. Being told costs a cycle
+     * that finds nothing in the usual case, where the claim arrives once and never changes.
+     */
+    this.#off = this.#atom.onassigned(() => this.#tick())
   }
 
   async close () {
     this.#closing = true
 
+    this.#off?.()
+
     if (this.#timer !== undefined) clearInterval(this.#timer)
 
     await this.#drain()

package/src/query/criteria.js

@@ -23,7 +23,14 @@ const coerce = (node, properties) => {
       throw new QuerySyntaxException(`Criteria selector '${node.left.selector}' is not defined`)
     }
 
-    if (COERCE[property.type] !== undefined) { node.right.value = COERCE[property.type](node.right.value) }
+    const coerce = COERCE[property.type]
+
+    // `=in=` and `=out=` carry a list, and coercing that as one value gives whatever
+    // `parseInt` makes of a comma-separated string
+    if (coerce !== undefined)
+      node.right.value = Array.isArray(node.right.value)
+        ? node.right.value.map((value) => coerce(value))
+        : coerce(node.right.value)
   } else {
     if (node.left !== undefined) coerce(node.left, properties)
     if (node.right !== undefined) coerce(node.right, properties)

package/test/outbox.test.js

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict'
 
 import { Outbox } from '../src/outbox/index.js'
 
-let emission, storage, atom, outbox
+let emission, storage, atom, outbox, listeners
 
 const BATCH = 4
 
@@ -28,7 +28,18 @@ beforeEach(() => {
     }
   }
 
-  atom = { slots: mock.fn(() => [0]), link: mock.fn() }
+  listeners = []
+
+  atom = {
+    slots: mock.fn(() => [0]),
+    onassigned: (listener) => {
+      listeners.push(listener)
+      listener({ i: 0, n: 1 })
+
+      return () => { listeners = listeners.filter((one) => one !== listener) }
+    },
+    link: mock.fn()
+  }
   outbox = new Outbox(emission, storage, atom, { interval: 1000, batch: BATCH })
 })
 
@@ -36,6 +47,11 @@ afterEach(() => {
   mock.timers.reset()
 })
 
+/** everything the current turn awaited, without moving the clock */
+const settled = async () => {
+  for (let i = 0; i < 20; i++) await Promise.resolve()
+}
+
 /** one cycle, and everything it awaited */
 const cycle = async () => {
   mock.timers.tick(1000)
@@ -119,3 +135,34 @@ function resetCalls (target = [assert, BATCH, page, cycle], seen = new Set()) {
     if (typeof value === 'function' && value.mock !== undefined) value.mock.resetCalls()
     else resetCalls(value, seen)
 }
+
+it('should read as soon as a claim arrives, rather than on its next cycle', async () => {
+  atom.slots.mock.mockImplementation(() => null)
+
+  await outbox.open()
+  await settled()
+
+  assert.strictEqual(storage.outbox.pending.mock.callCount(), 0, 'nothing is owned yet')
+
+  atom.slots.mock.mockImplementation(() => [0])
+
+  for (const listener of listeners) listener({ i: 0, n: 1 })
+
+  await settled()
+
+  assert.strictEqual(storage.outbox.pending.mock.callCount(), 1,
+    'the lane is its own now, and the cycle is up to five seconds away')
+})
+
+it('should read the lanes it inherits when the group resizes', async () => {
+  await outbox.open()
+  await settled()
+
+  const before = storage.outbox.pending.mock.callCount()
+
+  for (const listener of listeners) listener({ i: 0, n: 2 })
+
+  await settled()
+
+  assert.strictEqual(storage.outbox.pending.mock.callCount(), before + 1)
+})

package/test/query.test.js

@@ -23,6 +23,13 @@ describe('criteria', () => {
     assert.deepStrictEqual(query.criteria, fixtures.samples.simple.parsed.criteria)
   })
 
+  it('should coerce every value of a list', () => {
+    const instance = new Query({ n: { type: 'integer' } })
+    const query = instance.parse({ criteria: 'n=in=(1,2,3)' })
+
+    assert.deepStrictEqual(query.criteria.right.value, [1, 2, 3])
+  })
+
   it('should keep a parsed criteria', () => {
     const instance = new Query(fixtures.samples.simple.properties)
 

package/types/atomicity.d.ts

@@ -22,6 +22,20 @@ declare namespace toa.core {
        */
       slots (total: number): number[] | null
 
+      /**
+       * 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.
+       *
+       * What `slots` cannot say. Reading serves a consumer that asks often, where a stale
+       * answer costs it one cycle; a consumer that asks rarely has to be told, or it samples
+       * the one moment a rollout was passing through and stands down for a whole cycle.
+       */
+      onassigned (listener: (assignment: Assignment | null) => void): () => void
+
       /**
        * 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 what it alone has
@@ -45,6 +59,12 @@ declare namespace toa.core {
         routine: (signal: AbortSignal, context: unknown) => Promise<T>): Promise<T>
     }
 
+    /** Which of the group this replica is, and how many of them there are. */
+    interface Assignment {
+      i: number
+      n: number
+    }
+
     interface Factory {
       /** @param group what the replicas deciding together have in common */
       atom (group: string, options?: object): Atom
@@ -55,4 +75,5 @@ declare namespace toa.core {
 }
 
 export type Atom = toa.core.atomicity.Atom
+export type Assignment = toa.core.atomicity.Assignment
 export type Factory = toa.core.atomicity.Factory

package/types/call.d.ts

@@ -0,0 +1,13 @@
+import type { Request } from './request.js'
+
+/**
+ * How an endpoint is called. What it resolves to is what the operation declares — `toa types`
+ * writes that per operation, and these are what a hand-written context says instead.
+ */
+export type Call<Output = any, Input = any> = (request: Request<Input>) => Promise<Output>
+
+export type Observation<Output = any, Input = never, Entity = unknown> =
+  (request: Request<Input, Entity>) => Promise<Output extends unknown[] ? Output : Output | null>
+
+export type Transition<Output = any, Input = never, Entity = unknown> =
+  (request: Request<Input, Entity>) => Promise<Output | null>

package/types/extensions.d.ts

@@ -47,6 +47,25 @@ export interface Factory {
   receiver? (receiver: _core.Receiver, locator: _core.Locator): _core.Receiver
 }
 
+/**
+ * What an extension puts on a component's context, as the extension states it. How it is
+ * presented there is the bridge's — a bash bridge has no context to put anything on — and
+ * what is declared here is the key and what it holds.
+ */
+export interface Contribution {
+  /** the key on the context */
+  name: string
+
+  /** what the key holds, as TypeScript */
+  type?: string
+
+  /** what `type` names, by the module it comes from */
+  imports?: Record<string, string[]>
+
+  /** a JSON Schema to read the type from instead, where a component states one */
+  schema?: object
+}
+
 export interface Aspect extends _core.Connector {
   name: string
 

package/types/guard.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Runs on every change to an entity's state, before the contract is applied. `false` refuses
+ * the change as `EntityGuard`.
+ */
+export type Guard<T, C = unknown> = (state: T, origin: T | null, context: C) => boolean

package/types/index.ts

@@ -14,4 +14,8 @@ export type { Exception } from './exception.js'
 export { Locator } from './locator.js'
 export type { Receiver } from './receiver.js'
 export type { Message } from './message.js'
-export type { Request, Query, Reply, Source } from './request.js'
+export type { Maybe, Request, Query, Reply, RemoteError, Source } from './request.js'
+export type { Event } from './state.js'
+export type { Guard } from './guard.js'
+export type { Call, Observation, Transition } from './call.js'
+export type { Contribution } from './extensions.js'

package/types/remote.d.ts

@@ -5,6 +5,7 @@ export class Remote extends Component {
 }
 
 interface Explanation {
+  description?: string
   input: Schema | null
   output: Schema | null
   errors?: string[]

package/types/request.d.ts

@@ -1,6 +1,10 @@
 import { Exception } from './exception.js'
 
-export interface Query {
+/**
+ * What a call asks for. `Entity` is the record it is about, which narrows the projection;
+ * left out, any name is accepted.
+ */
+export interface Query<Entity = any> {
   id?: string
   ids?: Array<string>
   criteria?: string
@@ -9,7 +13,7 @@ export interface Query {
   omit?: number
   limit?: number
   sort?: Array<string>
-  projection?: Array<string>
+  projection?: Array<string & keyof Entity>
   version?: number
   deleted?: boolean
 }
@@ -22,15 +26,28 @@ export type Source =
   | { namespace: string, component: string, event: string }
   | { service: string }
 
-export interface Request {
-  input?: any
-  query?: Query
+export interface Request<Input = any, Entity = any> {
+  input?: Input
+  query?: Query<Entity>
+  /** What the operation acquires, where the caller supplies it rather than the storage. */
+  entity?: Entity
   authentic?: boolean
   task?: boolean
   telemetry?: string // W3C traceparent
   source?: Source
 }
 
+/**
+ * An error an operation declares and returns. A call resolves to it rather than throwing:
+ * only an exception is thrown.
+ */
+export interface RemoteError<Code extends string = string> extends Error {
+  code: Code
+}
+
+/** What an operation returns where it may refuse: the value, or the error it refused with. */
+export type Maybe<T> = T | Error
+
 export interface Reply {
   output?: any
   error?: object

package/types/state.d.ts

@@ -5,12 +5,12 @@ declare namespace toa.core {
 
   namespace transition {
 
-    type Event = {
+    type Event<State = Object, Trailers = Object> = {
       /** the pre-image; null when the entity did not exist before */
-      origin: Object | null
-      state: Object
+      origin: State | null
+      state: State
       /** out-of-band values an algorithm wrote into `state._trailers`; must be serializable */
-      trailers?: Object
+      trailers?: Trailers
       input?: Object
     }
 
@@ -35,4 +35,4 @@ declare namespace toa.core {
 }
 
 export type State = toa.core.State
-export type Event = toa.core.transition.Event
+export type Event<State = Object, Trailers = Object> = toa.core.transition.Event<State, Trailers>