oqronkit 0.0.1-alpha.1

package/dist/core/types/config.types.d.ts

@@ -0,0 +1,119 @@
+import type { ChronoLoggerConfig } from "../logger/index.js";
+import type { IOqronAdapter } from "./db.types.js";
+import type { ILockAdapter } from "./lock.types.js";
+export type DbAdapterType = "sqlite" | "memory" | "postgres" | "mysql" | "mongodb" | "redis";
+export type LockAdapterType = "db" | "memory" | "redis";
+export interface OqronConfig {
+    /**
+     * The name of this project/service (e.g. 'acme-billing-svc')
+     */
+    project?: string;
+    /**
+     * Environment isolation.
+     * Workers in 'development' will never execute jobs enqueued in 'production'.
+     * @default "development"
+     */
+    environment?: string;
+    /**
+     * The primary database adapter (State Store).
+     * Union of explicit DI or declarative config.
+     */
+    db?: IOqronAdapter | {
+        adapter: DbAdapterType;
+        url?: string;
+        poolMin?: number;
+        poolMax?: number;
+        tablePrefix?: string;
+        migrations?: "auto" | "manual" | false;
+        ssl?: boolean;
+    };
+    /**
+     * The distributed lock adapter for safe concurrency.
+     * Union of explicit DI or declarative config.
+     */
+    lock?: ILockAdapter | {
+        adapter: LockAdapterType;
+        url?: string;
+        ttl?: number;
+        retryDelay?: number;
+        retryCount?: number;
+    };
+    /**
+     * The high-throughput message broker (optional, for PubSub/Queueing at scale)
+     */
+    broker?: any;
+    /**
+     * List of core modules to enable.
+     * e.g. ['cron', 'queue', 'workflow', 'batch', 'webhook', 'pipeline']
+     * @default []
+     */
+    modules?: ("cron" | "scheduler" | "queue" | "workflow" | "batch" | "webhook" | "pipeline")[];
+    /**
+     * Module-specific configs
+     */
+    cron?: {
+        enable?: boolean;
+        timezone?: string;
+        tickInterval?: number;
+        missedFirePolicy?: "skip" | "run-once" | "run-all";
+        maxConcurrentJobs?: number;
+        leaderElection?: boolean;
+        /** Rolling execution history. `true` = infinite, `false` = 0, `number` = keep N */
+        keepJobHistory?: boolean | number;
+        /** Override for failed tasks. Handled explicitly under errors */
+        keepFailedJobHistory?: boolean | number;
+    };
+    scheduler?: {
+        enable?: boolean;
+        tickInterval?: number;
+        keepJobHistory?: boolean | number;
+        keepFailedJobHistory?: boolean | number;
+    };
+    /**
+     * Directory to auto-discover job definition files from.
+     * OqronKit.init() scans this directory recursively for .ts/.js files
+     * that export definitions and registers them automatically.
+     * @default "./src/jobs"
+     */
+    jobsDir?: string;
+    /**
+     * Global tags applied to every job processed by this node.
+     * @default []
+     */
+    tags?: string[];
+    /**
+     * Worker-level configurations
+     */
+    worker?: {
+        /** Number of concurrent jobs this node processes simultaneously */
+        concurrency?: number;
+        /** Time in ms to wait for active jobs before SIGTERM exits */
+        gracefulShutdownMs?: number;
+    };
+    /**
+     * Logger configuration (powered by voltlog-io).
+     * Set to `false` to disable logging entirely.
+     */
+    logger?: ChronoLoggerConfig | false;
+    /**
+     * Telemetry configuration
+     */
+    telemetry?: {
+        prometheus?: {
+            enabled?: boolean;
+            path?: string;
+        };
+        opentelemetry?: {
+            enabled?: boolean;
+        };
+    };
+    /**
+     * Graceful shutdown configuration
+     */
+    shutdown?: {
+        enabled?: boolean;
+        timeout?: number;
+        signals?: string[];
+    };
+}
+//# sourceMappingURL=config.types.d.ts.map

package/dist/core/types/config.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.types.d.ts","sourceRoot":"","sources":["../../../src/core/types/config.types.ts"],"names":[],"mappings":"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"}

package/dist/core/types/cron.types.d.ts

