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

package/source/types/extensions.ts

@@ -1,89 +0,0 @@
-import type { Connector } from '../connector.js'
-import type { Locator } from '../locator.js'
-import type { Component } from '../component.js'
-import type { Remote } from '../remote.js'
-import type { Receiver } from './receiver.js'
-import type { Context } from '../context.js'
-import type { Storage } from './storages.js'
-import type { Broadcast, Emitter } from './bindings.js'
-import type { Atom } from './atomicity.js'
-import type { Source } from './request.js'
-
-/**
- * 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: Locator, source?: Source): Promise<Remote>
-
-  /** a channel of the messaging binding */
-  broadcast<L extends string = string>(
-    channel: string,
-    group?: string
-  ): Promise<Broadcast<L>>
-
-  /** components to run inside the extension's own process */
-  composition(paths: string[]): Promise<Connector>
-
-  /** a consumer of an event of the context, `namespace.component.event` */
-  receive(label: string, receiver: Receiver): Promise<Connector>
-
-  /** what the replicas of one group decide together */
-  atom(group: string): Atom
-}
-
-/**
- * `Manifest` is a type parameter rather than an import: `@toa.io/norm` depends on core, so
- * core cannot name its types.
- */
-export interface Factory<Manifest = unknown> {
-  tenant?(
-    locator: Locator,
-    declaration: any,
-    manifest: Manifest
-  ): Connector | Promise<Connector>
-
-  aspect?(locator: Locator, declaration: any): Aspect | Aspect[]
-
-  /** what the extension runs as a process of its own; `null` where it is off here */
-  service?(): Connector | null | Promise<Connector | null>
-
-  component?(component: Component): Component
-
-  context?(context: Context): Context
-
-  manage?(composition: Connector): Connector
-
-  storage?(storage: Storage): Storage
-
-  emitter?(emitter: Emitter, label: string, locator: Locator): Emitter
-
-  receiver?(receiver: Receiver, locator: Locator): Receiver
-}
-
-export interface Aspect extends Connector {
-  /** the key it takes on the context; a duplicate is a boot error */
-  readonly name: string
-
-  invoke(...args: any[]): any
-}
-
-/**
- * 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
-}

package/source/types/index.ts

@@ -1,14 +0,0 @@
-export * as atomicity from './atomicity.js'
-export * as bindings from './bindings.js'
-export * as bridges from './bridges.js'
-export * as extensions from './extensions.js'
-export * as operations from './operations.js'
-export * as outbox from './outbox.js'
-export * as storages from './storages.js'
-
-export type { Contribution } from './extensions.js'
-export type { Event } from './state.js'
-export type { Message } from './message.js'
-export type { Receiver } from './receiver.js'
-export type { Call, Guard, Observation, Transition } from './operations.js'
-export type { Maybe, Query, Reply, RemoteError, Request, Source } from './request.js'

package/source/types/message.ts

@@ -1,5 +0,0 @@
-export interface Message<T = any> {
-  payload: T
-  /** W3C traceparent */
-  telemetry?: string
-}

package/source/types/operations.ts

