@db3.ai/app 0.1.0-beta.1

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

@@ -0,0 +1,50 @@
+import type { Queue } from '../Queue.js';
+import type { QueueableJob } from '../QueueableJob.js';
+import type { QueueJob, SerializedQueuedJob } from './QueuePayload.js';
+/**
+ * Serialized queueable job payload stored before a driver wraps it in an envelope.
+ */
+export type SerializedQueueableJob<TData extends Record<string, unknown> = Record<string, unknown>> = SerializedQueuedJob<TData>;
+/**
+ * Queue runtime metadata passed to a rehydrated job.
+ */
+export interface QueueableJobContext {
+    /** Claimed queue job being handled. */
+    job: QueueJob;
+    /** Queue service that is processing this job. */
+    queue: Queue;
+}
+/**
+ * Context passed after a failed attempt has safely been released for retry.
+ */
+export interface QueueableJobRetryContext extends QueueableJobContext {
+    /** Error raised by the failed handler attempt. */
+    error: unknown;
+    /** Seconds before the released job becomes available again. */
+    delaySeconds: number;
+}
+/**
+ * Context passed after a job exhausts its attempts and is durably failed.
+ */
+export interface QueueableJobFailureContext extends QueueableJobContext {
+    /** Terminal error persisted by the queue driver. */
+    error: unknown;
+}
+/**
+ * Constructor contract for serializable queueable job classes.
+ */
+export interface QueueableJobClass<TJob extends QueueableJob = QueueableJob> {
+    /** Runtime class name used as the default durable job name. */
+    readonly name: string;
+    /** Optional durable job name override. */
+    readonly jobName?: string;
+    /** Creates a job from its application-facing runtime data. */
+    new (data: any): TJob;
+    /**
+     * Rehydrates a queueable job instance from persisted payload data.
+     *
+     * @param data - JSON-safe data stored in the queue payload.
+     * @returns Queueable job instance ready to handle.
+     */
+    fromJSON(data: Record<string, unknown>): TJob;
+}

package/dist/queue/contracts/QueueableJob.js

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

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

@@ -0,0 +1,37 @@
+/**
+ * Connection and key options for the Redis queue driver.
+ */
+export interface RedisQueueDriverOptions {
+    /**
+     * Redis connection URL. When omitted, the driver reads QUEUE_REDIS_URL or REDIS_URL.
+     */
+    url?: string;
+    /**
+     * Redis host used when no URL is supplied.
+     */
+    host?: string;
+    /**
+     * Redis port used when no URL is supplied.
+     */
+    port?: number;
+    /**
+     * Redis username for ACL authentication.
+     */
+    username?: string;
+    /**
+     * Redis password for authentication.
+     */
+    password?: string;
+    /**
+     * Redis database index selected after connecting.
+     */
+    database?: number;
+    /**
+     * Prefix applied to every key owned by this queue driver.
+     */
+    keyPrefix?: string;
+    /**
+     * Milliseconds to wait before failing the Redis connection attempt.
+     */
+    connectionTimeoutMs?: number;
+}

package/dist/queue/contracts/RedisQueueDriver.js

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

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

@@ -0,0 +1,9 @@
+export * from './QueueDriver.js';
+export * from './QueueEvents.js';
+export * from './QueuePayload.js';
+export * from './QueueRetry.js';
+export * from './QueueableJob.js';
+export * from './QueueService.js';
+export * from './QueueWorkerLifecycle.js';
+export * from './RedisQueueDriver.js';
+export * from './CreateJob.js';

package/dist/queue/contracts/index.js

@@ -0,0 +1,9 @@
+export * from './QueueDriver.js';
+export * from './QueueEvents.js';
+export * from './QueuePayload.js';
+export * from './QueueRetry.js';
+export * from './QueueableJob.js';
+export * from './QueueService.js';
+export * from './QueueWorkerLifecycle.js';
+export * from './RedisQueueDriver.js';
+export * from './CreateJob.js';

