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

package/source/contract/reply.ts

@@ -0,0 +1,56 @@
+import { Contract } from './contract.js'
+import { ResponseContractException } from '../exceptions.js'
+import type { Refusal } from './contract.js'
+import type { JSONSchema } from './schemas.js'
+
+export class Reply extends Contract {
+  public static override Exception: Refusal =
+    ResponseContractException as unknown as Refusal
+
+  public static schema(output?: JSONSchema, errors?: Array<string | number>): JSONSchema {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    }
+
+    if (output !== undefined) {
+      /*
+       * A reply carries more than the operation declares — `VERSION` and the rest of the
+       * record's own fields — so what it is validated against is the declaration relaxed.
+       * On a copy: the declaration itself is what a component publishes when asked to
+       * explain, and relaxing that would publish a contract nobody wrote.
+       */
+      output = structuredClone(output)
+
+      if (output.type === 'object') output.additionalProperties = true
+      else if (output.type === 'array' && output.items?.type === 'object')
+        output.items.additionalProperties = true
+
+      schema.properties.output = output
+    }
+
+    /*
+     * An error a caller is meant to handle is one the operation states. Where none are
+     * stated, an error is not a reply this operation makes — it is a mistake, and the
+     * contract says so rather than passing an undeclared code on to whoever called.
+     */
+    schema.properties.error =
+      errors === undefined
+        ? false
+        : {
+            type: 'object',
+            properties: {
+              code: {
+                enum: errors
+              },
+              message: {
+                type: 'string'
+              }
+            },
+            required: ['code']
+          }
+
+    return schema
+  }
+}

package/source/contract/request.ts

@@ -0,0 +1,140 @@
+import * as schemas from './schemas.js'
+import { RequestContractException } from '../exceptions.js'
+import { Contract } from './contract.js'
+import type { Schema } from '@toa.io/schemas'
+import type { Refusal } from './contract.js'
+import type { JSONSchema } from './schemas.js'
+
+/** What an operation states about itself, and answers when asked to explain. */
+export interface Explanation {
+  description?: string
+  input?: JSONSchema | null
+  output?: JSONSchema | null
+  errors?: Array<string | number>
+}
+
+export interface Definition extends Explanation {
+  type?: string
+  scope?: string
+  query?: boolean
+}
+
+/** What the operation works on, as the manifest declares it. */
+export interface Entity {
+  properties: Record<string, JSONSchema>
+  required?: string[]
+}
+
+export class Request extends Contract {
+  public readonly discovery: Explanation = {}
+
+  public static override Exception: Refusal =
+    RequestContractException as unknown as Refusal
+
+  public constructor(schema: Schema, definition: Definition, entity?: Entity) {
+    super(schema)
+
+    for (const key of ['description', 'input', 'output', 'errors'] as const)
+      if (definition[key] !== undefined)
+        (this.discovery as Record<string, unknown>)[key] = definition[key]
+
+    /*
+     * An operation that states no output states an empty schema, which every reply fits —
+     * and which says nothing to whoever reads it. What its type answers does, so that is
+     * said here instead. Here and not in the definition, because the definition is what a
+     * reply is held to: a projection is a lawful answer, and describing one is not the same
+     * as requiring it.
+     */
+    if (empty(this.discovery.output)) {
+      const answered = answers(definition, entity)
+
+      if (answered !== undefined) this.discovery.output = answered
+    }
+  }
+
+  public static schema(
+    definition: Definition,
+    entity?: { properties: Record<string, JSONSchema> }
+  ): JSONSchema {
+    // `source` is not among these: the framework stamps it and whoever reads it takes the keys
+    // it knows, so holding it to a schema would only fail calls from a peer that stamps one more
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        authentic: { type: 'boolean' },
+        task: { type: 'boolean' }
+      },
+      additionalProperties: true
+    }
+
+    const required: string[] = []
+
+    if (definition.input !== undefined) {
+      schema.properties.input = definition.input
+      required.push('input')
+    } else schema.properties.input = { type: 'null' }
+
+    if (entity === undefined) definition.query = false
+
+    if (definition.query === true) required.push('query')
+
+    if (definition.query === false) schema.properties.query = { type: 'null' }
+
+    if (definition.query !== false) {
+      const query = structuredClone(schemas.query)
+
+      query.properties.id = entity?.properties.id
+
+      if (definition.type === 'observation') delete query.properties.version
+      else delete query.properties.projection
+
+      if (definition.type !== 'observation' || definition.scope !== 'objects') {
+        delete query.properties.omit
+        delete query.properties.limit
+      } else if (query.required === undefined) query.required = ['limit']
+      else query.required.push('limit')
+
+      schema.properties.query = query
+    }
+
+    if (required.length > 0) schema.required = required
+
+    return schema
+  }
+}
+
+/**
+ * What an operation of this type answers, where it did not say.
+ *
+ * A transition, an observation and an assignment work on the Entity Object, so that is what
+ * they answer — a set of them where the scope is a set. A computation neither uses the scope
+ * nor produces one, and an effect answers whatever it computed, so neither is guessed at.
+ * A stream is not a value with a schema, and is not one either.
+ *
+ * What the entity requires is said as well. It is a description and nothing is held to it —
+ * an operation answering a projection says so by declaring its own output — and a shape
+ * whose every property reads as optional says less than it knows.
+ */
+function answers(definition: Definition, entity?: Entity): JSONSchema | undefined {
+  if (entity === undefined || !ENTITY.has(definition.type as string)) return undefined
+
+  const object: JSONSchema = {
+    type: 'object',
+    properties: entity.properties,
+    ...(entity.required === undefined ? {} : { required: entity.required })
+  }
+
+  if (definition.scope === 'objects') return { type: 'array', items: object } as JSONSchema
+
+  return definition.scope === 'object' || definition.scope === 'changeset'
+    ? object
+    : undefined
+}
+
+/** The types whose subject is the Entity Object; see `documentation/design.md`. */
+const ENTITY = new Set(['transition', 'observation', 'assignment'])
+
+/** A schema that states nothing, which is what an operation saying nothing normalizes to. */
+function empty(schema: JSONSchema | null | undefined): boolean {
+  return schema === undefined || schema === null || Object.keys(schema).length === 0
+}