@@ -0,0 +1,53 @@
+import type { ICronContext } from "../context/cron-context.interface.js";
+export type MissedFirePolicy = "skip" | "run-once" | "run-all";
+export type OverlapPolicy = "skip" | "run" | boolean;
+export interface EveryConfig {
+    seconds?: number;
+    minutes?: number;
+    hours?: number;
+}
+export interface RetryConfig {
+    max: number;
+    strategy: "exponential" | "fixed";
+    baseDelay: number;
+}
+export interface CronHooks {
+    beforeRun?: (ctx: ICronContext) => Promise<void> | void;
+    afterRun?: (ctx: ICronContext, result: unknown) => Promise<void> | void;
+    onError?: (ctx: ICronContext, error: Error) => Promise<void> | void;
+    onMissedFire?: (ctx: ICronContext, missedAt: Date) => Promise<void> | void;
+}
+export interface CronDefinition {
+    name: string;
+    expression?: string;
+    intervalMs?: number;
+    timezone?: string;
+    missedFire: MissedFirePolicy;
+    overlap: OverlapPolicy;
+    guaranteedWorker?: boolean;
+    heartbeatMs?: number;
+    lockTtlMs?: number;
+    timeout?: number;
+    tags: string[];
+    /** Override global history rolling. `true` = infinite, `false` = none, `number` = max retained jobs. */
+    keepHistory?: boolean | number;
+    /** Keep specific bounded history length for failed jobs overriding general logic */
+    keepFailedHistory?: boolean | number;
+    handler: (ctx: ICronContext) => Promise<unknown>;
+    hooks?: CronHooks;
+    retries?: RetryConfig;
+}
+export interface JobRecord {
+    id: string;
+    scheduleId?: string;
+    status: "running" | "completed" | "failed" | "missed" | "dead";
+    startedAt: Date;
+    completedAt?: Date;
+    error?: string;
+    result?: string;
+    progressPercent?: number;
+    progressLabel?: string;
+    attempts?: number;
+    durationMs?: number;
+}
+//# sourceMappingURL=cron.types.d.ts.map

package/dist/core/types/cron.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.types.d.ts","sourceRoot":"","sources":["../../../src/core/types/cron.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEzE,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAC/D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;AAErD,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxD,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxE,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpE,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC5E;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,OAAO,EAAE,aAAa,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wGAAwG;IACxG,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC/B,oFAAoF;IACpF,iBAAiB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACrC,OAAO,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC/D,SAAS,EAAE,IAAI,CAAC;IAChB,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/core/types/db.types.d.ts

@@ -0,0 +1,32 @@
+import type { CronDefinition, JobRecord } from "./cron.types.js";
+import type { ScheduleDefinition } from "./scheduler.types.js";
+export interface IOqronAdapter {
+    /** Insert or update a schedule definition */
+    upsertSchedule(def: CronDefinition | ScheduleDefinition): Promise<void>;
+    /** Get schedules that are due to fire (nextRunAt <= now, or never run) */
+    getDueSchedules(now: Date, limit: number, prefix?: string): Promise<Pick<CronDefinition | ScheduleDefinition, "name">[]>;
+    /** Get all registered schedules and their run metadata */
+    getSchedules(prefix?: string): Promise<Array<{
+        name: string;
+        lastRunAt: Date | null;
+        nextRunAt: Date | null;
+    }>>;
+    /** Update nextRunAt for a schedule */
+    updateNextRun(scheduleId: string, nextRunAt: Date | null): Promise<void>;
+    /** Record a job execution (insert or update) */
+    recordExecution(job: JobRecord): Promise<void>;
+    /** Update progress of an active job */
+    updateJobProgress(id: string, progressPercent: number, progressLabel?: string): Promise<void>;
+    /** Get execution history for a schedule */
+    getExecutions(scheduleId: string, opts: {
+        limit: number;
+        offset: number;
+    }): Promise<JobRecord[]>;
+    /** Get all jobs currently marked as running */
+    getActiveJobs(): Promise<JobRecord[]>;
+    /** Clean old execution records */
+    cleanOldExecutions(before: Date): Promise<number>;
+    /** Roll history based on config settings */
+    pruneHistoryForSchedule(scheduleId: string, keepJobHistory: number | boolean, keepFailedJobHistory: number | boolean): Promise<void>;
+}
+//# sourceMappingURL=db.types.d.ts.map

