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

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

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

@@ -1,6 +1,17 @@
 import { console } from 'openspan'
 import { Connector } from '../connector.js'
 import { newid } from '../entities/newid.js'
+import type { Emission } from '../emission.js'
+import type { Atom } from '../types/atomicity.js'
+import type { Storage } from '../types/storages.js'
+import type { Row } from '../types/outbox.js'
+import type { Event } from '../types/state.js'
+
+export interface Options {
+  interval?: number
+  batch?: number
+  gap?: number
+}
 
 /**
  * Owns the intent to publish. A row is built before the write so that the storage can commit
@@ -14,29 +25,36 @@ import { newid } from '../entities/newid.js'
  * inline emission it replaces.
  */
 export class Outbox extends Connector {
-  #emission
-  #storage
-  #atom
+  readonly #emission: Emission
+  readonly #storage: Storage | undefined
+  readonly #atom: Atom
 
-  #gap
-  #interval
-  #batch
-  #defer
+  readonly #gap: number
+  readonly #interval: number
+  readonly #batch: number
+  readonly #defer: boolean
 
   /** ids this process has published, held until a cycle marks them */
-  #published = new Set()
+  readonly #published = new Set<string>()
 
   /** in-flight publications, awaited (with a bound) on close */
-  #inflight = new Set()
+  readonly #inflight = new Set<Promise<void>>()
 
   /** rows this replica is publishing right now, so a cycle does not pick them up again */
-  #publishing = new Set()
+  readonly #publishing = new Set<string>()
 
-  #timer
+  #timer: NodeJS.Timeout | undefined
+  #off: (() => void) | undefined
   #pumping = false
   #closing = false
 
-  constructor (emission, storage, atom, options = {}) {
+  // eslint-disable-next-line max-params
+  public constructor(
+    emission: Emission,
+    storage: Storage | undefined,
+    atom: Atom,
+    options: Options = {}
+  ) {
     super()
 
     this.#emission = emission
@@ -55,21 +73,21 @@ export class Outbox extends Connector {
   }
 
   /** whether the storage can commit a row atomically with the entity */
-  get durable () {
+  public get durable(): boolean {
     return this.#storage?.outbox !== undefined
   }
 
   /**
-   * @param event {toa.core.transition.Event}
-   * @returns {object}
+   * An assignment's images are the write's own, so it hands over an event with neither, and
+   * the storage fills them in.
    */
-  row (event) {
+  public row(event: Partial<Event>): Row {
     return {
       id: newid(),
       lane: this.#lane(),
       published: false,
       pending: Date.now() + this.#gap,
-      event
+      event: event as Event
     }
   }
 
@@ -77,35 +95,54 @@ export class Outbox extends Connector {
    * Hands a committed row over. Awaited by the caller only on the legacy path — with an
    * outbox this returns at once and the broker leaves the operation's path.
    */
-  publish (row) {
-    if (!this.durable)
-      return this.#emission.emit(row.event)
+  public publish(row: Row): Promise<void> | void {
+    // without a durable outbox this is the inline path, and the caller awaits the emission
+    if (!this.durable) return this.#emission.emit(row.event)
 
     /*
      * A publication started while the pump is closing would outlive the emitters it needs,
      * and `comq` waits on a connection that is going rather than failing. The row is already
      * durable, so leaving it is exactly what it is for.
      */
-    if (this.#closing || this.#defer ||
-      this.#inflight.size >= INFLIGHT || this.#published.size >= PUBLISHED)
+    if (
+      this.#closing ||
+      this.#defer ||
+      this.#inflight.size >= INFLIGHT ||
+      this.#published.size >= PUBLISHED
+    )
       return
 
     void this.#publish(row)
   }
 
-  async open () {
+  protected override async open(): Promise<void> {
     if (!this.durable) return
 
     if (this.#defer)
-      console.warn('Outbox immediate publication is deferred; events are published by the pump only')
+      console.warn(
+        'Outbox immediate publication is deferred; events are published by the pump only'
+      )
 
-    this.#timer = setInterval(() => this.#tick(), this.#interval)
+    this.#timer = setInterval(() => {
+      this.#tick()
+    }, this.#interval)
     this.#timer.unref()
+
+    /*
+     * A lane changing hands is exactly when rows stranded in it become this replica's to
+     * publish, and the cycle would not notice for up to an interval. Being told costs a cycle
+     * that finds nothing in the usual case, where the claim arrives once and never changes.
+     */
+    this.#off = this.#atom.onassigned(() => {
+      this.#tick()
+    })
   }
 
-  async close () {
+  protected override async close(): Promise<void> {
     this.#closing = true
 
+    this.#off?.()
+
     if (this.#timer !== undefined) clearInterval(this.#timer)
 
     await this.#drain()
@@ -121,9 +158,8 @@ export class Outbox extends Connector {
    * it would not stop it, it would only mean the row is published twice once it lands. What
    * bounds this instead is the in-flight cap and the drain on close.
    *
-   * @private
    */
-  async #publish (row) {
+  async #publish(row: Row): Promise<void> {
     this.#publishing.add(row.id)
 
     const publishing = this.#emission.emit(row.event)
@@ -146,9 +182,8 @@ export class Outbox extends Connector {
    * `comq` retries a publish for as long as the broker is down rather than rejecting, so an
    * unbounded drain outlives any grace period.
    *
-   * @private
    */
-  async #drain () {
+  async #drain(): Promise<void> {
     if (this.#inflight.size === 0) return
 
     await Promise.race([Promise.allSettled([...this.#inflight]), delay(DRAIN)])
@@ -158,9 +193,8 @@ export class Outbox extends Connector {
    * Reads what is due, publishes it, and marks everything this process has sent — what it just
    * published and what the immediate path published since the last cycle. One cycle at a time.
    *
-   * @private
    */
-  #tick () {
+  #tick(): void {
     if (this.#pumping) return
 
     this.#pumping = true
@@ -168,29 +202,33 @@ export class Outbox extends Connector {
     void this.#pump().finally(() => (this.#pumping = false))
   }
 
-  /** @private */
-  async #pump () {
-    let page
+  async #pump(): Promise<void> {
+    let page: Row[]
+    let after: string | undefined
 
     do {
-      page = await this.#read(page?.[page.length - 1]?.id)
+      page = await this.#read(after)
 
       if (page.length === 0) break
 
+      // so a page is never read twice
+      after = page[page.length - 1]?.id
+
       /*
        * A row is unpublished in the database until a cycle marks it, so a page includes what
        * this replica is sending right now and what a failed marking left behind. Only this
        * process knows either.
        */
-      const rows = page.filter((row) =>
-        !this.#published.has(row.id) && !this.#publishing.has(row.id))
+      const rows = page.filter(
+        (row) => !this.#published.has(row.id) && !this.#publishing.has(row.id)
+      )
 
       if (rows.length > 0) {
         console.info('Outbox recovering unpublished events', { count: rows.length })
 
         // every row is given its chance; what the broker refused stays unpublished and comes
         // back on a later cycle
-        await Promise.allSettled(rows.map((row) => this.#publish(row)))
+        await Promise.allSettled(rows.map(async (row) => this.#publish(row)))
       }
 
       // a full page is a page that may have been cut short
@@ -208,15 +246,15 @@ export class Outbox extends Connector {
    * assignment arrives. Reading without an assignment would be a different guarantee, where
    * every replica publishes every stranded row.
    *
-   * @private
-   * @param {string} [after] the last id of the page before, so a page is never read twice
+   * @param after the last id of the page before, so a page is never read twice
    */
-  async #read (after) {
+  async #read(after?: string): Promise<Row[]> {
     const lanes = this.#atom.slots(LANES)
 
     if (lanes === null || lanes.length === 0) return []
 
-    return this.#storage.outbox.pending(lanes, Date.now(), this.#batch, after)
+    return this.#storage!
+      .outbox!.pending(lanes, Date.now(), this.#batch, after)
       .catch((error) => {
         console.warn('Outbox read failed', { error })
 
@@ -229,15 +267,14 @@ export class Outbox extends Connector {
    * marked one by one. Ids that fail to be marked are kept and retried; a row that is never
    * marked is simply published again, which is within the contract.
    *
-   * @private
    */
-  async #mark () {
+  async #mark(): Promise<void> {
     if (this.#published.size === 0) return
 
     const ids = [...this.#published]
 
     try {
-      await this.#storage.outbox.settle(ids)
+      await this.#storage!.outbox!.settle(ids)
 
       for (const id of ids) this.#published.delete(id)
     } catch (error) {
@@ -245,14 +282,13 @@ export class Outbox extends Connector {
     }
   }
 
-   /**
+  /**
    * A lane this replica currently owns, so that in steady state it settles its own rows
    * before it ever reads them. Any lane at all when it owns none: the row still has to be
    * written, and whoever ends up owning that lane will pump it.
    *
-   * @private
    */
-  #lane () {
+  #lane(): number {
     const owned = this.#atom.slots(LANES)
 
     return owned === null || owned.length === 0
@@ -261,7 +297,11 @@ export class Outbox extends Connector {
   }
 }
 
-function number (variable, declared, fallback) {
+function number(
+  variable: string,
+  declared: number | undefined,
+  fallback: number
+): number {
   if (declared !== undefined) return declared
 
   const value = Number(process.env[variable])
@@ -269,7 +309,11 @@ function number (variable, declared, fallback) {
   return Number.isNaN(value) || value <= 0 ? fallback : value
 }
 
-const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms).unref())
+async function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms).unref()
+  })
+}
 
 /**
  * Constant, never configuration: rows carry their lane, so lowering this would leave rows in

package/source/query/criteria.ts

@@ -0,0 +1,90 @@
+import { parse } from '@rsql/parser'
+import { QuerySyntaxException } from '../exceptions.js'
+import type { Node } from '../types/storages.js'
+
+/** What a component declares about the properties a criteria may select on. */
+export type Properties = Record<string, { type: string }>
+
+export function criteria(expression: string, properties?: Properties): Node {
+  let ast: Node
+
+  try {
+    ast = parse(expression) as unknown as Node
+  } catch (e) {
+    throw new QuerySyntaxException((e as Error).message)
+  }
+
+  if (properties !== undefined) read(ast, properties)
+
+  return ast
+}
+
+function read(node: Node, properties: Properties): void {
+  if (
+    node.type === 'COMPARISON' &&
+    node.left?.type === 'SELECTOR' &&
+    node.right?.type === 'VALUE'
+  ) {
+    const selector = node.left.selector as string
+    const property = properties[selector]
+
+    if (property === undefined) {
+      throw new QuerySyntaxException(`Criteria selector '${selector}' is not defined`)
+    }
+
+    const cast = CAST[property.type]
+
+    // `=in=` and `=out=` carry a list, and casting that as one value gives whatever
+    // a comma-separated string reads as
+    if (cast !== undefined)
+      node.right.value = Array.isArray(node.right.value)
+        ? node.right.value.map((value: string) => cast(value, selector))
+        : cast(node.right.value as string, selector)
+  } else {
+    if (node.left !== undefined) read(node.left, properties)
+    if (node.right !== undefined) read(node.right, properties)
+  }
+}
+
+/**
+ * A criteria arrives as text, so a value is read as what the property it selects on holds. What
+ * cannot be read as that is refused rather than passed on: `parseInt` answers `NaN` for a word
+ * and `12` for `12kg`, and a storage asked to match either finds nothing and says nothing —
+ * a mistyped filter reads as an empty result.
+ *
+ * A string is left as it came, because every text is one: what a criteria may compare a string
+ * to is not the type's to say.
+ */
+const CAST: Record<string, (value: string, selector: string) => unknown> = {
+  number: (value, selector) => finite(value, selector, 'a number'),
+
+  integer: (value, selector) => {
+    const number = finite(value, selector, 'an integer')
+
+    if (!Number.isInteger(number)) refuse(selector, 'an integer', value)
+
+    return number
+  },
+
+  boolean: (value, selector) => {
+    if (value === 'true') return true
+    if (value === 'false') return false
+
+    return refuse(selector, 'a boolean', value)
+  }
+}
+
+function finite(value: string, selector: string, expected: string): number {
+  // `Number` reads a blank string as zero, and a criteria that says nothing says nothing
+  const number = value.trim() === '' ? Number.NaN : Number(value)
+
+  if (!Number.isFinite(number)) refuse(selector, expected, value)
+
+  return number
+}
+
+function refuse(selector: string, expected: string, value: string): never {
+  throw new QuerySyntaxException(
+    `Criteria selector '${selector}' takes ${expected}, and '${value}' is not one`
+  )
+}