@queuebase/core 1.3.0 → 1.5.0

package/dist/index.d.cts

@@ -23,6 +23,39 @@ interface EnqueueOptions {
     /** Maximum concurrent jobs of this type (per worker) */
     concurrency?: number;
 }
+/**
+ * Overlap policy for scheduled jobs
+ */
+type OverlapPolicy = 'skip' | 'allow';
+/**
+ * Full schedule configuration object
+ */
+interface ScheduleConfig {
+    /** Cron expression or plain english shorthand */
+    cron: string;
+    /** IANA timezone (default: 'UTC') */
+    timezone?: string;
+    /** Whether this schedule is active in code (default: true) */
+    enabled?: boolean;
+    /** Overlap policy when previous run is still running (default: 'skip') */
+    overlap?: OverlapPolicy;
+    /** Timeout for scheduled runs (e.g., '5m', '30s', or milliseconds) */
+    timeout?: string | number;
+}
+/**
+ * Schedule can be a plain english/cron string shorthand or a full config object
+ */
+type ScheduleInput = string | ScheduleConfig;
+/**
+ * Resolved schedule metadata after parsing — always has a standard cron expression
+ */
+interface ResolvedSchedule {
+    cronExpression: string;
+    timezone: string;
+    enabled: boolean;
+    overlap: OverlapPolicy;
+    timeoutMs: number | null;
+}
 /**
  * A job definition with typed input/output
  */
@@ -33,6 +66,8 @@ interface JobDefinition<TInput = unknown, TOutput = unknown> {
     handler: (ctx: JobContext<TInput>) => Promise<TOutput>;
     /** Default options for this job */
     defaults?: EnqueueOptions;
+    /** Cron schedule — only valid when input accepts empty object */
+    schedule?: ScheduleInput;
 }
 /**
  * Context passed to job handlers
@@ -46,6 +81,8 @@ interface JobContext<TInput = unknown> {
     attempt: number;
     /** Maximum attempts allowed */
     maxAttempts: number;
+    /** Explicitly mark this job as failed */
+    fail: (reason: string) => never;
 }
 /**
  * Internal representation of a queued job
@@ -119,6 +156,7 @@ interface AnyJobDefinition {
     input: z.ZodTypeAny;
     handler: (ctx: JobContext<unknown>) => Promise<unknown>;
     defaults?: EnqueueOptions;
+    schedule?: ScheduleInput;
 }
 /**
  * A collection of job definitions
@@ -159,13 +197,28 @@ type JobClient<T extends Record<string, AnyJobDefinition>> = CallableJobRouter<T
 };
 
 /**
- * Creates a job definition with typed input and handler
+ * A job definition that accepts empty input — schedule is allowed.
  */
-declare function job<TInput, TOutput>(definition: {
+interface SchedulableJobConfig<TInput extends Record<string, never>, TOutput> {
     input: z.ZodType<TInput>;
     handler: (ctx: JobContext<TInput>) => Promise<TOutput>;
     defaults?: EnqueueOptions;
-}): AnyJobDefinition;
+    schedule?: ScheduleInput;
+}
+/**
+ * A job definition with non-empty input — schedule is not allowed.
+ */
+interface NonSchedulableJobConfig<TInput, TOutput> {
+    input: z.ZodType<TInput>;
+    handler: (ctx: JobContext<TInput>) => Promise<TOutput>;
+    defaults?: EnqueueOptions;
+}
+/**
+ * Creates a job definition with typed input and handler.
+ * The `schedule` property is only available when the input schema accepts `{}`.
+ */
+declare function job<TInput extends Record<string, never>, TOutput>(definition: SchedulableJobConfig<TInput, TOutput>): AnyJobDefinition;
+declare function job<TInput, TOutput>(definition: NonSchedulableJobConfig<TInput, TOutput>): AnyJobDefinition;
 /**
  * Infer the input type from a job definition's Zod schema
  */
