@toa.io/norm 1.0.0-alpha.274 → 1.0.0-alpha.277

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.0.0-alpha.277](https://github.com/toa-io/toa/compare/v1.0.0-alpha.276...v1.0.0-alpha.277) (2026-09-03)
+
+### Bug Fixes
+
+* read a manifest the way js-yaml read one before ([fcea1b2](https://github.com/toa-io/toa/commit/fcea1b21996d6efa6c3198acbfc9f70f1ce0c35c))
+* settle what the module loader made asynchronous ([d4ab9df](https://github.com/toa-io/toa/commit/d4ab9dfb09e382da311dba08f52214e7645f4a6c))
+* what the loader resolves, and what it will not ([1b8a02f](https://github.com/toa-io/toa/commit/1b8a02ff0a5e0f18ee62e3f71bc81116f86f9af1))
+
+
 # [1.0.0-alpha.274](https://github.com/toa-io/toa/compare/v1.0.0-alpha.273...v1.0.0-alpha.274) (2026-09-02)
 
 **Note:** Version bump only for package @toa.io/norm

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@toa.io/norm",
-  "version": "1.0.0-alpha.274",
+  "version": "1.0.0-alpha.277",
+  "type": "module",
   "description": "Toa declarations normalization and validation",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -20,11 +21,11 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.273",
-    "@toa.io/generic": "1.0.0-alpha.273",
-    "@toa.io/schemas": "1.0.0-alpha.274",
-    "fast-glob": "3.2.12",
-    "js-yaml": "4.3.1"
+    "@toa.io/core": "1.0.0-alpha.277",
+    "@toa.io/generic": "1.0.0-alpha.277",
+    "@toa.io/schemas": "1.0.0-alpha.277",
+    "fast-glob": "3.3.3",
+    "js-yaml": "5.4.1"
   },
-  "gitHead": "7df32eb2872155c45681c299036b1efbeefd6518"
+  "gitHead": "0c0071418c2c56a44e621ba5ced5cdd23dff1738"
 }

package/src/.component/.expand/bridge.js

@@ -1,9 +1,5 @@
-'use strict'
+import { resolve } from '../../shortcuts.js'
 
-const { resolve } = require('../../shortcuts')
-
-function bridge (manifest) {
+export function bridge (manifest) {
   manifest.bridge = resolve(manifest.bridge)
 }
-
-exports.bridge = bridge

package/src/.component/.expand/entity.js

@@ -1,11 +1,7 @@
-'use strict'
+import { resolve } from '../../shortcuts.js'
 
-const { resolve } = require('../../shortcuts')
-
-function entity (manifest) {
+export function entity (manifest) {
   if (!('entity' in manifest)) return
 
   manifest.entity.storage = resolve(manifest.entity.storage)
 }
-
-exports.entity = entity

package/src/.component/.expand/events.js

@@ -1,8 +1,6 @@
-'use strict'
+import { resolve } from '../../shortcuts.js'
 
-const { resolve } = require('../../shortcuts')
-
-function events (manifest) {
+export function events (manifest) {
   if (manifest.events === undefined) return
 
   for (const event of Object.values(manifest.events)) {
@@ -10,5 +8,3 @@ function events (manifest) {
     if (event.bridge !== undefined) event.bridge = resolve(event.bridge)
   }
 }
-
-exports.events = events

package/src/.component/.expand/extensions.js

@@ -1,8 +1,6 @@
-'use strict'
+import { recognize } from '../../shortcuts.js'
 
-const { recognize } = require('../../shortcuts')
-
-function extensions (manifest) {
+export function extensions (manifest) {
   recognize(SHORTCUTS, manifest, 'extensions')
   recognize(SHORTCUTS, manifest.extensions)
 }
@@ -16,5 +14,3 @@ const SHORTCUTS = {
   storages: '@toa.io/extensions.storages',
   introspection: '@toa.io/extensions.introspection'
 }
-
-exports.extensions = extensions

package/src/.component/.expand/index.js

@@ -1,19 +1,8 @@
-'use strict'
-
-const { bridge } = require('./bridge')
-const { entity } = require('./entity')
-const { events } = require('./events')
-const { extensions } = require('./extensions')
-const { operations } = require('./operations')
-const { properties } = require('./properties')
-const { receivers } = require('./receivers')
-const { version } = require('./version')
-
-exports.bridge = bridge
-exports.entity = entity
-exports.events = events
-exports.extensions = extensions
-exports.operations = operations
-exports.properties = properties
-exports.receivers = receivers
-exports.version = version
+export { bridge } from './bridge.js'
+export { entity } from './entity.js'
+export { events } from './events.js'
+export { extensions } from './extensions.js'
+export { operations } from './operations.js'
+export { properties } from './properties.js'
+export { receivers } from './receivers.js'
+export { version } from './version.js'

package/src/.component/.expand/operations.js

@@ -1,8 +1,6 @@
-'use strict'
+import { resolve } from '../../shortcuts.js'
 
-const { resolve } = require('../../shortcuts')
-
-function operations (manifest) {
+export function operations (manifest) {
   if (manifest.operations === undefined) return
 
   for (const operation of Object.values(manifest.operations)) {
@@ -13,5 +11,3 @@ function operations (manifest) {
     }
   }
 }
-
-exports.operations = operations

package/src/.component/.expand/properties.js

@@ -1,8 +1,6 @@
-'use strict'
+import { recognize } from '../../shortcuts.js'
 
-const { recognize } = require('../../shortcuts')
-
-function properties (manifest) {
+export function properties (manifest) {
   recognize(SHORTCUTS, manifest, 'properties')
   recognize(SHORTCUTS, manifest.properties)
 }
@@ -10,5 +8,3 @@ function properties (manifest) {
 const SHORTCUTS = {
   queues: '@toa.io/storages.queues'
 }
-
-exports.properties = properties

package/src/.component/.expand/receivers.js

@@ -1,8 +1,6 @@
-'use strict'
+import { resolve } from '../../shortcuts.js'
 
-const { resolve } = require('../../shortcuts')
-
-function receivers (manifest) {
+export function receivers (manifest) {
   if (manifest.receivers === undefined) return
 
   for (const [locator, receiver] of Object.entries(manifest.receivers)) {
@@ -12,5 +10,3 @@ function receivers (manifest) {
     if (receiver.bridge !== undefined) receiver.bridge = resolve(receiver.bridge)
   }
 }
-
-exports.receivers = receivers

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

@@ -1,10 +1,8 @@
-'use strict'
+import { join } from 'node:path'
+import { createHash } from 'node:crypto'
+import fs from 'node:fs/promises'
 
-const { join } = require('node:path')
-const { createHash } = require('node:crypto')
-const fs = require('node:fs/promises')
-
-async function version (manifest) {
+export async function version (manifest) {
   manifest.version ??= await hash(manifest.path)
 }
 
@@ -57,5 +55,3 @@ async function digest (path) {
 }
 
 const EXCLUDED = new Set(['node_modules', '.git'])
-
-exports.version = version

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

@@ -1,13 +1,20 @@
-'use strict'
-
-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
   }
 }
 
-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 import(binding)
+
+    if (properties.async === true) return binding
+  }
+
+  return undefined
+}

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

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

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

@@ -1,6 +1,4 @@
-'use strict'
-
-const operations = (component) => {
+export const operations = (component) => {
   if (component.operations === undefined) return
 
   for (const [endpoint, operation] of Object.entries(component.operations)) {
@@ -12,5 +10,3 @@ const operations = (component) => {
     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
@@ -18,5 +16,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) {
@@ -49,5 +47,3 @@ const collapse = (manifest, prototype) => {
 
   merge(manifest, { entity, events, extensions })
 }
-
-exports.collapse = collapse

package/src/.component/defaults.js

@@ -1,9 +1,7 @@
-'use strict'
-
-const { hash } = require('@toa.io/generic')
+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)
@@ -34,5 +32,3 @@ function nameAfterDir (manifest) {
   manifest.name = name
   manifest.namespace = namespace
 }
-
-exports.defaults = defaults

package/src/.component/dependencies.js

@@ -1,16 +1,19 @@
-'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) => {
+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]
+  const paths = [root, import.meta.dirname]
   const options = { paths }
 
   let path
@@ -25,5 +28,3 @@ function resolve (root, reference) {
 
   return dirname(path)
 }
-
-exports.dependencies = dependencies

package/src/.component/dereference.js

@@ -1,8 +1,6 @@
-'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)
 
@@ -77,5 +75,3 @@ const forward = (operation, operations) => {
 
   merge(operation, real)
 }
-
-exports.dereference = dereference

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,11 +1,9 @@
-'use strict'
-
-const { find } = require('@toa.io/generic')
-const { resolve } = require('../shortcuts')
+import { find } from '@toa.io/generic'
+import { resolve } from '../shortcuts.js'
 
 const cache = {}
 
-const extensions = (manifest) => {
+export const extensions = async (manifest) => {
   manifest.extensions = Object.assign({}, PREDEFINED, manifest.extensions)
 
   const extensions = manifest.extensions
@@ -16,8 +14,9 @@ const extensions = (manifest) => {
     // relative path
     if (key[0] === '.') key = find(key, manifest.path)
 
-    cache[key] ??= require(key)
-    const extension = cache[key]
+    cache[key] ??= import(key)
+
+    const extension = await cache[key]
 
     if (extension.manifest !== undefined) {
       declaration = extension.manifest(declaration, manifest)
@@ -37,5 +36,3 @@ const PREDEFINED = {
   '@toa.io/extensions.fetch': null,
   '@toa.io/extensions.introspection': null
 }
-
-exports.extensions = extensions

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,6 +1,4 @@
-'use strict'
-
-const { merge } = require('@toa.io/generic')
+import { merge } from '@toa.io/generic'
 
 const bridge = async (root, manifest) => {
   await Promise.all([
@@ -20,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 = req(bridge).define
+      const { define } = await req(bridge)
       const definition = await define[singular](root, endpoint)
 
       merge(item, definition)
@@ -58,18 +56,19 @@ const define = async (root, manifest, property) => {
 
 const cache = {}
 
-function req(mod) {
-  cache[mod] ??= require(mod)
+// 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 = req(bridge).define
+  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/validate.js

@@ -1,26 +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 { readFileSync } = require('node:fs')
-const { load: parseYAML } = require('js-yaml')
-const schemas = require('@toa.io/schemas')
-
-const object = parseYAML(readFileSync(path.resolve(__dirname, 'schema.yaml'), 'utf8'))
+const object = yaml.load(readFileSync(path.resolve(import.meta.dirname, 'schema.yaml'), 'utf8'))
 const schema = schemas.schema(object)
 
-const validate = (manifest) => {
+export const validate = async (manifest) => {
   const error = schema.fit(manifest)
 
   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`)
     }
   }
@@ -39,5 +39,3 @@ const receivers = (manifest) => {
 }
 
 const TYPES = new Set(['transition', 'assignment', 'effect', 'unmanaged'])
-
-exports.validate = validate

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,6 +1,7 @@
-'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, context.annotations)
@@ -21,8 +22,6 @@ const extensions = async (context) => {
 }
 
 async function extractExtensionComponents (components, extensions, annotations) {
-  const { component: load } = require('../../component')
-  const { load: loadDependency } = require('./load')
 
   const extracted = []
 
@@ -34,7 +33,7 @@ async function extractExtensionComponents (components, extensions, annotations)
 
       extensions[reference] = []
 
-      const { metadata, module: mod } = loadDependency(reference)
+      const { metadata, module: mod } = await loadDependency(reference)
 
       if (mod.components === undefined) continue
 
@@ -56,5 +55,3 @@ async function extractExtensionComponents (components, extensions, annotations)
 
   return extracted.concat(deeper)
 }
-
-exports.extensions = extensions

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'