@db3.ai/app 0.1.0-beta.1

package/dist/db/queryMonitor.js

@@ -0,0 +1,357 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHttpEventDispatcher, devtoolsEventsUrl, isInteractiveDevelopmentEnvironment, } from '../devtools/index.js';
+import { isDevelopmentEnvironment } from './sqlErrors.js';
+const defaultMaxEntries = 500;
+const monitors = new WeakMap();
+const queryMonitorContext = new AsyncLocalStorage();
+/**
+ * Runs database work under a framework category copied onto monitored query events.
+ *
+ * Categories let development tooling separate framework bookkeeping from application
+ * queries without parsing SQL or changing how the database operation itself behaves.
+ *
+ * @param category - Stable framework operation category such as `queue`.
+ * @param callback - Database work to execute inside the category context.
+ * @returns The callback result without changing its sync or async behavior.
+ */
+export function withQueryMonitorCategory(category, callback) {
+    return queryMonitorContext.run({
+        category,
+    }, callback);
+}
+/**
+ * Captures completed Knex query timings from one database connection.
+ */
+export class QueryMonitor {
+    connection;
+    starts = new Map();
+    entries = [];
+    listeners = new Set();
+    maxEntries;
+    source;
+    slowMs;
+    includeBindings;
+    dispatch;
+    eventedConnection;
+    handleQueryBound = this.handleQuery.bind(this);
+    handleQueryResponseBound = this.handleQueryResponse.bind(this);
+    handleQueryErrorBound = this.handleQueryError.bind(this);
+    /**
+     * Attaches monitor listeners to a Knex connection.
+     */
+    constructor(connection, options = {}) {
+        this.connection = connection;
+        this.maxEntries = normalizePositiveInteger(options.maxEntries, defaultMaxEntries);
+        this.source = options.source || 'app';
+        this.slowMs = normalizeNonNegativeNumber(options.slowMs, 0);
+        this.includeBindings = options.includeBindings ?? false;
+        this.dispatch = options.dispatch;
+        this.eventedConnection = connection;
+        this.eventedConnection.on('query', this.handleQueryBound);
+        this.eventedConnection.on('query-response', this.handleQueryResponseBound);
+        this.eventedConnection.on('query-error', this.handleQueryErrorBound);
+    }
+    /**
+     * Returns completed query events retained in memory.
+     */
+    recent() {
+        return [...this.entries];
+    }
+    /**
+     * Removes completed query events from the in-memory buffer.
+     */
+    clear() {
+        this.entries.length = 0;
+    }
+    /**
+     * Subscribes to completed query events and returns an unsubscribe callback.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Removes Knex event listeners registered by this monitor.
+     */
+    destroy() {
+        removeConnectionListener(this.eventedConnection, 'query', this.handleQueryBound);
+        removeConnectionListener(this.eventedConnection, 'query-response', this.handleQueryResponseBound);
+        removeConnectionListener(this.eventedConnection, 'query-error', this.handleQueryErrorBound);
+        this.listeners.clear();
+        this.starts.clear();
+    }
+    /**
+     * Stores the start metadata needed to calculate query duration.
+     */
+    handleQuery(query) {
+        const id = queryIdentifier(query);
+        const sql = typeof query.sql === 'string' ? query.sql : '';
+        this.starts.set(id, {
+            id,
+            source: this.source,
+            category: queryMonitorContext.getStore()?.category,
+            sql,
+            bindings: this.includeBindings ? normalizeBindings(query.bindings) : undefined,
+            startedAt: performance.now(),
+            transactionId: stringValue(query.__knexTxId),
+            connectionId: stringValue(query.__knexUid),
+        });
+    }
+    /**
+     * Publishes a successful completed query event.
+     */
+    handleQueryResponse(_response, query) {
+        this.complete(query, 'ok');
+    }
+    /**
+     * Publishes a failed completed query event.
+     */
+    handleQueryError(error, query) {
+        this.complete(query, 'error', errorMessage(error));
+    }
+    /**
+     * Converts a Knex completion event into the public monitor event shape.
+     */
+    complete(query, status, errorMessageValue) {
+        const id = queryIdentifier(query);
+        const started = this.starts.get(id) ?? fallbackStartedQuery(id, query, this.source, this.includeBindings);
+        const durationMs = roundDuration(performance.now() - started.startedAt);
+        this.starts.delete(id);
+        if (durationMs < this.slowMs)
+            return;
+        this.record({
+            type: 'db.query',
+            id,
+            source: started.source,
+            timestamp: new Date().toISOString(),
+            category: started.category,
+            sql: started.sql,
+            bindings: started.bindings,
+            durationMs,
+            status,
+            errorMessage: errorMessageValue,
+            transactionId: started.transactionId,
+            connectionId: started.connectionId,
+        });
+    }
+    /**
+     * 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);
+    }
+}
+/**
+ * Returns the existing monitor for a connection or attaches a new one.
+ */
+export function queryMonitorFor(connection, options = {}) {
+    const existing = monitors.get(connection);
+    if (existing)
+        return existing;
+    const monitor = new QueryMonitor(connection, options);
+    monitors.set(connection, monitor);
+    return monitor;
+}
+/**
+ * Enables the environment-default query monitor when the runtime opts in.
+ */
+export function enableDefaultQueryMonitor(connection, options = undefined, env = process.env) {
+    if (options === false)
+        return null;
+    const defaults = defaultQueryMonitorOptions(env);
+    const resolved = defaults || options
+        ? {
+            ...(defaults ?? {}),
+            ...(options ?? {}),
+        }
+        : null;
+    if (!resolved)
+        return null;
+    return queryMonitorFor(connection, resolved);
+}
+/**
+ * Resolves query monitor defaults from development and observability env vars.
+ */
+export function defaultQueryMonitorOptions(env = process.env) {
+    const mode = queryMonitorMode(env.PLATFORM_QUERY_MONITOR, env.NODE_ENV);
+    if (!mode)
+        return null;
+    const includeBindings = booleanEnv(env.PLATFORM_QUERY_MONITOR_BINDINGS, mode === 'full' || (mode === 'dev' && isDevelopmentEnvironment(env.NODE_ENV ?? '')));
+    return {
+        source: env.PLATFORM_QUERY_MONITOR_SOURCE || env.npm_package_name || 'app',
+        maxEntries: parseIntegerEnv(env.PLATFORM_QUERY_MONITOR_MAX, defaultMaxEntries),
+        slowMs: mode === 'slow'
+            ? parseNumberEnv(env.PLATFORM_QUERY_MONITOR_SLOW_MS, 100)
+            : parseNumberEnv(env.PLATFORM_QUERY_MONITOR_SLOW_MS, 0),
+        includeBindings,
+        dispatch: createHttpQueryMonitorDispatcher({
+            url: devtoolsEventsUrl(env),
+        }),
+    };
+}
+/**
+ * Creates a fire-and-forget batched HTTP dispatcher for query events.
+ */
+export function createHttpQueryMonitorDispatcher(options = {}) {
+    return createHttpEventDispatcher(options);
+}
+/**
+ * Resolves whether monitoring should be active for the current environment.
+ */
+function queryMonitorMode(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 'slow':
+            return 'slow';
+        case '0':
+        case 'false':
+        case 'off':
+            return null;
+        default:
+            return isInteractiveDevelopmentEnvironment(environment) ? 'dev' : null;
+    }
+}
+/**
+ * Normalizes Knex query bindings into a JSON-safe array copy.
+ */
+function normalizeBindings(input) {
+    if (input === undefined)
+        return undefined;
+    if (Array.isArray(input))
+        return [...input];
+    return [input];
+}
+/**
+ * Resolves a stable key for correlating Knex query lifecycle events.
+ */
+function queryIdentifier(query) {
+    return stringValue(query.__knexQueryUid)
+        || `${stringValue(query.__knexUid) || 'connection'}:${stringValue(query.sql)}`;
+}
+/**
+ * Creates fallback start metadata when Knex reports completion without a start.
+ */
+function fallbackStartedQuery(id, query, source, includeBindings) {
+    return {
+        id,
+        source,
+        category: queryMonitorContext.getStore()?.category,
+        sql: typeof query.sql === 'string' ? query.sql : '',
+        bindings: includeBindings ? normalizeBindings(query.bindings) : undefined,
+        startedAt: performance.now(),
+        transactionId: stringValue(query.__knexTxId),
+        connectionId: stringValue(query.__knexUid),
+    };
+}
+/**
+ * Converts unknown values into non-empty strings where possible.
+ */
+function stringValue(input) {
+    if (input === undefined || input === null)
+        return undefined;
+    const value = String(input);
+    return value || undefined;
+}
+/**
+ * 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);
+}
+/**
+ * Parses a number env var while preserving a fallback.
+ */
+function parseNumberEnv(input, fallback) {
+    const parsed = Number(input);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return parsed;
+}
+/**
+ * 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);
+}
+/**
+ * Returns a non-negative number or the supplied fallback.
+ */
+function normalizeNonNegativeNumber(input, fallback) {
+    const value = Number(input);
+    if (!Number.isFinite(value) || value < 0)
+        return fallback;
+    return value;
+}
+/**
+ * Removes an event listener from a Knex-like connection object.
+ */
+function removeConnectionListener(connection, event, listener) {
+    if (connection.off) {
+        connection.off(event, listener);
+        return;
+    }
+    connection.removeListener?.(event, listener);
+}

