@db3.ai/app 0.1.0-beta.1

package/dist/storage/types.d.ts

@@ -0,0 +1,218 @@
+import type { Readable } from 'node:stream';
+import type { StorageListing, StorageListOptions } from './contracts/index.js';
+export type StorageVisibility = 'public' | 'private';
+export type StorageContents = string | Buffer | Uint8Array | ArrayBuffer;
+export interface StoragePutOptions {
+    visibility?: StorageVisibility;
+    mimeType?: string;
+}
+export interface StorageFileStat {
+    path: string;
+    size: number;
+    lastModified: Date;
+}
+/**
+ * Runtime interface implemented by configured storage disks.
+ */
+export interface StorageDisk {
+    readonly name: string;
+    /**
+     * Writes file contents to a path on this disk.
+     *
+     * Alias for put(), useful for command-line and REPL usage.
+     *
+     * @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 a path on this 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 a path on this 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 this 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 as bytes from this disk.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Stored file contents.
+     */
+    get(path: string): Promise<Buffer>;
+    /**
+     * Reads file contents into a string from this 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 this disk.
+     *
+     * Matches Flystorage's readToBuffer() API.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Stored file contents.
+     */
+    readToBuffer(path: string): Promise<Buffer>;
+    /**
+     * Reads file contents into a Uint8Array from this disk.
+     *
+     * Matches Flystorage's readToUint8Array() API.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Stored file contents.
+     */
+    readToUint8Array(path: string): Promise<Uint8Array>;
+    /**
+     * Reads file contents as a stream from this disk.
+     *
+     * Matches Flystorage's read() API.
+     *
+     * @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 this 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 this disk.
+     *
+     * @param path - Relative storage path to read.
+     * @param encoding - Text encoding used to decode the file.
+     * @returns Stored text content.
+     */
+    getText(path: string, encoding?: BufferEncoding): Promise<string>;
+    /**
+     * Returns true when a file exists at the given path.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns True when the file exists.
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Returns true when a file does not exist at the given path.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns True when the file is missing.
+     */
+    missing(path: string): Promise<boolean>;
+    /**
+     * Deletes a file from this disk.
+     *
+     * @param path - Relative storage path to delete.
+     * @returns True when a file was deleted.
+     */
+    delete(path: string): Promise<boolean>;
+    /**
+     * Copies a file between two paths on this disk.
+     *
+     * @param from - Existing relative storage path.
+     * @param to - New relative storage path.
+     * @returns Promise that resolves once the copy is complete.
+     */
+    copy(from: string, to: string): Promise<void>;
+    /**
+     * Moves a file between two paths on this disk.
+     *
+     * @param from - Existing relative storage path.
+     * @param to - New relative storage path.
+     * @returns Promise that resolves once the move is complete.
+     */
+    move(from: string, to: string): Promise<void>;
+    /**
+     * Returns file size in bytes.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns File size in bytes.
+     */
+    size(path: string): Promise<number>;
+    /**
+     * Returns the last modification time for a file.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns File modification date.
+     */
+    lastModified(path: string): Promise<Date>;
+    /**
+     * Returns a best-effort MIME type for a file path.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns MIME type for the file extension.
+     */
+    mimeType(path: string): Promise<string>;
+    /**
+     * Returns a public URL for a path when the disk supports URLs.
+     *
+     * @param path - Relative storage path to expose.
+     * @returns Public URL.
+     */
+    url(path: string): Promise<string>;
+    /**
+     * Returns an absolute filesystem path when the disk is local.
+     *
+     * @param path - Relative storage path to resolve.
+     * @returns Absolute filesystem path.
+     */
+    path(path: string): string;
+}
+export interface LocalStorageDiskConfig {
+    driver: 'local';
+    root?: string;
+    url?: string;
+    visibility?: StorageVisibility;
+}
+export interface S3StorageDiskConfig {
+    driver: 's3';
+    bucket: string;
+    region?: string;
+    endpoint?: string;
+    prefix?: string;
+    url?: string;
+    forcePathStyle?: boolean;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    sessionToken?: string;
+    key?: string;
+    secret?: string;
+    visibility?: StorageVisibility;
+}
+export interface CustomStorageDiskConfig {
+    driver: string;
+    [key: string]: unknown;
+}
+export type StorageDiskConfig = LocalStorageDiskConfig | S3StorageDiskConfig | CustomStorageDiskConfig;
+export type StorageDiskFactory = (name: string, config: StorageDiskConfig) => StorageDisk;
+export interface StorageOptions {
+    default?: string;
+    disks?: Record<string, StorageDiskConfig | StorageDisk>;
+    drivers?: Record<string, StorageDiskFactory>;
+}