package/dist/core/types/db.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.types.d.ts","sourceRoot":"","sources":["../../../src/core/types/db.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExE,0EAA0E;IAC1E,eAAe,CACb,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,cAAc,GAAG,kBAAkB,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IAEhE,0DAA0D;IAC1D,YAAY,CACV,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CACR,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;QAAC,SAAS,EAAE,IAAI,GAAG,IAAI,CAAA;KAAE,CAAC,CACxE,CAAC;IAEF,sCAAsC;IACtC,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzE,gDAAgD;IAChD,eAAe,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C,uCAAuC;IACvC,iBAAiB,CACf,EAAE,EAAE,MAAM,EACV,eAAe,EAAE,MAAM,EACvB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,2CAA2C;IAC3C,aAAa,CACX,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GACtC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAExB,+CAA+C;IAC/C,aAAa,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAEtC,kCAAkC;IAClC,kBAAkB,CAAC,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAElD,4CAA4C;IAC5C,uBAAuB,CACrB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GAAG,OAAO,EAChC,oBAAoB,EAAE,MAAM,GAAG,OAAO,GACrC,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB"}

package/dist/core/types/index.d.ts

@@ -0,0 +1,7 @@
+export type { OqronConfig } from "./config.types.js";
+export type { CronDefinition, CronHooks, EveryConfig, JobRecord, MissedFirePolicy, OverlapPolicy, } from "./cron.types.js";
+export type { IOqronAdapter } from "./db.types.js";
+export type { ILockAdapter } from "./lock.types.js";
+export type { IChronoModule } from "./module.types.js";
+export type { IScheduleContext, ScheduleDefinition, ScheduleHooks, ScheduleRecurring, ScheduleRunAfter, } from "./scheduler.types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,YAAY,EACV,cAAc,EACd,SAAS,EACT,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC"}

package/dist/core/types/lock.types.d.ts

@@ -0,0 +1,7 @@
+export interface ILockAdapter {
+    acquire(key: string, ownerId: string, ttlMs: number): Promise<boolean>;
+    renew(key: string, ownerId: string, ttlMs: number): Promise<boolean>;
+    release(key: string, ownerId: string): Promise<void>;
+    isOwner(key: string, ownerId: string): Promise<boolean>;
+}
+//# sourceMappingURL=lock.types.d.ts.map

package/dist/core/types/lock.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.types.d.ts","sourceRoot":"","sources":["../../../src/core/types/lock.types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzD"}

package/dist/core/types/module.types.d.ts

