@db3.ai/app 0.1.0-beta.1

package/dist/queue/QueuedJob.d.ts

@@ -0,0 +1,31 @@
+import { ActiveRecord, type FieldBuilder } from '../db/index.js';
+import type * as queue from './contracts/index.js';
+/**
+ * Active queue record persisted by the database queue driver.
+ */
+export declare class QueuedJob extends ActiveRecord {
+    static table: string;
+    static primaryKey: string;
+    /**
+     * Defines the database schema for active queued jobs.
+     *
+     * @param field - Field builder used by ActiveRecord schema installation.
+     * @returns Queue job field definitions.
+     */
+    static fields(field: FieldBuilder): {
+        id: import("../db/index.js").BigIncrementsField;
+        queue: import("../db/index.js").StringField;
+        payload: import("../db/index.js").JsonStringField<queue.JobEnvelope<Record<string, unknown>>>;
+        attempts: import("../db/index.js").IntegerField;
+        reservedAt: import("../db/index.js").IntegerField;
+        availableAt: import("../db/index.js").IntegerField;
+        createdAt: import("../db/index.js").IntegerField;
+    };
+    id: number | null;
+    queue: string | null;
+    payload: queue.JobEnvelope<Record<string, unknown>> | null;
+    attempts: number | null;
+    reservedAt: number | null;
+    availableAt: number | null;
+    createdAt: number | null;
+}

package/dist/queue/QueuedJob.js

@@ -0,0 +1,52 @@
+import { ActiveRecord } from '../db/index.js';
+/**
+ * Active queue record persisted by the database queue driver.
+ */
+export class QueuedJob extends ActiveRecord {
+    static table = 'jobs';
+    static primaryKey = 'id';
+    /**
+     * Defines the database schema for active queued jobs.
+     *
+     * @param field - Field builder used by ActiveRecord schema installation.
+     * @returns Queue job field definitions.
+     */
+    static fields(field) {
+        return {
+            id: field.bigIncrements(),
+            queue: field.string({
+                required: true,
+                length: 255,
+                index: true,
+            }),
+            payload: field.jsonLongText({
+                required: true,
+            }),
+            attempts: field.integer({
+                required: true,
+                unsigned: true,
+                min: 0,
+                default: 0,
+            }),
+            reservedAt: field.integer({
+                column: 'reserved_at',
+                unsigned: true,
+                min: 0,
+                index: true,
+            }),
+            availableAt: field.integer({
+                column: 'available_at',
+                required: true,
+                unsigned: true,
+                min: 0,
+                index: true,
+            }),
+            createdAt: field.integer({
+                column: 'created_at',
+                required: true,
+                unsigned: true,
+                min: 0,
+            }),
+        };
+    }
+}

package/dist/queue/RetryPolicy.d.ts

@@ -0,0 +1,51 @@
+import type * as queue from './contracts/index.js';
+/**
+ * Defaults used to resolve one durable queue retry policy.
+ */
+export interface QueueRetryBackoffDefaults {
+    /** Default delay-growth strategy. */
+    strategy: queue.QueueRetryBackoffStrategy;
+    /** Default first retry delay in seconds. */
+    initialSeconds: number;
+    /** Default maximum retry delay in seconds. */
+    maxSeconds: number;
+    /** Default equal-jitter behavior. */
+    jitter: boolean;
+}
+/**
+ * Resolves validated durable backoff values from dispatch overrides and defaults.
+ *
+ * @param options - Per-dispatch retry backoff overrides.
+ * @param defaults - Queue-level retry backoff defaults.
+ * @returns Complete retry backoff safe to persist with the job.
+ */
+export declare function resolveQueueRetryBackoff(options: queue.QueueRetryBackoffOptions | undefined, defaults: QueueRetryBackoffDefaults): queue.QueueRetryBackoff;
+/**
+ * Calculates the delay for one consumed queue attempt.
+ *
+ * Equal jitter keeps half of the calculated delay and randomizes the remaining
+ * half, preventing large groups of failed jobs from becoming available together.
+ *
+ * @param backoff - Durable retry backoff attached to the queued job.
+ * @param attempt - One-based consumed attempt count.
+ * @param random - Random number source used for jitter.
+ * @returns Retry delay in whole seconds.
+ */
+export declare function queueRetryDelaySeconds(backoff: queue.QueueRetryBackoff, attempt: number, random?: () => number): number;
+/**
+ * Converts a relative retry window into an absolute Unix timestamp.
+ *
+ * @param now - Dispatch timestamp in Unix seconds.
+ * @param retryUntilSeconds - Requested retry window in seconds.
+ * @returns Absolute retry deadline, or undefined when no valid window was supplied.
+ */
+export declare function queueRetryUntil(now: number, retryUntilSeconds: number | undefined): number | undefined;
+/**
+ * Checks whether scheduling another ordinary retry would exceed its deadline.
+ *
+ * @param retryUntil - Absolute Unix retry deadline stored on the queued job.
+ * @param delaySeconds - Calculated delay before the next attempt.
+ * @param now - Current Unix timestamp.
+ * @returns True when the next retry must become terminal instead.
+ */
+export declare function queueRetryDeadlineReached(retryUntil: number | undefined, delaySeconds: number, now: number): boolean;

