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

package/source/contract/request.ts

@@ -0,0 +1,85 @@
+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
+}
+
+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) {
+    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]
+  }
+
+  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
+  }
+}

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

@@ -1,26 +1,33 @@
 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 {
-  #lookup
-  #lookups
+  readonly #lookup: (locator: Locator) => Promise<Lookup>
+  #lookups: Record<string, Promise<Lookup>> = {}
 
-  constructor (lookup) {
+  public constructor(lookup: (locator: Locator) => Promise<Lookup>) {
     super()
 
     this.#lookup = lookup
   }
 
-  async open () {
+  protected override async open(): Promise<void> {
     this.#lookups = {}
   }
 
-  async lookup (locator) {
+  public async lookup(locator: Locator): Promise<any> {
     const id = locator.id
 
     if (this.#lookups[id] === undefined) {
-      this.#lookups[id] = await this.#lookup(locator)
-      this.depends(this.#lookups[id])
+      const lookup = await this.#lookup(locator)
+
+      this.#lookups[id] = Promise.resolve(lookup)
+      this.depends(lookup)
     }
 
     const since = Date.now()
@@ -35,7 +42,7 @@ export class Discovery extends Connector {
 
     warning.unref()
 
-    const output = await this.#lookups[id].invoke()
+    const output = await (await this.#lookups[id]).invoke()
 
     clearInterval(warning)
 

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

@@ -1,9 +1,11 @@
 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 {
-  #events
+  readonly #events: Event[]
 
-  constructor (events) {
+  public constructor(events: Event[]) {
     super()
 
     this.#events = events
@@ -11,7 +13,7 @@ export class Emission extends Connector {
     this.depends(events)
   }
 
-  async emit (event) {
+  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/{src/entities/newid.js → source/entities/newid.ts}

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

package/{src/entities/set.js → source/entities/set.ts}

@@ -1,24 +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 {
-  #set
+  readonly #set: Entity[]
 
-  constructor (set) {
+  public constructor(set: Entity[]) {
     this.#set = set
   }
 
-  get () {
+  public get(): Record[] {
     return this.#set.map((entity) => entity.get())
   }
 
-  set (values) {
+  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))
   }
 
-  events (input = undefined) {
+  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)
+      })
+    }
+  }
+}

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')