@db3.ai/app 0.1.0-beta.1

package/dist/storage/drivers/FlystorageDisk.js

@@ -0,0 +1,250 @@
+import { storageContentsToBuffer } from '../contents.js';
+import { mimeTypeFromPath } from '../mime.js';
+import { normalizeStorageDirectoryPath, normalizeStoragePath } from '../path.js';
+import { FlystorageListing } from './FlystorageListing.js';
+/**
+ * Base storage disk for drivers backed by Flystorage.
+ */
+export class FlystorageDisk {
+    name;
+    storage;
+    /**
+     * Creates a Flystorage-backed disk wrapper.
+     *
+     * @param name - Configured disk name.
+     * @param storage - Flystorage instance used for disk operations.
+     */
+    constructor(name, storage) {
+        this.name = name;
+        this.storage = storage;
+    }
+    /**
+     * 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, contents, options = {}) {
+        return this.put(path, contents, options);
+    }
+    /**
+     * 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.
+     */
+    async put(path, contents, options = {}) {
+        await this.storage.write(normalizeStoragePath(path), storageContentsToBuffer(contents), {
+            mimeType: options.mimeType,
+            visibility: options.visibility,
+        });
+    }
+    /**
+     * 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.
+     */
+    async writeStream(path, stream, options = {}) {
+        await this.storage.write(normalizeStoragePath(path), stream, {
+            mimeType: options.mimeType,
+            visibility: options.visibility,
+        });
+    }
+    /**
+     * 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 = '', options = {}) {
+        return new FlystorageListing(this.storage.list(normalizeStorageDirectoryPath(path), {
+            deep: options.deep ?? false,
+        }));
+    }
+    /**
+     * Reads a file from this disk as bytes.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Stored file bytes.
+     */
+    async get(path) {
+        return this.readToBuffer(path);
+    }
+    /**
+     * Reads a file from this disk as text.
+     *
+     * Matches Flystorage's readToString() API.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Stored text content.
+     */
+    async readToString(path) {
+        return this.storage.readToString(normalizeStoragePath(path));
+    }
+    /**
+     * 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.
+     */
+    async readToBuffer(path) {
+        return this.storage.readToBuffer(normalizeStoragePath(path));
+    }
+    /**
+     * 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.
+     */
+    async readToUint8Array(path) {
+        return this.storage.readToUint8Array(normalizeStoragePath(path));
+    }
+    /**
+     * 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.
+     */
+    async read(path) {
+        return this.storage.read(normalizeStoragePath(path));
+    }
+    /**
+     * Reads a file from this disk as a stream.
+     *
+     * @param path - Relative storage path to read.
+     * @returns Readable stream for the stored file.
+     */
+    async readStream(path) {
+        return this.read(path);
+    }
+    /**
+     * 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.
+     */
+    async getText(path, encoding = 'utf8') {
+        return (await this.readToBuffer(path)).toString(encoding);
+    }
+    /**
+     * Checks whether a file exists on this disk.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns True when the file exists.
+     */
+    async exists(path) {
+        return this.storage.fileExists(normalizeStoragePath(path));
+    }
+    /**
+     * Checks whether a file is missing from this disk.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns True when the file does not exist.
+     */
+    async missing(path) {
+        return !(await this.exists(path));
+    }
+    /**
+     * Deletes a file from this disk.
+     *
+     * @param path - Relative storage path to delete.
+     * @returns True when a file was removed.
+     */
+    async delete(path) {
+        const normalized = normalizeStoragePath(path);
+        const exists = await this.storage.fileExists(normalized);
+        await this.storage.deleteFile(normalized);
+        return exists;
+    }
+    /**
+     * 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.
+     */
+    async copy(from, to) {
+        await this.storage.copyFile(normalizeStoragePath(from), normalizeStoragePath(to));
+    }
+    /**
+     * 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.
+     */
+    async move(from, to) {
+        await this.storage.moveFile(normalizeStoragePath(from), normalizeStoragePath(to));
+    }
+    /**
+     * Returns file size in bytes.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns File size in bytes.
+     */
+    async size(path) {
+        return this.storage.fileSize(normalizeStoragePath(path));
+    }
+    /**
+     * Returns the last modification date for a file.
+     *
+     * @param path - Relative storage path to inspect.
+     * @returns Last modified date.
+     */
+    async lastModified(path) {
+        return new Date(await this.storage.lastModified(normalizeStoragePath(path)));
+    }
+    /**
+     * 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.
+     */
+    async mimeType(path) {
+        const normalized = normalizeStoragePath(path);
+        try {
+            return await this.storage.mimeType(normalized, {
+                fallbackMethod: 'path',
+            });
+        }
+        catch {
+            return mimeTypeFromPath(normalized);
+        }
+    }
+    /**
+     * 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.
+     */
+    async url(path) {
+        return this.storage.publicUrl(normalizeStoragePath(path));
+    }
+    /**
+     * 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) {
+        normalizeStoragePath(path);
+        throw new Error(`Storage disk "${this.name}" does not expose local filesystem paths.`);
+    }
+}

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

@@ -0,0 +1,27 @@
+import type { StatEntry } from '@flystorage/file-storage';
+import type { StorageEntry, StorageListing } from '../contracts/index.js';
+/**
+ * Normalizes a Flystorage directory listing behind Platform's storage contract.
+ */
+export declare class FlystorageListing implements StorageListing {
+    private readonly listing;
+    /**
+     * Creates a Platform listing over a Flystorage stat-entry source.
+     *
+     * @param listing - Lazy Flystorage directory entries.
+     */
+    constructor(listing: AsyncIterable<StatEntry>);
+    /**
+     * Collects all remaining entries from the underlying listing.
+     *
+     * @param sorted - Whether entries should be sorted by path.
+     * @returns Normalized storage entries.
+     */
+    toArray(sorted?: boolean): Promise<StorageEntry[]>;
+    /**
+     * Streams normalized storage entries from the underlying listing.
+     *
+     * @returns Async generator of normalized storage entries.
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<StorageEntry>;
+}

package/dist/storage/drivers/FlystorageListing.js

@@ -0,0 +1,69 @@
+/**
+ * Normalizes a Flystorage directory listing behind Platform's storage contract.
+ */
+export class FlystorageListing {
+    listing;
+    /**
+     * Creates a Platform listing over a Flystorage stat-entry source.
+     *
+     * @param listing - Lazy Flystorage directory entries.
+     */
+    constructor(listing) {
+        this.listing = listing;
+    }
+    /**
+     * Collects all remaining entries from the underlying listing.
+     *
+     * @param sorted - Whether entries should be sorted by path.
+     * @returns Normalized storage entries.
+     */
+    async toArray(sorted = true) {
+        const entries = [];
+        for await (const entry of this) {
+            entries.push(entry);
+        }
+        if (sorted) {
+            entries.sort((left, right) => left.path.localeCompare(right.path));
+        }
+        return entries;
+    }
+    /**
+     * Streams normalized storage entries from the underlying listing.
+     *
+     * @returns Async generator of normalized storage entries.
+     */
+    async *[Symbol.asyncIterator]() {
+        for await (const entry of this.listing) {
+            yield storageEntry(entry);
+        }
+    }
+}
+/**
+ * Converts one Flystorage stat entry into Platform's provider-neutral shape.
+ *
+ * @param entry - Flystorage file or directory metadata.
+ * @returns Normalized Platform storage entry.
+ */
+function storageEntry(entry) {
+    const lastModified = entry.lastModifiedMs === undefined
+        ? undefined
+        : new Date(entry.lastModifiedMs);
+    if (entry.type === 'file') {
+        return {
+            type: 'file',
+            isFile: true,
+            isDirectory: false,
+            path: entry.path,
+            lastModified,
+            size: entry.size,
+            mimeType: entry.mimeType,
+        };
+    }
+    return {
+        type: 'directory',
+        isFile: false,
+        isDirectory: true,
+        path: entry.path,
+        lastModified,
+    };
+}

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

@@ -0,0 +1,25 @@
+import type { LocalStorageDiskConfig } from '../types.js';
+import { FlystorageDisk } from './FlystorageDisk.js';
+/**
+ * Local filesystem storage disk.
+ *
+ * Paths are always relative to the configured disk root. The disk rejects empty,
+ * absolute, and parent-directory paths before touching the filesystem.
+ */
+export declare class LocalStorageDisk extends FlystorageDisk {
+    private readonly root;
+    /**
+     * Creates a local disk backed by Flystorage's local filesystem adapter.
+     *
+     * @param name - Configured disk name.
+     * @param config - Local disk configuration.
+     */
+    constructor(name: string, config?: LocalStorageDiskConfig);
+    /**
+     * Returns the absolute local filesystem path for a storage path.
+     *
+     * @param path - Relative storage path to resolve.
+     * @returns Absolute filesystem path inside the disk root.
+     */
+    path(path: string): string;
+}

package/dist/storage/drivers/LocalStorageDisk.js

@@ -0,0 +1,38 @@
+import { FileStorage } from '@flystorage/file-storage';
+import { LocalStorageAdapter } from '@flystorage/local-fs';
+import { resolve } from 'node:path';
+import { resolveLocalStoragePath } from '../path.js';
+import { FlystorageDisk } from './FlystorageDisk.js';
+/**
+ * Local filesystem storage disk.
+ *
+ * Paths are always relative to the configured disk root. The disk rejects empty,
+ * absolute, and parent-directory paths before touching the filesystem.
+ */
+export class LocalStorageDisk extends FlystorageDisk {
+    root;
+    /**
+     * Creates a local disk backed by Flystorage's local filesystem adapter.
+     *
+     * @param name - Configured disk name.
+     * @param config - Local disk configuration.
+     */
+    constructor(name, config = { driver: 'local' }) {
+        const root = resolve(config.root ?? 'storage/app');
+        super(name, new FileStorage(new LocalStorageAdapter(root, {
+            publicUrlOptions: {
+                baseUrl: config.url?.replace(/\/+$/, ''),
+            },
+        })));
+        this.root = root;
+    }
+    /**
+     * Returns the absolute local filesystem path for a storage path.
+     *
+     * @param path - Relative storage path to resolve.
+     * @returns Absolute filesystem path inside the disk root.
+     */
+    path(path) {
+        return resolveLocalStoragePath(this.root, path);
+    }
+}

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

@@ -0,0 +1,17 @@
+import type { S3StorageDiskConfig } from '../types.js';
+import { FlystorageDisk } from './FlystorageDisk.js';
+/**
+ * S3-compatible object storage disk.
+ *
+ * This driver supports AWS S3 plus providers that implement the S3 protocol,
+ * such as DigitalOcean Spaces, by using a custom endpoint.
+ */
+export declare class S3StorageDisk extends FlystorageDisk {
+    /**
+     * Creates an S3-compatible disk backed by Flystorage's AWS S3 adapter.
+     *
+     * @param name - Configured disk name.
+     * @param config - S3 disk configuration.
+     */
+    constructor(name: string, config: S3StorageDiskConfig);
+}

package/dist/storage/drivers/S3StorageDisk.js

@@ -0,0 +1,102 @@
+import { S3Client } from '@aws-sdk/client-s3';
+import { AwsS3StorageAdapter } from '@flystorage/aws-s3';
+import { FileStorage } from '@flystorage/file-storage';
+import { FlystorageDisk } from './FlystorageDisk.js';
+/**
+ * S3-compatible object storage disk.
+ *
+ * This driver supports AWS S3 plus providers that implement the S3 protocol,
+ * such as DigitalOcean Spaces, by using a custom endpoint.
+ */
+export class S3StorageDisk extends FlystorageDisk {
+    /**
+     * Creates an S3-compatible disk backed by Flystorage's AWS S3 adapter.
+     *
+     * @param name - Configured disk name.
+     * @param config - S3 disk configuration.
+     */
+    constructor(name, config) {
+        const bucket = requiredS3Option(config.bucket, 'bucket');
+        const client = new S3Client(s3ClientConfig(config));
+        super(name, new FileStorage(new AwsS3StorageAdapter(client, {
+            bucket,
+            prefix: trimSlashes(config.prefix),
+            region: config.region,
+            publicUrlOptions: {
+                baseUrl: publicUrlBase(config.url),
+                forcePathStyle: config.forcePathStyle,
+                region: config.region,
+            },
+        })));
+    }
+}
+/**
+ * Builds AWS SDK S3 client config from a storage disk config.
+ *
+ * @param config - S3 disk configuration.
+ * @returns AWS SDK S3 client config.
+ */
+function s3ClientConfig(config) {
+    return {
+        region: config.region ?? 'us-east-1',
+        endpoint: config.endpoint,
+        forcePathStyle: config.forcePathStyle,
+        credentials: credentials(config),
+    };
+}
+/**
+ * Resolves optional static S3 credentials from disk config.
+ *
+ * @param config - S3 disk configuration.
+ * @returns AWS SDK credentials or undefined for default provider resolution.
+ */
+function credentials(config) {
+    const accessKeyId = config.accessKeyId ?? config.key;
+    const secretAccessKey = config.secretAccessKey ?? config.secret;
+    if (!accessKeyId && !secretAccessKey)
+        return undefined;
+    if (!accessKeyId || !secretAccessKey) {
+        throw new Error('S3 storage disk requires both accessKeyId and secretAccessKey when either credential is configured.');
+    }
+    return {
+        accessKeyId,
+        secretAccessKey,
+        sessionToken: config.sessionToken,
+    };
+}
+/**
+ * Returns a required S3 string option.
+ *
+ * @param value - Option value.
+ * @param name - Option name used in error messages.
+ * @returns Required non-empty string.
+ */
+function requiredS3Option(value, name) {
+    if (!value?.trim()) {
+        throw new Error(`S3 storage disk requires a ${name}.`);
+    }
+    return value;
+}
+/**
+ * Removes leading and trailing slashes from a configured prefix.
+ *
+ * @param value - Prefix value to normalize.
+ * @returns Normalized prefix or undefined.
+ */
+function trimSlashes(value) {
+    const normalized = value?.replace(/^\/+|\/+$/g, '');
+    return normalized ? normalized : undefined;
+}
+/**
+ * Converts a configured public base URL into Flystorage's URL template shape.
+ *
+ * @param value - Configured public URL or template.
+ * @returns URL template with a path placeholder.
+ */
+function publicUrlBase(value) {
+    if (!value)
+        return undefined;
+    if (value.includes('{uri}'))
+        return value;
+    return `${value.replace(/\/+$/, '')}/{uri}`;
+}

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

@@ -0,0 +1,3 @@
+export * from './FlystorageDisk.js';
+export * from './LocalStorageDisk.js';
+export * from './S3StorageDisk.js';

package/dist/storage/drivers/index.js

@@ -0,0 +1,3 @@
+export * from './FlystorageDisk.js';
+export * from './LocalStorageDisk.js';
+export * from './S3StorageDisk.js';

package/dist/storage/index.d.ts

@@ -0,0 +1,7 @@
+export * from './Storage.js';
+export * from './contents.js';
+export * from './contracts/index.js';
+export * from './drivers/index.js';
+export * from './mime.js';
+export * from './path.js';
+export * from './types.js';

package/dist/storage/index.js

@@ -0,0 +1,7 @@
+export * from './Storage.js';
+export * from './contents.js';
+export * from './contracts/index.js';
+export * from './drivers/index.js';
+export * from './mime.js';
+export * from './path.js';
+export * from './types.js';

package/dist/storage/mime.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns a best-effort MIME type from a file path.
+ *
+ * @param path - File path or storage path with an extension.
+ * @returns MIME type for known extensions, or application/octet-stream.
+ */
+export declare function mimeTypeFromPath(path: string): string;

package/dist/storage/mime.js

@@ -0,0 +1,28 @@
+import { extname } from 'node:path';
+const mimeTypes = {
+    '.avif': 'image/avif',
+    '.css': 'text/css',
+    '.csv': 'text/csv',
+    '.gif': 'image/gif',
+    '.html': 'text/html',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.js': 'text/javascript',
+    '.json': 'application/json',
+    '.md': 'text/markdown',
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.txt': 'text/plain',
+    '.webp': 'image/webp',
+    '.xml': 'application/xml',
+};
+/**
+ * Returns a best-effort MIME type from a file path.
+ *
+ * @param path - File path or storage path with an extension.
+ * @returns MIME type for known extensions, or application/octet-stream.
+ */
+export function mimeTypeFromPath(path) {
+    return mimeTypes[extname(path).toLowerCase()] ?? 'application/octet-stream';
+}

package/dist/storage/path.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Normalizes a caller-provided storage path into a safe relative path.
+ *
+ * @param path - User or application supplied storage path.
+ * @returns Normalized relative storage path using forward slashes.
+ */
+export declare function normalizeStoragePath(path: string): string;
+/**
+ * Normalizes a storage directory path while allowing the disk root.
+ *
+ * @param path - User or application supplied directory path.
+ * @returns Normalized relative directory path, or an empty string for the root.
+ */
+export declare function normalizeStorageDirectoryPath(path?: string): string;
+/**
+ * Resolves a normalized storage path against a local disk root.
+ *
+ * @param root - Absolute or process-relative disk root.
+ * @param path - Storage path to resolve.
+ * @returns Absolute filesystem path inside the disk root.
+ */
+export declare function resolveLocalStoragePath(root: string, path: string): string;

package/dist/storage/path.js

@@ -0,0 +1,61 @@
+import { isAbsolute, resolve, sep } from 'node:path';
+import { posix } from 'node:path';
+/**
+ * Normalizes a caller-provided storage path into a safe relative path.
+ *
+ * @param path - User or application supplied storage path.
+ * @returns Normalized relative storage path using forward slashes.
+ */
+export function normalizeStoragePath(path) {
+    if (typeof path !== 'string') {
+        throw new Error('Storage path must be a string.');
+    }
+    if (path.includes('\0')) {
+        throw new Error('Storage path cannot contain null bytes.');
+    }
+    const input = path.trim().replace(/\\/g, '/');
+    if (!input) {
+        throw new Error('Storage path cannot be empty.');
+    }
+    if (input.startsWith('/') || isAbsolute(input)) {
+        throw new Error(`Storage path "${path}" must be relative.`);
+    }
+    if (/^[A-Za-z]:\//.test(input)) {
+        throw new Error(`Storage path "${path}" must be relative.`);
+    }
+    const normalized = posix.normalize(input);
+    if (normalized === '.' || normalized === '..' || normalized.startsWith('../')) {
+        throw new Error(`Storage path "${path}" cannot leave the storage disk root.`);
+    }
+    return normalized;
+}
+/**
+ * Normalizes a storage directory path while allowing the disk root.
+ *
+ * @param path - User or application supplied directory path.
+ * @returns Normalized relative directory path, or an empty string for the root.
+ */
+export function normalizeStorageDirectoryPath(path = '') {
+    if (typeof path !== 'string') {
+        throw new Error('Storage path must be a string.');
+    }
+    const input = path.trim().replace(/\\/g, '/');
+    if (input === '' || input === '.')
+        return '';
+    return normalizeStoragePath(input);
+}
+/**
+ * Resolves a normalized storage path against a local disk root.
+ *
+ * @param root - Absolute or process-relative disk root.
+ * @param path - Storage path to resolve.
+ * @returns Absolute filesystem path inside the disk root.
+ */
+export function resolveLocalStoragePath(root, path) {
+    const normalizedRoot = resolve(root);
+    const resolved = resolve(normalizedRoot, normalizeStoragePath(path));
+    if (resolved !== normalizedRoot && !resolved.startsWith(`${normalizedRoot}${sep}`)) {
+        throw new Error(`Storage path "${path}" cannot leave the storage disk root.`);
+    }
+    return resolved;
+}