@@ -175,6 +228,44 @@ type InferJobInput<T extends AnyJobDefinition> = T['input'] extends z.ZodType<in
  */
 type InferJobOutput<T extends AnyJobDefinition> = T['handler'] extends (ctx: JobContext<unknown>) => Promise<infer O> ? O : never;
 
+/**
+ * Parse a plain english expression to a cron string.
+ * Returns the input unchanged if no pattern matches (assumed to be raw cron).
+ */
+declare function parsePlainEnglish(expression: string): string;
+/**
+ * Validate a cron expression using croner.
+ * Throws if the expression is invalid.
+ */
+declare function validateCron(expression: string): void;
+/**
+ * Compute the next run time for a cron expression with optional timezone.
+ */
+declare function nextRun(expression: string, timezone?: string): Date | null;
+/**
+ * Compute multiple next run times for a cron expression.
+ */
+declare function nextRuns(expression: string, count: number, timezone?: string): Date[];
+/**
+ * Resolve a schedule input into a fully resolved schedule.
+ * Parses plain english, validates the cron expression, and resolves defaults.
+ */
+declare function resolveSchedule(input: ScheduleInput): ResolvedSchedule;
+/**
+ * Metadata for a single schedule extracted from a job router.
+ */
+interface ScheduleMetadata {
+    jobName: string;
+    schedule: ResolvedSchedule;
+}
+/**
+ * Extract all schedule metadata from a job router.
+ * Only includes jobs that have a schedule defined.
+ */
+declare function extractSchedules(router: Record<string, {
+    schedule?: ScheduleInput;
+}>): ScheduleMetadata[];
+
 /**
  * Parse a delay string into milliseconds
  * Supports: '5s', '5m', '5h', '5d' or raw milliseconds
@@ -213,6 +304,9 @@ declare function signPayload(payload: string, secret: string): {
  */
 declare function verifySignature(payload: string, signature: string, secret: string, toleranceSeconds?: number): boolean;
 
+declare class JobFailureError extends Error {
+    constructor(reason: string);
+}
 interface HandlerRequest {
     body: string;
     signatureHeader: string | null;
@@ -225,4 +319,4 @@ declare function processJobCallback(router: Record<string, AnyJobDefinition>, re
     webhookSecret?: string;
 }): Promise<HandlerResponse>;
 
-export { type AnyJobDefinition, type BackoffStrategy, type CallableJob, type CallableJobRouter, type EnqueueOptions, type EnqueueResult, type HandlerRequest, type HandlerResponse, type InferJobInput, type InferJobOutput, type JobClient, type JobContext, type JobDefinition, type JobResult, type JobRouter, type JobStatus, type JobStatusResponse, type QueuebaseConfig, type QueuedJob, WEBHOOK_HEADERS, calculateBackoff, createJobRouter, generateJobId, generatePublicId, job, parseDelay, processJobCallback, signPayload, verifySignature };
+export { type AnyJobDefinition, type BackoffStrategy, type CallableJob, type CallableJobRouter, type EnqueueOptions, type EnqueueResult, type HandlerRequest, type HandlerResponse, type InferJobInput, type InferJobOutput, type JobClient, type JobContext, type JobDefinition, JobFailureError, type JobResult, type JobRouter, type JobStatus, type JobStatusResponse, type OverlapPolicy, type QueuebaseConfig, type QueuedJob, type ResolvedSchedule, type ScheduleConfig, type ScheduleInput, type ScheduleMetadata, WEBHOOK_HEADERS, calculateBackoff, createJobRouter, extractSchedules, generateJobId, generatePublicId, job, nextRun, nextRuns, parseDelay, parsePlainEnglish, processJobCallback, resolveSchedule, signPayload, validateCron, verifySignature };

package/dist/index.d.ts

@@ -23,6 +23,39 @@ interface EnqueueOptions {
     /** Maximum concurrent jobs of this type (per worker) */
     concurrency?: number;
 }
