@db3.ai/app 0.1.0-beta.1

package/dist/server/App.d.ts

@@ -0,0 +1,141 @@
+import type { Knex } from 'knex';
+import { Ai, type AIOptions } from '../ai/index.js';
+import { Auth, type AuthOptions } from '../auth/index.js';
+import { Cache } from '../cache/index.js';
+import { Config, type ConfigValues } from '../config/index.js';
+import { Database, type DatabaseOptions } from '../db/index.js';
+import { Events } from '../events/index.js';
+import { UrlGenerator, type UrlGeneratorOptions } from '../url/index.js';
+import { Queue, type QueueOptions } from '../queue/index.js';
+import { Log, type LoggingOptions } from '../logging/index.js';
+import { Storage, type StorageOptions } from '../storage/index.js';
+import { Scheduler } from '../scheduler/index.js';
+import { Security } from '../security/index.js';
+import { Serializer, type SerializerOptions } from '../serialization/index.js';
+import { MediaManager } from '../media/index.js';
+import { RequestContext } from './RequestContext.js';
+/** Application root, service configuration and optional dependencies supplied at bootstrap. */
+export interface AppOptions {
+    /** App root as a path or file URL; defaults to the working directory at construction. */
+    directory?: string | URL;
+    /** Provider adapters and extensible ActiveRecord models for app().ai. */
+    ai?: AIOptions;
+    db?: Knex;
+    dbOptions?: DatabaseOptions;
+    auth?: Omit<AuthOptions<any>, 'db' | 'requestContext'>;
+    config?: ConfigValues | Config;
+    /** Application logging configuration or injectable logger driver. */
+    log?: LoggingOptions;
+    /** Canonical application URL configuration used across all runtimes. */
+    url?: UrlGeneratorOptions;
+    queue?: QueueOptions;
+    /** Serializable classes and ActiveRecord models registered with app().serializer. */
+    serializer?: SerializerOptions;
+    storage?: StorageOptions;
+}
+/**
+ * Application service hub.
+ *
+ * Keep this as the place where top-level framework capabilities are discovered
+ * and wired, not where domain logic itself accumulates.
+ */
+export declare class App {
+    protected readonly options: AppOptions;
+    private readonly services;
+    /** Absolute app root used for conventional server paths, independent of later working-directory changes. */
+    readonly directory: string;
+    /**
+     * Creates an application service hub and validates configured startup security.
+     *
+     * @param options - Framework services and application configuration.
+     */
+    constructor(options?: AppOptions);
+    /** Returns the lazy database service with this app's connection, model registry and root directory. */
+    get db(): Database;
+    get auth(): Auth<any>;
+    get requestContext(): RequestContext;
+    /** Returns the application AI service with durable request and conversation history. */
+    get ai(): Ai;
+    /**
+     * Returns the configured application cache.
+     *
+     * Cache driver selection lives under `config.cache`, keeping backend
+     * connection details out of application code.
+     *
+     * @returns Cache service using the configured named store.
+     */
+    get cache(): Cache;
+    /**
+     * Returns the typed in-process application event dispatcher.
+     *
+     * @returns Event service shared by framework and application code.
+     */
+    get events(): Events;
+    /**
+     * Returns the application logger shared by framework and app services.
+     *
+     * @returns Pino-backed logging service with app lifecycle ownership.
+     */
+    get log(): Log;
+    /**
+     * Returns the canonical application URL generator.
+     *
+     * This is independent of any concrete Fastify, Express, or other server
+     * instance so background processes resolve the same public application URL.
+     *
+     * @returns Shared canonical URL generator.
+     */
+    get url(): UrlGenerator;
+    /**
+     * Returns the configured app config repository.
+     */
+    get config(): Config;
+    get queue(): Queue;
+    /**
+     * Returns the application scheduler and attaches queue lifecycle recording.
+     *
+     * @returns Scheduler backed by the active database and queue services.
+     */
+    get scheduler(): Scheduler;
+    /**
+     * Returns the central application security service.
+     *
+     * @returns Shared authenticated encryption service.
+     */
+    get security(): Security;
+    /**
+     * Returns the application serializer and its scoped class/model registry.
+     *
+     * @returns Strict serializer configured for this application process.
+     */
+    get serializer(): Serializer;
+    /**
+     * Returns the configured file storage service.
+     */
+    get storage(): Storage;
+    /**
+     * Returns the configured media manager.
+     *
+     * Media options are resolved from `config.media`, allowing applications to
+     * place derived image variants on a disposable storage disk.
+     *
+     * @returns Media manager backed by configured durable and temporary storage.
+     */
+    get media(): MediaManager;
+    /**
+     * Registers a concrete service instance.
+     *
+     * Useful for tests and for services that are built by a provider.
+     */
+    set<TService>(name: string, service: TService): this;
+    /**
+     * Returns a configured service, creating and caching it on first access.
+     */
+    service<TService>(name: string, factory: () => TService): TService;
+    /**
+     * Closes shared resources owned by the default app.
+     */
+    close(): Promise<void>;
+    private resolveDbConnection;
+    private resolveDatabaseOptions;
+}