package/dist/queue/createJob.d.ts

@@ -0,0 +1,18 @@
+import type { CreateJobOptions, CreatedJob } from './contracts/CreateJob.js';
+/**
+ * Generates the source for an application-owned job using framework conventions.
+ *
+ * CLI and editor integrations can preview the same template before writing it.
+ * @param name - PascalCase class name ending in Job.
+ * @returns TypeScript source with payload validation and an explicit unfinished handler.
+ */
+export declare function jobTemplate(name: string): string;
+/**
+ * Creates a job in server/jobs without replacing an existing application file.
+ *
+ * @param options - Application root and validated class name.
+ * @returns Created path and source for a CLI, Studio or editor integration.
+ * @example
+ * await createJob({ appDirectory: process.cwd(), name: 'GenerateReportJob' });
+ */
+export declare function createJob(options: CreateJobOptions): Promise<CreatedJob>;

package/dist/queue/createJob.js

@@ -0,0 +1,52 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+/**
+ * Generates the source for an application-owned job using framework conventions.
+ *
+ * CLI and editor integrations can preview the same template before writing it.
+ * @param name - PascalCase class name ending in Job.
+ * @returns TypeScript source with payload validation and an explicit unfinished handler.
+ */
+export function jobTemplate(name) {
+    if (!/^[A-Z][A-Za-z0-9]*Job$/.test(name))
+        throw new Error('Use a PascalCase class name ending in Job, such as GenerateReportJob.');
+    return `import { QueueableJob } from '@db3.ai/app/queue';
+
+/** Data persisted with each ${name} dispatch. */
+export interface ${name}Data extends Record<string, unknown> {
+	message: string;
+}
+
+/** Application job restored by queue workers from its persisted data. */
+export class ${name} extends QueueableJob<${name}Data> {
+	static jobName = '${name}';
+
+	/** Validates payloads supplied by both callers and persisted queue records. */
+	constructor(data: ${name}Data) {
+		if (!data || typeof data.message !== 'string' || !data.message.trim()) throw new Error('${name} requires a message.');
+		super(data);
+	}
+
+	/** Performs this job's work; keep external side effects safe to retry. */
+	async handle(): Promise<void> {
+		throw new Error('Implement ${name}.handle() before dispatching this job.');
+	}
+}
+`;
+}
+/**
+ * Creates a job in server/jobs without replacing an existing application file.
+ *
+ * @param options - Application root and validated class name.
+ * @returns Created path and source for a CLI, Studio or editor integration.
+ * @example
+ * await createJob({ appDirectory: process.cwd(), name: 'GenerateReportJob' });
+ */
+export async function createJob(options) {
+    const source = jobTemplate(options.name);
+    const directory = resolve(options.appDirectory, 'server/jobs');
+    const path = join(directory, `${options.name}.ts`);
+    await mkdir(directory, { recursive: true });
+    await writeFile(path, source, { encoding: 'utf8', flag: 'wx' });
+    return { path, source };
+}

package/dist/queue/drivers/DatabaseQueueDriver.d.ts

