@toa.io/userland 0.10.1-dev.0 → 0.20.0-alpha.0

package/example/.env

@@ -0,0 +1,9 @@
+TOA_ENV=local
+TOA_AMQP_CONTEXT=eyIuIjpbImFtcXA6Ly9sb2NhbGhvc3QiXX0=
+TOA_AMQP_CONTEXT__USERNAME=developer
+TOA_AMQP_CONTEXT__PASSWORD=secret
+TOA_MONGODB_TEA_POTS=mongodb://localhost
+TOA_MONGODB_TEA_POTS_USERNAME=developer
+TOA_MONGODB_TEA_POTS_PASSWORD=secret
+TOA_ORIGINS_DEFAULT_WEB_DEV=http://localhost
+TOA_ORIGINS_DEFAULT_WEB__PROPERTIES=3gAA

package/example/components/echo/manifest.toa.yaml

@@ -3,6 +3,13 @@ name: echo
 operations:
   signal:
     output: string
+  get:
+    output: string
+  resolve:
+    input: string
+    output: string
 
 configuration:
   signal: quack
+
+state: ~

package/example/components/echo/operations/get.js

@@ -0,0 +1,7 @@
+'use strict'
+
+async function computation (_, context) {
+  return context.state.value
+}
+
+exports.computation = computation

package/example/components/echo/operations/resolve.js

@@ -0,0 +1,7 @@
+'use strict'
+
+async function computation (key, context) {
+  return context.state.values.get(key)
+}
+
+exports.computation = computation

package/example/components/echo/operations/signal.js

@@ -1,7 +1,15 @@
 'use strict'
 