package/dist/server/App.js

@@ -0,0 +1,225 @@
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Ai } from '../ai/index.js';
+import { Auth, } from '../auth/index.js';
+import { Cache, } from '../cache/index.js';
+import { Config, } from '../config/index.js';
+import { db as defaultDb, destroyDatabase, } from '../db/connection.js';
+import { Database, } from '../db/index.js';
+import { Events } from '../events/index.js';
+import { UrlGenerator } from '../url/index.js';
+import { Queue, } from '../queue/index.js';
+import { Log, } from '../logging/index.js';
+import { Storage, } from '../storage/index.js';
+import { Scheduler } from '../scheduler/index.js';
+import { Security } from '../security/index.js';
+import { Serializer } from '../serialization/index.js';
+import { MediaManager } from '../media/index.js';
+import { RequestContext } from './RequestContext.js';
+import { clearActiveApp, setActiveApp, } from './appContext.js';
+/**
+ * Application service hub.
+ *
+ * Keep this as the place where top-level framework capabilities are discovered
+ * and wired, not where domain logic itself accumulates.
+ */
+export class App {
+    options;
+    services = new Map();
+    /** Absolute app root used for conventional server paths, independent of later working-directory changes. */
+    directory;
+    /**
+     * Creates an application service hub and validates configured startup security.
+     *
+     * @param options - Framework services and application configuration.
+     */
+    constructor(options = {}) {
+        this.options = options;
+        this.directory = resolve(options.directory instanceof URL ? fileURLToPath(options.directory) : options.directory ?? process.cwd());
+        setActiveApp(this);
+        if (this.config.has('security'))
+            void this.security;
+    }
+    /** Returns the lazy database service with this app's connection, model registry and root directory. */
+    get db() {
+        return this.service('db', () => {
+            return new Database(this.resolveDbConnection(), this.resolveDatabaseOptions(), this.directory);
+        });
+    }
+    get auth() {
+        return this.service('auth', () => new Auth({
+            ...this.options.auth,
+            db: this.db,
+            config: this.config,
+            requestContext: this.requestContext,
+        }));
+    }
+    get requestContext() {
+        return this.service('requestContext', () => new RequestContext());
+    }
+    /** Returns the application AI service with durable request and conversation history. */
+    get ai() {
+        return this.service('ai', () => new Ai(this.options.ai ?? this.config.get('ai', {})));
+    }
+    /**
+     * Returns the configured application cache.
+     *
+     * Cache driver selection lives under `config.cache`, keeping backend
+     * connection details out of application code.
+     *
+     * @returns Cache service using the configured named store.
+     */
+    get cache() {
+        return this.service('cache', () => new Cache(this.config.get('cache', {})));
+    }
+    /**
+     * Returns the typed in-process application event dispatcher.
+     *
+     * @returns Event service shared by framework and application code.
+     */
+    get events() {
+        return this.service('events', () => new Events());
+    }
+    /**
+     * Returns the application logger shared by framework and app services.
+     *
+     * @returns Pino-backed logging service with app lifecycle ownership.
+     */
+    get log() {
+        return this.service('log', () => new Log(this.options.log));
+    }
+    /**
+     * Returns the canonical application URL generator.
+     *
+     * This is independent of any concrete Fastify, Express, or other server
+     * instance so background processes resolve the same public application URL.
+     *
+     * @returns Shared canonical URL generator.
+     */
+    get url() {
+        return this.service('url', () => new UrlGenerator(this.options.url));
+    }
+    /**
+     * Returns the configured app config repository.
+     */
+    get config() {
+        return this.service('config', () => {
+            if (this.options.config instanceof Config) {
+                return this.options.config;
+            }
+            return new Config(this.options.config);
+        });
+    }
+    get queue() {
+        return this.service('queue', () => new Queue(this.db, this.options.queue));
+    }
+    /**
+     * Returns the application scheduler and attaches queue lifecycle recording.
+     *
+     * @returns Scheduler backed by the active database and queue services.
+     */
+    get scheduler() {
+        return this.service('scheduler', () => new Scheduler(this.db, this.queue));
+    }
+    /**
+     * Returns the central application security service.
+     *
+     * @returns Shared authenticated encryption service.
+     */
+    get security() {
+        return this.service('security', () => new Security());
+    }
+    /**
+     * Returns the application serializer and its scoped class/model registry.
+     *
+     * @returns Strict serializer configured for this application process.
+     */
+    get serializer() {
+        return this.service('serializer', () => new Serializer(this.options.serializer));
+    }
+    /**
+     * Returns the configured file storage service.
+     */
+    get storage() {
+        return this.service('storage', () => new Storage(this.options.storage));
+    }
+    /**
+     * Returns the configured media manager.
+     *
+     * Media options are resolved from `config.media`, allowing applications to
+     * place derived image variants on a disposable storage disk.
+     *
+     * @returns Media manager backed by configured durable and temporary storage.
+     */
+    get media() {
+        return this.service('media', () => new MediaManager(this.storage, this.config.get('media', {})));
+    }
+    /**
+     * Registers a concrete service instance.
+     *
+     * Useful for tests and for services that are built by a provider.
+     */
+    set(name, service) {
+        this.services.set(name, service);
+        return this;
+    }
+    /**
+     * Returns a configured service, creating and caching it on first access.
+     */
+    service(name, factory) {
+        const existing = this.services.get(name);
+        if (existing) {
+            return existing;
+        }
+        const created = factory();
+        this.services.set(name, created);
+        return created;
+    }
+    /**
+     * Closes shared resources owned by the default app.
+     */
+    async close() {
+        clearActiveApp(this);
+        this.services.get('scheduler')?.close();
+        this.services.get('events')?.clear();
+        await this.services.get('cache')?.close();
+        await this.services.get('log')?.close();
+        if (!this.options.db) {
+            await destroyDatabase();
+        }
+        this.services.clear();
+    }
+    resolveDbConnection() {
+        if (!this.options.db) {
+            return defaultDb();
+        }
+        return this.options.db;
+    }
+    resolveDatabaseOptions() {
+        return {
+            ...this.options.dbOptions,
+            syncColumns: this.options.dbOptions?.syncColumns
+                ?? parseOptionalBoolean(process.env.DB_SYNC_COLUMNS)
+                ?? true,
+        };
+    }
+}
+function parseOptionalBoolean(input) {
+    if (input === undefined || input === '') {
+        return undefined;
+    }
+    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:
+            throw new Error(`Invalid DB_SYNC_COLUMNS value "${input}". Use true or false.`);
+    }
+}

