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

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2020-present Artem Gurtovoi
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/components/cadence.metronome/manifest.toa.yaml

@@ -5,35 +5,29 @@ name: metronome
 cadence: ~
 
 entity:
-  schema:
-    type: object
-    properties:
-      lane:
-        description: Which dispatcher takes this row, as the outbox partitions its lanes
-        type: integer
-      due:
-        description: When the call is to be made, in milliseconds since the epoch
-        type: integer
-      expires:
-        description: >
-          After this the call is not made at all. A scan bounds on it, so a call nothing was
-          running to make in time is a row nobody reads, rather than an event anything sees.
-        type: integer
-      endpoint:
-        description: What to call, as `namespace.component.operation`
-        type: string
-      request:
-        description: The request to make, as it was handed over
-        type: object
-    required:
-      - lane
-      - due
-      - expires
-      - endpoint
-  index:
+  properties:
+    lane:
+      description: Which dispatcher takes this row, as the outbox partitions its lanes
+      type: integer
     due:
-      lane: asc
-      due: asc
+      description: When the call is to be made, in milliseconds since the epoch
+      type: integer
+    expires:
+      description: >
+        After this the call is not made at all. A scan bounds on it, so a call nothing was
+        running to make in time is a row nobody reads, rather than an event anything sees.
+      type: integer
+    endpoint:
+      description: What to call, as `namespace.component.operation`
+      type: string
+    request:
+      description: The request to make, as it was handed over
+      type: object
+  required:
+    - lane
+    - due
+    - expires
+    - endpoint
 
 # `enumerate` reads what is due and `terminate` cancels one; both come from the prototype.
 operations:

package/components/cadence.metronome/migrations/0001-system-properties.yaml

@@ -0,0 +1,14 @@
+# 1.0.0-alpha.286 renamed the four system properties of a record. A database written before it
+# holds them under the old names, where nothing reads them: such a record is never created,
+# never updated, never deleted, and at version zero.
+#
+# `$rename` leaves a record that has none of them alone, so this is a no-op for a component
+# that has only ever run this release.
+- update:
+    filter: {}
+    update:
+      $rename:
+        _version: VERSION
+        _created: CREATED
+        _updated: UPDATED
+        _deleted: DELETED

package/components/cadence.metronome/migrations/0002-indexes.yaml

@@ -0,0 +1,5 @@
+- index:
+    name: index_due
+    keys:
+      lane: asc
+      due: asc

package/components/cadence.metronome/operations/delay.js

@@ -8,7 +8,7 @@ import { LANES } from '@toa.io/extensions.cadence'
  * row has no immediate path to settle, so nothing is gained, and an even spread is what the
  * dispatchers want.
  */
