@toa.io/norm 1.0.0-alpha.33 → 1.0.0-alpha.330

package/src/.component/schema.yaml

@@ -8,7 +8,7 @@ definitions:
   binding:
     type: string
     not:
-      const: '@toa.io/bindings.loop' # loop is for system use only
+      const: "@toa.io/bindings.loop" # loop is for system use only
 
 type: object
 properties:
@@ -17,40 +17,55 @@ properties:
     nullable: true
     properties:
       prototype:
-        $ref: '#/properties/prototype'
+        $ref: "#/properties/prototype"
       path:
         type: string
       operations:
         type: object
         propertyNames:
-          $ref: '#/definitions/name'
+          $ref: "#/definitions/name"
         patternProperties:
-          '.*':
+          ".*":
             type: object
             properties:
               bridge:
-                $ref: '#/properties/bridge'
+                $ref: "#/properties/bridge"
 
   path:
     type: string
 
+  files:
+    # what this component's version is made of, where a build of it copies only some of it
+    type: array
+    items:
+      type: string
+
+  ignore:
+    # what its version is not made of, added to what the bridge states; `!` puts one of those back
+    type: array
+    items:
+      type: string
+
   locator:
     type: object
     properties:
       id:
-        $ref: 'definitions#/definitions/locator'
+        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]+)?))$
       label:
-        $ref: 'definitions#/definitions/label'
+        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]+)?))*$
 
   name:
-    $ref: 'definitions#/definitions/token'
+    type: string
+    pattern: ^[a-zA-Z]([a-zA-Z0-9]{1,31})?$
 
   namespace:
-    $ref: 'definitions#/definitions/token'
-    default: 'default'
+    type: string
+    pattern: ^[a-zA-Z]([a-zA-Z0-9]{1,31})?$
     not:
       oneOf:
-        - const: 'system'
+        - const: "system"
 
   version:
     type: string
@@ -60,56 +75,60 @@ properties:
     properties:
       image:
         type: string
+      run:
+        type: string
 
   entity:
     type: object
     properties:
       storage:
         type: string
-        default: '@toa.io/storages.mongodb'
-      schema:
-        $ref: 'definitions#/definitions/schema'
+      properties:
         type: object
-        properties:
-          type:
-            default: object
-            const: object
-          properties:
-            type: object
-            propertyNames:
-              oneOf:
-                - $ref: '#/definitions/name'
-                - enum: [_version, _created, _updated, _deleted]
-      unique:
+        # a system property is named like any other, so nothing is enumerated beside them
+        propertyNames:
+          $ref: "#/definitions/name"
+        additionalProperties:
+          $ref: https://json-schema.org/draft/2019-09/schema
+      required:
+        type: array
+        uniqueItems: true
+        items:
+          $ref: "#/definitions/name"
+      blank:
+        # what a record holds before anything is written to it; a system property is the
+        # runtime's to write, so none may be named here
         type: object
-        patternProperties:
-          '.*':
-            type: array
-            items:
+        propertyNames:
+          not:
+            enum: [id, VERSION, CREATED, UPDATED, DELETED, REGION, TRAILERS, DISCARD]
+      migrations:
+        type: array
+        items:
+          type: object
+          properties:
+            id:
               type: string
-      index:
-        type: object
-        patternProperties:
-          '.*':
-            type: object
-            patternProperties:
-              '.*':
-                type: string
-                enum: [asc, desc, hash]
+            # what a step means belongs to the storage, which is the only thing that reads it
+            steps:
+              type: array
+            # the prototype it is inherited from; absent on the component's own
+            prototype:
+              type: string
+          required: [id, steps]
+          additionalProperties: false
       associated:
         type: boolean
-        default: false
       custom:
         type: boolean
-        default: false
-    required: [schema]
+    required: [properties]
     additionalProperties: false
 
   bindings:
     type: array
     uniqueItems: true
     items:
-      $ref: '#/definitions/binding'
+      $ref: "#/definitions/binding"
 
   bridge:
     type: string
@@ -117,27 +136,60 @@ properties:
   operations:
     type: object
     propertyNames:
-      $ref: '#/definitions/name'
+      $ref: "#/definitions/name"
     patternProperties:
-      '.*':
+      ".*":
         type: object
         properties:
           type:
-            enum: [transition, observation, assignment, computation, effect]
+            enum:
+              [
+                transition,
+                observation,
+                assignment,
+                computation,
+                effect,
+                unmanaged,
+              ]
           scope:
-            enum: [object, objects, changeset, stream, none]
+            enum: [entry, entries, changeset, stream, none]
           concurrency:
             enum: [none, retry]
