@toa.io/core 1.0.0-alpha.291 → 1.0.0-alpha.293

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/core",
-  "version": "1.0.0-alpha.291",
+  "version": "1.0.0-alpha.293",
   "type": "module",
   "description": "Toa Core",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -28,16 +28,22 @@
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "transpiled",
+    "!**/tsconfig.tsbuildinfo",
+    "!**/*.test.*",
+    "!**/.env*"
+  ],
   "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.291",
-    "@toa.io/schemas": "1.0.0-alpha.291",
-    "openspan": "1.0.0-alpha.286",
+    "@toa.io/generic": "1.0.0-alpha.292",
+    "@toa.io/schemas": "1.0.0-alpha.293",
+    "openspan": "1.0.0-alpha.293",
     "uuid": "14.0.2"
   },
-  "gitHead": "bcd8d8d07bd3e64fc826af8719472404662cc37f"
+  "gitHead": "1e05b3ab64758324c58c425f1f8e52e9f35f1da8"
 }

package/CHANGELOG.md

@@ -1,35 +0,0 @@
-# Change Log
-
-All notable changes to this project will be documented in this file.
-See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
-
-# [1.0.0-alpha.291](https://github.com/toa-io/toa/compare/v1.0.0-alpha.290...v1.0.0-alpha.291) (2026-09-07)
-
-**Note:** Version bump only for package @toa.io/core
-
-
-
-
-
-# [1.0.0-alpha.289](https://github.com/toa-io/toa/compare/v1.0.0-alpha.288...v1.0.0-alpha.289) (2026-09-07)
-
-* A deploy moves only what changed, and a component sees none of the runtime's environment (#1073) ([f38e3db](https://github.com/toa-io/toa/commit/f38e3db533f24db866c57bfa1ef294eff1eaf499)), closes [#1073](https://github.com/toa-io/toa/issues/1073) [#1064](https://github.com/toa-io/toa/issues/1064) [#1066](https://github.com/toa-io/toa/issues/1066) [#1067](https://github.com/toa-io/toa/issues/1067) [#1068](https://github.com/toa-io/toa/issues/1068) [#1069](https://github.com/toa-io/toa/issues/1069) [#1071](https://github.com/toa-io/toa/issues/1071) [#1070](https://github.com/toa-io/toa/issues/1070) [#1072](https://github.com/toa-io/toa/issues/1072)
-
-### BREAKING CHANGES
-
-* a component that read `process.env.TOA_*` reads `context` instead;
-  `echo(input)` no longer substitutes from the environment; a bash operation sees no
-  `TOA_*`; images no longer set `USER node` — see migrations/289.md.
-
-
-# [1.0.0-alpha.288](https://github.com/toa-io/toa/compare/v1.0.0-alpha.287...v1.0.0-alpha.288) (2026-09-06)
-
-**Note:** Version bump only for package @toa.io/core
-
-
-
-
-
-# [1.0.0-alpha.287](https://github.com/toa-io/toa/compare/v1.0.0-alpha.286...v1.0.0-alpha.287) (2026-09-06)
-
-**Note:** Version bump only for package @toa.io/core

package/source/assignment.ts

@@ -1,27 +0,0 @@
-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/source/call.ts

@@ -1,63 +0,0 @@
-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 {
-  readonly #transmitter: Transmission
-  readonly #contract: Contract
-  readonly #source: Source | undefined
-
-  public constructor(transmitter: Transmission, contract: Contract, source?: Source) {
-    super()
-
-    this.#transmitter = transmitter
-    this.#contract = contract
-    this.#source = source
-
-    this.depends(transmitter)
-  }
-
-  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
-
-    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
-    request.authentic = true
-
-    const context = current()
-
-    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.error !== undefined) return new RemoteError(reply.error)
-      else return reply.output
-    }
-  }
-
-  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 {
-  public constructor(error: object) {
-    super()
-
-    Object.assign(this, error)
-  }
-}

package/source/cascade.ts

