@db3.ai/app 0.1.0-beta.1

package/dist/storage/Storage.js

@@ -0,0 +1,348 @@
+import { LocalStorageDisk } from './drivers/LocalStorageDisk.js';
+import { S3StorageDisk } from './drivers/S3StorageDisk.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 class Storage {
+    options;
+    disks = new Map();
+    drivers = new Map();
+    /**
+     * Creates a storage manager with built-in local disk support.
+     *
+     * @param options - Storage defaults, disk definitions, and custom drivers.
+     */
+    constructor(options = {}) {
+        this.options = options;
+        this.drivers.set('local', (name, config) => {
+            return new LocalStorageDisk(name, config);
+        });
+        this.drivers.set('s3', (name, config) => {
+            return new S3StorageDisk(name, config);
+        });
+        for (const [driver, factory] of Object.entries(options.drivers ?? {})) {
+            this.drivers.set(driver, factory);
+        }
+    }
+    /**
+     * Returns the default disk name for this storage manager.
+     *
+     * @returns Configured default disk name.
+     */
+    get defaultDiskName() {
+        return this.options.default ?? 'local';
+    }
+    /**
+     * 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 = this.defaultDiskName) {
+        if (this.disks.has(name)) {
+            return this.disks.get(name);
+        }
+        const configured = this.resolveDiskConfig(name);
+        const disk = isStorageDisk(configured)
+            ? configured
+            : this.createDisk(name, configured);
+        this.disks.set(name, disk);
+        return disk;
+    }
+    /**
+     * 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 = this.defaultDiskName) {
+        return this.disk(name);
+    }
+    /**
+     * 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, disk) {
+        this.disks.set(name, disk);
+        return 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, factory) {
+        this.drivers.set(name, factory);
+        return 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, contents, options) {
+        return this.disk().write(path, contents, options);
+    }
+    /**
+     * 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, contents, options) {
+        return this.disk().put(path, contents, options);
+    }
+    /**
+     * 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, stream, options) {
+        return this.disk().writeStream(path, stream, options);
+    }
+    /**
+     * 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 = '', options = {}) {
+        return this.disk().list(path, options);
+    }
+    /**
+     * Reads file contents from the default disk.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Stored file bytes.
+     */
+    get(path) {
+        return this.disk().get(path);
+    }
+    /**
+     * 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) {
+        return this.disk().readToString(path);
+    }
+    /**
+     * 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) {
+        return this.disk().readToBuffer(path);
+    }
+    /**
+     * 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) {
+        return this.disk().readToUint8Array(path);
+    }
+    /**
+     * 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) {
+        return this.disk().read(path);
+    }
+    /**
+     * 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) {
+        return this.disk().readStream(path);
+    }
+    /**
+     * 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, encoding) {
+        return this.disk().getText(path, encoding);
+    }
+    /**
+     * Checks whether a file exists on the default disk.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns True when the file exists.
+     */
+    exists(path) {
+        return this.disk().exists(path);
+    }
+    /**
+     * 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) {
+        return this.disk().missing(path);
+    }
+    /**
+     * Deletes a file from the default disk.
+     *
+     * @param path - Relative storage path to delete.
+     * @returns True when a file was removed.
+     */
+    delete(path) {
+        return this.disk().delete(path);
+    }
+    /**
+     * 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, to) {
+        return this.disk().copy(from, to);
+    }
+    /**
+     * 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, to) {
+        return this.disk().move(from, to);
+    }
+    /**
+     * Returns file size from the default disk.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns File size in bytes.
+     */
+    size(path) {
+        return this.disk().size(path);
+    }
+    /**
+     * Returns the last modification time from the default disk.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns Last modified date.
+     */
+    lastModified(path) {
+        return this.disk().lastModified(path);
+    }
+    /**
+     * 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) {
+        return this.disk().mimeType(path);
+    }
+    /**
+     * Returns a public URL for a path on the default disk.
+     *
+     * @param path - Relative storage path to expose.
+     * @returns Public URL.
+     */
+    url(path) {
+        return this.disk().url(path);
+    }
+    /**
+     * 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) {
+        return this.disk().path(path);
+    }
+    /**
+     * Resolves configured disk options or the built-in local default.
+     *
+     * @param name - Disk name to resolve.
+     * @returns Disk config or concrete disk instance.
+     */
+    resolveDiskConfig(name) {
+        const configured = this.options.disks?.[name];
+        if (configured) {
+            return configured;
+        }
+        if (name === 'local') {
+            return {
+                driver: 'local',
+                root: 'storage/app',
+            };
+        }
+        throw new Error(`Storage disk "${name}" is not configured.`);
+    }
+    /**
+     * Creates a disk through the configured driver factory.
+     *
+     * @param name - Disk name being created.
+     * @param config - Disk configuration.
+     * @returns Storage disk instance.
+     */
+    createDisk(name, config) {
+        const factory = this.drivers.get(config.driver);
+        if (!factory) {
+            throw new Error(`Storage driver "${config.driver}" is not registered.`);
+        }
+        return factory(name, config);
+    }
+}
+/**
+ * Checks whether a configured disk value already implements the disk contract.
+ *
+ * @param value - Configured disk value.
+ * @returns True when value is a storage disk instance.
+ */
+function isStorageDisk(value) {
+    return typeof value === 'object'
+        && value !== null
+        && 'put' in value
+        && 'get' in value
+        && typeof value.put === 'function'
+        && typeof value.get === 'function';
+}

