@toa.io/norm 0.2.1-dev.1

package/features/component.operations.feature

@@ -0,0 +1,54 @@
+Feature: Operations declaration
+
+  Scenario Outline: Operation <channel> entity references
+
+  Operation IO schemas may reference entity's properties using syntax:
+  - `.` - entity's property with the same name
+  - '.foo` - entity's property with `foo` name
+
+    Given I have an entity schema:
+      """
+      foo: string
+      bar: 1
+      """
+    When I declare assignment with:
+      """
+      <channel>:
+        foo: .
+        baz: .bar
+      """
+    Then normalized assignment declaration must contain:
+      """
+      <channel>:
+        type: object
+        properties:
+          foo:
+            type: string
+          baz:
+            type: number
+            default: 1
+      """
+
+    Examples:
+      | channel |
+      | input   |
+      | output  |
+
+  Scenario: Prototype property reference
+
+  Operation IO schemas must be able to reference prototype's entity properties.
+
+    When I declare assignment with:
+      """
+      output:
+        id: .
+      """
+
+    Then normalized assignment declaration must contain:
+      """
+      output:
+        type: object
+        properties:
+          id:
+            $ref: https://schemas.toa.io/0.0.0/definitions#/definitions/id
+      """

package/features/steps/.test/manifest.test.js

@@ -0,0 +1,110 @@
+'use strict'
+
+const { AssertionError } = require('assert')
+const { dump } = require('@toa.io/yaml')
+const { gherkin } = require('@toa.io/mock')
+
+const mock = { gherkin }
+
+jest.mock('@cucumber/cucumber', () => mock.gherkin)
+require('../manifest')
+
+it('should be', () => undefined)
+
+/** @type {toa.norm.features.Context} */
+let context
+
+beforeEach(() => {
+  const manifest = {
+    name: 'test',
+    namespace: 'features',
+    version: '1.0.0',
+    entity: null
+  }
+
+  context = { manifest }
+})
+
+describe('Given I have an entity schema:', () => {
+  const step = gherkin.steps.Gi('I have an entity schema:')
+
+  it('should be', () => undefined)
+
+  it('should set entity schema', () => {
+    const schema = { foo: 'string' }
+    const yaml = dump(schema)
+
+    step.call(context, yaml)
+
+    expect(context.manifest.entity).toStrictEqual({ schema })
+  })
+})
+
+describe('When I declare {operation} with:', () => {
+  const step = gherkin.steps.Wh('I declare {operation} with:')
+
+  it('should be', () => undefined)
+
+  it('should declare operation', () => {
+    const type = 'assignment'
+    const scope = 'changeset'
+    const input = {}
+    const yaml = dump(input)
+
+    step.call(context, type, yaml)
+
+    expect(context.manifest.operations[type]).toStrictEqual({ type, scope })
+  })
+})
+
+describe('Then normalized {operation} declaration must contain:', () => {
+  const step = gherkin.steps.Th('normalized {operation} declaration must contain:')
+
+  it('should be', () => undefined)
+
+  it('should throw if does not contain', async () => {
+    const type = 'assignment'
+
+    context.manifest.operations = {
+      [type]: {
+        type,
+        input: { bar: 'number' },
+        scope: 'changeset'
+      }
+    }
+
+    const input = {
+      type: 'object',
+      properties: {
+        bar: { type: 'string' }
+      }
+    }
+
+    const yaml = dump({ input })
+
+    await expect(step.call(context, type, yaml)).rejects.toThrow(AssertionError)
+  })
+
+  it('should not throw if contain', async () => {
+    const type = 'assignment'
+
+    context.manifest.operations = {
+      [type]: {
+        type,
+        input: { bar: 'number' },
+        scope: 'changeset'
+      }
+    }
+
+    const input = {
+      type: 'object',
+      properties: {
+        bar: { type: 'number' }
+      }
+    }
+
+    const yaml = dump({ input })
+
+    await expect(step.call(context, type, yaml)).resolves.not.toThrow()
+  })
+})

package/features/steps/.types/context.d.ts

@@ -0,0 +1,9 @@
+import { Declaration } from '../../../types/component'
+
+declare namespace toa.norm.features {
+
+  type Context = {
+    manifest?: Declaration
+  }
+
+}

package/features/steps/hooks.js

