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

package/source/context.ts

@@ -0,0 +1,67 @@
+import { Connector } from './connector.js'
+import type { Locator } from './locator.js'
+import type { Component } from './component.js'
+import type { Remote } from './remote.js'
+import type { Aspect } from './types/extensions.js'
+import type { Request } from './types/request.js'
+
+type Discover = (namespace: string, name: string) => Promise<Remote>
+
+export class Context extends Connector {
+  public readonly env: string | undefined
+  public readonly name: string | undefined
+  public readonly aspects: Aspect[]
+  public readonly locator: Locator
+
+  readonly #local: Component
+  readonly #discover: Discover
+  readonly #remotes: Record<string, Promise<Remote>> = {}
+
+  public constructor(local: Component, discover: Discover, aspects: Aspect[] = []) {
+    super()
+
+    this.env = process.env.TOA_ENV
+    this.name = process.env.TOA_CONTEXT
+    this.aspects = aspects
+    this.locator = local?.locator
+
+    this.#local = local
+    this.#discover = discover
+
+    this.depends(local)
+
+    if (aspects.length > 0) this.depends(aspects)
+  }
+
+  public async apply(endpoint: string, request: Request): Promise<any> {
+    return this.#local.invoke(endpoint, request)
+  }
+
+  // eslint-disable-next-line max-params
+  public async call(
+    namespace: string,
+    name: string,
+    endpoint: string,
+    request: Request
+  ): Promise<any> {
+    const remote = await this.#remote(namespace, name)
+
+    return remote.invoke(endpoint, request)
+  }
+
+  async #remote(namespace: string, name: string): Promise<Remote> {
+    const key = namespace + '.' + name
+
+    this.#remotes[key] ??= this.#connect(namespace, name)
+
+    return this.#remotes[key]
+  }
+
+  async #connect(namespace: string, name: string): Promise<Remote> {
+    const remote = await this.#discover(namespace, name)
+
+    this.depends(remote)
+
+    return remote
+  }
+}

package/source/contract/contract.ts

@@ -0,0 +1,23 @@
+import { SystemException } from '../exceptions.js'
+import type { Schema, SchemaError } from '@toa.io/schemas'
+import type { Exception } from '../exceptions.js'
+
+/** What a contract throws with, stated by the subclass. */
+export type Refusal = new (error: SchemaError, cause?: unknown) => Exception
+
+export class Contract {
+  public readonly schema: Schema
+
+  public static Exception: Refusal = SystemException as unknown as Refusal
+
+  public constructor(schema: Schema) {
+    this.schema = schema
+  }
+
+  public fit(value: unknown): void {
+    const error = this.schema.fit(value)
+
+    if (error !== null)
+      throw new (this.constructor as typeof Contract).Exception(error, value)
+  }
+}

package/{src/contract/reply.js → source/contract/reply.ts}

@@ -1,23 +1,29 @@
 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 {
-  static Exception = ResponseContractException
+  public static override Exception: Refusal =
+    ResponseContractException as unknown as Refusal
 
-  static schema (output, errors) {
-    const schema = { type: 'object', properties: {}, additionalProperties: false }
+  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
+       * 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
+      if (output.type === 'object') output.additionalProperties = true
       else if (output.type === 'array' && output.items?.type === 'object')
         output.items.additionalProperties = true
 
@@ -29,20 +35,21 @@ export class Reply extends Contract {
      * 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
+    schema.properties.error =
+      errors === undefined
+        ? false
+        : {
+            type: 'object',
+            properties: {
+              code: {
+                enum: errors
+              },
+              message: {
+                type: 'string'
+              }
             },
-            message: {
-              type: 'string'
-            }
-          },
-          required: ['code']
-        }
+            required: ['code']
+          }
 
     return schema
   }

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