-export function transition (input, object) {
+export function transition(input, object) {
   const due = Date.now() + input.interval
 
   object.lane = Math.floor(Math.random() * LANES)

package/components/cadence.metronome/operations/settle.js

@@ -2,8 +2,8 @@
  * The rows whose calls have been made. They are tombstoned rather than removed: the record of
  * what was asked for outlives the call, and a query answers only what is still owed.
  */
-export function transition (_, objects) {
+export function transition(_, objects) {
   const now = Date.now()
 
-  for (const object of objects) object._deleted = now
+  for (const object of objects) object.DELETED = now
 }

package/components/cadence.metronome/types/toa.d.ts

@@ -1,7 +1,7 @@
 // Written by `toa types`. Every run rewrites it.
 // What a manifest does not state belongs in a file of your own.
 
-import type { Query } from '@toa.io/core'
+import type { Query } from '@toa.io/core/types'
 import type { Readable } from 'node:stream'
 
 export interface Entity {
@@ -16,10 +16,10 @@ export interface Entity {
   /** The request to make, as it was handed over */
   request?: Record<string, unknown>
   id: string
-  _version?: number
-  _created?: number
-  _updated?: number
-  _deleted?: number | null
+  VERSION?: number
+  CREATED?: number
+  UPDATED?: number
+  DELETED?: number | null
 }
 
 export type DelayInput = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.cadence",
-  "version": "1.0.0-alpha.284",
+  "version": "1.0.0-alpha.286",
   "type": "module",
   "description": "Toa Schedule",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -18,11 +18,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.284",
-    "@toa.io/schemas": "1.0.0-alpha.283",
-    "openspan": "1.0.0-alpha.277"
+    "@toa.io/core": "1.0.0-alpha.286",
+    "@toa.io/schemas": "1.0.0-alpha.286",
+    "openspan": "1.0.0-alpha.286"
   },
   "scripts": {
     "transpile": "tsc"
-  }
+  },
+  "gitHead": "81f3d0688f17668b902be336d1749cc715edcdb6"
 }

package/readme.md

@@ -14,9 +14,9 @@ at all.
 ```yaml
 # manifest.toa.yaml
 cadence:
-  sweep:                # an operation of this component
-    cycle: 86400        # seconds one whole cycle takes
-    intervals: 24       # what it is split into, so one call an hour
+  sweep: # an operation of this component
+    cycle: 86400 # seconds one whole cycle takes
+    intervals: 24 # what it is split into, so one call an hour
 ```
 
 The gap between calls is `cycle / intervals`, derived rather than declared, so the two cannot
@@ -26,13 +26,13 @@ declares:
 ```yaml
 # manifest.toa.yaml
 cadence:
-  sweep: 3600           # once an hour
+  sweep: 3600 # once an hour
 ```
 
 The operation is called with the cycle and the interval as its input:
 
 ```javascript
-async function sweep ({ n, i }, context) { }
+async function sweep({ n, i }, context) {}
 ```
 
 `n` is `intervals` and `i` is which of them this call is for, from `0` to `n - 1`. They are there
@@ -77,22 +77,25 @@ either answer put to everyone who wanted an operation called every hour is a wor
 picking one.
 
 `intervals` is not a replica count. With `intervals: 24` and three replicas each makes eight of
-the day's calls: the cycle is spread over *time*, not over the fleet. Replicas beyond `intervals`
+the day's calls: the cycle is spread over _time_, not over the fleet. Replicas beyond `intervals`
 make none.
 
 ## Delay
 
 ```javascript
-const id = await context.delay('mail.sender.remind', { input: { user } },
-  { interval: 7 * 24 * 3600 * 1000, overdue: null })
+const id = await context.delay(
+  'mail.sender.remind',
+  { input: { user } },
+  { interval: 7 * 24 * 3600 * 1000, overdue: null }
+)
 
 await context.delay.cancel(id)
 ```
 
-| | |
-|---|---|
-| `interval` | milliseconds from now |
-| `overdue` | milliseconds the call may be late and still be made, or `null` for no bound |
+|            |                                                                             |
+| ---------- | --------------------------------------------------------------------------- |
+| `interval` | milliseconds from now                                                       |
+| `overdue`  | milliseconds the call may be late and still be made, or `null` for no bound |
 
 The call is made once the delay has passed, and waits for the target where it is not there to
 take it. The id it answers cancels it, and `cancel` raises where the id was never issued.
@@ -111,11 +114,11 @@ cadence: ~
 ordinary path has: a call is made at the moment it is due. How much is left of that in practice
 depends on how coarsely the calls are looked over — see [Discreteness](#discreteness).
 
-| | |
-|---|---|
-| `null` | no bound: made whenever it can be, however late that is |
-| `0` | on time or never |
-| a number | made if no more than that many milliseconds late |
+|          |                                                         |
+| -------- | ------------------------------------------------------- |
+| `null`   | no bound: made whenever it can be, however late that is |
+| `0`      | on time or never                                        |
+| a number | made if no more than that many milliseconds late        |
 
 **There is no default, and it is stated on every call.** Only the caller knows whether a late
 call is still the right call — an unpaid order expires on time or not at all, a report is wanted
@@ -179,7 +182,7 @@ may no longer be one it accepts. Either way the attempt is spent.
 ```yaml
 # context.toa.yaml
 cadence:
-  discreteness: 60    # seconds between passes over the calls waiting to be made
+  discreteness: 60 # seconds between passes over the calls waiting to be made
 ```
 
 `discreteness` is how often the calls waiting to be made are looked over. It defaults to 60,

package/schemas/declaration.cos.yaml

@@ -16,6 +16,5 @@ patternProperties:
           and the operation is told which interval it is running for.
         type: integer
         minimum: 1
-        default: 1
     required: [cycle]
     additionalProperties: false

package/source/Aspect.ts

@@ -17,14 +17,13 @@ interface Input {
  * handing over the call it should have scheduled loses the call, and there is no way for this
  * to know. Where the semantics allow it, hand the call over first.
  *
- * @implements {toa.core.extensions.Aspect}
  */
 export class Aspect extends Connector {
   public readonly name = 'delay'
 
   private readonly metronome: Local
 
-  public constructor (metronome: Local) {
+  public constructor(metronome: Local) {
     super()
 
     this.metronome = metronome
@@ -34,18 +33,28 @@ export class Aspect extends Connector {
 
   // named rather than forwarded, so that the connector's lifecycle is not reachable from an
   // algorithm — the same reason the atom aspect names its own
-  public async invoke (method: string, ...args: any[]): Promise<unknown> {
+  public async invoke(method: string, ...args: any[]): Promise<unknown> {
     switch (method) {
-      case 'delay': return await this.delay(args[0], args[1], args[2])
-      case 'cancel': return await this.cancel(args[0])
-      default: throw new Error(`Delay aspect has no '${method}' method`)
+      case 'delay':
+        return await this.delay(args[0], args[1], args[2])
+      case 'cancel':
+        return await this.cancel(args[0])
+      default:
+        throw new Error(`Delay aspect has no '${method}' method`)
     }
   }
 
   /** Answers the id the call was given, which is what cancels it. */
-  private async delay (endpoint: string, request: object | null,
-    options: Options): Promise<unknown> {
-    const input: Input = { endpoint, interval: options.interval, overdue: options.overdue }
+  private async delay(
+    endpoint: string,
+    request: object | null,
+    options: Options
+  ): Promise<unknown> {
+    const input: Input = {
+      endpoint,
+      interval: options.interval,
+      overdue: options.overdue
+    }
 
     // a call that takes no request carries none, rather than a null one
     if (request !== null && request !== undefined) input.request = request
@@ -58,7 +67,7 @@ export class Aspect extends Connector {
    * nothing to terminate and raises; one whose call has already been made has a row still, and
    * terminating it again is not an error.
    */
-  private async cancel (id: string): Promise<unknown> {
+  private async cancel(id: string): Promise<unknown> {
     return await this.metronome.invoke('terminate', { query: { id }, input: null })
   }
 }

package/source/Composition.ts

@@ -5,7 +5,7 @@ import type { Dirent } from 'node:fs'
 import type { Host } from './Factory.js'
 
 /** The components this extension ships, which run inside its own service. */
-export function components (): Components {
+export function components(): Components {
   const labels: string[] = []
   const paths: string[] = []
 
@@ -20,13 +20,13 @@ export function components (): Components {
 export class Composition extends Connector {
   private readonly host: Host
 
-  public constructor (host: Host) {
+  public constructor(host: Host) {
     super()
 
     this.host = host
   }
 
-  protected override async open (): Promise<void> {
+  protected override async open(): Promise<void> {
     const composition = await this.host.composition(components().paths)
 
     await composition.connect()
@@ -35,7 +35,7 @@ export class Composition extends Connector {
   }
 }
 
-function entries (): Dirent[] {
+function entries(): Dirent[] {
   return readdirSync(ROOT, { withFileTypes: true }).filter((entry) => entry.isDirectory())
 }
 

package/source/Dispatcher.test.ts

@@ -4,7 +4,7 @@ import assert from 'node:assert/strict'
 import { Dispatcher } from './Dispatcher.js'
 import { LANES } from './const.js'
 import type { Local } from './Local.js'
-import type { atomicity } from '@toa.io/core'
+import type { atomicity } from '@toa.io/core/types'
 
 type Invoke = (endpoint: string, request: any) => Promise<unknown>
 type Slots = (total: number) => number[] | null
@@ -26,11 +26,20 @@ interface Row {
   request: object | null
 }
 
-const row = (id: string, due: number, lane = 0): Row =>
-  ({ id, lane, due, endpoint: 'tea.pots.transit', request: { input: { id } } })
+const row = (id: string, due: number, lane = 0): Row => ({
+  id,
+  lane,
+  due,
+  endpoint: 'tea.pots.transit',
+  request: { input: { id } }
+})
 
-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 advance = async (ms: number): Promise<void> => {
   mock.timers.tick(ms)
@@ -39,20 +48,20 @@ const advance = async (ms: number): Promise<void> => {
 }
 
 /** the query one scan made */
-const reads = (): any[] => metronome.invoke.mock.calls
-  .filter((call) => call.arguments[0] === 'enumerate')
-  .map((call) => call.arguments[1].query)
+const reads = (): any[] =>
+  metronome.invoke.mock.calls
+    .filter((call) => call.arguments[0] === 'enumerate')
+    .map((call) => call.arguments[1].query)
 
 /** what has been settled, flattened */
-const settled = (): string[] => metronome.invoke.mock.calls
-  .filter((call) => call.arguments[0] === 'settle')
-  .flatMap((call) => call.arguments[1].query.ids as string[])
+const settled = (): string[] =>
+  metronome.invoke.mock.calls
+    .filter((call) => call.arguments[0] === 'settle')
+    .flatMap((call) => call.arguments[1].query.ids as string[])
 
 const range = (total: number): number[] => Array.from({ length: total }, (_, i) => i)
 
-const create = (): Dispatcher =>
-  new Dispatcher(metronome, () => target, atom)
-
+const create = (): Dispatcher => new Dispatcher(metronome, () => target, atom)
 
 beforeEach(() => {
   process.env.TOA_CADENCE_DISCRETENESS = String(INTERVAL)
@@ -62,7 +71,9 @@ beforeEach(() => {
   listeners = []
 
   metronome = connector({
-    invoke: mock.fn<Invoke>(async (endpoint: string) => endpoint === 'enumerate' ? rows : null)
+    invoke: mock.fn<Invoke>(async (endpoint: string) =>
+      endpoint === 'enumerate' ? rows : null
+    )
   })
 
   target = connector({ invoke: mock.fn<Invoke>(async () => null) })
@@ -73,7 +84,9 @@ beforeEach(() => {
       listeners.push(listener)
       listener()
 
-      return () => { listeners = listeners.filter((one) => one !== listener) }
+      return () => {
+        listeners = listeners.filter((one) => one !== listener)
+      }
     }
   })
 })
@@ -92,8 +105,10 @@ it('should read what is due within the interval, in the lanes it owns', async ()
   const [first] = reads()
 
   // the first scan is the one the subscription runs as it is added, at time zero
-  assert.strictEqual(first.criteria,
-    `lane=in=(${range(LANES).join(',')});due<${INTERVAL};expires>0`)
+  assert.strictEqual(
+    first.criteria,
+    `lane=in=(${range(LANES).join(',')});due<${INTERVAL};expires>0`
+  )
   assert.deepStrictEqual(first.sort, ['due:asc'])
 })
 
@@ -136,8 +151,11 @@ it('should call one whose time has already passed at once', async () => {
   await dispatcher.connect()
   await advance(0)
 
-  assert.strictEqual(target.invoke.mock.callCount(), 1,
-    'a scan reads what is overdue along with what is coming')
+  assert.strictEqual(
+    target.invoke.mock.callCount(),
+    1,
+    'a scan reads what is overdue along with what is coming'
+  )
 })
 
 it('should arm a row once, however often a scan reads it', async () => {
@@ -159,8 +177,12 @@ it('should not arm a row again while its call is in flight', async () => {
   let release: () => void = () => {}
 
   rows = [row('a', 10)]
-  target.invoke.mock.mockImplementation(async () =>
-    await new Promise<void>((resolve) => { release = resolve }))
+  target.invoke.mock.mockImplementation(
+    async () =>
+      await new Promise<void>((resolve) => {
+        release = resolve
+      })
+  )
 
   const dispatcher = create()
 
@@ -175,7 +197,11 @@ it('should not arm a row again while its call is in flight', async () => {
   // far enough for anything that scan armed to have fired
   await advance(INTERVAL)
 
-  assert.strictEqual(target.invoke.mock.callCount(), 1, 'and does not send it a second time')
+  assert.strictEqual(
+    target.invoke.mock.callCount(),
+    1,
+    'and does not send it a second time'
+  )
 
   release()
   await advance(0)
@@ -199,19 +225,29 @@ it('should settle what it has called', async () => {
 
 it('should settle a row whose call failed, and keep dispatching', async () => {
   rows = [row('a', 10), row('b', 20)]
-  target.invoke.mock.mockImplementationOnce(async () => { throw new Error('nope') })
+  target.invoke.mock.mockImplementationOnce(async () => {
+    throw new Error('nope')
+  })
 
   const dispatcher = create()
 
   await dispatcher.connect()
   await advance(20)
 
-  assert.strictEqual(target.invoke.mock.callCount(), 2, 'the one after it is still called')
+  assert.strictEqual(
+    target.invoke.mock.callCount(),
+    2,
+    'the one after it is still called'
+  )
 
   rows = []
   await advance(INTERVAL)
 
-  assert.deepStrictEqual(settled().sort(), ['a', 'b'], 'and the one that failed is settled')
+  assert.deepStrictEqual(
+    settled().sort(),
+    ['a', 'b'],
+    'and the one that failed is settled'
+  )
 })
 
 it('should drop timers for lanes it no longer owns', async () => {
@@ -229,7 +265,7 @@ it('should drop timers for lanes it no longer owns', async () => {
 
   await advance(20_000)
 
-  assert.strictEqual(target.invoke.mock.callCount(), 0, 'lane 7 is somebody else\'s now')
+  assert.strictEqual(target.invoke.mock.callCount(), 0, "lane 7 is somebody else's now")
 })
 
 it('should drop everything it holds when it owns nothing', async () => {
@@ -247,8 +283,11 @@ it('should drop everything it holds when it owns nothing', async () => {
 
   await advance(20_000)
 
-  assert.strictEqual(target.invoke.mock.callCount(), 0,
-    'whoever holds lane 7 now is the one to make that call')
+  assert.strictEqual(
+    target.invoke.mock.callCount(),
+    0,
+    'whoever holds lane 7 now is the one to make that call'
+  )
 })
 
 it('should scan at once when what it owns changes', async () => {