@db3.ai/app 0.1.0-beta.1

package/dist/queue/queueMonitor.d.ts

@@ -0,0 +1,133 @@
+import { type DevtoolsEnvironment, type DevtoolsEventDispatcher, type HttpEventDispatcherOptions } from '../devtools/index.js';
+import type * as queue from './contracts/index.js';
+export type QueueMonitorMode = 'dev' | 'full';
+export type QueueMonitorAction = queue.QueueLifecycleAction;
+export interface QueueMonitorOptions {
+    /**
+     * Human-readable source name copied to every emitted queue event.
+     */
+    source?: string;
+    /**
+     * Number of recent queue events retained in memory.
+     */
+    maxEntries?: number;
+    /**
+     * Whether queued payload data should be copied into emitted events.
+     */
+    includePayload?: boolean;
+    /**
+     * Optional event sink that receives every retained queue event.
+     */
+    dispatch?: QueueMonitorDispatcher;
+}
+/**
+ * HTTP delivery configuration for queue monitor events.
+ */
+export type HttpQueueMonitorDispatcherOptions = HttpEventDispatcherOptions;
+export interface QueueMonitorEvent {
+    type: 'queue.job';
+    id: string;
+    source: string;
+    timestamp: string;
+    action: QueueMonitorAction;
+    queue: string;
+    jobName: string;
+    jobId?: queue.QueueJobId;
+    jobUuid?: string;
+    attempts?: number;
+    maxTries?: number;
+    delaySeconds?: number;
+    durationMs?: number;
+    errorMessage?: string;
+    origin?: queue.QueueJobOrigin;
+    payloadData?: Record<string, unknown>;
+}
+export interface QueueMonitorJobEventInput {
+    timestamp?: string;
+    action: QueueMonitorAction;
+    queue: string;
+    jobName: string;
+    jobId?: queue.QueueJobId;
+    jobUuid?: string;
+    attempts?: number;
+    maxTries?: number;
+    delaySeconds?: number;
+    durationMs?: number;
+    error?: unknown;
+    origin?: queue.QueueJobOrigin;
+    payloadData?: Record<string, unknown>;
+}
+export type QueueMonitorListener = (event: QueueMonitorEvent) => void;
+export type QueueMonitorDispatcher = (event: QueueMonitorEvent) => void;
+interface QueueMonitorEnvironment extends DevtoolsEnvironment {
+    PLATFORM_QUEUE_MONITOR?: string;
+    PLATFORM_QUEUE_MONITOR_MAX?: string;
+    PLATFORM_QUEUE_MONITOR_PAYLOAD?: string;
+    PLATFORM_QUEUE_MONITOR_SOURCE?: string;
+    npm_package_name?: string;
+}
+/**
+ * Captures queue lifecycle events for local development panels and tests.
+ */
+export declare class QueueMonitor {
+    private readonly entries;
+    private readonly listeners;
+    private readonly maxEntries;
+    private readonly source;
+    private readonly includePayload;
+    private readonly dispatch?;
+    /**
+     * Creates a queue lifecycle monitor.
+     */
+    constructor(options?: QueueMonitorOptions);
+    /**
+     * Returns queue events retained in memory.
+     */
+    recent(): QueueMonitorEvent[];
+    /**
+     * Removes queue events from the in-memory buffer.
+     */
+    clear(): void;
+    /**
+     * Subscribes to queue events and returns an unsubscribe callback.
+     */
+    subscribe(listener: QueueMonitorListener): () => void;
+    /**
+     * Records one queue job lifecycle event.
+     *
+     * @param input - Queue job lifecycle fields.
+     */
+    recordJob(input: QueueMonitorJobEventInput): void;
+    /**
+     * Records one event produced by the always-on queue lifecycle dispatcher.
+     *
+     * @param event - Queue lifecycle event to retain and forward.
+     */
+    recordLifecycleEvent(event: queue.QueueLifecycleEvent): void;
+    /**
+     * Creates a stable id for terminal failures and a unique id for lifecycle events.
+     *
+     * A job UUID keeps repeated terminal instrumentation deliveries as one panel row.
+     *
+     * @param input - Queue event fields used to identify a terminal failure.
+     * @returns Stable failed-event id or a fresh lifecycle event id.
+     */
+    private eventId;
+    /**
+     * Retains an event and notifies local plus external subscribers.
+     */
+    private record;
+}
+/**
+ * Enables the environment-default queue monitor when the runtime opts in.
+ */
+export declare function enableDefaultQueueMonitor(options?: QueueMonitorOptions | false | undefined, env?: QueueMonitorEnvironment): QueueMonitor | null;
+/**
+ * Resolves queue monitor defaults from development and observability env vars.
+ */
+export declare function defaultQueueMonitorOptions(env?: QueueMonitorEnvironment): QueueMonitorOptions | null;
+/**
+ * Creates a fire-and-forget batched HTTP dispatcher for queue events.
+ */
+export declare function createHttpQueueMonitorDispatcher(options?: HttpQueueMonitorDispatcherOptions): DevtoolsEventDispatcher<QueueMonitorEvent>;
+export {};

