@toa.io/userland 1.0.0-alpha.7 → 1.0.0-alpha.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/userland",
-  "version": "1.0.0-alpha.7",
+  "version": "1.0.0-alpha.9",
   "description": "Toa development kit",
   "homepage": "https://toa.io",
   "author": {
@@ -24,15 +24,15 @@
   "main": "src/index.js",
   "types": "types/index.d.ts",
   "dependencies": {
-    "@toa.io/boot": "1.0.0-alpha.7",
-    "@toa.io/core": "1.0.0-alpha.7",
-    "@toa.io/filesystem": "1.0.0-alpha.7",
-    "@toa.io/generic": "1.0.0-alpha.7",
-    "@toa.io/norm": "1.0.0-alpha.7",
-    "@toa.io/schemas": "1.0.0-alpha.7",
+    "@toa.io/boot": "1.0.0-alpha.9",
+    "@toa.io/core": "1.0.0-alpha.9",
+    "@toa.io/filesystem": "1.0.0-alpha.9",
+    "@toa.io/generic": "1.0.0-alpha.9",
+    "@toa.io/norm": "1.0.0-alpha.9",
+    "@toa.io/schemas": "1.0.0-alpha.9",
     "@toa.io/storages.null": "0.22.0",
-    "@toa.io/yaml": "1.0.0-alpha.7",
+    "@toa.io/yaml": "1.0.0-alpha.9",
     "tap": "16.3.4"
   },
-  "gitHead": "4f5ac0bc342d4b7bd469fbe5c74266f050b55c9f"
+  "gitHead": "017a3fa22e8c60654c240f8e55908773d44d4ed1"
 }

package/readme.md

@@ -1,8 +1,6 @@
 # Toa development kit
 
 - [Stage](./stage): integration tests framework (Node.js)
