cronwatch 1.0.0

package/README.md

@@ -0,0 +1,228 @@
+# CronWatch
+
+Lightweight cron job tracker, debugger, and monitor for Node.js applications.
+
+Zero dependencies. Full TypeScript support. Plugin-ready.
+
+## Install
+
+```bash
+npm install cronwatch
+```
+
+## Quick Start
+
+```js
+const { createCronWatch } = require('cronwatch');
+
+const cron = createCronWatch();
+
+await cron.trackJob('send-emails', async () => {
+  // your job logic here
+  await sendPendingEmails();
+});
+```
+
+Every call to `trackJob` automatically captures start/end time, duration, success/failure status, error stacks, and retry counts.
+
+## Configuration
+
+```js
+const cron = createCronWatch({
+  retries: 3,                // max retry attempts (default: 0)
+  retryDelay: 1000,          // base delay between retries in ms (default: 1000)
+  retryBackoff: 'exponential', // 'fixed' | 'linear' | 'exponential'
+  timeout: 30000,            // job timeout in ms, 0 = disabled (default: 0)
+  logLevel: LOG_LEVELS.INFO, // DEBUG | INFO | WARN | ERROR | SILENT
+  storeMaxEntries: 1000,     // max entries kept in memory (default: 1000)
+  timestamps: true,          // ISO timestamps in log output (default: true)
+  colorize: true,            // colorized console output (default: true)
+});
+```
+
+Per-job overrides:
+
+```js
+await cron.trackJob('heavy-job', jobFn, {
+  retries: 5,
+  retryDelay: 2000,
+  retryBackoff: 'linear',
+  timeout: 60000,
+});
+```
+
+## Structured Logs
+
+Every tracked job produces a structured entry:
+
+```json
+{
+  "jobName": "send-emails",
+  "status": "success",
+  "startTime": "2026-03-20T10:00:00.000Z",
+  "endTime": "2026-03-20T10:00:00.234Z",
+  "duration": 234,
+  "error": null,
+  "retries": 0
+}
+```
+
+On failure:
+
+```json
+{
+  "jobName": "sync-inventory",
+  "status": "failure",
+  "startTime": "2026-03-20T10:00:00.000Z",
+  "endTime": "2026-03-20T10:00:03.512Z",
+  "duration": 3512,
+  "error": {
+    "message": "Connection refused",
+    "stack": "Error: Connection refused\n    at ...",
+    "code": null
+  },
+  "retries": 3
+}
+```
+
+## Querying Logs
+
+```js
+const emailLogs = await cron.getJobLogs('send-emails');
+const allLogs   = await cron.getAllLogs();
+await cron.clearLogs();
+```
+
+## Plugin System
+
+Extend CronWatch by hooking into job lifecycle events.
+
+```js
+cron.use({
+  name: 'slack-alerter',
+  onFailure({ jobName, error }) {
+    slack.send(`Job ${jobName} failed: ${error.message}`);
+  },
+  onTimeout({ jobName }) {
+    slack.send(`Job ${jobName} timed out!`);
+  },
+});
+```
+
+### Available Hooks
+
+| Hook | Trigger |
+|------|---------|
+| `onStart` | Before job executes |
+| `onSuccess` | Job completed successfully |
+| `onFailure` | Job failed after all retries |
+| `onRetry` | Before each retry attempt |
+| `onTimeout` | Job exceeded timeout |
+
+## Custom Store Adapter
+
+By default, logs are kept in memory. You can plug in any backend:
+
+```js
+const { createCronWatch, StoreAdapter } = require('cronwatch');
+
+class MongoAdapter extends StoreAdapter {
+  async save(entry)          { /* insert into MongoDB */ }
+  async getByJob(jobName)    { /* query by jobName */ }
+  async getAll()             { /* return all entries */ }
+  async clear()              { /* drop collection */ }
+}
+
+const cron = createCronWatch({
+  storeAdapter: new MongoAdapter(),
+});
+```
+
+See `examples/custom-store-adapter.js` for a working file-based adapter.
+
+## Use with node-cron
+
+```js
+const nodeCron = require('node-cron');
+const { createCronWatch } = require('cronwatch');
+
+const cron = createCronWatch({ retries: 2, timeout: 10000 });
+
+nodeCron.schedule('*/5 * * * *', () => {
+  cron.trackJob('cleanup-temp-files', async () => {
+    await cleanupTempFiles();
+  });
+});
+```
+
+## TypeScript
+
+Full type definitions are included. Import and use directly:
+
+```ts
+import { createCronWatch, CronWatchPlugin, JobEntry } from 'cronwatch';
+
+const cron = createCronWatch({ retries: 2 });
+
+const plugin: CronWatchPlugin = {
+  name: 'my-plugin',
+  onSuccess({ jobName }) {
+    console.log(`${jobName} done`);
+  },
+};
+
+cron.use(plugin);
+```
+
+## API Reference
+
+### `createCronWatch(options?)`
+
+Creates a new CronWatch instance.
+
+### `instance.trackJob(jobName, jobFn, options?)`
+
+Executes and tracks a job. Returns a `Promise<JobEntry>`.
+
+### `instance.use(plugin)`
+
+Registers a plugin. Returns `this` for chaining.
+
+### `instance.getJobLogs(jobName)`
+
+Returns all log entries for a specific job.
+
+### `instance.getAllLogs()`
+
+Returns all log entries.
+
+### `instance.clearLogs()`
+
+Clears the log store.
+
+## Architecture
+
+```
+src/
+  config.js    - Centralized config with defaults and merging
+  logger.js    - Multi-level logger with pluggable outputs
+  store.js     - In-memory store with adapter interface
+  retry.js     - Retry engine with backoff strategies
+  plugin.js    - Plugin lifecycle manager
+  tracker.js   - Core trackJob orchestrator
+  index.js     - Public API surface
+types/
+  index.d.ts   - Full TypeScript definitions
+```
+
+## Roadmap
+
+- [ ] Database adapters (MongoDB, PostgreSQL, Redis)
+- [ ] Dashboard API (Express/Fastify)
+- [ ] Alert system (email, webhooks, Slack)
+- [ ] Job scheduling (built-in cron parser)
+- [ ] Metrics export (Prometheus, StatsD)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "cronwatch",
+  "version": "1.0.0",
+  "description": "Lightweight cron job tracker, debugger, and monitor for Node.js applications",
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "files": [
+    "src/",
+    "types/"
+  ],
+  "scripts": {
+    "example": "node examples/basic.js",
+    "example:cron": "node examples/with-node-cron.js",
+    "test": "node --test test/"
+  },
+  "keywords": [
+    "cron",
+    "scheduler",
+    "monitor",
+    "tracking",
+    "jobs",
+    "retry",
+    "logging",
+    "debug"
+  ],
+  "author": "Manav Dadwal",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {},
+  "dependencies": {}
+}

