Feat/compt 76 nestjs scheduler module and service

[saadmoumou]

Summary

• What does this PR change?

Why

• Why is this change needed?

Checklist

• Added/updated tests (if behavior changed)
• npm run lint passes
• npm run typecheck passes
• npm test passes
• npm run build passes
• Added a changeset (npx changeset) if this affects consumers

Notes

• Anything reviewers should pay attention to?

[Copilot]

Pull request overview

This PR introduces a new @ciscode/scheduler-kit library that provides a lightweight in-process scheduler for NestJS, including a SchedulerService, a SchedulerModule that auto-registers decorated methods, and cron helper utilities. It also updates build/lint configuration to support the new module packaging and tooling.

Changes:

• Added SchedulerService with interval/timeout/cron scheduling, job registry, status reporting, and overlap (concurrency) guarding.
• Added SchedulerModule with register() / registerAsync() and decorators (@Cron, @Interval, @Timeout) to auto-discover and schedule jobs on module init.
• Added cron utilities (CronExpression constants + cron builder) and updated build/lint configs and lockfile.

Reviewed changes

Copilot reviewed 19 out of 20 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tsconfig.eslint.json	Extends ESLint TS project include patterns (adds *.mjs).
tsconfig.build.json	Adjusts build output settings and narrows the build include list to scheduler-kit sources.
src/services/scheduler.service.ts	Implements the core scheduler (cron/interval/timeout), registry, and status APIs.
src/services/scheduler.service.spec.ts	Adds unit tests for interval/timeout scheduling, rescheduling, concurrency guard, and error handling.
src/scheduler.module.ts	Adds NestJS dynamic module to wire options and auto-schedule decorated provider methods.
src/scheduler.module.spec.ts	Adds unit tests validating decorator discovery and dynamic-module wiring.
src/interfaces/scheduler.interface.ts	Defines public scheduler types/contracts (job union timing types + status + interface).
src/index.ts	Exposes the scheduler-kit public API (module/service/decorators/types/errors/helpers).
src/errors/duplicate-job.error.ts	Adds a dedicated error for duplicate job registration.
src/errors/duplicate-job.error.spec.ts	Adds unit tests for the custom error behavior.
src/decorators/scheduler.decorators.ts	Adds decorators and metadata key used for discovery-based scheduling.
src/decorators/scheduler.decorators.spec.ts	Adds unit tests for metadata produced by decorators.
src/cron-expression.ts	Adds common cron-expression constants for readability.
src/cron-expression.spec.ts	Adds unit tests for cron-expression constants.
src/cron-builder.ts	Adds a fluent builder for cron expressions based on human-friendly inputs.
src/cron-builder.spec.ts	Adds unit tests for the cron builder output formats.
eslint.config.mjs	Updates ESLint ignores and TypeScript project configuration.
eslint.config.js	Removes the previous ESLint config file.
lint-staged.config.js	Switches lint-staged config to CommonJS export style.
package-lock.json	Updates locked dependencies and dependency metadata for the new scheduler-kit setup.

[Copilot]

In reschedule(), spreading entry.job into newJob retains the previous timing property (e.g. interval) when switching to a different timing (e.g. cron), producing an object with multiple timing keys. That breaks the discriminated-union contract and can lead to confusing runtime behavior (cron branch wins, but stale interval/timeout fields remain). Build newJob from { name, handler } + newTiming (or explicitly omit the old timing keys) instead of spreading the full previous job.

[Copilot]

Interval/timeout values are used directly in setInterval/setTimeout with no validation. Passing 0, a negative number, or NaN can cause extremely tight loops or immediate execution, which is an operational risk. Consider validating job.interval/job.timeout to be finite, positive integers and throwing a clear error if invalid.

[Copilot]

For timeout-based jobs, the registry entry is deleted immediately after invoking guardedHandler() (before the handler promise resolves). This means status()/list() can no longer report isRunning while the handler is still executing, and callers can't unschedule() to stop tracking/cancel the job once it has started. Consider deleting the registry entry only after guardedHandler() completes (e.g., await it inside an async timeout callback) so runtime state stays consistent.

Suggested change

	const id = setTimeout(() => {
	void guardedHandler();
	this.registry.delete(job.name);
	const id = setTimeout(async () => {
	try {
	await guardedHandler();
	} finally {
	this.registry.delete(job.name);
	}

[Copilot]

The comment says the metadata key is a "unique symbol", but CISCODE_SCHEDULER_METADATA is currently a string. Either update the comment to match reality, or switch the key to a Symbol (or Symbol.for(...)) to reduce collision risk with other metadata keys.

Suggested change

	// A unique symbol used as the key for storing scheduler metadata on methods.
	// Using a unique constant prevents collisions with other decorator libraries.
	// A string constant used as the key for storing scheduler metadata on methods.
	// Centralizing the key in one constant helps reduce accidental collisions.

[Copilot]

parseTime() accepts any 1–2 digit hour and any 2 digit minute without range checks, so inputs like "99:99" will generate invalid cron expressions. Similarly, cron.every(n) and monthlyOn(dayOfMonth, ...) don't validate n/dayOfMonth ranges. Since this is a public helper API, consider validating hour (0–23), minute (0–59), dayOfMonth (1–31), and n (>0), and throwing a clear error when out of range.

[Copilot]

The cron-based scheduling branch (new CronJob(...) / entry.cronJob) is not covered by the current SchedulerService tests (the suite only exercises interval/timeout paths). Adding a test that schedules a cron job and asserts status().nextRun/handler invocation would help prevent regressions in the cron integration.