package/dist/storage/types.js

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

package/dist/url/UrlGenerator.d.ts

@@ -0,0 +1,32 @@
+import type * as url from './contracts/index.js';
+/**
+ * Canonical application URL generator.
+ *
+ * The generator is intentionally independent of a concrete server adapter and
+ * the current request. API, queue, scheduler, console, and future SSR runtimes
+ * can therefore share one trusted application origin. Request-specific SSR
+ * state belongs to the request context and must not replace this canonical URL.
+ *
+ * @example
+ * const callback = app().url.to('/api/integrations/provider/callback');
+ */
+export declare class UrlGenerator {
+    /** Normalized browser-facing application URL without a trailing slash. */
+    readonly baseUrl: string;
+    /**
+     * Creates the canonical application URL generator.
+     *
+     * @param options - Public deployment URL or local browser port configuration.
+     */
+    constructor(options?: url.UrlGeneratorOptions);
+    /**
+     * Builds an absolute application URL from a path or relative reference.
+     *
+     * @param path - Application path or relative URL to resolve.
+     * @returns Absolute browser-facing application URL.
+     *
+     * @example
+     * app().url.to('/auth/reset-password');
+     */
+    to(path: string): string;
+}

package/dist/url/UrlGenerator.js

@@ -0,0 +1,61 @@
+/**
+ * Canonical application URL generator.
+ *
+ * The generator is intentionally independent of a concrete server adapter and
+ * the current request. API, queue, scheduler, console, and future SSR runtimes
+ * can therefore share one trusted application origin. Request-specific SSR
+ * state belongs to the request context and must not replace this canonical URL.
+ *
+ * @example
+ * const callback = app().url.to('/api/integrations/provider/callback');
+ */
+export class UrlGenerator {
+    /** Normalized browser-facing application URL without a trailing slash. */
+    baseUrl;
+    /**
+     * Creates the canonical application URL generator.
+     *
+     * @param options - Public deployment URL or local browser port configuration.
+     */
+    constructor(options = {}) {
+        this.baseUrl = resolveBaseUrl(options);
+    }
+    /**
+     * Builds an absolute application URL from a path or relative reference.
+     *
+     * @param path - Application path or relative URL to resolve.
+     * @returns Absolute browser-facing application URL.
+     *
+     * @example
+     * app().url.to('/auth/reset-password');
+     */
+    to(path) {
+        return new URL(path, `${this.baseUrl}/`).toString();
+    }
+}
+/**
+ * Resolves and validates the one canonical application base URL.
+ *
+ * @param options - Explicit public URL or local browser port configuration.
+ * @returns Normalized HTTP(S) application base URL without a trailing slash.
+ */
+function resolveBaseUrl(options) {
+    const configured = options.baseUrl
+        || process.env.APP_URL
+        || process.env.PUBLIC_APP_URL;
+    if (configured) {
+        const normalized = configured.trim().replace(/\/+$/, '');
+        const parsed = new URL(normalized);
+        if (!['http:', 'https:'].includes(parsed.protocol)) {
+            throw new Error('Application base URL must use http or https.');
+        }
+        return normalized;
+    }
+    if (options.localPort !== undefined) {
+        if (!Number.isInteger(options.localPort) || options.localPort < 1 || options.localPort > 65_535) {
+            throw new Error('Application local port must be an integer between 1 and 65535.');
+        }
+        return `http://localhost:${options.localPort}`;
+    }
+    throw new Error('Application base URL is not configured. Set APP_URL or provide a local port.');
+}

package/dist/url/contracts/UrlGeneratorOptions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Canonical application URL configuration.
+ *
+ * The explicit public URL is authoritative in deployed environments. A local
+ * port can provide a browser-facing development origin without duplicating a
+ * complete application URL alongside the frontend server configuration.
+ */
+export interface UrlGeneratorOptions {
+    /** Public application base URL, such as `https://example.com`. */
+    baseUrl?: string;
+    /** Browser-facing localhost port used when no public base URL is configured. */
+    localPort?: number;
+}

package/dist/url/contracts/UrlGeneratorOptions.js

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

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

@@ -0,0 +1 @@
+export * from './UrlGeneratorOptions.js';

package/dist/url/contracts/index.js

@@ -0,0 +1 @@
+export * from './UrlGeneratorOptions.js';

package/dist/url/index.d.ts

