@toa.io/norm 1.0.0-alpha.28 → 1.0.0-alpha.283

package/src/.component/expand.js

@@ -1,17 +1,6 @@
-'use strict'
+import { entity, bridge, operations, events, receivers, extensions, properties, version } from './.expand/index.js'
 
-const {
-  entity,
-  bridge,
-  operations,
-  events,
-  receivers,
-  extensions,
-  properties,
-  version
-} = require('./.expand')
-
-async function expand (manifest) {
+export async function expand (manifest) {
   entity(manifest)
   bridge(manifest)
   operations(manifest)
@@ -22,5 +11,3 @@ async function expand (manifest) {
 
   await version(manifest)
 }
-
-exports.expand = expand

package/src/.component/extensions.js

@@ -1,10 +1,10 @@
-'use strict'
+import { find } from '@toa.io/generic'
+import { resolve } from '../shortcuts.js'
 
-const { directory: { find } } = require('@toa.io/filesystem')
-const { resolve } = require('../shortcuts')
+const cache = {}
 
-const extensions = (manifest) => {
-  if (manifest.extensions === undefined) return
+export const extensions = async (manifest) => {
+  manifest.extensions = Object.assign({}, PREDEFINED, manifest.extensions)
 
   const extensions = manifest.extensions
 
@@ -14,7 +14,9 @@ const extensions = (manifest) => {
     // relative path
     if (key[0] === '.') key = find(key, manifest.path)
 
-    const extension = require(key)
+    cache[key] ??= import(key)
+
+    const extension = await cache[key]
 
     if (extension.manifest !== undefined) {
       declaration = extension.manifest(declaration, manifest)
@@ -29,4 +31,8 @@ const extensions = (manifest) => {
   }
 }
 
-exports.extensions = extensions
+const PREDEFINED = {
+  '@toa.io/extensions.telemetry': null,
+  '@toa.io/extensions.fetch': null,
+  '@toa.io/extensions.introspection': null
+}

package/src/.component/index.js

@@ -1,21 +1,9 @@
-'use strict'
-
-const { collapse } = require('./collapse')
-const { defaults } = require('./defaults')
-const { dependencies } = require('./dependencies')
-const { dereference } = require('./dereference')
-const { expand } = require('./expand')
-const { merge } = require('./merge')
-const { normalize } = require('./normalize')
-const { validate } = require('./validate')
-const { extensions } = require('./extensions')
-
-exports.collapse = collapse
-exports.defaults = defaults
-exports.dependencies = dependencies
-exports.dereference = dereference
-exports.expand = expand
-exports.merge = merge
-exports.normalize = normalize
-exports.validate = validate
-exports.extensions = extensions
+export { collapse } from './collapse.js'
+export { defaults } from './defaults.js'
+export { dependencies } from './dependencies.js'
+export { dereference } from './dereference.js'
+export { expand } from './expand.js'
+export { merge } from './merge.js'
+export { normalize } from './normalize.js'
+export { validate } from './validate.js'
+export { extensions } from './extensions.js'

package/src/.component/merge.js

@@ -1,12 +1,11 @@
-'use strict'
-
-const { merge } = require('@toa.io/generic')
+import { merge } from '@toa.io/generic'
 
 const bridge = async (root, manifest) => {
   await Promise.all([
     define(root, manifest, 'operations'),
     define(root, manifest, 'events'),
-    define(root, manifest, 'receivers')
+    define(root, manifest, 'receivers'),
+    define(root, manifest, 'guards')
   ])
 }
 
@@ -19,7 +18,7 @@ const define = async (root, manifest, property) => {
       if (item.bridge === undefined || item.bridge === manifest.bridge) continue // default bridge later
 
       const bridge = item.bridge || manifest.bridge
-      const { define } = require(bridge)
+      const { define } = await req(bridge)
       const definition = await define[singular](root, endpoint)
 
       merge(item, definition)
@@ -44,18 +43,32 @@ const define = async (root, manifest, property) => {
 
       const declared = manifest[property][endpoint]
 
-      if (declared === undefined) manifest[property][endpoint] = item
-      else merge(declared, item)
+      try {
+        if (declared === undefined) manifest[property][endpoint] = item
+        else merge(declared, item)
+      } catch (error) {
+        console.error(`Error merging ${singular} '${endpoint}' in ${root}`)
+        throw error
+      }
     }
   }
 }
 
+const cache = {}
+
+// the promise is what is remembered, so a bridge is loaded once
+function req (mod) {
+  cache[mod] ??= import(mod)
+
+  return cache[mod]
+}
+
 const scan = async (bridge, root, property) => {
-  const { define } = require(bridge)
+  const { define } = await req(bridge)
 
   if (property in define)
     return define[property](root)
   else return undefined
 }
 
-exports.merge = bridge
+export { bridge as merge }

package/src/.component/normalize.js

@@ -1,11 +1,7 @@
-'use strict'
+import { events, operations, receivers } from './.normalize/index.js'
 
-const { events, operations, receivers } = require('./.normalize')
-
-const normalize = (component) => {
+export const normalize = async (component) => {
   operations(component)
-  events(component)
+  await events(component)
   receivers(component)
 }
-
-exports.normalize = normalize

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,19 +17,19 @@ 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
@@ -38,19 +38,23 @@ properties:
     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})?$
+    default: "default"
     not:
       oneOf:
-        - const: 'system'
+        - const: "system"
 
   version:
     type: string
@@ -60,15 +64,17 @@ properties:
     properties:
       image:
         type: string
+      run:
+        type: string
 
   entity:
     type: object
     properties:
       storage:
         type: string
-        default: '@toa.io/storages.mongodb'
+        default: "@toa.io/storages.mongodb"
       schema:
-        $ref: 'definitions#/definitions/schema'
+        $ref: https://json-schema.org/draft/2019-09/schema
         type: object
         properties:
           type:
@@ -78,24 +84,24 @@ properties:
             type: object
             propertyNames:
               oneOf:
-                - $ref: '#/definitions/name'
+                - $ref: "#/definitions/name"
                 - enum: [_version, _created, _updated, _deleted]
       unique:
         type: object
         patternProperties:
-          '.*':
+          ".*":
             type: array
             items:
               type: string
       index:
         type: object
         patternProperties:
-          '.*':
+          ".*":
             type: object
             patternProperties:
-              '.*':
+              ".*":
                 type: string
-                enum: [asc, desc, hash]
+                enum: [asc, desc, hash, text]
       associated:
         type: boolean
         default: false
@@ -109,7 +115,7 @@ properties:
     type: array
     uniqueItems: true
     items:
-      $ref: '#/definitions/binding'
+      $ref: "#/definitions/binding"
 
   bridge:
     type: string
@@ -117,27 +123,41 @@ 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, none]
+            enum: [object, objects, changeset, stream, none]
           concurrency:
             enum: [none, retry]
           forward:
-            $ref: '#/definitions/name'
+            $ref: "#/definitions/name"
           bridge:
             type: string
           bindings:
-            $ref: '#/properties/bindings'
+            $ref: "#/properties/bindings"
           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
+            default: {}
+          errors:
+            # what a reply may carry as a code: the error schema allows either
+            type: array
+            items:
+              type: [string, integer]
           query:
             type: boolean
         required: [type, scope, bindings]
@@ -149,8 +169,8 @@ properties:
             then:
               properties:
                 scope:
-                  enum: [object]
-              if: # transition query: false
+                  enum: [object, objects]
+              if: # not query: false
                 not:
                   properties:
                     query:
@@ -158,6 +178,17 @@ properties:
                   required: [query]
               then:
                 required: [concurrency]
+          - if: # transition and scope=objects
+              properties:
+                type:
+                  const: transition
+                scope:
+                  const: objects
+            then:
+              properties:
+                query:
+                  not:
+                    const: false
           - if: # not transition
               not:
                 properties:
@@ -174,7 +205,7 @@ properties:
             then:
               properties:
                 scope:
-                  enum: [object, objects, none]
+                  enum: [object, objects, stream, none]
                 query:
                   not:
                     const: false
@@ -189,7 +220,7 @@ properties:
           - if: # computation
               properties:
                 type:
-                  const: computation
+                  enum: [computation, unmanaged]
             then:
               properties:
                 scope:
@@ -205,20 +236,17 @@ properties:
             then:
               properties:
                 scope:
-                  const: none
                   default: none
-                query:
-                  const: false
-                  default: false
+                  enum: [object, objects, stream, none]
         additionalProperties: false
     additionalProperties: false
 
   events:
     type: object
     propertyNames:
-      $ref: 'definitions#/definitions/name'
+      $ref: "#/definitions/name"
     patternProperties:
-      '.*':
+      ".*":
         type: object
         properties:
           bridge:
@@ -226,7 +254,7 @@ properties:
           path:
             type: string
           binding:
-            $ref: '#/definitions/binding'
+            $ref: "#/definitions/binding"
           conditioned:
             type: boolean
             default: false
@@ -239,17 +267,17 @@ properties:
   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:
@@ -260,9 +288,22 @@ properties:
           adaptive:
             type: boolean
             default: false
+          arguments:
+            type: array
         required: [operation]
         additionalProperties: false
 
+  guards:
+    type: object
+    patternProperties:
+      ".*":
+        type: object
+        properties:
+          bridge: { type: string }
+          path: { type: string }
+        required: [bridge, path]
+        additionalProperties: false
+
   extensions:
     type: object
 

package/src/.component/validate.js

@@ -1,25 +1,26 @@
-'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'
 
-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.events !== undefined) await events(manifest)
   if (manifest.receivers !== undefined) receivers(manifest)
 }
 