-- [Samples](./samples): YAML-based declarative tests
-- Features[^1]: Gherkin steps definition ([cucumber.js](https://github.com/cucumber/cucumber-js))
 
 See [example](./example).
 

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

@@ -1,12 +0,0 @@
-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,4 +0,0 @@
-title: Should substitute configuration
-output: woof
-configuration:
-  signal: woof

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

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

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

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

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

@@ -1,27 +0,0 @@
-title: Should increment number
-input:
-  value: 1
-  times: 1
-output: 2
-local:
-  add:
-    input:
-      a: 1
-      b: 1
-    output: 2
----
-title: Should increment twice
-input:
-  value: 0
-  times: 2
-output: 2
-local:
-  add:
-    - input:
-        a: 0
-        b: 1
-      output: 1
-    - input:
-        a: 1
-        b: 1
-      output: 2

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

@@ -1,11 +0,0 @@
-title: Should add numbers
-input:
-  a: 1
-  b: 2
-output: 3
-remote:
-  math.calculations.add:
-    input:
-      a: 1
-      b: 2
-    output: 3

package/example/components/tea.pots/samples/same.yaml

@@ -1,8 +0,0 @@
-title: Should find same material
-input: steel
-local:
-  enumerate:
-    query:
-      criteria: 'material==steel'
-      limit: 10
-    output: []

package/example/components/tea.pots/samples/transit.yaml

@@ -1,43 +0,0 @@
-title: Should create
-input:
-  material: glass
-  volume: 1.5
-next:
-  material: glass
-  volume: 1.5
----
-title: Should update
-input:
-  material: steel
-current:
-  material: glass
-  volume: 1.5
-next:
-  material: steel
-  volume: 1.5
----
-title: Should emit `created` event
-input:
-  material: glass
-  volume: 1.5
-next:
-  material: glass
-  volume: 1.5
-events:
-  created:
-    material: glass
-    volume: 1.5
----
-title: Should emit `updated` event
-input:
-  material: steel
-current:
-  material: glass
-  volume: 1.5
-next:
-  material: steel
-  volume: 1.5
-events:
-  updated:
-    material: steel
-    volume: 1.5

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

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

package/example/samples/math.proxy.add.yaml

@@ -1,5 +0,0 @@
-title: Should add numbers
-input:
-  a: 1
-  b: 2
-output: 3

package/example/samples/messages/store.orders.created.yaml

@@ -1,8 +0,0 @@
-title: Should book a pot
-component: tea.pots
-payload:
-  pot: a959effedd5d4c34a3ee9f640dab2d7e
-input:
-  booked: true
-query:
-  id: a959effedd5d4c34a3ee9f640dab2d7e

package/samples/notes.md

@@ -1,12 +0,0 @@
-# Developer notes
-
-## Extending Replay
-
-1. Update [`example`](../example). `toa replay` should either fail or throw exception.
-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 the feature is passing.
-6. Ensure example is passing with `toa replay`.

package/samples/package.json

@@ -1,5 +0,0 @@
-{
-  "private": true,
-  "main": "src/index.js",
-  "types": "types/index.d.ts"
-}

package/samples/readme.md

@@ -1,131 +0,0 @@
-# Samples
-
-## TL;DR
-
-<a href="https://miro.com/app/board/uXjVOoy0ImU=/?moveToWidget=3458764532091744292&cot=14">
-    <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="./docs/sampling-dark.jpg">
-        <img alt="4D" width="640" height="435" src="./docs/sampling-light.jpg">
-    </picture>
-</a>
-
-See [features](/features/replay).
-
-## Operation Samples
-
-Sample is an object containing values of operation inputs (i.e.: request, context outputs and
-current state) to be substituted and outcomes (reply, context calls, next state and events emission)
-to be verified. See its [schema](./src/.replay/.suite/translate/schemas/operation.cos.yaml).
-
-> Although `input` and `output` are declared as arbitrary values, they must conform to the
-> corresponding operation schemas.
-
-### Declaration
-
-> Samples must be declared
-> 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.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 the corresponding
-operation
-sample. See its [schema](./src/.replay/.suite/translate/schemas/message.cos.yaml).
-
-> 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.
-
-#### 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 code snippet above, 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).
-
-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
-context (so as required extensions). See [examples](../example/samples).
-
-> Integration samples are more flexible and less sensitive to implementation details.
-
-## Replay
-
-### 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

@@ -1,20 +0,0 @@
-'use strict'
-
-const stage = require('@toa.io/userland/stage')
-
-const { operation } = require('./operation')
-
-/**
- * @param {toa.core.Component} component
- * @param {toa.samples.operations.Set} set
- * @param {boolean} autonomous
- * @returns {Function}
- */
-const component = (component, set, autonomous) =>
-  async (test) => {
-    for (const [endpoint, samples] of Object.entries(set)) {
-      await test.test(endpoint, operation(component, endpoint, samples, autonomous))
-    }
-  }
-
-exports.component = component

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

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

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

@@ -1,39 +0,0 @@
-'use strict'
-
-const { binding } = require('@toa.io/userland/stage').binding
-
-const translate = require('./translate')
-
-/**
- * @param {toa.samples.messages.Set} messages
- * @param {boolean} autonomous
- * @return {Function}
- */
-const messages = (messages, autonomous) =>
-  async (test) => {
-    for (const [label, samples] of Object.entries(messages)) {
-      await test.test(label, message(label, samples, autonomous))
-    }
-  }
-
-/**
- * @param {string} label
- * @param {toa.samples.Message[]} samples
- * @param {boolean} autonomous
- * @returns {function}
- */
-const message = (label, samples, autonomous) =>
-  async (test) => {
-    let n = 0
-
-    for (const sample of samples) {
-      n++
-
-      const message = translate.message(sample, autonomous)
-      const name = sample.title ?? 'Sample #' + n
-
-      await test.test(name, async () => binding.emit(label, message))
-    }
-  }
-
-exports.messages = messages

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

@@ -1,28 +0,0 @@
-'use strict'
-
-const translate = require('./translate')
-
-/**
- * @param {toa.core.Component} remote
- * @param {string} endpoint
- * @param {toa.samples.Operation[]} samples
- * @param {boolean} autonomous
- * @returns {Function}
- */
-const operation = (remote, endpoint, samples, autonomous) =>
-  async (test) => {
-    let n = 0
-
-    for (const operation of samples) {
-      n++
-
-      const request = translate.operation(operation, autonomous)
-      const name = operation.title ?? 'Sample #' + n
-
-      await test.test(name, async () => await remote.invoke(endpoint, request))
-    }
-
-    test.end()
-  }
-
-exports.operation = operation

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

@@ -1,20 +0,0 @@
-'use strict'
-
-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, components, autonomous) =>
-  async (test) => {
-    for (const [id, set] of Object.entries(operations)) {
-      const remote = components[id]
-
-      await test.test(id, component(remote, set, autonomous))
-    }
-  }
-
-exports.operations = operations

package/samples/src/.replay/.suite/translate/.message/index.js

@@ -1,5 +0,0 @@
-'use strict'
-
-const { request } = require('./request')
-
-exports.request = request

package/samples/src/.replay/.suite/translate/.message/request.js

@@ -1,31 +0,0 @@
-'use strict'
-
-const { add, defined } = require('@toa.io/generic')
-const translate = require('../operation')
-
-/**
- * @param {toa.samples.Message} declaration
- * @param {boolean} autonomous
- * @returns {toa.sampling.request.Sample}
- */
-const request = (declaration, autonomous) => {
-  const { title, input, query } = declaration
-
-  /** @type {toa.sampling.request.Sample} */
-  const sample = declaration.request === undefined
-    ? {}
-    : translate.operation(declaration.request, autonomous).sample
-
-  const request = defined({ input, query })
-
-  /** @type {Partial<toa.sampling.request.Sample>} */
-  const patch = { title, autonomous, request }
-
-  if (declaration.request === undefined) patch.terminate = true
-
-  add(sample, patch)
-
-  return sample
-}
-
-exports.request = request

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

@@ -1,20 +0,0 @@
-'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

@@ -1,94 +0,0 @@
-'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

@@ -1,14 +0,0 @@
-'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

@@ -1,7 +0,0 @@
-'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

@@ -1,26 +0,0 @@
-'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