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

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.315](https://github.com/toa-io/toa/compare/v1.0.0-alpha.314...v1.0.0-alpha.315) (2026-09-23)
+
+* feat(map)!: leave out of a contract what the runtime gives every component ([b81837a](https://github.com/toa-io/toa/commit/b81837a3bc4771d7ee1c10fe613c9a1d7501bf1a))
+
+### BREAKING CHANGES
+
+* the deployed component map is `/etc/toa/.map.json.gz`.
+
+
+# [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.315",
   "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.315",
+    "@toa.io/core": "1.0.0-alpha.315",
+    "@toa.io/definitions": "1.0.0-alpha.315",
     "@toa.io/generic": "1.0.0-alpha.311",
-    "@toa.io/norm": "1.0.0-alpha.313",
+    "@toa.io/norm": "1.0.0-alpha.315",
     "@toa.io/schemas": "1.0.0-alpha.311",
     "clone-deep": "4.0.1",
-    "dotenv": "17.4.2",
+    "dotenv": "18.0.0",
     "openspan": "1.0.0-alpha.305"
   },
-  "gitHead": "7da3b2627ceeefd1fa19d5c8851be88d928523b6"
+  "gitHead": "d88ed286bf44bf95b5f3d9db6e7d4621261dbb99"
 }

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/map.js

@@ -1,4 +1,5 @@
 import assert from 'node:assert'
+import { gunzipSync } from 'node:zlib'
 import { readFile } from 'node:fs/promises'
 import * as core from '@toa.io/core'
 
@@ -78,6 +79,9 @@ export const contract = async (id) => {
 }
 
 /**
+ * A map is read gzipped where it is deployed and plain where it is not, so what it is is told by
+ * its first two bytes rather than by its name.
+ *
  * @param {string} path
  * @returns {Promise<Record<string, import('@toa.io/core').Contract>>}
  */
@@ -85,13 +89,19 @@ async function read(path) {
   let contents
 
   try {
-    contents = await readFile(path, 'utf8')
+    contents = await readFile(path)
   } catch (cause) {
     throw new Error(`Cannot read the component map '${path}'`, { cause })
   }
 
   try {
-    return JSON.parse(contents)
+    if (contents[0] === 0x1f && contents[1] === 0x8b) contents = gunzipSync(contents)
+  } catch (cause) {
+    throw new Error(`The component map '${path}' is not readable gzip`, { cause })
+  }
+
+  try {
+    return JSON.parse(contents.toString('utf8'))
   } catch (cause) {
     throw new Error(`The component map '${path}' is not JSON`, { cause })
   }

package/src/remote.js

@@ -1,4 +1,4 @@
-import { Remote, exceptions } from '@toa.io/core'
+import { Remote, contract as coreContract, exceptions } from '@toa.io/core'
 import { remap } from '@toa.io/generic'
 
 import * as boot from './index.js'
@@ -11,13 +11,17 @@ import * as boot from './index.js'
  *   tenant announced — and absent it, what the map this process was given states.
  */
 export const remote = async (locator, source, options = {}) => {
-  const contract = options.contract ?? (await boot.map.contract(locator.id))
+  const stated = options.contract ?? (await boot.map.contract(locator.id))
 
-  if (contract === undefined)
+  if (stated === undefined)
     throw new exceptions.UnstatedException(
       `Cannot call '${locator.id}': the component map states nothing of it. Run \`toa map\`.`
     )
 
+  // a contract states once, or not at all, what the runtime gives every component; the calls
+  // are made from the whole of it
+  const contract = coreContract.restore(stated)
+
   // a call binds its consumers, which are loaded rather than required
   const calls =
     contract.operations === undefined

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)
+  }
+}