package/dist/server/RequestContext.d.ts

@@ -0,0 +1,42 @@
+export type RequestContextValues = Map<string, unknown> | Record<string, unknown> | Iterable<readonly [string, unknown]>;
+/**
+ * Request-scoped key/value context.
+ *
+ * Values are isolated with AsyncLocalStorage so the app singleton can expose
+ * request data without sharing it across concurrent requests.
+ */
+export declare class RequestContext {
+    private readonly storage;
+    /**
+     * Returns true when code is running inside a request context.
+     */
+    get active(): boolean;
+    /**
+     * Runs a callback inside an isolated request context.
+     */
+    run<TResult>(callback: () => TResult, initialValues?: RequestContextValues): TResult;
+    /**
+     * Reads a value from the active request context.
+     */
+    get<TValue = unknown>(key: string): TValue | undefined;
+    /**
+     * Returns true when the active request context contains a value for the key.
+     */
+    has(key: string): boolean;
+    /**
+     * Stores a value on the active request context.
+     */
+    set<TValue>(key: string, value: TValue): TValue;
+    /**
+     * Returns an existing request value or stores the factory result for reuse.
+     */
+    remember<TValue>(key: string, factory: () => TValue): TValue;
+    /**
+     * Deletes a value from the active request context.
+     */
+    delete(key: string): boolean;
+    /**
+     * Normalises initial request values into the internal map store.
+     */
+    private initialStore;
+}

package/dist/server/RequestContext.js

