@toa.io/core 1.0.0-alpha.292 → 1.0.0-alpha.299

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
-  }
-}

package/source/contract/request.ts

@@ -1,140 +0,0 @@
-import * as schemas from './schemas.js'
-import { RequestContractException } from '../exceptions.js'
-import { Contract } from './contract.js'
-import type { Schema } from '@toa.io/schemas'
-import type { Refusal } from './contract.js'
-import type { JSONSchema } from './schemas.js'
-
-/** What an operation states about itself, and answers when asked to explain. */
-export interface Explanation {
-  description?: string
-  input?: JSONSchema | null
-  output?: JSONSchema | null
-  errors?: Array<string | number>
-}
-
-export interface Definition extends Explanation {
-  type?: string
-  scope?: string
-  query?: boolean
-}
-
-/** What the operation works on, as the manifest declares it. */
-export interface Entity {
-  properties: Record<string, JSONSchema>
-  required?: string[]
-}
-
-export class Request extends Contract {
-  public readonly discovery: Explanation = {}
-
-  public static override Exception: Refusal =
-    RequestContractException as unknown as Refusal
-
-  public constructor(schema: Schema, definition: Definition, entity?: Entity) {
-    super(schema)
-
-    for (const key of ['description', 'input', 'output', 'errors'] as const)
-      if (definition[key] !== undefined)
-        (this.discovery as Record<string, unknown>)[key] = definition[key]
-
-    /*
-     * An operation that states no output states an empty schema, which every reply fits —
-     * and which says nothing to whoever reads it. What its type answers does, so that is
-     * said here instead. Here and not in the definition, because the definition is what a
-     * reply is held to: a projection is a lawful answer, and describing one is not the same
-     * as requiring it.
-     */
-    if (empty(this.discovery.output)) {
-      const answered = answers(definition, entity)
-
-      if (answered !== undefined) this.discovery.output = answered
-    }
-  }
-
-  public static schema(
-    definition: Definition,
-    entity?: { properties: Record<string, JSONSchema> }
-  ): JSONSchema {
-    // `source` is not among these: the framework stamps it and whoever reads it takes the keys
-    // it knows, so holding it to a schema would only fail calls from a peer that stamps one more
-    const schema: JSONSchema = {
-      type: 'object',
-      properties: {
-        authentic: { type: 'boolean' },
-        task: { type: 'boolean' }
-      },
-      additionalProperties: true
-    }
-
-    const required: string[] = []
-
-    if (definition.input !== undefined) {
-      schema.properties.input = definition.input
-      required.push('input')
-    } else schema.properties.input = { type: 'null' }
-
-    if (entity === undefined) definition.query = false
-
-    if (definition.query === true) required.push('query')
-
-    if (definition.query === false) schema.properties.query = { type: 'null' }
-
-    if (definition.query !== false) {
-      const query = structuredClone(schemas.query)
-
-      query.properties.id = entity?.properties.id
-
-      if (definition.type === 'observation') delete query.properties.version
-      else delete query.properties.projection
-
-      if (definition.type !== 'observation' || definition.scope !== 'objects') {
-        delete query.properties.omit
-        delete query.properties.limit
-      } else if (query.required === undefined) query.required = ['limit']
-      else query.required.push('limit')
-
-      schema.properties.query = query
-    }
-
-    if (required.length > 0) schema.required = required
-
-    return schema
-  }
-}
-
-/**
- * What an operation of this type answers, where it did not say.
- *
- * A transition, an observation and an assignment work on the Entity Object, so that is what
- * they answer — a set of them where the scope is a set. A computation neither uses the scope
- * nor produces one, and an effect answers whatever it computed, so neither is guessed at.
- * A stream is not a value with a schema, and is not one either.
- *
- * What the entity requires is said as well. It is a description and nothing is held to it —
- * an operation answering a projection says so by declaring its own output — and a shape
- * whose every property reads as optional says less than it knows.
- */
-function answers(definition: Definition, entity?: Entity): JSONSchema | undefined {
-  if (entity === undefined || !ENTITY.has(definition.type as string)) return undefined
-
-  const object: JSONSchema = {
-    type: 'object',
-    properties: entity.properties,
-    ...(entity.required === undefined ? {} : { required: entity.required })
-  }
-
-  if (definition.scope === 'objects') return { type: 'array', items: object } as JSONSchema
-
-  return definition.scope === 'object' || definition.scope === 'changeset'
-    ? object
-    : undefined
-}
-
-/** The types whose subject is the Entity Object; see `documentation/design.md`. */
-const ENTITY = new Set(['transition', 'observation', 'assignment'])
-
-/** A schema that states nothing, which is what an operation saying nothing normalizes to. */
-function empty(schema: JSONSchema | null | undefined): boolean {
-  return schema === undefined || schema === null || Object.keys(schema).length === 0
-}

package/source/contract/schemas.ts

