@toa.io/extensions.cadence 1.0.0-alpha.284 → 1.0.0-alpha.286

package/source/Dispatcher.ts

@@ -2,7 +2,7 @@ import { console } from 'openspan'
 import { Connector, Locator } from '@toa.io/core'
 import { BATCH, DISCRETENESS, LANES, number } from './const.js'
 import type { Local } from './Local.js'
-import type { atomicity } from '@toa.io/core'
+import type { atomicity } from '@toa.io/core/types'
 
 /**
  * Makes the calls that were put off.
@@ -37,8 +37,11 @@ export class Dispatcher extends Connector {
   private scanning = false
   private closing = false
 
-  public constructor (metronome: Local, resolve: (locator: Locator) => Local,
-    atom: atomicity.Atom) {
+  public constructor(
+    metronome: Local,
+    resolve: (locator: Locator) => Local,
+    atom: atomicity.Atom
+  ) {
     super()
 
     this.metronome = metronome
@@ -50,15 +53,19 @@ export class Dispatcher extends Connector {
     this.depends(atom)
   }
 
-  protected override async open (): Promise<void> {
-    this.timer = setInterval(() => { this.tick() }, this.discreteness)
+  protected override async open(): Promise<void> {
+    this.timer = setInterval(() => {
+      this.tick()
+    }, this.discreteness)
     this.timer.unref()
 
     // a lane changing hands is when its rows become this replica's, or stop being
-    this.off = this.atom.onassigned(() => { this.adopt() })
+    this.off = this.atom.onassigned(() => {
+      this.adopt()
+    })
   }
 
-  protected override async close (): Promise<void> {
+  protected override async close(): Promise<void> {
     this.closing = true
 
     this.off?.()
@@ -72,14 +79,18 @@ export class Dispatcher extends Connector {
   }
 
   /** One scan at a time: a slow one must not have another started underneath it. */
