@toa.io/core 1.0.0-alpha.28 → 1.0.0-alpha.282

package/src/query/criteria.js

@@ -1,9 +1,7 @@
-'use strict'
+import { parse } from '@rsql/parser'
+import { QuerySyntaxException } from '../exceptions.js'
 
-const { parse } = require('@rsql/parser')
-const { QuerySyntaxException } = require('../exceptions')
-
-const criteria = (criteria, properties) => {
+export const criteria = (criteria, properties) => {
   let ast
 
   try {
@@ -37,5 +35,3 @@ const COERCE = {
   integer: Number.parseInt,
   boolean: (value) => value === 'true'
 }
-
-exports.criteria = criteria

package/src/query/options.js

@@ -1,8 +1,6 @@
-'use strict'
+import { QuerySyntaxException } from '../exceptions.js'
 
-const { QuerySyntaxException } = require('../exceptions')
-
-const options = (options, properties, system) => {
+export const options = (options, properties, system) => {
   if (options.sort !== undefined) options.sort = sort(options.sort, properties)
 
   if (options.projection !== undefined) projection(options.projection, properties)
@@ -33,8 +31,7 @@ const projection = (projection, properties) => {
     }
   }
 
-  if (projection.includes('_version') === false)
-    projection.push('_version')
+  for (const property of ['_version', '_created', '_updated', '_deleted'])
+    if (!projection.includes(property))
+      projection.push(property)
 }
-
-exports.options = options

package/src/query.js

@@ -1,12 +1,16 @@
-'use strict'
+import { empty } from '@toa.io/generic'
+import * as criteria from './query/criteria.js'
+import * as options from './query/options.js'
 
-const { empty } = require('@toa.io/generic')
-const parse = { ...require('./query/criteria'), ...require('./query/options') }
+const parse = { ...criteria, ...options }
 
-class Query {
+export class Query {
   #properties
   #system
 
+  /** @type {Map<string, object>} parsed criteria by their expression */
+  #asts = new Map()
+
   constructor (properties) {
     this.#properties = properties
     this.#system = Object.keys(properties).filter((key) => properties[key].system === true)
@@ -19,13 +23,15 @@ class Query {
   parse (query) {
     /** @type {toa.core.storages.Query} */
     const result = {}
-    const { id, version, criteria, ...rest } = query
+    const { id, ids, version, criteria, search, ...rest } = query
 
     const options = this.#options(rest)
 
     if (id !== undefined) result.id = id
+    if (ids !== undefined) result.ids = ids
     if (version !== undefined) result.version = version
-    if (criteria !== undefined) result.criteria = parse.criteria(criteria, this.#properties)
+    if (criteria !== undefined) result.criteria = this.#criteria(criteria)
+    if (search !== undefined) result.search = search
     if (options !== undefined) result.options = options
 
     return result
@@ -36,6 +42,29 @@ class Query {
 
     return parse.options(options, this.#properties, this.#system)
   }
+
+  /**
+   * Lexing an RSQL expression is the most expensive thing this class does, and the same
+   * expression arrives over and over: a route builds it from its own declaration and the
+   * request parameters. The tree is only read downstream — a storage builds a fresh query
+   * from it — so it is kept rather than parsed again.
+   *
+   * Expressions come from the client, hence the bound. An invalid one throws before it
+   * reaches the cache.
+   */
+  #criteria (criteria) {
+    const known = this.#asts.get(criteria)
+
+    if (known !== undefined) return known
+
+    const ast = parse.criteria(criteria, this.#properties)
+
+    if (this.#asts.size >= LIMIT) this.#asts.clear()
+
+    this.#asts.set(criteria, ast)
+
+    return ast
+  }
 }
 
-exports.Query = Query
+const LIMIT = 1024

package/src/receiver.js

@@ -1,12 +1,11 @@
-'use strict'
-
-const { add } = require('@toa.io/generic')
-const { Connector } = require('./connector')
+import { console, decode, run } from 'openspan'
+import { add } from '@toa.io/generic'
+import { Connector } from './connector.js'
 
 /**
  * @implements {toa.core.Receiver}
  */
-class Receiver extends Connector {
+export class Receiver extends Connector {
   /** @type {boolean} */
   #conditioned
 
@@ -16,18 +15,28 @@ class Receiver extends Connector {
   /** @type {string} */
   #endpoint
 
-  /** @type {toa.core.Component} */
+  /** @type {string} */
+  #label
+
+  /** @type {string} */
+  #destination
+
+  /** @type {unknown[]} */
+  #arguments
+
+  /** @type {toa.core.Source} */
+  #origin
+
   #local
 
-  /** @type {toa.core.bridges.Receiver} */
   #bridge
 
-  /**
-   *
-   * @param {toa.norm.component.Receiver} definition
-   * @param {toa.core.Component} local
-   * @param {toa.core.bridges.Receiver} bridge
-   */
+  /** @type {object} */
+  #delivery
+
+  /** @type {object} */
+  #processing
+
   constructor (definition, local, bridge) {
     super()
 
@@ -36,17 +45,42 @@ class Receiver extends Connector {
     this.#conditioned = conditioned
     this.#adaptive = adaptive
     this.#endpoint = operation
+    this.#label = definition.label ?? operation
+    this.#destination = definition.destination ?? this.#label
+    this.#arguments = definition.arguments
+    this.#origin = definition.origin
 
     this.#local = local
     this.#bridge = bridge
 
     this.depends(local)
     if (bridge !== undefined) this.depends(bridge)
+
+    /*
+     * The delivery span is created on behalf of the messaging destination, so that
+     * each consumer forms its own complete producer/consumer pair, and service graphs
+     * display fan-out correctly: producer -> destination -> each consumer
+     * (Tempo pairs spans one-to-one, thus multiple consumers can not pair
+     * with a single producer span, see grafana/tempo#5408)
+     */
+    this.#delivery = {
+      name: `${this.#label} deliver`,
+      kind: 'producer',
+      service: this.#destination,
+      attributes: { 'messaging.destination.name': this.#destination }
+    }
+
+    this.#processing = {
+      name: `${this.#label} process`,
+      kind: 'consumer',
+      service: local.locator.id,
+      attributes: { 'messaging.destination.name': this.#destination }
+    }
   }
 
   /** @hot */
   async receive (message) {
-    const { payload, ...extensions } = message
+    const { payload, telemetry, ...extensions } = message
 
     if (this.#conditioned && await this.#bridge.condition(payload) === false) return
 
@@ -54,12 +88,36 @@ class Receiver extends Connector {
 
     add(request, extensions)
 
-    await this.#local.invoke(this.#endpoint, request)
+    // set after `add`, so that a message field can not spoof the origin
+    if (this.#origin !== undefined) request.source = this.#origin
+
+    // continue the trace from the producer span
+    const remote = telemetry === undefined ? null : decode(telemetry)
+    const task = () => this.#process(request)
+
+    if (remote === null)
+      await task()
+    else
+      await run(remote, task)
+  }
+
+  async #process (request) {
+    return console.span(this.#delivery, async () => console.span(this.#processing, async () => {
+      try {
+        await this.#local.invoke(this.#endpoint, request)
+      } catch (error) {
+        console.error('Receiver error', {
+          component: this.#local.locator.id,
+          endpoint: this.#endpoint,
+          error
+        })
+
+        throw error
+      }
+    }))
   }
 
   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 }
   }
 }
-
-exports.Receiver = Receiver

package/src/reflection.js

@@ -1,11 +1,9 @@
-'use strict'
-
-const { Connector } = require('./connector')
+import { Connector } from './connector.js'
 
 /**
  * @implements {toa.core.Reflection}
  */
-class Reflection extends Connector {
+export class Reflection extends Connector {
   /** @type {toa.core.reflection.Source} */
   #source
 
@@ -24,5 +22,3 @@ class Reflection extends Connector {
     this.value = await this.#source()
   }
 }
-
-exports.Reflection = Reflection

package/src/remote.js

@@ -1,17 +1,14 @@
-'use strict'
+import assert from 'node:assert'
+import { Component } from './component.js'
 
-const { console } = require('@toa.io/console')
+export class Remote extends Component {
+  kind = 'client'
 
-const { Component } = require('./component')
+  explain (endpoint) {
+    if (!(endpoint in this.operations))
+      // `assert.fail`, not `assert.ok`: the message is built only when it is needed
+      assert.fail(`Endpoint '${endpoint}' is not provided by '${this.locator.id}'`)
 
-class Remote extends Component {
-  async open () {
-    console.info(`Remote '${this.locator.id}' connected`)
-  }
-
-  async dispose () {
-    console.info(`Remote '${this.locator.id}' disconnected`)
+    return this.operations[endpoint].explain()
   }
 }
-
-exports.Remote = Remote

package/src/state.js

@@ -1,82 +1,119 @@
-'use strict'
+import { StatePreconditionException, StateNotFoundException } from './exceptions.js'
 
-const { empty } = require('@toa.io/generic')
+export class State {
+  storage
 
-const {
-  StatePreconditionException,
-  StateNotFoundException
-} = require('./exceptions')
-
-class State {
   #associated
-  #storage
-  #entity
-  #emission
-
-  constructor (storage, entity, emission, associated) {
-    this.#storage = storage
-    this.#entity = entity
-    this.#emission = emission
+  #entities
+  #outbox
+
+  constructor (storage, entity, outbox, associated) {
+    this.storage = storage
+    this.#entities = entity
+    this.#outbox = outbox
     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)
+  async object (query, mutable = true) {
+    const record = await this.storage.get(query)
 
     if (record === null) {
-      if (this.#associated && query.id !== undefined && query.version === undefined) {
+      if (this.#associated && query.id !== undefined && query.criteria === undefined && query.version === undefined)
         return this.init(query.id)
-      } else if (query.version !== undefined) throw new StatePreconditionException()
-    }
+      else if (query.version !== undefined)
+        throw new StatePreconditionException()
 
-    if (record === null) {
       return null
-    } else {
-      return this.#entity.object(record)
-    }
+    } else
+      return this.#entities.object(record, mutable)
   }
 
-  async objects (query) {
-    const recordset = await this.#storage.find(query)
+  async objects (query, mutable = true) {
+    const recordset = await this.storage.find(query)
+    const missing = this.#associated && query.ids !== undefined && recordset.length < query.ids.length
+    const init = missing ? query.ids.filter((id) => !recordset.some((record) => record.id === id)) : undefined
+    
+    return this.#entities.objects(recordset, init, mutable)
+  }
 
-    return this.#entity.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 commit (state) {
-    const event = state.event()
+  async ensure (query, properties, input) {
+    const object = this.#entities.init()
+    const blank = object.get()
 
-    let ok = true
+    Object.assign(blank, properties)
 
-    if (!empty(event.changeset)) {
-      const object = state.get()
+    object.set(blank)
 
-      ok = await this.#storage.store(object)
+    const row = this.#outbox?.row(object.event(input))
+    const record = await this.storage.ensure(query, properties, object.get(), row)
 
-      // #20
-      if (ok === true) {
-        await this.#emission.emit(event)
-      }
-    }
+    if (record.id !== blank.id) // exists
+      return this.#entities.object(record, NOT_MUTABLE)
+
+    if (row !== undefined)
+      await this.#outbox.publish(row)
+
+    return object
+  }
+
+  async commit (state, input) {
+    if (state.constructor.name === 'EntitySet') 
+      return this.massCommit(state, input)
+
+    const data = state.get()
+
+    // the row is built before the write so that the storage can commit it in the same
+    // transaction, closing the window this used to have
+    const row = this.#outbox?.row(state.event(input))
+    const ok = await this.storage.store(data, row)
+
+    if (ok === true && row !== undefined)
+      await this.#outbox.publish(row)
+
+    return ok
+  }
+
+  async massCommit (state, input) {
+    const data = state.get()
+    const rows = this.#outbox === undefined
+      ? undefined
+      : state.events(input).map((event) => this.#outbox.row(event))
+
+    const ok = await this.storage.massStore(data, rows)
+
+    if (ok === true && rows !== undefined)
+      await Promise.all(rows.map((row) => this.#outbox.publish(row)))
 
     return ok
   }
 
-  async apply (state) {
+  async apply (state, input) {
     const changeset = state.export()
 
-    const result = await this.#storage.upsert(state.query, changeset)
+    // an assignment's event is the write's own images, so the storage fills them in;
+    // see `apply` in the outbox design
+    const row = this.#outbox?.row({ input })
+    const result = await this.storage.upsert(state.query, changeset, row)
 
     if (result === null) {
       if (state.query.version !== undefined) {
@@ -84,16 +121,18 @@ class State {
       } else {
         throw new StateNotFoundException()
       }
-    } else {
-      // same as above
-      await this.#emission.emit({
-        changeset,
-        state: result
-      })
+    } else if (row !== undefined) {
+      // the storage fills `origin` and `state` from its own write; a storage that does not
+      // know how leaves the event with what it was given
+      row.event.state ??= result
+      row.event.origin ??= null
+
+      await this.#outbox.publish(row)
     }
 
     return result
   }
 }
 
-exports.State = State
+/** an effect never commits what `ensure` hands it, see `Effect` */
+const NOT_MUTABLE = false

package/src/transition.js

@@ -1,14 +1,11 @@
-'use strict'
+import { retry } from '@toa.io/generic'
+import { Operation } from './operation.js'
+import { StateConcurrencyException, StateNotFoundException } from './exceptions.js'
 
-const { retry } = require('@toa.io/generic')
+export class Transition extends Operation {
+  /** a transition is the only operation that commits */
+  mutable = true
 
-const { Operation } = require('./operation')
-const {
-  StateConcurrencyException,
-  StateNotFoundException
-} = require('./exceptions')
-
-class Transition extends Operation {
   #concurrency
 
   constructor (cascade, scope, contract, query, definition) {
@@ -26,33 +23,26 @@ class Transition extends Operation {
 
     store.scope = request.query ? await this.query(request.query) : this.scope.init()
 
-    if (store.scope === null) {
+    if (store.scope === null || (store.scope.deleted === true && request.query?.options?.deleted !== true))
       throw new StateNotFoundException()
-    }
-
+  
     store.state = store.scope.get()
   }
 
   async commit (store) {
-    const {
-      scope,
-      state,
-      reply,
-      retry
-    } = store
+    const { scope, state, reply, retry } = store
 
     if (reply.error !== undefined) return
 
     scope.set(state)
 
-    const result = await this.scope.commit(scope)
+    const result = await this.scope.commit(scope, store.request.input)
 
     if (result === false) {
-      if (this.#concurrency === 'retry') {
+      if (this.#concurrency === 'retry')
         return retry()
-      } else {
+      else
         throw new StateConcurrencyException()
-      }
     }
   }
 
@@ -67,7 +57,5 @@ const RETRY = {
   base: 10,
   max: 5000,
   dispersion: 1,
-  retries: Infinity
+  retries: 32
 }
-
-exports.Transition = Transition

package/src/transmission.js

@@ -1,9 +1,7 @@
-'use strict'
+import { Connector } from './connector.js'
+import { TransmissionException } from './exceptions.js'
 
-const { Connector } = require('./connector')
-const { TransmissionException } = require('./exceptions')
-
-class Transmission extends Connector {
+export class Transmission extends Connector {
   #bindings
 
   constructor (bindings) {
@@ -18,16 +16,23 @@ 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
   }
 }
-
-exports.Transmission = Transmission

package/src/unmanaged.js

@@ -0,0 +1,7 @@
+import { Operation } from './operation.js'
+
+export class Unmanaged extends Operation {
+  acquire (context) {
+    context.state = this.scope.storage.raw
+  }
+}

package/test/call.fixtures.js

@@ -1,18 +1,18 @@
-'use strict'
+import { mock } from 'node:test'
 
-const { generate } = require('randomstring')
+import { generate } from 'randomstring'
 
 // noinspection JSCheckFunctionSignatures
-const transmission = {
-  request: jest.fn((request) => ({ [request.invalid ? 'exception' : 'output']: generate() })),
-  link: jest.fn()
+export const transmission = {
+  request: mock.fn((request) => ({ [request.invalid ? 'exception' : 'output']: generate() })),
+  link: mock.fn()
 }
 
-const contract = {
-  fit: jest.fn(() => null)
+export const contract = {
+  fit: mock.fn(() => null)
 }
 
-const request = () => ({
+export const request = () => ({
   ok: {
     input: { [generate()]: generate() },
     query: { [generate()]: generate() }
@@ -21,7 +21,3 @@ const request = () => ({
     invalid: true
   }
 })
-
-exports.transmission = transmission
-exports.contract = contract
-exports.request = request