# Storage API reference

> Current emitted signatures and options for @db3.ai/app/storage.

- Package: `@db3.ai/app/storage`
- Canonical page: [https://db3.ai/docs/storage-api](https://db3.ai/docs/storage-api)
- Markdown: [https://db3.ai/docs/storage-api.md](https://db3.ai/docs/storage-api.md)
- Framework source of truth: `packages/app/src/storage/README.md`

<a id="start"></a>

## Imports and examples

Import supported APIs from `@db3.ai/app/storage`. These signatures come from the staged package used by consumers. Relative filenames in declarations describe type dependencies; they are not extra supported deep imports.

Use the guide for setup, executable examples, failure handling and ownership. A signature is not proof that every deployment or provider has been exercised.

- [Guide, examples and testing](https://db3.ai/docs/storage.md)

<a id="manager"></a>

## Manager and disk configuration

### Manager and disk configuration

````typescript
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;
}
````

<a id="disk"></a>

## Disk operations and values

### Disk operations and values

```typescript
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>;
}
```

<a id="listing"></a>

## Lazy listings

### Lazy listings

```typescript
/**
 * 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[]>;
}
```

<a id="paths"></a>

## Path validation

### Path validation

```typescript
/**
 * 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;
```

<a id="contents"></a>

## Content conversion

### Content conversion

```typescript
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;
```

<a id="mime"></a>

## MIME helpers

### MIME helpers

```typescript
/**
 * 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;
```

## Related documentation
- [Storage](https://db3.ai/docs/storage.md): Write files to a named disk, stream large payloads and keep paths relative to storage. Add Media when files need durable identities and ownership metadata.

## Guidance for AI tools
Use the documented public import `@db3.ai/app/storage` and its exported types. Prefer the source-backed examples and behavioural outcomes above over invented APIs or source-relative internal imports.