@@ -1,32 +0,0 @@
-import { Connector } from './connector.js'
-import type { Algorithm } from './types/bridges.js'
-
-export class Cascade extends Connector {
-  readonly #last: Algorithm
-
-  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)
-  }
-
-  public async run(...args: [any, any?]): Promise<any> {
-    // const reply = {}
-    //
-    // for (const bridge of this.#bridges) {
-    //   const partial = await bridge.execute(...args)
-    //
-    //   if (partial.error) return { error: partial.error }
-    //
-    //   merge(reply, partial)
-    // }
-    //
-    // return reply
-
-    return this.#last.execute(...args)
-  }
-}

package/source/component.ts

@@ -1,83 +0,0 @@
-import assert from 'node:assert'
-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'
-
-/** 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 readonly operations: Record<string, O>
-
-  protected kind: 'server' | 'client' = 'server'
-
-  /** span options per endpoint */
-  readonly #spans: Record<string, SpanOptions> = {}
-
-  public constructor(locator: Locator, operations: Record<string, O>) {
-    super()
-
-    this.locator = locator
-    this.operations = operations
-
-    Object.values(operations).forEach((operation) => this.depends(operation))
-  }
-
-  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 = async (): Promise<any> => this.#process(endpoint, request)
-
-    if (remote === null) return task()
-    else return run(remote, task)
-  }
-
-  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) {
-        const span = current()
-
-        if (span !== undefined) span.status = 'error'
-
-        console.error('Failed to execute operation', {
-          endpoint: `${this.locator.id}.${endpoint}`,
-          exception: reply.exception
-        })
-      }
-
-      return reply
-    })
-  }
-
-  /**
-   * 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.
-   *
-   */
-  #span(endpoint: string): SpanOptions {
-    let options = this.#spans[endpoint]
-
-    if (options === undefined) {
-      options = { name: `${this.locator.id}.${endpoint}`, kind: this.kind }
-
-      // 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
-
-      this.#spans[endpoint] = options
-    }
-
-    return options
-  }
-}

package/source/composition.ts

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

package/source/connector.ts