@@ -0,0 +1,2 @@
+export * from './contracts/index.js';
+export * from './UrlGenerator.js';

package/dist/url/index.js

@@ -0,0 +1,2 @@
+export * from './contracts/index.js';
+export * from './UrlGenerator.js';

package/dist/validation/index.d.ts

@@ -0,0 +1,28 @@
+export type ValidationRuleName = 'required' | 'nullable' | 'string' | 'number' | 'integer' | 'boolean' | 'email' | 'url' | 'array' | 'object' | 'min' | 'max' | 'minLength' | 'maxLength' | 'in' | 'regex' | 'ulid' | 'uuid';
+export type ValidationRule = ValidationRuleName | `${ValidationRuleName}:${string}` | {
+    rule: ValidationRuleName;
+    value?: unknown;
+    values?: readonly unknown[];
+    pattern?: RegExp;
+    message?: string;
+};
+export type ValidationRules = Record<string, readonly ValidationRule[]>;
+export interface ValidationFailure {
+    field: string;
+    rule: ValidationRuleName;
+    message: string;
+    value?: unknown;
+    details?: Record<string, unknown>;
+}
+export interface ValidationResult<TData extends Record<string, unknown> = Record<string, unknown>> {
+    valid: boolean;
+    data: TData;
+    errors: ValidationFailure[];
+}
+export declare class ValidationException extends Error {
+    readonly errors: ValidationFailure[];
+    constructor(errors: ValidationFailure[]);
+}
+export declare function validate<TData extends Record<string, unknown> = Record<string, unknown>>(data: unknown, rules: ValidationRules): ValidationResult<TData>;
+export declare function assertValid<TData extends Record<string, unknown> = Record<string, unknown>>(data: unknown, rules: ValidationRules): TData;
+export declare function isEmail(value: unknown): boolean;

package/dist/validation/index.js