+          once:
+            # the same call arriving twice changes state once; see documentation/inbox.md
+            # a number is how many seconds a call is remembered, which a deployment's
+            # `inbox.retention` is the default for; ten minutes at least, because the broker
+            # alone repeats a call for about that long. One type list rather than `oneOf`: the
+            # manifest is validated with coercion, and a branch would coerce `true` into `1`
+            type: [boolean, integer]
+            minimum: 600
+          stateful:
+            # served by every process under an address of its own, which a call names; see documentation/stateful.md
+            type: boolean
+          unchained:
+            # every call begins a chain of its own, so a circle through it is refused by neither rule; see documentation/cycles.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'
+            $ref: "#/definitions/name"
           bridge:
             type: string
           bindings:
-            $ref: '#/properties/bindings'
+            $ref: "#/properties/bindings"
+          description:
+            # what the operation is, for whoever reads it: a generated type, an OPTIONS, a model
+            type: string
           input:
-            $ref: 'definitions#/definitions/schema'
+            $ref: https://json-schema.org/draft/2019-09/schema
           output:
-            $ref: 'definitions#/definitions/schema'
+            $ref: https://json-schema.org/draft/2019-09/schema
+          errors:
+            # what a reply may carry as a code: the message of the error returned
+            type: array
+            items:
+              type: string
           query:
             type: boolean
         required: [type, scope, bindings]
@@ -149,8 +201,8 @@ properties:
             then:
               properties:
                 scope:
-                  enum: [object]
-              if: # transition query: false
+                  enum: [entry, entries]
+              if: # not query: false
                 not:
                   properties:
                     query:
@@ -158,6 +210,17 @@ properties:
                   required: [query]
               then:
                 required: [concurrency]
+          - if: # transition and scope=entries
+              properties:
+                type:
+                  const: transition
+                scope:
+                  const: entries
+            then:
+              properties:
+                query:
+                  not:
+                    const: false
           - if: # not transition
               not:
                 properties:
@@ -167,6 +230,30 @@ properties:
               properties:
                 concurrency:
                   const: ~ # never pass
+          - if: # neither a transition nor an assignment
+              not:
+                properties:
+                  type:
+                    enum: [transition, assignment]
+            then:
+              properties:
+                # An operation that writes nothing has nothing to record. An effect writes, but
+                # its write is get-or-create, so a second arrival of one writes nothing already —
+                # and it writes in `acquire`, before its algorithm has run, so its reply is not
+                # known where the record is made.
+                once:
+                  const: ~ # never pass
+          - if: # commits more than one entity
+              properties:
+                type:
+                  const: transition
+                scope:
+                  const: entries
+            then:
+              properties:
+                # the reply is recorded, and over a set it is unbounded
+                once:
+                  const: ~ # never pass
           - if: # observation
               properties:
                 type:
@@ -174,7 +261,7 @@ properties:
             then:
               properties:
                 scope:
-                  enum: [object, objects, stream, none]
+                  enum: [entry, entries, stream, none]
                 query:
                   not:
                     const: false
@@ -189,15 +276,13 @@ properties:
           - if: # computation
               properties:
                 type:
-                  const: computation
+                  enum: [computation, unmanaged]
             then:
               properties:
                 scope:
                   const: none
-                  default: none
                 query:
                   const: false
-                  default: false
           - if: # effect
               properties:
                 type:
@@ -205,17 +290,23 @@ properties:
             then:
               properties:
                 scope:
-                  default: none
-                  enum: [object, objects, stream, none]
+                  enum: [entry, entries, 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
 
   events:
     type: object
     propertyNames:
-      $ref: 'definitions#/definitions/name'
+      $ref: "#/definitions/name"
     patternProperties:
-      '.*':
+      ".*":
         type: object
         properties:
           bridge:
@@ -223,49 +314,53 @@ properties:
           path:
             type: string
           binding:
-            $ref: '#/definitions/binding'
+            $ref: "#/definitions/binding"
           conditioned:
             type: boolean
-            default: false
           subjective:
             type: boolean
-            default: false
         required: [bridge, path]
         additionalProperties: false
 
   receivers:
     type: object
     patternProperties:
-      '.*':
+      ".*":
         type: object
         properties:
           operation:
-            $ref: 'definitions#/definitions/name'
+            $ref: "#/definitions/name"
           bridge:
             type: string
           binding:
             type: string
           source:
-            $ref: 'definitions#/definitions/name'
+            $ref: "#/definitions/name"
             not:
               const: context
           path:
             type: string
           conditioned:
             type: boolean
-            default: false
           adaptive:
             type: boolean
-            default: false
           arguments:
             type: array
         required: [operation]
         additionalProperties: false
 
-  extensions:
+  guards:
     type: object
+    patternProperties:
+      ".*":
+        type: object
+        properties:
+          bridge: { type: string }
+          path: { type: string }
+        required: [bridge, path]
+        additionalProperties: false
 
-  properties:
+  extensions:
     type: object
 
 additionalProperties: false

package/src/.component/validate.js

@@ -1,25 +1,73 @@
-'use strict'
+import path from 'node:path'
 
-const path = require('node:path')
+import { readFileSync } from 'node:fs'
+import { yaml } from '@toa.io/generic'
+import * as schemas from '@toa.io/schemas'
+import { definition } from '../definition.js'
 
-const { load } = require('@toa.io/yaml')
-const { Schema } = require('@toa.io/schema')
+const object = yaml.load(
+  readFileSync(path.resolve(import.meta.dirname, 'schema.yaml'), 'utf8')
+)
+const schema = schemas.schema(object)
 
-const object = load.sync(path.resolve(__dirname, 'schema.yaml'))
-const schema = new Schema(object)
-
-const validate = (manifest) => {
+export const validate = async (manifest) => {
   const error = schema.fit(manifest)
 
-  if (error) throw new Error(error.message)
+  if (error) throw error
 
-  if (manifest.events !== undefined) events(manifest)
+  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)
 }
 
-const events = (manifest) => {
+/** What only the entity's own declaration can answer: whether a name it uses is one it declares. */
+const entity = (manifest) => {
+  const { properties, required, blank } = manifest.entity
+
+  // what an algorithm writes beside the record: for the event of its commit, and to have
+  // nothing of it committed; neither is ever stored
+  for (const name of ['TRAILERS', 'DISCARD'])
+    if (properties[name] !== undefined)
+      throw new Error(`System property '${name}' cannot be declared`)
+
+  for (const name of required ?? [])
+    if (properties[name] === undefined)
+      throw new Error(`Entity requires property '${name}', which is not defined`)
+
+  for (const name of Object.keys(blank ?? {}))
+    if (properties[name] === undefined)
+      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)) {
-    if (require(event.binding).properties.async !== true) {
+    const { properties } = (await definition(event.binding)).module
+
+    if (properties.async !== true) {
       throw new Error(`Event '${label}' binding '${event.binding}' is not async`)
     }
   }
@@ -28,15 +76,17 @@ const events = (manifest) => {
 const receivers = (manifest) => {
   for (const [locator, receiver] of Object.entries(manifest.receivers)) {
     if (manifest.operations?.[receiver.operation] === undefined) {
-      throw new Error(`Receiver '${locator}' refers to undefined operation '${receiver.operation}'`)
+      throw new Error(
+        `Receiver '${locator}' refers to undefined operation '${receiver.operation}'`
+      )
     }
 
     if (!TYPES.has(manifest.operations[receiver.operation].type)) {
-      throw new Error(`Receiver '${locator}' must refer to an operation of one of the allowed types: ${Array.from(TYPES).join(', ')}`)
+      throw new Error(
+        `Receiver '${locator}' must refer to an operation of the allowed types: ${Array.from(TYPES).join(', ')}`
+      )
     }
   }
 }
 
-const TYPES = new Set(['transition', 'effect'])
-
-exports.validate = validate
+const TYPES = new Set(['transition', 'assignment', 'effect', 'unmanaged'])

package/src/.context/.dependencies/connectors.js

@@ -1,14 +1,12 @@
-'use strict'
+import { resolve } from 'node:path'
 
-const { resolve } = require('node:path')
-
-const connectors = (context, extracted) => {
+export const connectors = (context, extracted) => {
   const connectors = {}
 
-  const components = (context.components === undefined
+  const components =
+    (context.components === undefined
       ? extracted
-      : context.components.concat(extracted)
-  ) ?? []
+      : context.components.concat(extracted)) ?? []
 
   for (const component of components) {
     if (component.entity !== undefined) {
@@ -47,5 +45,3 @@ const connectors = (context, extracted) => {
 
   return connectors
 }
-
-exports.connectors = connectors

package/src/.context/.dependencies/describe.js

@@ -1,10 +1,9 @@
-'use strict'
-
 /**
  * @param {toa.norm.Component} component
  * @param {Object} manifest
  * @returns {toa.norm.context.dependencies.Instance}
  */
-const describe = (component, manifest = undefined) => ({ locator: component.locator, manifest })
-
-exports.describe = describe
+export const describe = (component, manifest = undefined) => ({
+  locator: component.locator,
+  manifest
+})