@toa.io/bridges.node 0.2.0-dev.0 → 0.2.1-dev.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/bridges.node",
-  "version": "0.2.0-dev.0",
+  "version": "0.2.1-dev.3",
   "description": "Toa Node Bridge (inproc)",
   "homepage": "https://toa.io",
   "author": {
@@ -26,11 +26,13 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@babel/parser": "7.16.2",
+    "@toa.io/core": "*",
+    "@toa.io/filesystem": "*",
+    "@toa.io/generic": "*",
     "fast-glob": "3.2.7"
   },
   "devDependencies": {
     "clone-deep": "4.0.1"
   },
-  "gitHead": "bee1e46d597d4f8a897fb8446bbeb5861b307d64"
+  "gitHead": "2be07592325b2e4dc823e81d882a4e50bf50de24"
 }

package/readme.md

@@ -0,0 +1,103 @@
+# Node.js Bridge
+
+> Currently, Node.js bridge only
+> supports [CommonJS modules](https://nodejs.org/api/modules.html#modules-commonjs-modules).
+
+## Algorithm Definition
+
+Operation's algorithms are defined as CommonJS modules in under `operations` directory in the
+component root. Algorithm module must export a function which is Algorithm Function, Class or
+Factory. Module file name without extension is an operation name (endpoint).
+
+### Function
+
+```javascript
+// operations/create.js
+
+function transition (input, object, context) {
+  // ...
+
+  return { output: { foo: 'bar' } }
+}
+
+exports.transition = transition
+```
+
+Exported function's name defines operation `type` property, thus must be one of:
+`transition`, `observation`, or `assignment`. Second (state) argument name must be `object`,
+`objects`, or `changeset` as it defines operation's `scope`.
+
+Following function signature defines operation of `observation` type with `objects` scope.
+
+```javascript
+// operations/set.js
+
+function observation (input, objects) {
+  // ...
+}
+```
+
+See [Operation properties](#).
+
+### Class
+
+```javascript
+// operations/transit.js
+
+class Transition {
+  constructor (context) {}
+
+  execute (input, object) {
+    // ...
+
+    return { output: { foo: 'bar' } }
+  }
+}
+
+exports.Transition = Transition
+```
+
+Exported class name must be one of: `Transition`, `Observation`, or `Assignment`, as it defines
+operation's `type`. Class must implement [Algorithm interface](./types/operations.d.ts).
+Second (state) argument name of the `execute` method must be `object`, `objects`, or `changeset` as
+it defines operation's `scope`.
+
+### Factory
+
+```javascript
+class ObjectTransitionFactory {
+  constructor (context) {}
+
+  create () {
+    // ...
+  }
+}
+
+exports.ObjectTransitionFactory = ObjectTransitionFactory
+```
+
+Exported class name must follow the pattern: `{Subject}{Type}Factory`, where `Subject` and `Type`
+defines operation's `scope` and `type` respectively. Class must
+implement [Algorithm Factory interface](#).
+
+> Factory class name examples: `ObjectTransitionFactory`, `ObjectsObservationFactory`,
+> `ChangesetAssignmentFactory`.
+
+### Return value
+
+Algorithm's return value must match [UCP Response](#), that is, to be an object with either `output`
+or `error` properties. If return value is a primitive or an object without neither `output`
+nor `error` properties, then it is considered as the value of `output`.
+
+Next two return values are equivalent.
+
+```javascript
+return { ok: 1 }
+
+return { output: { ok: 1 } } 
+```
+
+### Storing Context
+
+> Algorithm definition should store reference to the `context` object without copying its value
+> type variables as they may change over time.

package/src/algorithms/class.js

@@ -0,0 +1,6 @@
+'use strict'
+
+/** @type {toa.node.define.algorithms.Constructor} */
+const create = (Class, context) => new Class(context)
+
+exports.create = create

package/src/algorithms/factory.js

@@ -0,0 +1,10 @@
+'use strict'
+
+/** @type {toa.node.define.algorithms.Constructor} */
+const create = (Factory, context) => {
+  const factory = new Factory(context)
+
+  return factory.create()
+}
+
+exports.create = create

package/src/algorithms/function.js

@@ -0,0 +1,10 @@
+'use strict'
+
+/** @type {toa.node.define.algorithms.Constructor} */
+const create = (func, context) => {
+  const run = (input, state) => func(input, state, context)
+
+  return { run }
+}
+
+exports.create = create

package/src/algorithms/runner.js

@@ -0,0 +1,50 @@
+'use strict'
+
+const { Connector } = require('@toa.io/core')
+
+/**
+ * @implements {toa.core.bridges.Algorithm}
+ */
+class Runner extends Connector {
+  /** @type {toa.node.algorithms.Constructor} */
+  #ctor
+
+  /** @type {toa.core.bridges.Algorithm} */
+  #instance
+
+  /**
+   * @param {toa.node.algorithms.Constructor} ctor
+   * @param {toa.node.Context} context
+   */
+  constructor (ctor, context) {
+    super()
+
+    this.#ctor = ctor
+
+    this.depends(context)
+  }
+
+  async connection () {
+    this.#instance = /** @type {toa.core.bridges.Algorithm} */ this.#ctor()
+  }
+
+  async run (input, state) {
+    let reply = await this.#instance.run(input, state)
+
+    if (reply !== undefined) reply = normalize(reply)
+
+    return reply
+  }
+}
+
+function normalize (reply) {
+  const object = typeof reply === 'object'
+  const output = object && reply.output !== undefined
+  const error = object && reply.error !== undefined
+
+  if (!output && !error) reply = { output: reply }
+
+  return reply
+}
+
+exports.Runner = Runner

package/src/context.js

@@ -1,11 +1,21 @@
 'use strict'
 
 const { Connector } = require('@toa.io/core')
-const { underlay } = require('@toa.io/gears')
+const { underlay } = require('@toa.io/generic')
 
+/**
+ * @implements {toa.node.Context}
+ */
 class Context extends Connector {
+  aspects
+  configuration
+  origins
+
   #context
 
+  /**
+   * @param {toa.core.Context} context
+   */
   constructor (context) {
     super()
 
@@ -14,8 +24,63 @@ class Context extends Connector {
     this.depends(context)
   }
 
-  local = underlay(async (endpoint, request) => this.#context.apply(endpoint, request))
-  remote = underlay(async (domain, name, endpoint, request) => this.#context.call(domain, name, endpoint, request))
+  async connection () {
+    this.aspects = this.#aspects(/** @type {toa.core.extensions.Aspect[]} */ this.#context.aspects)
+  }
+
+  local = underlay(async ([endpoint], [request]) => {
+    return this.#context.apply(endpoint, request)
+  })
+
+  remote = underlay(async ([namespace, name, endpoint], [request]) => {
+    return this.#context.call(namespace, name, endpoint, request)
+  })
+
+  /**
+   * @param {toa.core.extensions.Aspect[]} aspects
+   * @returns {{ [key: string]: Function}}
+   */
+  #aspects (aspects) {
+    const map = {}
+
+    for (const aspect of aspects) {
+      if (map[aspect.name] !== undefined) throw new Error(`Aspect conflict on '${aspect.name}'`)
+
+      map[aspect.name] = aspect.invoke.bind(aspect)
+
+      // well-known aspects
+      if (aspect.name === 'configuration') this.#configuration(aspect)
+      if (aspect.name === 'origins') this.origins = this.#origins(aspect)
+    }
+
+    return map
+  }
+
+  /**
+   * @param {toa.core.extensions.Aspect} aspect
+   */
+  #origins (aspect) {
+    return underlay(async (segs, args) => {
+      if (segs.length < 2) throw new Error(`Origins call requires at least 2 arguments, ${segs.length} given`)
+
+      const name = segs.shift()
+      const method = segs.pop().toUpperCase()
+      const path = segs.join('/')
+      const request = { method, ...args[0] }
+      const options = args[1]
+
+      return await aspect.invoke(name, path, request, options)
+    })
+  }
+
+  /**
+   * @param {toa.core.extensions.Aspect} aspect
+   */
+  #configuration (aspect) {
+    Object.defineProperty(this, 'configuration', {
+      get: () => aspect.invoke()
+    })
+  }
 }
 
 exports.Context = Context

package/src/define/.operations/define.js

@@ -0,0 +1,16 @@
+'use strict'
+
+const { extract } = require('./extract')
+const syntaxes = require('./syntaxes')
+
+/**
+ * @param {Object} module
+ * @returns {toa.node.define.operations.Definition}
+ */
+const define = (module) => {
+  const descriptor = extract(module)
+
+  return syntaxes[descriptor.syntax].define(descriptor)
+}
+
+exports.define = define

package/src/define/.operations/extract.js

@@ -0,0 +1,48 @@
+'use strict'
+
+const parser = require('@babel/parser')
+const syntaxes = require('./syntaxes')
+
+/**
+ * @param {Object} module
+ * @returns {toa.node.define.algorithms.Descriptor}
+ */
+const extract = (module) => {
+  const [name, func] = find(module)
+  const statement = parse(func)
+
+  /** @type {toa.node.define.algorithms.Descriptor} */
+  const descriptor = { name, statement, syntax: undefined }
+
+  for (const [syntax, { test }] of Object.entries(syntaxes)) {
+    if (test(statement, name)) descriptor.syntax = /** @type {toa.node.define.algorithms.Syntax} */ syntax
+  }
+
+  if (descriptor.syntax === undefined) throw new Error('Exported function does not match conventions')
+
+  return descriptor
+}
+
+/**
+ * @param {Object} module
+ * @returns [string, Function]
+ */
+const find = (module) => {
+  for (const [key, value] of Object.entries(module)) {
+    if (typeof value === 'function') return [key, value]
+  }
+
+  throw new Error('Module does not export function')
+}
+
+/**
+ * @param {Function} func
+ * @returns {import('@babel/types').Statement}
+ */
+const parse = (func) => {
+  const file = parser.parse(func.toString())
+
+  return file.program.body[0]
+}
+
+exports.extract = extract

package/src/define/.operations/index.js

@@ -0,0 +1,7 @@
+'use strict'
+
+const { define } = require('./define')
+const { extract } = require('./extract')
+
+exports.define = define
+exports.extract = extract

package/src/define/.operations/syntaxes/class.js

@@ -0,0 +1,42 @@
+'use strict'
+
+const { letters: { capitalize } } = require('@toa.io/generic')
+const { types } = require('./constants')
+const func = require('./function')
+
+/** @type {toa.node.define.operations.Define} */
+const define = (descriptor) => {
+  const declaration = /** @type {import('@babel/types').ClassDeclaration} */ descriptor.statement
+
+  descriptor.name = descriptor.name.toLowerCase()
+  descriptor.statement = method(declaration, 'run')
+
+  return func.define(descriptor)
+}
+
+/** @type {toa.node.define.operations.Test} */
+const test = (statement, name) => {
+  const declaration = statement.type === 'ClassDeclaration'
+  const known = names.includes(name)
+
+  return declaration && known
+}
+
+/**
+ * @param {import('@babel/types').ClassDeclaration} statement
+ * @param {string} name
+ * @returns {import('@babel/types').Statement}
+ */
+const method = (statement, name) => {
+  const methods = statement.body.body
+  const method = methods.find((method) => method.type === 'ClassMethod' && method.key.name === name)
+
+  if (method === undefined) throw new Error(`Method '${name}' not found`)
+
+  return /** @type {import('@babel/types').Statement} */ method
+}
+
+const names = types.map((type) => capitalize(type))
+
+exports.define = define
+exports.test = test

package/src/define/.operations/syntaxes/constants.js

@@ -0,0 +1,4 @@
+'use strict'
+
+exports.types = ['transition', 'observation', 'assignment']
+exports.scopes = ['object', 'objects', 'changeset', 'none']

package/src/define/.operations/syntaxes/factory.js

@@ -0,0 +1,27 @@
+'use strict'
+
+/** @type {toa.node.define.operations.Define} */
+const define = (descriptor) => {
+  const match = descriptor.name.match(pattern)
+
+  /** @type {toa.node.define.operations.Definition} */
+  const definition = {}
+
+  definition.type = /** @type {typeof toa.norm.component.Operation.scope} */ match[2].toLowerCase()
+  definition.scope = /** @type {typeof toa.norm.component.Operation.type} */ match[1].toLowerCase()
+
+  return definition
+}
+
+/** @type {toa.node.define.operations.Test} */
+const test = (statement, name) => {
+  const declaration = statement.type === 'ClassDeclaration'
+  const match = name.match(pattern) !== null
+
+  return declaration && match
+}
+
+const pattern = new RegExp('^(Objects?|Changeset|None)(Transition|Observation|Assignment)Factory$')
+
+exports.define = define
+exports.test = test

package/src/define/.operations/syntaxes/function.js

@@ -0,0 +1,41 @@
+'use strict'
+
+const { types, scopes } = require('./constants')
+
+/** @type {toa.node.define.operations.Define} */
+const define = (descriptor) => {
+  const { statement, name } = descriptor
+  const node = statement.type === 'ExpressionStatement' ? statement.expression : statement
+
+  /** @type {toa.node.define.operations.Definition} */
+  const definition = {}
+
+  definition.type = /** @type {typeof toa.norm.component.Operation.type} */ name
+
+  if (node.params.length > 1) definition.scope = scope(node.params[1].name)
+  else definition.scope = 'none'
+
+  if (node.params.length === 0) definition.input = null
+
+  return definition
+}
+
+/** @type {toa.node.define.operations.Test} */
+const test = (statement, type) => {
+  const node = statement.type === 'ExpressionStatement' ? statement.expression : statement
+  const func = nodes.includes(node.type)
+  const known = types.includes(type)
+
+  return func && known
+}
+
+/**
+ * @param {string} name
+ * @returns {typeof toa.norm.component.Operation.scope}
+ */
+const scope = (name) => scopes.includes(name) ? name : undefined
+
+const nodes = ['FunctionDeclaration', 'ArrowFunctionExpression', 'ClassMethod']
+
+exports.define = define
+exports.test = test

package/src/define/.operations/syntaxes/index.js

@@ -0,0 +1,5 @@
+'use strict'
+
+exports.function = require('./function')
+exports.class = require('./class')
+exports.factory = require('./factory')

package/src/define/index.js

@@ -1,12 +1,9 @@
 'use strict'
 
-const { events, event } = require('./events')
-const { receivers, receiver } = require('./receivers')
-const { operation, operations } = require('./operations')
+const { events } = require('./events')
+const { receivers } = require('./receivers')
+const { operations } = require('./operations')
 
-exports.event = event
 exports.events = events
-exports.receiver = receiver
 exports.receivers = receivers
-exports.operation = operation
 exports.operations = operations

package/src/define/operations.js

@@ -1,12 +1,21 @@
 'use strict'
 
-const { definition } = require('./operations/definition')
 const load = require('../load')
+const algorithm = require('./.operations')
 
+/** @type {toa.node.define.Algorithms} */
 const operations = async (root) => {
   const modules = await load.operations(root)
 
-  return Object.fromEntries(modules.map(([name, module]) => [name, definition(module)]))
+  /** @type {toa.node.define.algorithms.List} */
+  const algorithms = {}
+
+  for (const [name, module] of modules) algorithms[name] = algorithm.define(module)
+
+  return algorithms
 }
 
+const extract = (module) => algorithm.extract(module)
+
 exports.operations = operations
+exports.extract = extract

package/src/event.js

@@ -1,9 +1,16 @@
 'use strict'
 
-class Event {
+const { Connector } = require('@toa.io/core')
+
+/**
+ * @implements {toa.core.bridges.Event}
+ */
+class Event extends Connector {
   #event
 
   constructor (event) {
+    super()
+
     this.#event = event
   }
 

package/src/factory.js

@@ -1,28 +1,48 @@
 'use strict'
 
 const load = require('./load')
-const { Operation } = require('./operation')
+const { Runner } = require('./algorithms/runner')
 const { Event } = require('./event')
 const { Receiver } = require('./receiver')
 const { Context } = require('./context')
+const { extract } = require('./define/operations')
 
+/**
+ * @implements {toa.core.bridges.Factory}
+ */
 class Factory {
-  operation (root, name, context) {
-    const operation = load.operation(root, name)
+  algorithm (root, name, context) {
+    const module = load.operation(root, name)
     const ctx = new Context(context)
 
-    return new Operation(operation, ctx)
+    return runner(module, ctx)
   }
 
   event (root, label) {
     const event = load.event(root, label)
+
     return new Event(event)
   }
 
   receiver (root, label) {
     const receiver = load.receiver(root, label)
+
     return new Receiver(receiver)
   }
 }
 
+/**
+ * @param {Object} module
+ * @param {toa.node.Context} context
+ * @returns {Runner}
+ */
+function runner (module, context) {
+  const descriptor = extract(module)
+  const func = module[descriptor.name]
+  const factory = require('./algorithms/' + descriptor.syntax)
+  const ctor = () => factory.create(func, context)
+
+  return new Runner(ctor, context)
+}
+
 exports.Factory = Factory

package/src/index.js

@@ -3,5 +3,4 @@
 const { Factory } = require('./factory')
 
 exports.define = require('./define')
-
 exports.Factory = Factory

package/src/load.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const { basename, resolve } = require('path')
-const glob = require('fast-glob')
+const { file: { glob } } = require('@toa.io/filesystem')
 
 const operation = (root, name) => load(root, OPERATIONS_DIRECTORY, name)
 const event = (root, name) => load(root, EVENTS_DIRECTORY, name)

package/src/receiver.js

@@ -1,9 +1,16 @@
 'use strict'
 
-class Receiver {
+const { Connector } = require('@toa.io/core')
+
+/**
+ * @implements {toa.core.bridges.Receiver}
+ */
+class Receiver extends Connector {
   #receiver
 
   constructor (receiver) {
+    super()
+
     this.#receiver = receiver
   }