@toa.io/norm 1.0.0-alpha.30 → 1.0.0-alpha.300

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,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,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'
-
-const { merge } = require('@toa.io/generic')
+import { merge } from '@toa.io/generic'
+import { definition } from '../definition.js'
 
 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 +19,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 bridged(bridge)
       const definition = await define[singular](root, endpoint)
 
       merge(item, definition)
@@ -29,8 +29,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 +43,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 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
+}
+
+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