@toa.io/userland 1.0.0-alpha.29 → 1.0.0-alpha.291

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# 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.291](https://github.com/toa-io/toa/compare/v1.0.0-alpha.290...v1.0.0-alpha.291) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.289](https://github.com/toa-io/toa/compare/v1.0.0-alpha.288...v1.0.0-alpha.289) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.288](https://github.com/toa-io/toa/compare/v1.0.0-alpha.287...v1.0.0-alpha.288) (2026-09-06)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.287](https://github.com/toa-io/toa/compare/v1.0.0-alpha.286...v1.0.0-alpha.287) (2026-09-06)
+
+**Note:** Version bump only for package @toa.io/userland

package/example/components/echo/manifest.toa.yaml

@@ -2,14 +2,24 @@ name: echo
 
 operations:
   signal:
-    output: string
+    output:
+      type: string
   get:
-    output: string
+    output:
+      type: string
   resolve:
-    input: string
-    output: string
+    input:
+      type: string
+    output:
+      type: string
 
 configuration:
-  signal: quack
+  schema:
+    type: object
+    properties:
+      signal:
+        type: string
+  defaults:
+    signal: quack
 
 state: ~

package/example/components/echo/operations/get.js

@@ -1,7 +1,3 @@
-'use strict'
-
-async function computation (_, context) {
+export async function computation(_, context) {
   return context.state.value
 }
-
-exports.computation = computation

package/example/components/echo/operations/resolve.js

@@ -1,7 +1,3 @@
-'use strict'
-
-async function computation (key, context) {
+export async function computation(key, context) {
   return context.state.values.get(key)
 }
-
-exports.computation = computation

package/example/components/echo/operations/signal.js

@@ -1,15 +1,11 @@
-'use strict'
-
-class Computation {
+export class Computation {
   #context
 
-  async mount (context) {
+  async mount(context) {
     this.#context = context
   }
 
-  async execute () {
+  async execute() {
     return this.#context.configuration.signal
   }
 }
-
-exports.Computation = Computation

package/example/components/math.calculations/manifest.toa.yaml

@@ -4,11 +4,24 @@ namespace: math
 operations:
   add:
     input:
-      a: number
-      b: number
-    output: number
+      properties:
+        a:
+          type: number
+        b:
+          type: number
+      type: object
+    output:
+      type: number
   increment:
     input:
-      value: number
-      times: 1
-    output: number
+      properties:
+        value:
+          type: number
+        times:
+          type: number
+      type: object
+      required:
+        - value
+        - times
+    output:
+      type: number

package/example/components/math.calculations/operations/add.js

@@ -1,7 +1,3 @@
-'use strict'
-
-async function computation (input) {
+export async function computation(input) {
   return input.a + input.b
 }
-
-exports.computation = computation

package/example/components/math.calculations/operations/increment.js

@@ -1,6 +1,4 @@
-'use strict'
-
-async function computation (input, context) {
+export async function computation(input, context) {
   let value = input.value
 
   for (let i = 0; i < input.times; i++) {
@@ -9,5 +7,3 @@ async function computation (input, context) {
 
   return value
 }
-
-exports.computation = computation

package/example/components/math.proxy/manifest.toa.yaml

@@ -4,6 +4,11 @@ namespace: math
 operations:
   add:
     input:
-      a: number
-      b: number
-    output: number
+      properties:
+        a:
+          type: number
+        b:
+          type: number
+      type: object
+    output:
+      type: number

package/example/components/math.proxy/operations/add.js

@@ -1,10 +1,6 @@
-'use strict'
-
-async function computation (input, context) {
+export async function computation(input, context) {
   const request = { input }
 
   // noinspection JSUnresolvedVariable
   return context.remote.math.calculations.add(request)
 }
-
-exports.computation = computation

package/example/components/tea.pots/manifest.toa.yaml

@@ -3,21 +3,43 @@ namespace: tea
 
 entity:
   storage: mongodb
-  schema:
-    material*: [ glass, ceramic, steel ]
-    volume: number
+  properties:
+    volume:
+      type: number
+    booked:
+      type: boolean
+    material:
+      type: string
+      enum:
+        - glass
+        - ceramic
+        - steel
+  required:
+    - material
+  blank:
     booked: false
 
 operations:
   transit:
     concurrency: none
     input:
-      material: .
-      volume: .
-      booked: .
+      properties:
+        material:
+          type: string
+          default: .
+        volume:
+          type: string
+          default: .
+        booked:
+          type: string
+          default: .
+      type: object
   same:
-    input: .material
-    output: array
+    input:
+      type: string
+      default: .material
+    output:
+      type: array
 
 receivers:
   store.orders.created:
@@ -25,4 +47,10 @@ receivers:
     binding: amqp # avoid discovery
 
 configuration:
-  step: 0.5
+  schema:
+    type: object
+    properties:
+      step:
+        type: number
+  defaults:
+    step: 0.5

package/example/components/tea.pots/operations/same.js

@@ -1,6 +1,4 @@
-'use strict'
-
-async function computation (input, context) {
+export async function computation(input, context) {
   const criteria = `material==${input}`
   const query = { criteria, limit }
 
@@ -9,5 +7,3 @@ async function computation (input, context) {
 }
 
 const limit = 10
-
-exports.computation = computation

package/example/components/tea.pots/receivers/store.orders.created.js

@@ -1,8 +1,4 @@
-'use strict'
-
-const request = async (payload) => ({
+export const request = async (payload) => ({
   input: { booked: true },
   query: { id: payload.pot }
 })
-
-exports.request = request

package/example/components/web/manifest.toa.yaml

@@ -2,7 +2,5 @@ name: web
 
 operations:
   get:
-    output: object
-
-origins:
-  dev: http://api.example.com
+    output:
+      type: object

package/example/components/web/operations/get.js

@@ -1,15 +1,10 @@
-'use strict'
-
-async function computation (_, context) {
-  const response = await context.http.dev.path.to.resource.get()
+export async function computation(_, context) {
+  const response = await context.fetch('http://api.example.com/path/to/resource')
   const type = response.headers.get('content-type')
 
-  if (type !== 'application/json')
-    return ERR_UNSUPPORTED_MEDIA_TYPE
+  if (type !== 'application/json') return ERR_UNSUPPORTED_MEDIA_TYPE
 
   return await response.json()
 }
 
 const ERR_UNSUPPORTED_MEDIA_TYPE = new Error('UNSUPPORTED_MEDIA_TYPE')
-
-exports.computation = computation

package/example/context.toa.yaml

@@ -1,10 +1,5 @@
 name: examples
-packages: components/*
 registry: example
 
-amqp: amqp://localhost
-mongodb: mongodb://localhost
-
-origins:
-  default.web:
-    dev: http://localhost
+amqp: amqp://localhost:31010
+mongodb: mongodb://localhost:31020

package/example/stage/call.test.js

@@ -1,16 +1,21 @@
-'use strict'
+import { it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
 
-const { resolve } = require('node:path')
-const { exceptions: { RequestContractException } } = require('@toa.io/core')
-const stage = require('@toa.io/userland/stage')
+import { resolve } from 'node:path'
+import { exceptions } from '@toa.io/core'
+import * as stage from '@toa.io/userland/stage'
 
-const root = resolve(__dirname, '../components')
+const { RequestContractException } = exceptions
+
+const root = resolve(import.meta.dirname, '../components')
 
 let echo
 let math
 
-beforeAll(async () => {
+before(async () => {
   process.env.TOA_DEV = '1'
+  process.env.TOA_CONFIGURATION_DEFAULT_ECHO = '{}'
+  process.env.TOA_CONFIGURATION_TEA_POTS = '{}'
 
   const paths = ['echo', 'math.calculations'].map((rel) => resolve(root, rel))
 
@@ -20,7 +25,7 @@ beforeAll(async () => {
   math = await stage.remote('math.calculations')
 })
 
-afterAll(async () => {
+after(async () => {
   await stage.shutdown()
 
   delete process.env.TOA_DEV
@@ -29,13 +34,15 @@ afterAll(async () => {
 it('should call endpoint', async () => {
   const reply = await echo.invoke('signal', {})
 
-  expect(reply).toStrictEqual('quack')
+  assert.deepStrictEqual(reply, 'quack')
 })
 
 it('should throw on invalid input', async () => {
   const a = 'not a number'
   const b = 'neither'
 
-  await expect(math.invoke('add', { input: { a, b } }))
-    .rejects.toBeInstanceOf(RequestContractException)
+  await assert.rejects(math.invoke('add', { input: { a, b } }), (error) => {
+    assert.ok(error instanceof RequestContractException)
+    return true
+  })
 })

package/example/stage/events.test.js

@@ -1,51 +1,98 @@
-'use strict'
+import { it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
 
-const { resolve } = require('node:path')
-const stage = require('@toa.io/userland/stage')
+import { resolve } from 'node:path'
+import * as boot from '@toa.io/boot'
+import { Connector, Locator } from '@toa.io/core'
+import { timeout } from '@toa.io/generic'
+import * as stage from '@toa.io/userland/stage'
 
-const binding = stage.binding.binding
-const root = resolve(__dirname, '../components')
+const root = resolve(import.meta.dirname, '../components')
 
 let remote
+let emitter
+let consumer
 
-beforeAll(async () => {
+before(async () => {
   process.env.TOA_DEV = '1'
+  process.env.TOA_CONFIGURATION_TEA_POTS = '{}'
+
+  // the outbox pumps on a tick; at the default five seconds a test would end before it ran
+  process.env.TOA_OUTBOX_INTERVAL = '100'
 
   const path = resolve(root, 'tea.pots')
 
   await stage.composition([path])
 
   remote = await stage.remote('tea.pots')
+
+  // what `store.orders` would emit, sent the way it would send it
+  emitter = await boot.bindings.emit(AMQP, new Locator('orders', 'store'), 'created')
+
+  await emitter.connect()
 })
 
-afterAll(async () => {
+after(async () => {
+  await consumer?.disconnect()
+  await emitter.disconnect()
   await stage.shutdown()
 
   delete process.env.TOA_DEV
+  delete process.env.TOA_CONFIGURATION_TEA_POTS
+  delete process.env.TOA_OUTBOX_INTERVAL
 })
 
 it('should receive event', async () => {
   const created = await remote.invoke('transit', { input: { material: 'glass' } })
   const id = created.id
-  const payload = { pot: id }
-  const message = { payload }
   const request = { query: { id } }
 
-  await binding.emit('store.orders.created', message)
+  await emitter.emit({ payload: { pot: id } })
+
+  // the receiver books the pot on delivery, which is asynchronous
+  const deadline = Date.now() + 5000
 
-  const reply = await remote.invoke('observe', request)
+  let reply
 
-  expect(reply.booked).toStrictEqual(true)
+  do {
+    await timeout(50)
+
+    reply = await remote.invoke('observe', request)
+  } while (reply.booked !== true && Date.now() < deadline)
+
+  assert.deepStrictEqual(reply.booked, true)
 })
 
 it('should emit event', async () => {
-  expect.assertions(1)
-
   const material = 'steel'
 
-  await binding.subscribe('tea.pots.created', (pot) => {
-    expect(pot.payload.material).toStrictEqual(material)
+  const received = new Promise((resolve) => {
+    consumer = boot.receive('tea.pots.created', new Subscriber(resolve))
   })
 
+  consumer = await consumer
+
+  await consumer.connect()
   await remote.invoke('transit', { input: { material } })
+
+  const payload = await received
+
+  assert.deepStrictEqual(payload.material, material)
 })
+
+/** What the event consumer hands deliveries to. */
+class Subscriber extends Connector {
+  #handler
+
+  constructor(handler) {
+    super()
+
+    this.#handler = handler
+  }
+
+  async receive(message) {
+    this.#handler(message.payload)
+  }
+}
+
+const AMQP = '@toa.io/bindings.amqp'

package/example/stage/invoke.test.js

@@ -1,22 +1,25 @@
-'use strict'
+import { it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
 
-const { resolve } = require('node:path')
-const stage = require('@toa.io/userland/stage')
+import { resolve } from 'node:path'
+import * as stage from '@toa.io/userland/stage'
 
-const root = resolve(__dirname, '../components')
+const root = resolve(import.meta.dirname, '../components')
 
-/** @type {toa.core.Component} */
+/** @type {import('@toa.io/core').Component} */
 let component
 
-beforeAll(async () => {
+before(async () => {
   process.env.TOA_DEV = '1'
+  process.env.TOA_CONFIGURATION_DEFAULT_ECHO = '{}'
+  process.env.TOA_CONFIGURATION_TEA_POTS = '{}'
 
   const path = resolve(root, 'math.calculations')
 
   component = await stage.component(path)
 })
 
-afterAll(async () => {
+after(async () => {
   await stage.shutdown()
 
   delete process.env.TOA_DEV
@@ -28,6 +31,6 @@ it('should invoke', async () => {
 
   const reply = await component.invoke('add', { input: { a, b } })
 
-  expect(reply.exception).toBeUndefined()
-  expect(reply.output).toStrictEqual(a + b)
+  assert.strictEqual(reply.exception, undefined)
+  assert.deepStrictEqual(reply.output, a + b)
 })

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@toa.io/userland",
-  "version": "1.0.0-alpha.29",
+  "version": "1.0.0-alpha.291",
+  "type": "module",
   "description": "Toa development kit",
   "homepage": "https://toa.io",
   "author": {
@@ -16,23 +17,28 @@
     "url": "https://github.com/toa-io/toa/issues"
   },
   "engines": {
-    "node": ">= 18.0.0"
+    "node": ">= 24.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "main": "src/index.js",
-  "types": "types/index.d.ts",
+  "exports": {
+    ".": "./src/index.js",
+    "./stage": {
+      "types": "./stage/types/index.d.ts",
+      "default": "./stage/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "dependencies": {
-    "@toa.io/boot": "1.0.0-alpha.29",
-    "@toa.io/core": "1.0.0-alpha.29",
-    "@toa.io/filesystem": "1.0.0-alpha.29",
-    "@toa.io/generic": "1.0.0-alpha.29",
-    "@toa.io/norm": "1.0.0-alpha.29",
-    "@toa.io/schemas": "1.0.0-alpha.29",
+    "@toa.io/boot": "1.0.0-alpha.291",
+    "@toa.io/core": "1.0.0-alpha.291",
+    "@toa.io/generic": "1.0.0-alpha.291",
+    "@toa.io/norm": "1.0.0-alpha.291",
+    "@toa.io/schemas": "1.0.0-alpha.291",
     "@toa.io/storages.null": "0.22.0",
-    "@toa.io/yaml": "1.0.0-alpha.29",
-    "tap": "16.3.4"
+    "js-yaml": "5.4.1"
   },
-  "gitHead": "186d0e17c12a9016b8076edf925963cbb32b9219"
+  "gitHead": "bcd8d8d07bd3e64fc826af8719472404662cc37f"
 }

package/stage/package.json

@@ -1,4 +1,5 @@
 {
+  "type": "module",
   "private": true,
   "main": "src/index.js",
   "types": "types/index.d.ts"

package/stage/src/component.js

@@ -1,12 +1,8 @@
-'use strict'
-
-const boot = require('@toa.io/boot')
-const { state } = require('./state')
+import * as boot from '@toa.io/boot'
+import { state } from './state.js'
 
 /** @type {toa.stage.Component} */
-const component = async (path, options) => {
-  options = Object.assign({}, DEFAULTS, options)
-
+export const component = async (path, options) => {
   const manifest = await boot.manifest(path, options)
   const component = await boot.component(manifest)
 
@@ -16,8 +12,3 @@ const component = async (path, options) => {
 
   return component
 }
-
-const binding = require.resolve('./binding')
-const DEFAULTS = { bindings: [binding] }
-
-exports.component = component

package/stage/src/composition.js

@@ -1,19 +1,11 @@
-'use strict'
-
-const boot = require('@toa.io/boot')
-const { state } = require('./state')
-
-const binding = require.resolve('./binding')
+import * as boot from '@toa.io/boot'
+import { state } from './state.js'
 
 /** @type {toa.stage.Composition} */
-const composition = async (paths, options) => {
-  options ??= { bindings: [binding] }
-
+export const composition = async (paths, options) => {
   const composition = await boot.composition(paths, options)
 
   await composition.connect()
 
   state.compositions.push(composition)
 }
-
-exports.composition = composition

package/stage/src/index.js

@@ -1,18 +1,16 @@
-'use strict'
+import { manifest } from './manifest.js'
+import { component } from './component.js'
+import { composition } from './composition.js'
+import { service } from './service.js'
+import { remote } from './remote.js'
+import { shutdown } from './shutdown.js'
 
-const { manifest } = require('./manifest')
-const { component } = require('./component')
-const { composition } = require('./composition')
-const { service } = require('./service')
-const { remote } = require('./remote')
-const { shutdown } = require('./shutdown')
-const binding = require('./binding')
-
-exports.manifest = manifest
-exports.component = component
-exports.composition = composition
-exports.compose = composition
-exports.serve = service
-exports.remote = remote
-exports.shutdown = shutdown
-exports.binding = binding
+export {
+  manifest,
+  component,
+  composition,
+  composition as compose,
+  service as serve,
+  remote,
+  shutdown
+}