@toa.io/norm 1.0.0-alpha.310 → 1.0.0-alpha.312

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 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.312](https://github.com/toa-io/toa/compare/v1.0.0-alpha.311...v1.0.0-alpha.312) (2026-09-18)
+
+### Features
+
+* **bindings.http:** carry a call that holds a stream ([c571793](https://github.com/toa-io/toa/commit/c571793b617e3d5ae1dce5b98b64d67d7d8224f6))
+* **cli:** write the property that carries a stream into a component's types ([8eae8ce](https://github.com/toa-io/toa/commit/8eae8cea011c0be78b27ed1380a1a6f17c9479f8))
+* **norm:** let an operation declare the input property that carries a stream ([85a8f1f](https://github.com/toa-io/toa/commit/85a8f1ff5b62f658e0527dcce7230d8388d28fe0))
+* **operations:** refuse to render a chart for a context with no version ([d6cd083](https://github.com/toa-io/toa/commit/d6cd083bfe8d7da9f3d451c2c25d821eb41ce958))
+
+
+# [1.0.0-alpha.311](https://github.com/toa-io/toa/compare/v1.0.0-alpha.310...v1.0.0-alpha.311) (2026-09-17)
+
+**Note:** Version bump only for package @toa.io/norm
+
+
+
+
+
 # [1.0.0-alpha.310](https://github.com/toa-io/toa/compare/v1.0.0-alpha.309...v1.0.0-alpha.310) (2026-09-16)
 
 **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.310",
+  "version": "1.0.0-alpha.312",
   "type": "module",
   "description": "Toa declarations normalization and validation",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -21,12 +21,12 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.310",
-    "@toa.io/definitions": "1.0.0-alpha.310",
-    "@toa.io/generic": "1.0.0-alpha.310",
+    "@toa.io/core": "1.0.0-alpha.312",
+    "@toa.io/definitions": "1.0.0-alpha.312",
+    "@toa.io/generic": "1.0.0-alpha.311",
     "@toa.io/prototype": "1.0.0-alpha.301",
-    "@toa.io/schemas": "1.0.0-alpha.310",
+    "@toa.io/schemas": "1.0.0-alpha.311",
     "fast-glob": "3.3.3"
   },
-  "gitHead": "d952c57f77279729e26d52d50c6df47138ad0a4f"
+  "gitHead": "3cdff9b9779eeb6ae83913fefc0b502a10a0236a"
 }

package/src/.component/schema.yaml

@@ -161,6 +161,9 @@ properties:
           stateful:
             # served by every process under an address of its own, which a call names; see documentation/stateful.md
             type: boolean
+          stream:
+            # the input property that carries a stream, read as its caller writes it; see documentation/streams.md
+            $ref: "#/definitions/name"
           forward:
             $ref: "#/definitions/name"
           bridge:
@@ -280,6 +283,13 @@ properties:
               properties:
                 scope:
                   enum: [object, objects, stream, none]
+          - if: # takes a stream
+              required: [stream]
+            then:
+              properties:
+                type:
+                  # a transition may run its algorithm twice over one call, and a stream is read once
+                  enum: [effect, computation, unmanaged]
         additionalProperties: false
     additionalProperties: false
 

package/src/.component/validate.js

@@ -16,6 +16,7 @@ export const validate = async (manifest) => {
   if (error) throw error
 
   if (manifest.entity !== undefined) entity(manifest)
+  if (manifest.operations !== undefined) await streams(manifest)
   if (manifest.events !== undefined) await events(manifest)
   if (manifest.receivers !== undefined) receivers(manifest)
 }
@@ -33,6 +34,27 @@ const entity = (manifest) => {
       throw new Error(`Entity blank names property '${name}', which is not defined`)
 }
 
+/**
+ * An operation that takes a stream is reachable over a binding that carries one. A binding that
+ * declares none is served in this process alone, which is a component saying so.
+ */
+const streams = async (manifest) => {
+  for (const [endpoint, operation] of Object.entries(manifest.operations)) {
+    if (operation.stream === undefined || operation.bindings.length === 0) continue
+    if (await carried(operation.bindings)) continue
+
+    throw new Error(`Operation '${endpoint}' takes a stream, which none of its bindings carries`)
+  }
+}
+
+/** Whether any of these bindings carries a call whose input holds a stream. */
+const carried = async (bindings) => {
+  for (const binding of bindings)
+    if ((await definition(binding)).module.properties.streams === true) return true
+
+  return false
+}
+
 const events = async (manifest) => {
   for (const [label, event] of Object.entries(manifest.events)) {
     const { properties } = (await definition(event.binding)).module

package/src/.context/validate.js

@@ -9,5 +9,8 @@ const object = yaml.load(readFileSync(path, 'utf8'))
 const schema = schemas.schema(object)
 
 export const validate = (context) => {
-  schema.validate(context)
+  schema.validate(context, CONTEXT)
 }
+
+/** The file a reader has to edit, since nothing else in the message names it. */
+const CONTEXT = 'context.toa.yaml'

package/src/shortcuts.js

@@ -38,6 +38,7 @@ export const recognize = (shortcuts, object, group) => {
 
 export const SHORTCUTS = {
   amqp: '@toa.io/bindings.amqp',
+  http: '@toa.io/bindings.http',
   node: '@toa.io/bridges.node',
   bash: '@toa.io/bridges.bash',
   mongodb: '@toa.io/storages.mongodb',

package/test/component/validate.test.js

@@ -330,3 +330,42 @@ describe('stateful', () => {
     await assert.rejects(validate(manifest), (error) => /must be boolean/.test(error.message))
   })
 })
+
+describe('stream', () => {
+  beforeEach(() => {
+    manifest.operations.read = {
+      type: 'computation',
+      scope: 'none',
+      query: false,
+      bridge: 'whatever',
+      bindings: ['@toa.io/bindings.amqp'],
+      stream: 'content'
+    }
+  })
+
+  it('should reject an operation whose bindings carry no stream', async () => {
+    await assert.rejects(validate(manifest), (error) =>
+      /takes a stream, which none of its bindings carries/.test(error.message)
+    )
+  })
+
+  it('should accept an operation served where it is composed', async () => {
+    manifest.operations.read.bindings = []
+
+    await assert.doesNotReject(validate(manifest))
+  })
+
+  it('should accept an operation bound to a binding that carries a stream', async () => {
+    manifest.operations.read.bindings = ['@toa.io/bindings.http']
+
+    await assert.doesNotReject(validate(manifest))
+  })
+
+  it('should reject a transition that takes a stream', async () => {
+    manifest.operations.add.stream = 'content'
+
+    await assert.rejects(validate(manifest), (error) =>
+      /must be equal to one of the allowed values/.test(error.message)
+    )
+  })
+})

package/types/component.d.ts

@@ -16,6 +16,8 @@ export type Operation = {
   query?: boolean
   /** served by every process under an address of its own, which a call to it names */
   stateful?: boolean
+  /** the input property that carries a stream, read as its caller writes it */
+  stream?: string
 }
 
 export type Operations = Record<string, Operation>