@@ -0,0 +1,8 @@
+export interface IChronoModule {
+    readonly name: string;
+    readonly enabled: boolean;
+    init(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=module.types.d.ts.map

package/dist/core/types/module.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.types.d.ts","sourceRoot":"","sources":["../../../src/core/types/module.types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB"}

package/dist/core/types/scheduler.types.d.ts

@@ -0,0 +1,62 @@
+import type { MissedFirePolicy, OverlapPolicy, RetryConfig } from "./cron.types.js";
+export interface ScheduleRecurring {
+    frequency: "daily" | "weekly" | "monthly" | "yearly";
+    dayOfMonth?: number;
+    at?: {
+        hour: number;
+        minute: number;
+    };
+    months?: number[];
+}
+export interface ScheduleRunAfter {
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+}
+export interface ScheduleHooks<TPayload = unknown> {
+    beforeRun?: (ctx: IScheduleContext<TPayload>) => Promise<void> | void;
+    afterRun?: (ctx: IScheduleContext<TPayload>, result: unknown) => Promise<void> | void;
+    onError?: (ctx: IScheduleContext<TPayload>, error: Error) => Promise<void> | void;
+    onMissedFire?: (ctx: IScheduleContext<TPayload>, missedAt: Date) => Promise<void> | void;
+}
+export interface IScheduleContext<TPayload = unknown> {
+    name: string;
+    firedAt: Date;
+    payload: TPayload;
+    duration: number;
+    environment?: string;
+    project?: string;
+    log(level: string, message: string, meta?: Record<string, unknown>): void;
+    progress(percent: number, label?: string): void;
+}
+export interface ScheduleDefinition<TPayload = unknown> {
+    name: string;
+    runAt?: Date;
+    runAfter?: ScheduleRunAfter;
+    recurring?: ScheduleRecurring;
+    rrule?: string;
+    every?: {
+        minutes?: number;
+        hours?: number;
+        seconds?: number;
+    };
+    timezone?: string;
+    missedFire: MissedFirePolicy;
+    overlap: OverlapPolicy;
+    guaranteedWorker?: boolean;
+    heartbeatMs?: number;
+    lockTtlMs?: number;
+    timeout?: number;
+    tags: string[];
+    /** Override global history rolling. `true` = infinite, `false` = none, `number` = max retained jobs. */
+    keepHistory?: boolean | number;
+    /** Keep specific bounded history length for failed jobs overriding general logic */
+    keepFailedHistory?: boolean | number;
+    condition?: (ctx: IScheduleContext<TPayload>) => Promise<boolean> | boolean;
+    handler: (ctx: IScheduleContext<TPayload>) => Promise<unknown>;
+    hooks?: ScheduleHooks<TPayload>;
+    retries?: RetryConfig;
+    payload?: TPayload;
+}
+//# sourceMappingURL=scheduler.types.d.ts.map

package/dist/core/types/scheduler.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.types.d.ts","sourceRoot":"","sources":["../../../src/core/types/scheduler.types.ts"],"names":[],"mappings":"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"}

package/dist/cron-V0k1GcxJ.d.mts

@@ -0,0 +1,102 @@
+import { Logger } from 'voltlog-io';
+
+interface ICronContext {
+    readonly id: string;
+    readonly log: Logger;
+    readonly signal: AbortSignal;
+    readonly firedAt: Date;
+    readonly scheduleName: string;
+    readonly duration: number;
+    readonly environment?: string;
+    readonly project?: string;
+    progress(value: number, label?: string): void;
+    getProgress(): number;
+}
+
+type MissedFirePolicy = "skip" | "run-once" | "run-all";
+type OverlapPolicy = "skip" | "run" | boolean;
+interface EveryConfig {
+    seconds?: number;
+    minutes?: number;
+    hours?: number;
+}
+interface RetryConfig {
+    max: number;
+    strategy: "exponential" | "fixed";
+    baseDelay: number;
+}
+interface CronHooks {
+    beforeRun?: (ctx: ICronContext) => Promise<void> | void;
+    afterRun?: (ctx: ICronContext, result: unknown) => Promise<void> | void;
+    onError?: (ctx: ICronContext, error: Error) => Promise<void> | void;
+    onMissedFire?: (ctx: ICronContext, missedAt: Date) => Promise<void> | void;
+}
+interface CronDefinition {
+    name: string;
+    expression?: string;
+    intervalMs?: number;
+    timezone?: string;
+    missedFire: MissedFirePolicy;
+    overlap: OverlapPolicy;
+    guaranteedWorker?: boolean;
+    heartbeatMs?: number;
+    lockTtlMs?: number;
+    timeout?: number;
+    tags: string[];
+    /** Override global history rolling. `true` = infinite, `false` = none, `number` = max retained jobs. */
+    keepHistory?: boolean | number;
+    /** Keep specific bounded history length for failed jobs overriding general logic */
+    keepFailedHistory?: boolean | number;
+    handler: (ctx: ICronContext) => Promise<unknown>;
+    hooks?: CronHooks;
+    retries?: RetryConfig;
+}
+interface JobRecord {
+    id: string;
+    scheduleId?: string;
+    status: "running" | "completed" | "failed" | "missed" | "dead";
+    startedAt: Date;
+    completedAt?: Date;
+    error?: string;
+    result?: string;
+    progressPercent?: number;
+    progressLabel?: string;
+    attempts?: number;
+    durationMs?: number;
+}
+
+type CronScheduleConfig = {
+    expression: string;
+    every?: never;
+} | {
+    every: EveryConfig;
+    expression?: never;
+};
+type DefineCronOptions = CronScheduleConfig & {
+    name: string;
+    timezone?: string;
+    missedFire?: MissedFirePolicy;
+    overlap?: OverlapPolicy;
+    guaranteedWorker?: boolean;
+    heartbeatMs?: number;
+    lockTtlMs?: number;
+    timeout?: number;
+    tags?: string[];
+    handler: (ctx: ICronContext) => Promise<unknown>;
+    hooks?: CronHooks;
+    retries?: RetryConfig;
+};
+/**
+ * Define a cron job. Automatically registers it with OqronKit
+ * so that `OqronKit.init()` discovers it without manual wiring.
+ *
+ * @example
+ * // Expression-based
+ * cron({ name: 'billing', expression: '0 0 1 * *', handler: ... })
+ *
+ * // Interval-based
+ * cron({ name: 'sync', every: { minutes: 15 }, handler: ... })
+ */
+declare const cron: (options: DefineCronOptions) => CronDefinition;
+
+export { type CronDefinition as C, type DefineCronOptions as D, type JobRecord as J, type MissedFirePolicy as M, type OverlapPolicy as O, type RetryConfig as R, cron as c };

package/dist/cron-V0k1GcxJ.d.ts

@@ -0,0 +1,102 @@
+import { Logger } from 'voltlog-io';
+
+interface ICronContext {
+    readonly id: string;
+    readonly log: Logger;
+    readonly signal: AbortSignal;
+    readonly firedAt: Date;
+    readonly scheduleName: string;
+    readonly duration: number;
+    readonly environment?: string;
+    readonly project?: string;
+    progress(value: number, label?: string): void;
+    getProgress(): number;
+}
+
+type MissedFirePolicy = "skip" | "run-once" | "run-all";
+type OverlapPolicy = "skip" | "run" | boolean;
+interface EveryConfig {
+    seconds?: number;
+    minutes?: number;
+    hours?: number;
+}
+interface RetryConfig {
+    max: number;
+    strategy: "exponential" | "fixed";
+    baseDelay: number;
+}
+interface CronHooks {
+    beforeRun?: (ctx: ICronContext) => Promise<void> | void;
+    afterRun?: (ctx: ICronContext, result: unknown) => Promise<void> | void;
+    onError?: (ctx: ICronContext, error: Error) => Promise<void> | void;
+    onMissedFire?: (ctx: ICronContext, missedAt: Date) => Promise<void> | void;
+}
+interface CronDefinition {
+    name: string;
+    expression?: string;
+    intervalMs?: number;
+    timezone?: string;
+    missedFire: MissedFirePolicy;
+    overlap: OverlapPolicy;
+    guaranteedWorker?: boolean;
+    heartbeatMs?: number;
+    lockTtlMs?: number;
+    timeout?: number;
+    tags: string[];
+    /** Override global history rolling. `true` = infinite, `false` = none, `number` = max retained jobs. */
+    keepHistory?: boolean | number;
+    /** Keep specific bounded history length for failed jobs overriding general logic */
+    keepFailedHistory?: boolean | number;
+    handler: (ctx: ICronContext) => Promise<unknown>;
+    hooks?: CronHooks;
+    retries?: RetryConfig;
+}
+interface JobRecord {
+    id: string;
+    scheduleId?: string;
+    status: "running" | "completed" | "failed" | "missed" | "dead";
+    startedAt: Date;
+    completedAt?: Date;
+    error?: string;
+    result?: string;
+    progressPercent?: number;
+    progressLabel?: string;
+    attempts?: number;
+    durationMs?: number;
+}
+
+type CronScheduleConfig = {
+    expression: string;
+    every?: never;
+} | {
+    every: EveryConfig;
+    expression?: never;
+};
+type DefineCronOptions = CronScheduleConfig & {
+    name: string;
+    timezone?: string;
+    missedFire?: MissedFirePolicy;
+    overlap?: OverlapPolicy;
+    guaranteedWorker?: boolean;
+    heartbeatMs?: number;
+    lockTtlMs?: number;
+    timeout?: number;
+    tags?: string[];
+    handler: (ctx: ICronContext) => Promise<unknown>;
+    hooks?: CronHooks;
+    retries?: RetryConfig;
+};
+/**
+ * Define a cron job. Automatically registers it with OqronKit
+ * so that `OqronKit.init()` discovers it without manual wiring.
+ *
+ * @example
+ * // Expression-based
+ * cron({ name: 'billing', expression: '0 0 1 * *', handler: ... })
+ *
+ * // Interval-based
+ * cron({ name: 'sync', every: { minutes: 15 }, handler: ... })
+ */
+declare const cron: (options: DefineCronOptions) => CronDefinition;
+
+export { type CronDefinition as C, type DefineCronOptions as D, type JobRecord as J, type MissedFirePolicy as M, type OverlapPolicy as O, type RetryConfig as R, cron as c };

package/dist/cron.d.mts

@@ -0,0 +1,2 @@
+export { D as DefineCronOptions, c as cron } from './cron-V0k1GcxJ.mjs';
+import 'voltlog-io';

package/dist/cron.d.ts

@@ -0,0 +1,2 @@
+export { cron, type DefineCronOptions } from "./scheduler/index.js";
+//# sourceMappingURL=cron.d.ts.map

package/dist/cron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.d.ts","sourceRoot":"","sources":["../src/cron.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC"}