package/dist/db/sqlErrors.d.ts

@@ -0,0 +1,11 @@
+import { isSqlError } from '@db3.ai/pure';
+export { isSqlError };
+/**
+ * Local dev and tests can show exact SQL errors. Explicit production cannot.
+ */
+export declare function shouldExposeSqlErrorDetails(environment?: string | undefined): boolean;
+export declare function isDevelopmentEnvironment(environment?: string | undefined): boolean;
+export declare function publicSqlErrorMessage(error: unknown, options?: {
+    environment?: string;
+    productionMessage?: string;
+}): string | null;

package/dist/db/sqlErrors.js

@@ -0,0 +1,17 @@
+import { isSqlError, isDevelopmentEnvironment as pureIsDevelopmentEnvironment, publicSqlErrorMessage as purePublicSqlErrorMessage, shouldExposeSqlErrorDetails as pureShouldExposeSqlErrorDetails, } from '@db3.ai/pure';
+export { isSqlError };
+/**
+ * Local dev and tests can show exact SQL errors. Explicit production cannot.
+ */
+export function shouldExposeSqlErrorDetails(environment = process.env.NODE_ENV) {
+    return pureShouldExposeSqlErrorDetails(environment);
+}
+export function isDevelopmentEnvironment(environment = process.env.NODE_ENV) {
+    return pureIsDevelopmentEnvironment(environment);
+}
+export function publicSqlErrorMessage(error, options = {}) {
+    return purePublicSqlErrorMessage(error, {
+        ...options,
+        environment: options.environment ?? process.env.NODE_ENV,
+    });
+}