package/dist/queue/queueMonitor.js

@@ -0,0 +1,238 @@
+import { randomUUID } from 'node:crypto';
+import { createHttpEventDispatcher, devtoolsEventsUrl, isInteractiveDevelopmentEnvironment, } from '../devtools/index.js';
+import { isDevelopmentEnvironment } from '../db/sqlErrors.js';
+const defaultMaxEntries = 500;
+/**
+ * Captures queue lifecycle events for local development panels and tests.
+ */
+export class QueueMonitor {
+    entries = [];
+    listeners = new Set();
+    maxEntries;
+    source;
+    includePayload;
+    dispatch;
+    /**
+     * Creates a queue lifecycle monitor.
+     */
+    constructor(options = {}) {
+        this.maxEntries = normalizePositiveInteger(options.maxEntries, defaultMaxEntries);
+        this.source = options.source || 'app';
+        this.includePayload = options.includePayload ?? false;
+        this.dispatch = options.dispatch;
+    }
+    /**
+     * Returns queue events retained in memory.
+     */
+    recent() {
+        return [...this.entries];
+    }
+    /**
+     * Removes queue events from the in-memory buffer.
+     */
+    clear() {
+        this.entries.length = 0;
+    }
+    /**
+     * Subscribes to queue events and returns an unsubscribe callback.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Records one queue job lifecycle event.
+     *
+     * @param input - Queue job lifecycle fields.
+     */
+    recordJob(input) {
+        this.record({
+            type: 'queue.job',
+            id: this.eventId(input),
+            source: this.source,
+            timestamp: input.timestamp ?? new Date().toISOString(),
+            action: input.action,
+            queue: input.queue,
+            jobName: input.jobName,
+            jobId: input.jobId,
+            jobUuid: input.jobUuid,
+            attempts: input.attempts,
+            maxTries: input.maxTries,
+            delaySeconds: input.delaySeconds,
+            durationMs: input.durationMs === undefined ? undefined : roundDuration(input.durationMs),
+            errorMessage: input.error === undefined ? undefined : errorMessage(input.error),
+            origin: input.origin,
+            payloadData: this.includePayload ? input.payloadData : undefined,
+        });
+    }
+    /**
+     * Records one event produced by the always-on queue lifecycle dispatcher.
+     *
+     * @param event - Queue lifecycle event to retain and forward.
+     */
+    recordLifecycleEvent(event) {
+        this.recordJob({
+            timestamp: event.timestamp,
+            action: event.action,
+            queue: event.queue,
+            jobName: event.jobName,
+            jobId: event.jobId,
+            jobUuid: event.jobUuid,
+            attempts: event.attempts,
+            maxTries: event.maxTries,
+            delaySeconds: event.delaySeconds,
+            durationMs: event.durationMs,
+            error: event.error,
+            origin: event.origin,
+            payloadData: event.payloadData,
+        });
+    }
+    /**
+     * Creates a stable id for terminal failures and a unique id for lifecycle events.
+     *
+     * A job UUID keeps repeated terminal instrumentation deliveries as one panel row.
+     *
+     * @param input - Queue event fields used to identify a terminal failure.
+     * @returns Stable failed-event id or a fresh lifecycle event id.
+     */
+    eventId(input) {
+        if (input.action === 'failed' && input.jobUuid) {
+            return `queue-failed:${input.jobUuid}`;
+        }
+        return randomUUID();
+    }
+    /**
+     * Retains an event and notifies local plus external subscribers.
+     */
+    record(event) {
+        this.entries.push(event);
+        while (this.entries.length > this.maxEntries) {
+            this.entries.shift();
+        }
+        for (const listener of this.listeners) {
+            listener(event);
+        }
+        this.dispatch?.(event);
+    }
+}
+/**
+ * Enables the environment-default queue monitor when the runtime opts in.
+ */
+export function enableDefaultQueueMonitor(options = undefined, env = process.env) {
+    if (options === false)
+        return null;
+    const defaults = defaultQueueMonitorOptions(env);
+    const resolved = defaults || options
+        ? {
+            ...(defaults ?? {}),
+            ...(options ?? {}),
+        }
+        : null;
+    if (!resolved)
+        return null;
+    return new QueueMonitor(resolved);
+}
+/**
+ * Resolves queue monitor defaults from development and observability env vars.
+ */
+export function defaultQueueMonitorOptions(env = process.env) {
+    const mode = queueMonitorMode(env.PLATFORM_QUEUE_MONITOR, env.NODE_ENV);
+    if (!mode)
+        return null;
+    return {
+        source: env.PLATFORM_QUEUE_MONITOR_SOURCE || env.npm_package_name || 'app',
+        maxEntries: parseIntegerEnv(env.PLATFORM_QUEUE_MONITOR_MAX, defaultMaxEntries),
+        includePayload: booleanEnv(env.PLATFORM_QUEUE_MONITOR_PAYLOAD, mode === 'full' || (mode === 'dev' && isDevelopmentEnvironment(env.NODE_ENV ?? ''))),
+        dispatch: createHttpQueueMonitorDispatcher({
+            url: devtoolsEventsUrl(env),
+        }),
+    };
+}
+/**
+ * Creates a fire-and-forget batched HTTP dispatcher for queue events.
+ */
+export function createHttpQueueMonitorDispatcher(options = {}) {
+    return createHttpEventDispatcher(options);
+}
+/**
+ * Resolves whether monitoring should be active for the current environment.
+ */
+function queueMonitorMode(input, environment) {
+    const normalized = (input || '').toLowerCase().trim();
+    switch (normalized) {
+        case '':
+            return isInteractiveDevelopmentEnvironment(environment) ? 'dev' : null;
+        case '1':
+        case 'true':
+        case 'on':
+        case 'dev':
+            return 'dev';
+        case 'full':
+            return 'full';
+        case '0':
+        case 'false':
+        case 'off':
+            return null;
+        default:
+            return isInteractiveDevelopmentEnvironment(environment) ? 'dev' : null;
+    }
+}
+/**
+ * Converts an unknown thrown value into a useful event message.
+ */
+function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (error === undefined || error === null)
+        return '';
+    return String(error);
+}
+/**
+ * Rounds a duration to one decimal place while keeping tiny timings visible.
+ */
+function roundDuration(durationMs) {
+    if (!Number.isFinite(durationMs) || durationMs < 0)
+        return 0;
+    return Math.round(durationMs * 10) / 10;
+}
+/**
+ * Parses a boolean env var while preserving a default value.
+ */
+function booleanEnv(input, fallback) {
+    if (input === undefined || input === '')
+        return fallback;
+    switch (input.toLowerCase().trim()) {
+        case '1':
+        case 'true':
+        case 'yes':
+        case 'on':
+            return true;
+        case '0':
+        case 'false':
+        case 'no':
+        case 'off':
+            return false;
+        default:
+            return fallback;
+    }
+}
+/**
+ * Parses an integer env var while enforcing a positive fallback.
+ */
+function parseIntegerEnv(input, fallback) {
+    const parsed = Number(input);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return normalizePositiveInteger(parsed, fallback);
+}
+/**
+ * Returns a positive integer or the supplied fallback.
+ */
+function normalizePositiveInteger(input, fallback) {
+    const value = Number(input);
+    if (!Number.isFinite(value) || value <= 0)
+        return fallback;
+    return Math.trunc(value);
+}

