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

package/src/reflection.js

@@ -1,24 +0,0 @@
-import { Connector } from './connector.js'
-
-/**
- * @implements {toa.core.Reflection}
- */
-export class Reflection extends Connector {
-  /** @type {toa.core.reflection.Source} */
-  #source
-
-  value
-
-  /**
-   * @param {toa.core.reflection.Source} source
-   */
-  constructor (source) {
-    super()
-
-    this.#source = source
-  }
-
-  async open () {
-    this.value = await this.#source()
-  }
-}

package/src/remote.js

@@ -1,14 +0,0 @@
-import assert from 'node:assert'
-import { Component } from './component.js'
-
-export class Remote extends Component {
-  kind = 'client'
-
-  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}'`)
-
-    return this.operations[endpoint].explain()
-  }
-}

package/src/state.js

@@ -1,138 +0,0 @@
-import { StatePreconditionException, StateNotFoundException } from './exceptions.js'
-
-export class State {
-  storage
-
-  #associated
-  #entities
-  #outbox
-
-  constructor (storage, entity, outbox, associated) {
-    this.storage = storage
-    this.#entities = entity
-    this.#outbox = outbox
-    this.#associated = associated === true
-  }
-
-  init (id) {
-    return this.#entities.init(id)
-  }
-
-  fit (values) {
-    return this.#entities.fit(values)
-  }
-
-  async object (query, mutable = true) {
-    const record = await this.storage.get(query)
-
-    if (record === null) {
-      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()
-
-      return null
-    } else
-      return this.#entities.object(record, mutable)
-  }
-
-  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)
-  }
-
-  async stream (query) {
-    return this.storage.stream(query)
-  }
-
-  changeset (query) {
-    return this.#entities.changeset(query)
-  }
-
-  none () {
-    return null
-  }
-
-  async ensure (query, properties, input) {
-    const object = this.#entities.init()
-    const blank = object.get()
-
-    Object.assign(blank, properties)
-
-    object.set(blank)
-
-    const row = this.#outbox?.row(object.event(input))
-    const record = await this.storage.ensure(query, properties, object.get(), row)
-
-    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, input) {
-    const changeset = state.export()
-
-    // 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) {
-        throw new StatePreconditionException()
-      } else {
-        throw new StateNotFoundException()
-      }
-    } 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
-  }
-}
-
-/** an effect never commits what `ensure` hands it, see `Effect` */
-const NOT_MUTABLE = false

package/src/transition.js

