bareloop 0.42.0 → 0.43.0

package/types/triggerclock.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The only way a clock schedule enters the system. Refuses anything else, naming the field.
+ * @param {unknown} s
+ * @returns {Schedule}
+ */
+export function validateSchedule(s: unknown): Schedule;
+/**
+ * Is a run due at `now`? Slots missed (panel off) collapse to ONE fire, for the latest slot, marked catch-up.
+ * Catch-up = more than one slot was missed, or the latest slot is more than GRACE_MS old.
+ * @param {Schedule} schedule
+ * @param {ClockRow[]} rows
+ * @param {number} now epoch ms
+ * @returns {Due}
+ */
+export function due(schedule: Schedule, rows: ClockRow[], now: number): Due;
+/**
+ * The next slot time strictly after `afterMs` (epoch ms). Words are the caller's (schedulewords.js).
+ * @param {Schedule} schedule
+ * @param {number} afterMs
+ * @returns {number}
+ */
+export function nextSlot(schedule: Schedule, afterMs: number): number;
+/** The trigger was set at `now` under signature `sig`: no slot before this ever fires. @param {string} file @param {number} now @param {string} sig */
+export function armTrigger(file: string, now: number, sig: string): void;
+/**
+ * Record that the run for this due slot is starting (the consuming row). Write-once per slot.
+ * @param {string} file @param {Due} d the result of `due` with fire true @param {number} now @param {string} sig
+ */
+export function recordFire(file: string, d: Due, now: number, sig: string): void;
+/** @typedef {{kind:'daily'|'weekdays', hour:number, minute:number} | {kind:'weekly', day:string, hour:number, minute:number}} Schedule */
+/** @typedef {import('./triggerledger.js').LedgerRow} ClockRow */
+/** @typedef {{fire:boolean, catchUp:boolean, missed:number, slot?:number}} Due */
+/** A slot seen MORE than this after its set time is a catch-up. Exactly this late is on time. */
+export const GRACE_MS: 120000;
+export const DAYS: string[];
+export type Schedule = {
+    kind: "daily" | "weekdays";
+    hour: number;
+    minute: number;
+} | {
+    kind: "weekly";
+    day: string;
+    hour: number;
+    minute: number;
+};
+export type ClockRow = import("./triggerledger.js").LedgerRow;
+export type Due = {
+    fire: boolean;
+    catchUp: boolean;
+    missed: number;
+    slot?: number;
+};

package/types/triggerfiles.d.ts

