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

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

/**
 * MastraFilesystem Base Class
 *
 * Abstract base class for filesystem providers that want automatic logger integration
 * and lifecycle management.
 *
 * Extends MastraBase to receive the Mastra logger when registered with a Mastra instance.
 *
 * ## Lifecycle Management
 *
 * The base class provides race-condition-safe lifecycle wrappers:
 * - `_init()` - Handles concurrent calls, status management
 * - `_destroy()` - Handles concurrent calls and status management
 *
 * Subclasses override the plain `init()` and `destroy()` methods to provide
 * their implementation. Callers use the `_`-prefixed wrappers (or `callLifecycle()`)
 * which add status tracking and race-condition safety.
 *
 * External providers can extend this class to get logger support, or implement
 * the WorkspaceFilesystem interface directly if they don't need logging.
 */
import { MastraBase } from '../../base.js';
import type { ProviderStatus } from '../lifecycle.js';
import type { WorkspaceFilesystem, FileContent, FileStat, FileEntry, ReadOptions, WriteOptions, ListOptions, RemoveOptions, CopyOptions } from './filesystem.js';
/**
 * Lifecycle hook that fires during filesystem state transitions.
 * Receives the filesystem instance so users can inspect state, log, etc.
 */
export type FilesystemLifecycleHook = (args: {
    filesystem: WorkspaceFilesystem;
}) => void | Promise<void>;
/**
 * Options for the MastraFilesystem base class constructor.
 * Providers extend this to add their own options while inheriting lifecycle hooks.
 */
export interface MastraFilesystemOptions {
    /** Called after the filesystem reaches 'ready' status */
    onInit?: FilesystemLifecycleHook;
    /** Called before the filesystem is destroyed */
    onDestroy?: FilesystemLifecycleHook;
}
/**
 * Abstract base class for filesystem providers with logger support and lifecycle management.
 *
 * Providers that extend this class automatically receive the Mastra logger
 * when the filesystem is used with a Mastra instance.
 *
 * @example
 * ```typescript
 * class MyCustomFilesystem extends MastraFilesystem {
 *   readonly id = 'my-fs';
 *   readonly name = 'MyCustomFilesystem';
 *   readonly provider = 'custom';
 *   status: ProviderStatus = 'pending';
 *
 *   constructor() {
 *     super({ name: 'MyCustomFilesystem' });
 *   }
 *
 *   // Override init() to provide initialization logic
 *   async init(): Promise<void> {
 *     // Your initialization logic here
 *   }
 *
 *   async readFile(path: string): Promise<string | Buffer> {
 *     await this.ensureReady();
 *     this.logger.debug('Reading file', { path });
 *     // Implementation...
 *   }
 *   // ... implement other WorkspaceFilesystem methods
 * }
 * ```
 */
export declare abstract class MastraFilesystem extends MastraBase implements WorkspaceFilesystem {
    /** Unique identifier for this filesystem instance */
    abstract readonly id: string;
    /** Human-readable name (e.g., 'LocalFilesystem', 'AgentFS') */
    abstract readonly name: string;
    /** Provider type identifier */
    abstract readonly provider: string;
    /** Current status of the filesystem */
    abstract status: ProviderStatus;
    /** Error message when status is 'error' */
    error?: string;
    /** Promise for _init() to prevent race conditions from concurrent calls */
    private _initPromise?;
    /** Promise for _destroy() to prevent race conditions from concurrent calls */
    private _destroyPromise?;
    /** Lifecycle callbacks */
    private readonly _onInit?;
    private readonly _onDestroy?;
    constructor(options: {
        name: string;
    } & MastraFilesystemOptions);
    /**
     * Initialize the filesystem (wrapper with status management and race-condition safety).
     *
     * This method is race-condition-safe - concurrent calls will return the same promise.
     * Handles status management automatically.
     *
     * Subclasses override `init()` to provide their initialization logic.
     */
    _init(): Promise<void>;
    /**
     * Internal init execution - handles status.
     */
    private _executeInit;
    /**
     * Override this method to implement filesystem initialization logic.
     *
     * Called by `_init()` after status is set to 'initializing'.
     * Status will be set to 'ready' on success, 'error' on failure.
     *
     * @example
     * ```typescript
     * async init(): Promise<void> {
     *   this._client = new StorageClient({ ... });
     *   await this._client.connect();
     * }
     * ```
     */
    init(): Promise<void>;
    /**
     * Ensure the filesystem is ready.
     *
     * Calls `_init()` if status is not 'ready'. Useful for lazy initialization
     * where operations should automatically initialize the filesystem if needed.
     *
     * @throws {FilesystemNotReadyError} if the filesystem fails to reach 'ready' status
     *
     * @example
     * ```typescript
     * async readFile(path: string): Promise<string | Buffer> {
     *   await this.ensureReady();
     *   // Now safe to use the filesystem
     * }
     * ```
     */
    protected ensureReady(): Promise<void>;
    /**
     * Destroy the filesystem and clean up all resources (wrapper with status management).
     *
     * This method is race-condition-safe - concurrent calls will return the same promise.
     * Handles status management.
     *
     * Subclasses override `destroy()` to provide their destroy logic.
     */
    _destroy(): Promise<void>;
    /**
     * Internal destroy execution - handles status.
     */
    private _executeDestroy;
    /**
     * Override this method to implement filesystem destroy logic.
     *
     * Called by `_destroy()` after status is set to 'destroying'.
     * Status will be set to 'destroyed' on success, 'error' on failure.
     */
    destroy(): Promise<void>;
    abstract readFile(path: string, options?: ReadOptions): Promise<string | Buffer>;
    abstract writeFile(path: string, content: FileContent, options?: WriteOptions): Promise<void>;
    abstract appendFile(path: string, content: FileContent): Promise<void>;
    abstract deleteFile(path: string, options?: RemoveOptions): Promise<void>;
    abstract copyFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
    abstract moveFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
    abstract mkdir(path: string, options?: {
        recursive?: boolean;
    }): Promise<void>;
    abstract rmdir(path: string, options?: RemoveOptions): Promise<void>;
    abstract readdir(path: string, options?: ListOptions): Promise<FileEntry[]>;
    abstract exists(path: string): Promise<boolean>;
    abstract stat(path: string): Promise<FileStat>;
}
//# sourceMappingURL=mastra-filesystem.d.ts.map