@@ -0,0 +1,95 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Request-scoped key/value context.
+ *
+ * Values are isolated with AsyncLocalStorage so the app singleton can expose
+ * request data without sharing it across concurrent requests.
+ */
+export class RequestContext {
+    storage = new AsyncLocalStorage();
+    /**
+     * Returns true when code is running inside a request context.
+     */
+    get active() {
+        return Boolean(this.storage.getStore());
+    }
+    /**
+     * Runs a callback inside an isolated request context.
+     */
+    run(callback, initialValues) {
+        return this.storage.run(this.initialStore(initialValues), callback);
+    }
+    /**
+     * Reads a value from the active request context.
+     */
+    get(key) {
+        return this.storage.getStore()?.get(key);
+    }
+    /**
+     * Returns true when the active request context contains a value for the key.
+     */
+    has(key) {
+        return this.storage.getStore()?.has(key) ?? false;
+    }
+    /**
+     * Stores a value on the active request context.
+     */
+    set(key, value) {
+        const store = this.storage.getStore();
+        if (!store) {
+            throw new Error('No active request context.');
+        }
+        store.set(key, value);
+        return value;
+    }
+    /**
+     * Returns an existing request value or stores the factory result for reuse.
+     */
+    remember(key, factory) {
+        const store = this.storage.getStore();
+        if (!store) {
+            return factory();
+        }
+        if (store.has(key)) {
+            return store.get(key);
+        }
+        const value = factory();
+        store.set(key, value);
+        if (isPromiseLike(value)) {
+            Promise.resolve(value).catch(() => {
+                if (store.get(key) === value) {
+                    store.delete(key);
+                }
+            });
+        }
+        return value;
+    }
+    /**
+     * Deletes a value from the active request context.
+     */
+    delete(key) {
+        return this.storage.getStore()?.delete(key) ?? false;
+    }
+    /**
+     * Normalises initial request values into the internal map store.
+     */
+    initialStore(initialValues) {
+        if (!initialValues)
+            return new Map();
+        if (initialValues instanceof Map)
+            return new Map(initialValues);
+        if (Symbol.iterator in Object(initialValues)) {
+            return new Map(initialValues);
+        }
+        return new Map(Object.entries(initialValues));
+    }
+}
+/**
+ * Detects promise-like values without forcing callers to return real promises.
+ */
+function isPromiseLike(value) {
+    return Boolean(value
+        && typeof value === 'object'
+        && 'then' in value
+        && typeof value.then === 'function');
+}

package/dist/server/appContext.d.ts

@@ -0,0 +1,34 @@
+import type { Knex } from 'knex';
+import type { App } from './App.js';
+import type { RequestContext } from './RequestContext.js';
+export interface AppDatabaseProvider {
+    db: {
+        knex: Knex;
+    };
+    requestContext?: RequestContext;
+}
+/**
+ * Registers the active app for framework services that need app-scoped access.
+ */
+export declare function setActiveApp(app: AppDatabaseProvider): AppDatabaseProvider;
+/**
+ * Returns the active application service hub.
+ *
+ * Framework and application jobs use this accessor to resolve services when
+ * their handle methods run inside a bootstrapped worker process.
+ *
+ * @returns Active application instance.
+ */
+export declare function app<TApp extends AppDatabaseProvider = App>(): TApp;
+/**
+ * Clears the active app when the caller owns the current active instance.
+ */
+export declare function clearActiveApp(app?: AppDatabaseProvider): void;
+/**
+ * Returns the active app database connection when an app is registered.
+ */
+export declare function activeAppDatabase(): Knex | null;
+/**
+ * Returns the active app request context when an app is registered.
+ */
+export declare function activeAppRequestContext(): RequestContext | null;

package/dist/server/appContext.js

@@ -0,0 +1,42 @@
+let activeApp = null;
+/**
+ * Registers the active app for framework services that need app-scoped access.
+ */
+export function setActiveApp(app) {
+    activeApp = app;
+    return app;
+}
+/**
+ * Returns the active application service hub.
+ *
+ * Framework and application jobs use this accessor to resolve services when
+ * their handle methods run inside a bootstrapped worker process.
+ *
+ * @returns Active application instance.
+ */
+export function app() {
+    if (!activeApp) {
+        throw new Error('No active application has been created.');
+    }
+    return activeApp;
+}
+/**
+ * Clears the active app when the caller owns the current active instance.
+ */
+export function clearActiveApp(app) {
+    if (app && activeApp !== app)
+        return;
+    activeApp = null;
+}
+/**
+ * Returns the active app database connection when an app is registered.
+ */
+export function activeAppDatabase() {
+    return activeApp?.db.knex ?? null;
+}
+/**
+ * Returns the active app request context when an app is registered.
+ */
+export function activeAppRequestContext() {
+    return activeApp?.requestContext ?? null;
+}

