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

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 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.292](https://github.com/toa-io/toa/compare/v1.0.0-alpha.291...v1.0.0-alpha.292) (2026-09-07)
+
+### Features
+
+* **cli:** the deployment library is a peer, and the binary is the CLI's ([a923f81](https://github.com/toa-io/toa/commit/a923f8173a55ed1c091213a7c7db1863ca1d0ba6))
+* **definitions:** the version of Toa is the definitions package's ([3d0272e](https://github.com/toa-io/toa/commit/3d0272ea0ab862f4b6c2e58a2f003f92d0f8a87f))
+* **definitions:** what a package declares is read from one package ([7052341](https://github.com/toa-io/toa/commit/70523411b5d9e2b204c999aa02365173f3bb518d))
+* **norm:** a package's definition is read by one resolver ([bffd41c](https://github.com/toa-io/toa/commit/bffd41c8d18c42786b0bf321623088b9dabc4724))
+
+
 # [1.0.0-alpha.291](https://github.com/toa-io/toa/compare/v1.0.0-alpha.290...v1.0.0-alpha.291) (2026-09-07)
 
 **Note:** Version bump only for package @toa.io/norm

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/norm",
-  "version": "1.0.0-alpha.291",
+  "version": "1.0.0-alpha.292",
   "type": "module",
   "description": "Toa declarations normalization and validation",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -21,11 +21,13 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.291",
-    "@toa.io/generic": "1.0.0-alpha.291",
-    "@toa.io/schemas": "1.0.0-alpha.291",
+    "@toa.io/core": "1.0.0-alpha.292",
+    "@toa.io/definitions": "1.0.0-alpha.292",
+    "@toa.io/generic": "1.0.0-alpha.292",
+    "@toa.io/prototype": "1.0.0-alpha.289",
+    "@toa.io/schemas": "1.0.0-alpha.292",
     "fast-glob": "3.3.3",
     "js-yaml": "5.4.1"
   },
-  "gitHead": "bcd8d8d07bd3e64fc826af8719472404662cc37f"
+  "gitHead": "0f6aa3ad9dbec86bb632a7975ea61d1dde1d8fc5"
 }

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

@@ -1,3 +1,5 @@
+import { definition } from '../../definition.js'
+
 export const events = async (component) => {
   if (component.events === undefined) return
 
@@ -14,7 +16,7 @@ export const events = async (component) => {
 /** 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)
+    const { properties } = (await definition(binding)).module
 
     if (properties.async === true) return binding
   }

package/src/.component/extensions.js

@@ -1,7 +1,6 @@
 import { find } from '@toa.io/generic'
 import { resolve } from '../shortcuts.js'
-
-const cache = {}
+import { definition } from '../definition.js'
 
 export const extensions = async (manifest) => {
   manifest.extensions = Object.assign({}, PREDEFINED, manifest.extensions)
@@ -14,9 +13,7 @@ export const extensions = async (manifest) => {
     // relative path
     if (key[0] === '.') key = find(key, manifest.path)
 
-    cache[key] ??= import(key)
-
-    const extension = await cache[key]
+    const { module: extension } = await definition(key)
 
     if (extension.manifest !== undefined) {
       declaration = extension.manifest(declaration, manifest)

package/src/.component/merge.js

@@ -1,4 +1,5 @@
 import { merge } from '@toa.io/generic'
+import { definition } from '../definition.js'
 
 const bridge = async (root, manifest) => {
   await Promise.all([
@@ -18,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 } = await req(bridge)
+      const { define } = await bridged(bridge)
       const definition = await define[singular](root, endpoint)
 
       merge(item, definition)
@@ -53,20 +54,20 @@ const define = async (root, manifest, property) => {
   }
 }
 
-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 } = await req(bridge)
+  const { define } = await bridged(bridge)
 
   if (property in define) return define[property](root)
   else return undefined
 }
 
+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/validate.js

@@ -3,6 +3,7 @@ import path from 'node:path'
 import { readFileSync } from 'node:fs'
 import { yaml } from '@toa.io/generic'
 import * as schemas from '@toa.io/schemas'
+import { definition } from '../definition.js'
 
 const object = yaml.load(
   readFileSync(path.resolve(import.meta.dirname, 'schema.yaml'), 'utf8')
@@ -34,7 +35,7 @@ const entity = (manifest) => {
 
 const events = async (manifest) => {
   for (const [label, event] of Object.entries(manifest.events)) {
-    const { properties } = await import(event.binding)
+    const { properties } = (await definition(event.binding)).module
 
     if (properties.async !== true) {
       throw new Error(`Event '${label}' binding '${event.binding}' is not async`)

package/src/.context/.dependencies/extensions.js

@@ -1,5 +1,6 @@
+import { Locator } from '@toa.io/core'
 import { component as load } from '../../component.js'
-import { load as loadDependency } from './load.js'
+import { definition } from '../../definition.js'
 
 export const extensions = async (context) => {
   const extensions = {}
@@ -84,15 +85,28 @@ async function extractExtensionComponents(components, extensions, annotations) {
 async function extract(reference, extensions, annotations) {
   extensions[reference] = []
 
-  const { metadata, module: mod } = await loadDependency(reference)
+  const { name, module: mod } = await definition(reference)
 
   if (mod.components === undefined) return []
 
   // the annotation decides whether an extension contributes components at all
-  const annotation = annotations?.[metadata?.name ?? reference]
+  const annotation = annotations?.[name]
+  const { manifests, paths } = mod.components(annotation)
+
+  // a definition carries the manifests, read where the extension is not installed;
+  // an entry names the directories, where it is
+  if (manifests !== undefined) return manifests.map(revive)
+
   const extracted = []
 
-  for (const path of mod.components(annotation).paths) extracted.push(await load(path))
+  for (const path of paths) extracted.push(await load(path))
 
   return extracted
 }
+
+/** A manifest as a digest carries it, which is one norm read, without the locator. */
+function revive(manifest) {
+  manifest.locator = new Locator(manifest.name, manifest.namespace)
+
+  return manifest
+}

package/src/.context/.dependencies/resolve.js

@@ -1,11 +1,10 @@
-import { load } from './load.js'
+import { definition } from '../../definition.js'
 
 export const resolve = async (references, annotations = {}) => {
   const dependencies = {}
 
   for (const [dependency, components] of Object.entries(references)) {
-    const { metadata, module } = await load(dependency)
-    const id = metadata.name
+    const { name: id, module } = await definition(dependency)
 
     const instances = components.map((component) => ({
       locator: component.locator,
@@ -40,7 +39,7 @@ export const resolve = async (references, annotations = {}) => {
  */
 async function optional(reference) {
   try {
-    return (await load(reference)).module
+    return (await definition(reference)).module
   } catch {
     return null
   }

package/src/.context/normalize.js

@@ -1,14 +1,14 @@
-import * as runtime from '@toa.io/runtime'
+import * as definitions from '@toa.io/definitions'
 
 /**
  * @param {toa.norm.context.Declaration | Object} context
  */
 export const normalize = (context) => {
-  if (context.runtime === undefined) context.runtime = { version: runtime.version }
+  if (context.runtime === undefined) context.runtime = { version: definitions.version }
   if (typeof context.runtime === 'string') context.runtime = { version: context.runtime }
 
   if (context.runtime.version === undefined || context.runtime.version === '.') {
-    context.runtime.version = runtime.version
+    context.runtime.version = definitions.version
   }
 
   if (typeof context.registry === 'string') context.registry = { base: context.registry }

package/src/definition.js

@@ -0,0 +1,56 @@
+import { createRequire } from 'node:module'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import * as definitions from '@toa.io/definitions'
+
+// import.meta.resolve takes no paths, and a dependency is named rather than
+// written as a path
+const require = createRequire(import.meta.url)
+
+/**
+ * What a package declares, read without running it.
+ *
+ * A first-party package's definition is in `@toa.io/definitions`. Another package's is
+ * its `definition.js`, or its entry where it ships none — so an extension that exports
+ * its `manifest` and `deployment` beside its `Factory` is read as it always was.
+ *
+ * @param {string} reference a package name, or a directory
+ * @returns {Promise<toa.norm.Definition>}
+ */
+export function definition(reference) {
+  cache[reference] ??= load(reference)
+
+  return cache[reference]
+}
+
+const cache = {}
+
+async function load(reference) {
+  const known = await definitions.definition(reference)
+
+  if (known !== undefined) return { name: reference, module: known }
+
+  const name = metadata(reference)?.name ?? reference
+  const module = await import(pathToFileURL(resolve(reference)).href)
+
+  return { name, module }
+}
+
+function resolve(reference) {
+  try {
+    return require.resolve(join(reference, 'definition.js'))
+  } catch {
+    return require.resolve(reference)
+  }
+}
+
+function metadata(reference) {
+  try {
+    return JSON.parse(
+      readFileSync(require.resolve(join(reference, 'package.json')), 'utf8')
+    )
+  } catch {
+    return null
+  }
+}

package/src/index.js

@@ -1,4 +1,5 @@
 export { context } from './context.js'
 export { component } from './component.js'
+export { definition } from './definition.js'
 export * as shortcuts from './shortcuts.js'
 export * as entity from './entity.js'

package/test/context/normalize.test.js

@@ -1,4 +1,4 @@
-import * as runtime from '@toa.io/runtime'
+import * as definitions from '@toa.io/definitions'
 import { it, beforeEach } from 'node:test'
 import assert from 'node:assert/strict'
 
@@ -20,7 +20,7 @@ it('should resolve local version', () => {
   normalize(context)
 
   assert.notDeepStrictEqual(context.runtime, '.')
-  assert.deepStrictEqual(context.runtime.version, runtime.version)
+  assert.deepStrictEqual(context.runtime.version, definitions.version)
 })
 
 it('should expand registry', () => {

package/test/definition.test.js

@@ -0,0 +1,35 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+import { join } from 'node:path'
+
+import { definition } from '../src/definition.js'
+
+it('reads a definition.js where a package ships one', async () => {
+  const { name, module } = await definition(join(import.meta.dirname, 'dummies/defined'))
+
+  assert.equal(name, 'dummies.defined')
+  assert.equal(module.declares, true)
+  assert.equal(module.runs, undefined)
+})
+
+it('reads the entry where a package ships no definition.js', async () => {
+  const path = join(import.meta.dirname, '../')
+  const { name, module } = await definition(path)
+
+  assert.equal(name, '@toa.io/norm')
+  assert.ok(module.context instanceof Function)
+})
+
+it('names a directory without package.json by its reference', async () => {
+  const path = join(import.meta.dirname, 'dummies/bare')
+  const { name, module } = await definition(path)
+
+  assert.equal(name, path)
+  assert.equal(module.declares, true)
+})
+
+it('loads a definition once', async () => {
+  const path = join(import.meta.dirname, 'dummies/bare')
+
+  assert.equal(await definition(path), await definition(path))
+})

package/test/dummies/bare/index.js

@@ -0,0 +1 @@
+export const declares = true

package/test/dummies/defined/definition.js

@@ -0,0 +1 @@
+export const declares = true

package/test/dummies/defined/index.js

@@ -0,0 +1 @@
+export const runs = true

package/test/dummies/defined/package.json

@@ -0,0 +1 @@
+{ "name": "dummies.defined", "type": "module", "main": "index.js" }

package/types/index.d.ts

@@ -3,3 +3,11 @@ export * as component from './component.js'
 
 export { Manifest } from './component.js'
 export * as entity from './entity.js'
+
+export interface Definition {
+  /** The package's name, or the reference where it has no package.json */
+  name: string
+  module: Record<string, any>
+}
+
+export function definition(reference: string): Promise<Definition>

package/src/.context/.dependencies/load.js

@@ -1,39 +0,0 @@
-import { createRequire } from 'node:module'
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-// import.meta.resolve takes no paths, and a dependency is named rather than
-// written as a path
-const require = createRequire(import.meta.url)
-
-/**
- * @param {string} path
- * @returns {Promise<{ metadata: object, module: object }>}
- */
-export async function load(path) {
-  const metadata = loadMetadata(path)
-  const module = await loadModule(path)
-
-  return { metadata, module }
-}
-
-function loadMetadata(reference) {
-  try {
-    return JSON.parse(
-      readFileSync(require.resolve(join(reference, 'package.json')), 'utf8')
-    )
-  } catch {
-    return null
-  }
-}
-
-/**
- * @param {string} reference
- * @returns {Promise<object>}
- */
-async function loadModule(reference) {
-  const path = require.resolve(reference)
-
-  return await import(pathToFileURL(path).href)
-}

package/test/context/dependencies.load.test.js

@@ -1,25 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { join } from 'node:path'
-import { load } from '../../src/.context/.dependencies/load.js'
-
-it('should be', async () => {
-  assert.ok(load instanceof Function)
-})
-
-it('should load module', async () => {
-  const path = join(import.meta.dirname, '../../')
-  const { metadata, module } = await load(path)
-
-  assert.deepStrictEqual(metadata.name, '@toa.io/norm')
-  assert.ok(module.context instanceof Function)
-})
-
-it('should return null metadata if no package.json', async () => {
-  const path = join(import.meta.dirname, '../../src')
-  const { metadata, module } = await load(path)
-
-  assert.strictEqual(metadata, null)
-  assert.ok(module.context instanceof Function)
-})