@@ -0,0 +1,18 @@
+'use strict'
+
+const { Before } = require('@cucumber/cucumber')
+
+Before(
+  /**
+   * @this {toa.norm.features.Context}
+   */
+  function () {
+    this.manifest = {
+      name: 'test',
+      namespace: 'features',
+      version: '1.0.0',
+      entity: {
+        storage: null
+      }
+    }
+  })

package/features/steps/manifest.js

@@ -0,0 +1,66 @@
+'use strict'
+
+const assert = require('node:assert')
+const { join } = require('node:path')
+const { parse, save } = require('@toa.io/yaml')
+const { directory } = require('@toa.io/filesystem')
+const { match } = require('@toa.io/generic')
+
+const { component: load } = require('../../src')
+
+const { Given, When, Then } = require('@cucumber/cucumber')
+
+Given('I have an entity schema:',
+  /**
+   * @param {string} yaml
+   * @this {toa.norm.features.Context}
+   */
+  function (yaml) {
+    const schema = parse(yaml)
+
+    this.manifest.entity = { schema }
+  })
+
+When('I declare {operation} with:',
+  /**
+   * @param {toa.norm.component.operations.Type} type
+   * @param {string} yaml
+   * @this {toa.norm.features.Context}
+   */
+  function (type, yaml) {
+    /** @type {toa.norm.component.Operation} */
+    const declaration = parse(yaml)
+
+    declaration.type = type
+    declaration.scope = scope(type)
+
+    this.manifest.operations = { [type]: declaration }
+  })
+
+Then('normalized {operation} declaration must contain:',
+  /**
+   * @param {toa.norm.component.operations.Type} type
+   * @param {string} yaml
+   * @this {toa.norm.features.Context}
+   */
+  async function (type, yaml) {
+    const temp = await directory.temp()
+    const path = join(temp, 'manifest.toa.yaml')
+
+    await save(this.manifest, path)
+
+    const manifest = await load(temp)
+    const operation = manifest.operations[type]
+    const query = parse(yaml)
+    const contains = match(operation, query)
+
+    assert.equal(contains, true)
+  })
+
+/**
+ * @param {toa.norm.component.operations.Type} type
+ * @returns {toa.norm.component.operations.Scope}
+ */
+const scope = (type) => {
+  return type === 'assignment' ? 'changeset' : 'object'
+}

package/features/steps/parameters.js

@@ -0,0 +1,9 @@
+'use strict'
+
+const { defineParameterType } = require('@cucumber/cucumber')
+
+defineParameterType({
+  name: 'operation',
+  regexp: /transition|observation|assignment/,
+  transformer: (type) => type
+})

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@toa.io/norm",
+  "version": "0.2.1-dev.1",
+  "description": "Toa declarations normalization and validation",
+  "author": "temich <tema.gurtovoy@gmail.com>",
+  "homepage": "https://github.com/toa-io/toa#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/toa-io/toa.git"
+  },
+  "bugs": {
+    "url": "https://github.com/toa-io/toa/issues"
+  },
+  "main": "src/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "echo \"Error: run tests from root\" && exit 1"
+  },
+  "devDependencies": {
+    "@toa.io/mock": "*"
+  },
+  "dependencies": {
+    "@toa.io/core": "*",
+    "@toa.io/generic": "*",
+    "@toa.io/schema": "*",
+    "@toa.io/schemas": "*",
+    "@toa.io/yaml": "*"
+  }
+}

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

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

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

@@ -0,0 +1,14 @@
+'use strict'
+
+const { expand } = require('@toa.io/schemas')
+
+const { resolve } = require('../../shortcuts')
+
+function entity (manifest) {
+  if (manifest.entity === undefined) return
+
+  manifest.entity.schema = expand(manifest.entity.schema)
+  manifest.entity.storage = resolve(manifest.entity.storage)
+}
+
+exports.entity = entity

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

@@ -0,0 +1,14 @@
+'use strict'
+
+const { resolve } = require('../../shortcuts')
+
+function events (manifest) {
+  if (manifest.events === undefined) return
+
+  for (const event of Object.values(manifest.events)) {
+    if (event.binding !== undefined) event.binding = resolve(event.binding)
+    if (event.bridge !== undefined) event.bridge = resolve(event.bridge)
+  }
+}
+
+exports.events = events

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

@@ -0,0 +1,10 @@
+'use strict'
+
+const { recognize } = require('../../shortcuts')
+
+function extensions (manifest) {
+  recognize(manifest, 'extensions')
+  recognize(manifest.extensions)
+}
+
+exports.extensions = extensions

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

