@toa.io/userland 0.7.3 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/userland",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Toa development kit",
   "homepage": "https://toa.io",
   "author": {
@@ -33,5 +33,5 @@
     "@toa.io/yaml": "0.7.1",
     "tap": "16.3.4"
   },
-  "gitHead": "9989ea316ebf5698b1eee933e83a86e6a18b406b"
+  "gitHead": "38a4b7aa2f80ba650a796c517056fde8daeec75d"
 }

package/samples/readme.md

@@ -15,11 +15,10 @@ See [features](/features/replay).
 
 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/.suite/.component/sample.cos.yaml).
+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.
+> corresponding operation schemas.
 
 ### Declaration
 
@@ -35,7 +34,7 @@ and `name` must match corresponding component, therefore are optional.
 
 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
-sample. See its [schema](#).
+sample. See its [schema](./src/.replay/.suite/translate/schemas/message.cos.yaml).
 
 > Message samples are always [autonomous](#autonomy).
 

package/samples/src/components.js

@@ -4,8 +4,8 @@ const { components: load } = require('./suite')
 const { replay } = require('./replay')
 
 /** @type {toa.samples.replay.components} */
-const components = async (paths) => {
-  const suite = await load(paths)
+const components = async (paths, options = {}) => {
+  const suite = await load(paths, options)
 
   return await replay(suite, paths)
 }

package/samples/src/context.js

@@ -7,12 +7,17 @@ const { context: load } = require('./suite')
 const { replay } = require('./replay')
 
 /** @type {toa.samples.replay.context} */
-const context = async (path) => {
+const context = async (path, options = {}) => {
   const context = await norm.context(path)
   const paths = context.components.map((component) => component.path)
-  const suite = await load(path)
+  const suite = await load(path, options)
 
-  return await test.components(paths) && await replay(suite, paths)
+  let ok = true
+
+  if (options.integration !== true) ok = await test.components(paths, options)
+  if (ok) ok = await replay(suite, paths)
+
+  return ok
 }
 
 exports.context = context

package/samples/src/suite/.read/filter.js

@@ -0,0 +1,15 @@
+'use strict'
+
+/**
+ * @template {{ title: string }} T
+ * @param {T[]} samples
+ * @param {string} expression
+ * @returns {T}
+ */
+function filter (samples, expression) {
+  const rx = new RegExp(expression)
+
+  return samples.filter((sample) => rx.test(sample.title))
+}
+
+exports.filter = filter

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

@@ -4,12 +4,14 @@ const { join, basename } = require('node:path')
 const { file: { glob } } = require('@toa.io/filesystem')
 const yaml = require('@toa.io/yaml')
 
+const { filter } = require('./filter')
+
 /**
  * @param {string} path
- * @param {string} [id]
+ * @param {toa.samples.suite.Options} options
  * @returns {Promise<toa.samples.messages.Set>}
  */
-const messages = async (path, id) => {
+const messages = async (path, options) => {
   /** @type {toa.samples.messages.Set} */
   const messages = {}
 
@@ -18,9 +20,12 @@ const messages = async (path, id) => {
 
   for (const file of files) {
     const label = basename(file, EXTENSION)
-    const samples = /** @type {toa.samples.Message[]} */ await yaml.load.all(file)
 
-    if (id !== undefined) samples.forEach((sample) => (sample.component = id))
+    let samples = /** @type {toa.samples.Message[]} */ await yaml.load.all(file)
+
+    if (options.id !== undefined) samples.forEach((sample) => (sample.component = options.id))
+    if (options.component !== undefined) samples = samples.filter((sample) => sample.component === options.component)
+    if (options.title !== undefined) samples = filter(samples, options.title)
 
     messages[label] = samples
   }

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

@@ -6,13 +6,14 @@ const { merge } = require('@toa.io/generic')
 const yaml = require('@toa.io/yaml')
 
 const { parse } = require('./parse')
+const { filter } = require('./filter')
 
 /**
  * @param {string} path
- * @param {string} [id]
+ * @param {toa.samples.suite.Options} options
  * @returns {Promise<toa.samples.suite.Operations>}
  */
-const operations = async (path, id) => {
+const operations = async (path, options) => {
   /** @type {toa.samples.suite.Operations} */
   const operations = {}
 
@@ -21,10 +22,15 @@ const operations = async (path, id) => {
 
   for (const file of files) {
     const name = basename(file, EXTENSION)
-    const [component, operation] = parse(name, id)
+    const [component, operation] = parse(name, options.id)
 
-    /** @type {toa.samples.Operation[]} */
-    const samples = await yaml.load.all(file)
+    if (options.component !== undefined && component !== options.component) continue
+    if (options.operation !== undefined && operation !== options.operation) continue
+
+    let samples = /** @type {toa.samples.Operation[]} */ await yaml.load.all(file)
+
+    if (options.title !== undefined) samples = filter(samples, options.title)
+    if (samples.length === 0) continue
 
     if (operations[component] === undefined) operations[component] = {}
 
@@ -32,7 +38,7 @@ const operations = async (path, id) => {
     const set = operations[component]
 
     if (set[operation] === undefined) set[operation] = samples
-    else set[operation] = merge(set[operation], samples)
+    else set[operation] = /** @type {toa.samples.Operation[]} */ merge(set[operation], samples)
   }
 
   return operations

package/samples/src/suite/.read/parse.js

@@ -14,10 +14,6 @@ const parse = (name, def) => {
     throw new Error(`Component id mismatch: '${id}' expected, '${component}' given`)
   }
 
-  // if (id === undefined) {
-  //   throw new Error('Sample file name must be an operation endpoint')
-  // }
-
   return [id, endpoint]
 }
 

package/samples/src/suite/components.js

@@ -7,17 +7,20 @@ const read = require('./.read')
 
 /**
  * @param {string[]} paths
+ * @param {toa.samples.suite.Options} [options]
  * @returns {Promise<toa.samples.Suite>}
  */
-const components = async (paths) => {
+const components = async (paths, options = {}) => {
   /** @type {toa.samples.Suite} */
   const suite = { title: 'Component samples', autonomous: true, operations: {}, messages: {} }
 
   for (const path of paths) {
     const manifest = await norm.component(path)
-    const id = manifest.locator.id
-    const operations = await read.operations(path, id)
-    const messages = await read.messages(path, id)
+
+    options.id = manifest.locator.id
+
+    const operations = await read.operations(path, options)
+    const messages = await read.messages(path, options)
 
     merge(suite, { operations, messages })
   }

package/samples/src/suite/context.js

@@ -4,14 +4,15 @@ const read = require('./.read')
 
 /**
  * @param {string} path
+ * @param {toa.samples.suite.Options} [options]
  * @returns {Promise<toa.samples.Suite>}
  */
-const context = async (path) => {
+const context = async (path, options = {}) => {
   /** @type {toa.samples.Suite} */
   const suite = { title: 'Integration samples', autonomous: false }
 
-  suite.operations = await read.operations(path)
-  suite.messages = await read.messages(path)
+  suite.operations = await read.operations(path, options)
+  suite.messages = await read.messages(path, options)
 
   return suite
 }

package/samples/test/components.test.js

@@ -17,15 +17,18 @@ it('should be', () => {
 
 const paths = [generate()]
 
+/** @type {toa.samples.suite.Options} */
+const options = { component: generate() }
+
 /** @type {boolean} */
 let result
 
 beforeAll(async () => {
-  result = await components(paths)
+  result = await components(paths, options)
 })
 
 it('should load suite', async () => {
-  expect(mock.suite.components).toHaveBeenCalledWith(paths)
+  expect(mock.suite.components).toHaveBeenCalledWith(paths, options)
 })
 
 it('should replay suite', async () => {

package/samples/test/context/components/dummy/samples/messages/somewhere.something.happened.yaml

@@ -0,0 +1,6 @@
+title: Something happened with a dummy
+payload:
+  foo: bar
+input: foo
+query:
+  id: bar

package/samples/test/context/components/pot/manifest.toa.yaml

@@ -0,0 +1,2 @@
+namespace: dummies
+name: pot

package/samples/test/context/components/pot/samples/do.yaml

@@ -0,0 +1,11 @@
+title: First case
+input:
+  foo: bar
+output:
+  baz: true
+---
+title: Second case
+input:
+  foo: qux
+output:
+  baz: false

package/samples/test/context/components/{ok → pot}/samples/messages/somewhere.something.happened.yaml

@@ -1,4 +1,4 @@
-title: Foobar
+title: Something happened with a pot
 payload:
   foo: bar
 input: foo

package/samples/test/context.test.js

@@ -14,6 +14,7 @@ jest.mock('../src/replay', () => mock.replay)
 jest.mock('../src/components', () => mock.components)
 
 const { context } = require('../src/context')
+const { generate } = require('randomstring')
 
 it('should be', async () => {
   expect(context).toBeDefined()
@@ -25,6 +26,9 @@ const COMPONENTS = resolve(CONTEXT, 'components/*')
 /** @type {string[]} */
 let paths
 
+/** @type {toa.samples.suite.Options} */
+const options = { component: generate() }
+
 /** @type {boolean} */
 let ok
 
@@ -37,15 +41,15 @@ beforeEach(async () => {
 
   mock.components.components.mockImplementation(async () => true)
 
-  ok = await context(CONTEXT)
+  ok = await context(CONTEXT, options)
 })
 
 it('should replay context components sample sets', async () => {
-  expect(mock.components.components).toHaveBeenCalledWith(paths)
+  expect(mock.components.components).toHaveBeenCalledWith(paths, options)
 })
 
 it('should load integration suite', async () => {
-  expect(mock.suite.context).toHaveBeenCalledWith(CONTEXT)
+  expect(mock.suite.context).toHaveBeenCalledWith(CONTEXT, options)
 })
 
 it('should replay integration suite', async () => {

package/samples/test/suite.components.test.js

@@ -9,14 +9,16 @@ it('should be', () => {
   expect(components).toBeDefined()
 })
 
-const root = resolve(__dirname, 'context/components/ok')
-const paths = [root]
+const dummy = resolve(__dirname, 'context/components/dummy')
+const pot = resolve(__dirname, 'context/components/pot')
 const component = 'dummies.dummy'
 
 /** @type {toa.samples.Suite} */
 let suite
 
 beforeAll(async () => {
+  const paths = [dummy]
+
   suite = await components(paths)
 })
 
@@ -51,11 +53,72 @@ it('should load message samples', async () => {
   expect(suite.messages).toStrictEqual(expected)
 })
 
+describe('options', () => {
+  const paths = [dummy, pot]
+
+  it('should filter samples by component id', async () => {
+    /** @type {toa.samples.suite.Options} */
+    const options = { component: 'dummies.dummy' }
+
+    suite = await components(paths, options)
+
+    expect(suite.operations['dummies.pot']).toBeUndefined()
+
+    const messages = suite.messages['somewhere.something.happened']
+
+    expect(messages.length).toStrictEqual(1)
+    expect(messages[0].component).toStrictEqual('dummies.dummy')
+  })
+
+  it('should filter samples by operation name', async () => {
+    /** @type {toa.samples.suite.Options} */
+    const options = { operation: 'do' }
+
+    suite = await components(paths, options)
+
+    expect('undo' in suite.operations['dummies.dummy']).toStrictEqual(false)
+  })
+
+  it('should filter operation samples by title', async () => {
+    /** @type {toa.samples.suite.Options} */
+    const options = { title: 'Should not undo' }
+
+    suite = await components(paths, options)
+
+    expect('do' in suite.operations['dummies.dummy']).toStrictEqual(false)
+    expect(suite.operations['dummies.dummy'].undo.length).toStrictEqual(1)
+    expect(suite.operations['dummies.dummy'].undo[0].title).toStrictEqual(options.title)
+  })
+
+  it('should filter operation samples by title as regexp', async () => {
+    /** @type {toa.samples.suite.Options} */
+    const options = { title: 'Should [a-z]{2}t undo' }
+
+    suite = await components(paths, options)
+
+    expect(suite.operations['dummies.dummy']?.do).toBeUndefined()
+    expect(suite.operations['dummies.dummy'].undo.length).toStrictEqual(1)
+    expect(suite.operations['dummies.dummy'].undo[0].title).toStrictEqual('Should not undo')
+  })
+
+  it('should filter message samples by title', async () => {
+    /** @type {toa.samples.suite.Options} */
+    const options = { title: 'Something happened with a dummy' }
+
+    suite = await components(paths, options)
+
+    const messages = suite.messages['somewhere.something.happened']
+
+    expect(messages.length).toStrictEqual(1)
+    expect(messages[0].title).toStrictEqual(options.title)
+  })
+})
+
 /**
  * @returns {Promise<toa.samples.operations.Set>}
  */
 const operations = async () => {
-  const path = resolve(root, 'samples')
+  const path = resolve(dummy, 'samples')
 
   /** @type {toa.samples.Operation[]} */
   const do1 = (await yaml.load.all(resolve(path, 'do.yaml')))
@@ -77,7 +140,7 @@ const operations = async () => {
  */
 const messages = async () => {
   const label = 'somewhere.something.happened'
-  const file = resolve(root, 'samples/messages', label + '.yaml')
+  const file = resolve(dummy, 'samples/messages', label + '.yaml')
   const declarations = await yaml.load.all(file)
   const messages = declarations.map((sample) => ({ component, ...sample }))
 

package/samples/types/replay.d.ts

@@ -1,9 +1,9 @@
-import * as _suite from "./suite";
+import * as _suite from './suite'
 
 declare namespace toa.samples.replay {
 
-  type components = (paths: string[]) => Promise<boolean>
-  type context = (path: string) => Promise<boolean>
+  type components = (paths: string[], options?: _suite.Options) => Promise<boolean>
+  type context = (path: string, options?: _suite.Options) => Promise<boolean>
   type replay = (suite: _suite.Suite, paths: string[]) => Promise<boolean>
 
 }

package/samples/types/suite.d.ts

@@ -5,6 +5,14 @@ declare namespace toa.samples {
 
   namespace suite {
     type Operations = Record<string, _operations.Set>
+
+    type Options = {
+      id?: string
+      integration?: boolean
+      component?: string
+      operation?: string
+      title?: string
+    }
   }
 
   type Suite = {
@@ -17,3 +25,4 @@ declare namespace toa.samples {
 }
 
 export type Suite = toa.samples.Suite
+export type Options = toa.samples.suite.Options