silent-cronx 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pradeep Kumar Sheoran, BSG Technologies
+
+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/README.md

@@ -0,0 +1,314 @@
+# SilentCronX
+
+SilentCronX is a fast, safe, non-blocking, and reliable background job engine for Node.js.
+
+Package: `silent-cronx`  
+Developer: Pradeep Kumar Sheoran (Developer)  
+Company: BSG Technologies  
+Contact / WhatsApp: `+91-8595147850`  
+Donation / Support UPI mobile number: `+91-8595147850`
+
+Hashtags: `#SilentCronX` `#NodeJS` `#TypeScript` `#Cron` `#BackgroundJobs` `#WorkerThreads` `#BSGTechnologies`
+
+## Features
+
+- Cron jobs with 5-field syntax and optional seconds.
+- Delayed jobs, recurring jobs, and one-time background jobs.
+- Queue jobs with concurrency, priority, retry, and backpressure.
+- Worker thread pool for CPU-heavy module-based jobs.
+- Retry with fixed, linear, or exponential backoff.
+- Timeout and cancellation through `AbortSignal`.
+- Prevent-overlap locks with lock TTL.
+- Pause, resume, start, stop, and graceful shutdown.
+- Job status, lifecycle events, logs through your logger, metrics, and health snapshots.
+- In-memory storage adapter plus Redis and Postgres adapter placeholders.
+- ESM, CJS, and TypeScript declaration output through `tsup`.
+- Security-first design: no `eval`, no hidden process behavior, no shell execution by default.
+
+## Installation
+
+```bash
+npm install silent-cronx
+```
+
+## Basic Cron Job
+
+```ts
+import { createSilentCronX } from "silent-cronx";
+
+const cron = createSilentCronX({
+  timezone: "Asia/Kolkata",
+  maxWorkers: 4,
+  defaultTimeout: 30000,
+  logger: console,
+});
+
+await cron.schedule("daily-report", {
+  cron: "0 9 * * *",
+  task: async ({ jobId, signal }) => {
+    if (signal.aborted) return;
+    console.log("Generating daily report...", jobId);
+  },
+});
+
+cron.start();
+```
+
+## Delayed Job
+
+```ts
+await cron.delay("send-email", {
+  delayMs: 5000,
+  payload: {
+    userId: 101,
+    email: "test@example.com",
+  },
+  task: async ({ payload }) => {
+    console.log("Sending email", payload.email);
+  },
+});
+```
+
+## Recurring Job
+
+```ts
+await cron.every("sync-cache", {
+  intervalMs: 60000,
+  preventOverlap: true,
+  task: async () => {
+    await refreshCache();
+  },
+});
+```
+
+## Worker Thread Job
+
+Worker jobs should use a module reference. SilentCronX does not serialize or `eval` function source.
+
+```ts
+const result = await cron.runWorker("heavy-csv-processing", {
+  payload: { filePath: "./large.csv" },
+  timeout: 60000,
+  worker: {
+    path: new URL("./workers/csvWorker.js", import.meta.url),
+    exportName: "processCsv",
+  },
+});
+```
+
+```ts
+// workers/csvWorker.ts
+export async function processCsv({ payload }) {
+  return { processed: true, filePath: payload.filePath };
+}
+```
+
+## Queue Job
+
+```ts
+cron.queue("invoice-queue", {
+  concurrency: 5,
+  retry: {
+    attempts: 3,
+    backoff: "exponential",
+    delayMs: 1000,
+  },
+  processor: async ({ payload }) => {
+    console.log("Generating invoice", payload.invoiceId);
+  },
+});
+
+await cron.addJob("invoice-queue", {
+  name: "generate-invoice",
+  priority: 10,
+  payload: { invoiceId: 5001 },
+});
+```
+
+## Retry Example
+
+```ts
+await cron.runNow("retry-api-call", {
+  retry: {
+    attempts: 3,
+    delayMs: 1000,
+    backoff: "exponential",
+    shouldRetry: (error) => error instanceof Error,
+  },
+  task: async () => {
+    await callExternalApi();
+  },
+});
+```
+
+## Timeout Example
+
+```ts
+await cron.runNow("limited-job", {
+  timeout: 10000,
+  task: async ({ signal }) => {
+    await doWork({ signal });
+  },
+});
+```
+
+## Prevent Overlapping
+
+```ts
+await cron.schedule("billing-close", {
+  cron: "0 * * * *",
+  preventOverlap: true,
+  task: async () => {
+    await closeBillingWindow();
+  },
+});
+```
+
+## Job Cancellation
+
+```ts
+const jobId = await cron.delay("cancel-me", {
+  delayMs: 30000,
+  task: async () => console.log("will not run"),
+});
+
+await cron.cancel(jobId);
+```
+
+## Graceful Shutdown
+
+```ts
+process.once("SIGINT", async () => {
+  await cron.shutdown();
+  process.exit(0);
+});
+```
+
+## Events
+
+```ts
+cron.on("job:started", (event) => {
+  console.log("Job started", event.jobId);
+});
+
+cron.on("job:success", (event) => {
+  console.log("Job success", event.jobId, event.durationMs);
+});
+
+cron.on("job:failed", (event) => {
+  console.log("Job failed", event.jobId, event.error);
+});
+```
+
+## Health Status
+
+```ts
+const health = await cron.getHealth();
+console.log(health);
+```
+
+Example response:
+
+```json
+{
+  "running": true,
+  "scheduledJobs": 10,
+  "runningJobs": 2,
+  "queuedJobs": 15,
+  "workers": {
+    "max": 4,
+    "busy": 2,
+    "idle": 2
+  },
+  "memory": {
+    "storage": "memory"
+  }
+}
+```
+
+## Storage Adapter
+
+```ts
+import type { StorageAdapter } from "silent-cronx";
+
+const storage: StorageAdapter = {
+  async saveJob(job) {},
+  async updateJob(jobId, patch) {},
+  async getJob(jobId) {
+    return null;
+  },
+  async listJobs(filter) {
+    return [];
+  },
+  async deleteJob(jobId) {},
+  async acquireLock(lockKey, ttlMs) {
+    return true;
+  },
+  async releaseLock(lockKey) {},
+};
+
+const cron = createSilentCronX({ storage });
+```
+
+Use Redis or Postgres in production when multiple app instances need shared locks and durable history.
+
+## API Reference
+
+- `createSilentCronX(config)`
+- `cron.schedule(name, options)`
+- `cron.delay(name, options)`
+- `cron.every(name, options)`
+- `cron.runNow(name, options)`
+- `cron.runWorker(name, options)`
+- `cron.queue(name, options)`
+- `cron.addJob(queueName, job)`
+- `cron.cancel(jobId)`
+- `cron.pause(jobId)`
+- `cron.resume(jobId)`
+- `cron.getStatus(jobId)`
+- `cron.getJobs()`
+- `cron.getHealth()`
+- `cron.start()`
+- `cron.stop()`
+- `cron.shutdown()`
+- `cron.on(eventName, handler)`
+- `cron.off(eventName, handler)`
+
+## Security Notes
+
+SilentCronX is designed to be controllable, observable, auditable, and stoppable. It does not create hidden processes, bypass monitoring tools, execute shell commands by default, use `eval`, or run arbitrary code strings. Validate payloads from users before enqueueing jobs, keep job handlers idempotent, and use persistent storage plus distributed locks for multi-instance deployments.
+
+## Production Checklist
+
+- Do not run unknown user code.
+- Do not use `eval`.
+- Use worker threads for CPU-heavy jobs.
+- Set job timeouts.
+- Set retry limits.
+- Prevent overlapping for critical jobs.
+- Use persistent storage for production.
+- Use locks in multi-instance deployment.
+- Log failures.
+- Monitor job health.
+- Gracefully shutdown workers.
+- Keep jobs idempotent.
+- Use queue backpressure.
+- Validate payloads.
+
+## Implementation Guide
+
+1. Create a `createSilentCronX` instance near application startup.
+2. Register cron, interval, delay, worker, or queue jobs.
+3. Attach lifecycle event handlers for observability.
+4. Call `cron.start()` after registration.
+5. Wire `SIGINT` and `SIGTERM` to `cron.shutdown()`.
+6. Use Redis/Postgres storage for durable multi-instance workloads.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm run pack:dry
+```