-  private tick (): void {
+  private tick(): void {
     if (this.scanning || this.closing) return
 
     this.scanning = true
 
     void this.scan()
-      .catch((error: unknown) => { console.error('Delayed calls scan failed', { error }) })
-      .finally(() => { this.scanning = false })
+      .catch((error: unknown) => {
+        console.error('Delayed calls scan failed', { error })
+      })
+      .finally(() => {
+        this.scanning = false
+      })
   }
 
   /**
@@ -87,7 +98,7 @@ export class Dispatcher extends Connector {
    * whoever holds them now will arm them — and a scan runs at once rather than at the next
    * interval, so lanes just acquired are not left waiting.
    */
-  private adopt (): void {
+  private adopt(): void {
     // nothing owned is nothing held: what was armed under a claim this replica no longer has
     // belongs to whoever has it now, and firing it anyway is the call twice
     this.disarm(this.atom.slots(LANES) ?? [])
@@ -96,7 +107,7 @@ export class Dispatcher extends Connector {
   }
 
   /** What is armed for a lane this replica no longer holds: whoever holds it now will arm it. */
-  private disarm (lanes: number[]): void {
+  private disarm(lanes: number[]): void {
     for (const [id, { timer, lane }] of this.armed) {
       if (lanes.includes(lane)) continue
 
@@ -105,7 +116,7 @@ export class Dispatcher extends Connector {
     }
   }
 
-  private async scan (): Promise<void> {
+  private async scan(): Promise<void> {
     const lanes = this.atom.slots(LANES)
 
     if (lanes === null || lanes.length === 0) return
@@ -115,14 +126,14 @@ export class Dispatcher extends Connector {
     const now = Date.now()
     const until = now + this.discreteness
 
-    const rows = await this.metronome.invoke('enumerate', {
+    const rows = (await this.metronome.invoke('enumerate', {
       query: {
         // a call nothing was running to make in time has expired, and is simply not read
         criteria: `lane=in=(${lanes.join(',')});due<${until};expires>${now}`,
         sort: ['due:asc'],
         limit: BATCH
       }
-    }) as Row[]
+    })) as Row[]
 
     for (const row of rows) this.arm(row)
   }
@@ -131,10 +142,15 @@ export class Dispatcher extends Connector {
    * A row already armed is left alone: a scan reads what it read before, because a row stays
    * until its call has been made.
    */
-  private arm (row: Row): void {
+  private arm(row: Row): void {
     if (this.armed.has(row.id) || this.called.has(row.id)) return
 
-    const timer = setTimeout(() => { void this.dispatch(row) }, Math.max(row.due - Date.now(), 0))
+    const timer = setTimeout(
+      () => {
+        void this.dispatch(row)
+      },
+      Math.max(row.due - Date.now(), 0)
+    )
 
     timer.unref()
     this.armed.set(row.id, { timer, lane: row.lane })
@@ -145,7 +161,7 @@ export class Dispatcher extends Connector {
    * makes the call twice, and the other order would lose it. It travels as a task, so the
    * broker holds it if the target is not there to take it.
    */
-  private async dispatch (row: Row): Promise<void> {
+  private async dispatch(row: Row): Promise<void> {
     if (this.closing) {
       this.armed.delete(row.id)
 
@@ -170,20 +186,27 @@ export class Dispatcher extends Connector {
      *
      * Skipped, as a pulse skips: reported, and the row settled on the attempt either way.
      */
-    await local.invoke(endpoint, { input: null, ...row.request, task: true })
+    await local
+      .invoke(endpoint, { input: null, ...row.request, task: true })
       .catch((error: unknown) => {
-        console.error('Delayed call failed', { endpoint: row.endpoint, id: row.id, error })
+        console.error('Delayed call failed', {
+          endpoint: row.endpoint,
+          id: row.id,
+          error
+        })
       })
       // held for as long as the call is, so `armed` answers what this replica has in hand
       // rather than what it has a timer for
-      .finally(() => { this.armed.delete(row.id) })
+      .finally(() => {
+        this.armed.delete(row.id)
+      })
   }
 
   /**
    * A remote is resolved once per target and held: it opens a connection, and one nothing
    * depends on would outlive the dispatcher that made it.
    */
-  private target (locator: Locator): Local {
+  private target(locator: Locator): Local {
     const local = this.resolve(locator)
 
     if (!this.targets.has(local)) {
@@ -195,7 +218,7 @@ export class Dispatcher extends Connector {
   }
 
   /** One write for many rows, which is why the ids are held rather than settled one by one. */
-  private async settle (): Promise<void> {
+  private async settle(): Promise<void> {
     if (this.called.size === 0) return
 
     const ids = [...this.called]

package/source/Factory.ts

@@ -6,7 +6,7 @@ import { Dispatcher } from './Dispatcher.js'
 import { Local } from './Local.js'
 import { Pulse } from './Pulse.js'
 import type { Declaration } from './types.js'
-import type { extensions } from '@toa.io/core'
+import type { extensions } from '@toa.io/core/types'
 
 export class Factory implements extensions.Factory {
   private readonly host: Host
@@ -14,7 +14,7 @@ export class Factory implements extensions.Factory {
   /** one per component, however much of this extension calls through it */
   private readonly locals: Record<string, Local> = {}
 
-  public constructor (host: Host) {
+  public constructor(host: Host) {
     this.host = host
   }
 
@@ -25,10 +25,13 @@ export class Factory implements extensions.Factory {
    * A tenant is created before the components of its composition are, which is why nothing here
    * reaches for one.
    */
-  public tenant (locator: Locator, declaration: object): Connector {
+  public tenant(locator: Locator, declaration: object): Connector {
     if (mine(locator))
-      return new Dispatcher(this.metronome(), (target) => this.local(target),
-        this.host.atom(locator.id))
+      return new Dispatcher(
+        this.metronome(),
+        (target) => this.local(target),
+        this.host.atom(locator.id)
+      )
 
     const tenant = new Connector()
     const pulses = declaration as Declaration | null
@@ -46,27 +49,27 @@ export class Factory implements extensions.Factory {
   }
 
   /** `context.delay` — for every component but the one that keeps the calls. */
-  public aspect (locator: Locator): extensions.Aspect | extensions.Aspect[] {
+  public aspect(locator: Locator): extensions.Aspect | extensions.Aspect[] {
     if (mine(locator)) return []
 
     return new Aspect(this.metronome())
   }
 
-  public service (): Connector {
+  public service(): Connector {
     return new Composition(this.host)
   }
 
-  private metronome (): Local {
+  private metronome(): Local {
     return this.local(new Locator(COMPONENT, NAMESPACE))
   }
 
-  private local (locator: Locator): Local {
+  private local(locator: Locator): Local {
     return (this.locals[locator.id] ??= new Local(this.host, locator))
   }
 }
 
 /** Whether this is a component the extension ships rather than one of the application's. */
-function mine (locator: Locator): boolean {
+function mine(locator: Locator): boolean {
   return locator.namespace === NAMESPACE
 }
 

package/source/Local.ts

@@ -1,6 +1,7 @@
 import { Connector } from '@toa.io/core'
 import type { Host } from './Factory.js'
-import type { Locator, Remote, Reply, Request } from '@toa.io/core'
+import type { Locator, Remote } from '@toa.io/core'
+import type { Reply, Request } from '@toa.io/core/types'
 
 /**
  * The component a tenant belongs to, as something to call.
@@ -14,20 +15,20 @@ export class Local extends Connector {
   private readonly locator: Locator
   private remote?: Promise<Remote>
 
-  public constructor (host: Host, locator: Locator) {
+  public constructor(host: Host, locator: Locator) {
     super()
 
     this.host = host
     this.locator = locator
   }
 
-  public async invoke (endpoint: string, request: Request): Promise<Reply> {
+  public async invoke(endpoint: string, request: Request): Promise<Reply> {
     this.remote ??= this.locate()
 
     return await (await this.remote).invoke(endpoint, request)
   }
 
-  private async locate (): Promise<Remote> {
+  private async locate(): Promise<Remote> {
     const remote = await this.host.remote(this.locator)
 
     this.depends(remote)

package/source/Pulse.test.ts

@@ -3,7 +3,8 @@ import assert from 'node:assert/strict'
 
 import { Pulse } from './Pulse.js'
 import type { Local } from './Local.js'
-import type { Locator, Request, atomicity } from '@toa.io/core'
+import type { Locator } from '@toa.io/core'
+import type { Request, atomicity } from '@toa.io/core/types'
 
 type Invoke = (endpoint: string, request: Request) => Promise<unknown>
 type Slots = (total: number) => number[] | null
@@ -17,11 +18,16 @@ const DAY = 24 * HOUR
 
 const locator = { id: 'tea.pots' } as Locator
 
-const range = (total: number): number[] => Array.from({ length: total }, (_, index) => index)
+const range = (total: number): number[] =>
+  Array.from({ length: total }, (_, index) => index)
 
 /** what a Pulse reaches for, with a lifecycle it can connect through */
-const connector = (properties: object): any =>
-  ({ ...properties, link: mock.fn(), connect: async () => {}, disconnect: async () => {} })
+const connector = (properties: object): any => ({
+  ...properties,
+  link: mock.fn(),
+  connect: async () => {},
+  disconnect: async () => {}
+})
 
 const create = (cycle: number, intervals: number): Pulse =>
   new Pulse({ locator, endpoint: 'sweep', cycle, intervals }, local, atom)
@@ -37,7 +43,6 @@ const advance = async (ms: number): Promise<void> => {
 const intervals = (): number[] =>
   local.invoke.mock.calls.map((call) => (call.arguments[1].input as { i: number }).i)
 
-
 beforeEach(() => {
   mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 0 })
 
@@ -72,7 +77,10 @@ it('should give every interval of a cycle that does not divide evenly', () => {
     now = pulse.boundary(now)
   }
 
-  assert.deepStrictEqual([...seen].sort((a, b) => a - b), [0, 1, 2, 3, 4, 5, 6])
+  assert.deepStrictEqual(
+    [...seen].sort((a, b) => a - b),
+    [0, 1, 2, 3, 4, 5, 6]
+  )
   assert.strictEqual(now, DAY * SECOND, 'seven boundaries land exactly on the next cycle')
 })
 
@@ -130,8 +138,10 @@ it('should call once per interval, and every interval of a cycle', async () => {
 
   for (let hour = 0; hour < 24; hour++) await advance(HOUR * SECOND)
 
-  assert.deepStrictEqual(intervals(), [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16,
-    17, 18, 19, 20, 21, 22, 23, 0])
+  assert.deepStrictEqual(
+    intervals(),
+    [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 0]
+  )
 })
 
 it('should keep calling a cycle it is not splitting', async () => {
@@ -167,13 +177,17 @@ it('should not call an interval it acquired after the boundary', async () => {
 
   await advance(30 * 60 * SECOND) // and half an hour later it is
 
-  assert.strictEqual(local.invoke.mock.callCount(), 0,
-    'the replica that held it at the boundary is the only one that could have called')
+  assert.strictEqual(
+    local.invoke.mock.callCount(),
+    0,
+    'the replica that held it at the boundary is the only one that could have called'
+  )
 })
 
 it('should not call an interval another replica owns', async () => {
   atom.slots.mock.mockImplementation((total) =>
-    range(total).filter((slot) => slot % 2 === 0))
+    range(total).filter((slot) => slot % 2 === 0)
+  )
 
   const pulse = create(DAY, 24)
 
@@ -190,8 +204,12 @@ it('should not call an interval another replica owns', async () => {
 it('should not start a call while the one before has not returned', async () => {
   let release: () => void = () => {}
 
-  local.invoke.mock.mockImplementation(async () =>
-    await new Promise<void>((resolve) => { release = resolve }))
+  local.invoke.mock.mockImplementation(
+    async () =>
+      await new Promise<void>((resolve) => {
+        release = resolve
+      })
+  )
 
   const pulse = create(DAY, 24)
 
@@ -211,7 +229,9 @@ it('should not start a call while the one before has not returned', async () =>
 })
 
 it('should keep its cadence when a call raises', async () => {
-  local.invoke.mock.mockImplementationOnce(async () => { throw new Error('nope') })
+  local.invoke.mock.mockImplementationOnce(async () => {
+    throw new Error('nope')
+  })
 
   const pulse = create(DAY, 24)
 
@@ -220,8 +240,11 @@ it('should keep its cadence when a call raises', async () => {
   await advance(HOUR * SECOND)
   await advance(HOUR * SECOND)
 
-  assert.strictEqual(local.invoke.mock.callCount(), 2,
-    'the interval that raised is skipped, and the next one is called')
+  assert.strictEqual(
+    local.invoke.mock.callCount(),
+    2,
+    'the interval that raised is skipped, and the next one is called'
+  )
 })
 
 it('should wait out a cycle longer than one timer in instalments', async () => {
@@ -243,15 +266,21 @@ it('should wait for a call in flight before closing', async () => {
   let release: () => void = () => {}
   let closed = false
 
-  local.invoke.mock.mockImplementation(async () =>
-    await new Promise<void>((resolve) => { release = resolve }))
+  local.invoke.mock.mockImplementation(
+    async () =>
+      await new Promise<void>((resolve) => {
+        release = resolve
+      })
+  )
 
   const pulse = create(DAY, 24)
 
   await pulse.connect()
   await advance(HOUR * SECOND)
 
-  const closing = pulse.disconnect().then(() => { closed = true })
+  const closing = pulse.disconnect().then(() => {
+    closed = true
+  })
 
   await advance(0)
   assert.strictEqual(closed, false, 'the call is still running')

package/source/Pulse.ts

@@ -2,7 +2,8 @@ import { console } from 'openspan'
 import { Connector } from '@toa.io/core'
 import type { Local } from './Local.js'
 import type { SpanOptions } from 'openspan'
-import type { Locator, atomicity } from '@toa.io/core'
+import type { Locator } from '@toa.io/core'
+import type { atomicity } from '@toa.io/core/types'
 
 /**
  * A recurring call to an operation of its own component, on the cadence its manifest states.
@@ -43,7 +44,7 @@ export class Pulse extends Connector {
 
   private closing = false
 
-  public constructor (definition: Definition, local: Local, atom: atomicity.Atom) {
+  public constructor(definition: Definition, local: Local, atom: atomicity.Atom) {
     super()
 
     const { locator, endpoint, cycle, intervals } = definition
@@ -75,17 +76,17 @@ export class Pulse extends Connector {
    * as large as the cycle has seconds, so their product leaves the range a double is exact in
    * for a long cycle cut finely. It is evaluated once per interval, where this costs nothing.
    */
-  public ordinal (now: number): number {
-    return Number(BigInt(now) * BigInt(this.n) / BigInt(this.cycle))
+  public ordinal(now: number): number {
+    return Number((BigInt(now) * BigInt(this.n)) / BigInt(this.cycle))
   }
 
   /** Which of the cycle's intervals `now` falls in. */
-  public index (now: number): number {
+  public index(now: number): number {
     return this.ordinal(now) % this.n
   }
 
   /** When the interval `now` falls in gives way to the next one. */
-  public boundary (now: number): number {
+  public boundary(now: number): number {
     const cycle = BigInt(this.cycle)
     const n = BigInt(this.n)
     const next = BigInt(this.ordinal(now) + 1)
@@ -94,7 +95,7 @@ export class Pulse extends Connector {
     return Number((next * cycle + n - 1n) / n)
   }
 
-  protected override async open (): Promise<void> {
+  protected override async open(): Promise<void> {
     // whatever interval it is now, this replica was not there when it began, so it is not
     // this one's to call — the first call is at the next boundary
     this.fired = this.ordinal(Date.now())
@@ -102,7 +103,7 @@ export class Pulse extends Connector {
     this.arm()
   }
 
-  protected override async close (): Promise<void> {
+  protected override async close(): Promise<void> {
     this.closing = true
 
     clearTimeout(this.timer)
@@ -110,11 +111,10 @@ export class Pulse extends Connector {
     // a call still running holds the remote it was made through, which is torn down after
     // this returns. Bounded, because an operation that never returns would outlive any
     // grace period and the interval is over either way
-    if (this.firing !== undefined)
-      await Promise.race([this.firing, delay(DRAIN)])
+    if (this.firing !== undefined) await Promise.race([this.firing, delay(DRAIN)])
   }
 
-  private arm (): void {
+  private arm(): void {
     const now = Date.now()
 
     // a delay past this fires at once rather than late, so a long cycle is waited out in
@@ -125,7 +125,7 @@ export class Pulse extends Connector {
     this.timer.unref()
   }
 
-  private tick (): void {
+  private tick(): void {
     if (this.closing) return
 
     const ordinal = this.ordinal(Date.now())
@@ -145,10 +145,12 @@ export class Pulse extends Connector {
    * Nothing queues here. A call still running when the next boundary arrives means the work
    * does not fit the gap, and starting a second one would only make that worse.
    */
-  private async fire (i: number): Promise<void> {
+  private async fire(i: number): Promise<void> {
     if (this.firing !== undefined) {
-      console.warn('Pulse skipped: the previous call has not returned',
-        { pulse: this.label, interval: i })
+      console.warn('Pulse skipped: the previous call has not returned', {
+        pulse: this.label,
+        interval: i
+      })
 
       return
     }
@@ -156,8 +158,10 @@ export class Pulse extends Connector {
     const owned = this.atom.slots(this.n)
 
     if (owned === null) {
-      console.warn('Pulse skipped: this replica owns nothing',
-        { pulse: this.label, interval: i })
+      console.warn('Pulse skipped: this replica owns nothing', {
+        pulse: this.label,
+        interval: i
+      })
 
       return
     }
@@ -171,12 +175,17 @@ export class Pulse extends Connector {
      * only wanted an operation called every hour. So the interval is skipped: it is reported,
      * and the next one is called as though it had not happened.
      */
-    const firing = console.span(this.options,
-      async () => await this.local.invoke(this.endpoint, { input: { n: this.n, i } }))
+    const firing = console
+      .span(
+        this.options,
+        async () => await this.local.invoke(this.endpoint, { input: { n: this.n, i } })
+      )
       .catch((error: unknown) => {
         console.error('Pulse failed', { pulse: this.label, interval: i, error })
       })
-      .finally(() => { this.firing = undefined })
+      .finally(() => {
+        this.firing = undefined
+      })
 
     this.firing = firing
 
@@ -191,7 +200,7 @@ export interface Definition {
   intervals: number
 }
 
-async function delay (ms: number): Promise<void> {
+async function delay(ms: number): Promise<void> {
   await new Promise((resolve) => setTimeout(resolve, ms).unref())
 }
 

package/source/const.ts

@@ -16,7 +16,7 @@ export const DISCRETENESS = 60
 export const BATCH = 200
 
 /** A number from the environment, where a deployment or a test suite states one. */
-export function number (variable: string, fallback: number): number {
+export function number(variable: string, fallback: number): number {
   const value = Number(process.env[variable])
 
   return Number.isNaN(value) || value <= 0 ? fallback : value

package/source/context.ts

@@ -1,7 +1,7 @@
-import type { Contribution } from '@toa.io/core'
+import type { Contribution } from '@toa.io/core/types'
 
 /** What this extension puts on the context of a component that declares it. */
-export function context (): Contribution {
+export function context(): Contribution {
   return {
     name: 'delay',
     type: 'Delay',

package/source/deployment.ts

@@ -9,19 +9,24 @@ import type { Dependency, Service, Variable } from '@toa.io/operations'
  * The component that keeps delayed calls runs in a service of its own, the way the identity
  * components run in the gateway. A composition may claim it and run it in its own pods instead.
  */
-export function deployment (_: unknown, annotation?: Annotation | null): Dependency {
-  schemas.annotation.validate<Annotation | null>(annotation ?? null, 'Invalid cadence annotation')
+export function deployment(_: unknown, annotation?: Annotation | null): Dependency {
+  schemas.annotation.validate<Annotation | null>(
+    annotation ?? null,
+    'Invalid cadence annotation'
+  )
 
   // stated in seconds and carried in milliseconds, so that what an application writes is what
   // the rest of a manifest is written in
   const discreteness = (annotation?.discreteness ?? DISCRETENESS) * 1000
-  const variables: Variable[] =
-    [{ name: 'TOA_CADENCE_DISCRETENESS', value: String(discreteness) }]
+  const variables: Variable[] = [
+    { name: 'TOA_CADENCE_DISCRETENESS', value: String(discreteness) }
+  ]
 
   const service: Service = {
     group: NAMESPACE,
     name: 'metronome',
-    version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version,
+    version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+      .version,
     components: components().labels,
     variables
   }

package/source/manifest.test.ts

@@ -35,18 +35,21 @@ it('should answer a component that only delays calls', () => {
 })
 
 it('should refuse an undefined operation', () => {
-  assert.throws(() => manifest({ nothing: 3600 } as any, component),
-    /refers to undefined operation 'nothing'/)
+  assert.throws(
+    () => manifest({ nothing: 3600 } as any, component),
+    /refers to undefined operation 'nothing'/
+  )
 })
 
 it('should refuse an operation that produces no side effects', () => {
-  assert.throws(() => manifest({ peek: 3600 } as any, component),
-    /of the allowed types/)
+  assert.throws(() => manifest({ peek: 3600 } as any, component), /of the allowed types/)
 })
 
 it('should refuse an interval shorter than a second', () => {
-  assert.throws(() => manifest({ sweep: { cycle: 60, intervals: 61 } }, component),
-    /less than a second/)
+  assert.throws(
+    () => manifest({ sweep: { cycle: 60, intervals: 61 } }, component),
+    /less than a second/
+  )
 })
 
 it('should refuse a cycle of no time at all', () => {