@@ -1,31 +0,0 @@
-import type { Request } from './request.js'
-
-export type type =
-  | 'transition'
-  | 'observation'
-  | 'assignment'
-  | 'computation'
-  | 'effect'
-  | 'unmanaged'
-
-export type scope = 'object' | 'objects' | 'changeset' | 'stream' | 'none'
-
-/**
- * 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>
-
-/**
- * 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/source/types/outbox.ts

@@ -1,35 +0,0 @@
-import type { Event } from './state.js'
-
-/**
- * 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.
- */
-export 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
-
-  /** an assignment's images are absent until the storage fills them in */
-  event: Event
-}
-
-/**
- * The read side of an outbox. What writes a row is the storage's own: it happens inside the
- * transaction the storage opened, which core never reaches into.
- */
-export interface Storage {
-  /**
-   * 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>
-}

package/source/types/receiver.ts

@@ -1,10 +0,0 @@
-import type { Connector } from '../connector.js'
-import type { Message } from './message.js'
-
-/**
- * What consumes an event of the context. Core ships one, and an extension may put its own
- * in its place, so what a binding is handed is this rather than core's class.
- */
-export interface Receiver extends Connector {
-  receive(message: Message): Promise<void>
-}

package/source/types/request.ts

@@ -1,54 +0,0 @@
-import type { Exception } from '../exceptions.js'
-
-/**
- * What a call asks for. `Entity` is the record it is about, which narrows the projection;
- * left out, any name is accepted.
- */
-export interface Query<Entity = any> {
-  id?: string
-  ids?: string[]
-  criteria?: string
-  search?: string
-  sample?: number
-  omit?: number
-  limit?: number
-  sort?: string[]
-  projection?: Array<string & keyof Entity>
-  version?: number
-  deleted?: boolean
-}
-
-/** Origin of a call. Stamped by the framework; whoever reads it takes the keys it knows. */
-export type Source =
-  | { namespace: string; component: string; operation: string }
-  | { namespace: string; component: string; event: string }
-  | { service: string }
-
-export interface Request<Input = any, Entity = any> {
-  input?: Input
-  query?: Query<Entity>
-  /** What the operation acquires, where the caller supplies it rather than the storage. */
-  entity?: Entity
-  authentic?: boolean
-  task?: boolean
-  /** W3C traceparent */
-  telemetry?: string
-  source?: Source
-}
-
-/**
- * An error an operation declares and returns. A call resolves to it rather than throwing:
- * only an exception is thrown.
- */
-export interface RemoteError<Code extends string = string> extends Error {
-  code: Code
-}
-
-/** What an operation returns where it may refuse: the value, or the error it refused with. */
-export type Maybe<T> = T | Error
-
-export interface Reply {
-  output?: any
-  error?: object
-  exception?: Exception
-}

package/source/types/state.ts

@@ -1,9 +0,0 @@
-/** What a commit publishes: the images of one state change. */
-export interface Event<State = object, Trailers = object> {
-  /** the pre-image; null when the entity did not exist before */
-  origin: State | null
-  state: State
-  /** out-of-band values an algorithm wrote into `state._trailers`; must be serializable */
-  trailers?: Trailers
-  input?: object
-}

package/source/types/storages.ts

@@ -1,134 +0,0 @@
-import type { Readable } from 'node:stream'
-import type { Connector } from '../connector.js'
-import type { Locator } from '../locator.js'
-import type { Row, Storage as Outbox } from './outbox.js'
-
-/** the RSQL tree `@rsql/parser` produces; a storage translates it into its own dialect */
-export interface Node {
-  type: 'LOGIC' | 'COMPARISON' | 'SELECTOR' | 'VALUE'
-  left?: Node
-  right?: Node
-  operator?: string
-  selector?: string
-  value?: unknown
-}
-
-/** What a storage stores. `id` is the key; the upper-cased names are core's. */
-export interface Record {
-  id: string
-  VERSION: number
-  CREATED?: number
-  UPDATED?: number
-  /** a tombstone's timestamp; `null` on a live record */
-  DELETED?: number | null
-  [key: string]: any
-}
-
-/** Everything a request query carried that was not a selector. */
-export interface Options {
-  omit?: number
-  limit?: number
-  /** normalised by `query/options.ts` from `'name:asc'` into pairs */
-  sort?: Array<[property: string, direction: string]>
-  /** always includes `VERSION`, `CREATED`, `UPDATED`, `DELETED` */
-  projection?: string[]
-  sample?: number
-  /** include tombstones; without it an observation answers `null` over one */
-  deleted?: boolean
-}
-
-/** What core hands a storage, written by `Query.parse`. */
-export interface Query {
-  id?: string
-  /** many identities at once; `State.objects` inits whichever of them are missing */
-  ids?: string[]
-  version?: number
-  criteria?: Node
-  search?: string
-  options?: Options
-}
-
-/**
- * What core requires of a storage. Every member but `outbox` is called unguarded, so a
- * storage that leaves one out throws where an operation needs it — a storage may serve
- * only some scopes, and says so by failing rather than by declaring less.
- */
-export interface Storage extends Connector {
-  /** scope `object` */
-  get(query: Query): Promise<Record | null>
-
-  /** scope `objects` */
-  find(query: Query): Promise<Record[]>
-
-  /** scope `stream` */
-  stream(query?: Query): Promise<Readable>
-
-  /**
-   * A transition's commit. `false` is a lost compare-and-swap, not an error. Where `row` is
-   * given, it is committed in the same transaction as the record or not at all.
-   */
-  store(record: Record, row?: Row): Promise<boolean>
-
-  /** a transition over `objects` */
-  massStore(records: Record[], rows?: Row[]): Promise<boolean>
-
-  /** an assignment; `null` where the query matched nothing */
-  upsert(query: Query, changeset: object, row?: Row): Promise<Record | null>
-
-  /** get-or-create, in one indivisible step */
-  ensure(
-    query: Query | undefined,
-    properties: object,
-    record: Record,
-    row?: Row
-  ): Promise<Record>
-
-  /** the driver's own handle, which an unmanaged operation is given as its state */
-  readonly raw: unknown
-
-  /**
-   * Present only where a row can be committed atomically with the entity. Its absence is
-   * what makes the runtime publish inline, so a storage that cannot do this must not offer
-   * it: a row written outside the transaction would be a second write with a crash window
-   * in front of it, which is the defect the outbox exists to close.
-   */
-  readonly outbox?: Outbox
-
-  /**
-   * Whether this storage applies `entity.migrations`. Absent is what a storage that does not
-   * says, and a component declaring migrations against one is refused at boot rather than
-   * starting with a structure nothing has made.
-   */
-  readonly migrates?: boolean
-}
-
-/**
- * The subset of a component's entity declaration a storage reads. Structural, so that core
- * names no type of `@toa.io/norm`, which depends on core.
- */
-export interface Entity {
-  associated?: boolean
-  custom?: boolean
-  /** in the order they are applied; what a step is belongs to the storage that reads it */
-  migrations?: Migration[]
-}
-
-/**
- * One file of a `migrations` directory, named after it — the component's own, or a prototype's,
- * which every descendant applies to its collection ahead of its own.
- */
-export interface Migration {
-  id: string
-  steps: unknown[]
-  /** the prototype it is inherited from; absent on the component's own */
-  prototype?: string
-}
-
-export interface StorageOptions {
-  /** whether the component publishes anything, and so needs a place to commit a row */
-  outbox?: boolean
-}
-
-export interface Factory {
-  storage(locator: Locator, entity: Entity, options?: StorageOptions): Storage
-}

package/source/unmanaged.ts

@@ -1,8 +0,0 @@
-import { Operation } from './operation.js'
-import type { Store } from './operation.js'
-
-export class Unmanaged extends Operation {
-  protected override async acquire(store: Store): Promise<void> {
-    store.state = this.scope.storage.raw
-  }
-}

package/test/call.fixtures.js

@@ -1,25 +0,0 @@
-import { mock } from 'node:test'
-
-import { generate } from 'randomstring'
-
-// noinspection JSCheckFunctionSignatures
-export const transmission = {
-  request: mock.fn((request) => ({
-    [request.invalid ? 'exception' : 'output']: generate()
-  })),
-  link: mock.fn()
-}
-
-export const contract = {
-  fit: mock.fn(() => null)
-}
-
-export const request = () => ({
-  ok: {
-    input: { [generate()]: generate() },
-    query: { [generate()]: generate() }
-  },
-  bad: {
-    invalid: true
-  }
-})

package/test/call.test.js

@@ -1,79 +0,0 @@
-import { it, beforeEach } from 'node:test'
-import assert from 'node:assert/strict'
-import { isDeepStrictEqual } from 'node:util'
-
-import * as fixtures from './call.fixtures.js'
-import { Call } from '../source/call.js'
-
-let call
-
-beforeEach(() => {
-  resetCalls()
-
-  call = new Call(fixtures.transmission, fixtures.contract)
-})
-
-it('should depend on transmission', () => {
-  assert.ok(
-    ((invocation) =>
-      invocation.arguments.length === 1 &&
-      isDeepStrictEqual(invocation.arguments[0], call))(
-      fixtures.transmission.link.mock.calls.at(-1) ?? { arguments: [] }
-    )
-  )
-})
-
-it('should call transmission', async () => {
-  const request = fixtures.request().ok
-
-  await call.invoke(request)
-
-  assert.ok(
-    fixtures.transmission.request.mock.calls.some(
-      (invocation) =>
-        invocation.arguments.length === 1 &&
-        isDeepStrictEqual(invocation.arguments[0], request)
-    )
-  )
-})
-
-it('should fit request', async () => {
-  const request = fixtures.request().ok
-
-  await call.invoke(request)
-
-  assert.ok(
-    ((invocation) =>
-      invocation.arguments.length === 1 &&
-      isDeepStrictEqual(invocation.arguments[0], request))(
-      fixtures.contract.fit.mock.calls.at(-1) ?? { arguments: [] }
-    )
-  )
-})
-
-it('should return reply', async () => {
-  const request = fixtures.request().ok
-
-  const reply = await call.invoke(request)
-
-  assert.deepStrictEqual(reply, fixtures.transmission.request.mock.calls[0].result.output)
-})
-
-it('should throw received exceptions', async () => {
-  const request = fixtures.request().bad
-
-  await assert.rejects(call.invoke(request), (error) => {
-    assert.notStrictEqual(error, undefined)
-    return true
-  })
-})
-
-function resetCalls(target = [assert, fixtures], seen = new Set()) {
-  if (target === null || typeof target !== 'object' || seen.has(target)) return
-
-  seen.add(target)
-
-  for (const value of Object.values(target))
-    if (typeof value === 'function' && value.mock !== undefined) value.mock.resetCalls()
-    else resetCalls(value, seen)
-}

package/test/component.fixtures.js

@@ -1,18 +0,0 @@
-import { mock } from 'node:test'
-
-import randomstring from 'randomstring'
-
-const invocation = () => mock.fn(() => randomstring.generate())
-
-export const invocations = {
-  foo: {
-    invoke: invocation('foo'),
-    link: () => null
-  },
-  bar: {
-    invoke: invocation('bar'),
-    link: () => null
-  }
-}
-
-export const locator = {}

package/test/component.test.js

@@ -1,57 +0,0 @@
-import { describe, it, beforeEach } from 'node:test'
-import assert from 'node:assert/strict'
-import { isDeepStrictEqual } from 'node:util'
-
-import { Component } from '../source/component.js'
-import * as fixtures from './component.fixtures.js'
-import { AssertionError } from 'node:assert'
-
-describe('Invocations', () => {
-  const name = ['foo', 'bar'][Math.floor(2 * Math.random())]
-  const invocation = fixtures.invocations[name]
-  const component = new Component(fixtures.locator, fixtures.invocations)
-
-  beforeEach(() => {
-    resetCalls()
-  })
-
-  it('should invoke', async () => {
-    await component.invoke(name)
-
-    assert.ok(invocation.invoke.mock.callCount() > 0)
-  })
-
-  it('should throw on unknown invocation name', async () => {
-    await assert.rejects(() => component.invoke('baz'), AssertionError)
-  })
-
-  it('should invoke input and query', async () => {
-    const input = { test: Math.random() }
-    const query = { test: Math.random() }
-    await component.invoke(name, { input, query })
-
-    assert.ok(
-      invocation.invoke.mock.calls.some(
-        (call) =>
-          call.arguments.length === 1 &&
-          isDeepStrictEqual(call.arguments[0], { input, query })
-      )
-    )
-  })
-
-  it('should return io', async () => {
-    const io = await component.invoke(name)
-
-    assert.strictEqual(io, fixtures.invocations[name].invoke.mock.calls[0].result)
-  })
-})
-
-function resetCalls(target = [assert, fixtures], seen = new Set()) {
-  if (target === null || typeof target !== 'object' || seen.has(target)) return
-
-  seen.add(target)
-
-  for (const value of Object.values(target))
-    if (typeof value === 'function' && value.mock !== undefined) value.mock.resetCalls()
-    else resetCalls(value, seen)
-}

package/test/connector.fixtures.js

@@ -1,56 +0,0 @@
-import { random, timeout } from '@toa.io/generic'
-import { Connector } from '../source/connector.js'
-
-export class TestConnector extends Connector {
-  #label
-  #seq
-
-  constructor(label, seq) {
-    super()
-
-    this.#seq = seq
-    this.#label = label
-  }
-
-  async open() {
-    await timeout(random(10))
-    this.#seq.push(`+${this.#label}`)
-  }
-
-  async close() {
-    await timeout(random(10))
-    this.#seq.push(`-${this.#label}`)
-  }
-
-  async dispose() {
-    this.#seq.push(`*${this.#label}`)
-  }
-}
-
-export class FailingConnector extends Connector {
-  async open() {
-    await timeout(random(10))
-    throw new Error('FailingConnector')
-  }
-}
-
-/** Stands for a connector whose connection lands once it has been disconnected. */
-export class LateConnector extends Connector {
-  #arrive
-
-  async open() {
-    await new Promise((resolve) => (this.#arrive = resolve))
-  }
-
-  /** Lets the connection land. */
-  arrive() {
-    this.#arrive()
-  }
-}
-
-/** Stands for a connector waiting for something that never arrives. */
-export class StuckConnector extends Connector {
-  async open() {
-    return new Promise(() => undefined)
-  }
-}