@mastra/core/dist/workspace/filesystem/composite-filesystem.d.ts

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

/**
 * CompositeFilesystem - Routes operations to mounted filesystems based on path.
 *
 * Creates a unified filesystem view by combining multiple filesystems at different
 * mount points. Useful for composing local storage, S3, and other backends.
 *
 * @example
 * ```typescript
 * const cfs = new CompositeFilesystem({
 *   mounts: {
 *     '/local': new LocalFilesystem({ basePath: './data' }),
 *     '/s3': new S3Filesystem({ bucket: 'my-bucket', ... }),
 *   }
 * });
 *
 * // readdir('/') returns ['local', 's3']
 * // readFile('/local/file.txt') reads from LocalFilesystem
 * // readFile('/s3/data.json') reads from S3Filesystem
 * ```
 */
import type { RequestContext } from '../../request-context/index.js';
import type { ProviderStatus } from '../lifecycle.js';
import type { WorkspaceFilesystem, FileContent, FileEntry, FileStat, FilesystemInfo, ReadOptions, WriteOptions, ListOptions, CopyOptions, RemoveOptions } from './filesystem.js';
/**
 * Configuration for CompositeFilesystem.
 */
export interface CompositeFilesystemConfig<TMounts extends Record<string, WorkspaceFilesystem> = Record<string, WorkspaceFilesystem>> {
    /** Map of mount paths to filesystem instances */
    mounts: TMounts;
}
/**
 * CompositeFilesystem implementation.
 *
 * Routes file operations to the appropriate underlying filesystem based on path.
 * Supports cross-mount operations (copy/move between different filesystems).
 *
 * The generic parameter preserves the concrete types of mounted filesystems,
 * enabling typed access via `mounts.get()`.
 *
 * @example
 * ```typescript
 * const cfs = new CompositeFilesystem({
 *   mounts: {
 *     '/local': new LocalFilesystem({ basePath: './data' }),
 *     '/s3': new S3Filesystem({ bucket: 'my-bucket' }),
 *   },
 * });
 *
 * cfs.mounts.get('/local') // LocalFilesystem
 * cfs.mounts.get('/s3')    // S3Filesystem
 * ```
 */
export declare class CompositeFilesystem<TMounts extends Record<string, WorkspaceFilesystem> = Record<string, WorkspaceFilesystem>> implements WorkspaceFilesystem {
    readonly id: string;
    readonly name = "CompositeFilesystem";
    readonly provider = "composite";
    readonly readOnly?: boolean;
    status: ProviderStatus;
    private readonly _mounts;
    constructor(config: CompositeFilesystemConfig<TMounts>);
    /**
     * Get all mount paths.
     */
    get mountPaths(): string[];
    /**
     * Get the mounts map.
     * Returns a typed map where `get()` preserves the concrete filesystem type per mount path.
     */
    get mounts(): ReadonlyMountMap<TMounts>;
    /**
     * Get status and metadata for this composite filesystem.
     * Includes info from each mounted filesystem in `metadata.mounts`.
     */
    getInfo(): Promise<FilesystemInfo>;
    /**
     * Get the underlying filesystem for a given path.
     * Returns undefined if the path doesn't resolve to any mount.
     */
    getFilesystemForPath(path: string): WorkspaceFilesystem | undefined;
    /**
     * Get the mount path for a given path.
     * Returns undefined if the path doesn't resolve to any mount.
     */
    getMountPathForPath(path: string): string | undefined;
    /**
     * Resolve a workspace-relative path to an absolute disk path.
     * Strips the mount prefix and delegates to the underlying filesystem.
     */
    resolveAbsolutePath(path: string): string | undefined;
    private normalizePath;
    private resolveMount;
    private getVirtualEntries;
    private isVirtualPath;
    /**
     * Assert that a filesystem is writable (not read-only).
     * @throws {PermissionError} if the filesystem is read-only
     */
    private assertWritable;
    init(): Promise<void>;
    destroy(): Promise<void>;
    readFile(path: string, options?: ReadOptions): Promise<string | Buffer>;
    writeFile(path: string, content: FileContent, options?: WriteOptions): Promise<void>;
    appendFile(path: string, content: FileContent): Promise<void>;
    deleteFile(path: string, options?: RemoveOptions): Promise<void>;
    copyFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
    moveFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
    readdir(path: string, options?: ListOptions): Promise<FileEntry[]>;
    mkdir(path: string, options?: {
        recursive?: boolean;
    }): Promise<void>;
    rmdir(path: string, options?: RemoveOptions): Promise<void>;
    exists(path: string): Promise<boolean>;
    stat(path: string): Promise<FileStat>;
    isFile(path: string): Promise<boolean>;
    isDirectory(path: string): Promise<boolean>;
    /**
     * Get instructions describing the mounted filesystems.
     * Used by agents to understand available storage locations.
     */
    getInstructions(_opts?: {
        requestContext?: RequestContext;
    }): string;
}
/**
 * Distributive mapped type that produces a union of correlated `[key, value]` tuples.
 *
 * For `{ '/local': LocalFilesystem, '/s3': S3Filesystem }` this yields:
 * `['/local', LocalFilesystem] | ['/s3', S3Filesystem]`
 *
 * This enables discriminated-union narrowing when iterating entries without destructuring:
 * ```typescript
 * for (const entry of mounts.entries()) {
 *   if (entry[0] === '/local') {
 *     entry[1] // LocalFilesystem
 *   }
 * }
 * ```
 */
export type MountMapEntry<TMounts extends Record<string, WorkspaceFilesystem>> = {
    [K in string & keyof TMounts]: [K, TMounts[K]];
}[string & keyof TMounts];
/**
 * A read-only view of mounted filesystems with typed per-key access.
 *
 * Unlike `ReadonlyMap<string, WorkspaceFilesystem>`, this preserves the
 * concrete filesystem type for each mount path via an overloaded `get()`.
 *
 * Iteration methods return correlated `[key, value]` tuples ({@link MountMapEntry})
 * so that checking `entry[0]` narrows `entry[1]` to the concrete filesystem type.
 *
 * @example
 * ```typescript
 * const mounts = cfs.mounts;
 * mounts.get('/local') // LocalFilesystem
 * mounts.get('/s3')    // S3Filesystem
 * ```
 */
export interface ReadonlyMountMap<TMounts extends Record<string, WorkspaceFilesystem>> {
    /** Get a mounted filesystem by path. Returns the concrete type for known mount paths. */
    get<K extends string & keyof TMounts>(key: K): TMounts[K];
    get(key: string): WorkspaceFilesystem | undefined;
    has(key: string): boolean;
    readonly size: number;
    keys(): IterableIterator<string & keyof TMounts>;
    values(): IterableIterator<TMounts[keyof TMounts & string]>;
    entries(): IterableIterator<MountMapEntry<TMounts>>;
    forEach(callbackfn: (value: TMounts[keyof TMounts & string], key: string & keyof TMounts, map: ReadonlyMountMap<TMounts>) => void): void;
    [Symbol.iterator](): IterableIterator<MountMapEntry<TMounts>>;
}
//# sourceMappingURL=composite-filesystem.d.ts.map