package/dist/queue/RetryPolicy.js

@@ -0,0 +1,84 @@
+/**
+ * Resolves validated durable backoff values from dispatch overrides and defaults.
+ *
+ * @param options - Per-dispatch retry backoff overrides.
+ * @param defaults - Queue-level retry backoff defaults.
+ * @returns Complete retry backoff safe to persist with the job.
+ */
+export function resolveQueueRetryBackoff(options, defaults) {
+    const initialSeconds = finiteNonNegative(options?.initialSeconds, defaults.initialSeconds);
+    const maxSeconds = Math.max(initialSeconds, finiteNonNegative(options?.maxSeconds, defaults.maxSeconds));
+    return {
+        strategy: options?.strategy === 'linear' || options?.strategy === 'exponential'
+            ? options.strategy
+            : defaults.strategy,
+        initialSeconds,
+        maxSeconds,
+        jitter: options?.jitter ?? defaults.jitter,
+    };
+}
+/**
+ * Calculates the delay for one consumed queue attempt.
+ *
+ * Equal jitter keeps half of the calculated delay and randomizes the remaining
+ * half, preventing large groups of failed jobs from becoming available together.
+ *
+ * @param backoff - Durable retry backoff attached to the queued job.
+ * @param attempt - One-based consumed attempt count.
+ * @param random - Random number source used for jitter.
+ * @returns Retry delay in whole seconds.
+ */
+export function queueRetryDelaySeconds(backoff, attempt, random = Math.random) {
+    const normalizedAttempt = Math.max(1, Math.trunc(attempt));
+    const multiplier = backoff.strategy === 'exponential'
+        ? 2 ** Math.max(0, normalizedAttempt - 1)
+        : normalizedAttempt;
+    const calculated = Math.min(backoff.maxSeconds, backoff.initialSeconds * multiplier);
+    if (!backoff.jitter || calculated <= 0) {
+        return Math.ceil(calculated);
+    }
+    const minimum = calculated / 2;
+    const boundedRandom = Math.min(1, Math.max(0, random()));
+    return Math.max(1, Math.ceil(minimum + ((calculated - minimum) * boundedRandom)));
+}
+/**
+ * Converts a relative retry window into an absolute Unix timestamp.
+ *
+ * @param now - Dispatch timestamp in Unix seconds.
+ * @param retryUntilSeconds - Requested retry window in seconds.
+ * @returns Absolute retry deadline, or undefined when no valid window was supplied.
+ */
+export function queueRetryUntil(now, retryUntilSeconds) {
+    if (typeof retryUntilSeconds !== 'number'
+        || !Number.isFinite(retryUntilSeconds)
+        || retryUntilSeconds <= 0) {
+        return undefined;
+    }
+    return now + Math.ceil(retryUntilSeconds);
+}
+/**
+ * Checks whether scheduling another ordinary retry would exceed its deadline.
+ *
+ * @param retryUntil - Absolute Unix retry deadline stored on the queued job.
+ * @param delaySeconds - Calculated delay before the next attempt.
+ * @param now - Current Unix timestamp.
+ * @returns True when the next retry must become terminal instead.
+ */
+export function queueRetryDeadlineReached(retryUntil, delaySeconds, now) {
+    return typeof retryUntil === 'number'
+        && Number.isFinite(retryUntil)
+        && now + delaySeconds > retryUntil;
+}
+/**
+ * Normalizes an optional numeric value to a finite non-negative number.
+ *
+ * @param value - Requested numeric value.
+ * @param fallback - Value used when the request is invalid.
+ * @returns Finite non-negative number.
+ */
+function finiteNonNegative(value, fallback) {
+    const selected = typeof value === 'number' && Number.isFinite(value)
+        ? value
+        : fallback;
+    return Math.max(0, selected);
+}

