@toa.io/norm 1.0.0-alpha.32 → 1.0.0-alpha.320

package/src/.component/.normalize/operations.js

@@ -1,16 +1,23 @@
-'use strict'
-
-const operations = (component) => {
+export const operations = (component) => {
   if (component.operations === undefined) return
 
   for (const [endpoint, operation] of Object.entries(component.operations)) {
-    if (operation.type === 'computation' || operation.type === 'effect')
+    // what an operation of this type acquires, where it did not say
+    if (operation.type === 'computation' || operation.type === 'unmanaged') {
+      operation.scope = 'none'
       operation.query = false
+    } else if (operation.type === 'effect') operation.scope ??= 'none'
+
+    if (operation.scope === 'none') operation.query = false
+
+    // an operation that states no output states an empty schema, which every reply fits
+    operation.output ??= {}
+
+    // a bridge says an algorithm takes no input with `null`, which the manifest states as none
+    if (operation.input === null) delete operation.input
 
     if (operation.bindings === undefined) operation.bindings = component.bindings
     if (operation.bindings === null) operation.bindings = []
     if (operation.virtual === true) delete component.operations[endpoint]
   }
 }
-
-exports.operations = operations

package/src/.component/.normalize/receivers.js

@@ -1,6 +1,4 @@
-'use strict'
-
-function receivers (component) {
+export function receivers(component) {
   if (component.receivers === undefined) return
 
   const receivers = component.receivers
@@ -9,6 +7,9 @@ function receivers (component) {
     const segments = key.split('.')
     const source = value.source ?? 'default'
 
+    value.conditioned ??= false
+    value.adaptive ??= false
+
     if (source !== 'default') continue
     if (segments.length === 3) continue // already with a namespace
 
@@ -18,5 +19,3 @@ function receivers (component) {
     receivers[newKey] = value
   }
 }
-
-exports.receivers = receivers

package/src/.component/collapse.js

@@ -1,8 +1,6 @@
-'use strict'
+import { merge } from '@toa.io/generic'
 
-const { merge } = require('@toa.io/generic')
-
-const collapse = (manifest, prototype) => {
+export const collapse = (manifest, prototype) => {
   delete manifest.prototype
 
   if (prototype.operations) {
@@ -14,7 +12,8 @@ const collapse = (manifest, prototype) => {
       if (manifest.operations === undefined) manifest.operations = {}
 
       for (let [endpoint, operation] of operations) {
-        if (manifest.operations[endpoint] === undefined) manifest.operations[endpoint] = {}
+        if (manifest.operations[endpoint] === undefined)
+          manifest.operations[endpoint] = {}
         else {
           const { virtual, ...real } = operation
 
@@ -26,7 +25,8 @@ const collapse = (manifest, prototype) => {
         merge(manifest.operations[endpoint], declaration)
 
         if (bridge !== undefined) {
-          if (manifest.prototype.operations === undefined) manifest.prototype.operations = {}
+          if (manifest.prototype.operations === undefined)
+            manifest.prototype.operations = {}
 
           manifest.prototype.operations[endpoint] = { bridge }
         }
@@ -36,13 +36,64 @@ const collapse = (manifest, prototype) => {
 
   const { entity, events, extensions } = prototype
 
-  if (manifest.entity?.schema?.properties.id !== undefined && entity?.schema?.properties.id !== undefined) {
+  if (
+    manifest.entity?.properties?.id !== undefined &&
+    entity?.properties?.id !== undefined
+  ) {
     manifest.entity.custom = true
 
-    delete prototype.entity.schema.properties.id
+    delete prototype.entity.properties.id
   }
 
+  /*
+   * `id` is the only one a component may state for itself. The rest are written by the runtime
+   * and read by it, so one redeclared here would be merged over what the prototype says and
+   * change what the record holds, or what a criterion against it compares — without the
+   * component that wrote it having anything to do with either.
+   */
+  for (const name of SYSTEM)
+    if (
+      manifest.entity?.properties?.[name] !== undefined &&
+      entity?.properties?.[name] !== undefined
+    )
+      throw new Error(`System property '${name}' cannot be overridden`)
+
+  if (prototype.events !== undefined && manifest.events !== undefined)
+    for (const event of Object.keys(prototype.events))
+      if (event in manifest.events) delete prototype.events[event]
+
+  if (entity?.migrations !== undefined) inherit(manifest, prototype)
+
   merge(manifest, { entity, events, extensions })
 }
 
-exports.collapse = collapse
+/**
+ * What a prototype declares is in every record of its descendants, so its migrations are applied
+ * to each descendant's collection — ahead of the descendant's own, which are written against
+ * what they leave. An inherited one is recorded under the prototype's name, so that it collides
+ * with nothing the component names itself; one inherited from further up already carries its
+ * name and is passed on as it is.
+ */
+function inherit(manifest, prototype) {
+  const inherited = prototype.entity.migrations.map((migration) =>
+    migration.prototype === undefined
+      ? {
+          ...migration,
+          id: `${prototype.name}:${migration.id}`,
+          prototype: prototype.name
+        }
+      : migration
+  )
+
+  const own = manifest.entity?.migrations ?? []
+
+  if (manifest.entity === undefined) manifest.entity = {}
+
+  manifest.entity.migrations = [...inherited, ...own]
+
+  // merged below by `merge`, which would append them a second time
+  delete prototype.entity.migrations
+}
+
+/** What the runtime writes into every record. `id` is not among them: a component may own it. */
+const SYSTEM = ['VERSION', 'CREATED', 'UPDATED', 'DELETED', 'REGION']

package/src/.component/defaults.js

@@ -1,10 +1,7 @@
-'use strict'
-
-const { hash } = require('@toa.io/generic')
-const assert = require('node:assert')
+import { hash } from '@toa.io/generic'
 
 // these defaults are required before validation
-const defaults = (manifest, proto) => {
+export const defaults = (manifest, proto) => {
   if (manifest.name === undefined)
     if (proto) manifest.name = protoName(manifest)
     else nameAfterDir(manifest)
@@ -16,18 +13,17 @@ const defaults = (manifest, proto) => {
     if (manifest.entity.storage === null)
       manifest.entity.storage = '@toa.io/storages.null'
   } else {
-    if (manifest.prototype === undefined)
-      manifest.prototype = null
+    if (manifest.prototype === undefined) manifest.prototype = null
   }
 
   if (manifest.prototype === undefined) manifest.prototype = '@toa.io/prototype'
 }
 
-function protoName (manifest) {
+function protoName(manifest) {
   return 'proto' + hash(manifest.path)
 }
 
-function nameAfterDir (manifest) {
+function nameAfterDir(manifest) {
   const parts = manifest.path.split('/')
   const dirname = parts[parts.length - 1]
   const [name, namespace] = dirname.split('.').reverse()
@@ -35,5 +31,3 @@ function nameAfterDir (manifest) {
   manifest.name = name
   manifest.namespace = namespace
 }
-
-exports.defaults = defaults

package/src/.component/dependencies.js

@@ -1,29 +1,33 @@
-'use strict'
+import { createRequire } from 'node:module'
+import { join, dirname } from 'node:path'
 
-const { join, dirname } = require('node:path')
+// import.meta.resolve takes no paths, and a storage is resolved against the
+// component that names it
+const require = createRequire(import.meta.url)
 
 /**
  * @param {toa.norm.Component} component
  */
-const dependencies = (component) => {
-  if ('entity' in component) component.entity.storage = resolve(component.path, component.entity.storage)
+export const dependencies = (component) => {
+  if ('entity' in component)
+    component.entity.storage = resolve(component.path, component.entity.storage)
 }
 
-function resolve (root, reference) {
-  const paths = [root, __dirname]
+function resolve(root, reference) {
+  const paths = [root, import.meta.dirname]
   const options = { paths }
 
   let path
 
-  try { // as package
+  try {
+    // as package
     const packageJsonRef = join(reference, 'package.json')
 
     path = require.resolve(packageJsonRef, options)
-  } catch { // as directory
+  } catch {
+    // as directory
     path = require.resolve(reference, options)
   }
 
   return dirname(path)
 }
-
-exports.dependencies = dependencies

package/src/.component/dereference.js

@@ -1,34 +1,8 @@
-'use strict'
+import { merge } from '@toa.io/generic'
 
-const { merge } = require('@toa.io/generic')
+export const dereference = (manifest) => {
+  if (!('operations' in manifest)) return
 
-const dereference = (manifest) => {
-  // schemas
-  const resolver = createResolver(manifest.entity?.schema?.properties)
-
-  if (manifest.entity !== undefined)
-    schema(manifest.entity.schema, resolver)
-
-  if ('operations' in manifest)
-    operations(manifest, resolver)
-
-}
-
-const createResolver = (properties) => (property) => {
-  if (properties?.[property] === undefined) {
-    throw new Error(`Referenced property '${property}' is not defined`)
-  }
-
-  return properties[property]
-}
-
-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)
-  }
-
-  // forwarding
   for (const operation of Object.values(manifest.operations)) {
     if (operation.forward !== undefined) forward(operation, manifest.operations)
   }
@@ -36,29 +10,13 @@ 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 === '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)
-      else object.properties[name] = schema(value, resolve)
-    }
-  }
-
-  return object
 }
 
 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 +30,3 @@ const forward = (operation, operations) => {
 
   merge(operation, real)
 }
-
-exports.dereference = dereference

package/src/.component/expand.js

@@ -1,26 +1,20 @@
-'use strict'
-
-const {
+import {
   entity,
   bridge,
   operations,
   events,
   receivers,
   extensions,
-  properties,
   version
-} = require('./.expand')
+} from './.expand/index.js'
 
-async function expand (manifest) {
+export async function expand(manifest) {
   entity(manifest)
   bridge(manifest)
   operations(manifest)
   events(manifest)
   receivers(manifest)
-  properties(manifest)
   extensions(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 { PREDEFINED } from '@toa.io/definitions'
+import { resolve } from '../shortcuts.js'
+import { definition } from '../definition.js'
 
-const { directory: { find } } = require('@toa.io/filesystem')
-const { resolve } = require('../shortcuts')
-
-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,13 @@ const extensions = (manifest) => {
     // relative path
     if (key[0] === '.') key = find(key, manifest.path)
 
-    const extension = require(key)
+    const { module: extension } = await definition(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
@@ -28,5 +29,3 @@ const extensions = (manifest) => {
     if (reference !== key) delete extensions[reference]
   }
 }
-
-exports.extensions = extensions

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,12 @@
-'use strict'
+import { merge as combine } from '@toa.io/generic'
+import { definition } from '../definition.js'
 
-const { merge } = require('@toa.io/generic')
-
-const bridge = async (root, manifest) => {
+export const merge = 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,18 +19,17 @@ 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 bridged(bridge)
       const definition = await define[singular](root, endpoint)
 
-      merge(item, definition)
+      combine(item, definition)
     }
   }
 
   // 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 +43,29 @@ 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 combine(declared, item)
+      } catch (error) {
+        console.error(`Error merging ${singular} '${endpoint}' in ${root}`)
+        throw error
+      }
     }
   }
 }
 
 const scan = async (bridge, root, property) => {
-  const { define } = require(bridge)
+  const { define } = await bridged(bridge)
 
-  if (property in define)
-    return define[property](root)
+  if (property in define) return define[property](root)
   else return undefined
 }
 
-exports.merge = bridge
+async function bridged(reference) {
+  const { module } = await definition(reference)
+
+  if (module.define === undefined)
+    throw new Error(`Bridge '${reference}' defines nothing: it exports no 'define'`)
+
+  return module
+}

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