package/dist/server/index.d.ts

@@ -0,0 +1,3 @@
+export { App, type AppOptions, } from './App.js';
+export { app, activeAppDatabase, activeAppRequestContext, clearActiveApp, setActiveApp, type AppDatabaseProvider, } from './appContext.js';
+export { RequestContext, type RequestContextValues, } from './RequestContext.js';

package/dist/server/index.js

@@ -0,0 +1,3 @@
+export { App, } from './App.js';
+export { app, activeAppDatabase, activeAppRequestContext, clearActiveApp, setActiveApp, } from './appContext.js';
+export { RequestContext, } from './RequestContext.js';

package/dist/ssr/constants.d.ts

@@ -0,0 +1,6 @@
+/** Marker replaced with document head tags during SSR document assembly. */
+export declare const SSR_HEAD_MARKER = "<!--platform-ssr-head-->";
+/** Marker replaced with application markup during SSR document assembly. */
+export declare const SSR_APP_MARKER = "<!--platform-ssr-app-->";
+/** Marker replaced with safely serialised hydration state. */
+export declare const SSR_STATE_MARKER = "<!--platform-ssr-state-->";

package/dist/ssr/constants.js

@@ -0,0 +1,6 @@
+/** Marker replaced with document head tags during SSR document assembly. */
+export const SSR_HEAD_MARKER = '<!--platform-ssr-head-->';
+/** Marker replaced with application markup during SSR document assembly. */
+export const SSR_APP_MARKER = '<!--platform-ssr-app-->';
+/** Marker replaced with safely serialised hydration state. */
+export const SSR_STATE_MARKER = '<!--platform-ssr-state-->';

package/dist/ssr/contracts/DocumentHead.d.ts

@@ -0,0 +1,32 @@
+/** Attribute value supported by server-rendered document head tags. */
+export type DocumentHeadAttributeValue = string | number | boolean | null | undefined;
+/** Attributes written onto a server-rendered document head tag. */
+export type DocumentHeadAttributes = Record<string, DocumentHeadAttributeValue>;
+/**
+ * Script emitted through the single server-rendered document head pipeline.
+ *
+ * Content must come from trusted application code. The renderer prevents a
+ * closing script sequence from escaping the tag but does not sanitise scripts.
+ */
+export interface DocumentHeadScript {
+    /** HTML attributes written onto the script element. */
+    attributes?: DocumentHeadAttributes;
+    /** Trusted inline script or JSON-LD content. */
+    content?: string;
+}
+/**
+ * Head metadata collected while rendering one HTTP request.
+ *
+ * Applications can mutate this request-owned object from their SSR router or
+ * page components. It is rendered once into the document template.
+ */
+export interface DocumentHead {
+    /** Browser and search-result title for the rendered document. */
+    title?: string;
+    /** Meta elements, including descriptions, robots and social metadata. */
+    meta: DocumentHeadAttributes[];
+    /** Link elements, including canonical URLs and alternate resources. */
+    link: DocumentHeadAttributes[];
+    /** Trusted scripts, including JSON-LD structured data. */
+    script: DocumentHeadScript[];
+}

package/dist/ssr/contracts/DocumentHead.js

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

package/dist/ssr/contracts/SsrRenderContext.d.ts

@@ -0,0 +1,23 @@
+import type { DocumentHead } from './DocumentHead.js';
+import type { SsrRequest } from './SsrRequest.js';
+/** JSON-compatible request state made available to the hydrating client. */
+export type SsrState = Record<string, unknown>;
+/**
+ * Mutable state isolated to one server-side render request.
+ *
+ * Vue and other renderers may use `modules` to record the modules touched by a
+ * render. A later build adapter can map those identifiers to route-specific
+ * JavaScript and CSS without changing the application renderer contract.
+ */
+export interface SsrRenderContext<TState extends object = SsrState> {
+    /** Transport-neutral request information. */
+    request: SsrRequest;
+    /** Response status used when the render result does not override it. */
+    status: number;
+    /** Document metadata collected during rendering. */
+    head: DocumentHead;
+    /** State serialised into the document for client hydration. */
+    state: TState;
+    /** Module identifiers observed by the concrete server renderer. */
+    modules: Set<string>;
+}

package/dist/ssr/contracts/SsrRenderContext.js

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