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

package/types/extensions.d.ts

@@ -1,28 +1,72 @@
-import * as _core from './index'
-import * as _component from './component'
-import * as _context from './context'
-import * as _storages from './storages'
-import * as _bindings from './bindings'
+import * as _core from './index.js'
+import * as _component from './component.js'
+import * as _context from './context.js'
+import * as _storages from './storages.js'
+import * as _bindings from './bindings.js'
+import { Manifest } from '@toa.io/norm'
 
-export interface Factory{
-  tenant? (locator: _core.Locator, manifest: object): _core.Connector
+/**
+ * What the process hosting an extension provides to it: the counterpart of a component's
+ * `Context`. What is returned is a connector the extension depends on.
+ */
+export interface Host {
+  /** a component of the context, by locator */
+  remote (locator: _core.Locator, source?: _core.Source): Promise<_core.Remote>
+
+  /** a channel of the messaging binding */
+  broadcast<T = unknown> (channel: string, group?: string): Promise<_bindings.Broadcast<T>>
+
+  /** components to run inside the extension's own process */
+  composition (paths: string[]): Promise<_core.Connector>
+
+  /** a consumer of an event of the context, `namespace.component.event` */
+  receive (label: string, receiver: _core.Receiver): Promise<_core.Connector>
+
+  /** what the replicas of one group decide together */
+  atom (group: string): _core.atomicity.Atom
+}
+
+export interface Factory {
+  tenant? (locator: _core.Locator, manifest: object, component: Manifest):
+  _core.Connector | Promise<_core.Connector>
 
   aspect? (locator: _core.Locator, manifest: object | null): Aspect | Aspect[]
 
-  service? (name?: string): _core.Connector | null
+  service? (name?: string): _core.Connector | null | Promise<_core.Connector | null>
 
   component? (component: _component.Component): _component.Component
 
   context? (context: _context.Context): _context.Context
 
+  manage? (composition: _core.Connector): _core.Connector
+
   storage? (storage: _storages.Storage): _storages.Storage
 
-  emitter? (emitter: _bindings.Emitter, label: string): _bindings.Emitter
+  emitter? (emitter: _bindings.Emitter, label: string, locator: _core.Locator): _bindings.Emitter
 
   receiver? (receiver: _core.Receiver, locator: _core.Locator): _core.Receiver
 }
 
-export interface Aspect extends _core.Connector{
+/**
+ * What an extension puts on a component's context, as the extension states it. How it is
+ * presented there is the bridge's — a bash bridge has no context to put anything on — and
+ * what is declared here is the key and what it holds.
+ */
+export interface Contribution {
+  /** the key on the context */
+  name: string
+
+  /** what the key holds, as TypeScript */
+  type?: string
+
+  /** what `type` names, by the module it comes from */
+  imports?: Record<string, string[]>
+
+  /** a JSON Schema to read the type from instead, where a component states one */
+  schema?: object
+}
+
+export interface Aspect extends _core.Connector {
   name: string
 
   invoke (...args: any[]): any

package/types/guard.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Runs on every change to an entity's state, before the contract is applied. `false` refuses
+ * the change as `EntityGuard`.
+ */
+export type Guard<T, C = unknown> = (state: T, origin: T | null, context: C) => boolean

package/types/index.ts

@@ -1,14 +1,21 @@
-export * as bindings from './bindings'
-export * as extensions from './extensions'
-export * as storages from './storages'
-export * as bridges from './bridges'
-export * as operations from './operations'
+export * as bindings from './bindings.js'
+export * as extensions from './extensions.js'
+export * as storages from './storages.js'
+export * as outbox from './outbox.js'
+export * as atomicity from './atomicity.js'
+export * as bridges from './bridges.js'
+export * as operations from './operations.js'
 
-export type { Component } from './component'
-export { Connector } from './connector'
-export type { Context } from './context'
-export type { Exception } from './exception'
-export { Locator } from './locator'
-export type { Receiver } from './receiver'
-export type { Message } from './message'
-export type { Request, Query, Reply } from './request'
+export type { Component } from './component.js'
+export type { Remote } from './remote.js'
+export { Connector } from './connector.js'
+export type { Context } from './context.js'
+export type { Exception } from './exception.js'
+export { Locator } from './locator.js'
+export type { Receiver } from './receiver.js'
+export type { Message } from './message.js'
+export type { Maybe, Request, Query, Reply, RemoteError, Source } from './request.js'
+export type { Event } from './state.js'
+export type { Guard } from './guard.js'
+export type { Call, Observation, Transition } from './call.js'
+export type { Contribution } from './extensions.js'

package/types/message.d.ts

@@ -1,3 +1,4 @@
 export interface Message<T = any> {
   payload: T
+  telemetry?: string // W3C traceparent
 }

package/types/operations.d.ts

@@ -1,2 +1,8 @@
+import { Request } from './request.js'
+
 export type type = 'transition' | 'observation' | 'assignment' | 'computation' | 'effect'
 export type scope = 'object' | 'objects' | 'changeset'
+
+export class Operation {
+  invoke<T = any> (request: Request): Promise<T>
+}

package/types/outbox.d.ts

@@ -0,0 +1,53 @@
+import * as _state from './state.js'
+import * as _atomicity from './atomicity.js'
+
+declare namespace toa.core {
+
+  namespace outbox {
+
+    /**
+     * The intent to publish, committed with the state change it belongs to. Everything about
+     * it is core's: the storage writes it and, where the images are the write's own, fills
+     * `event.origin` and `event.state` in.
+     */
+    interface Row {
+      id: string
+
+      /** which replica pumps this row; carries no other meaning, and no ordering */
+      lane: number
+
+      published: boolean
+
+      /** not before this */
+      pending: number
+
+      event: _state.Event
+    }
+
+    /** What a storage offers when it can commit a row atomically with the entity. */
+    interface Storage {
+      insert (row: Row, session?: unknown): Promise<void>
+
+      insertMany (rows: Row[], session?: unknown): Promise<void>
+
+      /**
+       * One page of what is due, still unpublished, and in one of the given lanes, in the
+       * order the rows were written. `after` continues from the last id of the page before.
+       */
+      pending (lanes: number[], now: number, limit: number, after?: string): Promise<Row[]>
+
+      settle (ids: string[]): Promise<void>
+    }
+
+  }
+
+}
+
+export type Row = toa.core.outbox.Row
+export type Storage = toa.core.outbox.Storage
+
+/**
+ * A lane is a slot of `atomicity`: which replica pumps a row, and nothing else. The outbox is
+ * the first thing to claim slots this way, not the last.
+ */
+export type Atom = _atomicity.Atom

package/types/query.d.ts

@@ -4,6 +4,8 @@ declare namespace toa.core {
     id?: string
     version?: number
     criteria?: Object
+    search?: string
+    sample?: number
     omit?: number
     limit?: number
     sort?: string[]

package/types/receiver.d.ts

@@ -1,5 +1,5 @@
-import * as _message from './message'
-import * as _connector from './connector'
+import * as _message from './message.js'
+import * as _connector from './connector.js'
 
 declare namespace toa.core {
 

package/types/reflection.d.ts

@@ -1,4 +1,4 @@
-import * as _core from './connector'
+import * as _core from './connector.js'
 
 declare namespace toa.core {
 

package/types/remote.d.ts

@@ -0,0 +1,18 @@
+import { Component } from './component.js'
+
+export class Remote extends Component {
+  explain (endpoint: string): Promise<Explanation>
+}
+
+interface Explanation {
+  input: Schema | null
+  output: Schema | null
+  errors?: string[]
+}
+
+interface Schema {
+  type: string
+  properties: {
+    [key: string]: Schema
+  }
+}

package/types/request.d.ts

@@ -1,21 +1,53 @@
-import { Exception } from './exception'
+import { Exception } from './exception.js'
 
-export interface Query {
+/**
+ * What a call asks for. `Entity` is the record it is about, which narrows the projection;
+ * left out, any name is accepted.
+ */
+export interface Query<Entity = any> {
   id?: string
+  ids?: Array<string>
   criteria?: string
+  search?: string
+  sample?: number
   omit?: number
   limit?: number
   sort?: Array<string>
-  projection?: Array<string>
+  projection?: Array<string & keyof Entity>
   version?: number
+  deleted?: boolean
 }
 
-export interface Request {
-  input?: any
-  query?: Query
+/**
+ * Origin of a call. Stamped by the caller, sanitized by the request contract.
+ */
+export type Source =
+  | { namespace: string, component: string, operation: string }
+  | { namespace: string, component: string, event: string }
+  | { service: string }
+
+export interface Request<Input = any, Entity = any> {
+  input?: Input
+  query?: Query<Entity>
+  /** What the operation acquires, where the caller supplies it rather than the storage. */
+  entity?: Entity
   authentic?: boolean
+  task?: boolean
+  telemetry?: string // W3C traceparent
+  source?: Source
+}
+
+/**
+ * An error an operation declares and returns. A call resolves to it rather than throwing:
+ * only an exception is thrown.
+ */
+export interface RemoteError<Code extends string = string> extends Error {
+  code: Code
 }
 
+/** What an operation returns where it may refuse: the value, or the error it refused with. */
+export type Maybe<T> = T | Error
+
 export interface Reply {
   output?: any
   error?: object

package/types/state.d.ts

@@ -1,14 +1,17 @@
-import * as _entity from './entity'
-import * as _storages from './storages'
+import * as _entity from './entity.js'
+import * as _storages from './storages.js'
 
 declare namespace toa.core {
 
   namespace transition {
 
-    type Event = {
-      origin: Object
-      state: Object
-      changeset: Object
+    type Event<State = Object, Trailers = Object> = {
+      /** the pre-image; null when the entity did not exist before */
+      origin: State | null
+      state: State
+      /** out-of-band values an algorithm wrote into `state._trailers`; must be serializable */
+      trailers?: Trailers
+      input?: Object
     }
 
   }
@@ -16,20 +19,20 @@ declare namespace toa.core {
   interface State {
     init(id: string): _entity.Entity
 
-    object(query: _storages.Query): Promise<_entity.Entity>
+    object(query: _storages.Query, mutable?: boolean): Promise<_entity.Entity>
 
-    objects(query: _storages.Query): Promise<_entity.Entity[]>
+    objects(query: _storages.Query, mutable?: boolean): Promise<_entity.Entity[]>
 
     changeset(query: _storages.Query): _entity.Changeset
 
     none(): null
 
-    commit(entity: _entity.Entity): Promise<boolean>
+    commit(entity: _entity.Entity, input?: Object): Promise<boolean>
 
-    apply(changeset: _entity.Changeset): Promise<void>
+    apply(changeset: _entity.Changeset, input?: Object): Promise<_storages.Record>
   }
 
 }
 
 export type State = toa.core.State
-export type Event = toa.core.transition.Event
+export type Event<State = Object, Trailers = Object> = toa.core.transition.Event<State, Trailers>

package/types/storages.d.ts

@@ -1,7 +1,8 @@
 // noinspection ES6UnusedImports
 
-import { Locator } from './locator'
-import { Connector } from './connector'
+import { Locator } from './locator.js'
+import { Connector } from './connector.js'
+import * as outbox from './outbox.js'
 
 declare namespace toa.core {
 
@@ -30,36 +31,60 @@ declare namespace toa.core {
       id?: string
       version?: number
       criteria?: ast.Node
+      search?: string
+      sample?: number
       options?: Object
     }
 
     interface Migration {
-      disconnect(): Promise<void>
+      disconnect (): Promise<void>
 
-      database(name: string): Promise<void>
+      database (name: string): Promise<void>
 
-      table(database: string, locator: Locator, schema: Object, reset?: boolean): Promise<string>
+      table (database: string, locator: Locator, schema: Object, reset?: boolean): Promise<string>
+    }
+
+    interface Options {
+      /** whether this component publishes anything, and so needs an outbox */
+      outbox?: boolean
     }
 
     interface Factory {
-      storage(locator: Locator, properties?: object): Storage
+      storage (locator: Locator, properties?: object, options?: Options): Storage
 
-      migration?(driver?: string): Migration
+      migration? (driver?: string): Migration
     }
   }
 
   interface Storage extends Connector {
     // object observation
-    get?(query: storages.Query): Promise<storages.Record | null>
+    get? (query: storages.Query): Promise<storages.Record | null>
 
     // objects observation
-    find?(query: storages.Query): Promise<storages.Record[]>
+    find? (query: storages.Query): Promise<storages.Record[]>
 
     // commit
-    store?(record: storages.Record): Promise<boolean>
+    store? (record: storages.Record, row?: outbox.Row): Promise<boolean>
+
+    // mass commit
+    massStore? (records: storages.Record[], rows?: outbox.Row[]): Promise<boolean>
 
     // assignment
-    upsert?(query: storages.Query, changeset: Object, insert: storages.Record): Promise<storages.Record>
+    upsert? (query: storages.Query, changeset: Object, row?: outbox.Row): Promise<storages.Record>
+
+    // atomic get-or-create
+    ensure? (query: storages.Query, properties: Object, record: storages.Record, row?: outbox.Row): Promise<storages.Record>
+
+    /**
+     * Present only where a row can be committed atomically with the entity. Its absence is
+     * what makes the runtime fall back to publishing inline, so a storage that cannot do
+     * this must not offer it: a row written outside the transaction would be a second write
+     * with a crash window in front of it, which is the defect the outbox exists to close.
+     *
+     * The row schema is the connector's own — it also owns `pending` and `settle` — and
+     * never crosses this boundary.
+     */
+    outbox?: outbox.Storage
   }
 
 }

package/src/contract/conditions.js

@@ -1,21 +0,0 @@
-'use strict'
-
-const { SystemException } = require('../exceptions')
-
-class Conditions {
-  #schema
-
-  constructor (schema) {
-    this.#schema = schema
-  }
-
-  fit (value) {
-    const error = this.#schema.fit(value)
-
-    if (error !== null) throw new this.constructor.Exception(error)
-  }
-
-  static Exception = SystemException
-}
-
-exports.Conditions = Conditions