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

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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.294](https://github.com/toa-io/toa/compare/v1.0.0-alpha.293...v1.0.0-alpha.294) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/norm
+
+
+
+
+
+# [1.0.0-alpha.293](https://github.com/toa-io/toa/compare/v1.0.0-alpha.292...v1.0.0-alpha.293) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/norm
+
+
+
+
+
 # [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/norm",
-  "version": "1.0.0-alpha.292",
+  "version": "1.0.0-alpha.294",
   "type": "module",
   "description": "Toa declarations normalization and validation",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -21,13 +21,12 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.292",
-    "@toa.io/definitions": "1.0.0-alpha.292",
+    "@toa.io/core": "1.0.0-alpha.293",
+    "@toa.io/definitions": "1.0.0-alpha.294",
     "@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"
+    "@toa.io/schemas": "1.0.0-alpha.293",
+    "fast-glob": "3.3.3"
   },
-  "gitHead": "0f6aa3ad9dbec86bb632a7975ea61d1dde1d8fc5"
+  "gitHead": "50b2b596a46a4d639d9f198f834d70c190f0a3c6"
 }

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

@@ -3,6 +3,5 @@ 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.js

@@ -5,7 +5,6 @@ import {
   events,
   receivers,
   extensions,
-  properties,
   version
 } from './.expand/index.js'
 
