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

package/src/.component/.expand/version.js

@@ -1,45 +1,89 @@
-'use strict'
+import { join } from 'node:path'
+import { createHash } from 'node:crypto'
+import fs from 'node:fs/promises'
+import { glob } from 'tinyglobby'
 
-const { join } = require('node:path')
-const { createHash } = require('node:crypto')
-const fs = require('node:fs/promises')
-const { createReadStream } = require('node:fs')
-const { once } = require('node:events')
+import { definition } from '../../definition.js'
 
-async function version (manifest) {
-  manifest.version ??= await hash(manifest.path)
+export async function version(manifest) {
+  manifest.version ??= await hash(manifest)
 }
 
-async function hash (path) {
-  const hash = await hashd(path)
+/**
+ * Identifies a build of a component: it becomes the tag of its image, so it must be the
+ * same for the same sources and different for different ones — on any machine, and whichever
+ * build produced them.
+ *
+ * What a build leaves out cannot change it: the bridge states what no build ships, a component
+ * adds to that with `ignore` and puts one back with `!`, and `files` names what its version is
+ * made of where a build copies only some of it. Its manifest is always one of them, because
+ * what it declares is what a caller is held to.
+ */
+async function hash(manifest) {
+  const files = (await list(manifest)).sort()
+  const digests = await Promise.all(
+    files.map((file) => digest(join(manifest.path, file)))
+  )
+  const total = createHash('sha256')
 
-  return hash.digest('hex').slice(0, 8)
+  // the path is part of it: moving a file changes the build even if no content did
+  for (let i = 0; i < files.length; i++) total.update(files[i]).update(digests[i])
+
+  return total.digest('hex').slice(0, 8)
 }
 
 /**
- * @param {string} path
- * @param {import('node:crypto').Hash} hash
+ * @param {toa.norm.Component} manifest
+ * @returns {Promise<string[]>} paths relative to the component
  */
-async function hashd (path, hash = createHash('sha256')) {
-  const stat = await fs.stat(path)
+async function list(manifest) {
+  const files = await glob(patterns(manifest.files), {
+    cwd: manifest.path,
+    dot: true,
+    onlyFiles: true,
+    expandDirectories: false,
+    // sources a component keeps outside its own directory are its own: what a link points to is
+    // hashed as the file it stands for, so changing it changes the version
+    followSymbolicLinks: true,
+    ignore: await ignore(manifest)
+  })
+
+  // what a component declares is what a caller is held to, so its manifest is always one of them
+  if (!files.includes(MANIFEST) && (await exists(join(manifest.path, MANIFEST))))
+    files.push(MANIFEST)
 
-  if (stat.isFile()) {
-    const stream = createReadStream(path)
+  return files
+}
 
-    stream.pipe(hash, { end: false })
+/** A path names what is under it, and a pattern is taken as it is. */
+function patterns(files = ['**']) {
+  return files.flatMap((file) => (file.includes('*') ? [file] : [file, file + '/**']))
+}
 
-    return await once(stream, 'end')
-  }
+async function ignore(manifest) {
+  const { module } = await definition(manifest.bridge)
+  const stated = manifest.ignore ?? []
+  const back = new Set(
+    stated.filter((pattern) => pattern[0] === '!').map((pattern) => pattern.slice(1))
+  )
 
-  if (stat.isDirectory()) {
-    const entries = await fs.opendir(path)
+  return [
+    ...(module.ignore ?? []).filter((pattern) => !back.has(pattern)),
+    ...stated.filter((pattern) => pattern[0] !== '!')
+  ]
+}
 
-    for await (const entry of entries) {
-      await hashd(join(path, entry.name), hash)
-    }
+async function exists(path) {
+  return await fs
+    .access(path)
+    .then(() => true)
+    .catch(() => false)
+}
 
-    return hash
-  }
+async function digest(path) {
+  return createHash('sha256')
+    .update(await fs.readFile(path))
+    .digest()
 }
 
-exports.version = version
+const MANIFEST = 'manifest.toa.yaml'

package/src/.component/.normalize/entity.js

@@ -0,0 +1,7 @@
+export function entity(component) {
+  if (component.entity === undefined) return
+
+  component.entity.storage ??= '@toa.io/storages.mongodb'
+  component.entity.associated ??= false
+  component.entity.custom ??= false
+}

package/src/.component/.normalize/events.js

@@ -1,13 +1,25 @@
-'use strict'
+import { definition } from '../../definition.js'
 
-const events = (component) => {
+export const events = async (component) => {
   if (component.events === undefined) return
 
-  const binding = component.bindings.find((binding) => require(binding).properties.async === true)
+  const binding = await asynchronous(component.bindings)
 
   for (const event of Object.values(component.events)) {
     if (event.binding === undefined) event.binding = binding
+
+    event.conditioned ??= false
+    event.subjective ??= false
   }
 }
 
-exports.events = events
+/** The first binding that carries events, which only its module can say. */
+async function asynchronous(bindings) {
+  for (const binding of bindings) {
+    const { properties } = (await definition(binding)).module
+
+    if (properties.async === true) return binding
+  }
+
+  return undefined
+}

package/src/.component/.normalize/index.js

@@ -1,9 +1,4 @@
-'use strict'
-
-const { events } = require('./events')
-const { operations } = require('./operations')
-const { receivers } = require('./receivers')
-
-exports.events = events
-exports.operations = operations
-exports.receivers = receivers
+export { entity } from './entity.js'
+export { events } from './events.js'
+export { operations } from './operations.js'
+export { receivers } from './receivers.js'

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.scope === 'none')
+    // 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
+}