package/dist/db/test/db.d.ts

@@ -0,0 +1,11 @@
+import 'dotenv/config';
+import { type Knex } from 'knex';
+export interface GeneratedTestDatabase {
+    readonly db: Knex;
+    readonly databaseName: string;
+    destroy(): Promise<void>;
+}
+/**
+ * Creates an isolated test database for the configured SQL dialect.
+ */
+export declare function createGeneratedTestDatabase(label?: string): Promise<GeneratedTestDatabase>;

package/dist/db/test/db.js

@@ -0,0 +1,109 @@
+import 'dotenv/config';
+import crypto from 'node:crypto';
+import knex from 'knex';
+import { rememberDatabaseDialect, resolveDatabaseDialect, } from '../dialects/index.js';
+const SAFE_DATABASE_NAME = /^[A-Za-z0-9_]+$/;
+/**
+ * Creates an isolated test database for the configured SQL dialect.
+ */
+export async function createGeneratedTestDatabase(label = 'suite') {
+    const databaseName = createDatabaseName(label);
+    const dialect = resolveDatabaseDialect();
+    const admin = createKnex(undefined, dialect);
+    try {
+        await dialect.createDatabase(admin, databaseName);
+        const db = createKnex(databaseName, dialect);
+        return {
+            db,
+            databaseName,
+            async destroy() {
+                await db.destroy();
+                await dialect.dropDatabase(admin, databaseName);
+                await admin.destroy();
+            },
+        };
+    }
+    catch (error) {
+        await admin.destroy();
+        throw error;
+    }
+}
+/**
+ * Creates a Knex connection bound to the configured test dialect.
+ */
+function createKnex(databaseName, dialect = resolveDatabaseDialect()) {
+    const connection = knex({
+        client: dialect.knexClient,
+        connection: createConnection(databaseName, dialect),
+        pool: {
+            min: 0,
+            max: 2,
+        },
+    });
+    rememberDatabaseDialect(connection, dialect);
+    return connection;
+}
+/**
+ * Builds the test database connection object from environment variables.
+ */
+function createConnection(databaseName, dialect = resolveDatabaseDialect()) {
+    if (process.env.DATABASE_URL) {
+        return connectionFromUrl(process.env.DATABASE_URL, databaseName, dialect);
+    }
+    return {
+        host: process.env.DB_HOST || '127.0.0.1',
+        port: Number(process.env.DB_PORT || dialect.defaultPort),
+        user: process.env.DB_USER || 'root',
+        password: process.env.DB_PASSWORD || '',
+        database: databaseName,
+    };
+}
+/**
+ * Parses a database URL while allowing the generated database name to override it.
+ */
+function connectionFromUrl(databaseUrl, databaseName, dialect = resolveDatabaseDialect()) {
+    const url = new URL(databaseUrl);
+    return {
+        host: url.hostname,
+        port: Number(url.port || dialect.defaultPort),
+        user: decodeURIComponent(url.username),
+        password: decodeURIComponent(url.password),
+        database: databaseName,
+    };
+}
+/**
+ * Creates a safe generated database name for an integration test suite.
+ */
+function createDatabaseName(label) {
+    const prefix = process.env.DB_TEST_DATABASE_PREFIX || 'db3_app_test';
+    const suffix = label.replace(/[^A-Za-z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
+    const random = crypto.randomUUID().replace(/-/g, '').slice(0, 12);
+    const databaseName = `${prefix}_${process.pid}_${suffix || 'suite'}_${random}`;
+    assertSafeGeneratedDatabaseName(databaseName);
+    return databaseName.slice(0, 64);
+}
+/**
+ * Guards generated database names before create/drop SQL is executed.
+ */
+function assertSafeGeneratedDatabaseName(databaseName) {
+    const appDatabaseName = getAppDatabaseName();
+    if (!SAFE_DATABASE_NAME.test(databaseName)) {
+        throw new Error(`Unsafe test database name "${databaseName}".`);
+    }
+    if (!databaseName.toLowerCase().includes('test')) {
+        throw new Error(`Refusing to manage database "${databaseName}" because it does not contain "test".`);
+    }
+    if (appDatabaseName && databaseName === appDatabaseName) {
+        throw new Error(`Refusing to manage test database "${databaseName}" because it matches DB_DATABASE.`);
+    }
+}
+/**
+ * Resolves the configured application database name for destructive safety checks.
+ */
+function getAppDatabaseName() {
+    if (process.env.DATABASE_URL) {
+        const url = new URL(process.env.DATABASE_URL);
+        return url.pathname.replace(/^\//, '') || null;
+    }
+    return process.env.DB_DATABASE || null;
+}

package/dist/devtools/HttpEventDispatcher.d.ts

@@ -0,0 +1,19 @@
+import type * as devtools from './contracts/index.js';
+/**
+ * Builds the configured development event ingestion endpoint.
+ *
+ * @param env - Environment values controlling the devtools service address.
+ * @returns Absolute HTTP endpoint for event batches.
+ */
+export declare function devtoolsEventsUrl(env?: devtools.DevtoolsEnvironment): string;
+/**
+ * Creates a bounded, fire-and-forget HTTP dispatcher for framework events.
+ *
+ * Events are batched off the caller's stack. Failed batches are discarded and
+ * subsequent delivery pauses briefly, keeping development instrumentation from
+ * affecting application behavior when the event service is unavailable.
+ *
+ * @param options - Batching, endpoint, timeout, and test-fetch configuration.
+ * @returns Callable dispatcher with flush and close lifecycle methods.
+ */
+export declare function createHttpEventDispatcher<TEvent extends object>(options?: devtools.HttpEventDispatcherOptions): devtools.DevtoolsEventDispatcher<TEvent>;