+/**
+ * Overlap policy for scheduled jobs
+ */
+type OverlapPolicy = 'skip' | 'allow';
+/**
+ * Full schedule configuration object
+ */
+interface ScheduleConfig {
+    /** Cron expression or plain english shorthand */
+    cron: string;
+    /** IANA timezone (default: 'UTC') */
+    timezone?: string;
+    /** Whether this schedule is active in code (default: true) */
+    enabled?: boolean;
+    /** Overlap policy when previous run is still running (default: 'skip') */
+    overlap?: OverlapPolicy;
+    /** Timeout for scheduled runs (e.g., '5m', '30s', or milliseconds) */
+    timeout?: string | number;
+}
+/**
+ * Schedule can be a plain english/cron string shorthand or a full config object
+ */
+type ScheduleInput = string | ScheduleConfig;
+/**
+ * Resolved schedule metadata after parsing — always has a standard cron expression
+ */
+interface ResolvedSchedule {
+    cronExpression: string;
+    timezone: string;
+    enabled: boolean;
+    overlap: OverlapPolicy;
+    timeoutMs: number | null;
+}
 /**
  * A job definition with typed input/output
  */
@@ -33,6 +66,8 @@ interface JobDefinition<TInput = unknown, TOutput = unknown> {
     handler: (ctx: JobContext<TInput>) => Promise<TOutput>;
     /** Default options for this job */
     defaults?: EnqueueOptions;
+    /** Cron schedule — only valid when input accepts empty object */
+    schedule?: ScheduleInput;
 }
 /**
  * Context passed to job handlers
@@ -46,6 +81,8 @@ interface JobContext<TInput = unknown> {
     attempt: number;
     /** Maximum attempts allowed */
     maxAttempts: number;
+    /** Explicitly mark this job as failed */
+    fail: (reason: string) => never;
 }
 /**
  * Internal representation of a queued job
@@ -119,6 +156,7 @@ interface AnyJobDefinition {
     input: z.ZodTypeAny;
     handler: (ctx: JobContext<unknown>) => Promise<unknown>;
     defaults?: EnqueueOptions;
+    schedule?: ScheduleInput;
 }
 /**
  * A collection of job definitions
@@ -159,13 +197,28 @@ type JobClient<T extends Record<string, AnyJobDefinition>> = CallableJobRouter<T
 };
 
 /**
- * Creates a job definition with typed input and handler
+ * A job definition that accepts empty input — schedule is allowed.
  */
-declare function job<TInput, TOutput>(definition: {
+interface SchedulableJobConfig<TInput extends Record<string, never>, TOutput> {
     input: z.ZodType<TInput>;
     handler: (ctx: JobContext<TInput>) => Promise<TOutput>;
     defaults?: EnqueueOptions;
-}): AnyJobDefinition;
+    schedule?: ScheduleInput;
+}
+/**
+ * A job definition with non-empty input — schedule is not allowed.
+ */
+interface NonSchedulableJobConfig<TInput, TOutput> {
+    input: z.ZodType<TInput>;
+    handler: (ctx: JobContext<TInput>) => Promise<TOutput>;
+    defaults?: EnqueueOptions;
+}
+/**
+ * Creates a job definition with typed input and handler.
+ * The `schedule` property is only available when the input schema accepts `{}`.
+ */
+declare function job<TInput extends Record<string, never>, TOutput>(definition: SchedulableJobConfig<TInput, TOutput>): AnyJobDefinition;
+declare function job<TInput, TOutput>(definition: NonSchedulableJobConfig<TInput, TOutput>): AnyJobDefinition;
 /**
  * Infer the input type from a job definition's Zod schema
  */
@@ -175,6 +228,44 @@ type InferJobInput<T extends AnyJobDefinition> = T['input'] extends z.ZodType<in
  */
 type InferJobOutput<T extends AnyJobDefinition> = T['handler'] extends (ctx: JobContext<unknown>) => Promise<infer O> ? O : never;
 