package/dist/storage/contents.d.ts

@@ -0,0 +1,8 @@
+import type { StorageContents } from './types.js';
+/**
+ * Converts supported storage input values into a Buffer for driver writes.
+ *
+ * @param contents - Text, Buffer, ArrayBuffer, or typed-array contents.
+ * @returns Buffer containing the file bytes.
+ */
+export declare function storageContentsToBuffer(contents: StorageContents): Buffer;

package/dist/storage/contents.js

@@ -0,0 +1,18 @@
+/**
+ * Converts supported storage input values into a Buffer for driver writes.
+ *
+ * @param contents - Text, Buffer, ArrayBuffer, or typed-array contents.
+ * @returns Buffer containing the file bytes.
+ */
+export function storageContentsToBuffer(contents) {
+    if (typeof contents === 'string') {
+        return Buffer.from(contents);
+    }
+    if (Buffer.isBuffer(contents)) {
+        return contents;
+    }
+    if (contents instanceof ArrayBuffer) {
+        return Buffer.from(contents);
+    }
+    return Buffer.from(contents.buffer, contents.byteOffset, contents.byteLength);
+}

package/dist/storage/contracts/StorageListing.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Controls how a storage directory is enumerated.
+ */
+export interface StorageListOptions {
+    /** Whether descendants below the immediate directory should be included. */
+    deep?: boolean;
+}
+/**
+ * Metadata shared by files and directories returned from storage listings.
+ */
+export interface StorageEntryBase {
+    /** Relative path within the selected storage disk. */
+    path: string;
+    /** Last modification time when the storage provider exposes it. */
+    lastModified?: Date;
+}
+/**
+ * File metadata returned from a storage directory listing.
+ */
+export interface StorageFileEntry extends StorageEntryBase {
+    type: 'file';
+    isFile: true;
+    isDirectory: false;
+    /** File size in bytes when the storage provider exposes it. */
+    size?: number;
+    /** Stored MIME type when the storage provider exposes it. */
+    mimeType?: string;
+}
+/**
+ * Directory metadata returned from a storage directory listing.
+ */
+export interface StorageDirectoryEntry extends StorageEntryBase {
+    type: 'directory';
+    isFile: false;
+    isDirectory: true;
+}
+/** One normalized file or directory returned from a storage listing. */
+export type StorageEntry = StorageFileEntry | StorageDirectoryEntry;
+/**
+ * Lazy directory listing that can be streamed or collected into an array.
+ */
+export interface StorageListing extends AsyncIterable<StorageEntry> {
+    /**
+     * Collects all remaining entries in this listing.
+     *
+     * @param sorted - Whether entries should be sorted by path.
+     * @returns Storage entries from this listing.
+     */
+    toArray(sorted?: boolean): Promise<StorageEntry[]>;
+}

