@nextera.one/tes-cron

TesCron — TES-based scheduling for NestJS

A human-readable, intent-preserving alternative to cron expressions. Schedule tasks using TES temporal expressions instead of cryptic cron strings.

Install

npm install @nextera.one/tes-cron

TesCron vs Cron

| Feature | Cron | TesCron | | ---------------- | ------------------- | ------------------------------ | | Syntax | 0 10 5 4 * | tes://2026/April[5^50]@10:00 | | Readability | Cryptic | Human-readable | | Intent preserved | No | Yes (raw expression stored) | | Duration/span | No (single trigger) | Yes (start + end) | | Business days | No | !weekend built-in | | Validation | Weak | Strict (fail-fast) | | Deterministic | Depends | Always | | Auditable | No | Yes |

Usage — Standalone

import { TesCronScheduler } from "@nextera.one/tes-cron";

const scheduler = new TesCronScheduler();

// Fire when span starts
scheduler.schedule("tes://2026/April[5^50]@10:00", () => {
  console.log("Task started!");
});

// Fire at span end
scheduler.schedule(
  "tes://2026/April[5^50]@10:00",
  () => {
    console.log("Task ended!");
  },
  { trigger: "end" },
);

// Fire at both start and end
scheduler.schedule(
  "tes://2026/April[5^50]@10:00",
  () => {
    console.log("Boundary hit!");
  },
  { trigger: "both" },
);

Usage — NestJS Decorator

import { TesCron } from "@nextera.one/tes-cron";

@Injectable()
export class TaskService {
  // Instead of: @Cron('0 10 5 4 *')
  @TesCron({ expression: "tes://2026/April[5^50]@10:00" })
  handleDeploy() {
    console.log("Deploy window started!");
  }

  @TesCron({
    expression: "tes://2026/April[6^10]!weekend",
    trigger: "end",
  })
  handleSprintEnd() {
    console.log("Sprint completed!");
  }
}

Usage — NestJS Module

import { TesCronModule } from "@nextera.one/tes-cron/module";

@Module({
  imports: [TesCronModule.forRoot()],
})
export class AppModule {}

API

TesCronScheduler

| Method | Description | | -------------------------------- | ------------------------------- | | schedule(expr, handler, opts?) | Schedule a job. Returns job ID. | | cancel(id) | Cancel a scheduled job. | | getJob(id) | Get job status and details. | | listJobs() | List all jobs. | | destroy() | Cancel all jobs and clean up. |

If the selected boundary time has already passed when it is scheduled, the job status is expired and the handler is not called.

@TesCron(options)

| Option | Type | Default | Description | | ------------ | ---------------------------- | --------- | -------------- | | expression | string | required | TES expression | | trigger | 'start' \| 'end' \| 'both' | 'start' | When to fire |

new TesCronScheduler(options?)

| Option | Type | Description | | --------- | ------------------------------------------- | --------------------------------------- | | onError | (error: unknown, job: TesCronJob) => void | Called when a handler throws or rejects |

Related Package

Use @nextera.one/tes-queue when jobs also need retries, dead-letter handling, expiry windows, or pluggable storage adapters.

License

MIT — Nextera.one