@@ -1,61 +0,0 @@
-import { retry } from '@toa.io/generic'
-import { Operation } from './operation.js'
-import { StateConcurrencyException, StateNotFoundException } from './exceptions.js'
-
-export class Transition extends Operation {
-  /** a transition is the only operation that commits */
-  mutable = true
-
-  #concurrency
-
-  constructor (cascade, scope, contract, query, definition) {
-    super(cascade, scope, contract, query, definition)
-
-    this.#concurrency = definition.concurrency
-  }
-
-  async process (store) {
-    return retry((retry) => this.#retry(store, retry), RETRY)
-  }
-
-  async acquire (store) {
-    const { request } = store
-
-    store.scope = request.query ? await this.query(request.query) : this.scope.init()
-
-    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
-
-    if (reply.error !== undefined) return
-
-    scope.set(state)
-
-    const result = await this.scope.commit(scope, store.request.input)
-
-    if (result === false) {
-      if (this.#concurrency === 'retry')
-        return retry()
-      else
-        throw new StateConcurrencyException()
-    }
-  }
-
-  async #retry (store, retry) {
-    store.retry = retry
-
-    return super.process(store)
-  }
-}
-
-const RETRY = {
-  base: 10,
-  max: 5000,
-  dispersion: 1,
-  retries: 32
-}

package/src/unmanaged.js

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

package/types/atomicity.d.ts

@@ -1,58 +0,0 @@
-// noinspection ES6UnusedImports
-
-import { Connector } from './connector.js'
-
-declare namespace toa.core {
-
-  namespace atomicity {
-
-    /**
-     * What one group of replicas decides together, in one place. The decisions here are the
-     * ones processes cannot arrange by talking to each other: they need a single arbiter and a
-     * step indivisible from its point of view.
-     */
-    interface Atom extends Connector {
-      /**
-       * An exclusive claim on slots of `0..total`: while this replica holds one, no other
-       * replica of the group does. Answered from memory, so it costs nothing to ask.
-       *
-       * `null` while this replica owns nothing — after a restart, during a rollout, or while
-       * coordination is unreachable. Whoever asks must be able to stand down: acting on a
-       * claim that cannot be supported is a different guarantee, not a degraded one.
-       */
-      slots (total: number): number[] | null
-
-      /**
-       * Debt the group has run up under each key, in milliseconds. Every call adds its own
-       * deltas and reads back where the group stands, so a replica reports what it alone has
-       * spent and still decides on what all of them have.
-       *
-       * Rejects where there is nothing to arbitrate through.
-       */
-      meter (keys: string[], deltas: number[]): Promise<number[]>
-
-      /**
-       * Runs `routine` holding `keys`, and while it holds them no other replica of the group
-       * does. Waits for as long as it takes to acquire them.
-       *
-       * The lease is extended for as long as the routine runs. An extension that fails aborts
-       * the signal the routine is given, which is the only way it learns it no longer holds
-       * what it is working under.
-       *
-       * Rejects where there is nothing to arbitrate through.
-       */
-      lock<T> (keys: string | string[],
-        routine: (signal: AbortSignal, context: unknown) => Promise<T>): Promise<T>
-    }
-
-    interface Factory {
-      /** @param group what the replicas deciding together have in common */
-      atom (group: string, options?: object): Atom
-    }
-
-  }
-
-}
-
-export type Atom = toa.core.atomicity.Atom
-export type Factory = toa.core.atomicity.Factory

package/types/bindings.d.ts

@@ -1,42 +0,0 @@
-import * as _core from './index.js'
-
-declare namespace toa.core.bindings {
-
-  type Properties = {
-    async?: boolean
-  }
-
-  interface Consumer extends _core.Connector {
-    request (request: Request): Promise<_core.Reply>
-
-    task (request: Request): Promise<void>
-  }
-
-  interface Emitter extends _core.Connector {
-    emit (message: _core.Message): Promise<void>
-  }
-
-  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 {
-    producer? (locator: _core.Locator, endpoints: Array<string>, producer: _core.Component): _core.Connector
-
-    consumer? (locator: _core.Locator, endpoint: string): Consumer
-
-    emitter? (locator: _core.Locator, label: string): Emitter
-
-    receiver? (locator: _core.Locator, label: string, group: string, receiver: _core.Receiver): _core.Connector
-
-    broadcast? (name: string, group?: string): Broadcast
-  }
-
-}
-
-export type Emitter = toa.core.bindings.Emitter
-export type Factory = toa.core.bindings.Factory
-export type Properties = toa.core.bindings.Properties
-export type Broadcast<L = any> = toa.core.bindings.Broadcast<L>

package/types/bridges.ts

@@ -1,33 +0,0 @@
-import type { Request, Reply } from './request.js'
-import type { Context } from './context.js'
-import type { Connector } from './connector.js'
-
-export interface Algorithm {
-  mount: (context?: Context) => Promise<void>
-
-  execute: ((input: any, scope: object | object[]) => Promise<Reply>) |
-  ((input: any) => Promise<Reply>) |
-  (() => Promise<Reply>)
-}
-
-export interface Event {
-  condition: (object: object) => Promise<boolean>
-
-  payload: (object: object) => Promise<object>
-}
-
-export interface Receiver {
-  condition: (object: object) => Promise<boolean>
-
-  request: (object: object) => Promise<Request>
-}
-
-export interface Factory {
-  algorithm?: (path: string, name: string, context: Context) => Algorithm
-
-  event?: (path: string, label: string) => Event
-
-  receiver?: (path: string, label: string) => Receiver
-
-  rc?: (path: string, context: Context) => Promise<{ preflight?: Connector, settle?: Connector, dispose?: Connector } | undefined>
-}

package/types/call.d.ts

@@ -1,13 +0,0 @@
-import type { Request } from './request.js'
-
-/**
- * How an endpoint is called. What it resolves to is what the operation declares — `toa types`
- * writes that per operation, and these are what a hand-written context says instead.
- */
-export type Call<Output = any, Input = any> = (request: Request<Input>) => Promise<Output>
-
-export type Observation<Output = any, Input = never, Entity = unknown> =
-  (request: Request<Input, Entity>) => Promise<Output extends unknown[] ? Output : Output | null>
-
-export type Transition<Output = any, Input = never, Entity = unknown> =
-  (request: Request<Input, Entity>) => Promise<Output | null>

package/types/component.d.ts

@@ -1,12 +0,0 @@
-import { Connector } from './connector.js'
-import { Locator } from './locator.js'
-import { Request } from './request.js'
-import { Operation } from './operations.js'
-
-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/connector.d.ts

@@ -1,18 +0,0 @@
-export class Connector {
-  public id: string
-  public connected: boolean
-
-  public connect (): Promise<void>
-
-  public disconnect (interrupt?: boolean): Promise<void>
-
-  public depends (connector: Connector | Connector[]): Connector
-
-  link (connector: Connector): void
-
-  protected open (): Promise<void> | void
-
-  protected close (): Promise<void> | void
-
-  protected dispose (): Promise<void> | void
-}

package/types/context.d.ts

@@ -1,24 +0,0 @@
-import * as _request from './request.js'
-import { Locator } from './locator.js'
-import * as _reply from './reply'
-import * as _extensions from './extensions.js'
-import * as _connector from './connector.js'
-
-export interface Context extends _connector.Connector{
-  aspects: _extensions.Aspect[]
-
-  locator: Locator
-
-  /**
-   * Calls local endpoint
-   */
-  apply (endpoint: string, request: _request.Request): Promise<_reply.Reply>
-
-  /**
-   * Calls remote endpoint
-   */
-  call (namespace: string, name: string, endpoint: string, request: _request.Request): Promise<_reply.Reply>
-
-  // shortcuts
-  [key: string]: any
-}

package/types/entity.d.ts

@@ -1,46 +0,0 @@
-import * as _event from './event.js'
-import * as _storages from './storages.js'
-
-declare namespace toa.core {
-
-  namespace entity {
-
-    interface Factory {
-      init(id: string): Entity
-
-      object(record: Object, mutable?: boolean): Entity
-
-      objects(recordset: Object[], init?: string[], mutable?: boolean): Entity[]
-
-      changeset(query: _storages.Query): Changeset
-    }
-
-  }
-
-  interface Entity {
-    get(): _storages.Record
-
-    set(value: _storages.Record): void
-
-    event(): _event.Event
-  }
-
-  type Upsert = {
-    changeset: Object
-    insert: Object
-  }
-
-  interface Changeset {
-    query: _storages.Query
-
-    get(): Object
-
-    set(value: Object): void
-
-    export(): Upsert
-  }
-
-}
-
-export type Entity = toa.core.Entity
-export type Changeset = toa.core.Changeset

package/types/event.d.ts

@@ -1,11 +0,0 @@
-import * as _state from './state.js'
-
-declare namespace toa.core {
-
-  interface Event {
-    emit(event: _state.Event): Promise<void>
-  }
-
-}
-
-export type Event = toa.core.Event

package/types/exception.d.ts

@@ -1,4 +0,0 @@
-export interface Exception {
-  code: number
-  message: string
-}

package/types/extensions.d.ts

@@ -1,73 +0,0 @@
-import * as _core from './index.js'
-import * as _component from './component.js'
-import * as _context from './context.js'
-import * as _storages from './storages.js'
-import * as _bindings from './bindings.js'
-import { Manifest } from '@toa.io/norm'
-
-/**
- * What the process hosting an extension provides to it: the counterpart of a component's
- * `Context`. What is returned is a connector the extension depends on.
- */
-export interface Host {
-  /** a component of the context, by locator */
-  remote (locator: _core.Locator, source?: _core.Source): Promise<_core.Remote>
-
-  /** a channel of the messaging binding */
-  broadcast<T = unknown> (channel: string, group?: string): Promise<_bindings.Broadcast<T>>
-
-  /** components to run inside the extension's own process */
-  composition (paths: string[]): Promise<_core.Connector>
-
-  /** a consumer of an event of the context, `namespace.component.event` */
-  receive (label: string, receiver: _core.Receiver): Promise<_core.Connector>
-
-  /** what the replicas of one group decide together */
-  atom (group: string): _core.atomicity.Atom
-}
-
-export interface Factory {
-  tenant? (locator: _core.Locator, manifest: object, component: Manifest):
-  _core.Connector | Promise<_core.Connector>
-
-  aspect? (locator: _core.Locator, manifest: object | null): Aspect | Aspect[]
-
-  service? (name?: string): _core.Connector | null | Promise<_core.Connector | null>
-
-  component? (component: _component.Component): _component.Component
-
-  context? (context: _context.Context): _context.Context
-
-  manage? (composition: _core.Connector): _core.Connector
-
-  storage? (storage: _storages.Storage): _storages.Storage
-
-  emitter? (emitter: _bindings.Emitter, label: string, locator: _core.Locator): _bindings.Emitter
-
-  receiver? (receiver: _core.Receiver, locator: _core.Locator): _core.Receiver
-}
-
-/**
- * What an extension puts on a component's context, as the extension states it. How it is
- * presented there is the bridge's — a bash bridge has no context to put anything on — and
- * what is declared here is the key and what it holds.
- */
-export interface Contribution {
-  /** the key on the context */
-  name: string
-
-  /** what the key holds, as TypeScript */
-  type?: string
-
-  /** what `type` names, by the module it comes from */
-  imports?: Record<string, string[]>
-
-  /** a JSON Schema to read the type from instead, where a component states one */
-  schema?: object
-}
-
-export interface Aspect extends _core.Connector {
-  name: string
-
-  invoke (...args: any[]): any
-}

package/types/guard.d.ts

@@ -1,5 +0,0 @@
-/**
- * Runs on every change to an entity's state, before the contract is applied. `false` refuses
- * the change as `EntityGuard`.
- */
-export type Guard<T, C = unknown> = (state: T, origin: T | null, context: C) => boolean

package/types/locator.d.ts

@@ -1,13 +0,0 @@
-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)
-
-  hostname (type?: string): string
-}