@@ -0,0 +1,83 @@
+import { type Database } from '../../db/index.js';
+import type * as queue from '../contracts/index.js';
+/**
+ * Queue driver that stores pending and failed jobs in the app database.
+ */
+export declare class DatabaseQueueDriver implements queue.QueueDriver {
+    private readonly db;
+    readonly name = "database";
+    /**
+     * Creates a database-backed queue driver.
+     *
+     * @param db - Database service used for queue persistence.
+     */
+    constructor(db: Database);
+    /**
+     * Persists a job in the `jobs` table.
+     *
+     * @param job - Queue job payload and scheduling data.
+     * @returns Database id of the queued job record.
+     */
+    push<TData extends Record<string, unknown>>(job: queue.QueueDriverPushInput<TData>): Promise<queue.QueueJobId>;
+    /**
+     * Claims the next available job from a named queue.
+     *
+     * @param queue - Named queue/channel to claim from.
+     * @param options - Claim controls such as retry expiry.
+     * @returns Claimed queue job, or null when no job is ready.
+     */
+    pop(queue: string, options: queue.QueueDriverPopOptions): Promise<queue.QueueJob | null>;
+    /**
+     * Renews the reservation for the current database queue attempt.
+     *
+     * @param job - Claimed job whose id and attempt count identify the lease owner.
+     * @param _retryAfterSeconds - Lease duration used by queue polling expiry checks.
+     * @returns True when the current attempt still owns the job.
+     */
+    touch(job: queue.QueueJob, _retryAfterSeconds: number): Promise<boolean>;
+    /**
+     * Moves a terminally failed job to `jobs_failed` and removes it from `jobs`.
+     *
+     * @param job - Claimed queue job that exhausted retries.
+     * @param error - Error thrown by the job handler.
+     * @returns True when the current attempt owned and failed the job.
+     */
+    fail(job: queue.QueueJob, error: unknown): Promise<boolean>;
+    /**
+     * Releases a failed attempt for another try after a delay.
+     *
+     * @param job - Claimed queue job to release.
+     * @param delaySeconds - Number of seconds before the job can be claimed again.
+     * @returns True when the current attempt owned and released the job.
+     */
+    release(job: queue.QueueJob, delaySeconds: number): Promise<boolean>;
+    /**
+     * Defers a claimed job without consuming one of its retry attempts.
+     *
+     * @param job - Claimed queue job.
+     * @param delaySeconds - Number of seconds before the job can be claimed again.
+     * @returns True when the current attempt owned and deferred the job.
+     */
+    defer(job: queue.QueueJob, delaySeconds: number): Promise<boolean>;
+    /**
+     * Deletes a completed job from the active queue table.
+     *
+     * @param job - Claimed queue job to delete.
+     * @returns True when the current attempt owned and deleted the job.
+     */
+    delete(job: queue.QueueJob): Promise<boolean>;
+    /**
+     * Returns recent terminal failures for queue monitoring and diagnostics.
+     *
+     * @param limit - Maximum number of recent failed jobs to return.
+     * @returns Recent failed jobs ordered from newest to oldest.
+     */
+    failedJobs(limit?: number): Promise<queue.QueueFailedJob[]>;
+    /**
+     * Returns one terminal failure by its database identifier.
+     *
+     * @param id - Failed-job table identifier.
+     * @returns Persisted failed job, or null when it does not exist.
+     */
+    failedJob(id: queue.QueueJobId): Promise<queue.QueueFailedJob | null>;
+}

package/dist/queue/drivers/DatabaseQueueDriver.js

