@db3.ai/app 0.1.0-beta.1

package/dist/ssr/vite/fastifyViteSsr.js

@@ -0,0 +1,213 @@
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { fastifySsr } from '../fastify/index.js';
+import { applyViteSsrManifest } from './viteSsrManifest.js';
+const DEFAULT_TEMPLATE = 'index.html';
+const DEFAULT_DEVELOPMENT_ENTRY = '/src/entry-server.ts';
+const DEFAULT_CLIENT_OUT_DIR = 'dist/client';
+const DEFAULT_SERVER_ENTRY = 'dist/server/entry-server.js';
+const DEFAULT_MANIFEST = 'dist/client/.vite/ssr-manifest.json';
+const DEFAULT_RENDER_EXPORT = 'render';
+const DEVELOPMENT_ASSET_ROUTES = [
+    '/@vite/*',
+    '/@id/*',
+    '/@fs/*',
+    '/src/*',
+    '/node_modules/*',
+];
+/**
+ * Creates a Fastify plugin that owns Vite development and production SSR.
+ *
+ * The adapter loads application code through Vite in development, immutable
+ * build artifacts in production, optional static assets, and route-specific
+ * manifest links. Vue, routing and page data remain application concerns.
+ *
+ * @param options - Vite application paths and explicit SSR route ownership.
+ * @returns Fastify plugin ready to register on a web-delivery process.
+ *
+ * @example
+ * await server.register(fastifyViteSsr({
+ * 	root: import.meta.dirname,
+ * 	routes: ['/blog', '/blog/*'],
+ * 	staticAssets: {
+ * 		prefix: '/site-assets/',
+ * 		directory: 'dist/client/site-assets',
+ * 	},
+ * }));
+ */
+export function fastifyViteSsr(options) {
+    return async function platformFastifyViteSsr(server) {
+        if (!options.routes.length) {
+            throw new Error('Vite SSR requires at least one explicit page route.');
+        }
+        const mode = options.mode ?? (process.env.NODE_ENV === 'production' ? 'production' : 'development');
+        if (mode === 'development') {
+            const runtime = await developmentRuntime(server.server, options);
+            await server.register((await import('@fastify/middie')).default);
+            server.use(runtime.vite.middlewares);
+            registerDevelopmentAssetRoutes(server);
+            server.addHook('onClose', async () => {
+                await runtime.vite.close();
+            });
+            await server.register(fastifySsr({
+                routes: options.routes,
+                template: runtime.template,
+                render: runtime.render,
+            }));
+            return;
+        }
+        if (options.staticAssets) {
+            await server.register((await import('@fastify/static')).default, {
+                root: applicationPath(options.root, options.staticAssets.directory),
+                prefix: normalizedAssetPrefix(options.staticAssets.prefix),
+                index: false,
+            });
+        }
+        const runtime = await productionRuntime(options);
+        await server.register(fastifySsr({
+            routes: options.routes,
+            template: runtime.template,
+            render: runtime.render,
+        }));
+    };
+}
+/**
+ * Registers the Vite URL namespaces needed by browser development requests.
+ *
+ * Fastify resolves a route before running encapsulated middleware. These
+ * fallback routes keep Vite's middleware reachable for source styles, module
+ * transforms, dependency chunks, and its HMR client without claiming unrelated
+ * application page URLs. When Vite does not handle a matching request, the
+ * application's ordinary not-found boundary remains authoritative.
+ *
+ * @param server - Encapsulated Fastify instance hosting the Vite middleware.
+ */
+function registerDevelopmentAssetRoutes(server) {
+    for (const route of DEVELOPMENT_ASSET_ROUTES) {
+        server.get(route, (_request, reply) => reply.callNotFound());
+    }
+}
+/**
+ * Creates Vite middleware and hot server-entry loading for development.
+ *
+ * @param httpServer - Fastify's underlying HTTP server used for Vite HMR.
+ * @param options - Vite SSR application options.
+ * @returns Development runtime consumed by the transport adapter.
+ */
+async function developmentRuntime(httpServer, options) {
+    const { createServer } = await import('vite');
+    const vite = await createServer({
+        root: options.root,
+        configFile: options.viteConfigFile
+            ? applicationPath(options.root, options.viteConfigFile)
+            : undefined,
+        appType: 'custom',
+        server: {
+            middlewareMode: true,
+            hmr: { server: httpServer },
+        },
+    });
+    const templatePath = applicationPath(options.root, options.template ?? DEFAULT_TEMPLATE);
+    const developmentEntry = options.developmentEntry ?? DEFAULT_DEVELOPMENT_ENTRY;
+    const renderExport = options.renderExport ?? DEFAULT_RENDER_EXPORT;
+    return {
+        vite,
+        template: async (request) => {
+            const template = await readFile(templatePath, 'utf8');
+            return vite.transformIndexHtml(request.url, template);
+        },
+        render: async (context) => {
+            try {
+                const module = await vite.ssrLoadModule(developmentEntry);
+                const render = moduleRenderer(module, renderExport);
+                return await render(context);
+            }
+            catch (error) {
+                vite.ssrFixStacktrace(error);
+                throw error;
+            }
+        },
+    };
+}
+/**
+ * Loads immutable production templates, server code and optional manifest data.
+ *
+ * @param options - Vite SSR application options.
+ * @returns Production runtime consumed by the transport adapter.
+ */
+async function productionRuntime(options) {
+    const clientOutDir = options.clientOutDir ?? DEFAULT_CLIENT_OUT_DIR;
+    const templatePath = applicationPath(options.root, join(clientOutDir, options.template ?? DEFAULT_TEMPLATE));
+    const serverEntry = applicationPath(options.root, options.serverEntry ?? DEFAULT_SERVER_ENTRY);
+    const renderExport = options.renderExport ?? DEFAULT_RENDER_EXPORT;
+    const [template, module, manifest] = await Promise.all([
+        readFile(templatePath, 'utf8'),
+        import(pathToFileURL(serverEntry).href),
+        loadManifest(options),
+    ]);
+    const render = moduleRenderer(module, renderExport);
+    return {
+        template,
+        render: async (context) => {
+            const result = await render(context);
+            applyViteSsrManifest(context, manifest, {
+                preloadJavaScript: options.preloadJavaScript,
+            });
+            return result;
+        },
+    };
+}
+/**
+ * Loads the optional production SSR manifest.
+ *
+ * @param options - Vite SSR application options.
+ * @returns Parsed manifest or an empty map when explicitly disabled.
+ */
+async function loadManifest(options) {
+    if (options.manifest === false)
+        return {};
+    const path = applicationPath(options.root, options.manifest ?? DEFAULT_MANIFEST);
+    const value = JSON.parse(await readFile(path, 'utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`Vite SSR manifest must contain an object: ${path}`);
+    }
+    return value;
+}
+/**
+ * Resolves the configured server-entry renderer and validates its contract.
+ *
+ * @param module - Loaded development or production module namespace.
+ * @param name - Named renderer export.
+ * @returns Framework-compatible application renderer.
+ */
+function moduleRenderer(module, name) {
+    const render = module[name];
+    if (typeof render !== 'function') {
+        throw new Error(`Vite SSR server entry must export a "${name}" renderer.`);
+    }
+    return render;
+}
+/**
+ * Resolves an application-owned path without changing absolute paths.
+ *
+ * @param root - Absolute application root.
+ * @param path - Absolute or application-relative path.
+ * @returns Absolute filesystem path.
+ */
+function applicationPath(root, path) {
+    return isAbsolute(path) ? path : resolve(root, path);
+}
+/**
+ * Normalizes a Fastify static prefix to an absolute trailing-slash path.
+ *
+ * @param prefix - Application-provided public asset prefix.
+ * @returns Normalized Fastify route prefix.
+ */
+function normalizedAssetPrefix(prefix) {
+    const value = `/${prefix.trim().replace(/^\/+|\/+$/g, '')}/`;
+    if (value === '//') {
+        throw new Error('Vite SSR static asset prefix cannot be empty.');
+    }
+    return value;
+}

package/dist/ssr/vite/index.d.ts

@@ -0,0 +1,4 @@
+export type * from './contracts/index.js';
+export { fastifyViteSsr } from './fastifyViteSsr.js';
+export { applyViteSsrManifest } from './viteSsrManifest.js';
+export type { ApplyViteSsrManifestOptions, ViteSsrManifest } from './viteSsrManifest.js';

package/dist/ssr/vite/index.js

@@ -0,0 +1,2 @@
+export { fastifyViteSsr } from './fastifyViteSsr.js';
+export { applyViteSsrManifest } from './viteSsrManifest.js';

package/dist/ssr/vite/viteSsrManifest.d.ts

@@ -0,0 +1,16 @@
+import type { SsrRenderContext } from '../contracts/index.js';
+/** Vite SSR manifest mapping rendered module ids to their client build files. */
+export type ViteSsrManifest = Record<string, string[]>;
+/** Controls which client files should be preloaded for a rendered request. */
+export interface ApplyViteSsrManifestOptions {
+    /** Whether JavaScript module chunks should be preloaded for hydration. */
+    preloadJavaScript?: boolean;
+}
+/**
+ * Adds request-used Vite assets to the single document-head pipeline.
+ *
+ * @param context - Request-owned SSR context populated by the Vue renderer.
+ * @param manifest - Production Vite SSR manifest.
+ * @param options - Client preload policy for the current application.
+ */
+export declare function applyViteSsrManifest<TState extends object>(context: SsrRenderContext<TState>, manifest: ViteSsrManifest, options?: ApplyViteSsrManifestOptions): void;

package/dist/ssr/vite/viteSsrManifest.js

@@ -0,0 +1,63 @@
+/**
+ * Adds request-used Vite assets to the single document-head pipeline.
+ *
+ * @param context - Request-owned SSR context populated by the Vue renderer.
+ * @param manifest - Production Vite SSR manifest.
+ * @param options - Client preload policy for the current application.
+ */
+export function applyViteSsrManifest(context, manifest, options = {}) {
+    const seen = new Set(context.head.link
+        .map(link => typeof link.href === 'string' ? link.href : '')
+        .filter(Boolean));
+    for (const moduleId of context.modules) {
+        for (const file of manifest[moduleId] ?? []) {
+            const href = assetHref(file);
+            if (!href || seen.has(href))
+                continue;
+            const attributes = preloadAttributes(href, options);
+            if (!attributes)
+                continue;
+            context.head.link.push(attributes);
+            seen.add(href);
+        }
+    }
+}
+/**
+ * Normalizes one manifest file to a root-relative public URL.
+ *
+ * @param file - File path emitted by Vite.
+ * @returns Root-relative public URL or an empty string.
+ */
+function assetHref(file) {
+    const value = file.trim();
+    if (!value)
+        return '';
+    return value.startsWith('/') ? value : `/${value}`;
+}
+/**
+ * Maps a built asset to the corresponding preload or stylesheet element.
+ *
+ * @param href - Root-relative public asset URL.
+ * @param options - JavaScript preload policy.
+ * @returns Document-head attributes or null for unsupported assets.
+ */
+function preloadAttributes(href, options) {
+    if (href.endsWith('.css')) {
+        return { rel: 'stylesheet', href };
+    }
+    if (href.endsWith('.js')) {
+        return options.preloadJavaScript === false
+            ? null
+            : { rel: 'modulepreload', crossorigin: true, href };
+    }
+    if (href.endsWith('.woff2')) {
+        return { rel: 'preload', href, as: 'font', type: 'font/woff2', crossorigin: true };
+    }
+    if (href.endsWith('.woff')) {
+        return { rel: 'preload', href, as: 'font', type: 'font/woff', crossorigin: true };
+    }
+    if (/\.(avif|gif|jpe?g|png|webp)$/.test(href)) {
+        return { rel: 'preload', href, as: 'image' };
+    }
+    return null;
+}

package/dist/storage/Storage.d.ts

@@ -0,0 +1,244 @@
+import type { Readable } from 'node:stream';
+import type { StorageListing, StorageListOptions } from './contracts/index.js';
+import type { StorageContents, StorageDisk, StorageDiskFactory, StorageOptions, StoragePutOptions } from './types.js';
+/**
+ * Storage manager for configured application disks.
+ *
+ * This service owns disk discovery and caching. App code should usually use the
+ * default disk or a named disk instead of constructing driver classes directly.
+ */
+export declare class Storage {
+    private readonly options;
+    private readonly disks;
+    private readonly drivers;
+    /**
+     * Creates a storage manager with built-in local disk support.
+     *
+     * @param options - Storage defaults, disk definitions, and custom drivers.
+     */
+    constructor(options?: StorageOptions);
+    /**
+     * Returns the default disk name for this storage manager.
+     *
+     * @returns Configured default disk name.
+     */
+    get defaultDiskName(): string;
+    /**
+     * Returns a configured storage disk by name.
+     *
+     * @param name - Optional disk name; defaults to the configured default disk.
+     * @returns Cached storage disk instance.
+     *
+     * @example
+     * ```ts
+     * await app.storage.disk('agent').put('images/header.png', bytes);
+     * ```
+     */
+    disk(name?: string): StorageDisk;
+    /**
+     * Alias for disk(), matching Laravel's drive naming.
+     *
+     * @param name - Optional disk name; defaults to the configured default disk.
+     * @returns Cached storage disk instance.
+     */
+    drive(name?: string): StorageDisk;
+    /**
+     * Registers a storage disk instance for tests or providers.
+     *
+     * @param name - Disk name to register.
+     * @param disk - Concrete disk instance.
+     * @returns This storage manager.
+     */
+    setDisk(name: string, disk: StorageDisk): this;
+    /**
+     * Registers a named storage driver factory.
+     *
+     * @param name - Driver name used in disk config.
+     * @param factory - Factory that creates a disk from config.
+     * @returns This storage manager.
+     */
+    registerDriver(name: string, factory: StorageDiskFactory): this;
+    /**
+     * Writes file contents to the default disk.
+     *
+     * Alias for put(), useful when working from a shell or REPL.
+     *
+     * @param path - Relative storage path to write.
+     * @param contents - Bytes or text content to persist.
+     * @param options - Optional write metadata.
+     * @returns Promise that resolves once the file is written.
+     */
+    write(path: string, contents: StorageContents, options?: StoragePutOptions): Promise<void>;
+    /**
+     * Writes file contents to the default disk.
+     *
+     * @param path - Relative storage path to write.
+     * @param contents - Bytes or text content to persist.
+     * @param options - Optional write metadata.
+     * @returns Promise that resolves once the file is written.
+     */
+    put(path: string, contents: StorageContents, options?: StoragePutOptions): Promise<void>;
+    /**
+     * Writes streamed file contents to the default disk.
+     *
+     * @param path - Relative storage path to write.
+     * @param stream - Readable stream containing file bytes.
+     * @param options - Optional write metadata.
+     * @returns Promise that resolves once the stream is written.
+     */
+    writeStream(path: string, stream: Readable, options?: StoragePutOptions): Promise<void>;
+    /**
+     * Lists files and directories beneath a path on the default disk.
+     *
+     * @param path - Relative directory path, or an empty string for the disk root.
+     * @param options - Directory traversal options.
+     * @returns Lazy provider-neutral directory listing.
+     */
+    list(path?: string, options?: StorageListOptions): StorageListing;
+    /**
+     * Reads file contents from the default disk.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Stored file bytes.
+     */
+    get(path: string): Promise<Buffer>;
+    /**
+     * Reads file contents as text from the default disk.
+     *
+     * Matches Flystorage's readToString() API.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Stored text content.
+     */
+    readToString(path: string): Promise<string>;
+    /**
+     * Reads file contents into a Buffer from the default disk.
+     *
+     * Matches Flystorage's readToBuffer() API.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Stored file bytes.
+     */
+    readToBuffer(path: string): Promise<Buffer>;
+    /**
+     * Reads file contents into a Uint8Array from the default disk.
+     *
+     * Matches Flystorage's readToUint8Array() API.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Stored file bytes.
+     */
+    readToUint8Array(path: string): Promise<Uint8Array>;
+    /**
+     * Reads file contents as a stream from the default disk.
+     *
+     * Matches Flystorage's read() API. Use get() or getText() when the caller
+     * intentionally wants buffered contents instead.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Readable stream for the stored file.
+     */
+    read(path: string): Promise<Readable>;
+    /**
+     * Reads file contents as a stream from the default disk.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Readable stream for the stored file.
+     */
+    readStream(path: string): Promise<Readable>;
+    /**
+     * Reads file contents as text from the default disk.
+     *
+     * @param path - Relative storage path to read.
+     * @param encoding - Text encoding used to decode the bytes.
+     * @returns Stored text content.
+     */
+    getText(path: string, encoding?: BufferEncoding): Promise<string>;
+    /**
+     * Checks whether a file exists on the default disk.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns True when the file exists.
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Checks whether a file is missing from the default disk.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns True when the file does not exist.
+     */
+    missing(path: string): Promise<boolean>;
+    /**
+     * Deletes a file from the default disk.
+     *
+     * @param path - Relative storage path to delete.
+     * @returns True when a file was removed.
+     */
+    delete(path: string): Promise<boolean>;
+    /**
+     * Copies a file on the default disk.
+     *
+     * @param from - Existing relative storage path.
+     * @param to - New relative storage path.
+     * @returns Promise that resolves once the file is copied.
+     */
+    copy(from: string, to: string): Promise<void>;
+    /**
+     * Moves a file on the default disk.
+     *
+     * @param from - Existing relative storage path.
+     * @param to - New relative storage path.
+     * @returns Promise that resolves once the file is moved.
+     */
+    move(from: string, to: string): Promise<void>;
+    /**
+     * Returns file size from the default disk.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns File size in bytes.
+     */
+    size(path: string): Promise<number>;
+    /**
+     * Returns the last modification time from the default disk.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns Last modified date.
+     */
+    lastModified(path: string): Promise<Date>;
+    /**
+     * Returns a MIME type for a path on the default disk.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns MIME type inferred by the disk.
+     */
+    mimeType(path: string): Promise<string>;
+    /**
+     * Returns a public URL for a path on the default disk.
+     *
+     * @param path - Relative storage path to expose.
+     * @returns Public URL.
+     */
+    url(path: string): Promise<string>;
+    /**
+     * Returns an absolute filesystem path for a path on the default disk.
+     *
+     * @param path - Relative storage path to resolve.
+     * @returns Absolute filesystem path.
+     */
+    path(path: string): string;
+    /**
+     * Resolves configured disk options or the built-in local default.
+     *
+     * @param name - Disk name to resolve.
+     * @returns Disk config or concrete disk instance.
+     */
+    private resolveDiskConfig;
+    /**
+     * Creates a disk through the configured driver factory.
+     *
+     * @param name - Disk name being created.
+     * @param config - Disk configuration.
+     * @returns Storage disk instance.
+     */
+    private createDisk;
+}