@@ -0,0 +1,260 @@
+import { isUlid } from '@db3.ai/pure/ulid';
+export class ValidationException extends Error {
+    errors;
+    constructor(errors) {
+        super('Validation failed');
+        this.errors = errors;
+        this.name = 'ValidationException';
+    }
+}
+export function validate(data, rules) {
+    const input = isPlainRecord(data) ? data : {};
+    const errors = [];
+    for (const [field, fieldRules] of Object.entries(rules)) {
+        const value = input[field];
+        const present = Object.prototype.hasOwnProperty.call(input, field);
+        const normalizedRules = fieldRules.map(normalizeRule);
+        const nullable = normalizedRules.some(rule => rule.name === 'nullable');
+        for (const rule of normalizedRules) {
+            if (rule.name === 'nullable')
+                continue;
+            if (rule.name === 'required') {
+                if (!present || isEmpty(value)) {
+                    errors.push(failure(field, rule, value));
+                }
+                continue;
+            }
+            if (!present || value === undefined || value === null || (nullable && value === '')) {
+                continue;
+            }
+            if (!passesRule(value, rule)) {
+                errors.push(failure(field, rule, value));
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        data: input,
+        errors,
+    };
+}
+export function assertValid(data, rules) {
+    const result = validate(data, rules);
+    if (!result.valid) {
+        throw new ValidationException(result.errors);
+    }
+    return result.data;
+}
+function normalizeRule(rule) {
+    if (typeof rule === 'object') {
+        return {
+            name: rule.rule,
+            value: rule.value,
+            values: rule.values,
+            pattern: rule.pattern,
+            message: rule.message,
+        };
+    }
+    const [name, ...parts] = rule.split(':');
+    const value = parts.join(':');
+    if (!isRuleName(name)) {
+        throw new Error(`Unknown validation rule "${name}"`);
+    }
+    if (name === 'regex') {
+        return {
+            name,
+            pattern: regexFromString(value),
+        };
+    }
+    if (name === 'in') {
+        return {
+            name,
+            values: value.split(',').map(item => item.trim()),
+        };
+    }
+    return {
+        name,
+        value: value === '' ? undefined : value,
+    };
+}
+function passesRule(value, rule) {
+    switch (rule.name) {
+        case 'required':
+        case 'nullable':
+            return true;
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+            return isNumberLike(value);
+        case 'integer':
+            return isIntegerLike(value);
+        case 'boolean':
+            return isBooleanLike(value);
+        case 'email':
+            return isEmail(value);
+        case 'url':
+            return isUrlLike(value);
+        case 'array':
+            return Array.isArray(value);
+        case 'object':
+            return isPlainRecord(value);
+        case 'min':
+            return compareSizedValue(value, rule.value, (actual, expected) => actual >= expected);
+        case 'max':
+            return compareSizedValue(value, rule.value, (actual, expected) => actual <= expected);
+        case 'minLength':
+            return compareLength(value, rule.value, (actual, expected) => actual >= expected);
+        case 'maxLength':
+            return compareLength(value, rule.value, (actual, expected) => actual <= expected);
+        case 'in':
+            return Boolean(rule.values?.some(item => Object.is(item, value) || String(item) === String(value)));
+        case 'regex':
+            return typeof value === 'string' && Boolean(rule.pattern?.test(value));
+        case 'ulid':
+            return isUlid(value);
+        case 'uuid':
+            return typeof value === 'string'
+                && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+    }
+}
+function failure(field, rule, value) {
+    return {
+        field,
+        rule: rule.name,
+        message: rule.message ?? defaultMessage(field, rule),
+        value,
+        details: detailsForRule(rule),
+    };
+}
+function defaultMessage(field, rule) {
+    switch (rule.name) {
+        case 'required':
+            return `${field} is required`;
+        case 'email':
+            return `${field} must be a valid email address`;
+        case 'url':
+            return `${field} must be a valid URL`;
+        case 'in':
+            return `${field} must be one of the allowed values`;
+        default:
+            return `${field} is invalid`;
+    }
+}
+function detailsForRule(rule) {
+    if (rule.value !== undefined) {
+        return { value: rule.value };
+    }
+    if (rule.values) {
+        return { values: rule.values };
+    }
+    if (rule.pattern) {
+        return { pattern: String(rule.pattern) };
+    }
+    return undefined;
+}
+function compareSizedValue(value, expectedInput, compare) {
+    const expected = numberFromUnknown(expectedInput);
+    if (expected === null)
+        return false;
+    const actual = numberFromUnknown(value);
+    if (actual !== null) {
+        return compare(actual, expected);
+    }
+    if (typeof value === 'string' || Array.isArray(value)) {
+        return compare(value.length, expected);
+    }
+    return false;
+}
+function compareLength(value, expectedInput, compare) {
+    const expected = numberFromUnknown(expectedInput);
+    if (expected === null)
+        return false;
+    if (typeof value === 'string' || Array.isArray(value)) {
+        return compare(value.length, expected);
+    }
+    return false;
+}
+function isNumberLike(value) {
+    return numberFromUnknown(value) !== null;
+}
+function isIntegerLike(value) {
+    const number = numberFromUnknown(value);
+    return number !== null && Number.isInteger(number);
+}
+function numberFromUnknown(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : null;
+    }
+    if (typeof value !== 'string' || !value.trim()) {
+        return null;
+    }
+    const number = Number(value.trim());
+    return Number.isFinite(number) ? number : null;
+}
+function isBooleanLike(value) {
+    if (typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return value === 0 || value === 1;
+    if (typeof value !== 'string')
+        return false;
+    return ['true', 'false', '1', '0', 'yes', 'no', 'on', 'off'].includes(value.trim().toLowerCase());
+}
+function isUrlLike(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return false;
+    const candidate = /^[a-z][a-z\d+.-]*:\/\//i.test(value)
+        ? value
+        : `https://${value}`;
+    try {
+        const url = new URL(candidate);
+        return ['http:', 'https:'].includes(url.protocol) && url.hostname.includes('.');
+    }
+    catch {
+        return false;
+    }
+}
+export function isEmail(value) {
+    const EMAIL_REGEX = /^[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+$/;
+    return typeof value === 'string'
+        && value.length <= 254
+        && EMAIL_REGEX.test(value);
+}
+function regexFromString(value) {
+    const match = value.match(/^\/(.*)\/([dgimsuvy]*)$/);
+    return match ? new RegExp(match[1], match[2]) : new RegExp(value);
+}
+function isPlainRecord(value) {
+    return typeof value === 'object'
+        && value !== null
+        && !Array.isArray(value)
+        && !(value instanceof Date);
+}
+function isEmpty(value) {
+    return value === null
+        || value === undefined
+        || value === ''
+        || (Array.isArray(value) && value.length === 0);
+}
+function isRuleName(value) {
+    return [
+        'required',
+        'nullable',
+        'string',
+        'number',
+        'integer',
+        'boolean',
+        'email',
+        'url',
+        'array',
+        'object',
+        'min',
+        'max',
+        'minLength',
+        'maxLength',
+        'in',
+        'regex',
+        'ulid',
+        'uuid',
+    ].includes(value);
+}