@@ -0,0 +1,15 @@
+'use strict'
+
+const { bridge } = require('./bridge')
+const { entity } = require('./entity')
+const { events } = require('./events')
+const { extensions } = require('./extensions')
+const { operations } = require('./operations')
+const { receivers } = require('./receivers')
+
+exports.bridge = bridge
+exports.entity = entity
+exports.events = events
+exports.extensions = extensions
+exports.operations = operations
+exports.receivers = receivers

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

@@ -0,0 +1,17 @@
+'use strict'
+
+const { expand } = require('@toa.io/schemas')
+const { resolve } = require('../../shortcuts')
+
+function operations (manifest) {
+  if (manifest.operations === undefined) return
+
+  for (const operation of Object.values(manifest.operations)) {
+    if (operation.input !== undefined) operation.input = expand(operation.input)
+    if (operation.output !== undefined) operation.output = expand(operation.output)
+    if (operation.bridge !== undefined) operation.bridge = resolve(operation.bridge)
+    if (operation.bindings !== undefined) operation.bindings = operation.bindings.map(resolve)
+  }
+}
+
+exports.operations = operations

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

@@ -0,0 +1,16 @@
+'use strict'
+
+const { resolve } = require('../../shortcuts')
+
+function receivers (manifest) {
+  if (manifest.receivers === undefined) return
+
+  for (const [locator, receiver] of Object.entries(manifest.receivers)) {
+    if (typeof receiver === 'string') manifest.receivers[locator] = { transition: receiver }
+
+    if (receiver.binding !== undefined) receiver.binding = resolve(receiver.binding)
+    if (receiver.bridge !== undefined) receiver.bridge = resolve(receiver.bridge)
+  }
+}
+
+exports.receivers = receivers

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

@@ -0,0 +1,13 @@
+'use strict'
+
+const events = (component) => {
+  if (component.events === undefined) return
+
+  const binding = component.bindings.find((binding) => require(binding).properties.async === true)
+
+  for (const event of Object.values(component.events)) {
+    if (event.binding === undefined) event.binding = binding
+  }
+}
+
+exports.events = events

package/src/.component/.normalize/extensions.js

@@ -0,0 +1,35 @@
+'use strict'
+
+const { directory: { find } } = require('@toa.io/filesystem')
+const { resolve } = require('../../shortcuts')
+
+/**
+ * @param {toa.norm.Component} manifest
+ */
+const extensions = (manifest) => {
+  if (manifest.extensions === undefined) return
+
+  const extensions = manifest.extensions
+
+  for (let [reference, declaration] of Object.entries(extensions)) {
+    let key = resolve(reference)
+
+    // relative path
+    if (key[0] === '.') key = find(key, manifest.path)
+
+    const extension = require(key)
+
+    if (extension.manifest !== undefined) {
+      declaration = extension.manifest(declaration, manifest)
+
+      if (declaration === undefined) throw new Error(`Extension '${reference}' didn't return manifest`)
+    }
+
+    extensions[key] = declaration
+
+    // shortcut was used
+    if (reference !== key) delete extensions[reference]
+  }
+}
+
+exports.extensions = extensions

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

@@ -0,0 +1,9 @@
+'use strict'
+
+const { events } = require('./events')
+const { extensions } = require('./extensions')
+const { operations } = require('./operations')
+
+exports.events = events
+exports.extensions = extensions
+exports.operations = operations

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

@@ -0,0 +1,12 @@
+'use strict'
+
+const operations = (component) => {
+  if (component.operations === undefined) return
+
+  for (const [endpoint, operation] of Object.entries(component.operations)) {
+    if (operation.bindings === undefined) operation.bindings = component.bindings
+    if (operation.virtual === true) delete component.operations[endpoint]
+  }
+}
+
+exports.operations = operations

package/src/.component/collapse.js

@@ -0,0 +1,44 @@
+'use strict'
+
+const { merge } = require('@toa.io/generic')
+
+const collapse = (manifest, prototype) => {
+  delete manifest.prototype
+
+  if (prototype.operations) {
+    manifest.prototype = { prototype: prototype.prototype, path: prototype.path }
+
+    const operations = Object.entries(prototype.operations)
+
+    if (operations.length > 0) {
+      if (manifest.operations === undefined) manifest.operations = {}
+
+      for (let [endpoint, operation] of operations) {
+        if (manifest.operations[endpoint] === undefined) manifest.operations[endpoint] = {}
+        else {
+          const { virtual, ...real } = operation
+
+          operation = real
+        }
+
+        const { bridge, binding, ...declaration } = operation
+
+        merge(manifest.operations[endpoint], declaration)
+
+        if (bridge !== undefined) {
+          if (manifest.prototype.operations === undefined) manifest.prototype.operations = {}
+
+          manifest.prototype.operations[endpoint] = { bridge }
+        }
+      }
+    }
+  }
+
+  delete prototype.entity?.storage
+
+  const { entity, remotes, events } = prototype
+
+  merge(manifest, { entity, remotes, events })
+}
+
+exports.collapse = collapse

