@toa.io/userland 1.0.0 → 1.1.0-dev.0

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

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

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/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/web/manifest.toa.yaml

@@ -0,0 +1,8 @@
+name: web
+
+operations:
+  get:
+    output: object
+
+origins:
+  dev: https://null

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

@@ -0,0 +1,10 @@
+'use strict'
+
+async function computation (_, context) {
+  const response = await context.http.dev.path.to.resource.get()
+  const output = await response.json()
+
+  return { output }
+}
+
+exports.computation = computation

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

@@ -0,0 +1,6 @@
+title: Should return response
+http:
+  json:async:
+    foo: bar
+output:
+  foo: bar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/userland",
-  "version": "1.0.0",
+  "version": "1.1.0-dev.0",
   "description": "Toa development kit",
   "homepage": "https://toa.io",
   "author": {
@@ -24,14 +24,14 @@
   "main": "src/index.js",
   "types": "types/index.d.ts",
   "dependencies": {
-    "@toa.io/boot": "1.0.0",
-    "@toa.io/core": "1.0.0",
-    "@toa.io/filesystem": "1.0.0",
-    "@toa.io/generic": "0.9.1",
-    "@toa.io/norm": "1.0.0",
-    "@toa.io/schemas": "0.8.2",
-    "@toa.io/yaml": "0.7.4",
+    "@toa.io/boot": "1.0.1-dev.0",
+    "@toa.io/core": "1.0.1-dev.0",
+    "@toa.io/filesystem": "1.0.1-dev.0",
+    "@toa.io/generic": "0.10.0-dev.0",
+    "@toa.io/norm": "1.0.1-dev.0",
+    "@toa.io/schemas": "0.8.3-dev.0",
+    "@toa.io/yaml": "0.7.5-dev.0",
     "tap": "16.3.4"
   },
-  "gitHead": "4280d81a44cfcc9e7ebdec37e8438cc6c03923f0"
+  "gitHead": "5e7998b39ea6111a2cf7d38fad8aeae71d742621"
 }

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,14 +26,14 @@ 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).
@@ -42,15 +42,47 @@ sample. See its [schema](./src/.replay/.suite/translate/schemas/message.cos.yaml
 
 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

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

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

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

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

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

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

@@ -0,0 +1,9 @@
+'use strict'
+
+const { configuration } = require('./configuration')
+const { state } = require('./state')
+const { http } = require('./http')
+
+exports.configuration = configuration
+exports.state = state
+exports.http = http

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

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

package/samples/src/.replay/.suite/translate/.operation/.prepare/types/async.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = (value) => async () => value

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

@@ -0,0 +1,26 @@
+'use strict'
+
+const { map } = require('@toa.io/generic')
+
+const types = {
+  Map: require('./map'),
+  Set: require('./set'),
+  sync: require('./sync'),
+  async: require('./async')
+}
+
+function cast (value) {
+  return map(value, replace)
+}
+
+function replace (key, value) {
+  const [name, type] = key.split(':')
+
+  if (!(type in types)) return
+
+  const typed = types[type](value)
+
+  return [name, typed]
+}
+
+exports.cast = cast

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

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

package/samples/src/.replay/.suite/translate/.operation/.prepare/types/map.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = (value) => new Map(Object.entries(value))

package/samples/src/.replay/.suite/translate/.operation/.prepare/types/set.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = (value) => new Set(value)

package/samples/src/.replay/.suite/translate/.operation/.prepare/types/sync.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = (value) => () => value

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

@@ -1,14 +1,14 @@
 'use strict'
 
-const specials = require('./specials')
+const { cast, expand } = require('./.prepare')
 
 /**
  * @param {toa.samples.Operation & Object} declaration
  */
 const prepare = (declaration) => {
-  for (const [keyword, prepare] of Object.entries(specials)) {
-    if (keyword in declaration) prepare(declaration)
-  }
+  expand(declaration)
+
+  if ('extensions' in declaration) cast(declaration.extensions)
 }
 
 exports.prepare = prepare

package/samples/types/operation.d.ts

@@ -1,5 +1,5 @@
 import * as _core from '@toa.io/core/types'
-import * as _sampling from '@toa.io/extensions.sampling'
+import * as _sampling from '@toa.io/extensions.sampling/types/request'
 
 declare namespace toa.samples {
 
@@ -27,7 +27,7 @@ declare namespace toa.samples {
     remote?: operations.Calls
     local?: operations.Calls
     events?: operations.Events
-    extensions?: _sampling.request.Extensions
+    extensions?: _sampling.Extensions
   }
 
 }

package/samples/src/.replay/.suite/translate/.operation/specials/configuration.js

@@ -1,26 +0,0 @@
-'use strict'
-
-/**
- * @param {toa.samples.Operation & Object} declaration
- */
-const configuration = (declaration) => {
-  const configuration = declaration.configuration
-
-  delete declaration.configuration
-
-  if (declaration.extensions === undefined) declaration.extensions = {}
-
-  if ('configuration' in declaration.extensions) {
-    throw new Error('Configuration extension sample is ambiguous')
-  }
-
-  /** @type {toa.sampling.request.extensions.Call} */
-  const call = {
-    result: configuration,
-    permanent: true
-  }
-
-  declaration.extensions.configuration = [call]
-}
-
-exports.configuration = configuration

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

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