@ecosy/schedule 0.1.0

package/src/task.ts

@@ -0,0 +1,124 @@
+import { nextFire, parseCron, type CronExpression } from "./cron";
+import type { TaskDefinition } from "./types";
+
+export interface TaskStatus {
+  key: string;
+  enabled: boolean;
+  expression: string;
+  timezone: string;
+  nextAt: Date | null;
+  running: boolean;
+  lastRunAt: Date | null;
+  lastOk: boolean | null;
+  runs: number;
+  failures: number;
+}
+
+/**
+ * One scheduled task: its definition, when it fires next, and how it has been
+ * doing.
+ *
+ * The split between the two matters at sync time. A definition that changed
+ * gets a freshly computed schedule — the new expression decides the next fire,
+ * not an adjustment of the old one — while the history carries over, because
+ * "when did this last succeed" is the question people ask after an edit, not
+ * before it.
+ */
+export class Task {
+  readonly key: string;
+
+  private definition: TaskDefinition;
+  private cron: CronExpression;
+
+  nextAt: Date | null = null;
+  running = false;
+
+  lastRunAt: Date | null = null;
+  lastOk: boolean | null = null;
+  runs = 0;
+  failures = 0;
+
+  constructor(definition: TaskDefinition, from: Date = new Date()) {
+    this.key = definition.key;
+    this.definition = definition;
+    this.cron = parseCron(definition.expression);
+    this.schedule(from);
+  }
+
+  get enabled(): boolean {
+    return this.definition.enabled !== false;
+  }
+
+  get timezone(): string {
+    return this.definition.timezone ?? "UTC";
+  }
+
+  get current(): TaskDefinition {
+    return this.definition;
+  }
+
+  /** Recomputes the next fire from scratch. History is untouched. */
+  private schedule(from: Date): void {
+    this.nextAt = this.enabled ? nextFire(this.cron, from, this.timezone) : null;
+  }
+
+  /**
+   * Applies a changed definition.
+   *
+   * Only reparses when the expression or zone actually moved: reparsing on
+   * every sync would reset `nextAt` each time and, for anything firing less
+   * often than the sync interval, push the fire permanently into the future.
+   */
+  update(definition: TaskDefinition, from: Date = new Date()): void {
+    const rescheduled =
+      definition.expression !== this.definition.expression ||
+      definition.timezone !== this.definition.timezone ||
+      (definition.enabled !== false) !== this.enabled;
+
+    this.definition = definition;
+
+    if (rescheduled) {
+      this.cron = parseCron(definition.expression);
+      this.schedule(from);
+    }
+  }
+
+  due(now: Date): boolean {
+    return this.enabled && !this.running && this.nextAt !== null && this.nextAt <= now;
+  }
+
+  /**
+   * Moves to the fire after this one.
+   *
+   * Called the moment a run is picked up, before it finishes, so a task that
+   * takes longer than its interval does not push its own schedule along behind
+   * it. Overlap is prevented by `running`, not by delaying the clock.
+   */
+  advance(): Date {
+    const fired = this.nextAt ?? new Date();
+    this.nextAt = nextFire(this.cron, fired, this.timezone);
+    return fired;
+  }
+
+  record(ok: boolean, at: Date): void {
+    this.runs++;
+    if (!ok) this.failures++;
+    this.lastRunAt = at;
+    this.lastOk = ok;
+  }
+
+  status(): TaskStatus {
+    return {
+      key: this.key,
+      enabled: this.enabled,
+      expression: this.definition.expression,
+      timezone: this.timezone,
+      nextAt: this.nextAt,
+      running: this.running,
+      lastRunAt: this.lastRunAt,
+      lastOk: this.lastOk,
+      runs: this.runs,
+      failures: this.failures,
+    };
+  }
+}

package/src/types.ts

