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

package/source/types/request.ts

@@ -0,0 +1,54 @@
+import type { Exception } from '../exceptions.js'
+
+/**
+ * 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?: string[]
+  criteria?: string
+  search?: string
+  sample?: number
+  omit?: number
+  limit?: number
+  sort?: string[]
+  projection?: Array<string & keyof Entity>
+  version?: number
+  deleted?: boolean
+}
+
+/** 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 }
+  | { 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
+  /** W3C traceparent */
+  telemetry?: string
+  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
+  exception?: Exception
+}

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,134 @@
+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 `migrations` directory, named after it — the component's own, or a prototype's,
+ * which every descendant applies to its collection ahead of its own.
+ */
+export interface Migration {
+  id: string
+  steps: unknown[]
+  /** the prototype it is inherited from; absent on the component's own */
+  prototype?: string
+}
+
+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

@@ -1,18 +1,20 @@
-'use strict'
+import { mock } from 'node:test'
 
-const { generate } = require('randomstring')
+import { generate } from 'randomstring'
 
 // noinspection JSCheckFunctionSignatures
-const transmission = {
-  request: jest.fn((request) => ({ [request.invalid ? 'exception' : 'output']: generate() })),
-  link: jest.fn()
+export const transmission = {
+  request: mock.fn((request) => ({
+    [request.invalid ? 'exception' : 'output']: generate()
+  })),
+  link: mock.fn()
 }
 
-const contract = {
-  fit: jest.fn(() => null)
+export const contract = {
+  fit: mock.fn(() => null)
 }
 
-const request = () => ({
+export const request = () => ({
   ok: {
     input: { [generate()]: generate() },
     query: { [generate()]: generate() }
@@ -21,7 +23,3 @@ const request = () => ({
     invalid: true
   }
 })
-
-exports.transmission = transmission
-exports.contract = contract
-exports.request = request

package/test/call.test.js

@@ -1,18 +1,26 @@
-'use strict'
+import { it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { isDeepStrictEqual } from 'node:util'
 
-const fixtures = require('./call.fixtures')
-const { Call } = require('../src/call')
+import * as fixtures from './call.fixtures.js'
+import { Call } from '../source/call.js'
 
 let call
 
 beforeEach(() => {
-  jest.clearAllMocks()
+  resetCalls()
 
   call = new Call(fixtures.transmission, fixtures.contract)
 })
 
 it('should depend on transmission', () => {
-  expect(fixtures.transmission.link).toHaveBeenLastCalledWith(call)
+  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 () => {
@@ -20,7 +28,13 @@ it('should call transmission', async () => {
 
   await call.invoke(request)
 
-  expect(fixtures.transmission.request).toHaveBeenCalledWith(request)
+  assert.ok(
+    fixtures.transmission.request.mock.calls.some(
+      (invocation) =>
+        invocation.arguments.length === 1 &&
+        isDeepStrictEqual(invocation.arguments[0], request)
+    )
+  )
 })
 
 it('should fit request', async () => {
@@ -28,7 +42,13 @@ it('should fit request', async () => {
 
   await call.invoke(request)
 
-  expect(fixtures.contract.fit).toHaveBeenLastCalledWith(request)
+  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 () => {
@@ -36,11 +56,24 @@ it('should return reply', async () => {
 
   const reply = await call.invoke(request)
 
-  expect(reply).toStrictEqual(fixtures.transmission.request.mock.results[0].value.output)
+  assert.deepStrictEqual(reply, fixtures.transmission.request.mock.calls[0].result.output)
 })
 
 it('should throw received exceptions', async () => {
   const request = fixtures.request().bad
 
-  await expect(call.invoke(request)).rejects.toBeDefined()
+  await assert.rejects(call.invoke(request), (error) => {
+    assert.notStrictEqual(error, undefined)
+    return true
+  })
 })
+
+function resetCalls(target = [assert, fixtures], seen = new Set()) {
+  if (target === null || typeof target !== 'object' || seen.has(target)) return
+
+  seen.add(target)
+
+  for (const value of Object.values(target))
+    if (typeof value === 'function' && value.mock !== undefined) value.mock.resetCalls()
+    else resetCalls(value, seen)
+}

package/test/component.fixtures.js

@@ -1,10 +1,10 @@
-'use strict'
+import { mock } from 'node:test'
 
-const randomstring = require('randomstring')
+import randomstring from 'randomstring'
 
-const invocation = () => jest.fn(() => randomstring.generate())
+const invocation = () => mock.fn(() => randomstring.generate())
 
-const invocations = {
+export const invocations = {
   foo: {
     invoke: invocation('foo'),
     link: () => null
@@ -15,7 +15,4 @@ const invocations = {
   }
 }
 
-const locator = {}
-
-exports.invocations = invocations
-exports.locator = locator
+export const locator = {}

package/test/component.test.js

@@ -1,8 +1,10 @@
-'use strict'
+import { describe, it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { isDeepStrictEqual } from 'node:util'
 
-const { Component } = require('../src/component')
-const { codes } = require('../src/exceptions')
-const fixtures = require('./component.fixtures')
+import { Component } from '../source/component.js'
+import * as fixtures from './component.fixtures.js'
+import { AssertionError } from 'node:assert'
 
 describe('Invocations', () => {
   const name = ['foo', 'bar'][Math.floor(2 * Math.random())]
@@ -10,18 +12,17 @@ describe('Invocations', () => {
   const component = new Component(fixtures.locator, fixtures.invocations)
 
   beforeEach(() => {
-    jest.clearAllMocks()
+    resetCalls()
   })
 
   it('should invoke', async () => {
     await component.invoke(name)
 
-    expect(invocation.invoke).toBeCalled()
+    assert.ok(invocation.invoke.mock.callCount() > 0)
   })
 
   it('should throw on unknown invocation name', async () => {
-    await expect(() => component.invoke('baz'))
-      .rejects.toMatchObject({ code: codes.NotImplemented })
+    await assert.rejects(() => component.invoke('baz'), AssertionError)
   })
 
   it('should invoke input and query', async () => {
@@ -29,12 +30,28 @@ describe('Invocations', () => {
     const query = { test: Math.random() }
     await component.invoke(name, { input, query })
 
-    expect(invocation.invoke).toBeCalledWith({ 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 () => {
     const io = await component.invoke(name)
 
-    expect(io).toBe(fixtures.invocations[name].invoke.mock.results[0].value)
+    assert.strictEqual(io, fixtures.invocations[name].invoke.mock.calls[0].result)
   })
 })
+
+function resetCalls(target = [assert, fixtures], seen = new Set()) {
+  if (target === null || typeof target !== 'object' || seen.has(target)) return
+
+  seen.add(target)
+
+  for (const value of Object.values(target))
+    if (typeof value === 'function' && value.mock !== undefined) value.mock.resetCalls()
+    else resetCalls(value, seen)
+}

package/test/connector.fixtures.js

@@ -1,40 +1,56 @@
-'use strict'
+import { random, timeout } from '@toa.io/generic'
+import { Connector } from '../source/connector.js'
 
-const { random, timeout } = require('@toa.io/generic')
-const { Connector } = require('../src/connector')
-
-class TestConnector extends Connector {
+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}`)
   }
 }
 
-class FailingConnector extends Connector {
-  async open () {
+export class FailingConnector extends Connector {
+  async open() {
     await timeout(random(10))
     throw new Error('FailingConnector')
   }
 }
 
-exports.TestConnector = TestConnector
-exports.FailingConnector = FailingConnector
+/** Stands for a connector whose connection lands once it has been disconnected. */
+export class LateConnector extends Connector {
+  #arrive
+
+  async open() {
+    await new Promise((resolve) => (this.#arrive = resolve))
+  }
+
+  /** Lets the connection land. */
+  arrive() {
+    this.#arrive()
+  }
+}
+
+/** Stands for a connector waiting for something that never arrives. */
+export class StuckConnector extends Connector {
+  async open() {
+    return new Promise(() => undefined)
+  }
+}