@@ -0,0 +1,393 @@
+import { ActiveRecord, RecordValidationError, withQueryMonitorCategory } from '../../db/index.js';
+import { FailedJob } from '../FailedJob.js';
+import { QueuedJob } from '../QueuedJob.js';
+/**
+ * Queue driver that stores pending and failed jobs in the app database.
+ */
+export class DatabaseQueueDriver {
+    db;
+    name = 'database';
+    /**
+     * Creates a database-backed queue driver.
+     *
+     * @param db - Database service used for queue persistence.
+     */
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Persists a job in the `jobs` table.
+     *
+     * @param job - Queue job payload and scheduling data.
+     * @returns Database id of the queued job record.
+     */
+    async push(job) {
+        return withQueueQueryCategory(() => ActiveRecord.withDb(this.db.knex, async () => {
+            const record = QueuedJob.create({
+                queue: job.queue,
+                payload: job.payload,
+                attempts: 0,
+                reservedAt: null,
+                availableAt: job.createdAt + job.delaySeconds,
+                createdAt: job.createdAt,
+            });
+            const valid = await record.validate();
+            if (!valid) {
+                throw new RecordValidationError(record.getErrors());
+            }
+            const row = await record.getDataForDb({
+                isInsert: true,
+                onlyDirty: false,
+            });
+            const [jobId] = await this.db.knex(QueuedJob.table).insert(row);
+            return Number(jobId);
+        }));
+    }
+    /**
+     * Claims the next available job from a named queue.
+     *
+     * @param queue - Named queue/channel to claim from.
+     * @param options - Claim controls such as retry expiry.
+     * @returns Claimed queue job, or null when no job is ready.
+     */
+    async pop(queue, options) {
+        const now = unixTimestamp();
+        const expiredAt = now - options.retryAfterSeconds;
+        return withQueueQueryCategory(() => this.db.transaction(async () => {
+            const row = await QueuedJob
+                .where('queue', queue)
+                .where('availableAt', '<=', now)
+                .orderBy('id')
+                .toKnex()
+                .where(builder => {
+                builder
+                    .whereNull('reserved_at')
+                    .orWhere('reserved_at', '<=', expiredAt);
+            })
+                .forUpdate()
+                .skipLocked()
+                .first();
+            if (!row)
+                return null;
+            const record = QueuedJob.fromDb(row);
+            const attempts = Number(record.attempts ?? 0) + 1;
+            await QueuedJob
+                .where('id', record.id)
+                .patch({
+                attempts,
+                reservedAt: now,
+            });
+            return {
+                id: Number(record.id),
+                queue: String(record.queue),
+                attempts,
+                payload: parsePayload(record.payload),
+            };
+        }));
+    }
+    /**
+     * Renews the reservation for the current database queue attempt.
+     *
+     * @param job - Claimed job whose id and attempt count identify the lease owner.
+     * @param _retryAfterSeconds - Lease duration used by queue polling expiry checks.
+     * @returns True when the current attempt still owns the job.
+     */
+    async touch(job, _retryAfterSeconds) {
+        return withQueueQueryCategory(() => ActiveRecord.withDb(this.db.knex, async () => {
+            const updated = await QueuedJob
+                .where('id', job.id)
+                .where('attempts', job.attempts)
+                .patch({
+                reservedAt: unixTimestamp(),
+            });
+            return updated === 1;
+        }));
+    }
+    /**
+     * Moves a terminally failed job to `jobs_failed` and removes it from `jobs`.
+     *
+     * @param job - Claimed queue job that exhausted retries.
+     * @param error - Error thrown by the job handler.
+     * @returns True when the current attempt owned and failed the job.
+     */
+    async fail(job, error) {
+        return await withQueueQueryCategory(() => this.db.transaction(async () => {
+            const deleted = await QueuedJob
+                .where('id', job.id)
+                .where('attempts', job.attempts)
+                .delete();
+            if (deleted !== 1)
+                return false;
+            const failedJob = FailedJob.create({
+                uuid: job.payload.uuid,
+                connection: this.name,
+                queue: job.queue,
+                payload: job.payload,
+                exception: errorStack(error),
+                failedAt: new Date(),
+            });
+            await failedJob.save();
+            return true;
+        }));
+    }
+    /**
+     * Releases a failed attempt for another try after a delay.
+     *
+     * @param job - Claimed queue job to release.
+     * @param delaySeconds - Number of seconds before the job can be claimed again.
+     * @returns True when the current attempt owned and released the job.
+     */
+    async release(job, delaySeconds) {
+        return await withQueueQueryCategory(() => ActiveRecord.withDb(this.db.knex, async () => {
+            const updated = await QueuedJob
+                .where('id', job.id)
+                .where('attempts', job.attempts)
+                .patch({
+                reservedAt: null,
+                availableAt: unixTimestamp() + delaySeconds,
+            });
+            return updated === 1;
+        }));
+    }
+    /**
+     * Defers a claimed job without consuming one of its retry attempts.
+     *
+     * @param job - Claimed queue job.
+     * @param delaySeconds - Number of seconds before the job can be claimed again.
+     * @returns True when the current attempt owned and deferred the job.
+     */
+    async defer(job, delaySeconds) {
+        return await withQueueQueryCategory(() => ActiveRecord.withDb(this.db.knex, async () => {
+            const updated = await QueuedJob
+                .where('id', job.id)
+                .where('attempts', job.attempts)
+                .patch({
+                attempts: Math.max(0, job.attempts - 1),
+                reservedAt: null,
+                availableAt: unixTimestamp() + delaySeconds,
+            });
+            return updated === 1;
+        }));
+    }
+    /**
+     * Deletes a completed job from the active queue table.
+     *
+     * @param job - Claimed queue job to delete.
+     * @returns True when the current attempt owned and deleted the job.
+     */
+    async delete(job) {
+        return await withQueueQueryCategory(() => ActiveRecord.withDb(this.db.knex, async () => {
+            const deleted = await QueuedJob
+                .where('id', job.id)
+                .where('attempts', job.attempts)
+                .delete();
+            return deleted === 1;
+        }));
+    }
+    /**
+     * Returns recent terminal failures for queue monitoring and diagnostics.
+     *
+     * @param limit - Maximum number of recent failed jobs to return.
+     * @returns Recent failed jobs ordered from newest to oldest.
+     */
+    async failedJobs(limit = 100) {
+        return withQueueQueryCategory(() => ActiveRecord.withDb(this.db.knex, async () => {
+            const records = await FailedJob
+                .query()
+                .orderBy('failedAt', 'desc')
+                .limit(normalizeFailureLimit(limit))
+                .all();
+            return records.map(queueFailedJobFromRecord);
+        }));
+    }
+    /**
+     * Returns one terminal failure by its database identifier.
+     *
+     * @param id - Failed-job table identifier.
+     * @returns Persisted failed job, or null when it does not exist.
+     */
+    async failedJob(id) {
+        return withQueueQueryCategory(() => ActiveRecord.withDb(this.db.knex, async () => {
+            const record = await FailedJob.find(id);
+            return record ? queueFailedJobFromRecord(record) : null;
+        }));
+    }
+}
+/**
+ * Runs queue persistence inside the query-monitor category hidden by the dev panel.
+ *
+ * @param callback - Queue database operation to execute.
+ * @returns The callback result.
+ */
+function withQueueQueryCategory(callback) {
+    return withQueryMonitorCategory('queue', callback);
+}
+/**
+ * Normalizes the number of stored failures returned to development tooling.
+ *
+ * @param limit - Requested maximum failure count.
+ * @returns Positive bounded failure count.
+ */
+function normalizeFailureLimit(limit) {
+    if (!Number.isFinite(limit) || limit <= 0)
+        return 100;
+    return Math.min(500, Math.max(1, Math.trunc(limit)));
+}
+/**
+ * Converts a failed-job ActiveRecord into the driver-independent contract.
+ *
+ * @param record - Persisted failed queue record.
+ * @returns Serialized terminal queue failure.
+ */
+function queueFailedJobFromRecord(record) {
+    return {
+        id: Number(record.id),
+        connection: String(record.connection),
+        queue: String(record.queue),
+        payload: parsePayload(record.payload),
+        exception: String(record.exception),
+        failedAt: failedAtIso(record.failedAt),
+    };
+}
+/**
+ * Converts a failed-job timestamp into the serialized driver contract.
+ *
+ * @param value - Timestamp converted by the failed-job model.
+ * @returns ISO failed-job timestamp.
+ */
+function failedAtIso(value) {
+    return value instanceof Date && !Number.isNaN(value.getTime())
+        ? value.toISOString()
+        : new Date(0).toISOString();
+}
+/**
+ * Returns the current Unix timestamp in seconds for queue scheduling fields.
+ *
+ * @returns Current Unix timestamp in seconds.
+ */
+function unixTimestamp() {
+    return Math.floor(Date.now() / 1000);
+}
+/**
+ * Formats an error for failed job storage.
+ *
+ * @param error - Unknown handler error.
+ * @returns Stack or message with validation details when available.
+ */
+function errorStack(error) {
+    const details = validationErrorDetails(error);
+    const message = error instanceof Error ? error.stack || error.message : String(error);
+    if (details.length === 0 || message.includes('Validation errors:')) {
+        return message;
+    }
+    return [
+        message,
+        '',
+        'Validation errors:',
+        ...details.map(detail => `- ${detail}`),
+    ].join('\n');
+}
+/**
+ * Validates and returns a stored queue payload.
+ *
+ * @param payload - Payload read from the queued job record.
+ * @returns Valid queue payload envelope.
+ */
+function parsePayload(payload) {
+    if (!payload || !payload.job || typeof payload.job !== 'string') {
+        throw new Error('Queued job payload is missing a job name.');
+    }
+    return payload;
+}
+/**
+ * Extracts nested field validation errors from an unknown error.
+ *
+ * @param error - Unknown error value.
+ * @returns Flattened validation error details.
+ */
+function validationErrorDetails(error) {
+    const errors = fieldErrorsFrom(error);
+    if (errors.length > 0) {
+        return errors.map(formatFieldError);
+    }
+    if (error && typeof error === 'object' && 'cause' in error) {
+        return validationErrorDetails(error.cause);
+    }
+    return [];
+}
+/**
+ * Returns field validation errors attached to an error object.
+ *
+ * @param error - Unknown error value.
+ * @returns Field validation errors, or an empty array.
+ */
+function fieldErrorsFrom(error) {
+    if (!error || typeof error !== 'object')
+        return [];
+    const errors = error.errors;
+    if (!Array.isArray(errors) || !errors.every(isFieldError)) {
+        return [];
+    }
+    return errors;
+}
+/**
+ * Checks whether a value has the framework field error shape.
+ *
+ * @param value - Unknown value to inspect.
+ * @returns True when the value is a field error.
+ */
+function isFieldError(value) {
+    return (typeof value === 'object'
+        && value !== null
+        && typeof value.field === 'string'
+        && typeof value.message === 'string');
+}
+/**
+ * Formats one field validation error for failed job diagnostics.
+ *
+ * @param error - Field error to format.
+ * @returns Human-readable validation error.
+ */
+function formatFieldError(error) {
+    const details = [
+        error.code ? `code: ${error.code}` : null,
+        Object.prototype.hasOwnProperty.call(error, 'value')
+            ? `value: ${formatValidationValue(error.value)}`
+            : null,
+        error.details !== undefined
+            ? `details: ${formatValidationValue(error.details)}`
+            : null,
+    ].filter((value) => Boolean(value));
+    return details.length
+        ? `${error.field}: ${error.message} (${details.join(', ')})`
+        : `${error.field}: ${error.message}`;
+}
+/**
+ * Formats an arbitrary validation detail value.
+ *
+ * @param value - Unknown validation detail value.
+ * @returns String representation safe for failed job storage.
+ */
+function formatValidationValue(value) {
+    if (value === undefined)
+        return 'undefined';
+    try {
+        const serialized = JSON.stringify(value);
+        return truncateValidationValue(serialized === undefined ? String(value) : serialized);
+    }
+    catch {
+        return truncateValidationValue(String(value));
+    }
+}
+/**
+ * Bounds long validation values before storing them in failed job output.
+ *
+ * @param value - Value to truncate.
+ * @returns Original or truncated value.
+ */
+function truncateValidationValue(value) {
+    const maxLength = 500;
+    if (value.length <= maxLength)
+        return value;
+    return `${value.slice(0, maxLength - 3)}...`;
+}