@@ -0,0 +1,147 @@
+/**
+ * What the scheduler needs from the world.
+ *
+ * One thing is required — a source, because nothing can guess where task
+ * definitions live. Everything else is optional and has a defined behaviour
+ * when absent, so a scheduler with just a source and a registry is a complete,
+ * working single-instance scheduler.
+ */
+
+/**
+ * A class constructible with no arguments.
+ *
+ * The single currency of this package: anything the scheduler builds for you —
+ * a source, a parser, a coordinator, a hook, a handler — arrives as one of
+ * these. Configuration that a constructor would need is captured by a factory
+ * that hands back a class, the way `DiskCache(dir)` and `Source(fn)` do.
+ *
+ * One currency is why there is no `typeof x === "function"` check anywhere in
+ * here: nothing has to work out at runtime what it was given.
+ */
+export type ClassType<Instance = unknown> = new () => Instance;
+
+export type InjectMap = Record<string, ClassType>;
+
+export type Injected<Context, Injects extends InjectMap> = Context & {
+  [K in keyof Injects]: Injects[K] extends ClassType<infer Instance> ? Instance : never;
+};
+
+export type Promisable<T> = T | Promise<T>;
+
+/* ------------------------------------------------------------ task shape */
+
+/**
+ * What a task does when it fires.
+ *
+ * Three kinds, and they fail in genuinely different ways — see `TaskFailure`.
+ */
+export type TaskTarget =
+  /** A function registered in code. Fast and typed; cannot be interrupted. */
+  | { type: "handler"; key: string }
+  /** An HTTP call. Works across instances; the request can be abandoned but the server keeps going. */
+  | { type: "api"; url: string; method?: string; headers?: Record<string, string>; body?: string }
+  /** A child process. The only kind that can genuinely be killed. */
+  | { type: "file"; path: string; args?: string[] };
+
+/** One task, after a parser has read it out of whatever the source returned. */
+export interface TaskDefinition {
+  /** Unique. Used for the registry lookup, for coordination, and as the sync identity. */
+  key: string;
+  /** Six-field cron, or five for standard crontab. */
+  expression: string;
+  target: TaskTarget;
+  /** IANA zone. Defaults to UTC — never the host zone, which differs between machines. */
+  timezone?: string;
+  /** False keeps the task known but unscheduled, so its history survives a pause. */
+  enabled?: boolean;
+  /** Overrides the schedule-level default. */
+  retry?: number;
+  /** Milliseconds. Overrides the schedule-level default. */
+  timeout?: number;
+}
+
+/** Turns one entry from a source into a task. Implement this to accept your own format. */
+export interface TaskParser<Entry = string> {
+  parse(entry: Entry): TaskDefinition;
+}
+
+/* -------------------------------------------------------------- outcomes */
+
+/**
+ * Why a run failed, normalised across the three target kinds.
+ *
+ * Without this every consumer of a hook would branch on target type to find
+ * out what went wrong. `raw` keeps the original for anyone who needs it.
+ */
+export type TaskFailure =
+  | "throw"    // handler threw
+  | "status"   // api answered outside 2xx
+  | "timeout"  // deadline passed
+  | "exit"     // file exited non-zero, or was killed
+  | "unknown";
+
+export interface TaskEvent {
+  key: string;
+  /** The fire time this run belongs to, computed from the expression — not `now`. */
+  scheduledFor: Date;
+  startedAt: Date;
+  durationMs: number;
+  /** 1 for the first try. */
+  attempt: number;
+  ok: boolean;
+  reason?: TaskFailure;
+  detail?: string;
+  /** Whatever the target produced: return value, response body, stdout. */
+  raw?: unknown;
+}
+
+/* ----------------------------------------------------------------- ports */
+
+/**
+ * Where task definitions come from. Required.
+ *
+ * A class, not a callback — everything the scheduler constructs is a class, so
+ * there is one currency and nothing has to guess at runtime what it was handed.
+ * `Source(fn)` wraps a one-line reader into one, so brevity costs nothing.
+ */
+export interface SourceAdapter<Entry = string, Context = unknown> {
+  read(context: Context): Promisable<Entry[]>;
+}
+
+export type Source<Entry = string, Context = unknown> = ClassType<SourceAdapter<Entry, Context>>;
+
+/**
+ * Decides which instance runs a given fire. Optional.
+ *
+ * Without one every instance runs everything, which is correct for a single
+ * process and wrong the moment there are two. Deliberately separate from the
+ * source: a file-backed schedule behind a load balancer still needs
+ * coordination, and a database-backed one on a single box does not.
+ *
+ * `claim` must be atomic across instances. A unique constraint on
+ * `(key, scheduledFor)` is a stronger guarantee than a distributed lock, and
+ * it leaves a run history behind for free.
+ */
+export interface Coordinator {
+  /** True when this instance won the right to run. False when another already has it. */
+  claim(key: string, scheduledFor: Date): Promisable<boolean>;
+  /** Called once the run ends, so an abandoned claim can be told from a live one. */
+  release(key: string, scheduledFor: Date, event: TaskEvent): Promisable<void>;
+}
+
+/**
+ * Where run outcomes go. Optional — without one, a finished task reports
+ * nowhere.
+ *
+ * One hook, not a list: `combine` turns several into one, so nothing
+ * downstream ever branches on how many there are.
+ */
+export interface Hook {
+  notify(event: TaskEvent): Promisable<void>;
+}
+
+/** Called when a source entry names a handler that was never registered. */
+export type NotFoundHandler = (key: string, task: TaskDefinition) => Promisable<void>;
+
+/** Called when a run fails, before any retry decision. */
+export type ErrorHandler = (event: TaskEvent, task: TaskDefinition) => Promisable<void>;

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}