-const events = (manifest) => {
+const events = async (manifest) => {
   for (const [label, event] of Object.entries(manifest.events)) {
-    if (require(event.binding).properties.async !== true) {
+    const { properties } = await import(event.binding)
+
+    if (properties.async !== true) {
       throw new Error(`Event '${label}' binding '${event.binding}' is not async`)
     }
   }
@@ -32,11 +33,9 @@ const receivers = (manifest) => {
     }
 
     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,8 +1,6 @@
-'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
@@ -47,5 +45,3 @@ const connectors = (context, extracted) => {
 
   return connectors
 }
-
-exports.connectors = connectors

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

@@ -1,10 +1,6 @@
-'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 })

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

@@ -1,9 +1,16 @@
-'use strict'
+import { component as load } from '../../component.js'
+import { load as loadDependency } from './load.js'
 
-const extensions = async (context) => {
+export const extensions = async (context) => {
   const extensions = {}
   const components = context.components?.slice() ?? []
-  const extracted = await extractExtensionComponents(components, extensions)
+
+  // 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)
 
@@ -20,8 +27,25 @@ const extensions = async (context) => {
   return { extensions, components: extracted }
 }
 
-async function extractExtensionComponents (components, extensions) {
-  const { component: load } = require('../../component')
+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,26 +55,39 @@ async function extractExtensionComponents (components, extensions) {
     for (const reference of Object.keys(component.extensions)) {
       if (reference in extensions) continue
 
-      extensions[reference] = []
-
-      const mod = require(reference)
-
-      if (mod.components === undefined) continue
-
-      for (const path of mod.components().paths) {
-        const component = await load(path)
-
-        extracted.push(component)
-      }
+      extracted.push(...await extract(reference, extensions, annotations))
     }
   }
 
   if (extracted.length === 0)
     return extracted
 
-  const deeper = await extractExtensionComponents(extracted, extensions)
+  const deeper = await extractExtensionComponents(extracted, extensions, annotations)
 
   return extracted.concat(deeper)
 }
 
-exports.extensions = extensions
+/**
+ * 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/index.js

@@ -1,9 +1,3 @@
-'use strict'
-
-const { connectors } = require('./connectors')
-const { extensions } = require('./extensions')
-const { resolve } = require('./resolve')
-
-exports.connectors = connectors
-exports.extensions = extensions
-exports.resolve = resolve
+export { connectors } from './connectors.js'
+export { extensions } from './extensions.js'
+export { resolve } from './resolve.js'