@toa.io/norm 1.0.0-alpha.29 → 1.0.0-alpha.291

package/src/.component/dereference.js

@@ -1,17 +1,15 @@
-'use strict'
+import { merge } from '@toa.io/generic'
 
-const { merge } = require('@toa.io/generic')
-
-const dereference = (manifest) => {
+export const dereference = (manifest) => {
   // schemas
-  const resolver = createResolver(manifest.entity?.schema?.properties)
-
-  if (manifest.entity !== undefined)
-    schema(manifest.entity.schema, resolver)
+  const properties = manifest.entity?.properties
+  const resolver = createResolver(properties)
 
-  if ('operations' in manifest)
-    operations(manifest, resolver)
+  if (properties !== undefined)
+    for (const [name, property] of Object.entries(properties))
+      properties[name] = schema(property, resolver)
 
+  if ('operations' in manifest) operations(manifest, resolver)
 }
 
 const createResolver = (properties) => (property) => {
@@ -22,10 +20,14 @@ const createResolver = (properties) => (property) => {
   return properties[property]
 }
 
-function operations (manifest, resolver) {
+function operations(manifest, resolver) {
   for (const operation of Object.values(manifest.operations)) {
     if (operation.input !== undefined) operation.input = schema(operation.input, resolver)
-    if (operation.output !== undefined) operation.output = schema(operation.output, resolver)
+
+    if (operation.output !== undefined)
+      if (Array.isArray(operation.output) && operation.output.length === 1)
+        operation.output = [schema(operation.output[0], resolver)]
+      else operation.output = schema(operation.output, resolver)
   }
 
   // forwarding
@@ -36,18 +38,19 @@ function operations (manifest, resolver) {
   for (const operation of Object.values(manifest.operations)) {
     delete operation.forwarded
   }
-
 }
 
 const schema = (object, resolve) => {
   if (object === undefined || object === null || typeof object !== 'object') return
-  if (object.type === 'string' && object.default?.[0] === '.') return resolve(object.default.substring(1))
+  if (object.type === 'string' && object.default?.[0] === '.')
+    return resolve(object.default.substring(1))
 
   if (object.type === 'array') {
     object.items = schema(object.items, resolve)
   } else if (object.properties !== undefined) {
     for (const [name, value] of Object.entries(object.properties)) {
-      if (value?.type === 'string' && value.default === '.') object.properties[name] = resolve(name)
+      if (value?.type === 'string' && value.default === '.')
+        object.properties[name] = resolve(name)
       else object.properties[name] = schema(value, resolve)
     }
   }
@@ -58,7 +61,8 @@ const schema = (object, resolve) => {
 const forward = (operation, operations) => {
   const target = operations[operation.forward]
 
-  if (target === undefined) throw new Error(`Referenced operation '${operation.forward}' is not defined`)
+  if (target === undefined)
+    throw new Error(`Referenced operation '${operation.forward}' is not defined`)
 
   if (target.forward !== undefined) {
     if (target.forwarded !== true) forward(target, operations)
@@ -72,5 +76,3 @@ const forward = (operation, operations) => {
 
   merge(operation, real)
 }
-
-exports.dereference = dereference

package/src/.component/expand.js

@@ -1,6 +1,4 @@
-'use strict'
-
-const {
+import {
   entity,
   bridge,
   operations,
@@ -9,9 +7,9 @@ const {
   extensions,
   properties,
   version
-} = require('./.expand')
+} from './.expand/index.js'
 
-async function expand (manifest) {
+export async function expand(manifest) {
   entity(manifest)
   bridge(manifest)
   operations(manifest)
@@ -22,5 +20,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,12 +14,15 @@ 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)
 
-      if (declaration === undefined) throw new Error(`Extension '${reference}' hasn't returned manifest`)
+      if (declaration === undefined)
+        throw new Error(`Extension '${reference}' hasn't returned manifest`)
     }
 
     extensions[key] = declaration
@@ -29,4 +32,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,10 @@
-'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 { migrations } from './migrations.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)
@@ -29,8 +28,7 @@ const define = async (root, manifest, property) => {
   // default bridge
   const definition = await scan(manifest.bridge, root, property)
 
-  if (definition === undefined)
-    return
+  if (definition === undefined) return
 
   const items = Object.entries(definition)
 
@@ -44,18 +42,31 @@ 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)
+  if (property in define) return define[property](root)
   else return undefined
 }
 
-exports.merge = bridge
+export { bridge as merge }

package/src/.component/migrations.js

@@ -0,0 +1,57 @@
+import { basename, extname, resolve } from 'node:path'
+import { readFile } from 'node:fs/promises'
+
+import glob from 'fast-glob'
+import { yaml } from '@toa.io/generic'
+
+/**
+ * The migrations a component declares, in the order they are applied. The file name without its
+ * extension is the migration's id, and sorting those ids is what orders them — so a name is
+ * written to sort: `0001-indexes`, then `0002-default-role`.
+ *
+ * What a file contains is the storage's business; this reads it and hands it over.
+ */
+export const migrations = async (root, manifest) => {
+  const paths = await glob(resolve(root, DIRECTORY, '*' + EXTENSIONS), GLOB)
+
+  if (paths.length === 0) return
+
+  if (manifest.entity === undefined)
+    throw new Error(`Component at '${root}' declares migrations but stores nothing`)
+
+  const ids = new Map()
+
+  // sorted, so the two files a conflict names are the same two on every machine
+  for (const path of paths.sort()) {
+    const id = basename(path, extname(path))
+    const found = ids.get(id)
+
+    if (found !== undefined)
+      throw new Error(
+        `Component at '${root}' has more than one ${DIRECTORY}/${id}: ` +
+          `${basename(found)} and ${basename(path)}`
+      )
+
+    ids.set(id, path)
+  }
+
+  manifest.entity.migrations = await Promise.all(
+    Array.from(ids, async ([id, path]) => ({ id, steps: await read(path) }))
+  )
+}
+
+/**
+ * A migration is a list of steps. A file that is not one is refused here rather than at the
+ * storage, where the component it belongs to is no longer known.
+ */
+async function read(path) {
+  const steps = yaml.load(await readFile(path, 'utf8'))
+
+  if (!Array.isArray(steps)) throw new Error(`Migration '${path}' is not a list of steps`)
+
+  return steps
+}
+
+const DIRECTORY = 'migrations'
+const EXTENSIONS = '.{yaml,yml,json}'
+const GLOB = { onlyFiles: true, absolute: true }

package/src/.component/normalize.js

@@ -1,11 +1,15 @@
-'use strict'
+import { entity, events, operations, receivers } from './.normalize/index.js'
 
-const { events, operations, receivers } = require('./.normalize')
+/**
+ * What a manifest does not say but the runtime needs said. The schema states what a value may
+ * be; what it is where nothing was written is decided here, so that validating a manifest is
+ * reading it rather than completing it.
+ */
+export const normalize = async (component) => {
+  component.namespace ??= 'default'
 
-const normalize = (component) => {
+  entity(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,22 @@ 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})?$
     not:
       oneOf:
-        - const: 'system'
+        - const: "system"
 
   version:
     type: string
@@ -60,56 +63,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]
+      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 +124,43 @@ 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"
+          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 error schema allows either
+            type: array
+            items:
+              type: [string, integer]
           query:
             type: boolean
         required: [type, scope, bindings]
@@ -149,8 +172,8 @@ properties:
             then:
               properties:
                 scope:
-                  enum: [object]
-              if: # transition query: false
+                  enum: [object, objects]
+              if: # not query: false
                 not:
                   properties:
                     query:
@@ -158,6 +181,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 +208,7 @@ properties:
             then:
               properties:
                 scope:
-                  enum: [object, objects, none]
+                  enum: [object, objects, stream, none]
                 query:
                   not:
                     const: false
@@ -189,15 +223,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,20 +237,16 @@ 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,43 +254,52 @@ 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
 
+  guards:
+    type: object
+    patternProperties:
+      ".*":
+        type: object
+        properties:
+          bridge: { type: string }
+          path: { type: string }
+        required: [bridge, path]
+        additionalProperties: false
+
   extensions:
     type: object