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

package/source/exceptions.ts

@@ -0,0 +1,133 @@
+import { swap } from '@toa.io/generic'
+import type { SchemaError } from '@toa.io/schemas'
+
+export const codes = {
+  System: 0,
+
+  Contract: 200,
+  RequestSyntax: 201,
+  RequestContract: 202,
+  RequestConflict: 203,
+  ResponseContract: 211,
+  EntityContract: 212,
+  EntityGuard: 213,
+  QuerySyntax: 221,
+
+  State: 300,
+  StateNotFound: 302,
+  StatePrecondition: 303,
+  StateConcurrency: 304,
+  StateInitialization: 305,
+  Duplicate: 306,
+
+  Communication: 400,
+  Transmission: 401
+}
+
+export class Exception {
+  public readonly code: number
+  public readonly message: string
+  public cause?: unknown;
+
+  /** what a contract exception copies off the schema error it refused with */
+  [key: string]: unknown
+
+  public constructor(code: number, message: string, cause?: unknown) {
+    this.code = code
+    this.message = message
+
+    if (cause !== undefined) this.cause = cause
+  }
+}
+
+export class SystemException extends Exception {
+  public readonly stack?: string
+
+  public constructor(error: Error | string) {
+    super(codes.System, typeof error === 'string' ? error : error.message)
+
+    if (typeof error !== 'string' && error.stack !== undefined) this.stack = error.stack
+  }
+}
+
+export class ContractException extends Exception {
+  public constructor(
+    code: number | undefined,
+    error: SchemaError | string | null,
+    cause?: unknown
+  ) {
+    super(
+      code ?? codes.Contract,
+      typeof error === 'string' ? error : (error?.message ?? ''),
+      cause
+    )
+
+    if (typeof error === 'object' && error !== null)
+      for (const k of ['keyword', 'property', 'schema', 'path', 'params'] as const)
+        if (k in error) this[k] = (error as unknown as Record<string, unknown>)[k]
+  }
+}
+
+export class RequestContractException extends ContractException {
+  public constructor(error: SchemaError | string, cause?: unknown) {
+    super(codes.RequestContract, error, cause)
+  }
+}
+
+export class ResponseContractException extends ContractException {
+  public constructor(error: SchemaError | string, cause?: unknown) {
+    super(codes.ResponseContract, error, cause)
+  }
+}
+
+export class EntityContractException extends ContractException {
+  public constructor(error: SchemaError | string, cause?: unknown) {
+    super(codes.EntityContract, error, cause)
+  }
+}
+
+export class EntityGuardException extends ContractException {
+  public constructor(name: string, cause?: unknown) {
+    super(codes.EntityGuard, name, cause)
+  }
+}
+
+// #region exports
+
+// a module's exports are static, so the ones that follow a code are named rather
+// than generated onto the namespace
+type Derived = new (message?: string, cause?: unknown) => Exception
+
+function derive(name: keyof typeof codes): Derived {
+  const classname = name + 'Exception'
+
+  const derived = class extends Exception {
+    public constructor(message?: string, cause?: unknown) {
+      super(
+        codes[name],
+        message === undefined ? classname : `${classname}: ${message}`,
+        cause
+      )
+    }
+  }
+
+  // the name is the class's own, and a class expression has none worth reporting
+  Object.defineProperty(derived, 'name', { value: classname })
+
+  return derived
+}
+
+export const RequestSyntaxException = derive('RequestSyntax')
+export const RequestConflictException = derive('RequestConflict')
+export const QuerySyntaxException = derive('QuerySyntax')
+export const StateException = derive('State')
+export const StateNotFoundException = derive('StateNotFound')
+export const StatePreconditionException = derive('StatePrecondition')
+export const StateConcurrencyException = derive('StateConcurrency')
+export const StateInitializationException = derive('StateInitialization')
+export const DuplicateException = derive('Duplicate')
+export const CommunicationException = derive('Communication')
+export const TransmissionException = derive('Transmission')
+
+export const names = swap(codes)
+// #endregion

package/source/exposition.ts