package/source/contract/schemas.ts

@@ -0,0 +1,39 @@
+/** A JSON Schema, loose because it is handed to a validator and edited by the contracts. */
+export type JSONSchema = Record<string, any>
+
+export const query: JSONSchema = {
+  type: 'object',
+  properties: {
+    id: { type: 'string' },
+    ids: { type: 'array', uniqueItems: true, minItems: 1, items: { type: 'string' } },
+    version: { type: 'integer', minimum: 0 },
+    criteria: { type: 'string' },
+    search: { type: 'string' },
+    sample: { type: 'number' },
+    omit: { type: 'integer', minimum: 0 },
+    limit: { type: 'integer', minimum: 0 },
+    sort: {
+      type: 'array',
+      uniqueItems: true,
+      minItems: 1,
+      items: { type: 'string', pattern: '^\\w{1,32}(?::(?:asc|desc))?$' }
+    },
+    projection: {
+      type: 'array',
+      uniqueItems: true,
+      minItems: 1,
+      items: { type: 'string', not: { const: 'id' } }
+    },
+    deleted: { type: 'boolean' }
+  },
+  additionalProperties: false
+}
+
+export const error: JSONSchema = {
+  type: 'object',
+  properties: {
+    code: { anyOf: [{ type: 'integer' }, { type: 'string' }] },
+    message: { type: 'string' }
+  },
+  required: ['code']
+}

package/source/discovery.ts