package/dist/storage/contracts/StorageListing.js

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

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

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

package/dist/storage/contracts/index.js

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

package/dist/storage/drivers/FlystorageDisk.d.ts

@@ -0,0 +1,185 @@
+import type { FileStorage } from '@flystorage/file-storage';
+import type { Readable } from 'node:stream';
+import type { StorageListing, StorageListOptions } from '../contracts/index.js';
+import type { StorageContents, StorageDisk, StoragePutOptions } from '../types.js';
+/**
+ * Base storage disk for drivers backed by Flystorage.
+ */
+export declare class FlystorageDisk implements StorageDisk {
+    readonly name: string;
+    protected readonly storage: FileStorage;
+    /**
+     * Creates a Flystorage-backed disk wrapper.
+     *
+     * @param name - Configured disk name.
+     * @param storage - Flystorage instance used for disk operations.
+     */
+    constructor(name: string, storage: FileStorage);
+    /**
+     * Writes file contents to this disk.
+     *
+     * Alias for put(), useful when testing storage 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 reserved for compatible drivers.
+     * @returns Promise that resolves once the file is written.
+     */
+    write(path: string, contents: StorageContents, options?: StoragePutOptions): Promise<void>;
+    /**
+     * Writes file contents to this disk.
+     *
+     * @param path - Relative storage path to write.
+     * @param contents - Bytes or text content to persist.
+     * @param options - Optional write metadata reserved for compatible drivers.
+     * @returns Promise that resolves once the file is written.
+     */
+    put(path: string, contents: StorageContents, options?: StoragePutOptions): Promise<void>;
+    /**
+     * Writes streamed file contents to this disk.
+     *
+     * @param path - Relative storage path to write.
+     * @param stream - Readable stream containing file bytes.
+     * @param options - Optional write metadata reserved for compatible drivers.
+     * @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 a file from this disk as bytes.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Stored file bytes.
+     */
+    get(path: string): Promise<Buffer>;
+    /**
+     * Reads a file from this disk as text.
+     *
+     * Matches Flystorage's readToString() API.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Stored text content.
+     */
+    readToString(path: string): Promise<string>;
+    /**
+     * Reads a file from this disk as a Buffer.
+     *
+     * Matches Flystorage's readToBuffer() API.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Stored file bytes.
+     */
+    readToBuffer(path: string): Promise<Buffer>;
+    /**
+     * Reads a file from this disk as a Uint8Array.
+     *
+     * Matches Flystorage's readToUint8Array() API.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Stored file bytes.
+     */
+    readToUint8Array(path: string): Promise<Uint8Array>;
+    /**
+     * Reads a file from this disk as a stream.
+     *
+     * 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 a file from this disk as a stream.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Readable stream for the stored file.
+     */
+    readStream(path: string): Promise<Readable>;
+    /**
+     * Reads a file from this disk as text.
+     *
+     * @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 this 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 this 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 this disk.
+     *
+     * @param path - Relative storage path to delete.
+     * @returns True when a file was removed.
+     */
+    delete(path: string): Promise<boolean>;
+    /**
+     * Copies a file to another path on this 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 to another path on this 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 in bytes.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns File size in bytes.
+     */
+    size(path: string): Promise<number>;
+    /**
+     * Returns the last modification date for a file.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns Last modified date.
+     */
+    lastModified(path: string): Promise<Date>;
+    /**
+     * Returns a MIME type for a storage path.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns MIME type inferred from the file extension or storage metadata.
+     */
+    mimeType(path: string): Promise<string>;
+    /**
+     * Builds a public URL for this disk when supported by the driver.
+     *
+     * @param path - Relative storage path to expose.
+     * @returns Public URL for the storage path.
+     */
+    url(path: string): Promise<string>;
+    /**
+     * Reports that this disk is not backed by a local filesystem path.
+     *
+     * @param path - Relative storage path requested by the caller.
+     * @returns This method never returns for non-local disks.
+     */
+    path(path: string): string;
+}