+/**
+ * Parse a plain english expression to a cron string.
+ * Returns the input unchanged if no pattern matches (assumed to be raw cron).
+ */
+declare function parsePlainEnglish(expression: string): string;
+/**
+ * Validate a cron expression using croner.
+ * Throws if the expression is invalid.
+ */
+declare function validateCron(expression: string): void;
+/**
+ * Compute the next run time for a cron expression with optional timezone.
+ */
+declare function nextRun(expression: string, timezone?: string): Date | null;
+/**
+ * Compute multiple next run times for a cron expression.
+ */
+declare function nextRuns(expression: string, count: number, timezone?: string): Date[];
+/**
+ * Resolve a schedule input into a fully resolved schedule.
+ * Parses plain english, validates the cron expression, and resolves defaults.
+ */
+declare function resolveSchedule(input: ScheduleInput): ResolvedSchedule;
+/**
+ * Metadata for a single schedule extracted from a job router.
+ */
+interface ScheduleMetadata {
+    jobName: string;
+    schedule: ResolvedSchedule;
+}
+/**
+ * Extract all schedule metadata from a job router.
+ * Only includes jobs that have a schedule defined.
+ */
+declare function extractSchedules(router: Record<string, {
+    schedule?: ScheduleInput;
+}>): ScheduleMetadata[];
+
 /**
  * Parse a delay string into milliseconds
  * Supports: '5s', '5m', '5h', '5d' or raw milliseconds
@@ -213,6 +304,9 @@ declare function signPayload(payload: string, secret: string): {
  */
 declare function verifySignature(payload: string, signature: string, secret: string, toleranceSeconds?: number): boolean;
 
+declare class JobFailureError extends Error {
+    constructor(reason: string);
+}
 interface HandlerRequest {
     body: string;
     signatureHeader: string | null;
@@ -225,4 +319,4 @@ declare function processJobCallback(router: Record<string, AnyJobDefinition>, re
     webhookSecret?: string;
 }): Promise<HandlerResponse>;
 
-export { type AnyJobDefinition, type BackoffStrategy, type CallableJob, type CallableJobRouter, type EnqueueOptions, type EnqueueResult, type HandlerRequest, type HandlerResponse, type InferJobInput, type InferJobOutput, type JobClient, type JobContext, type JobDefinition, type JobResult, type JobRouter, type JobStatus, type JobStatusResponse, type QueuebaseConfig, type QueuedJob, WEBHOOK_HEADERS, calculateBackoff, createJobRouter, generateJobId, generatePublicId, job, parseDelay, processJobCallback, signPayload, verifySignature };
+export { type AnyJobDefinition, type BackoffStrategy, type CallableJob, type CallableJobRouter, type EnqueueOptions, type EnqueueResult, type HandlerRequest, type HandlerResponse, type InferJobInput, type InferJobOutput, type JobClient, type JobContext, type JobDefinition, JobFailureError, type JobResult, type JobRouter, type JobStatus, type JobStatusResponse, type OverlapPolicy, type QueuebaseConfig, type QueuedJob, type ResolvedSchedule, type ScheduleConfig, type ScheduleInput, type ScheduleMetadata, WEBHOOK_HEADERS, calculateBackoff, createJobRouter, extractSchedules, generateJobId, generatePublicId, job, nextRun, nextRuns, parseDelay, parsePlainEnglish, processJobCallback, resolveSchedule, signPayload, validateCron, verifySignature };

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,SAAS,EACT,eAAe,EACf,cAAc,EACd,aAAa,EACb,UAAU,EACV,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,aAAa,EACb,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,GAAG,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAGxE,OAAO,EACL,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,iBAAiB,GACvB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG3F,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG7E,OAAO,EACL,kBAAkB,EAClB,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,SAAS,EACT,eAAe,EACf,cAAc,EACd,aAAa,EACb,UAAU,EACV,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,aAAa,EACb,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,GAAG,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAGxE,OAAO,EACL,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,SAAS,GACf,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG3F,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG7E,OAAO,EACL,kBAAkB,EAClB,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC"}