@@ -0,0 +1,93 @@
+/** The file-kind rows of the job's ledger that still count (a released `ran` does not). @param {string} file @returns {SeenRow[]} */
+export function readSeen(file: string): SeenRow[];
+/** Arrived rows are never overwritten: the 2nd arrival of a sha (after a drop) gets its own id. @param {string} ledger @param {ToRun & {name?:string}} item @param {number} at the scheduler's clock, never the file's mtime @param {string} sig */
+export function recordArrived(ledger: string, item: ToRun & {
+    name?: string;
+}, at: number, sig: string): boolean;
+/** `of` = the arrived row it cancels (item.id when a queue row is passed). @param {string} ledger @param {{sha:string, path:string, size:number, id?:string}} item @param {string} why a plain reason: deleted, changed, schedule-changed, schedule-cancelled @param {number} at @param {string} sig */
+export function recordDropped(ledger: string, item: {
+    sha: string;
+    path: string;
+    size: number;
+    id?: string;
+}, why: string, at: number, sig: string): boolean;
+/**
+ * The queue: arrived and neither ran nor dropped, oldest arrival first. Identical arrival times: by name, then by sha (deterministic).
+ * @param {SeenRow[]} rows @returns {(SeenRow & {path:string})[]}
+ */
+export function queueOf(rows: SeenRow[]): (SeenRow & {
+    path: string;
+})[];
+/**
+ * At a queued file's turn, look at it again, at use time: lstat (no symlink, a regular file), realpath of its folder, re-hash.
+ * @param {{path:string, sha:string}} item
+ * @returns {{state:'ok', path:string, sha:string, size:number} | {state:'deleted', say:string} | {state:'changed', sha:string}}
+ */
+export function recheck(item: {
+    path: string;
+    sha: string;
+}): {
+    state: "ok";
+    path: string;
+    sha: string;
+    size: number;
+} | {
+    state: "deleted";
+    say: string;
+} | {
+    state: "changed";
+    sha: string;
+};
+/**
+ * The target is usable NOW, or an Error naming why: a file that is not a symlink and not something else (a file that does not exist yet
+ * is allowed: it may arrive), a folder that exists, resolved with realpathSync. The one rule `arm` and a door's set-time check share.
+ * @param {'new'|'updated'} mode @param {string} target
+ */
+export function checkTarget(mode: "new" | "updated", target: string): void;
+/**
+ * @param {{mode:'new'|'updated', target:string, ledger:string, sig:string, now?:() => number}} opts target = folder (new) or file (updated)
+ */
+export function createFileTrigger({ mode, target, ledger, sig, now }: {
+    mode: "new" | "updated";
+    target: string;
+    ledger: string;
+    sig: string;
+    now?: () => number;
+}): {
+    arm: () => void;
+    poll: () => {
+        arrived: ToRun[];
+        refused: Refused[];
+    };
+};
+/** @typedef {{id:string, kind:'baseline'|'arrived'|'ran'|'dropped', sha:string, name:string, size:number, at:number, sig?:string, path?:string, why?:string, of?:string}} SeenRow */
+/** @typedef {{path:string, sha:string, size:number}} ToRun */
+/** @typedef {{path:string, why:string}} Refused */
+/** Consecutive polls with the same size and mtime before a file is taken. (Two matches in a row = taken on the third sighting.) */
+export const STABLE_POLLS: 2;
+export function recordRan(ledger: string, item: {
+    sha: string;
+    path: string;
+    size: number;
+}, at: number, sig: string): boolean;
+export type SeenRow = {
+    id: string;
+    kind: "baseline" | "arrived" | "ran" | "dropped";
+    sha: string;
+    name: string;
+    size: number;
+    at: number;
+    sig?: string;
+    path?: string;
+    why?: string;
+    of?: string;
+};
+export type ToRun = {
+    path: string;
+    sha: string;
+    size: number;
+};
+export type Refused = {
+    path: string;
+    why: string;
+};

package/types/triggerledger.d.ts

@@ -0,0 +1,35 @@
+/** @typedef {{id?: string, kind: string, sig?: string, at?: number, [k: string]: unknown}} LedgerRow */
+/**
+ * Every row that parses, oldest first, and how many lines did not. A missing file is no rows.
+ * @param {string} file
+ * @returns {{rows: LedgerRow[], skipped: number}}
+ */
+export function readLedger(file: string): {
+    rows: LedgerRow[];
+    skipped: number;
+};
+/**
+ * Append one row (dir 0700, file 0600). A torn tail gets a newline first. `once` refuses a row whose `id` is
+ * already on disk (write-once ids), by throwing.
+ * @param {string} file
+ * @param {LedgerRow} row
+ * @param {{once?: boolean}} [opts]
+ */
+export function appendRow(file: string, row: LedgerRow, opts?: {
+    once?: boolean;
+}): void;
+/**
+ * Walk the rows in order: a `released` row (`of` = an id) cancels the latest earlier live row with that id, and
+ * is itself dropped. A released `fire` or `ran` is not consumed, so its slot or file is retryable (Part 4) and
+ * the same id may be written again.
+ * @param {LedgerRow[]} rows
+ * @returns {LedgerRow[]}
+ */
+export function withoutReleased(rows: LedgerRow[]): LedgerRow[];
+export type LedgerRow = {
+    id?: string;
+    kind: string;
+    sig?: string;
+    at?: number;
+    [k: string]: unknown;
+};