@@ -0,0 +1,33 @@
+import { Connector } from './connector.js'
+import type { Locator } from './locator.js'
+
+interface Manifest {
+  namespace: string
+  name: string
+  entity?: object
+  operations?: object
+  events?: object
+}
+
+export class Exposition extends Connector {
+  public readonly locator: Locator
+
+  readonly #exposition: Partial<Manifest>
+
+  public constructor(locator: Locator, manifest: Manifest) {
+    super()
+
+    this.locator = locator
+    this.#exposition = expose(manifest)
+  }
+
+  public async invoke(): Promise<{ output: Partial<Manifest> }> {
+    return { output: this.#exposition }
+  }
+}
+
+function expose(manifest: Manifest): Partial<Manifest> {
+  const { namespace, name, entity, operations, events } = manifest
+
+  return { namespace, name, entity, operations, events }
+}

package/source/guard.ts

@@ -0,0 +1,16 @@
+import type { Guard as Bridge } from './types/bridges.js'
+
+export class Guard {
+  public readonly name: string
+
+  readonly #bridge: Bridge
+
+  public constructor(name: string, bridge: Bridge) {
+    this.name = name
+    this.#bridge = bridge
+  }
+
+  public fit(state: object, origin: object | null): boolean {
+    return this.#bridge.fit(state, origin)
+  }
+}

package/source/index.ts

@@ -0,0 +1,36 @@
+export { Assignment } from './assignment.js'
+export { Call } from './call.js'
+export { Cascade } from './cascade.js'
+export { Component } from './component.js'
+export { Composition } from './composition.js'
+export { Connector } from './connector.js'
+export { Context } from './context.js'
+export { Discovery } from './discovery.js'
+export { Effect } from './effect.js'
+export { Emission } from './emission.js'
+export { Event } from './event.js'
+export { Exposition } from './exposition.js'
+export { Locator } from './locator.js'
+export { Observation } from './observation.js'
+export { Outbox } from './outbox/index.js'
+export { Operation } from './operation.js'
+export { Query } from './query.js'
+export { Receiver } from './receiver.js'
+export { Reflection } from './reflection.js'
+export { Remote } from './remote.js'
+export { State } from './state.js'
+export { Transition } from './transition.js'
+export { Transmission } from './transmission.js'
+export { Unmanaged } from './unmanaged.js'
+export { Guard } from './guard.js'
+export * as entities from './entities/index.js'
+export * as exceptions from './exceptions.js'
+export * as contract from './contract/index.js'
+
+export type { Exception } from './exceptions.js'
+export type { Invocable } from './component.js'
+export type { Explicable } from './remote.js'
+export type { Scoped, Store } from './operation.js'
+export type { Source as ReflectionSource } from './reflection.js'
+export type { Explanation } from './contract/request.js'
+export type { JSONSchema } from './contract/schemas.js'

package/source/locator.ts

@@ -0,0 +1,37 @@
+import { concat } from '@toa.io/generic'
+
+/** Where a component is, as every name derived from it. */
+export class Locator {
+  public readonly name: string
+  public readonly namespace: string | undefined
+
+  public readonly id: string
+  public readonly label: string
+  public readonly uppercase: string
+  public readonly lowercase: string
+
+  public constructor(name: string, namespace?: string) {
+    if (name === undefined) throw new TypeError('Locator name must be defined')
+
+    this.name = name
+    this.namespace = namespace
+
+    this.id = concat(namespace, '.') + name
+    this.label = (concat(namespace, '-') + name).toLowerCase()
+    this.uppercase = (concat(namespace, '_') + name).toUpperCase()
+    this.lowercase = (concat(namespace, '_') + name).toLowerCase()
+  }
+
+  public static parse(string: string): Locator {
+    const [namespace, name] = string.split(DOT)
+
+    if (name === undefined) return new Locator(namespace)
+    else return new Locator(name, namespace)
+  }
+
+  public hostname(prefix?: string): string {
+    return concat(prefix?.toLowerCase(), '-') + this.label
+  }
+}
+
+const DOT = '.'

package/source/observation.ts

@@ -0,0 +1,16 @@
+import { Operation } from './operation.js'
+import type { Store } from './operation.js'
+import type { Entity } from './entities/entity.js'
+
+export class Observation extends Operation {
+  protected override async run(store: Store): Promise<void> {
+    const scope = store.scope as Entity | null
+
+    if (
+      scope === null ||
+      (scope?.deleted === true && (store.request.query as any)?.options?.deleted !== true)
+    )
+      store.reply = null
+    else await super.run(store)
+  }
+}

package/source/operation.ts

@@ -0,0 +1,139 @@
+import { Readable } from 'node:stream'
+import { Connector } from './connector.js'
+import { SystemException, RequestContractException } from './exceptions.js'
+import { environment } from '@toa.io/generic'
+import type { Cascade } from './cascade.js'
+import type { State } from './state.js'
+import type { Query as Translator } from './query.js'
+import type { Contract } from './contract/contract.js'
+import type { Entity } from './entities/entity.js'
+import type { EntitySet } from './entities/set.js'
+import type { Changeset } from './entities/changeset.js'
+import type { scope as Scope } from './types/operations.js'
+import type { Query, Request } from './types/request.js'
+
+/** What an operation acquires for the algorithm to run against. */
+export type Scoped = Entity | EntitySet | Changeset | Readable | null
+
+/** What one invocation carries from step to step. */
+export interface Store {
+  request: Request
+  scope?: Scoped
+  state?: any
+  reply?: any
+  /** set by a transition, which is the only operation that runs its steps again */
+  retry?: () => Promise<any>
+}
+
+export interface Contracts {
+  request: Contract
+  reply: Contract
+}
+
+export interface Definition {
+  scope: Scope
+  concurrency?: string
+}
+
+export class Operation extends Connector {
+  public scope: State
+
+  /**
+   * Whether what this operation acquires may be modified and committed. Only a
+   * transition commits, and only a commit needs the pre-image an entity keeps
+   * to diff the new state against.
+   *
+   * @protected
+   */
+  protected mutable: boolean = false
+
+  readonly #cascade: Cascade
+  readonly #contracts: Contracts
+  readonly #query: Translator
+  readonly #scope: Scope
+
+  // eslint-disable-next-line max-params
+  public constructor(
+    cascade: Cascade,
+    scope: State,
+    contracts: Contracts,
+    query: Translator,
+    definition: Definition
+  ) {
+    super()
+
+    this.scope = scope
+
+    this.#cascade = cascade
+    this.#contracts = contracts
+    this.#query = query
+    this.#scope = definition.scope
+
+    this.depends(cascade)
+  }
+
+  public async invoke(request: Request): Promise<any> {
+    try {
+      if (request.authentic !== true) this.#contracts.request.fit(request)
+
+      // the request carries the query onward in its parsed form: what a storage is given,
+      // not what the caller sent
+      if ('query' in request)
+        request.query = this.#query.parse(request.query as Query) as any
+
+      // validate entity
+      if ('entity' in request) this.scope.fit(request.entity)
+
+      const store = { request }
+
+      return await this.process(store)
+    } catch (e) {
+      const exception = e instanceof Error ? new SystemException(e) : e
+
+      return { exception }
+    }
+  }
+
+  protected async process(store: Store): Promise<any> {
+    await this.acquire(store)
+    await this.run(store)
+    await this.commit(store)
+
+    return store.reply
+  }
+
+  protected async acquire(store: Store): Promise<void> {
+    if (this.#scope === 'none') return
+
+    const scope = await this.query(store.request.query)
+    const raw = scope === null || scope instanceof Readable
+
+    store.scope = scope
+    store.state = raw ? scope : (scope as Entity).get()
+  }
+
+  protected async run(store: Store): Promise<void> {
+    const { request, state } = store
+    const reply = await this.#cascade.run(request.input, state)
+
+    // validate reply only on local environments
+    if (environment.get('TOA_ENV') === 'local' && !(reply instanceof Readable))
+      this.#contracts.reply.fit(reply)
+
+    store.reply = reply
+  }
+
+  protected async commit(_store: Store): Promise<void> {}
+
+  protected async query(query?: Query): Promise<Scoped> {
+    if (query === undefined)
+      throw new RequestContractException('Request query is required')
+
+    const acquire = this.scope[this.#scope] as (
+      query: Query,
+      mutable?: boolean
+    ) => Promise<Scoped>
+
+    return acquire.call(this.scope, query, this.mutable)
+  }
+}

package/source/outbox/index.ts

@@ -0,0 +1 @@
+export { Outbox, LANES } from './outbox.js'