@@ -0,0 +1,53 @@
+import { console } from 'openspan'
+import { Connector } from './connector.js'
+import type { Locator } from './locator.js'
+
+interface Lookup extends Connector {
+  invoke: () => Promise<any>
+}
+
+export class Discovery extends Connector {
+  readonly #lookup: (locator: Locator) => Promise<Lookup>
+  #lookups: Record<string, Promise<Lookup>> = {}
+
+  public constructor(lookup: (locator: Locator) => Promise<Lookup>) {
+    super()
+
+    this.#lookup = lookup
+  }
+
+  protected override async open(): Promise<void> {
+    this.#lookups = {}
+  }
+
+  public async lookup(locator: Locator): Promise<any> {
+    const id = locator.id
+
+    if (this.#lookups[id] === undefined) {
+      const lookup = await this.#lookup(locator)
+
+      this.#lookups[id] = Promise.resolve(lookup)
+      this.depends(lookup)
+    }
+
+    const since = Date.now()
+
+    // the wait is unbounded by design, as a dependency may still be starting,
+    // so repeating is the only way a component stuck on one stays visible
+    const warning = setInterval(() => {
+      const waiting = Math.round((Date.now() - since) / 1000)
+
+      console.warn('Waiting for lookup response', { component: id, waiting })
+    }, INTERVAL)
+
+    warning.unref()
+
+    const output = await (await this.#lookups[id]).invoke()
+
+    clearInterval(warning)
+
+    return output
+  }
+}
+
+const INTERVAL = 5000

package/source/effect.ts

@@ -0,0 +1,14 @@
+import { Observation } from './observation.js'
+import type { Store } from './operation.js'
+import type { Entity } from './entities/entity.js'
+
+export class Effect extends Observation {
+  protected override async acquire(store: Store): Promise<void> {
+    const { query, entity, input } = store.request
+
+    if (entity === undefined) return super.acquire(store)
+
+    store.scope = await this.scope.ensure(query as any, entity, input)
+    store.state = (store.scope as Entity).get()
+  }
+}

package/source/emission.ts

@@ -0,0 +1,21 @@
+import { Connector } from './connector.js'
+import type { Event } from './event.js'
+import type { Event as StateEvent } from './types/state.js'
+
+export class Emission extends Connector {
+  readonly #events: Event[]
+
+  public constructor(events: Event[]) {
+    super()
+
+    this.#events = events
+
+    this.depends(events)
+  }
+
+  public async emit(event: StateEvent): Promise<void> {
+    const emission = this.#events.map((e) => e.emit(event))
+
+    await Promise.all(emission)
+  }
+}

package/source/entities/changeset.ts

@@ -0,0 +1,37 @@
+import { EntityContractException } from '../exceptions.js'
+import type { Schema } from '@toa.io/schemas'
+import type { Query, Record } from '../types/storages.js'
+
+export class Changeset {
+  public readonly query: Query
+
+  /** the changeset schema: the entity's properties, none of them required */
+  readonly #schema: Schema
+  #state: Record | object
+
+  public constructor(schema: Schema, query: Query) {
+    this.query = query
+
+    this.#schema = schema
+    this.#state = {}
+  }
+
+  public get(): object {
+    return this.#state
+  }
+
+  public set(value: Record): void {
+    const error = this.#schema.fit(value)
+
+    if (error !== null) throw new EntityContractException(error, value)
+
+    delete (value as Partial<Record>).VERSION
+    value.UPDATED = Date.now()
+
+    this.#state = value
+  }
+
+  public export(): object {
+    return this.#state
+  }
+}

package/source/entities/entity.ts

@@ -0,0 +1,137 @@
+import { EntityContractException, EntityGuardException } from '../exceptions.js'
+import { newid } from './newid.js'
+import type { Schema } from '@toa.io/schemas'
+import type { Guard } from '../guard.js'
+import type { Record } from '../types/storages.js'
+import type { Event } from '../types/state.js'
+
+export class Entity {
+  public deleted = false
+
+  readonly #schema: Schema
+  readonly #blank: object
+  readonly #guards: Guard[] | undefined
+  #origin: Record | null = null
+  #state!: Record
+  #mutable = true
+
+  /**
+   * A record makes an entity of what a storage holds; a string, or nothing at all, makes a
+   * blank one under that identity, out of what the component declared a record starts as.
+   *
+   * @param blank what the component declares a record holds before anything is written to it
+   * @param mutable whether the entity may be modified and committed
+   */
+  // eslint-disable-next-line max-params
+  public constructor(
+    schema: Schema,
+    blank: object,
+    argument?: Record | string,
+    guards?: Guard[],
+    mutable = true
+  ) {
+    this.#schema = schema
+    this.#blank = blank
+    this.#guards = guards
+
+    if (typeof argument === 'object') this.#acquire(argument, mutable)
+    else this.#write(this.#compose(argument ?? newid()))
+  }
+
+  public get(): Record {
+    return this.#state
+  }
+
+  public set(value: Record): void {
+    if (!this.#mutable)
+      throw new Error('Entity acquired by a read-only operation cannot be modified')
+
+    this.#guard(value)
+
+    const error = this.#schema.fit(value)
+
+    if (error !== null) throw new EntityContractException(error, value)
+
+    this.#revive(value)
+    this.#write(value)
+  }
+
+  public event(input?: object): Event {
+    return {
+      origin: this.#origin,
+      state: this.#state,
+      trailers: this.#state._trailers,
+      input
+    }
+  }
+
+  /**
+   * The origin is the pre-image a commit diffs the new state against. An operation that
+   * cannot commit has nothing to diff, so it takes the record as it came from the storage
+   * instead of paying for a deep copy of every record it read.
+   */
+  #acquire(record: Record, mutable: boolean): void {
+    this.#mutable = mutable
+
+    if (!mutable) {
+      this.#write(record)
+
+      return
+    }
+
+    this.#write(structuredClone(record))
+    this.#origin = record
+  }
+
+  /**
+   * A blank is not validated: what the component declared is fitted once, at boot, and the
+   * system properties are the runtime's own. It is copied because every entity the component
+   * makes is written over its own.
+   */
+  #compose(id: string): Record {
+    return { id, VERSION: 0, DELETED: null, ...structuredClone(this.#blank) } as Record
+  }
+
+  #guard(value: Record): void {
+    if (this.#guards === undefined) return
+
+    for (const guard of this.#guards) {
+      const ok = guard.fit(value, this.#origin)
+
+      if (ok === false) throw new EntityGuardException(guard.name, value)
+    }
+  }
+
+  // deletion is only expressed as a new DELETED timestamp,
+  // so committing over a tombstone without touching it means revival
+  #revive(value: Record): void {
+    if (this.#origin?.DELETED == null || value.DELETED !== this.#origin.DELETED) return
+
+    value.DELETED = null
+    this.deleted = false
+  }
+
+  #write(value: Record): void {
+    if (!('_trailers' in value))
+      Object.defineProperty(value, '_trailers', {
+        writable: false,
+        configurable: false,
+        enumerable: false,
+        value: {}
+      })
+
+    if (!('CREATED' in value)) {
+      value.CREATED = Date.now()
+      value.UPDATED ??= value.CREATED
+    }
+
+    if ('DELETED' in value && value.DELETED !== null) this.deleted = true
+
+    if (this.#state !== undefined) {
+      value.UPDATED = Date.now()
+      value.VERSION++
+    }
+
+    this.#state = value
+  }
+}

package/source/entities/factory.ts

@@ -0,0 +1,52 @@
+import { newid } from './newid.js'
+import { Entity } from './entity.js'
+import { EntitySet } from './set.js'
+import { Changeset } from './changeset.js'
+import type { Schema } from '@toa.io/schemas'
+import type { Guard } from '../guard.js'
+import type { Query, Record } from '../types/storages.js'
+
+/** The two schemas a component's records are held to, and what a new one starts as. */
+export interface Schemas {
+  /** what a stored record must fit */
+  entity: Schema
+
+  /** what a changeset must fit: the same properties, none of them required */
+  changeset: Schema
+}
+
+export class Factory {
+  readonly #schemas: Schemas
+  readonly #blank: object
+  readonly #guards: Guard[] | undefined
+
+  public constructor(schemas: Schemas, blank: object, guards?: Guard[]) {
+    this.#schemas = schemas
+    this.#blank = blank
+    this.#guards = guards
+  }
+
+  public fit(values: object): void {
+    this.#schemas.entity.validate({ id: newid(), ...this.#blank, ...values }, 'Entity')
+  }
+
+  public init(id?: string): Entity {
+    return new Entity(this.#schemas.entity, this.#blank, id, this.#guards)
+  }
+
+  public object(record: Record, mutable = true): Entity {
+    return new Entity(this.#schemas.entity, this.#blank, record, this.#guards, mutable)
+  }
+
+  public objects(recordset: Record[], init?: string[], mutable = true): EntitySet {
+    const set = recordset.map((record) => this.object(record, mutable))
+
+    if (init !== undefined) for (const id of init) set.unshift(this.init(id))
+
+    return new EntitySet(set)
+  }
+
+  public changeset(query: Query): Changeset {
+    return new Changeset(this.#schemas.changeset, query)
+  }
+}

package/source/entities/index.ts

@@ -0,0 +1,4 @@
+export { Factory } from './factory.js'
+export { Entity } from './entity.js'
+export { EntitySet } from './set.js'
+export { Changeset } from './changeset.js'

package/source/entities/newid.ts

@@ -0,0 +1,9 @@
+import * as uuid from 'uuid'
+
+export function newid(): string {
+  const buf = Buffer.alloc(16)
+
+  uuid.v7(undefined, buf)
+
+  return buf.toString('hex')
+}

package/source/entities/set.ts

@@ -0,0 +1,27 @@
+import { SystemException } from '../exceptions.js'
+import type { Entity } from './entity.js'
+import type { Record } from '../types/storages.js'
+import type { Event } from '../types/state.js'
+
+export class EntitySet {
+  readonly #set: Entity[]
+
+  public constructor(set: Entity[]) {
+    this.#set = set
+  }
+
+  public get(): Record[] {
+    return this.#set.map((entity) => entity.get())
+  }
+
+  public set(values: Record[]): void {
+    if (values.length !== this.#set.length)
+      throw new SystemException('Objects array must not be modified')
+
+    values.forEach((value, index) => this.#set[index].set(value))
+  }
+
+  public events(input?: object): Event[] {
+    return this.#set.map((entity) => entity.event(input))
+  }
+}

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