package/dist/scheduler/ScheduledCall.d.ts

@@ -0,0 +1,25 @@
+import type * as scheduler from './contracts/index.js';
+import { ScheduledEvent } from './ScheduledEvent.js';
+/**
+ * Fluent daily schedule for one short inline callback.
+ */
+export declare class ScheduledCall extends ScheduledEvent {
+    private readonly callback;
+    readonly kind: "call";
+    /**
+     * Creates a scheduled inline callback.
+     *
+     * @param callback - Short synchronous or asynchronous task.
+     */
+    constructor(callback: scheduler.ScheduledCallHandler);
+    /**
+     * Runs the scheduled callback and awaits asynchronous completion.
+     */
+    run(): Promise<void>;
+    /**
+     * Requires every callback schedule to declare a stable explicit name.
+     *
+     * @returns Null because anonymous callback identity is not durable.
+     */
+    protected defaultName(): string | null;
+}

package/dist/scheduler/ScheduledCall.js

@@ -0,0 +1,31 @@
+import { ScheduledEvent } from './ScheduledEvent.js';
+/**
+ * Fluent daily schedule for one short inline callback.
+ */
+export class ScheduledCall extends ScheduledEvent {
+    callback;
+    kind = 'call';
+    /**
+     * Creates a scheduled inline callback.
+     *
+     * @param callback - Short synchronous or asynchronous task.
+     */
+    constructor(callback) {
+        super();
+        this.callback = callback;
+    }
+    /**
+     * Runs the scheduled callback and awaits asynchronous completion.
+     */
+    async run() {
+        await this.callback();
+    }
+    /**
+     * Requires every callback schedule to declare a stable explicit name.
+     *
+     * @returns Null because anonymous callback identity is not durable.
+     */
+    defaultName() {
+        return null;
+    }
+}

