@toa.io/core 1.0.0-alpha.283 → 1.0.0-alpha.286

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/core",
-  "version": "1.0.0-alpha.283",
+  "version": "1.0.0-alpha.286",
   "type": "module",
   "description": "Toa Core",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -12,20 +12,32 @@
   "bugs": {
     "url": "https://github.com/toa-io/toa/issues"
   },
-  "main": "src/index.js",
-  "types": "types/index.ts",
+  "main": "transpiled/index.js",
+  "types": "transpiled/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./transpiled/index.d.ts",
+      "default": "./transpiled/index.js"
+    },
+    "./types": {
+      "types": "./transpiled/types/index.d.ts",
+      "default": "./transpiled/types/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
+    "transpile": "tsc",
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
     "@rsql/parser": "1.6.0",
-    "@toa.io/generic": "1.0.0-alpha.283",
-    "js-yaml": "5.4.1",
-    "openspan": "1.0.0-alpha.277",
+    "@toa.io/generic": "1.0.0-alpha.286",
+    "@toa.io/schemas": "1.0.0-alpha.286",
+    "openspan": "1.0.0-alpha.286",
     "uuid": "14.0.2"
   },
-  "gitHead": "2f52b023bed0ccb2ecdb2b82fe59fbe38bf282e1"
+  "gitHead": "81f3d0688f17668b902be336d1749cc715edcdb6"
 }

package/source/assignment.ts

@@ -0,0 +1,27 @@
+import { Operation } from './operation.js'
+import type { Store } from './operation.js'
+import type { Changeset } from './entities/changeset.js'
+
+export class Assignment extends Operation {
+  protected override async acquire(store: Store): Promise<void> {
+    const changeset = this.scope.changeset(store.request.query as any)
+
+    store.scope = changeset
+    store.state = changeset.get()
+  }
+
+  protected override async commit(store: Store): Promise<void> {
+    const { scope, state, reply, request } = store
+
+    if (reply.error !== undefined) return
+
+    const changeset = scope as Changeset
+
+    changeset.set(state)
+
+    const output = await this.scope.apply(changeset, request.input)
+
+    // assignment returns new state by default
+    if (store.reply.output === undefined) store.reply.output = output
+  }
+}

package/{src/call.js → source/call.ts}

@@ -1,13 +1,16 @@
 import { Readable } from 'node:stream'
 import { current, encode } from 'openspan'
 import { Connector } from './connector.js'