package/dist/queue/commands/index.d.ts

@@ -0,0 +1,4 @@
+import makeJob from './makeJob.js';
+export { makeJob };
+/** Queue's explicit command index; source generation does not require a running app. */
+export declare const queueCommands: import("../../cli/index.js").CliCommand[];

package/dist/queue/commands/index.js

@@ -0,0 +1,11 @@
+import { defineCommand } from '../../cli/index.js';
+import makeJob from './makeJob.js';
+export { makeJob };
+/** Queue's explicit command index; source generation does not require a running app. */
+export const queueCommands = [defineCommand({
+        name: 'queue:make-job', description: 'Create an application job under server/jobs.',
+        parameters: [{ name: 'name', required: true }], needsApp: false,
+        /** Maps the command's named parameter and app root to the source-generation action. */
+        handle: (parameters, context) => makeJob({ appDirectory: context.directory, name: parameters.name }),
+        formatResult: result => `Created ${result.path}\nImplement handle(), then register the class in your application bootstrap.`,
+    })];

package/dist/queue/commands/makeJob.d.ts

@@ -0,0 +1,7 @@
+import type { CreateJobOptions, CreatedJob } from '../contracts/CreateJob.js';
+/**
+ * Creates an app-owned job through the shared source-generation operation.
+ * @param options - Application directory and validated job class name.
+ * @returns Created file and source, usable by terminal and editor callers alike.
+ */
+export default function makeJob(options: CreateJobOptions): Promise<CreatedJob>;

package/dist/queue/commands/makeJob.js

@@ -0,0 +1,9 @@
+import { createJob } from '../createJob.js';
+/**
+ * Creates an app-owned job through the shared source-generation operation.
+ * @param options - Application directory and validated job class name.
+ * @returns Created file and source, usable by terminal and editor callers alike.
+ */
+export default async function makeJob(options) {
+    return createJob(options);
+}

package/dist/queue/console.d.ts

@@ -0,0 +1,60 @@
+import type { Logger } from '../logging/index.js';
+import type * as queue from './contracts/index.js';
+import type { Queue } from './Queue.js';
+interface QueueConsoleLogOptions {
+    verbose?: boolean;
+}
+export interface ParsedQueueConsoleArgs {
+    command: string;
+    args: string[];
+    options: Record<string, string | boolean>;
+}
+export interface QueueConsoleApp {
+    queue: Queue;
+    /** Application logger used by long-running queue workers when available. */
+    log?: Logger;
+    close(): void | Promise<void>;
+}
+export interface QueueConsoleCommandContext {
+    parsed: ParsedQueueConsoleArgs;
+    app: QueueConsoleApp;
+    dispatchOptions(): queue.DispatchOptions;
+    optionString(name: string): string | undefined;
+    optionBoolean(name: string): boolean;
+    optionNumber(name: string, fallback?: string): number | undefined;
+}
+export interface QueueConsoleCommand {
+    command: string;
+    bootstrap?: boolean;
+    close?: boolean;
+    run(context: QueueConsoleCommandContext): void | Promise<void>;
+}
+export interface QueueConsoleOptions {
+    app: () => QueueConsoleApp;
+    bootstrap?: () => void | Promise<void>;
+    commands?: QueueConsoleCommand[];
+    helpText?: string;
+    unknownCommandMessage?: (command: string) => string;
+}
+export declare function runQueueConsole(options: QueueConsoleOptions, argv?: string[]): Promise<void>;
+export declare function parseQueueConsoleArgs(argv: string[]): ParsedQueueConsoleArgs;
+export declare function queueConsoleOptionString(parsed: ParsedQueueConsoleArgs, name: string): string | undefined;
+export declare function queueConsoleOptionBoolean(parsed: ParsedQueueConsoleArgs, name: string): boolean;
+export declare function queueConsoleOptionNumber(parsed: ParsedQueueConsoleArgs, name: string, fallback?: string): number | undefined;
+export declare function queueConsoleDispatchOptions(parsed: ParsedQueueConsoleArgs): queue.DispatchOptions;
+/**
+ * Resolves the process title for a long-running queue worker.
+ *
+ * @param parsed - Parsed console arguments.
+ * @returns Process title to show in system process lists.
+ */
+export declare function queueConsoleWorkerProcessTitle(parsed: ParsedQueueConsoleArgs): string;
+export declare function logQueueProcessResult(result: queue.QueueProcessResult, options?: QueueConsoleLogOptions): void;
+/**
+ * Logs that a queue job has been claimed in one-off worker mode.
+ *
+ * @param job - Claimed queue job.
+ * @param options - Console logging options.
+ */
+export declare function logQueueClaimed(job: queue.QueueJob, options?: QueueConsoleLogOptions): void;
+export {};