package/dist/scheduler/ScheduledEvent.d.ts

@@ -0,0 +1,74 @@
+import type * as scheduler from './contracts/index.js';
+/**
+ * Shared fluent timing configuration for scheduled jobs and calls.
+ */
+export declare abstract class ScheduledEvent {
+    abstract readonly kind: scheduler.ScheduledTaskKind;
+    protected configuredName: string | null;
+    protected configuredFrequency: scheduler.DailyScheduleFrequency | null;
+    protected configuredTimezone: string;
+    /**
+     * Sets the stable identity used for deduplication and history.
+     *
+     * @param name - Stable non-empty schedule name.
+     * @returns This scheduled event.
+     */
+    name(name: string): this;
+    /**
+     * Schedules this task every day at local midnight.
+     *
+     * @returns This scheduled event.
+     */
+    daily(): this;
+    /**
+     * Schedules this task every day at one local wall-clock time.
+     *
+     * @param time - Time in 24-hour HH:mm form.
+     * @returns This scheduled event.
+     */
+    dailyAt(time: string): this;
+    /**
+     * Sets the IANA timezone used to interpret this event's local time.
+     *
+     * @param timezone - IANA timezone such as Europe/London.
+     * @returns This scheduled event.
+     */
+    timezone(timezone: string): this;
+    /**
+     * Returns whether this event is due at one canonical UTC minute.
+     *
+     * @param instant - UTC minute being evaluated.
+     * @returns True when the configured daily time matches.
+     */
+    isDue(instant: Date): boolean;
+    /**
+     * Returns the normalized public schedule definition.
+     *
+     * @returns Validated schedule definition.
+     */
+    definition(): scheduler.ScheduledTaskDefinition;
+    /**
+     * Resolves the stable event name or throws when one is unavailable.
+     *
+     * @returns Stable event name.
+     */
+    protected resolvedName(): string;
+    /**
+     * Returns the daily frequency or throws when none was configured.
+     *
+     * @returns Configured daily frequency.
+     */
+    private frequency;
+    /**
+     * Returns the default stable name supplied by the concrete event type.
+     *
+     * @returns Default name, or null when explicit naming is required.
+     */
+    protected abstract defaultName(): string | null;
+    /**
+     * Returns the known queue job name for public schedule inspection.
+     *
+     * @returns Queue job name, or null for calls and deferred factories.
+     */
+    protected resolvedJobName(): string | null;
+}

package/dist/scheduler/ScheduledEvent.js

