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

package/{types/request.d.ts → source/types/request.ts}

@@ -1,4 +1,4 @@
-import { Exception } from './exception.js'
+import type { Exception } from '../exceptions.js'
 
 /**
  * What a call asks for. `Entity` is the record it is about, which narrows the projection;
@@ -6,24 +6,22 @@ import { Exception } from './exception.js'
  */
 export interface Query<Entity = any> {
   id?: string
-  ids?: Array<string>
+  ids?: string[]
   criteria?: string
   search?: string
   sample?: number
   omit?: number
   limit?: number
-  sort?: Array<string>
+  sort?: string[]
   projection?: Array<string & keyof Entity>
   version?: number
   deleted?: boolean
 }
 
-/**
- * Origin of a call. Stamped by the caller, sanitized by the request contract.
- */
+/** Origin of a call. Stamped by the framework; whoever reads it takes the keys it knows. */
 export type Source =
-  | { namespace: string, component: string, operation: string }
-  | { namespace: string, component: string, event: string }
+  | { namespace: string; component: string; operation: string }
+  | { namespace: string; component: string; event: string }
   | { service: string }
 
 export interface Request<Input = any, Entity = any> {
@@ -33,7 +31,8 @@ export interface Request<Input = any, Entity = any> {
   entity?: Entity
   authentic?: boolean
   task?: boolean
-  telemetry?: string // W3C traceparent
+  /** W3C traceparent */
+  telemetry?: string
   source?: Source
 }
 

package/source/types/state.ts

@@ -0,0 +1,9 @@
+/** What a commit publishes: the images of one state change. */
+export interface 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
+}

package/source/types/storages.ts

@@ -0,0 +1,129 @@
+import type { Readable } from 'node:stream'
+import type { Connector } from '../connector.js'
+import type { Locator } from '../locator.js'
+import type { Row, Storage as Outbox } from './outbox.js'
+
+/** the RSQL tree `@rsql/parser` produces; a storage translates it into its own dialect */
+export interface Node {
+  type: 'LOGIC' | 'COMPARISON' | 'SELECTOR' | 'VALUE'
+  left?: Node
+  right?: Node
+  operator?: string
+  selector?: string
+  value?: unknown
+}
+
+/** What a storage stores. `id` is the key; the upper-cased names are core's. */
+export interface Record {
+  id: string
+  VERSION: number
+  CREATED?: number
+  UPDATED?: number
+  /** a tombstone's timestamp; `null` on a live record */
+  DELETED?: number | null
+  [key: string]: any
+}
+
+/** Everything a request query carried that was not a selector. */
+export interface Options {
+  omit?: number
+  limit?: number
+  /** normalised by `query/options.ts` from `'name:asc'` into pairs */
+  sort?: Array<[property: string, direction: string]>
+  /** always includes `VERSION`, `CREATED`, `UPDATED`, `DELETED` */
+  projection?: string[]
+  sample?: number
+  /** include tombstones; without it an observation answers `null` over one */
+  deleted?: boolean
+}
+
+/** What core hands a storage, written by `Query.parse`. */
+export interface Query {
+  id?: string
+  /** many identities at once; `State.objects` inits whichever of them are missing */
+  ids?: string[]
+  version?: number
+  criteria?: Node
+  search?: string
+  options?: Options
+}
+
+/**
+ * What core requires of a storage. Every member but `outbox` is called unguarded, so a
+ * storage that leaves one out throws where an operation needs it — a storage may serve
+ * only some scopes, and says so by failing rather than by declaring less.
+ */
+export interface Storage extends Connector {
+  /** scope `object` */
+  get(query: Query): Promise<Record | null>
+
+  /** scope `objects` */
+  find(query: Query): Promise<Record[]>
+
+  /** scope `stream` */
+  stream(query?: Query): Promise<Readable>
+
+  /**
+   * A transition's commit. `false` is a lost compare-and-swap, not an error. Where `row` is
+   * given, it is committed in the same transaction as the record or not at all.
+   */
+  store(record: Record, row?: Row): Promise<boolean>
+
+  /** a transition over `objects` */
+  massStore(records: Record[], rows?: Row[]): Promise<boolean>
+
+  /** an assignment; `null` where the query matched nothing */
+  upsert(query: Query, changeset: object, row?: Row): Promise<Record | null>
+
+  /** get-or-create, in one indivisible step */
+  ensure(
+    query: Query | undefined,
+    properties: object,
+    record: Record,
+    row?: Row
+  ): Promise<Record>
+
+  /** the driver's own handle, which an unmanaged operation is given as its state */
+  readonly raw: unknown
+
+  /**
+   * Present only where a row can be committed atomically with the entity. Its absence is
+   * what makes the runtime publish 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.
+   */
+  readonly outbox?: Outbox
+
+  /**
+   * Whether this storage applies `entity.migrations`. Absent is what a storage that does not
+   * says, and a component declaring migrations against one is refused at boot rather than
+   * starting with a structure nothing has made.
+   */
+  readonly migrates?: boolean
+}
+
+/**
+ * The subset of a component's entity declaration a storage reads. Structural, so that core
+ * names no type of `@toa.io/norm`, which depends on core.
+ */
+export interface Entity {
+  associated?: boolean
+  custom?: boolean
+  /** in the order they are applied; what a step is belongs to the storage that reads it */
+  migrations?: Migration[]
+}
+
+/** One file of a component's `migrations` directory, named after it. */
+export interface Migration {
+  id: string
+  steps: unknown[]
+}
+
+export interface StorageOptions {
+  /** whether the component publishes anything, and so needs a place to commit a row */
+  outbox?: boolean
+}
+
+export interface Factory {
+  storage(locator: Locator, entity: Entity, options?: StorageOptions): Storage
+}

