@toa.io/boot 1.0.0-alpha.313 → 1.0.0-alpha.314

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.314](https://github.com/toa-io/toa/compare/v1.0.0-alpha.313...v1.0.0-alpha.314) (2026-09-19)
+
+* feat(core)!: let an operation state how long its calls are remembered ([af177c2](https://github.com/toa-io/toa/commit/af177c2ab3d00d475840b5ef9e612f04e82b72bd))
+
+### Features
+
+* **core:** a destination renders the component's events ([2f93b28](https://github.com/toa-io/toa/commit/2f93b28bed61a0afe99cb8cfa646ed7815467497))
+* **core:** a reference may name a declaration its package claims ([8040f60](https://github.com/toa-io/toa/commit/8040f60976549ab90497675bb54e664261f5b6bb))
+
+### BREAKING CHANGES
+
+* `inbox.retention` under 600 is refused. See
+  migrations/313.md.
+
+
 # [1.0.0-alpha.313](https://github.com/toa-io/toa/compare/v1.0.0-alpha.312...v1.0.0-alpha.313) (2026-09-18)
 
 **Note:** Version bump only for package @toa.io/boot

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/boot",
-  "version": "1.0.0-alpha.313",
+  "version": "1.0.0-alpha.314",
   "type": "module",
   "description": "Toa Boot",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -21,15 +21,15 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/atomicity": "1.0.0-alpha.312",
-    "@toa.io/core": "1.0.0-alpha.312",
-    "@toa.io/definitions": "1.0.0-alpha.313",
+    "@toa.io/atomicity": "1.0.0-alpha.314",
+    "@toa.io/core": "1.0.0-alpha.314",
+    "@toa.io/definitions": "1.0.0-alpha.314",
     "@toa.io/generic": "1.0.0-alpha.311",
-    "@toa.io/norm": "1.0.0-alpha.313",
+    "@toa.io/norm": "1.0.0-alpha.314",
     "@toa.io/schemas": "1.0.0-alpha.311",
     "clone-deep": "4.0.1",
     "dotenv": "17.4.2",
     "openspan": "1.0.0-alpha.305"
   },
-  "gitHead": "7da3b2627ceeefd1fa19d5c8851be88d928523b6"
+  "gitHead": "4b7c0f4468e6fa89f95a69f43fed85c648fb033d"
 }

package/src/component.js

@@ -34,6 +34,10 @@ const create = async (manifest, locator) => {
   )
   const context = await boot.context(manifest)
   const emission = await boot.emission(events, locator, context)
+
+  // a destination that renders the component's events renders them with its context
+  await boot.rendering(manifest, destinations, context)
+
   const outbox = boot.outbox(manifest, storage, emission, destinations)
 
   let state

package/src/extensions/resolve.js

@@ -20,12 +20,12 @@ const loading = {}
  * @returns {Promise<import('@toa.io/core/types').extensions.Factory>}
  */
 export const resolve = async (reference, base = process.cwd()) => {
-  const path = find(reference, base)
+  const path = find(pack(reference), base)
 
   loading[path] ??= create(path)
   instances[path] = await loading[path]
 
-  return instances[path]
+  return keyed(instances[path], reference)
 }
 
 /**
@@ -38,13 +38,37 @@ export const resolve = async (reference, base = process.cwd()) => {
  * @returns {import('@toa.io/core/types').extensions.Factory}
  */
 export const instance = (reference, base = process.cwd()) => {
-  const factory = instances[find(reference, base)]
+  const factory = instances[find(pack(reference), base)]
 
   if (factory === undefined) throw new Error(`Extension '${reference}' is not loaded`)
 
-  return factory
+  return keyed(factory, reference)
 }
 
+/**
+ * `package#key` is a declaration a package claims beside its main one, and what the package's
+ * factory offers for that key answers for it — so a key is never taken for the package itself.
+ *
+ * @param {import('@toa.io/core/types').extensions.Factory} factory
+ * @param {string} reference
+ * @returns {import('@toa.io/core/types').extensions.Factory}
+ */
+const keyed = (factory, reference) => {
+  const key = reference.split('#')[1]
+
+  if (key === undefined) return factory
+
+  const claimed = factory.keys?.[key]
+
+  if (claimed === undefined)
+    throw new Error(`'${reference}' names a key its package does not claim`)
+
+  return claimed
+}
+
+/** The package a reference is of. */
+const pack = (reference) => reference.split('#')[0]
+
 const create = async (path) => {
   const { Factory } = await import(pathToFileURL(require.resolve(path)).href)
 

package/src/inbox.js

@@ -7,4 +7,6 @@
  * @returns {boolean}
  */
 export const inbox = (manifest) =>
-  Object.values(manifest.operations ?? {}).some((definition) => definition.once === true)
+  Object.values(manifest.operations ?? {}).some(
+    (definition) => definition.once === true || typeof definition.once === 'number'
+  )

package/src/index.js

@@ -22,6 +22,7 @@ export { manifest } from './manifest.js'
 export { operation } from './operation.js'
 export { receivers, receive } from './receivers.js'
 export { remote } from './remote.js'
+export { rendering } from './rendering.js'
 export { storage } from './storage.js'
 export { guards } from './guards.js'
 export { host } from './host.js'

package/src/rendering.js

@@ -0,0 +1,50 @@
+import { Event, Rendering } from '@toa.io/core'
+
+import * as boot from './index.js'
+
+/**
+ * Gives every destination that names the events it renders a `Rendering` of them, made with the
+ * component's own bridges. Every event of the manifest may be named, including those nothing
+ * consumes and are therefore not published: a destination writes somewhere of its own.
+ *
+ * @param {toa.norm.Component} manifest
+ * @param {import('@toa.io/core/types').outbox.Destination[]} destinations
+ * @param {import('@toa.io/core').Context} context
+ * @returns {Promise<void>}
+ */
+export const rendering = async (manifest, destinations, context) => {
+  for (const destination of destinations) {
+    if (destination.renders === undefined) continue
+
+    const events = new Map()
+
+    for (const label of destination.renders) {
+      const definition = manifest.events?.[label]
+
+      if (definition === undefined)
+        throw new Error(
+          `Component '${manifest.locator.id}' has no event '${label}' to render for ` +
+            `'${destination.name}'`
+        )
+
+      const bridge = await boot.bridge.event(
+        definition.bridge,
+        definition.path,
+        label,
+        context
+      )
+      const event = new Event(
+        { ...definition, label: `${manifest.locator.id}.${label}` },
+        null,
+        bridge
+      )
+
+      events.set(label, event)
+    }
+
+    const rendering = new Rendering(events)
+
+    destination.rendering = rendering
+    destination.depends(rendering)
+  }
+}