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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/norm",
-  "version": "1.0.0-alpha.284",
+  "version": "1.0.0-alpha.286",
   "type": "module",
   "description": "Toa declarations normalization and validation",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -21,11 +21,11 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.284",
-    "@toa.io/generic": "1.0.0-alpha.283",
-    "@toa.io/schemas": "1.0.0-alpha.283",
+    "@toa.io/core": "1.0.0-alpha.286",
+    "@toa.io/generic": "1.0.0-alpha.286",
+    "@toa.io/schemas": "1.0.0-alpha.286",
     "fast-glob": "3.3.3",
     "js-yaml": "5.4.1"
   },
-  "gitHead": "006755556879e91e8d68fa86753aa3b475bdf4bf"
+  "gitHead": "81f3d0688f17668b902be336d1749cc715edcdb6"
 }

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

@@ -1,5 +1,5 @@
 import { resolve } from '../../shortcuts.js'
 
-export function bridge (manifest) {
+export function bridge(manifest) {
   manifest.bridge = resolve(manifest.bridge)
 }

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

@@ -1,6 +1,6 @@
 import { resolve } from '../../shortcuts.js'
 
-export function entity (manifest) {
+export function entity(manifest) {
   if (!('entity' in manifest)) return
 
   manifest.entity.storage = resolve(manifest.entity.storage)

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

@@ -1,6 +1,6 @@
 import { resolve } from '../../shortcuts.js'
 
-export function events (manifest) {
+export function events(manifest) {
   if (manifest.events === undefined) return
 
   for (const event of Object.values(manifest.events)) {

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

@@ -1,6 +1,6 @@
 import { recognize } from '../../shortcuts.js'
 
-export function extensions (manifest) {
+export function extensions(manifest) {
   recognize(SHORTCUTS, manifest, 'extensions')
   recognize(SHORTCUTS, manifest.extensions)
 }

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

@@ -1,6 +1,6 @@
 import { resolve } from '../../shortcuts.js'
 
-export function operations (manifest) {
+export function operations(manifest) {
   if (manifest.operations === undefined) return
 
   for (const operation of Object.values(manifest.operations)) {

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

@@ -1,6 +1,6 @@
 import { recognize } from '../../shortcuts.js'
 
-export function properties (manifest) {
+export function properties(manifest) {
   recognize(SHORTCUTS, manifest, 'properties')
   recognize(SHORTCUTS, manifest.properties)
 }

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

@@ -1,10 +1,11 @@
 import { resolve } from '../../shortcuts.js'
 
-export function receivers (manifest) {
+export function receivers(manifest) {
   if (manifest.receivers === undefined) return
 
   for (const [locator, receiver] of Object.entries(manifest.receivers)) {
-    if (typeof receiver === 'string') manifest.receivers[locator] = { operation: receiver }
+    if (typeof receiver === 'string')
+      manifest.receivers[locator] = { operation: receiver }
 
     if (receiver.binding !== undefined) receiver.binding = resolve(receiver.binding)
     if (receiver.bridge !== undefined) receiver.bridge = resolve(receiver.bridge)

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

@@ -2,7 +2,7 @@ import { join } from 'node:path'
 import { createHash } from 'node:crypto'
 import fs from 'node:fs/promises'
 
-export async function version (manifest) {
+export async function version(manifest) {
   manifest.version ??= await hash(manifest.path)
 }
 
@@ -14,14 +14,13 @@ export async function version (manifest) {
  * build writes (see `operations/src/deployment/images/image.js`), so hashing it would only
  * retag an identical image after a local install.
  */
-async function hash (path) {
+async function hash(path) {
   const files = (await list(path)).sort()
   const digests = await Promise.all(files.map((file) => digest(join(path, file))))
   const total = createHash('sha256')
 
   // the path is part of it: moving a file changes the build even if no content did
-  for (let i = 0; i < files.length; i++)
-    total.update(files[i]).update(digests[i])
+  for (let i = 0; i < files.length; i++) total.update(files[i]).update(digests[i])
 
   return total.digest('hex').slice(0, 8)
 }
@@ -32,26 +31,25 @@ async function hash (path) {
  * @param {string[]} [acc]
  * @returns {Promise<string[]>} paths relative to `root`
  */
-async function list (root, path = '', acc = []) {
+async function list(root, path = '', acc = []) {
   const entries = await fs.readdir(join(root, path), { withFileTypes: true })
 
   for (const entry of entries) {
-    if (EXCLUDED.has(entry.name))
-      continue
+    if (EXCLUDED.has(entry.name)) continue
 
     const relative = path === '' ? entry.name : `${path}/${entry.name}`
 
-    if (entry.isDirectory())
-      await list(root, relative, acc)
-    else if (entry.isFile())
-      acc.push(relative)
+    if (entry.isDirectory()) await list(root, relative, acc)
+    else if (entry.isFile()) acc.push(relative)
   }
 
   return acc
 }
 
-async function digest (path) {
-  return createHash('sha256').update(await fs.readFile(path)).digest()
+async function digest(path) {
+  return createHash('sha256')
+    .update(await fs.readFile(path))
+    .digest()
 }
 
 const EXCLUDED = new Set(['node_modules', '.git'])

package/src/.component/.normalize/entity.js

@@ -0,0 +1,7 @@
+export function entity(component) {
+  if (component.entity === undefined) return
+
+  component.entity.storage ??= '@toa.io/storages.mongodb'
+  component.entity.associated ??= false
+  component.entity.custom ??= false
+}

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

@@ -5,11 +5,14 @@ export const events = async (component) => {
 
   for (const event of Object.values(component.events)) {
     if (event.binding === undefined) event.binding = binding
+
+    event.conditioned ??= false
+    event.subjective ??= false
   }
 }
 
 /** The first binding that carries events, which only its module can say. */
-async function asynchronous (bindings) {
+async function asynchronous(bindings) {
   for (const binding of bindings) {
     const { properties } = await import(binding)
 

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

@@ -1,3 +1,4 @@
+export { entity } from './entity.js'
 export { events } from './events.js'
 export { operations } from './operations.js'
 export { receivers } from './receivers.js'

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

@@ -2,8 +2,16 @@ export const operations = (component) => {
   if (component.operations === undefined) return
 
   for (const [endpoint, operation] of Object.entries(component.operations)) {
-    if (operation.scope === 'none')
+    // what an operation of this type acquires, where it did not say
+    if (operation.type === 'computation' || operation.type === 'unmanaged') {
+      operation.scope = 'none'
       operation.query = false
+    } else if (operation.type === 'effect') operation.scope ??= 'none'
+
+    if (operation.scope === 'none') operation.query = false
+
+    // an operation that states no output states an empty schema, which every reply fits
+    operation.output ??= {}
 
     if (operation.bindings === undefined) operation.bindings = component.bindings
     if (operation.bindings === null) operation.bindings = []

package/src/.component/.normalize/receivers.js

@@ -1,4 +1,4 @@
-export function receivers (component) {
+export function receivers(component) {
   if (component.receivers === undefined) return
 
   const receivers = component.receivers
@@ -7,6 +7,9 @@ export function receivers (component) {
     const segments = key.split('.')
     const source = value.source ?? 'default'
 
+    value.conditioned ??= false
+    value.adaptive ??= false
+
     if (source !== 'default') continue
     if (segments.length === 3) continue // already with a namespace
 

package/src/.component/collapse.js

@@ -12,7 +12,8 @@ export const collapse = (manifest, prototype) => {
       if (manifest.operations === undefined) manifest.operations = {}
 
       for (let [endpoint, operation] of operations) {
-        if (manifest.operations[endpoint] === undefined) manifest.operations[endpoint] = {}
+        if (manifest.operations[endpoint] === undefined)
+          manifest.operations[endpoint] = {}
         else {
           const { virtual, ...real } = operation
 
@@ -24,7 +25,8 @@ export const collapse = (manifest, prototype) => {
         merge(manifest.operations[endpoint], declaration)
 
         if (bridge !== undefined) {
-          if (manifest.prototype.operations === undefined) manifest.prototype.operations = {}
+          if (manifest.prototype.operations === undefined)
+            manifest.prototype.operations = {}
 
           manifest.prototype.operations[endpoint] = { bridge }
         }
@@ -34,16 +36,22 @@ export const collapse = (manifest, prototype) => {
 
   const { entity, events, extensions } = prototype
 
-  if (manifest.entity?.schema?.properties.id !== undefined && entity?.schema?.properties.id !== undefined) {
+  if (
+    manifest.entity?.properties?.id !== undefined &&
+    entity?.properties?.id !== undefined
+  ) {
     manifest.entity.custom = true
 
-    delete prototype.entity.schema.properties.id
+    delete prototype.entity.properties.id
   }
 
   if (prototype.events !== undefined && manifest.events !== undefined)
     for (const event of Object.keys(prototype.events))
-      if (event in manifest.events)
-        delete prototype.events[event]
+      if (event in manifest.events) delete prototype.events[event]
+
+  // a migration is applied to a collection, and a prototype has none: what it declares belongs
+  // to the component that declared it, so it is not collapsed into this one
+  if (entity?.migrations !== undefined) delete entity.migrations
 
   merge(manifest, { entity, events, extensions })
 }

package/src/.component/defaults.js

@@ -13,18 +13,17 @@ export const defaults = (manifest, proto) => {
     if (manifest.entity.storage === null)
       manifest.entity.storage = '@toa.io/storages.null'
   } else {
-    if (manifest.prototype === undefined)
-      manifest.prototype = null
+    if (manifest.prototype === undefined) manifest.prototype = null
   }
 
   if (manifest.prototype === undefined) manifest.prototype = '@toa.io/prototype'
 }
 
-function protoName (manifest) {
+function protoName(manifest) {
   return 'proto' + hash(manifest.path)
 }
 
-function nameAfterDir (manifest) {
+function nameAfterDir(manifest) {
   const parts = manifest.path.split('/')
   const dirname = parts[parts.length - 1]
   const [name, namespace] = dirname.split('.').reverse()

package/src/.component/dependencies.js

@@ -9,20 +9,23 @@ const require = createRequire(import.meta.url)
  * @param {toa.norm.Component} component
  */
 export const dependencies = (component) => {
-  if ('entity' in component) component.entity.storage = resolve(component.path, component.entity.storage)
+  if ('entity' in component)
+    component.entity.storage = resolve(component.path, component.entity.storage)
 }
 
-function resolve (root, reference) {
+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)
   }
 

package/src/.component/dereference.js

@@ -2,14 +2,14 @@ import { merge } from '@toa.io/generic'
 
 export const dereference = (manifest) => {
   // schemas
-  const resolver = createResolver(manifest.entity?.schema?.properties)
+  const properties = manifest.entity?.properties
+  const resolver = createResolver(properties)
 
-  if (manifest.entity !== undefined)
-    schema(manifest.entity.schema, resolver)
-
-  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) => {
@@ -20,15 +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)
       if (Array.isArray(operation.output) && operation.output.length === 1)
         operation.output = [schema(operation.output[0], resolver)]
-      else
-        operation.output = schema(operation.output, resolver)
+      else operation.output = schema(operation.output, resolver)
   }
 
   // forwarding
@@ -39,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)
     }
   }
@@ -61,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)

package/src/.component/expand.js

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

package/src/.component/extensions.js

@@ -21,7 +21,8 @@ export const extensions = async (manifest) => {
     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

package/src/.component/index.js

@@ -4,6 +4,7 @@ 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

@@ -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]