@@ -0,0 +1,115 @@
+import { dailyScheduleIsDue, normalizeDailyTime, normalizeScheduleTimezone } from './scheduleTime.js';
+/**
+ * Shared fluent timing configuration for scheduled jobs and calls.
+ */
+export class ScheduledEvent {
+    configuredName = null;
+    configuredFrequency = null;
+    configuredTimezone = 'UTC';
+    /**
+     * Sets the stable identity used for deduplication and history.
+     *
+     * @param name - Stable non-empty schedule name.
+     * @returns This scheduled event.
+     */
+    name(name) {
+        const normalized = name.trim();
+        if (!normalized) {
+            throw new Error('Scheduled event names cannot be empty.');
+        }
+        if (normalized.length > 255) {
+            throw new Error('Scheduled event names cannot exceed 255 characters.');
+        }
+        this.configuredName = normalized;
+        return this;
+    }
+    /**
+     * Schedules this task every day at local midnight.
+     *
+     * @returns This scheduled event.
+     */
+    daily() {
+        return this.dailyAt('00:00');
+    }
+    /**
+     * Schedules this task every day at one local wall-clock time.
+     *
+     * @param time - Time in 24-hour HH:mm form.
+     * @returns This scheduled event.
+     */
+    dailyAt(time) {
+        this.configuredFrequency = {
+            type: 'daily',
+            time: normalizeDailyTime(time),
+        };
+        return this;
+    }
+    /**
+     * Sets the IANA timezone used to interpret this event's local time.
+     *
+     * @param timezone - IANA timezone such as Europe/London.
+     * @returns This scheduled event.
+     */
+    timezone(timezone) {
+        this.configuredTimezone = normalizeScheduleTimezone(timezone);
+        return this;
+    }
+    /**
+     * Returns whether this event is due at one canonical UTC minute.
+     *
+     * @param instant - UTC minute being evaluated.
+     * @returns True when the configured daily time matches.
+     */
+    isDue(instant) {
+        const frequency = this.frequency();
+        return dailyScheduleIsDue(instant, frequency.time, this.configuredTimezone);
+    }
+    /**
+     * Returns the normalized public schedule definition.
+     *
+     * @returns Validated schedule definition.
+     */
+    definition() {
+        const jobName = this.resolvedJobName();
+        return {
+            name: this.resolvedName(),
+            kind: this.kind,
+            frequency: this.frequency(),
+            timezone: this.configuredTimezone,
+            ...(jobName ? {
+                jobName,
+            } : {}),
+        };
+    }
+    /**
+     * Resolves the stable event name or throws when one is unavailable.
+     *
+     * @returns Stable event name.
+     */
+    resolvedName() {
+        const name = this.configuredName ?? this.defaultName();
+        if (!name) {
+            throw new Error(`${this.constructor.name} requires an explicit stable name.`);
+        }
+        return name;
+    }
+    /**
+     * Returns the daily frequency or throws when none was configured.
+     *
+     * @returns Configured daily frequency.
+     */
+    frequency() {
+        if (!this.configuredFrequency) {
+            throw new Error(`Scheduled event "${this.resolvedName()}" requires a frequency.`);
+        }
+        return this.configuredFrequency;
+    }
+    /**
+     * Returns the known queue job name for public schedule inspection.
+     *
+     * @returns Queue job name, or null for calls and deferred factories.
+     */
+    resolvedJobName() {
+        return null;
+    }
+}

package/dist/scheduler/ScheduledJob.d.ts

@@ -0,0 +1,34 @@
+import { type QueueableJob } from '../queue/index.js';
+import type * as scheduler from './contracts/index.js';
+import { ScheduledEvent } from './ScheduledEvent.js';
+/**
+ * Fluent daily schedule that creates a fresh QueueableJob when due.
+ */
+export declare class ScheduledJob extends ScheduledEvent {
+    private readonly source;
+    readonly kind: "job";
+    /**
+     * Creates a scheduled job definition.
+     *
+     * @param source - Zero-argument QueueableJob class or fresh-job factory.
+     */
+    constructor(source: scheduler.ScheduledJobSource);
+    /**
+     * Creates the QueueableJob for one claimed occurrence.
+     *
+     * @returns Fresh serializable queue job.
+     */
+    createJob(): QueueableJob;
+    /**
+     * Returns the class job name when no factory invocation is required.
+     *
+     * @returns Durable queue job name, or null for factories.
+     */
+    resolvedJobName(): string | null;
+    /**
+     * Uses the durable class job name as the default schedule identity.
+     *
+     * @returns Default job name, or null for parameterised factories.
+     */
+    protected defaultName(): string | null;
+}

package/dist/scheduler/ScheduledJob.js

@@ -0,0 +1,50 @@
+import { isQueueableJob, isQueueableJobClass, queueableJobName } from '../queue/index.js';
+import { ScheduledEvent } from './ScheduledEvent.js';
+/**
+ * Fluent daily schedule that creates a fresh QueueableJob when due.
+ */
+export class ScheduledJob extends ScheduledEvent {
+    source;
+    kind = 'job';
+    /**
+     * Creates a scheduled job definition.
+     *
+     * @param source - Zero-argument QueueableJob class or fresh-job factory.
+     */
+    constructor(source) {
+        super();
+        this.source = source;
+    }
+    /**
+     * Creates the QueueableJob for one claimed occurrence.
+     *
+     * @returns Fresh serializable queue job.
+     */
+    createJob() {
+        const job = isQueueableJobClass(this.source)
+            ? new this.source()
+            : this.source();
+        if (!isQueueableJob(job)) {
+            throw new Error(`Scheduled job "${this.resolvedName()}" did not create a QueueableJob.`);
+        }
+        return job;
+    }
+    /**
+     * Returns the class job name when no factory invocation is required.
+     *
+     * @returns Durable queue job name, or null for factories.
+     */
+    resolvedJobName() {
+        if (!isQueueableJobClass(this.source))
+            return null;
+        return queueableJobName(this.source);
+    }
+    /**
+     * Uses the durable class job name as the default schedule identity.
+     *
+     * @returns Default job name, or null for parameterised factories.
+     */
+    defaultName() {
+        return this.resolvedJobName();
+    }
+}