package/dist/queue/console.js

@@ -0,0 +1,348 @@
+import { parseJsonRecord, unknownErrorMessage } from '@db3.ai/pure';
+export async function runQueueConsole(options, argv = process.argv.slice(2)) {
+    const parsed = parseQueueConsoleArgs(argv);
+    switch (parsed.command) {
+        case 'queue:work':
+            await bootstrap(options);
+            await workQueue(options, parsed);
+            return;
+        case 'queue:dispatch':
+            await bootstrap(options);
+            {
+                const app = options.app();
+                try {
+                    await dispatchQueueJob(app, parsed);
+                }
+                finally {
+                    await app.close();
+                }
+            }
+            return;
+        case 'queue:retry':
+            await bootstrap(options);
+            {
+                const app = options.app();
+                try {
+                    await retryFailedQueueJob(app, parsed);
+                }
+                finally {
+                    await app.close();
+                }
+            }
+            return;
+        case 'queue:help':
+        case 'help':
+        case '':
+            printHelp(options);
+            return;
+    }
+    const command = options.commands?.find(candidate => {
+        return candidate.command === parsed.command;
+    });
+    if (command) {
+        if (command.bootstrap !== false) {
+            await bootstrap(options);
+        }
+        const context = createCommandContext(options, parsed);
+        try {
+            await command.run(context);
+        }
+        finally {
+            if (command.close !== false) {
+                await context.app.close();
+            }
+        }
+        return;
+    }
+    throw new Error(options.unknownCommandMessage?.(parsed.command)
+        ?? `Unknown queue command "${parsed.command}".`);
+}
+export function parseQueueConsoleArgs(argv) {
+    const [command = '', ...rest] = argv;
+    const args = [];
+    const options = {};
+    for (let index = 0; index < rest.length; index += 1) {
+        const value = rest[index];
+        if (!value.startsWith('--')) {
+            args.push(value);
+            continue;
+        }
+        const [rawKey, inlineValue] = value.slice(2).split('=', 2);
+        const key = rawKey.trim();
+        if (!key)
+            continue;
+        if (inlineValue !== undefined) {
+            options[key] = inlineValue;
+            continue;
+        }
+        const next = rest[index + 1];
+        if (next && !next.startsWith('--')) {
+            options[key] = next;
+            index += 1;
+            continue;
+        }
+        options[key] = true;
+    }
+    return {
+        command,
+        args,
+        options,
+    };
+}
+export function queueConsoleOptionString(parsed, name) {
+    const value = parsed.options[name];
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+export function queueConsoleOptionBoolean(parsed, name) {
+    const value = parsed.options[name];
+    return value === true || value === 'true' || value === '1';
+}
+export function queueConsoleOptionNumber(parsed, name, fallback) {
+    const rawValue = parsed.options[name] ?? fallback;
+    if (rawValue === undefined || rawValue === true)
+        return undefined;
+    if (typeof rawValue === 'string' && rawValue.trim() === '')
+        return undefined;
+    const value = Number(rawValue);
+    if (!Number.isFinite(value))
+        return undefined;
+    return value;
+}
+export function queueConsoleDispatchOptions(parsed) {
+    return {
+        queue: queueConsoleOptionString(parsed, 'queue'),
+        delaySeconds: queueConsoleOptionNumber(parsed, 'delay'),
+        maxTries: queueConsoleOptionNumber(parsed, 'tries'),
+    };
+}
+/**
+ * Resolves the process title for a long-running queue worker.
+ *
+ * @param parsed - Parsed console arguments.
+ * @returns Process title to show in system process lists.
+ */
+export function queueConsoleWorkerProcessTitle(parsed) {
+    return queueConsoleOptionString(parsed, 'name')
+        || queueConsoleEnvString('QUEUE_WORKER_NAME')
+        || 'queue-worker';
+}
+export function logQueueProcessResult(result, options = {}) {
+    const job = result.job;
+    const label = `${job.payload.job}#${job.id}`;
+    if (result.status === 'succeeded') {
+        console.log(`[queue] Processed ${label} on "${job.queue}".${queueConsoleVerboseNextJobMessage(job, options)}`);
+        return;
+    }
+    if (result.status === 'released') {
+        console.warn(`[queue] Released ${label} after attempt ${job.attempts}/${job.payload.maxTries}; retrying in ${result.delaySeconds ?? 0}s. ${unknownErrorMessage(result.error)}`);
+        return;
+    }
+    if (result.status === 'deferred') {
+        console.warn(`[queue] Deferred ${label}; retrying in ${result.delaySeconds ?? 0}s. ${unknownErrorMessage(result.error)}`);
+        return;
+    }
+    if (result.status === 'lease_lost') {
+        console.warn(`[queue] Stopped fenced ${label} attempt ${job.attempts}; lease ownership could not be confirmed. ${unknownErrorMessage(result.error)}`);
+        return;
+    }
+    console.error(`[queue] Failed ${label} after ${job.attempts}/${job.payload.maxTries} attempts. ${unknownErrorMessage(result.error)}`);
+}
+/**
+ * Logs that a queue job has been claimed in one-off worker mode.
+ *
+ * @param job - Claimed queue job.
+ * @param options - Console logging options.
+ */
+export function logQueueClaimed(job, options = {}) {
+    const label = `${job.payload.job}#${job.id}`;
+    console.log(`[queue] Claimed ${label} on "${job.queue}" attempt ${job.attempts}/${job.payload.maxTries}.`);
+    if (!options.verbose)
+        return;
+    console.log(`[queue] Running ${label}; payload keys: ${queueConsolePayloadKeys(job)}; next on success: ${queueConsoleNextJobLabel(job) ?? 'none'}.`);
+}
+async function bootstrap(options) {
+    await options.bootstrap?.();
+}
+async function workQueue(options, parsed) {
+    const queue = queueConsoleOptionString(parsed, 'queue')
+        || parsed.args[0]
+        || process.env.QUEUE_NAME
+        || 'default';
+    const once = queueConsoleOptionBoolean(parsed, 'once');
+    const verbose = queueConsoleVerbose(parsed);
+    if (!once) {
+        process.title = queueConsoleWorkerProcessTitle(parsed);
+    }
+    const app = options.app();
+    if (once) {
+        if (verbose) {
+            console.log(`[queue] Checking "${queue}" once.`);
+        }
+        const result = await app.queue.workNextJob(queue, {
+            onClaimed: job => logQueueClaimed(job, {
+                verbose,
+            }),
+        });
+        if (!result) {
+            console.log(`[queue] No jobs available on "${queue}".`);
+            await app.close();
+            return;
+        }
+        logQueueProcessResult(result, {
+            verbose,
+        });
+        await app.close();
+        return;
+    }
+    const worker = app.queue.startWorker(queue, {
+        force: true,
+        logger: app.log?.child({
+            component: 'queue-worker',
+        }) ?? console,
+        verbose,
+        intervalMs: queueConsoleOptionNumber(parsed, 'interval', process.env.QUEUE_WORKER_INTERVAL_MS),
+        maxJobsPerTick: queueConsoleOptionNumber(parsed, 'max-jobs', process.env.QUEUE_WORKER_MAX_JOBS_PER_TICK),
+    });
+    if (!worker) {
+        throw new Error('Queue worker could not start.');
+    }
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.log(`[queue] Received ${signal}; stopping worker.`);
+        await worker.stopAndDrain();
+        await app.close();
+        process.exit(0);
+    };
+    process.on('SIGINT', () => {
+        void shutdown('SIGINT');
+    });
+    process.on('SIGTERM', () => {
+        void shutdown('SIGTERM');
+    });
+}
+async function dispatchQueueJob(app, parsed) {
+    const name = parsed.args[0];
+    if (!name) {
+        throw new Error('Provide a job name, for example: queue:dispatch TestLogJob \'{"message":"Hello"}\'');
+    }
+    const data = parseJsonRecord(parsed.args[1] ?? '{}', 'Job data must be a JSON object.');
+    const id = await app.queue.dispatch(name, data, queueConsoleDispatchOptions(parsed));
+    console.log(`[queue] Dispatched ${name} as job ${id}.`);
+}
+/**
+ * Replays one persisted terminal queue failure.
+ *
+ * @param app - Bootstrapped application exposing the queue service.
+ * @param parsed - Parsed command arguments and dispatch overrides.
+ */
+async function retryFailedQueueJob(app, parsed) {
+    const failedJobId = parsed.args[0];
+    if (!failedJobId) {
+        throw new Error('Provide a failed job id, for example: queue:retry 206');
+    }
+    const replacementId = await app.queue.retryFailed(failedJobId, queueConsoleDispatchOptions(parsed));
+    console.log(`[queue] Retried failed job ${failedJobId} as job ${replacementId}.`);
+}
+function createCommandContext(options, parsed) {
+    return {
+        parsed,
+        app: options.app(),
+        dispatchOptions: () => queueConsoleDispatchOptions(parsed),
+        optionString: name => queueConsoleOptionString(parsed, name),
+        optionBoolean: name => queueConsoleOptionBoolean(parsed, name),
+        optionNumber: (name, fallback) => queueConsoleOptionNumber(parsed, name, fallback),
+    };
+}
+function printHelp(options) {
+    console.log(options.helpText ?? defaultHelpText());
+}
+/**
+ * Builds the default queue console help text shown by framework consumers.
+ */
+function defaultHelpText() {
+    return `Queue commands
+
+  queue:work [--queue=default]
+  queue:work --once
+  queue:dispatch <job> '{"key":"value"}'
+  queue:retry <failed-job-id>
+  queue:help
+
+Options:
+  --queue=<name>       Queue name, defaults to "default".
+  --delay=<seconds>    Delay before the job is available.
+  --tries=<count>      Maximum attempts before jobs_failed.
+  --once               Process one available job, then exit.
+  --interval=<ms>      Worker polling interval.
+  --max-jobs=<count>   Jobs processed per worker tick.
+  --name=<name>        Process title for long-running workers.
+  --verbose            Show idle polls, payload keys, and chained next jobs.
+`;
+}
+/**
+ * Resolves whether verbose queue worker logging should be enabled.
+ *
+ * @param parsed - Parsed console arguments.
+ * @returns True when verbose logging is enabled by flag or environment.
+ */
+function queueConsoleVerbose(parsed) {
+    return queueConsoleOptionBoolean(parsed, 'verbose')
+        || queueConsoleEnvBoolean('QUEUE_WORKER_VERBOSE')
+        || queueConsoleEnvBoolean('QUEUE_VERBOSE');
+}
+/**
+ * Reads a boolean-like value from the process environment.
+ *
+ * @param name - Environment variable name.
+ * @returns True when the environment value enables a setting.
+ */
+function queueConsoleEnvBoolean(name) {
+    const value = process.env[name];
+    return value === 'true' || value === '1' || value === 'yes';
+}
+/**
+ * Reads a trimmed string value from the process environment.
+ *
+ * @param name - Environment variable name.
+ * @returns Trimmed environment value when present.
+ */
+function queueConsoleEnvString(name) {
+    const value = process.env[name];
+    return value?.trim() || undefined;
+}
+/**
+ * Returns a verbose suffix describing the next chained job.
+ *
+ * @param job - Completed queue job.
+ * @param options - Console logging options.
+ * @returns Empty string or a sentence fragment for the next queued job.
+ */
+function queueConsoleVerboseNextJobMessage(job, options) {
+    if (!options.verbose)
+        return '';
+    const next = queueConsoleNextJobLabel(job);
+    return next ? ` Queued next ${next}.` : ' No chained job remains.';
+}
+/**
+ * Returns a readable list of payload keys for terminal output.
+ *
+ * @param job - Queue job whose payload data should be described.
+ * @returns Comma-separated payload keys or none.
+ */
+function queueConsolePayloadKeys(job) {
+    const keys = Object.keys(job.payload.data ?? {});
+    return keys.length > 0 ? keys.join(', ') : 'none';
+}
+/**
+ * Returns the next chained job name from a queue payload.
+ *
+ * @param job - Queue job whose chain should be inspected.
+ * @returns Next chained job label or null.
+ */
+function queueConsoleNextJobLabel(job) {
+    const [next] = job.payload.chained ?? [];
+    return next ? next.displayName || next.job : null;
+}

package/dist/queue/contracts/CreateJob.d.ts

@@ -0,0 +1,12 @@
+/** Application location and class name for a convention-based job scaffold. */
+export interface CreateJobOptions {
+    /** Absolute or working-directory-relative application root. */
+    appDirectory: string;
+    /** PascalCase TypeScript class name ending in Job. */
+    name: string;
+}
+/** Created application file and its source, suitable for opening in an editor. */
+export interface CreatedJob {
+    path: string;
+    source: string;
+}

package/dist/queue/contracts/CreateJob.js

@@ -0,0 +1 @@
+export {};