@toa.io/norm 1.0.0-alpha.284 → 1.0.0-alpha.287

package/src/.component/merge.js

@@ -28,8 +28,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)
 
@@ -57,7 +56,7 @@ const define = async (root, manifest, property) => {
 const cache = {}
 
 // the promise is what is remembered, so a bridge is loaded once
-function req (mod) {
+function req(mod) {
   cache[mod] ??= import(mod)
 
   return cache[mod]
@@ -66,8 +65,7 @@ function req (mod) {
 const scan = async (bridge, root, property) => {
   const { define } = await req(bridge)
 
-  if (property in define)
-    return define[property](root)
+  if (property in define) return define[property](root)
   else return undefined
 }
 

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,6 +1,14 @@
-import { events, operations, receivers } from './.normalize/index.js'
+import { entity, events, operations, receivers } from './.normalize/index.js'
 
+/**
+ * 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'
+
+  entity(component)
   operations(component)
   await events(component)
   receivers(component)

package/src/.component/schema.yaml

@@ -51,7 +51,6 @@ properties:
   namespace:
     type: string
     pattern: ^[a-zA-Z]([a-zA-Z0-9]{1,31})?$
-    default: "default"
     not:
       oneOf:
         - const: "system"
@@ -72,43 +71,42 @@ properties:
     properties:
       storage:
         type: string
-        default: "@toa.io/storages.mongodb"
-      schema:
-        $ref: https://json-schema.org/draft/2019-09/schema
+      properties:
         type: object
-        properties:
-          type:
-            default: object
-            const: object
-          properties:
-            type: object
-            propertyNames:
-              oneOf:
-                - $ref: "#/definitions/name"
-                - enum: [_version, _created, _updated, _deleted]
-      unique:
+        # a system property is named like any other, so nothing is enumerated beside them
+        propertyNames:
+          $ref: "#/definitions/name"
+        additionalProperties:
+          $ref: https://json-schema.org/draft/2019-09/schema
+      required:
+        type: array
+        uniqueItems: true
+        items:
+          $ref: "#/definitions/name"
+      blank:
+        # what a record holds before anything is written to it; a system property is the
+        # runtime's to write, so none may be named here
         type: object
-        patternProperties:
-          ".*":
-            type: array
-            items:
+        propertyNames:
+          not:
+            enum: [id, VERSION, CREATED, UPDATED, DELETED]
+      migrations:
+        type: array
+        items:
+          type: object
+          properties:
+            id:
               type: string
-      index:
-        type: object
-        patternProperties:
-          ".*":
-            type: object
-            patternProperties:
-              ".*":
-                type: string
-                enum: [asc, desc, hash, text]
+            # what a step means belongs to the storage, which is the only thing that reads it
+            steps:
+              type: array
+          required: [id, steps]
+          additionalProperties: false
       associated:
         type: boolean
-        default: false
       custom:
         type: boolean
-        default: false
-    required: [schema]
+    required: [properties]
     additionalProperties: false
 
   bindings:
@@ -155,7 +153,6 @@ properties:
             $ref: https://json-schema.org/draft/2019-09/schema
           output:
             $ref: https://json-schema.org/draft/2019-09/schema
-            default: {}
           errors:
             # what a reply may carry as a code: the error schema allows either
             type: array
@@ -228,10 +225,8 @@ properties:
               properties:
                 scope:
                   const: none
-                  default: none
                 query:
                   const: false
-                  default: false
           - if: # effect
               properties:
                 type:
@@ -239,7 +234,6 @@ properties:
             then:
               properties:
                 scope:
-                  default: none
                   enum: [object, objects, stream, none]
         additionalProperties: false
     additionalProperties: false
@@ -260,10 +254,8 @@ properties:
             $ref: "#/definitions/binding"
           conditioned:
             type: boolean
-            default: false
           subjective:
             type: boolean
-            default: false
         required: [bridge, path]
         additionalProperties: false
 
@@ -287,10 +279,8 @@ properties:
             type: string
           conditioned:
             type: boolean
-            default: false
           adaptive:
             type: boolean
-            default: false
           arguments:
             type: array
         required: [operation]

package/src/.component/validate.js

@@ -4,7 +4,9 @@ import { readFileSync } from 'node:fs'
 import { yaml } from '@toa.io/generic'
 import * as schemas from '@toa.io/schemas'
 
-const object = yaml.load(readFileSync(path.resolve(import.meta.dirname, 'schema.yaml'), 'utf8'))
+const object = yaml.load(
+  readFileSync(path.resolve(import.meta.dirname, 'schema.yaml'), 'utf8')
+)
 const schema = schemas.schema(object)
 
 export const validate = async (manifest) => {
@@ -12,10 +14,24 @@ export const validate = async (manifest) => {
 
   if (error) throw error
 
+  if (manifest.entity !== undefined) entity(manifest)
   if (manifest.events !== undefined) await events(manifest)
   if (manifest.receivers !== undefined) receivers(manifest)
 }
 
+/** What only the entity's own declaration can answer: whether a name it uses is one it declares. */
+const entity = (manifest) => {
+  const { properties, required, blank } = manifest.entity
+
+  for (const name of required ?? [])
+    if (properties[name] === undefined)
+      throw new Error(`Entity requires property '${name}', which is not defined`)
+
+  for (const name of Object.keys(blank ?? {}))
+    if (properties[name] === undefined)
+      throw new Error(`Entity blank names property '${name}', which is not defined`)
+}
+
 const events = async (manifest) => {
   for (const [label, event] of Object.entries(manifest.events)) {
     const { properties } = await import(event.binding)
@@ -29,11 +45,15 @@ const events = async (manifest) => {
 const receivers = (manifest) => {
   for (const [locator, receiver] of Object.entries(manifest.receivers)) {
     if (manifest.operations?.[receiver.operation] === undefined) {
-      throw new Error(`Receiver '${locator}' refers to undefined operation '${receiver.operation}'`)
+      throw new Error(
+        `Receiver '${locator}' refers to undefined operation '${receiver.operation}'`
+      )
     }
 
     if (!TYPES.has(manifest.operations[receiver.operation].type)) {
-      throw new Error(`Receiver '${locator}' must refer to an operation of the allowed types: ${Array.from(TYPES).join(', ')}`)
+      throw new Error(
+        `Receiver '${locator}' must refer to an operation of the allowed types: ${Array.from(TYPES).join(', ')}`
+      )
     }
   }
 }

package/src/.context/.dependencies/connectors.js

@@ -3,10 +3,10 @@ import { resolve } from 'node:path'
 export const connectors = (context, extracted) => {
   const connectors = {}
 
-  const components = (context.components === undefined
+  const components =
+    (context.components === undefined
       ? extracted
-      : context.components.concat(extracted)
-  ) ?? []
+      : context.components.concat(extracted)) ?? []
 
   for (const component of components) {
     if (component.entity !== undefined) {

package/src/.context/.dependencies/describe.js

@@ -3,4 +3,7 @@
  * @param {Object} manifest
  * @returns {toa.norm.context.dependencies.Instance}
  */
-export const describe = (component, manifest = undefined) => ({ locator: component.locator, manifest })
+export const describe = (component, manifest = undefined) => ({
+  locator: component.locator,
+  manifest
+})

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

@@ -10,7 +10,12 @@ export const extensions = async (context) => {
   const declared = await extractDeclaredServices(context, extensions)
 
   const extracted = declared.concat(
-    await extractExtensionComponents(components.concat(declared), extensions, context.annotations))
+    await extractExtensionComponents(
+      components.concat(declared),
+      extensions,
+      context.annotations
+    )
+  )
 
   components.push(...extracted)
 
@@ -27,7 +32,7 @@ export const extensions = async (context) => {
   return { extensions, components: extracted }
 }
 
-async function extractDeclaredServices (context, extensions) {
+async function extractDeclaredServices(context, extensions) {
   const extracted = []
 
   for (const composition of context.compositions ?? [])
@@ -35,18 +40,20 @@ async function extractDeclaredServices (context, extensions) {
       if (reference in extensions) continue
 
       try {
-        extracted.push(...await extract(reference, extensions, context.annotations))
+        extracted.push(...(await extract(reference, extensions, context.annotations)))
       } catch (e) {
-        throw new Error(`Composition '${composition.name}' lists '${reference}', ` +
-          `which cannot be resolved: ${e.message}`, { cause: e })
+        throw new Error(
+          `Composition '${composition.name}' lists '${reference}', ` +
+            `which cannot be resolved: ${e.message}`,
+          { cause: e }
+        )
       }
     }
 
   return extracted
 }
 
-async function extractExtensionComponents (components, extensions, annotations) {
-
+async function extractExtensionComponents(components, extensions, annotations) {
   const extracted = []
 
   for (const component of components) {
@@ -55,12 +62,11 @@ async function extractExtensionComponents (components, extensions, annotations)
     for (const reference of Object.keys(component.extensions)) {
       if (reference in extensions) continue
 
-      extracted.push(...await extract(reference, extensions, annotations))
+      extracted.push(...(await extract(reference, extensions, annotations)))
     }
   }
 
-  if (extracted.length === 0)
-    return extracted
+  if (extracted.length === 0) return extracted
 
   const deeper = await extractExtensionComponents(extracted, extensions, annotations)
 
@@ -75,7 +81,7 @@ async function extractExtensionComponents (components, extensions, annotations)
  * @param {object} [annotations]
  * @returns {Promise<Array<toa.norm.Component>>}
  */
-async function extract (reference, extensions, annotations) {
+async function extract(reference, extensions, annotations) {
   extensions[reference] = []
 
   const { metadata, module: mod } = await loadDependency(reference)
@@ -86,8 +92,7 @@ async function extract (reference, extensions, annotations) {
   const annotation = annotations?.[metadata?.name ?? reference]
   const extracted = []
 
-  for (const path of mod.components(annotation).paths)
-    extracted.push(await load(path))
+  for (const path of mod.components(annotation).paths) extracted.push(await load(path))
 
   return extracted
 }

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

@@ -11,16 +11,18 @@ const require = createRequire(import.meta.url)
  * @param {string} path
  * @returns {Promise<{ metadata: object, module: object }>}
  */
-export async function load (path) {
+export async function load(path) {
   const metadata = loadMetadata(path)
   const module = await loadModule(path)
 
   return { metadata, module }
 }
 
-function loadMetadata (reference) {
+function loadMetadata(reference) {
   try {
-    return JSON.parse(readFileSync(require.resolve(join(reference, 'package.json')), 'utf8'))
+    return JSON.parse(
+      readFileSync(require.resolve(join(reference, 'package.json')), 'utf8')
+    )
   } catch {
     return null
   }
@@ -30,7 +32,7 @@ function loadMetadata (reference) {
  * @param {string} reference
  * @returns {Promise<object>}
  */
-async function loadModule (reference) {
+async function loadModule(reference) {
   const path = require.resolve(reference)
 
   return await import(pathToFileURL(path).href)

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

@@ -38,7 +38,7 @@ export const resolve = async (references, annotations = {}) => {
  * @param {string} reference
  * @returns {object | null}
  */
-async function optional (reference) {
+async function optional(reference) {
   try {
     return (await load(reference)).module
   } catch {

package/src/.context/dereference.js

@@ -12,7 +12,9 @@ export const dereference = (context) => {
         const component = components[id]
 
         if (component === undefined)
-          throw new Error(`Composition '${composition.name}' lists an unknown component '${id}'.`)
+          throw new Error(
+            `Composition '${composition.name}' lists an unknown component '${id}'.`
+          )
 
         return component
       })

package/src/.context/normalize.js

@@ -12,4 +12,9 @@ export const normalize = (context) => {
   }
 
   if (typeof context.registry === 'string') context.registry = { base: context.registry }
+
+  // what an image is built for, where the Context does not say
+  if (context.registry !== undefined) context.registry.platforms ??= PLATFORMS
 }
+
+const PLATFORMS = ['linux/amd64', 'linux/arm/v7', 'linux/arm64']

package/src/.context/schema.yaml

@@ -40,10 +40,12 @@ properties:
         minItems: 1
         items:
           type: string
-        default:
-          - linux/amd64
-          - linux/arm/v7
-          - linux/arm64
+      services:
+        description: >
+          Where an extension service's image comes from. `build`, which absence means,
+          builds it into `registry.base` the way a composition is built. `published` uses
+          the image the extension ships, which is neither built nor pushed.
+        enum: [build, published]
     # required: [base]
   compositions:
     type: array

package/src/component.js

@@ -5,7 +5,17 @@ import { yaml as jsyaml } from '@toa.io/generic'
 import { find } from '@toa.io/generic'
 import { Locator } from '@toa.io/core'
 
-import { expand, merge, validate, collapse, dereference, defaults, normalize, extensions } from './.component/index.js'
+import {
+  expand,
+  merge,
+  migrations,
+  validate,
+  collapse,
+  dereference,
+  defaults,
+  normalize,
+  extensions
+} from './.component/index.js'
 
 export const component = async (path) => {
   const manifest = await load(path)
@@ -23,7 +33,7 @@ const load = async (path, base, proto = false) => {
   if (base !== undefined) path = find(path, base, MANIFEST)
 
   const file = join(path, MANIFEST)
-  const manifest = await read(file) ?? {}
+  const manifest = (await read(file)) ?? {}
 
   manifest.path = path
 
@@ -31,6 +41,7 @@ const load = async (path, base, proto = false) => {
   await expand(manifest)
 
   await merge(path, manifest)
+  await migrations(path, manifest)
 
   if (manifest.prototype !== null) {
     const prototype = await load(manifest.prototype, path, true)
@@ -46,8 +57,6 @@ const load = async (path, base, proto = false) => {
 
 const MANIFEST = 'manifest.toa.yaml'
 
-
-
 /**
  * Reads a YAML file, resolving anchors into distinct objects so that
  * mutating one node cannot reach another.
@@ -55,7 +64,7 @@ const MANIFEST = 'manifest.toa.yaml'
  * @param {string} path
  * @return {Promise<object>}
  */
-async function read (path) {
+async function read(path) {
   const object = jsyaml.load(await readFile(path, 'utf8'))
 
   return jsyaml.load(jsyaml.dump(object, { noRefs: true, lineWidth: -1 }))

package/src/context.js

@@ -6,7 +6,14 @@ import { yaml as jsyaml } from '@toa.io/generic'
 
 import { component } from './component.js'
 
-import { dependencies, normalize, complete, dereference, expand, validate } from './.context/index.js'
+import {
+  dependencies,
+  normalize,
+  complete,
+  dereference,
+  expand,
+  validate
+} from './.context/index.js'
 
 export const context = async (root, environment = process.env.TOA_ENV) => {
   const path = resolve(root, CONTEXT)
@@ -34,11 +41,8 @@ export const context = async (root, environment = process.env.TOA_ENV) => {
 const CONTEXT = 'context.toa.yaml'
 const COMPONENTS = 'components/*'
 
-
 const GLOB = { onlyDirectories: true, absolute: true }
 
-
-
 /**
  * Reads a YAML file, resolving anchors into distinct objects so that
  * mutating one node cannot reach another.
@@ -46,7 +50,7 @@ const GLOB = { onlyDirectories: true, absolute: true }
  * @param {string} path
  * @return {Promise<object>}
  */
-async function read (path) {
+async function read(path) {
   const object = jsyaml.load(await readFile(path, 'utf8'))
 
   return jsyaml.load(jsyaml.dump(object, { noRefs: true, lineWidth: -1 }))

package/src/entity.js

@@ -0,0 +1,15 @@
+/**
+ * What a component declares about its records is a property map and a list of the properties a
+ * whole one has. A validator wants a schema, so it is assembled here rather than declared: one
+ * that a stored record must fit, and one for a changeset, which is whatever subset of the same
+ * properties an assignment writes.
+ */
+export const schema = (entity) =>
+  entity.required === undefined
+    ? changeset(entity)
+    : { type: 'object', properties: entity.properties, required: entity.required }
+
+export const changeset = (entity) => ({
+  type: 'object',
+  properties: entity.properties
+})

package/src/index.js

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

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',
-  sql: '@toa.io/storages.sql',
   queues: '@toa.io/storages.queues',
   exposition: '@toa.io/extensions.exposition',
   realtime: '@toa.io/extensions.realtime',

package/test/component/collapse.fixtures.js

@@ -3,51 +3,45 @@ import { generate } from 'randomstring'
 const entity = {
   manifest: {
     entity: {
-      schema: {
-        properties: {
-          foo: {
-            type: 'string'
-          },
-          bar: {
-            type: 'integer'
-          }
+      properties: {
+        foo: {
+          type: 'string'
         },
-        required: ['foo']
-      }
+        bar: {
+          type: 'integer'
+        }
+      },
+      required: ['foo']
     }
   },
   prototype: {
     entity: {
-      schema: {
-        properties: {
-          foo: {
-            default: 'ok'
-          },
-          baz: {
-            type: 'boolean'
-          }
+      properties: {
+        foo: {
+          minLength: 1
         },
-        required: ['baz']
-      }
+        baz: {
+          type: 'boolean'
+        }
+      },
+      required: ['baz']
     }
   },
   result: {
     entity: {
-      schema: {
-        properties: {
-          foo: {
-            type: 'string',
-            default: 'ok'
-          },
-          bar: {
-            type: 'integer'
-          },
-          baz: {
-            type: 'boolean'
-          }
+      properties: {
+        foo: {
+          type: 'string',
+          minLength: 1
         },
-        required: ['foo', 'baz']
-      }
+        bar: {
+          type: 'integer'
+        },
+        baz: {
+          type: 'boolean'
+        }
+      },
+      required: ['foo', 'baz']
     }
   }
 }