@@ -1,39 +0,0 @@
-/** A JSON Schema, loose because it is handed to a validator and edited by the contracts. */
-export type JSONSchema = Record<string, any>
-
-export const query: JSONSchema = {
-  type: 'object',
-  properties: {
-    id: { type: 'string' },
-    ids: { type: 'array', uniqueItems: true, minItems: 1, items: { type: 'string' } },
-    version: { type: 'integer', minimum: 0 },
-    criteria: { type: 'string' },
-    search: { type: 'string' },
-    sample: { type: 'number' },
-    omit: { type: 'integer', minimum: 0 },
-    limit: { type: 'integer', minimum: 0 },
-    sort: {
-      type: 'array',
-      uniqueItems: true,
-      minItems: 1,
-      items: { type: 'string', pattern: '^\\w{1,32}(?::(?:asc|desc))?$' }
-    },
-    projection: {
-      type: 'array',
-      uniqueItems: true,
-      minItems: 1,
-      items: { type: 'string', not: { const: 'id' } }
-    },
-    deleted: { type: 'boolean' }
-  },
-  additionalProperties: false
-}
-
-export const error: JSONSchema = {
-  type: 'object',
-  properties: {
-    code: { anyOf: [{ type: 'integer' }, { type: 'string' }] },
-    message: { type: 'string' }
-  },
-  required: ['code']
-}

package/source/discovery.ts

@@ -1,53 +0,0 @@
-import { console } from 'openspan'
-import { Connector } from './connector.js'
-import type { Locator } from './locator.js'
-
-interface Lookup extends Connector {
-  invoke: () => Promise<any>
-}
-
-export class Discovery extends Connector {
-  readonly #lookup: (locator: Locator) => Promise<Lookup>
-  #lookups: Record<string, Promise<Lookup>> = {}
-
-  public constructor(lookup: (locator: Locator) => Promise<Lookup>) {
-    super()
-
-    this.#lookup = lookup
-  }
-
-  protected override async open(): Promise<void> {
-    this.#lookups = {}
-  }
-
-  public async lookup(locator: Locator): Promise<any> {
-    const id = locator.id
-
-    if (this.#lookups[id] === undefined) {
-      const lookup = await this.#lookup(locator)
-
-      this.#lookups[id] = Promise.resolve(lookup)
-      this.depends(lookup)
-    }
-
-    const since = Date.now()
-
-    // the wait is unbounded by design, as a dependency may still be starting,
-    // so repeating is the only way a component stuck on one stays visible
-    const warning = setInterval(() => {
-      const waiting = Math.round((Date.now() - since) / 1000)
-
-      console.warn('Waiting for lookup response', { component: id, waiting })
-    }, INTERVAL)
-
-    warning.unref()
-
-    const output = await (await this.#lookups[id]).invoke()
-
-    clearInterval(warning)
-
-    return output
-  }
-}
-
-const INTERVAL = 5000

package/source/effect.ts

@@ -1,14 +0,0 @@
-import { Observation } from './observation.js'
-import type { Store } from './operation.js'
-import type { Entity } from './entities/entity.js'
-
-export class Effect extends Observation {
-  protected override async acquire(store: Store): Promise<void> {
-    const { query, entity, input } = store.request
-
-    if (entity === undefined) return super.acquire(store)
-
-    store.scope = await this.scope.ensure(query as any, entity, input)
-    store.state = (store.scope as Entity).get()
-  }
-}

package/source/emission.ts

@@ -1,21 +0,0 @@
-import { Connector } from './connector.js'
-import type { Event } from './event.js'
-import type { Event as StateEvent } from './types/state.js'
-
-export class Emission extends Connector {
-  readonly #events: Event[]
-
-  public constructor(events: Event[]) {
-    super()
-
-    this.#events = events
-
-    this.depends(events)
-  }
-
-  public async emit(event: StateEvent): Promise<void> {
-    const emission = this.#events.map((e) => e.emit(event))
-
-    await Promise.all(emission)
-  }
-}

package/source/entities/changeset.ts

@@ -1,37 +0,0 @@
-import { EntityContractException } from '../exceptions.js'
-import type { Schema } from '@toa.io/schemas'
-import type { Query, Record } from '../types/storages.js'
-
-export class Changeset {
-  public readonly query: Query
-
-  /** the changeset schema: the entity's properties, none of them required */
-  readonly #schema: Schema
-  #state: Record | object
-
-  public constructor(schema: Schema, query: Query) {
-    this.query = query
-
-    this.#schema = schema
-    this.#state = {}
-  }
-
-  public get(): object {
-    return this.#state
-  }
-
-  public set(value: Record): void {
-    const error = this.#schema.fit(value)
-
-    if (error !== null) throw new EntityContractException(error, value)
-
-    delete (value as Partial<Record>).VERSION
-    value.UPDATED = Date.now()
-
-    this.#state = value
-  }
-
-  public export(): object {
-    return this.#state
-  }
-}