@toa.io/core 1.0.0-alpha.284 → 1.0.0-alpha.287

package/source/event.ts

@@ -0,0 +1,57 @@
+import { console, current, encode, type SpanOptions } from 'openspan'
+import { Connector } from './connector.js'
+import type { Emitter } from './types/bindings.js'
+import type { Event as Bridge } from './types/bridges.js'
+import type { Message } from './types/message.js'
+import type { Event as StateEvent } from './types/state.js'
+
+export interface Definition {
+  conditioned?: boolean
+  subjective?: boolean
+  label?: string
+}
+
+export class Event extends Connector {
+  readonly #emitter: Emitter
+  readonly #bridge: Bridge | undefined
+  readonly #conditioned: boolean | undefined
+  readonly #subjective: boolean | undefined
+  readonly #label: string
+
+  public constructor(definition: Definition, emitter: Emitter, bridge?: Bridge) {
+    super()
+
+    this.#conditioned = definition.conditioned
+    this.#subjective = definition.subjective
+    this.#label = definition.label ?? 'event'
+    this.#emitter = emitter
+    this.#bridge = bridge
+
+    this.depends(emitter)
+
+    if (bridge !== undefined) this.depends(bridge)
+  }
+
+  public async emit(event: StateEvent): Promise<void> {
+    if (this.#conditioned === false || (await this.#bridge?.condition(event)) === true) {
+      const payload =
+        this.#subjective === true ? await this.#bridge?.payload(event) : event.state
+
+      const message: Message = { payload }
+
+      const options: SpanOptions = {
+        name: `${this.#label} publish`,
+        kind: 'producer',
+        attributes: { 'messaging.destination.name': this.#label }
+      }
+
+      await console.span(options, async () => {
+        const context = current()
+
+        if (context !== undefined) message.telemetry = encode(context)
+
+        await this.#emitter.emit(message)
+      })
+    }
+  }
+}

package/{src/exceptions.js → source/exceptions.ts}

@@ -1,4 +1,5 @@
 import { swap } from '@toa.io/generic'
+import type { SchemaError } from '@toa.io/schemas'
 
 export const codes = {
   System: 0,
@@ -23,79 +24,97 @@ export const codes = {
   Transmission: 401
 }
 
-/**
- * @implements {toa.core.Exception}
- */
 export class Exception {
-  code
-  message
+  public readonly code: number
+  public readonly message: string
+  public cause?: unknown;
 
-  constructor (code, message, cause) {
+  /** 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
+    if (cause !== undefined) this.cause = cause
   }
 }
 
 export class SystemException extends Exception {
-  stack
+  public readonly stack?: string
 
-  constructor (error) {
-    super(codes.System, error.message)
+  public constructor(error: Error | string) {
+    super(codes.System, typeof error === 'string' ? error : error.message)
 
-    if (error.stack !== undefined) this.stack = error.stack
+    if (typeof error !== 'string' && error.stack !== undefined) this.stack = error.stack
   }
 }
 
 export class ContractException extends Exception {
-  constructor (code, error, cause) {
-    super(code || codes.Contract, typeof error === 'string' ? error : error?.message, cause)
+  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'])
-        if (k in error)
-          this[k] = error[k]
+      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 {
-  constructor (error, cause) { super(codes.RequestContract, error, cause) }
+  public constructor(error: SchemaError | string, cause?: unknown) {
+    super(codes.RequestContract, error, cause)
+  }
 }
 
 export class ResponseContractException extends ContractException {
-  constructor (error, cause) { super(codes.ResponseContract, error, cause) }
+  public constructor(error: SchemaError | string, cause?: unknown) {
+    super(codes.ResponseContract, error, cause)
+  }
 }
 
 export class EntityContractException extends ContractException {
-  constructor (error, cause) { super(codes.EntityContract, error, cause) }
+  public constructor(error: SchemaError | string, cause?: unknown) {
+    super(codes.EntityContract, error, cause)
+  }
 }
 
 export class EntityGuardException extends ContractException {
-  constructor (name, cause) { super(codes.EntityGuard, name, cause) }
+  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
-function derive (name) {
+type Derived = new (message?: string, cause?: unknown) => Exception
+
+function derive(name: keyof typeof codes): Derived {
   const classname = name + 'Exception'
 
-  return class extends Exception {
-    constructor (message, cause) {
-      super(codes[name], message ? `${classname}: ${message}` : classname, cause)
+  const derived = class extends Exception {
+    public constructor(message?: string, cause?: unknown) {
+      super(
+        codes[name],
+        message === undefined ? classname : `${classname}: ${message}`,
+        cause
+      )
     }
-
-    static name = classname
   }
+
+  // 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')

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/{src/index.js → source/index.ts}

@@ -26,3 +26,11 @@ 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/{src/locator.js → source/locator.ts}

@@ -1,22 +1,16 @@
 import { concat } from '@toa.io/generic'
 
-/**
- * @implements {toa.core.Locator}
- */
+/** Where a component is, as every name derived from it. */
 export class Locator {
-  name
-  namespace
-
-  id
-  label
-  uppercase
-  lowercase
-
-  /**
-   * @param {string} name
-   * @param {string} [namespace]
-   */
-  constructor (name, namespace) {
+  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
@@ -28,22 +22,15 @@ export class Locator {
     this.lowercase = (concat(namespace, '_') + name).toLowerCase()
   }
 
-  hostname (prefix) {
-    return concat(prefix?.toLowerCase(), '-') + this.label
-  }
-
-  /**
-   * @param {string} string
-   * @returns {Locator}
-   */
-  static parse (string) {
+  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)
-    }
+    if (name === undefined) return new Locator(namespace)
+    else return new Locator(name, namespace)
+  }
+
+  public hostname(prefix?: string): string {
+    return concat(prefix?.toLowerCase(), '-') + this.label
   }
 }
 

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,138 @@
+import { Readable } from 'node:stream'
+import { Connector } from './connector.js'
+import { SystemException, RequestContractException } from './exceptions.js'
+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 (process.env.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)
+  }
+}