package/src/.component/defaults.js

@@ -0,0 +1,25 @@
+'use strict'
+
+// these defaults are required before validation
+const defaults = (manifest) => {
+  if (manifest.prototype === undefined) manifest.prototype = '@toa.io/prototype'
+
+  if (manifest.bindings === undefined) {
+    const local = process.env.TOA_ENV === 'local'
+
+    manifest.bindings = local
+      ? ['@toa.io/bindings.amqp']
+      : ['@toa.io/bindings.http', '@toa.io/bindings.amqp']
+  }
+
+  if (manifest.bridge === undefined) manifest.bridge = '@toa.io/bridges.node'
+
+  if (manifest.entity === null || manifest.entity === undefined) manifest.entity = { storage: null }
+  if (manifest.entity.storage === undefined) manifest.entity.storage = '@toa.io/storages.mongodb'
+  if (manifest.entity.storage === null) manifest.entity.storage = '@toa.io/storages.null'
+
+  // TODO: bridge.version()
+  if (manifest.version === undefined) manifest.version = '0.0.0'
+}
+
+exports.defaults = defaults

package/src/.component/dereference.js

@@ -0,0 +1,72 @@
+'use strict'
+
+const { merge } = require('@toa.io/generic')
+
+const dereference = (manifest) => {
+  // schemas
+  const property = resolve(manifest.entity.schema.properties)
+
+  schema(manifest.entity.schema, property)
+
+  for (const operation of Object.values(manifest.operations)) {
+    if (operation.input !== undefined) operation.input = schema(operation.input, property)
+    if (operation.output !== undefined) operation.output = schema(operation.output, property)
+  }
+
+  // forwarding
+  for (const operation of Object.values(manifest.operations)) {
+    if (operation.forward !== undefined) forward(operation, manifest.operations)
+  }
+
+  for (const operation of Object.values(manifest.operations)) {
+    delete operation.forwarded
+  }
+}
+
+const resolve = (schema) => (property) => {
+  if (schema[property] === undefined) {
+    throw new Error(`Referenced property '${property}' is not defined`)
+  }
+
+  return schema[property]
+}
+
+const schema = (object, resolve) => {
+  if (object === undefined || typeof object !== 'object') return
+  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)
+      else object.properties[name] = schema(value, resolve)
+    }
+  }
+
+  return object
+}
+
+const types = {
+  id: { $ref: 'https://schemas.toa.io/0.0.0/definitions#/definitions/id' }
+}
+
+const forward = (operation, operations) => {
+  const target = operations[operation.forward]
+
+  if (target === undefined) throw new Error(`Referenced operation '${operation.forward}' is not defined`)
+
+  if (target.forward !== undefined) {
+    if (target.forwarded !== true) forward(target, operations)
+
+    operation.forward = target.forward
+  }
+
+  operation.forwarded = true
+
+  const { virtual, ...real } = target
+
+  merge(operation, real)
+}
+
+exports.dereference = dereference

package/src/.component/expand.js

@@ -0,0 +1,14 @@
+'use strict'
+
+const { entity, bridge, operations, events, receivers, extensions } = require('./.expand')
+
+const expand = (manifest) => {
+  entity(manifest)
+  bridge(manifest)
+  operations(manifest)
+  events(manifest)
+  receivers(manifest)
+  extensions(manifest)
+}
+
+exports.expand = expand

package/src/.component/index.js

@@ -0,0 +1,17 @@
+'use strict'
+
+const { collapse } = require('./collapse')
+const { defaults } = require('./defaults')
+const { dereference } = require('./dereference')
+const { expand } = require('./expand')
+const { merge } = require('./merge')
+const { normalize } = require('./normalize')
+const { validate } = require('./validate')
+
+exports.collapse = collapse
+exports.defaults = defaults
+exports.dereference = dereference
+exports.expand = expand
+exports.merge = merge
+exports.normalize = normalize
+exports.validate = validate