+import type { Transmission } from './transmission.js'
+import type { Request as Contract } from './contract/request.js'
+import type { Request, Source } from './types/request.js'
 
 export class Call extends Connector {
-  #transmitter
-  #contract
-  #source
+  readonly #transmitter: Transmission
+  readonly #contract: Contract
+  readonly #source: Source | undefined
 
-  constructor (transmitter, contract, source) {
+  public constructor(transmitter: Transmission, contract: Contract, source?: Source) {
     super()
 
     this.#transmitter = transmitter
@@ -17,15 +20,13 @@ export class Call extends Connector {
     this.depends(transmitter)
   }
 
-  async invoke (request = {}) {
+  public async invoke(request: Request = {}): Promise<any> {
     // the caller may have attributed the call itself, as the node bridge does
-    if (this.#source !== undefined)
-      request.source ??= this.#source
+    if (this.#source !== undefined) request.source ??= this.#source
 
-    // fitting first lets the input schema supply its default;
-    // an operation that takes no input still has to send an explicit null
     this.#contract.fit(request)
 
+    // an operation that takes no input still has to send an explicit null
     request.input ??= null
 
     // avoid validation on the recipient's side
@@ -33,34 +34,28 @@ export class Call extends Connector {
 
     const context = current()
 
-    if (context !== undefined)
-      request.telemetry = encode(context)
+    if (context !== undefined) request.telemetry = encode(context)
 
     const reply = await this.#transmitter.request(request)
 
     if (reply === null) return null
     else if (reply instanceof Readable) return reply
     else {
-      if (reply.exception !== undefined)
-        throw reply.exception
+      if (reply.exception !== undefined) throw reply.exception
 
-      if (reply.error !== undefined)
-        return new RemoteError(reply.error)
-      else
-        return reply.output
+      if (reply.error !== undefined) return new RemoteError(reply.error)
+      else return reply.output
     }
   }
 
-  explain () {
+  public explain(): any {
     return this.#contract.discovery
   }
 }
 
-
-
 // the remote error as a value: every property it carries, and nothing else enumerable
 class RemoteError extends Error {
-  constructor (error) {
+  public constructor(error: object) {
     super()
 
     Object.assign(this, error)

package/{src/cascade.js → source/cascade.ts}

@@ -1,22 +1,20 @@
 import { Connector } from './connector.js'
+import type { Algorithm } from './types/bridges.js'
 
 export class Cascade extends Connector {
-  // #bridges
-  #last
+  readonly #last: Algorithm
 
-  constructor (bridges, preflight) {
+  public constructor(bridges: Algorithm[], preflight?: Connector) {
     super()
 
     // this.#bridges = bridges
     this.#last = bridges[bridges.length - 1]
 
-    if (preflight === undefined)
-      this.depends(bridges)
-    else
-      this.depends(bridges).depends(preflight)
+    if (preflight === undefined) this.depends(bridges)
+    else this.depends(bridges).depends(preflight)
   }
 
-  async run (...args) {
+  public async run(...args: [any, any?]): Promise<any> {
     // const reply = {}
     //
     // for (const bridge of this.#bridges) {

package/{src/component.js → source/component.ts}

@@ -1,20 +1,25 @@
 import assert from 'node:assert'
-import { console, current, decode, run } from 'openspan'
+import { console, current, decode, run, type SpanOptions } from 'openspan'
 import { Connector } from './connector.js'
+import type { Locator } from './locator.js'
+import type { Request } from './types/request.js'
 
-export class Component extends Connector {
-  locator
+/** What a component holds one of per endpoint: an operation, or the call that stands for it. */
+export interface Invocable extends Connector {
+  invoke: (request: Request) => Promise<any>
+}
+
+export class Component<O extends Invocable = Invocable> extends Connector {
+  public readonly locator: Locator
 
-  /** @protected */
-  operations
+  protected readonly operations: Record<string, O>
 
-  /** @protected */
-  kind = 'server'
+  protected kind: 'server' | 'client' = 'server'
 
-  /** @type {Record<string, object>} span options per endpoint */
-  #spans = {}
+  /** span options per endpoint */
+  readonly #spans: Record<string, SpanOptions> = {}
 
-  constructor (locator, operations) {
+  public constructor(locator: Locator, operations: Record<string, O>) {
     super()
 
     this.locator = locator
@@ -23,28 +28,27 @@ export class Component extends Connector {
     Object.values(operations).forEach((operation) => this.depends(operation))
   }
 
-  async invoke (endpoint, request) {
+  public async invoke<T = any>(endpoint: string, request?: Request): Promise<T> {
     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}'`)
 
     // if the request carries no telemetry, the trace starts here
     const remote = request?.telemetry === undefined ? null : decode(request.telemetry)
-    const task = () => this.process(endpoint, request)
+    const task = async (): Promise<any> => this.#process(endpoint, request)
 
-    if (remote === null)
-      return task()
-    else
-      return run(remote, task)
+    if (remote === null) return task()
+    else return run(remote, task)
   }
 
-  /** @private */
-  async process (endpoint, request) {
-    return console.span(this.span(endpoint), async () => {
-      const reply = await this.operations[endpoint].invoke(request)
+  async #process(endpoint: string, request?: Request): Promise<any> {
+    return console.span(this.#span(endpoint), async () => {
+      const reply = await this.operations[endpoint].invoke(request as Request)
 
       if (reply?.exception !== undefined) {
-        current().status = 'error'
+        const span = current()
+
+        if (span !== undefined) span.status = 'error'
 
         console.error('Failed to execute operation', {
           endpoint: `${this.locator.id}.${endpoint}`,
@@ -60,9 +64,8 @@ export class Component extends Connector {
    * The span of an endpoint never changes, so it is built once. Not in the constructor:
    * `kind` is a field of the subclass, and those are assigned after this one is built.
    *
-   * @private
    */
-  span (endpoint) {
+  #span(endpoint: string): SpanOptions {
     let options = this.#spans[endpoint]
 
     if (options === undefined) {
@@ -70,8 +73,7 @@ export class Component extends Connector {
 
       // the server span is emitted by the component itself, while the client span
       // belongs to the calling service and inherits it from the context
-      if (this.kind === 'server')
-        options.service = this.locator.id
+      if (this.kind === 'server') options.service = this.locator.id
 
       this.#spans[endpoint] = options
     }

package/{src/composition.js → source/composition.ts}

@@ -2,7 +2,13 @@ import { console } from 'openspan'
 import { Connector } from './connector.js'
 
 export class Composition extends Connector {
-  constructor (expositions, producers, receivers, tenants) {
+  // eslint-disable-next-line max-params
+  public constructor(
+    expositions: Connector[],
+    producers: Connector[],
+    receivers: Connector[],
+    tenants: Connector[]
+  ) {
     super()
 
     if (expositions.length > 0) this.depends(expositions)
@@ -11,11 +17,11 @@ export class Composition extends Connector {
     if (tenants.length > 0) this.depends(tenants)
   }
 
-  async open () {
+  protected override async open(): Promise<void> {
     console.info('Composition complete')
   }
 
-  async dispose () {
+  protected override async dispose(): Promise<void> {
     console.info('Composition shutdown complete')
   }
 }

package/{src/connector.js → source/connector.ts}

@@ -1,28 +1,17 @@
 import { console } from 'openspan'
+import type { Locator } from './locator.js'
 
-/**
- * Abstract connections hierarchy
- * @implements {toa.core.Connector}
- */
+/** Abstract connections hierarchy */
 export class Connector {
-  /** @type {Array<Connector>} */
-  #dependencies = []
+  #dependencies: Connector[] = []
+  #links: Connector[] = []
+  #connecting: Promise<void> | undefined
+  #disconnecting: Promise<void> | undefined
 
-  /** @type {Array<Connector>} */
-  #links = []
+  public readonly id: string
+  public connected: boolean = false
 
-  /** @type {Promise} */
-  #connecting
-
-  /** @type {Promise} */
-  #disconnecting
-
-  /** @type {string} */
-  id
-  /** @type {boolean} */
-  connected = false
-
-  constructor () {
+  public constructor() {
     this.id = this.constructor.name + '#' + Math.random().toString(36).substring(2, 8)
   }
 
@@ -31,12 +20,9 @@ export class Connector {
    *
    * See .connect() and .disconnect()
    *
-   * @param connector {Connector | any | Array<Connector | any>}
-   * @returns {Connector}
    */
-  depends (connector) {
-    /** @type {Connector} */
-    let next
+  public depends(connector: Connector | Connector[]): Connector {
+    let next: Connector
 
     if (connector instanceof Array) {
       if (connector.length === 0) throw new Error('Connectors array must not be empty')
@@ -62,10 +48,8 @@ export class Connector {
    *
    * See .connect() and .disconnect()
    *
-   * @param connector {Connector}
-   * @returns {void}
    */
-  link (connector) {
+  public link(connector: Connector): void {
     this.#links.push(connector)
   }
 
@@ -76,9 +60,8 @@ export class Connector {
    *
    * Method is idempotent
    *
-   * @returns {Promise<void>}
    */
-  async connect () {
+  public async connect(): Promise<void> {
     if (this.#connecting) return this.#connecting
 
     this.#disconnecting = undefined
@@ -89,12 +72,17 @@ export class Connector {
     }
 
     // anonymous grouping nodes are not worth a span
-    this.#connecting = TRACE_BOOT && this.constructor.name !== 'Connector'
-      ? console.span({
-        name: `connect ${this.constructor.name}`,
-        attributes: { id: this.locator?.id ?? this.id }
-      }, work)
-      : work()
+    this.#connecting =
+      TRACE_BOOT && this.constructor.name !== 'Connector'
+        ? console.span(
+            {
+              name: `connect ${this.constructor.name}`,
+              // a connector that has a locator is named by it; a grouping node has none
+              attributes: { id: (this as { locator?: Locator }).locator?.id ?? this.id }
+            },
+            work
+          )
+        : work()
 
     try {
       await this.#connecting
@@ -112,10 +100,8 @@ export class Connector {
    *
    * Method is idempotent
    *
-   * @param [interrupt] {boolean}
-   * @returns {Promise<void>}
    */
-  async disconnect (interrupt) {
+  public async disconnect(interrupt?: boolean): Promise<void> {
     // a connector that has not finished connecting has nothing to close, and
     // awaiting a connection that may never settle outlives any grace period
     const pending = interrupt === true || this.connected === false
@@ -149,7 +135,7 @@ export class Connector {
 
       clearInterval(interval)
 
-      await Promise.all(this.#dependencies.map(connector => connector.disconnect()))
+      await Promise.all(this.#dependencies.map((connector) => connector.disconnect()))
 
       await this.dispose()
     })()
@@ -157,33 +143,28 @@ export class Connector {
     await this.#disconnecting
   }
 
-  async reconnect () {
+  public async reconnect(): Promise<void> {
     await this.disconnect()
     await this.connect()
   }
 
-  debug (node = {}) {
+  public debug(node: Record<string, any> = {}): Record<string, any> {
     node[this.id] = { connected: this.connected }
 
-    if (this.#dependencies.length > 0) for (const connector of this.#dependencies) connector.debug?.(node[this.id])
+    if (this.#dependencies.length > 0)
+      for (const connector of this.#dependencies) connector.debug?.(node[this.id])
 
     return node
   }
 
-  /**
-   * Called on connection
-   */
-  async open () {}
+  /** Called on connection */
+  protected open(): Promise<void> | void {}
 
-  /**
-   * Called on disconnection
-   */
-  async close () {}
+  /** Called on disconnection */
+  protected close(): Promise<void> | void {}
 
-  /**
-   * Called after self and dependants disconnection is complete
-   */
-  async dispose () {}
+  /** Called after self and dependants disconnection is complete */
+  protected dispose(): Promise<void> | void {}
 }
 
 const DELAY = 5000

package/source/context.ts

@@ -0,0 +1,67 @@
+import { Connector } from './connector.js'
+import type { Locator } from './locator.js'
+import type { Component } from './component.js'
+import type { Remote } from './remote.js'
+import type { Aspect } from './types/extensions.js'
+import type { Request } from './types/request.js'
+
+type Discover = (namespace: string, name: string) => Promise<Remote>
+
+export class Context extends Connector {
+  public readonly env: string | undefined
+  public readonly name: string | undefined
+  public readonly aspects: Aspect[]
+  public readonly locator: Locator
+
+  readonly #local: Component
+  readonly #discover: Discover
+  readonly #remotes: Record<string, Promise<Remote>> = {}
+
+  public constructor(local: Component, discover: Discover, aspects: Aspect[] = []) {
+    super()
+
+    this.env = process.env.TOA_ENV
+    this.name = process.env.TOA_CONTEXT
+    this.aspects = aspects
+    this.locator = local?.locator
+
+    this.#local = local
+    this.#discover = discover
+
+    this.depends(local)
+
+    if (aspects.length > 0) this.depends(aspects)
+  }
+
+  public async apply(endpoint: string, request: Request): Promise<any> {
+    return this.#local.invoke(endpoint, request)
+  }
+
+  // eslint-disable-next-line max-params
+  public async call(
+    namespace: string,
+    name: string,
+    endpoint: string,
+    request: Request
+  ): Promise<any> {
+    const remote = await this.#remote(namespace, name)
+
+    return remote.invoke(endpoint, request)
+  }
+
+  async #remote(namespace: string, name: string): Promise<Remote> {
+    const key = namespace + '.' + name
+
+    this.#remotes[key] ??= this.#connect(namespace, name)
+
+    return this.#remotes[key]
+  }
+
+  async #connect(namespace: string, name: string): Promise<Remote> {
+    const remote = await this.#discover(namespace, name)
+
+    this.depends(remote)
+
+    return remote
+  }
+}

package/source/contract/contract.ts

@@ -0,0 +1,23 @@
+import { SystemException } from '../exceptions.js'
+import type { Schema, SchemaError } from '@toa.io/schemas'
+import type { Exception } from '../exceptions.js'
+
+/** What a contract throws with, stated by the subclass. */
+export type Refusal = new (error: SchemaError, cause?: unknown) => Exception
+
+export class Contract {
+  public readonly schema: Schema
+
+  public static Exception: Refusal = SystemException as unknown as Refusal
+
+  public constructor(schema: Schema) {
+    this.schema = schema
+  }
+
+  public fit(value: unknown): void {
+    const error = this.schema.fit(value)
+
+    if (error !== null)
+      throw new (this.constructor as typeof Contract).Exception(error, value)
+  }
+}

package/{src/contract/reply.js → source/contract/reply.ts}

@@ -1,23 +1,29 @@
 import { Contract } from './contract.js'
 import { ResponseContractException } from '../exceptions.js'
+import type { Refusal } from './contract.js'
+import type { JSONSchema } from './schemas.js'
 
 export class Reply extends Contract {
-  static Exception = ResponseContractException
+  public static override Exception: Refusal =
+    ResponseContractException as unknown as Refusal
 
-  static schema (output, errors) {
-    const schema = { type: 'object', properties: {}, additionalProperties: false }
+  public static schema(output?: JSONSchema, errors?: Array<string | number>): JSONSchema {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    }
 
     if (output !== undefined) {
       /*
-       * A reply carries more than the operation declares — `_version` and the rest of the
+       * A reply carries more than the operation declares — `VERSION` and the rest of the
        * record's own fields — so what it is validated against is the declaration relaxed.
        * On a copy: the declaration itself is what a component publishes when asked to
        * explain, and relaxing that would publish a contract nobody wrote.
        */
       output = structuredClone(output)
 
-      if (output.type === 'object')
-        output.additionalProperties = true
+      if (output.type === 'object') output.additionalProperties = true
       else if (output.type === 'array' && output.items?.type === 'object')
         output.items.additionalProperties = true
 
@@ -29,20 +35,21 @@ export class Reply extends Contract {
      * stated, an error is not a reply this operation makes — it is a mistake, and the
      * contract says so rather than passing an undeclared code on to whoever called.
      */
-    schema.properties.error = errors === undefined
-      ? false
-      : {
-          type: 'object',
-          properties: {
-            code: {
-              enum: errors
+    schema.properties.error =
+      errors === undefined
+        ? false
+        : {
+            type: 'object',
+            properties: {
+              code: {
+                enum: errors
+              },
+              message: {
+                type: 'string'
+              }
             },
-            message: {
-              type: 'string'
-            }
-          },
-          required: ['code']
-        }
+            required: ['code']
+          }
 
     return schema
   }