@toa.io/core 1.0.0-alpha.6 → 1.0.0-alpha.64

package/src/operation.js

@@ -1,7 +1,9 @@
 'use strict'
 
+const { console } = require('openspan')
 const { Connector } = require('./connector')
-const { SystemException } = require('./exceptions')
+const { SystemException, RequestContractException } = require('./exceptions')
+const { Readable } = require('node:stream')
 
 class Operation extends Connector {
   scope
@@ -26,13 +28,22 @@ class Operation extends Connector {
 
   async invoke (request) {
     try {
-      if (request.authentic !== true) this.#contracts.request.fit(request)
-      if ('query' in request) request.query = this.#query.parse(request.query)
+      if (request.authentic !== true)
+        this.#contracts.request.fit(request)
+
+      if ('query' in request)
+        request.query = this.#query.parse(request.query)
+
+      // validate entity
+      if ('entity' in request)
+        this.scope.fit(request.entity)
 
       const store = { request }
 
       return await this.process(store)
     } catch (e) {
+      console.error('Failed to execute operation', e)
+
       const exception = e instanceof Error ? new SystemException(e) : e
 
       return { exception }
@@ -47,14 +58,24 @@ class Operation extends Connector {
     return store.reply
   }
 
-  async acquire () {}
+  async acquire (store) {
+    if (this.#scope === 'none')
+      return
+
+    const scope = await this.query(store.request.query)
+    const raw = scope === null || scope instanceof Readable
+
+    store.scope = scope
+    store.state = raw ? scope : scope.get()
+  }
 
   async run (store) {
     const { request, state } = store
-    // noinspection UnnecessaryLocalVariableJS
-    const reply = await this.#cascade.run(request.input, state) || {}
+    const reply = await this.#cascade.run(request.input, state)
 
-    // this.#contracts.reply.fit(reply)
+    // validate reply only on local environments
+    if (process.env.TOA_ENV === 'local' && !(reply instanceof Readable))
+      this.#contracts.reply.fit(reply)
 
     store.reply = reply
   }
@@ -62,6 +83,9 @@ class Operation extends Connector {
   async commit () {}
 
   async query (query) {
+    if (query === undefined)
+      throw new RequestContractException('Request query is required')
+
     return this.scope[this.#scope](query)
   }
 }

package/src/receiver.js

@@ -16,18 +16,13 @@ class Receiver extends Connector {
   /** @type {string} */
   #endpoint
 
-  /** @type {toa.core.Component} */
+  /** @type {unknown[]} */
+  #arguments
+
   #local
 
-  /** @type {toa.core.bridges.Receiver} */
   #bridge
 
-  /**
-   *
-   * @param {toa.norm.component.Receiver} definition
-   * @param {toa.core.Component} local
-   * @param {toa.core.bridges.Receiver} bridge
-   */
   constructor (definition, local, bridge) {
     super()
 
@@ -36,6 +31,7 @@ class Receiver extends Connector {
     this.#conditioned = conditioned
     this.#adaptive = adaptive
     this.#endpoint = operation
+    this.#arguments = definition.arguments
 
     this.#local = local
     this.#bridge = bridge
@@ -58,7 +54,7 @@ class Receiver extends Connector {
   }
 
   async #request (payload) {
-    return this.#adaptive ? await this.#bridge.request(payload) : { input: payload }
+    return this.#adaptive ? await this.#bridge.request(payload, ...(this.#arguments ?? [])) : { input: payload }
   }
 }
 

package/src/remote.js

@@ -1,16 +1,14 @@
 'use strict'
 
-const { console } = require('@toa.io/console')
-
+const assert = require('node:assert')
 const { Component } = require('./component')
 
 class Remote extends Component {
-  async open () {
-    console.info(`Remote '${this.locator.id}' connected`)
-  }
+  explain (endpoint) {
+    assert.ok(endpoint in this.operations,
+      `Endpoint '${endpoint}' is not provided by '${this.locator.id}'`)
 
-  async dispose () {
-    console.info(`Remote '${this.locator.id}' disconnected`)
+    return this.operations[endpoint].explain()
   }
 }
 

package/src/state.js

@@ -1,62 +1,79 @@
 'use strict'
 
-const { empty } = require('@toa.io/generic')
+const { empty, newid } = require('@toa.io/generic')
+const { StatePreconditionException, StateNotFoundException } = require('./exceptions')
 
-const {
-  StatePreconditionException,
-  StateNotFoundException,
-  StateInitializationException
-} = require('./exceptions')
-
-/**
- * @implements {toa.core.State}
- */
 class State {
-  /** @type {toa.core.Storage} */
+  #associated
   #storage
-
-  /** @type {toa.core.entity.Factory} */
-  #entity
+  #entities
   #emission
-  #dependent
 
-  constructor (storage, entity, emission, dependent) {
+  constructor (storage, entity, emission, associated) {
     this.#storage = storage
-    this.#entity = entity
+    this.#entities = entity
     this.#emission = emission
-    this.#dependent = dependent === true
+    this.#associated = associated === true
   }
 
   init (id) {
-    return this.#entity.init(id)
+    return this.#entities.init(id)
+  }
+
+  fit (values) {
+    return this.#entities.fit(values)
   }
 
   async object (query) {
     const record = await this.#storage.get(query)
 
     if (record === null) {
-      if (this.#dependent && query.id !== undefined && query.version === undefined) return this.init(query.id)
-      else if (query.version !== undefined) throw new StatePreconditionException()
-    }
-
-    if (record === null) return null
-    else return this.#entity.object(record)
+      if (this.#associated && query.id !== undefined && query.version === undefined)
+        return this.init(query.id)
+      else if (query.version !== undefined)
+        throw new StatePreconditionException()
+
+      return null
+    } else
+      return this.#entities.object(record)
   }
 
   async objects (query) {
     const recordset = await this.#storage.find(query)
 
-    return this.#entity.objects(recordset)
+    return this.#entities.objects(recordset)
+  }
+
+  async stream (query) {
+    return this.#storage.stream(query)
   }
 
   changeset (query) {
-    return this.#entity.changeset(query)
+    return this.#entities.changeset(query)
   }
 
   none () {
     return null
   }
 
+  async ensure (query, properties) {
+    const object = this.#entities.init()
+    const blank = object.get()
+
+    Object.assign(blank, properties)
+
+    object.set(blank)
+
+    const record = await this.#storage.ensure(query, properties, object.get())
+
+    if (record.id !== blank.id) // exists
+      return this.#entities.object(record)
+
+    await this.#emission.emit(object.event())
+
+    return object
+  }
+
   async commit (state) {
     const event = state.event()
 
@@ -68,30 +85,34 @@ class State {
       ok = await this.#storage.store(object)
 
       // #20
-      await this.#emission.emit(event)
+      if (ok === true) {
+        await this.#emission.emit(event)
+      }
     }
 
     return ok
   }
 
   async apply (state) {
-    const { changeset, insert } = state.export()
-
-    let upsert
-
-    if (this.#dependent && state.query.id !== undefined && state.query.version === undefined) {
-      upsert = insert
-    }
+    const changeset = state.export()
 
-    const result = await this.#storage.upsert(state.query, changeset, upsert)
+    const result = await this.#storage.upsert(state.query, changeset)
 
     if (result === null) {
-      if (state.query.version !== undefined) throw new StatePreconditionException()
-      else throw new StateNotFoundException()
+      if (state.query.version !== undefined) {
+        throw new StatePreconditionException()
+      } else {
+        throw new StateNotFoundException()
+      }
+    } else {
+      // same as above
+      await this.#emission.emit({
+        changeset,
+        state: result
+      })
     }
 
-    // same as above
-    await this.#emission.emit({ changeset, state: result })
+    return result
   }
 }
 

package/src/transition.js

@@ -3,7 +3,10 @@
 const { retry } = require('@toa.io/generic')
 
 const { Operation } = require('./operation')
-const { StateConcurrencyException, StateNotFoundException } = require('./exceptions')
+const {
+  StateConcurrencyException,
+  StateNotFoundException
+} = require('./exceptions')
 
 class Transition extends Operation {
   #concurrency
@@ -23,7 +26,9 @@ class Transition extends Operation {
 
     store.scope = request.query ? await this.query(request.query) : this.scope.init()
 
-    if (store.scope === null) throw new StateNotFoundException()
+    if (store.scope === null) {
+      throw new StateNotFoundException()
+    }
 
     store.state = store.scope.get()
   }
@@ -35,11 +40,13 @@ class Transition extends Operation {
 
     scope.set(state)
 
-    const ok = await this.scope.commit(scope)
+    const result = await this.scope.commit(scope)
 
-    if (ok !== true) {
-      if (this.#concurrency === 'retry') retry()
-      else throw new StateConcurrencyException()
+    if (result === false) {
+      if (this.#concurrency === 'retry')
+        return retry()
+      else
+        throw new StateConcurrencyException()
     }
   }
 

package/src/transmission.js

@@ -18,13 +18,22 @@ class Transmission extends Connector {
     let i = 0
 
     while (reply === false && i < this.#bindings.length) {
-      reply = await this.#bindings[i].request(request)
+      const binding = this.#bindings[i]
+
       i++
+
+      if (request?.task === true) {
+        if (binding.task === undefined)
+          continue
+
+        await binding.task(request)
+        reply = null
+      } else
+        reply = await binding.request(request)
     }
 
-    if (reply === false) {
+    if (reply === false)
       throw new TransmissionException(`All (${this.#bindings.length}) bindings rejected.`)
-    }
 
     return reply
   }

package/test/component.test.js

@@ -3,6 +3,7 @@
 const { Component } = require('../src/component')
 const { codes } = require('../src/exceptions')
 const fixtures = require('./component.fixtures')
+const { AssertionError } = require('node:assert')
 
 describe('Invocations', () => {
   const name = ['foo', 'bar'][Math.floor(2 * Math.random())]
@@ -21,7 +22,7 @@ describe('Invocations', () => {
 
   it('should throw on unknown invocation name', async () => {
     await expect(() => component.invoke('baz'))
-      .rejects.toMatchObject({ code: codes.NotImplemented })
+      .rejects.toThrow(AssertionError)
   })
 
   it('should invoke input and query', async () => {

package/test/contract/conditions.test.js

@@ -2,19 +2,19 @@
 
 const { generate } = require('randomstring')
 
-const { Conditions } = require('../../src/contract/conditions')
+const { Contract } = require('../../src/contract/contract')
 const fixtures = require('./contract.fixtures')
 
-let conditions
+let contract
 
 beforeEach(() => {
-  conditions = new Conditions(fixtures.schema)
+  contract = new Contract(fixtures.schema)
 })
 
 it('should fit value', () => {
   const value = { foo: generate() }
 
-  conditions.fit(value)
+  contract.fit(value)
 
   expect(fixtures.schema.fit).toHaveBeenCalledWith(value)
 })
@@ -22,5 +22,5 @@ it('should fit value', () => {
 it('should throw on invalid value', () => {
   const value = { invalid: true }
 
-  expect(() => conditions.fit(value)).toThrow()
+  expect(() => contract.fit(value)).toThrow()
 })

package/test/contract/request.test.js

@@ -3,10 +3,10 @@
 const clone = require('clone-deep')
 const { generate } = require('randomstring')
 
-jest.mock('../../src/contract/conditions')
+jest.mock('../../src/contract/contract')
 
 const { Request } = require('../../src/contract/request')
-const { Conditions } = require('../../src/contract/conditions')
+const { Contract } = require('../../src/contract/contract')
 const fixtures = require('./contract.fixtures')
 
 let contract
@@ -14,14 +14,14 @@ let contract
 beforeEach(() => {
   jest.clearAllMocks()
 
-  contract = new Request(fixtures.schema)
+  contract = new Request(fixtures.schema, {})
 })
 
 const dummy = { schema: { properties: {} } }
 
 it('should extend Conditions', () => {
-  expect(contract).toBeInstanceOf(Conditions)
-  expect(Conditions).toHaveBeenCalledWith(fixtures.schema)
+  expect(contract).toBeInstanceOf(Contract)
+  expect(Contract).toHaveBeenCalledWith(fixtures.schema)
 })
 
 it('should fit request', () => {
@@ -29,7 +29,7 @@ it('should fit request', () => {
 
   contract.fit(request)
 
-  expect(Conditions.mock.instances[0].fit).toHaveBeenCalledWith(request)
+  expect(Contract.mock.instances[0].fit).toHaveBeenCalledWith(request)
 })
 
 describe('schema', () => {
@@ -59,7 +59,7 @@ describe('schema', () => {
 
   it('should not contain query if declaration.query is false', () => {
     schema.properties.query = { type: 'null' }
-    expect(Request.schema({ query: false }, dummy)).toStrictEqual(schema)
+    expect(Request.schema({ query: false }, dummy)).toMatchObject(schema)
   })
 
   it('should require query if declaration.query is true', () => {

package/test/entities/entity.test.js

@@ -7,35 +7,7 @@ beforeEach(() => {
   jest.clearAllMocks()
 })
 
-describe('new', () => {
-  it('should throw on schema error', () => {
-    const entity = new Entity(fixtures.schema)
-
-    expect(() => entity.set(fixtures.failed())).toThrow()
-  })
-
-  it('should provide state', () => {
-    const entity = new Entity(fixtures.schema)
-    const state = fixtures.state()
-
-    entity.set(state)
-
-    expect(entity.get()).toEqual(state)
-  })
-})
-
 describe('argument', () => {
-  it('should provide initial state if no argument passed', () => {
-    const entity = new Entity(fixtures.schema)
-    const defaults = fixtures.schema.defaults.mock.results[0].value
-    const expected = {
-      ...defaults,
-      _version: 0
-    }
-
-    expect(entity.get()).toStrictEqual(expected)
-  })
-
   it('should set state', () => {
     const state = fixtures.state()
     const entity = new Entity(fixtures.schema, state)
@@ -54,29 +26,12 @@ it('should provide event', () => {
 
   const event = entity.event()
 
-  expect(event).toEqual({
+  expect(event).toEqual(expect.objectContaining({
     state,
     origin,
-    changeset: {
+    changeset: expect.objectContaining({
       foo: 'new value',
       _version: 1
-    }
-  })
-})
-
-it('should define `id` as readonly', async () => {
-  const origin = fixtures.state()
-  const entity = new Entity(fixtures.schema, origin)
-  const state = entity.get()
-
-  expect(() => (state.id = 1)).toThrow('assign to read only property')
-})
-
-it('should seal id', async () => {
-  const origin = fixtures.state()
-  const entity = new Entity(fixtures.schema, origin)
-  const state = entity.get()
-  const redefine = () => Object.defineProperty(state, 'id', { writable: true })
-
-  expect(redefine).toThrow('redefine property')
+    })
+  }))
 })

package/types/bindings.d.ts

@@ -1,26 +1,28 @@
 import * as _core from './index'
 
-declare namespace toa.core.bindings{
+declare namespace toa.core.bindings {
 
   type Properties = {
     async?: boolean
   }
 
-  interface Consumer extends _core.Connector{
+  interface Consumer extends _core.Connector {
     request (request: Request): Promise<_core.Reply>
+
+    task (request: Request): Promise<void>
   }
 
-  interface Emitter extends _core.Connector{
+  interface Emitter extends _core.Connector {
     emit (message: _core.Message): Promise<void>
   }
 
-  interface Broadcast<L> extends _core.Connector{
+  interface Broadcast<L> extends _core.Connector {
     transmit<T> (label: L, payload: T): Promise<void>
 
     receive<T> (label: L, callback: (payload: T) => void | Promise<void>): Promise<void>
   }
 
-  interface Factory{
+  interface Factory {
     producer? (locator: _core.Locator, endpoints: Array<string>, producer: _core.Component): _core.Connector
 
     consumer? (locator: _core.Locator, endpoint: string): Consumer

package/types/component.d.ts

@@ -1,9 +1,12 @@
 import { Connector } from './connector'
 import { Locator } from './locator'
 import { Request } from './request'
+import { Operation } from './operations'
 
-export interface Component extends Connector{
+export class Component extends Connector {
   locator: Locator
 
+  constructor (locator: Locator, operations: Record<string, Operation>)
+
   invoke<T = any> (endpoint: string, request: Request): Promise<T>
 }

package/types/index.ts

@@ -5,6 +5,7 @@ export * as bridges from './bridges'
 export * as operations from './operations'
 
 export type { Component } from './component'
+export type { Remote } from './remote'
 export { Connector } from './connector'
 export type { Context } from './context'
 export type { Exception } from './exception'

package/types/locator.d.ts

@@ -1,10 +1,11 @@
-export class Locator {
+export class Locator{
   public readonly name: string
   public readonly namespace: string
 
   public readonly id: string
   public readonly label: string
   public readonly uppercase: string
+  public readonly lowercase: string
 
   constructor (name: string, namespace?: string)
 

package/types/operations.d.ts

@@ -1,2 +1,8 @@
+import { Request } from './request'
+
 export type type = 'transition' | 'observation' | 'assignment' | 'computation' | 'effect'
 export type scope = 'object' | 'objects' | 'changeset'
+
+export class Operation {
+  invoke<T = any> (request: Request): Promise<T>
+}

package/types/remote.d.ts

@@ -0,0 +1,18 @@
+import { Component } from './component'
+
+export class Remote extends Component {
+  explain (endpoint: string): Promise<Explanation>
+}
+
+interface Explanation {
+  input: Schema | null
+  output: Schema | null
+  errors?: string[]
+}
+
+interface Schema {
+  type: string
+  properties: {
+    [key: string]: Schema
+  }
+}

package/types/request.d.ts

@@ -14,6 +14,7 @@ export interface Request {
   input?: any
   query?: Query
   authentic?: boolean
+  task?: boolean
 }
 
 export interface Reply {

package/src/contract/conditions.js

@@ -1,21 +0,0 @@
-'use strict'
-
-const { SystemException } = require('../exceptions')
-
-class Conditions {
-  #schema
-
-  constructor (schema) {
-    this.#schema = schema
-  }
-
-  fit (value) {
-    const error = this.#schema.fit(value)
-
-    if (error !== null) throw new this.constructor.Exception(error)
-  }
-
-  static Exception = SystemException
-}
-
-exports.Conditions = Conditions