package/src/config.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const LOG_LEVELS = Object.freeze({
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3,
+  SILENT: 4,
+});
+
+const DEFAULTS = Object.freeze({
+  retries: 0,
+  retryDelay: 1000,
+  retryBackoff: 'fixed',
+  timeout: 0,
+  logLevel: LOG_LEVELS.INFO,
+  storeMaxEntries: 1000,
+  timestamps: true,
+  colorize: true,
+});
+
+class Config {
+  #settings;
+
+  constructor(overrides = {}) {
+    this.#settings = { ...DEFAULTS, ...stripUndefined(overrides) };
+  }
+
+  get(key) {
+    return this.#settings[key];
+  }
+
+  set(key, value) {
+    this.#settings[key] = value;
+    return this;
+  }
+
+  merge(overrides = {}) {
+    return new Config({ ...this.#settings, ...stripUndefined(overrides) });
+  }
+
+  toJSON() {
+    return { ...this.#settings };
+  }
+}
+
+function stripUndefined(obj) {
+  const clean = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) clean[k] = v;
+  }
+  return clean;
+}
+
+module.exports = { Config, LOG_LEVELS, DEFAULTS };

package/src/index.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const { Config, LOG_LEVELS, DEFAULTS } = require('./config');
+const { Logger } = require('./logger');
+const { Store, StoreAdapter, MemoryAdapter } = require('./store');
+const { PluginManager, HOOK_NAMES } = require('./plugin');
+const { trackJob: _trackJob, TimeoutError } = require('./tracker');
+const { BACKOFF_STRATEGIES } = require('./retry');
+
+class CronWatch {
+  #config;
+  #logger;
+  #store;
+  #plugins;
+
+  constructor(options = {}) {
+    this.#config = new Config(options);
+    this.#logger = new Logger(this.#config);
+    this.#store = new Store(
+      options.storeAdapter || new MemoryAdapter(this.#config.get('storeMaxEntries'))
+    );
+    this.#plugins = new PluginManager();
+  }
+
+  async trackJob(jobName, jobFn, options = {}) {
+    return _trackJob(jobName, jobFn, options, {
+      logger: this.#logger,
+      store: this.#store,
+      pluginManager: this.#plugins,
+      config: this.#config,
+    });
+  }
+
+  use(plugin) {
+    this.#plugins.register(plugin);
+    this.#logger.debug(`Plugin registered: ${plugin.name}`);
+    return this;
+  }
+
+  async getJobLogs(jobName) {
+    return this.#store.getByJob(jobName);
+  }
+
+  async getAllLogs() {
+    return this.#store.getAll();
+  }
+
+  async clearLogs() {
+    await this.#store.clear();
+    this.#logger.debug('All logs cleared');
+  }
+
+  get config() {
+    return this.#config;
+  }
+
+  get logger() {
+    return this.#logger;
+  }
+
+  get plugins() {
+    return this.#plugins.plugins;
+  }
+}
+
+function createCronWatch(options = {}) {
+  return new CronWatch(options);
+}
+
+module.exports = {
+  CronWatch,
+  createCronWatch,
+  Config,
+  Logger,
+  Store,
+  StoreAdapter,
+  MemoryAdapter,
+  PluginManager,
+  TimeoutError,
+  LOG_LEVELS,
+  DEFAULTS,
+  HOOK_NAMES,
+  BACKOFF_STRATEGIES,
+};

package/src/logger.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const { LOG_LEVELS } = require('./config');
+
+const COLORS = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+  magenta: '\x1b[35m',
+  gray: '\x1b[90m',
+};
+
+const LEVEL_TAGS = {
+  [LOG_LEVELS.DEBUG]: { label: 'DEBUG', color: COLORS.gray },
+  [LOG_LEVELS.INFO]: { label: 'INFO ', color: COLORS.cyan },
+  [LOG_LEVELS.WARN]: { label: 'WARN ', color: COLORS.yellow },
+  [LOG_LEVELS.ERROR]: { label: 'ERROR', color: COLORS.red },
+};
+
+class Logger {
+  #level;
+  #colorize;
+  #timestamps;
+  #outputs;
+
+  constructor(config) {
+    this.#level = config.get('logLevel');
+    this.#colorize = config.get('colorize');
+    this.#timestamps = config.get('timestamps');
+    this.#outputs = [consoleOutput];
+  }
+
+  addOutput(fn) {
+    if (typeof fn === 'function') this.#outputs.push(fn);
+    return this;
+  }
+
+  debug(msg, meta) { this.#log(LOG_LEVELS.DEBUG, msg, meta); }
+  info(msg, meta) { this.#log(LOG_LEVELS.INFO, msg, meta); }
+  warn(msg, meta) { this.#log(LOG_LEVELS.WARN, msg, meta); }
+  error(msg, meta) { this.#log(LOG_LEVELS.ERROR, msg, meta); }
+
+  #log(level, msg, meta) {
+    if (level < this.#level) return;
+
+    const entry = {
+      level,
+      label: LEVEL_TAGS[level]?.label || 'LOG',
+      timestamp: this.#timestamps ? new Date().toISOString() : null,
+      message: msg,
+      meta: meta || null,
+    };
+
+    const formatted = this.#format(entry);
+    for (const output of this.#outputs) {
+      output(entry, formatted);
+    }
+  }
+
+  #format(entry) {
+    const c = this.#colorize ? COLORS : noColors();
+    const tag = LEVEL_TAGS[entry.level] || { label: 'LOG', color: '' };
+    const color = this.#colorize ? tag.color : '';
+
+    const parts = [];
+    if (entry.timestamp) {
+      parts.push(`${c.dim}${entry.timestamp}${c.reset}`);
+    }
+    parts.push(`${color}[${entry.label}]${c.reset}`);
+    parts.push(`${c.magenta}[CronWatch]${c.reset}`);
+    parts.push(entry.message);
+
+    return parts.join(' ');
+  }
+}
+
+function consoleOutput(entry, formatted) {
+  const stream = entry.level >= LOG_LEVELS.ERROR ? console.error : console.log;
+  stream(formatted);
+  if (entry.meta) {
+    stream(
+      entry.level >= LOG_LEVELS.ERROR
+        ? entry.meta
+        : JSON.stringify(entry.meta, null, 2)
+    );
+  }
+}
+
+function noColors() {
+  const empty = {};
+  for (const key of Object.keys(COLORS)) empty[key] = '';
+  return empty;
+}
+
+module.exports = { Logger, LOG_LEVELS };

package/src/plugin.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const HOOK_NAMES = ['onStart', 'onSuccess', 'onFailure', 'onRetry', 'onTimeout'];
+
+class PluginManager {
+  #plugins;
+
+  constructor() {
+    this.#plugins = [];
+  }
+
+  register(plugin) {
+    if (!plugin || typeof plugin !== 'object') {
+      throw new TypeError('Plugin must be an object');
+    }
+    if (!plugin.name || typeof plugin.name !== 'string') {
+      throw new TypeError('Plugin must have a string "name" property');
+    }
+
+    const hasHook = HOOK_NAMES.some((h) => typeof plugin[h] === 'function');
+    if (!hasHook) {
+      throw new TypeError(
+        `Plugin "${plugin.name}" must implement at least one hook: ${HOOK_NAMES.join(', ')}`
+      );
+    }
+
+    this.#plugins.push(plugin);
+    return this;
+  }
+
+  async emit(hookName, context) {
+    if (!HOOK_NAMES.includes(hookName)) return;
+
+    for (const plugin of this.#plugins) {
+      if (typeof plugin[hookName] === 'function') {
+        try {
+          await plugin[hookName](context);
+        } catch (err) {
+          console.error(`[CronWatch] Plugin "${plugin.name}" threw in ${hookName}:`, err);
+        }
+      }
+    }
+  }
+
+  get plugins() {
+    return this.#plugins.map((p) => p.name);
+  }
+}
+
+module.exports = { PluginManager, HOOK_NAMES };

package/src/retry.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const BACKOFF_STRATEGIES = {
+  fixed: (delay, _attempt) => delay,
+  linear: (delay, attempt) => delay * attempt,
+  exponential: (delay, attempt) => delay * Math.pow(2, attempt - 1),
+};
+
+function getDelay(strategy, baseDelay, attempt) {
+  const calc = BACKOFF_STRATEGIES[strategy] || BACKOFF_STRATEGIES.fixed;
+  return calc(baseDelay, attempt);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function withRetry(fn, options = {}, hooks = {}) {
+  const maxRetries = options.retries ?? 0;
+  const baseDelay = options.retryDelay ?? 1000;
+  const strategy = options.retryBackoff ?? 'fixed';
+
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+
+      if (attempt < maxRetries) {
+        const delay = getDelay(strategy, baseDelay, attempt + 1);
+        if (hooks.onRetry) {
+          await hooks.onRetry({ attempt: attempt + 1, maxRetries, delay, error: err });
+        }
+        await sleep(delay);
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+module.exports = { withRetry, BACKOFF_STRATEGIES };

package/src/store.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * Pluggable storage adapter interface.
+ *
+ * Any custom adapter must implement:
+ *   save(entry)          -> Promise<void>
+ *   getByJob(jobName)    -> Promise<Array>
+ *   getAll()             -> Promise<Array>
+ *   clear()              -> Promise<void>
+ */
+class StoreAdapter {
+  async save(_entry) { throw new Error('save() not implemented'); }
+  async getByJob(_jobName) { throw new Error('getByJob() not implemented'); }
+  async getAll() { throw new Error('getAll() not implemented'); }
+  async clear() { throw new Error('clear() not implemented'); }
+}
+
+class MemoryAdapter extends StoreAdapter {
+  #entries;
+  #maxEntries;
+
+  constructor(maxEntries = 1000) {
+    super();
+    this.#entries = [];
+    this.#maxEntries = maxEntries;
+  }
+
+  async save(entry) {
+    this.#entries.push(Object.freeze({ ...entry }));
+    if (this.#entries.length > this.#maxEntries) {
+      this.#entries = this.#entries.slice(-this.#maxEntries);
+    }
+  }
+
+  async getByJob(jobName) {
+    return this.#entries.filter((e) => e.jobName === jobName);
+  }
+
+  async getAll() {
+    return [...this.#entries];
+  }
+
+  async clear() {
+    this.#entries = [];
+  }
+
+  get size() {
+    return this.#entries.length;
+  }
+}
+
+class Store {
+  #adapter;
+
+  constructor(adapter) {
+    if (adapter && !(adapter instanceof StoreAdapter)) {
+      throw new TypeError('Store adapter must extend StoreAdapter');
+    }
+    this.#adapter = adapter || new MemoryAdapter();
+  }
+
+  save(entry) { return this.#adapter.save(entry); }
+  getByJob(jobName) { return this.#adapter.getByJob(jobName); }
+  getAll() { return this.#adapter.getAll(); }
+  clear() { return this.#adapter.clear(); }
+
+  get adapter() { return this.#adapter; }
+}
+
+module.exports = { Store, StoreAdapter, MemoryAdapter };

package/src/tracker.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const { withRetry } = require('./retry');
+
+class TimeoutError extends Error {
+  constructor(jobName, ms) {
+    super(`Job "${jobName}" timed out after ${ms}ms`);
+    this.name = 'TimeoutError';
+    this.code = 'ERR_JOB_TIMEOUT';
+  }
+}
+
+function withTimeout(fn, ms, jobName) {
+  if (!ms || ms <= 0) return fn();
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new TimeoutError(jobName, ms));
+    }, ms);
+
+    fn()
+      .then((val) => { clearTimeout(timer); resolve(val); })
+      .catch((err) => { clearTimeout(timer); reject(err); });
+  });
+}
+
+function buildEntry(jobName, status, startTime, endTime, error, retryCount) {
+  return {
+    jobName,
+    status,
+    startTime: startTime.toISOString(),
+    endTime: endTime.toISOString(),
+    duration: endTime - startTime,
+    error: error
+      ? { message: error.message, stack: error.stack, code: error.code || null }
+      : null,
+    retries: retryCount,
+  };
+}
+
+async function trackJob(jobName, jobFn, opts = {}, deps) {
+  const { logger, store, pluginManager, config } = deps;
+
+  if (typeof jobName !== 'string' || !jobName.trim()) {
+    throw new TypeError('jobName must be a non-empty string');
+  }
+  if (typeof jobFn !== 'function') {
+    throw new TypeError('jobFn must be a function');
+  }
+
+  const merged = config.merge(opts);
+  const timeout = merged.get('timeout');
+  const maxRetries = merged.get('retries');
+
+  let retryCount = 0;
+  const startTime = new Date();
+
+  logger.info(`Starting job "${jobName}"`, maxRetries > 0 ? { maxRetries } : undefined);
+  await pluginManager.emit('onStart', { jobName, startTime, config: merged });
+
+  try {
+    const wrappedFn = () => {
+      const result = jobFn();
+      const promise = result && typeof result.then === 'function' ? result : Promise.resolve(result);
+      return timeout > 0 ? withTimeout(() => promise, timeout, jobName) : promise;
+    };
+
+    const result = await withRetry(wrappedFn, merged.toJSON(), {
+      onRetry: async ({ attempt, delay, error }) => {
+        retryCount = attempt;
+        logger.warn(`Retrying job "${jobName}" (${attempt}/${maxRetries}) after ${delay}ms`, {
+          error: error.message,
+        });
+        await pluginManager.emit('onRetry', {
+          jobName, attempt, maxRetries, delay, error,
+        });
+      },
+    });
+
+    const endTime = new Date();
+    const entry = buildEntry(jobName, 'success', startTime, endTime, null, retryCount);
+
+    logger.info(`Job "${jobName}" completed in ${entry.duration}ms`);
+    await store.save(entry);
+    await pluginManager.emit('onSuccess', { jobName, entry, result });
+
+    return entry;
+  } catch (error) {
+    const endTime = new Date();
+    const isTimeout = error.name === 'TimeoutError';
+    const status = isTimeout ? 'timeout' : 'failure';
+    const entry = buildEntry(jobName, status, startTime, endTime, error, retryCount);
+
+    if (isTimeout) {
+      logger.error(`Job "${jobName}" timed out after ${timeout}ms`);
+      await pluginManager.emit('onTimeout', { jobName, entry, error });
+    } else {
+      logger.error(`Job "${jobName}" failed after ${retryCount} retries`, error);
+      await pluginManager.emit('onFailure', { jobName, entry, error });
+    }
+
+    await store.save(entry);
+    return entry;
+  }
+}
+
+module.exports = { trackJob, TimeoutError };

package/types/index.d.ts

@@ -0,0 +1,142 @@
+export interface CronWatchOptions {
+  /** Max retry attempts (default: 0) */
+  retries?: number;
+  /** Base delay between retries in ms (default: 1000) */
+  retryDelay?: number;
+  /** Backoff strategy: 'fixed' | 'linear' | 'exponential' (default: 'fixed') */
+  retryBackoff?: 'fixed' | 'linear' | 'exponential';
+  /** Job timeout in ms, 0 = no timeout (default: 0) */
+  timeout?: number;
+  /** Minimum log level (default: LOG_LEVELS.INFO) */
+  logLevel?: number;
+  /** Max entries retained in memory store (default: 1000) */
+  storeMaxEntries?: number;
+  /** Include ISO timestamps in logs (default: true) */
+  timestamps?: boolean;
+  /** Colorize console output (default: true) */
+  colorize?: boolean;
+  /** Custom store adapter instance */
+  storeAdapter?: StoreAdapter;
+}
+
+export interface JobTrackOptions {
+  retries?: number;
+  retryDelay?: number;
+  retryBackoff?: 'fixed' | 'linear' | 'exponential';
+  timeout?: number;
+}
+
+export interface JobEntry {
+  jobName: string;
+  status: 'success' | 'failure' | 'timeout';
+  startTime: string;
+  endTime: string;
+  duration: number;
+  error: JobError | null;
+  retries: number;
+}
+
+export interface JobError {
+  message: string;
+  stack: string;
+  code: string | null;
+}
+
+export interface PluginContext {
+  jobName: string;
+  [key: string]: unknown;
+}
+
+export interface CronWatchPlugin {
+  name: string;
+  onStart?(ctx: PluginContext): void | Promise<void>;
+  onSuccess?(ctx: PluginContext): void | Promise<void>;
+  onFailure?(ctx: PluginContext): void | Promise<void>;
+  onRetry?(ctx: PluginContext): void | Promise<void>;
+  onTimeout?(ctx: PluginContext): void | Promise<void>;
+}
+
+export declare class Config {
+  constructor(overrides?: Partial<CronWatchOptions>);
+  get<K extends keyof CronWatchOptions>(key: K): CronWatchOptions[K];
+  set<K extends keyof CronWatchOptions>(key: K, value: CronWatchOptions[K]): this;
+  merge(overrides?: Partial<CronWatchOptions>): Config;
+  toJSON(): CronWatchOptions;
+}
+
+export declare class Logger {
+  constructor(config: Config);
+  addOutput(fn: (entry: object, formatted: string) => void): this;
+  debug(msg: string, meta?: unknown): void;
+  info(msg: string, meta?: unknown): void;
+  warn(msg: string, meta?: unknown): void;
+  error(msg: string, meta?: unknown): void;
+}
+
+export declare class StoreAdapter {
+  save(entry: JobEntry): Promise<void>;
+  getByJob(jobName: string): Promise<JobEntry[]>;
+  getAll(): Promise<JobEntry[]>;
+  clear(): Promise<void>;
+}
+
+export declare class MemoryAdapter extends StoreAdapter {
+  constructor(maxEntries?: number);
+  readonly size: number;
+}
+
+export declare class Store {
+  constructor(adapter?: StoreAdapter);
+  save(entry: JobEntry): Promise<void>;
+  getByJob(jobName: string): Promise<JobEntry[]>;
+  getAll(): Promise<JobEntry[]>;
+  clear(): Promise<void>;
+  readonly adapter: StoreAdapter;
+}
+
+export declare class PluginManager {
+  register(plugin: CronWatchPlugin): this;
+  emit(hookName: string, context: PluginContext): Promise<void>;
+  readonly plugins: string[];
+}
+
+export declare class TimeoutError extends Error {
+  readonly code: string;
+  constructor(jobName: string, ms: number);
+}
+
+export declare class CronWatch {
+  constructor(options?: CronWatchOptions);
+  trackJob(
+    jobName: string,
+    jobFn: () => unknown | Promise<unknown>,
+    options?: JobTrackOptions
+  ): Promise<JobEntry>;
+  use(plugin: CronWatchPlugin): this;
+  getJobLogs(jobName: string): Promise<JobEntry[]>;
+  getAllLogs(): Promise<JobEntry[]>;
+  clearLogs(): Promise<void>;
+  readonly config: Config;
+  readonly logger: Logger;
+  readonly plugins: string[];
+}
+
+export declare function createCronWatch(options?: CronWatchOptions): CronWatch;
+
+export declare const LOG_LEVELS: {
+  readonly DEBUG: 0;
+  readonly INFO: 1;
+  readonly WARN: 2;
+  readonly ERROR: 3;
+  readonly SILENT: 4;
+};
+
+export declare const DEFAULTS: Readonly<CronWatchOptions>;
+
+export declare const HOOK_NAMES: readonly string[];
+
+export declare const BACKOFF_STRATEGIES: {
+  readonly fixed: (delay: number, attempt: number) => number;
+  readonly linear: (delay: number, attempt: number) => number;
+  readonly exponential: (delay: number, attempt: number) => number;
+};