package/source/unmanaged.ts

@@ -0,0 +1,8 @@
+import { Operation } from './operation.js'
+import type { Store } from './operation.js'
+
+export class Unmanaged extends Operation {
+  protected override async acquire(store: Store): Promise<void> {
+    store.state = this.scope.storage.raw
+  }
+}

package/test/call.fixtures.js

@@ -4,7 +4,9 @@ import { generate } from 'randomstring'
 
 // noinspection JSCheckFunctionSignatures
 export const transmission = {
-  request: mock.fn((request) => ({ [request.invalid ? 'exception' : 'output']: generate() })),
+  request: mock.fn((request) => ({
+    [request.invalid ? 'exception' : 'output']: generate()
+  })),
   link: mock.fn()
 }
 

package/test/call.test.js

@@ -1,9 +1,9 @@
-import { it, beforeEach, mock } from 'node:test'
+import { it, beforeEach } from 'node:test'
 import assert from 'node:assert/strict'
 import { isDeepStrictEqual } from 'node:util'
 
 import * as fixtures from './call.fixtures.js'
-import { Call } from '../src/call.js'
+import { Call } from '../source/call.js'
 
 let call
 
@@ -14,7 +14,13 @@ beforeEach(() => {
 })
 
 it('should depend on transmission', () => {
-  assert.ok(((invocation) => invocation.arguments.length === 1 && isDeepStrictEqual(invocation.arguments[0], call))(fixtures.transmission.link.mock.calls.at(-1) ?? { arguments: [] }))
+  assert.ok(
+    ((invocation) =>
+      invocation.arguments.length === 1 &&
+      isDeepStrictEqual(invocation.arguments[0], call))(
+      fixtures.transmission.link.mock.calls.at(-1) ?? { arguments: [] }
+    )
+  )
 })
 
 it('should call transmission', async () => {
@@ -22,7 +28,13 @@ it('should call transmission', async () => {
 
   await call.invoke(request)
 
-  assert.ok(fixtures.transmission.request.mock.calls.some((invocation) => invocation.arguments.length === 1 && isDeepStrictEqual(invocation.arguments[0], request)))
+  assert.ok(
+    fixtures.transmission.request.mock.calls.some(
+      (invocation) =>
+        invocation.arguments.length === 1 &&
+        isDeepStrictEqual(invocation.arguments[0], request)
+    )
+  )
 })
 
 it('should fit request', async () => {
@@ -30,7 +42,13 @@ it('should fit request', async () => {
 
   await call.invoke(request)
 
-  assert.ok(((invocation) => invocation.arguments.length === 1 && isDeepStrictEqual(invocation.arguments[0], request))(fixtures.contract.fit.mock.calls.at(-1) ?? { arguments: [] }))
+  assert.ok(
+    ((invocation) =>
+      invocation.arguments.length === 1 &&
+      isDeepStrictEqual(invocation.arguments[0], request))(
+      fixtures.contract.fit.mock.calls.at(-1) ?? { arguments: [] }
+    )
+  )
 })
 
 it('should return reply', async () => {
@@ -44,10 +62,13 @@ it('should return reply', async () => {
 it('should throw received exceptions', async () => {
   const request = fixtures.request().bad
 
-  await assert.rejects(call.invoke(request), (error) => { assert.notStrictEqual(error, undefined); return true })
+  await assert.rejects(call.invoke(request), (error) => {
+    assert.notStrictEqual(error, undefined)
+    return true
+  })
 })
 
-function resetCalls (target = [assert, fixtures], seen = new Set()) {
+function resetCalls(target = [assert, fixtures], seen = new Set()) {
   if (target === null || typeof target !== 'object' || seen.has(target)) return
 
   seen.add(target)

package/test/component.test.js

@@ -1,9 +1,8 @@
-import { describe, it, beforeEach, mock } from 'node:test'
+import { describe, it, beforeEach } from 'node:test'
 import assert from 'node:assert/strict'
 import { isDeepStrictEqual } from 'node:util'
 
-import { Component } from '../src/component.js'
-import { codes } from '../src/exceptions.js'
+import { Component } from '../source/component.js'
 import * as fixtures from './component.fixtures.js'
 import { AssertionError } from 'node:assert'
 
@@ -31,7 +30,13 @@ describe('Invocations', () => {
     const query = { test: Math.random() }
     await component.invoke(name, { input, query })
 
-    assert.ok(invocation.invoke.mock.calls.some((call) => call.arguments.length === 1 && isDeepStrictEqual(call.arguments[0], { input, query })))
+    assert.ok(
+      invocation.invoke.mock.calls.some(
+        (call) =>
+          call.arguments.length === 1 &&
+          isDeepStrictEqual(call.arguments[0], { input, query })
+      )
+    )
   })
 
   it('should return io', async () => {
@@ -41,7 +46,7 @@ describe('Invocations', () => {
   })
 })
 
-function resetCalls (target = [assert, fixtures], seen = new Set()) {
+function resetCalls(target = [assert, fixtures], seen = new Set()) {
   if (target === null || typeof target !== 'object' || seen.has(target)) return
 
   seen.add(target)

package/test/connector.fixtures.js

@@ -1,34 +1,34 @@
 import { random, timeout } from '@toa.io/generic'
-import { Connector } from '../src/connector.js'
+import { Connector } from '../source/connector.js'
 
 export class TestConnector extends Connector {
   #label
   #seq
 
-  constructor (label, seq) {
+  constructor(label, seq) {
     super()
 
     this.#seq = seq
     this.#label = label
   }
 
-  async open () {
+  async open() {
     await timeout(random(10))
     this.#seq.push(`+${this.#label}`)
   }
 
-  async close () {
+  async close() {
     await timeout(random(10))
     this.#seq.push(`-${this.#label}`)
   }
 
-  async dispose () {
+  async dispose() {
     this.#seq.push(`*${this.#label}`)
   }
 }
 
 export class FailingConnector extends Connector {
-  async open () {
+  async open() {
     await timeout(random(10))
     throw new Error('FailingConnector')
   }
@@ -36,7 +36,7 @@ export class FailingConnector extends Connector {
 
 /** Stands for a connector waiting for something that never arrives. */
 export class StuckConnector extends Connector {
-  async open () {
+  async open() {
     return new Promise(() => undefined)
   }
 }

package/test/connector.test.js

@@ -87,7 +87,10 @@ describe('dependencies', () => {
   })
 
   it('should throw on empty array', async () => {
-    assert.throws(() => a.depends([]), (error) => /must not be empty/.test(error.message))
+    assert.throws(
+      () => a.depends([]),
+      (error) => /must not be empty/.test(error.message)
+    )
   })
 
   it('should await 2-way dependencies', async () => {
@@ -143,7 +146,17 @@ describe('dependencies', () => {
 
     await b.disconnect()
 
-    assert.deepStrictEqual(sequence, ['+c', '+a', '+b', '-a', '*a', '-b', '-c', '*c', '*b'])
+    assert.deepStrictEqual(sequence, [
+      '+c',
+      '+a',
+      '+b',
+      '-a',
+      '*a',
+      '-b',
+      '-c',
+      '*c',
+      '*b'
+    ])
   })
 
   it('should throw if depends not on Connector', async () => {

package/test/context.fixtures.js

@@ -1,6 +1,6 @@
 import { mock } from 'node:test'
 
-import { Connector } from '../src/connector.js'
+import { Connector } from '../source/connector.js'
 
 export const local = {
   link: mock.fn()

package/test/context.test.js

@@ -1,10 +1,10 @@
-import { describe, it, beforeEach, mock } from 'node:test'
+import { describe, it, beforeEach } from 'node:test'
 import assert from 'node:assert/strict'
 
 import * as fixtures from './context.fixtures.js'
-import { Context } from '../src/context.js'
+import { Context } from '../source/context.js'
 
-/** @type {toa.core.Context} */
+/** @type {import('@toa.io/core').Context} */
 let context
 
 beforeEach(() => {
@@ -29,7 +29,7 @@ describe('call', () => {
   })
 })
 
-function resetCalls (target = [assert, fixtures], seen = new Set()) {
+function resetCalls(target = [assert, fixtures], seen = new Set()) {
   if (target === null || typeof target !== 'object' || seen.has(target)) return
 
   seen.add(target)

package/test/contract/conditions.test.js

@@ -4,7 +4,7 @@ import { isDeepStrictEqual } from 'node:util'
 
 import { generate } from 'randomstring'
 
-import { Contract } from '../../src/contract/contract.js'
+import { Contract } from '../../source/contract/contract.js'
 import * as fixtures from './contract.fixtures.js'
 
 let contract
@@ -18,7 +18,11 @@ it('should fit value', () => {
 
   contract.fit(value)
 
-  assert.ok(fixtures.schema.fit.mock.calls.some((call) => call.arguments.length === 1 && isDeepStrictEqual(call.arguments[0], value)))
+  assert.ok(
+    fixtures.schema.fit.mock.calls.some(
+      (call) => call.arguments.length === 1 && isDeepStrictEqual(call.arguments[0], value)
+    )
+  )
 })
 
 it('should throw on invalid value', () => {

package/test/contract/contract.fixtures.js

@@ -1,9 +1,8 @@
 import { mock } from 'node:test'
 
 import { generate } from 'randomstring'
-import { readFileSync } from 'node:fs'
-import { load as parseYAML } from 'js-yaml'
-import { resolve } from 'path'
+
+import { query as querySchema } from '../../source/contract/schemas.js'
 
 // noinspection JSCheckFunctionSignatures
 export const schema = {
@@ -21,7 +20,7 @@ export const schemas = {
     type: 'object',
     properties: {
       input: { type: 'null' },
-      query: parseYAML(readFileSync(resolve(import.meta.dirname, '../../src/contract/schemas/query.yaml'), 'utf8')),
+      query: querySchema,
       authentic: { type: 'boolean' }
     },
     additionalProperties: true

package/test/contract/request.test.js

@@ -6,8 +6,8 @@ import { isDeepStrictEqual } from 'node:util'
 import clone from 'clone-deep'
 import { generate } from 'randomstring'
 
-import { Request } from '../../src/contract/request.js'
-import { Contract } from '../../src/contract/contract.js'
+import { Request } from '../../source/contract/request.js'
+import { Contract } from '../../source/contract/contract.js'
 import * as fixtures from './contract.fixtures.js'
 
 // the base is real; what it was constructed with and told to fit is observable
@@ -22,7 +22,7 @@ beforeEach(() => {
   contract = new Request(fixtures.schema, {})
 })
 
-const dummy = { schema: { properties: {} } }
+const dummy = { properties: {} }
 
 it('should extend Conditions', () => {
   assert.ok(contract instanceof Contract)
@@ -34,8 +34,11 @@ it('should fit request', () => {
 
   contract.fit(request)
 
-  assert.ok(fit.mock.calls.some((call) =>
-    call.this === contract && isDeepStrictEqual(call.arguments[0], request)))
+  assert.ok(
+    fit.mock.calls.some(
+      (call) => call.this === contract && isDeepStrictEqual(call.arguments[0], request)
+    )
+  )
 })
 
 describe('schema', () => {
@@ -70,21 +73,45 @@ describe('schema', () => {
 
   it('should require query if declaration.query is true', () => {
     schema.required = ['query']
-    assert.ok(['query'].every((item) => Request.schema({ query: true }, dummy).required.some((candidate) => isDeepStrictEqual(candidate, item))))
+    assert.ok(
+      ['query'].every((item) =>
+        Request.schema({ query: true }, dummy).required.some((candidate) =>
+          isDeepStrictEqual(candidate, item)
+        )
+      )
+    )
   })
 
   it('should forbid projection for non observations', () => {
-    assert.strictEqual(Request.schema({ type: 'transition' }, dummy).properties.query.properties.projection, undefined)
-
-    assert.strictEqual(Request.schema({ type: 'assignment' }, dummy).properties.query.properties.projection, undefined)
-
-    assert.notStrictEqual(Request.schema({ type: 'observation' }, dummy).properties.query.properties.projection, undefined)
+    assert.strictEqual(
+      Request.schema({ type: 'transition' }, dummy).properties.query.properties
+        .projection,
+      undefined
+    )
+
+    assert.strictEqual(
+      Request.schema({ type: 'assignment' }, dummy).properties.query.properties
+        .projection,
+      undefined
+    )
+
+    assert.notStrictEqual(
+      Request.schema({ type: 'observation' }, dummy).properties.query.properties
+        .projection,
+      undefined
+    )
   })
 
   it('should forbid version for observations', () => {
-    assert.notStrictEqual(Request.schema({ type: 'transition' }, dummy).properties.query.properties.version, undefined)
-
-    assert.strictEqual(Request.schema({ type: 'observation' }, dummy).properties.query.properties.version, undefined)
+    assert.notStrictEqual(
+      Request.schema({ type: 'transition' }, dummy).properties.query.properties.version,
+      undefined
+    )
+
+    assert.strictEqual(
+      Request.schema({ type: 'observation' }, dummy).properties.query.properties.version,
+      undefined
+    )
   })
 
   it('should allow omit, limit only for set observations', () => {
@@ -94,18 +121,24 @@ describe('schema', () => {
     assert.strictEqual(transition.omit, undefined)
     assert.strictEqual(transition.limit, undefined)
 
-    const object = Request.schema({
-      type: 'observation',
-      scope: 'object'
-    }, dummy).properties.query.properties
+    const object = Request.schema(
+      {
+        type: 'observation',
+        scope: 'object'
+      },
+      dummy
+    ).properties.query.properties
 
     assert.strictEqual(object.omit, undefined)
     assert.strictEqual(object.limit, undefined)
 
-    const objects = Request.schema({
-      type: 'observation',
-      scope: 'objects'
-    }, dummy).properties.query.properties
+    const objects = Request.schema(
+      {
+        type: 'observation',
+        scope: 'objects'
+      },
+      dummy
+    ).properties.query.properties
 
     assert.notStrictEqual(objects.omit, undefined)
     assert.notStrictEqual(objects.limit, undefined)
@@ -113,16 +146,13 @@ describe('schema', () => {
 })
 
 describe('source', () => {
-
-
   const compile = (definition, entity) =>
-    schemas.schema(Request.schema(definition, entity), { removeAdditional: true })
+    schemas.schema(Request.schema(definition, entity))
 
-  it('should declare source', () => {
+  it('should not hold source to a schema', () => {
     const schema = Request.schema({}, dummy)
 
-    assert.notStrictEqual(schema.properties.source, undefined)
-    assert.deepStrictEqual(schema.properties.source.additionalProperties, false)
+    assert.strictEqual(schema.properties.source, undefined)
   })
 
   it('should pass known source variants', () => {
@@ -140,18 +170,22 @@ describe('source', () => {
     }
   })
 
-  // `source` crosses the wire and keys the introspection map, so whatever
-  // a peer adds to it must not survive
-  it('should strip unknown source properties', () => {
+  // whatever a peer puts beside the keys this release knows travels through: what reads
+  // `source` takes the keys it knows, and the contract does not fail a call over the rest
+  it('should pass a source a peer added to', () => {
     const schema = compile({}, undefined)
-    const request = { input: null, query: null, source: { service: 'exposition', evil: 'x' } }
+    const request = {
+      input: null,
+      query: null,
+      source: { service: 'exposition', mystery: 'x' }
+    }
 
     assert.deepStrictEqual(schema.fit(request), null)
-    assert.deepStrictEqual(request.source, { service: 'exposition' })
+    assert.deepStrictEqual(request.source, { service: 'exposition', mystery: 'x' })
   })
 })
 
-function resetCalls (target = [assert, clone, fixtures, dummy], seen = new Set()) {
+function resetCalls(target = [assert, clone, fixtures, dummy], seen = new Set()) {
   if (target === null || typeof target !== 'object' || seen.has(target)) return
 
   seen.add(target)

package/test/discovery.test.js

@@ -3,8 +3,8 @@ import assert from 'node:assert/strict'
 import { isDeepStrictEqual } from 'node:util'
 
 import { console } from 'openspan'
-import { Connector } from '../src/connector.js'
-import { Discovery } from '../src/discovery.js'
+import { Connector } from '../source/connector.js'
+import { Discovery } from '../source/discovery.js'
 
 class Lookup extends Connector {
   invoke = mock.fn(async () => ({ operations: {} }))
@@ -60,5 +60,12 @@ it('should keep warning while a lookup is unanswered', async () => {
 
   assert.strictEqual(warn.mock.callCount(), 2)
 
-  assert.ok(((call) => call.arguments.length === 2 && isDeepStrictEqual(call.arguments[0], 'Waiting for lookup response') && isDeepStrictEqual(call.arguments[1], { component: locator.id, waiting: 10 }))(warn.mock.calls.at(-1) ?? { arguments: [] }))
+  assert.ok(
+    ((call) =>
+      call.arguments.length === 2 &&
+      isDeepStrictEqual(call.arguments[0], 'Waiting for lookup response') &&
+      isDeepStrictEqual(call.arguments[1], { component: locator.id, waiting: 10 }))(
+      warn.mock.calls.at(-1) ?? { arguments: [] }
+    )
+  )
 })