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

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 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)
+
+### Features
+
+* an operation states what it is ([b5e2f66](https://github.com/toa-io/toa/commit/b5e2f66c8bf67924e2eaaaa11f283dfb4d810981))
+* **cadence:** calls a component makes to itself, and calls it puts off ([8bbde5f](https://github.com/toa-io/toa/commit/8bbde5fc89e8e5549d5aa2bfcddb1beec0871565))
+
+
+# [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
+
+* **exposition:** declare the errors the built-in components return ([27200c3](https://github.com/toa-io/toa/commit/27200c348ab09068d58c52c3e83208cb29cd7290))
+
+### Features
+
+* **operations:** run extension services inside a composition ([154aced](https://github.com/toa-io/toa/commit/154aced047228a250ac3bab353e09432fcc5a34d))
+
+
 # [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)
 
 **Note:** Version bump only for package @toa.io/norm

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/norm",
-  "version": "1.0.0-alpha.282",
+  "version": "1.0.0-alpha.284",
   "type": "module",
   "description": "Toa declarations normalization and validation",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -21,11 +21,11 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.282",
-    "@toa.io/generic": "1.0.0-alpha.282",
-    "@toa.io/schemas": "1.0.0-alpha.282",
+    "@toa.io/core": "1.0.0-alpha.284",
+    "@toa.io/generic": "1.0.0-alpha.283",
+    "@toa.io/schemas": "1.0.0-alpha.283",
     "fast-glob": "3.3.3",
     "js-yaml": "5.4.1"
   },
-  "gitHead": "4007c814725dd015d3bbebb9a28e28a247645c4f"
+  "gitHead": "006755556879e91e8d68fa86753aa3b475bdf4bf"
 }

package/src/.component/.expand/extensions.js

@@ -12,5 +12,6 @@ const SHORTCUTS = {
   state: '@toa.io/extensions.state',
   stash: '@toa.io/extensions.stash',
   storages: '@toa.io/extensions.storages',
+  cadence: '@toa.io/extensions.cadence',
   introspection: '@toa.io/extensions.introspection'
 }

package/src/.component/schema.yaml

@@ -148,15 +148,19 @@ properties:
             type: string
           bindings:
             $ref: "#/properties/bindings"
+          description:
+            # what the operation is, for whoever reads it: a generated type, an OPTIONS, a model
+            type: string
           input:
             $ref: https://json-schema.org/draft/2019-09/schema
           output:
             $ref: https://json-schema.org/draft/2019-09/schema
             default: {}
           errors:
+            # what a reply may carry as a code: the error schema allows either
             type: array
             items:
-              type: string
+              type: [string, integer]
           query:
             type: boolean
         required: [type, scope, bindings]

package/src/.context/.dependencies/extensions.js

@@ -4,7 +4,13 @@ import { load as loadDependency } from './load.js'
 export const extensions = async (context) => {
   const extensions = {}
   const components = context.components?.slice() ?? []
-  const extracted = await extractExtensionComponents(components, extensions, context.annotations)
+
+  // an extension a composition runs may be referenced by no component of this context,
+  // and its own components must be extracted all the same
+  const declared = await extractDeclaredServices(context, extensions)
+
+  const extracted = declared.concat(
+    await extractExtensionComponents(components.concat(declared), extensions, context.annotations))
 
   components.push(...extracted)
 
@@ -21,6 +27,24 @@ export const extensions = async (context) => {
   return { extensions, components: extracted }
 }
 
+async function extractDeclaredServices (context, extensions) {
+  const extracted = []
+
+  for (const composition of context.compositions ?? [])
+    for (const reference of composition.services ?? []) {
+      if (reference in extensions) continue
+
+      try {
+        extracted.push(...await extract(reference, extensions, context.annotations))
+      } catch (e) {
+        throw new Error(`Composition '${composition.name}' lists '${reference}', ` +
+          `which cannot be resolved: ${e.message}`, { cause: e })
+      }
+    }
+
+  return extracted
+}
+
 async function extractExtensionComponents (components, extensions, annotations) {
 
   const extracted = []
@@ -31,20 +55,7 @@ async function extractExtensionComponents (components, extensions, annotations)
     for (const reference of Object.keys(component.extensions)) {
       if (reference in extensions) continue
 
-      extensions[reference] = []
-
-      const { metadata, module: mod } = await loadDependency(reference)
-
-      if (mod.components === undefined) continue
-
-      // the annotation decides whether an extension contributes components at all
-      const annotation = annotations?.[metadata?.name ?? reference]
-
-      for (const path of mod.components(annotation).paths) {
-        const component = await load(path)
-
-        extracted.push(component)
-      }
+      extracted.push(...await extract(reference, extensions, annotations))
     }
   }
 
@@ -55,3 +66,28 @@ async function extractExtensionComponents (components, extensions, annotations)
 
   return extracted.concat(deeper)
 }
+
+/**
+ * The components an extension contributes, if it contributes any.
+ *
+ * @param {string} reference
+ * @param {object} extensions
+ * @param {object} [annotations]
+ * @returns {Promise<Array<toa.norm.Component>>}
+ */
+async function extract (reference, extensions, annotations) {
+  extensions[reference] = []
+
+  const { metadata, module: mod } = await loadDependency(reference)
+
+  if (mod.components === undefined) return []
+
+  // the annotation decides whether an extension contributes components at all
+  const annotation = annotations?.[metadata?.name ?? reference]
+  const extracted = []
+
+  for (const path of mod.components(annotation).paths)
+    extracted.push(await load(path))
+
+  return extracted
+}

package/src/.context/.dependencies/resolve.js

@@ -1,6 +1,6 @@
 import { load } from './load.js'
 
-export const resolve = async (references, annotations) => {
+export const resolve = async (references, annotations = {}) => {
   const dependencies = {}
 
   for (const [dependency, components] of Object.entries(references)) {

package/src/.context/dereference.js

@@ -8,7 +8,14 @@ export const dereference = (context) => {
 
   if (context.compositions !== undefined) {
     for (const composition of context.compositions) {
-      composition.components = composition.components.map((id) => components[id])
+      composition.components = composition.components.map((id) => {
+        const component = components[id]
+
+        if (component === undefined)
+          throw new Error(`Composition '${composition.name}' lists an unknown component '${id}'.`)
+
+        return component
+      })
     }
   }
 }

package/src/.context/expand.js

@@ -6,4 +6,10 @@ import * as shortcuts from '../shortcuts.js'
 export const expand = (context) => {
   shortcuts.recognize(shortcuts.SHORTCUTS, context, 'annotations')
   shortcuts.recognize(shortcuts.SHORTCUTS, context.annotations)
+
+  // a composition names a service the way a manifest names an extension, and everything
+  // downstream matches it against a dependency, which is keyed by package reference
+  for (const composition of context.compositions ?? [])
+    if (composition.services !== undefined)
+      composition.services = composition.services.map(shortcuts.resolve)
 }

package/src/.context/schema.yaml

@@ -50,6 +50,7 @@ properties:
     minItems: 1
     items:
       type: object
+      additionalProperties: false
       properties:
         name:
           type: string
@@ -62,6 +63,16 @@ properties:
           items:
             type: string
             pattern: ^([a-zA-Z]+([_a-zA-Z0-9]*[a-zA-Z0-9]+)?)(\.([a-zA-Z]+([_a-zA-Z0-9]*[a-zA-Z0-9]+)?))$
+        services:
+          description: >
+            Extension services this composition runs in its own pod, named by shortcut or
+            package reference, rather than each as its own deployment. A service listed here
+            keeps its own Service and Ingress; what changes is the pod they select.
+          type: array
+          minItems: 1
+          items:
+            type: string
+            minLength: 1
         resources:
           $ref: '#/definitions/resources'
       required: [name, components]

package/src/shortcuts.js

@@ -49,5 +49,6 @@ export const SHORTCUTS = {
   stash: '@toa.io/extensions.stash',
   storages: '@toa.io/extensions.storages',
   telemetry: '@toa.io/extensions.telemetry',
+  cadence: '@toa.io/extensions.cadence',
   introspection: '@toa.io/extensions.introspection'
 }

package/test/context/dereference.test.js

@@ -23,3 +23,12 @@ it('should not throw on empty compositions', () => {
 
   assert.doesNotThrow(() => dereference(context))
 })
+
+it('should throw on an unknown component', () => {
+  const broken = clone(fixtures.context)
+
+  broken.compositions[1].components.push('nope.here')
+
+  assert.throws(() => dereference(broken),
+    { message: "Composition 'bar' lists an unknown component 'nope.here'." })
+})

package/test/context/expand.test.js

@@ -40,3 +40,28 @@ describe('annotations', () => {
     assert.notStrictEqual(context.annotations['@toa.io/storages.mongodb'], undefined)
   })
 })
+
+describe('composition services', () => {
+  it('should resolve shortcuts', () => {
+    context.compositions[0].services = ['exposition', 'configuration']
+
+    expand(context)
+
+    assert.deepStrictEqual(context.compositions[0].services,
+      ['@toa.io/extensions.exposition', '@toa.io/extensions.configuration'])
+  })
+
+  it('should leave a package reference alone', () => {
+    context.compositions[0].services = ['@acme/extension']
+
+    expand(context)
+
+    assert.deepStrictEqual(context.compositions[0].services, ['@acme/extension'])
+  })
+
+  it('should not throw without compositions', () => {
+    delete context.compositions
+
+    assert.doesNotThrow(() => expand(context))
+  })
+})

package/test/context/validate.test.js

@@ -83,3 +83,26 @@ it('should allow mono replicas and resources', () => {
 
   assert.doesNotThrow(() => validate(context))
 })
+
+describe('compositions', () => {
+  it('should allow services', () => {
+    context.compositions[0].services = ['@toa.io/extensions.exposition']
+
+    assert.doesNotThrow(() => validate(context))
+  })
+
+  it('should require services to be a non-empty array of strings', () => {
+    context.compositions[0].services = []
+    assert.throws(() => validate(context), (error) => /fewer than 1 items/.test(error.message))
+
+    context.compositions[0].services = 'exposition'
+    assert.throws(() => validate(context), (error) => /must be array/.test(error.message))
+  })
+
+  it('should reject an unknown property', () => {
+    context.compositions[0].compoments = ['a.b']
+
+    assert.throws(() => validate(context),
+      (error) => /Property compoments is not expected to be here/.test(error.message))
+  })
+})

package/types/component.d.ts

@@ -8,6 +8,7 @@ export type Operation = {
   type: operations.type
   scope?: operations.scope
   bindings?: string[]
+  description?: string
   input?: any
   output?: any
   error?: any

package/types/context/declaration.d.ts

@@ -1,8 +1,10 @@
-import { Composition, Registry, Runtime } from '../context.js'
+import { Registry, Runtime } from '../context.js'
 
+/** A composition as declared, before its members are resolved. */
 interface Composition {
   name: string,
   components: string[]
+  services?: string[]
 }
 
 export interface Resources {

package/types/context.d.ts

@@ -20,7 +20,8 @@ interface Registry{
 
 interface Composition{
   name: string,
-  components: _component.Component[]
+  components: Manifest[]
+  services?: string[]
 }
 
 export interface Dependency<T = undefined>{
@@ -34,7 +35,7 @@ interface Context extends Declaration{
   environment?: string
   registry?: Registry
   compositions?: Composition[]
-  components?: _component.Component[]
+  components?: Manifest[]
   dependencies?: Record<string, Dependency[]>
 }