@@ -15,7 +14,6 @@ export async function expand(manifest) {
   operations(manifest)
   events(manifest)
   receivers(manifest)
-  properties(manifest)
   extensions(manifest)
 
   await version(manifest)

package/src/.component/schema.yaml

@@ -303,7 +303,4 @@ properties:
   extensions:
     type: object
 
-  properties:
-    type: object
-
 additionalProperties: false

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

@@ -1,6 +1,6 @@
 import { definition } from '../../definition.js'
 
-export const resolve = async (references, annotations = {}) => {
+export const resolve = async (references, annotations = {}, context = {}) => {
   const dependencies = {}
 
   for (const [dependency, components] of Object.entries(references)) {
@@ -19,6 +19,27 @@ export const resolve = async (references, annotations = {}) => {
     if (annotation !== undefined && module.annotation !== undefined) {
       annotations[id] = module.annotation(annotation, instances)
     }
+
+    // what a declaration costs to install, read from the definition rather than from the
+    // package: a deploy installs it, and nothing that declares nothing carries it. A component
+    // is asked for its own instance; a composition that runs the package's service is asked
+    // with none, because what a service brings is not a component's to declare
+    if (module.installs !== undefined) {
+      for (const instance of instances)
+        Object.assign(
+          (instance.component.packages ??= {}),
+          module.installs(instance, annotations[id])
+        )
+
+      const service = module.installs(undefined, annotations[id])
+
+      // mono runs every service in one process, so it takes every service's packages
+      Object.assign((context.packages ??= {}), service)
+
+      for (const composition of context.compositions ?? [])
+        if (composition.services?.includes(dependency) === true)
+          Object.assign((composition.packages ??= {}), service)
+    }
   }
 
   for (const dependency of Object.keys(annotations)) {

package/src/.context/dependencies.js

@@ -5,5 +5,5 @@ export const dependencies = async (context) => {
   const c = connectors(context, components)
   const references = { ...c, ...e }
 
-  return resolve(references, context.annotations)
+  return resolve(references, context.annotations, context)
 }

package/src/index.js

@@ -1,5 +1,6 @@
 export { context } from './context.js'
 export { component } from './component.js'
+export { plain, revive, NORMALIZED } from './manifest.js'
 export { definition } from './definition.js'
 export * as shortcuts from './shortcuts.js'
 export * as entity from './entity.js'

package/src/manifest.js

@@ -0,0 +1,154 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, isAbsolute, join, parse, relative, sep } from 'node:path'
+
+import { Locator } from '@toa.io/core'
+import { find } from '@toa.io/generic'
+
+/**
+ * A normalised manifest, as it is carried in a file beside the component it is of.
+ *
+ * A build normalises every component to tag its image; the process that runs it normalised them
+ * again at start, reading every operation module's source through its bridge to do it. What the
+ * build derived is written instead, and the two cannot disagree: the sources it was read from are
+ * what the image's tag digests, and the version of Toa that read them is in that tag as well.
+ *
+ * What cannot be carried is where things are. A workspace and an image put a component in one
+ * directory and Toa's own packages in another, so every path is written as what it is of rather
+ * than as where it was — the component itself, or the package that holds it — and is resolved
+ * again on the other side, the way norm resolved it.
+ *
+ * A key with no value is not carried: a file has no way to say `undefined`, and nothing reads
+ * one apart from a key that is not there.
+ */
+export function plain(manifest) {
+  const { locator, packages, path, ...rest } = manifest
+
+  // what is carried is written, not the manifest the caller goes on using, and it is written
+  // as a file holds it: a key with no value does not survive and is not meant to
+  const declared = JSON.parse(JSON.stringify(rest))
+
+  walk(declared, (item) => {
+    item.path = carried(item.path, path)
+  })
+
+  local(declared, path)
+
+  return declared
+}
+
+/** What `plain` wrote, read back beside the component it is of. */
+export function revive(declared, path) {
+  const manifest = { ...structuredClone(declared), path }
+
+  walk(manifest, (item) => {
+    item.path = resolved(item.path, path)
+  })
+
+  manifest.locator = new Locator(manifest.name, manifest.namespace)
+
+  return manifest
+}
+
+/**
+ * Everything in a manifest that says where a module of it is: what an inherited one declares is
+ * in the prototype it came from, and what the component declares is in the component.
+ */
+function walk(manifest, rewrite) {
+  for (const property of ROOTED)
+    for (const item of Object.values(manifest[property] ?? {}))
+      if (item.path !== undefined) rewrite(item)
+
+  for (let prototype = manifest.prototype; prototype != null; prototype = prototype.prototype)
+    if (prototype.path !== undefined) rewrite(prototype)
+}
+
+/** Where it is written. A workspace has none: it is a build's output, read by a process. */
+export const NORMALIZED = 'manifest.toa.json'
+
+/** Where norm says a module is, beside what it says about it. */
+const ROOTED = ['events', 'receivers', 'guards']
+
+/** The component's own directory, which is where it is read back. */
+const SELF = '.'
+
+function carried(path, root) {
+  if (path === root) return SELF
+  if (path.startsWith(root + sep)) return SELF + '/' + relative(root, path).split(sep).join('/')
+
+  return specifier(path)
+}
+
+function resolved(path, root) {
+  if (path === SELF) return root
+  if (path.startsWith(SELF + '/')) return join(root, path.slice(2))
+
+  return find(path, root, MANIFEST)
+}
+
+/**
+ * A directory in a package, named the way a manifest would name it, so that it is found again
+ * wherever the package is installed. A prototype that is a directory of the application's own is
+ * refused here rather than in the container: an image carries components and nothing between
+ * them, so nothing would be there to find, whether it is normalised here or there.
+ */
+function specifier(path) {
+  const root = above(path)
+
+  if (root !== undefined) {
+    const { name, private: hidden } = JSON.parse(
+      readFileSync(join(root, 'package.json'), 'utf8')
+    )
+
+    if (name !== undefined && hidden !== true)
+      return [name, ...relative(root, path).split(sep)].filter(Boolean).join('/')
+  }
+
+  throw new Error(
+    `'${path}' is in no package, so an image cannot carry what is in it: ` +
+      'what a component inherits is reached by the reference of the package it is in.'
+  )
+}
+
+/** The directory of the package a path is in. */
+function above(path) {
+  const { root } = parse(path)
+
+  let current = path
+
+  while (current !== root) {
+    if (existsSync(join(current, 'package.json'))) return current
+
+    current = dirname(current)
+  }
+
+  return undefined
+}
+
+/**
+ * Nothing that is carried may say where it was on the machine that read it. What is checked is
+ * what can be told apart from a value of the application's own — an HTTP route is `/accounts`
+ * and is a path to nobody — so: anything inside the component, and any directory a manifest
+ * declares a component or a prototype in. This is what catches a path norm starts writing
+ * somewhere this file does not know about, at the build rather than at the start of a container
+ * that cannot find it.
+ */
+function local(value, root, at = '') {
+  if (typeof value === 'string') {
+    if (value === root || value.startsWith(root + sep) || component(value))
+      throw new Error(`'${at}' carries a path of the machine that read it: ${value}`)
+
+    return
+  }
+
+  if (value === null || typeof value !== 'object') return
+
+  for (const [key, item] of Object.entries(value))
+    local(item, root, at === '' ? key : `${at}.${key}`)
+}
+
+/** Whether a value is a directory a component or a prototype is declared in. */
+function component(value) {
+  return isAbsolute(value) && existsSync(join(value, MANIFEST))
+}
+
+const MANIFEST = 'manifest.toa.yaml'

package/src/shortcuts.js

@@ -41,7 +41,6 @@ export const SHORTCUTS = {
   node: '@toa.io/bridges.node',
   bash: '@toa.io/bridges.bash',
   mongodb: '@toa.io/storages.mongodb',
-  queues: '@toa.io/storages.queues',
   exposition: '@toa.io/extensions.exposition',
   realtime: '@toa.io/extensions.realtime',
   configuration: '@toa.io/extensions.configuration',

package/test/component/expand.test.js

@@ -30,14 +30,3 @@ it('should keep declared version', async () => {
 
   assert.deepStrictEqual(source.version, '1.0.0')
 })
-
-it('should recognize storages.queues', async () => {
-  const queues = { foo: 'bar' }
-
-  source.queues = clone(queues)
-
-  await expand(source)
-
-  assert.strictEqual(source.queues, undefined)
-  assert.partialDeepStrictEqual(source.properties['@toa.io/storages.queues'], queues)
-})

package/test/manifest.test.js

@@ -0,0 +1,126 @@
+import { it, describe } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resolve } from 'node:path'
+
+import { component } from '../src/component.js'
+import { plain, revive } from '../src/manifest.js'
+
+/** the prototype itself: an entity, operations and events, and no prototype of its own */
+const PROTOTYPE = resolve(import.meta.dirname, '../../prototype')
+
+/** a component on the default prototype, with an entity, events and receivers */
+const COMPONENT = resolve(
+  import.meta.dirname,
+  '../../../features/steps/.workspace/components/collection/external.consumer'
+)
+
+/** a component whose prototype is a directory of the workspace's own */
+const EXTENDED = resolve(
+  import.meta.dirname,
+  '../../../features/steps/.workspace/components/collection/configuration.extended'
+)
+
+const carry = (manifest) => JSON.parse(JSON.stringify(plain(manifest)))
+
+describe('a manifest carried through a file', () => {
+  for (const [name, path] of [
+    ['the prototype', PROTOTYPE],
+    ['a component', COMPONENT]
+  ])
+    it(`comes back the same: ${name}`, async () => {
+      const manifest = await component(path)
+
+      assert.deepStrictEqual(revive(carry(manifest), path), manifest)
+    })
+
+  it('does not carry a key with no value', () => {
+    const carried = plain({ name: 'a', namespace: 'b', path: '/x', operations: { echo: { input: undefined } } })
+
+    assert.deepStrictEqual(carried.operations.echo, {})
+  })
+
+  it('leaves the manifest it was given alone', async () => {
+    const manifest = await component(COMPONENT)
+    const before = JSON.stringify(manifest)
+
+    plain(manifest)
+
+    assert.strictEqual(JSON.stringify(manifest), before)
+  })
+
+  it('is read beside the component wherever it is', async () => {
+    const carried = carry(await component(COMPONENT))
+    const revived = revive(carried, '/composition/external-consumer')
+
+    assert.strictEqual(revived.path, '/composition/external-consumer')
+
+    // what the component declares is in the component
+    assert.strictEqual(
+      revived.receivers['something_happened'].path,
+      '/composition/external-consumer'
+    )
+  })
+
+  it('reads what is inherited where the prototype is', async () => {
+    const prototype = (await component(COMPONENT)).prototype.path
+    const revived = revive(carry(await component(COMPONENT)), '/composition/external-consumer')
+
+    // an event of the prototype's is in the prototype, wherever the component is
+    assert.strictEqual(revived.events.created.path, prototype)
+  })
+
+  it('carries what is inherited by the package that holds it', async () => {
+    const carried = carry(await component(COMPONENT))
+
+    assert.strictEqual(carried.prototype.path, '@toa.io/prototype')
+    assert.strictEqual(carried.events.created.path, '@toa.io/prototype')
+    assert.strictEqual(carried.receivers['something_happened'].path, '.')
+  })
+})
+
+describe('what cannot be carried', () => {
+  it('leaves out where the manifest is and what only a deploy reads', async () => {
+    const manifest = await component(PROTOTYPE)
+
+    manifest.packages = { cloudinary: '2.11.0' }
+
+    const carried = plain(manifest)
+
+    assert.ok(!('locator' in carried))
+    assert.ok(!('path' in carried))
+    assert.ok(!('packages' in carried))
+  })
+
+  it('refuses a prototype an image would not have', async () => {
+    const manifest = await component(EXTENDED)
+
+    assert.throws(() => plain(manifest), /is in no package, so an image cannot carry what is in it/)
+  })
+
+  it('refuses a path inside the component it does not know about', () => {
+    assert.throws(
+      () => plain({ name: 'a', namespace: 'b', path: '/x', invented: { at: '/x/y' } }),
+      /carries a path of the machine that read it/
+    )
+  })
+
+  it('refuses a component directory it does not know about', async () => {
+    const manifest = await component(PROTOTYPE)
+
+    manifest.invented = { at: COMPONENT }
+
+    assert.throws(() => plain(manifest), /carries a path of the machine that read it/)
+  })
+
+  it('leaves a value of the application\'s own alone', () => {
+    const carried = plain({
+      name: 'a',
+      namespace: 'b',
+      path: '/x',
+      extensions: { exposition: { routes: [{ path: '/accounts' }] } }
+    })
+
+    assert.strictEqual(carried.extensions.exposition.routes[0].path, '/accounts')
+  })
+})

package/types/component.d.ts

@@ -65,10 +65,11 @@ type Declaration = {
   events?: Events
   receivers?: Record<string, Receiver>
   extensions?: Record<string, object>
-  properties?: Record<string, object>
 }
 
 export type Manifest = Declaration & {
   locator: Locator
   path: string
+  /** what a deploy installs beside this component for what it declares, by package name */
+  packages?: Record<string, string>
 }

package/types/context.d.ts

@@ -23,6 +23,8 @@ interface Composition {
   name: string
   components: Manifest[]
   services?: string[]
+  /** what a deploy installs for the services this composition runs, by package name */
+  packages?: Record<string, string>
 }
 
 export interface Dependency<T = undefined> {
@@ -38,6 +40,8 @@ interface Context extends Declaration {
   compositions?: Composition[]
   components?: Manifest[]
   dependencies?: Record<string, Dependency[]>
+  /** what a deploy installs for every service, which is what `mono` runs */
+  packages?: Record<string, string>
 }
 
 export function context(path: string, environment?: string): Promise<Context>

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

@@ -1,10 +0,0 @@
-import { recognize } from '../../shortcuts.js'
-
-export function properties(manifest) {
-  recognize(SHORTCUTS, manifest, 'properties')
-  recognize(SHORTCUTS, manifest.properties)
-}
-
-const SHORTCUTS = {
-  queues: '@toa.io/storages.queues'
-}