-async function computation (input, context) {
-  return context.configuration.signal
+class Computation {
+  #context
+
+  async mount (context) {
+    this.#context = context
+  }
+
+  async execute () {
+    return this.#context.configuration.signal
+  }
 }
 
-exports.computation = computation
+exports.Computation = Computation

package/example/components/echo/samples/get.yaml

@@ -0,0 +1,12 @@
+title: Should return value
+extensions:
+  state:
+    - result:
+        value: bar
+      permanent: true
+output: bar
+---
+title: Should return value (declaration with a shortcut)
+state:
+  value: bar
+output: bar

package/example/components/echo/samples/signal.yaml

@@ -1,6 +1,3 @@
-title: Should echo
-output: quack
----
 title: Should substitute configuration
 output: woof
 configuration:

package/example/components/math.calculations/operations/increment.js

@@ -4,9 +4,7 @@ async function computation (input, context) {
   let value = input.value
 
   for (let i = 0; i < input.times; i++) {
-    const reply = await context.local.add({ input: { a: value, b: 1 } })
-
-    value = reply.output
+    value = await context.local.add({ input: { a: value, b: 1 } })
   }
 
   return value

package/example/components/math.calculations/samples/add.yaml

@@ -1,7 +1,6 @@
 title: Should add numbers
 input:
-  a: 1
-  b: 2
+  <assign: assets/ab.yaml
 output: 3
 ---
 title: Should add negative numbers

package/example/components/math.calculations/samples/assets/ab.yaml

@@ -0,0 +1,2 @@
+a: 1
+b: 2

package/example/components/math.calculations/samples/increment.yaml

@@ -1,6 +1,7 @@
 title: Should increment number
 input:
   value: 1
+  times: 1
 output: 2
 local:
   add:
@@ -9,12 +10,7 @@ local:
       b: 1
     output: 2
 ---
-title: Should increment with actual call
-input:
-  value: 2
-output: 3
----
-title: Should increment twice (with second actual call)
+title: Should increment twice
 input:
   value: 0
   times: 2
@@ -28,3 +24,4 @@ local:
     - input:
         a: 1
         b: 1
+      output: 2

package/example/components/tea.pots/manifest.toa.yaml

@@ -4,7 +4,7 @@ namespace: tea
 entity:
   storage: mongodb
   schema:
-    material*: [glass, ceramic, steel]
+    material*: [ glass, ceramic, steel ]
     volume: number
     booked: false
 
@@ -21,7 +21,7 @@ operations:
 
 receivers:
   store.orders.created:
-    transition: transit
+    operation: transit
     binding: amqp # avoid discovery
 
 configuration:

package/example/components/web/manifest.toa.yaml

@@ -0,0 +1,8 @@
+name: web
+
+operations:
+  get:
+    output: object
+
+origins:
+  dev: http://api.example.com

package/example/components/web/operations/get.js

@@ -0,0 +1,14 @@
+'use strict'
+
+const { Nope } = require('nopeable')
+
+async function computation (_, context) {
+  const response = await context.http.dev.path.to.resource.get()
+  const type = response.headers.get('content-type')
+
+  if (type !== 'application/json') return new Nope(0, 'Unsupported media type ' + type)
+
+  return await response.json()
+}
+
+exports.computation = computation

package/example/components/web/samples/get.yaml

@@ -0,0 +1,8 @@
+title: Should return response
+http:
+  headers:
+    get:sync: 'application/json'
+  json:async:
+    foo: bar
+output:
+  foo: bar

package/example/context.toa.yaml

@@ -1,3 +1,10 @@
 name: examples
 packages: components/*
 registry: example
+
+amqp: amqp://localhost
+mongodb: mongodb://localhost
+
+origins:
+  default.web:
+    dev: http://localhost

package/example/stage/call.test.js

@@ -6,13 +6,12 @@ const stage = require('@toa.io/userland/stage')
 
 const root = resolve(__dirname, '../components')
 
-/** @type {toa.core.Component} */
 let echo
-
-/** @type {toa.core.Component} */
 let math
 
 beforeAll(async () => {
+  process.env.TOA_DEV = '1'
+
   const paths = ['echo', 'math.calculations'].map((rel) => resolve(root, rel))
 
   await stage.composition(paths)
@@ -23,12 +22,14 @@ beforeAll(async () => {
 
 afterAll(async () => {
   await stage.shutdown()
+
+  delete process.env.TOA_DEV
 })
 
 it('should call endpoint', async () => {
   const reply = await echo.invoke('signal', {})
 
-  expect(reply.output).toStrictEqual('quack')
+  expect(reply).toStrictEqual('quack')
 })
 
 it('should throw on invalid input', async () => {

package/example/stage/events.test.js

@@ -6,10 +6,11 @@ const stage = require('@toa.io/userland/stage')
 const binding = stage.binding.binding
 const root = resolve(__dirname, '../components')
 
-/** @type {toa.core.Component} */
 let remote
 
 beforeAll(async () => {
+  process.env.TOA_DEV = '1'
+
   const path = resolve(root, 'tea.pots')
 
   await stage.composition([path])
@@ -19,11 +20,13 @@ beforeAll(async () => {
 
 afterAll(async () => {
   await stage.shutdown()
+
+  delete process.env.TOA_DEV
 })
 
 it('should receive event', async () => {
   const created = await remote.invoke('transit', { input: { material: 'glass' } })
-  const id = created.output.id
+  const id = created.id
   const payload = { pot: id }
   const message = { payload }
   const request = { query: { id } }
@@ -32,7 +35,7 @@ it('should receive event', async () => {
 
   const reply = await remote.invoke('observe', request)
 
-  expect(reply.output.booked).toStrictEqual(true)
+  expect(reply.booked).toStrictEqual(true)
 })
 
 it('should emit event', async () => {

package/example/stage/invoke.test.js

@@ -9,6 +9,8 @@ const root = resolve(__dirname, '../components')
 let component
 
 beforeAll(async () => {
+  process.env.TOA_DEV = '1'
+
   const path = resolve(root, 'math.calculations')
 
   component = await stage.component(path)
@@ -16,6 +18,8 @@ beforeAll(async () => {
 
 afterAll(async () => {
   await stage.shutdown()
+
+  delete process.env.TOA_DEV
 })
 
 it('should invoke', async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/userland",
-  "version": "0.10.1-dev.0",
+  "version": "0.20.0-alpha.0",
   "description": "Toa development kit",
   "homepage": "https://toa.io",
   "author": {
@@ -24,14 +24,15 @@
   "main": "src/index.js",
   "types": "types/index.d.ts",
   "dependencies": {
-    "@toa.io/boot": "0.8.2-dev.0",
-    "@toa.io/core": "0.8.1",
-    "@toa.io/filesystem": "0.7.2",
-    "@toa.io/generic": "0.9.0",
-    "@toa.io/norm": "0.10.1-dev.0",
-    "@toa.io/schemas": "0.8.1",
-    "@toa.io/yaml": "0.7.3",
+    "@toa.io/boot": "0.20.0-alpha.0",
+    "@toa.io/core": "0.20.0-alpha.0",
+    "@toa.io/filesystem": "0.20.0-alpha.0",
+    "@toa.io/generic": "0.20.0-alpha.0",
+    "@toa.io/norm": "0.20.0-alpha.0",
+    "@toa.io/schemas": "0.20.0-alpha.0",
+    "@toa.io/storages.null": "0.20.0-alpha.0",
+    "@toa.io/yaml": "0.20.0-alpha.0",
     "tap": "16.3.4"
   },
-  "gitHead": "7f1fdbfe3aa33eb4a06cb1a33d15be18854bcd88"
+  "gitHead": "d047190899218b5249901a01a2a4caec5b34cf09"
 }

package/samples/notes.md

@@ -3,10 +3,10 @@
 ## Extending Replay
 
 1. Update [`example`](../example). `toa replay` should either fail or throw exception.
-2. Add [feature](./features). It should fail.
+2. Add [feature](/features). It should fail.
 3. If the new decorator is being developed:
     1. Add the [decorator](/extensions/sampling/docs/replay.md).
     2. Add [boot extension](/runtime/boot/src/extensions).
 4. Update `suite` [translation](./src/.suite/.component/translate.js).
-5. Ensure feature is passing.
+5. Ensure the feature is passing.
 6. Ensure example is passing with `toa replay`.

package/samples/readme.md

@@ -26,31 +26,63 @@ to be verified. See its [schema](./src/.replay/.suite/translate/schemas/operatio
 > as [multi-document YAML files](https://yaml.org/spec/1.2.2/#22-structures).
 
 Operation samples must be located under the `samples` directory in the component or context root.
-Sample file names must follow the convention: `namespace.name.operation.yaml`, that is, be an
+Sample file names must follow the convention: `namespace.component.operation.yaml`, that is, be an
 endpoint of the operation samples to be applied to. For component-level sample files `namespace`
 and `name` must match corresponding component, therefore are optional.
 
 ## Message Samples
 
 Message Sample is an object containing receiver's input (`payload`) to be substituted and
-outcomes (`input` and `query`) to be verified. Message sample may contain corresponding operation
+outcomes (`input` and `query`) to be verified. Message sample may contain the corresponding operation
 sample. See its [schema](./src/.replay/.suite/translate/schemas/message.cos.yaml).
 
-> Message samples are always [autonomous](#autonomy).
+> Message samples are only supported at [context level](#autonomy).
 
 ### Declaration
 
 Operation samples must be located under the `samples/messages` directory in the component or context
 root. Samples file names must follow the convention `namesace.component.event.yaml`, that is, be a
-label
-of the event receiver is consuming.
+label of the event receiver is consuming.
+
+#### Aspect Shortcuts
+
+- `configuration` for [Configuration](/extensions/configuration)
+- `state` for [State](/extensions/state)
+- `http` for HTTP Aspect from [Origins](/extensions/origins)
+
+#### Aspect Result Type Hints
+
+When using aspect calls, there might be situations where the returned values cannot be adequately described using YAML.
+To address this issue, type hints can be used.
+
+```yaml
+state:
+  values:Map:
+    foo: 1
+    bar: 2
+```
+
+In the above code snippet, the `state` Aspect returns a `values` field of type Map.
+
+```yaml
+state:
+  values:Set: [foo, bar]
+```
+
+`sync` and `async` hints define functions:
+
+```yaml
+state:
+  get:sync: foo
+  request:async: bar
+```
 
 ## Autonomy
 
 Component level samples are *autonomous*, namely, does not assume actual remote calls as
 replaying of component-level samples will boot only that component. Remote call attempt not declared
 within sample will cause an exception.
-See [examples](../example/components/math/calculations/samples).
+See [examples](../example/components/math.calculations/samples).
 
 For context level samples (integration samples), remote calls with non-declared outputs will be
 actually performed. Replaying these samples will boot the composition with all components of the
@@ -60,6 +92,40 @@ context (so as required extensions). See [examples](../example/samples).
 
 ## Replay
 
-Samples may be *replayed* using [`toa replay`](/runtime/cli/readme.md#replay) command.
-
 > Replaying samples requires local deployment environment.
+
+### CLI
+
+Samples may be replayed using [`toa replay`](/runtime/cli/readme.md#replay) command.
+
+See [features](/features/cli/replay.feature).
+
+### Framework
+
+`async components(paths: string[], options?): boolean`
+
+Replay component samples.
+
+`async components(paths: string[], options?): boolean`
+
+Replay context and its components' samples.
+
+#### Options
+
+<dl>
+<dt><code><strong>id</strong>: string</code></dt>
+<dd>Replay samples for a specified component</dd>
+
+<dt><code><strong>integration</strong>: string</code></dt>
+<dd>Replay samples for a specified component only</dd>
+<dd></dd>
+
+<dt><code><strong>operation</strong>: string</code></dt>
+<dd>Replay samples for specified operation</dd>
+
+<dt><code><strong>title</strong>: string</code></dt>
+<dd>Replay samples with titles matching given regexp</dd>
+
+</dl>
+
+See [types](types/suite.d.ts).

package/samples/src/.replay/.suite/component.js

@@ -5,21 +5,16 @@ const stage = require('@toa.io/userland/stage')
 const { operation } = require('./operation')
 
 /**
- *
- * @param {string} id
+ * @param {toa.core.Component} component
  * @param {toa.samples.operations.Set} set
  * @param {boolean} autonomous
  * @returns {Function}
  */
-const component = (id, set, autonomous) =>
+const component = (component, set, autonomous) =>
   async (test) => {
-    const remote = await stage.remote(id)
-
     for (const [endpoint, samples] of Object.entries(set)) {
-      await test.test(endpoint, operation(remote, endpoint, samples, autonomous))
+      await test.test(endpoint, operation(component, endpoint, samples, autonomous))
     }
-
-    await remote.disconnect()
   }
 
 exports.component = component

package/samples/src/.replay/.suite/operation.js

@@ -19,7 +19,7 @@ const operation = (remote, endpoint, samples, autonomous) =>
       const request = translate.operation(operation, autonomous)
       const name = operation.title ?? 'Sample #' + n
 
-      await test.test(name, async () => remote.invoke(endpoint, request))
+      await test.test(name, async () => await remote.invoke(endpoint, request))
     }
 
     test.end()

package/samples/src/.replay/.suite/operations.js

@@ -4,15 +4,17 @@ const { component } = require('./component')
 
 /**
  * @param {toa.samples.suite.Operations} operations
+ * @param {Record<string, toa.core.Component>} components
  * @param {boolean} autonomous
  * @return {Function}
  */
-const operations = (operations, autonomous) =>
+const operations = (operations, components, autonomous) =>
   async (test) => {
     for (const [id, set] of Object.entries(operations)) {
-      await test.test(id, component(id, set, autonomous))
-    }
+      const remote = components[id]
 
+      await test.test(id, component(remote, set, autonomous))
+    }
   }
 
 exports.operations = operations

package/samples/src/.replay/.suite/translate/.operation/.prepare/cast.js

@@ -0,0 +1,20 @@
+'use strict'
+
+const { plain } = require('@toa.io/generic')
+const types = require('./types')
+
+/**
+ * @param {toa.sampling.request.Extensions} extensions
+ */
+function cast (extensions) {
+  for (const calls of Object.values(extensions)) calls.map(resolve)
+}
+
+/**
+ * @param {toa.sampling.request.extensions.Call} call
+ */
+function resolve (call) {
+  if (plain(call.result)) call.result = types.cast(call.result)
+}
+
+exports.cast = cast

package/samples/src/.replay/.suite/translate/.operation/.prepare/cast.test.js

@@ -0,0 +1,94 @@
+'use strict'
+
+const { cast } = require('./')
+
+it('should be', async () => {
+  expect(cast).toBeInstanceOf(Function)
+})
+
+it('should cast to a Map', async () => {
+  /** @type {toa.sampling.request.Extensions} */
+  const extensions = {
+    state: [{
+      result: {
+        'value:Map': { foo: 'bar' }
+      }
+    }]
+  }
+
+  cast(extensions)
+
+  const value = /** @type {Map} */ extensions.state[0].result.value
+
+  expect(value).toBeDefined()
+  expect(value).toBeInstanceOf(Map)
+  expect(Array.from(value.keys())).toStrictEqual(['foo'])
+  expect(value.get('foo')).toStrictEqual('bar')
+})
+
+it('should not throw if result is undefined', async () => {
+  const extensions = { state: [{}] }
+
+  expect(() => cast(extensions)).not.toThrow()
+})
+
+it('should cast to a Set', async () => {
+  const names = ['Mary', 'Bob', 'Elizabeth']
+
+  /** @type {toa.sampling.request.Extensions} */
+  const extensions = {
+    state: [{
+      result: {
+        'names:Set': names
+      }
+    }]
+  }
+
+  cast(extensions)
+
+  const set = /** @type {Map} */ extensions.state[0].result.names
+
+  expect(set).toBeDefined()
+  expect(set).toBeInstanceOf(Set)
+  expect(Array.from(set)).toStrictEqual(names)
+})
+
+it('should cast to a Function', async () => {
+  const extensions = {
+    foo: [{
+      result: {
+        'resolve:sync': 'hello'
+      }
+    }]
+  }
+
+  cast(extensions)
+
+  const resolve = extensions.foo[0].result.resolve
+
+  expect(resolve).toBeDefined()
+  expect(resolve).toBeInstanceOf(Function)
+  expect(resolve()).toStrictEqual('hello')
+})
+
+it('should cast to async Function', async () => {
+  const extensions = {
+    foo: [{
+      result: {
+        'resolve:async': 'hello'
+      }
+    }]
+  }
+
+  cast(extensions)
+
+  const resolve = extensions.foo[0].result.resolve
+
+  expect(resolve).toBeDefined()
+  expect(resolve).toBeInstanceOf(Function)
+
+  const promise = resolve()
+
+  expect(promise).toBeInstanceOf(Promise)
+  await expect(promise).resolves.toStrictEqual('hello')
+})

package/samples/src/.replay/.suite/translate/.operation/.prepare/expand.js

@@ -0,0 +1,14 @@
+'use strict'
+
+const shortcuts = require('./shortcuts')
+
+/**
+ * @param {toa.samples.Operation & Object} declaration
+ */
+function expand (declaration) {
+  for (const [shortcut, expand] of Object.entries(shortcuts)) {
+    if (shortcut in declaration) expand(declaration)
+  }
+}
+
+exports.expand = expand

package/samples/src/.replay/.suite/translate/.operation/.prepare/index.js

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

package/samples/src/.replay/.suite/translate/.operation/.prepare/shortcuts/.aspect.js

@@ -0,0 +1,26 @@
+'use strict'
+
+const aspect = (name) =>
+  /**
+   * @param {toa.samples.Operation & Record<string, any>} declaration
+   */
+    (declaration) => {
+    const value = declaration[name]
+
+    delete declaration[name]
+
+    if (declaration.extensions === undefined) declaration.extensions = {}
+
+    if (name in declaration.extensions) throw new Error(`${name} aspect sample is ambiguous`)
+
+    /** @type {toa.sampling.request.extensions.Call} */
+    const call = {
+      result: value,
+      permanent: true
+    }
+
+    declaration.extensions[name] = [call]
+
+  }
+
+exports.aspect = aspect