@@ -1,217 +0,0 @@
-import { console } from 'openspan'
-import { environment } from '@toa.io/generic'
-import type { Locator } from './locator.js'
-
-/** Abstract connections hierarchy */
-export class Connector {
-  #dependencies: Connector[] = []
-  #links: Connector[] = []
-  #connecting: Promise<void> | undefined
-  #disconnecting: Promise<void> | undefined
-  #discarded: boolean = false
-
-  public readonly id: string
-  public connected: boolean = false
-
-  public constructor() {
-    this.id = this.constructor.name + '#' + Math.random().toString(36).substring(2, 8)
-  }
-
-  /**
-   * Creates a dependency and backlink with another Connector or a set of Connectors
-   *
-   * See .connect() and .disconnect()
-   *
-   */
-  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')
-
-      if (connector.length > 1) {
-        next = new Connector()
-
-        for (const item of connector) {
-          this.#dependencies.push(item)
-          item.depends(next)
-        }
-      } else next = connector[0]
-    } else next = connector
-
-    this.#dependencies.push(next)
-    next.link(this)
-
-    // See .#discard()
-    if (this.#disconnecting !== undefined) next.#discard()
-
-    return next
-  }
-
-  /**
-   * Disconnects, now and again if a connection is still to land.
-   *
-   * A dependency taken on after its dependant was disconnected — a lookup that returns
-   * once the teardown walk has gone by — is one nothing is left to take down, as the
-   * walk that would have reached it is over. One that stays connected holds open
-   * everything it depends on with it: a dependency reads `connected` of every dependant
-   * before it closes, and a dependant that is connected for good is a dependency that
-   * never closes.
-   */
-  #discard(): void {
-    this.#discarded = true
-
-    // one that is up already, or on its way, is taken down here; one that is not is
-    // taken down by the connection when it comes, and until then there is nothing to do
-    if (this.#connecting !== undefined) void this.#drop()
-  }
-
-  /**
-   * Creates a backlink to another Connector
-   *
-   * See .connect() and .disconnect()
-   *
-   */
-  public link(connector: Connector): void {
-    this.#links.push(connector)
-  }
-
-  /**
-   * Connects dependants then self
-   *
-   * In case of exception disconnects with current connection interruption
-   *
-   * Method is idempotent
-   *
-   */
-  public async connect(): Promise<void> {
-    if (this.#connecting) return this.#connecting
-
-    this.#disconnecting = undefined
-
-    const work = async () => {
-      await Promise.all(this.#dependencies.map((connector) => connector.connect()))
-      await this.open()
-    }
-
-    // anonymous grouping nodes are not worth a span
-    const 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()
-
-    this.#connecting = connecting
-
-    try {
-      await connecting
-
-      /*
-       * A disconnection that did not wait for this connection emptied `#connecting` to
-       * say so. Reporting `connected` now would report it of a connector nothing takes
-       * down again — its `#disconnecting` has settled, so a later call returns at once —
-       * and what it depends on reads that of every dependant before it closes.
-       */
-      if (this.#connecting === connecting) this.connected = true
-    } catch (e) {
-      await this.disconnect(true)
-      throw e
-    }
-
-    // a connection asked for before this one was discarded, landing after. See .#discard()
-    if (this.#discarded) await this.#drop()
-  }
-
-  /** Disconnects a discarded connector, saying so rather than throwing at whoever is not waiting. */
-  async #drop(): Promise<void> {
-    this.#discarded = false
-
-    try {
-      await this.disconnect()
-    } catch (error) {
-      console.error('Discarded connector failed to disconnect', { id: this.id, error })
-    }
-  }
-
-  /**
-   * Disconnects self then dependants
-   *
-   * Does nothing if there are connected linked Connectors
-   *
-   * Method is idempotent
-   *
-   */
-  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
-
-    if (!pending) await this.#connecting
-
-    if (this.#disconnecting) return this.#disconnecting
-
-    const linked = this.#links.reduce((acc, parent) => acc || parent.connected, false)
-
-    if (linked && interrupt !== true) return
-
-    this.#disconnecting = (async () => {
-      const start = +new Date()
-
-      const interval = setInterval(() => {
-        const delay = +new Date() - start
-
-        if (delay > DELAY)
-          console.warn(`Connector ${this.id} still disconnecting (${delay})`)
-      }, DELAY)
-
-      if (!pending) await this.close()
-
-      // said once the closing is done rather than when it starts: a dependant that is
-      // still closing is still using what it depends on, and the check above reads this
-      // of every dependant. Saying it early lets the first to start tear down a shared
-      // dependency under the others.
-      this.connected = false
-      this.#connecting = undefined
-
-      clearInterval(interval)
-
-      await Promise.all(this.#dependencies.map((connector) => connector.disconnect()))
-
-      await this.dispose()
-    })()
-
-    await this.#disconnecting
-  }
-
-  public async reconnect(): Promise<void> {
-    await this.disconnect()
-    await this.connect()
-  }
-
-  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])
-
-    return node
-  }
-
-  /** Called on connection */
-  protected open(): Promise<void> | void {}
-
-  /** Called on disconnection */
-  protected close(): Promise<void> | void {}
-
-  /** Called after self and dependants disconnection is complete */
-  protected dispose(): Promise<void> | void {}
-}
-
-const DELAY = 5000
-const TRACE_BOOT = environment.get('TOA_BOOT_TRACE') === '1'

package/source/context.ts

@@ -1,68 +0,0 @@
-import { Connector } from './connector.js'
-import { environment } from '@toa.io/generic'
-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 = environment.get('TOA_ENV')
-    this.name = environment.get('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

@@ -1,23 +0,0 @@
-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/source/contract/index.ts

@@ -1,2 +0,0 @@
-export { Request } from './request.js'
-export { Reply } from './reply.js'

package/source/contract/reply.ts

@@ -1,56 +0,0 @@
-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 {
-  public static override Exception: Refusal =
-    ResponseContractException as unknown as Refusal
-
-  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
-       * 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
-      else if (output.type === 'array' && output.items?.type === 'object')
-        output.items.additionalProperties = true
-
-      schema.properties.output = output
-    }
-
-    /*
-     * An error a caller is meant to handle is one the operation states. Where none are
-     * 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
-              },
-              message: {
-                type: 'string'
-              }
-            },
-            required: ['code']
-          }
-
-    return schema
-  }
-}