package/types/operations.d.ts

@@ -1,8 +0,0 @@
-import { Request } from './request.js'
-
-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/outbox.d.ts

@@ -1,53 +0,0 @@
-import * as _state from './state.js'
-import * as _atomicity from './atomicity.js'
-
-declare namespace toa.core {
-
-  namespace outbox {
-
-    /**
-     * The intent to publish, committed with the state change it belongs to. Everything about
-     * it is core's: the storage writes it and, where the images are the write's own, fills
-     * `event.origin` and `event.state` in.
-     */
-    interface Row {
-      id: string
-
-      /** which replica pumps this row; carries no other meaning, and no ordering */
-      lane: number
-
-      published: boolean
-
-      /** not before this */
-      pending: number
-
-      event: _state.Event
-    }
-
-    /** What a storage offers when it can commit a row atomically with the entity. */
-    interface Storage {
-      insert (row: Row, session?: unknown): Promise<void>
-
-      insertMany (rows: Row[], session?: unknown): Promise<void>
-
-      /**
-       * One page of what is due, still unpublished, and in one of the given lanes, in the
-       * order the rows were written. `after` continues from the last id of the page before.
-       */
-      pending (lanes: number[], now: number, limit: number, after?: string): Promise<Row[]>
-
-      settle (ids: string[]): Promise<void>
-    }
-
-  }
-
-}
-
-export type Row = toa.core.outbox.Row
-export type Storage = toa.core.outbox.Storage
-
-/**
- * A lane is a slot of `atomicity`: which replica pumps a row, and nothing else. The outbox is
- * the first thing to claim slots this way, not the last.
- */
-export type Atom = _atomicity.Atom