@mastra/core/dist/storage/filesystem-versioned.d.ts

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

import type { VersionBase, ListVersionsInputBase, ListVersionsOutputBase, VersionedEntityBase } from './domains/versioned.js';
import type { FilesystemDB } from './filesystem-db.js';
import type { StorageOrderBy } from './types.js';
/**
 * Configuration for a filesystem-backed versioned storage domain.
 */
export interface FilesystemVersionedConfig {
    /** The FilesystemDB instance for I/O */
    db: FilesystemDB;
    /** Filename for the entities JSON file (e.g., 'agents.json') */
    entitiesFile: string;
    /** The key name of the parent FK field on versions (e.g., 'agentId') */
    parentIdField: string;
    /** Name for logging/error messages */
    name: string;
    /**
     * Fields that are version metadata (not part of the snapshot config).
     * These are stripped when writing to disk.
     * e.g., ['id', 'agentId', 'versionNumber', 'changedFields', 'changeMessage', 'createdAt']
     */
    versionMetadataFields: string[];
    /** Maximum number of git commits to load per file (default: 50) */
    gitHistoryLimit?: number;
}
/**
 * Generic helpers for filesystem-backed versioned storage domains.
 *
 * Versions are kept entirely in memory. Only the published snapshot config
 * (the clean primitive configuration) is persisted to the on-disk JSON file.
 * This means the JSON files are human-readable, Git-friendly, and contain
 * no version metadata like `changedFields` or `changeMessage`.
 *
 * When the storage directory is inside a git repository, committed versions
 * of the JSON file are automatically loaded as read-only version history.
 * Each git commit that touched the file becomes a version record, giving
 * users a full published history in the version panel — powered by git.
 *
 * On-disk format for `agents.json`:
 * ```json
 * {
 *   "my-agent-id": {
 *     "name": "My Agent",
 *     "instructions": "Be helpful",
 *     "model": { "provider": "openai", "name": "gpt-4" }
 *   }
 * }
 * ```
 */
export declare class FilesystemVersionedHelpers<TEntity extends VersionedEntityBase & {
    createdAt: Date;
    updatedAt: Date;
    status: string;
}, TVersion extends VersionBase> {
    readonly db: FilesystemDB;
    readonly entitiesFile: string;
    readonly parentIdField: string;
    readonly name: string;
    readonly versionMetadataFields: string[];
    private readonly gitHistoryLimit;
    /**
     * In-memory entity records (thin metadata), keyed by entity ID.
     */
    private entities;
    /**
     * In-memory version records, keyed by version ID.
     * Includes both in-memory/hydrated versions and git-based versions (metadata only).
     */
    private versions;
    /**
     * Whether we've loaded from disk yet.
     */
    private hydrated;
    /**
     * Git history utility instance (shared across all helpers).
     */
    private static gitHistory;
    /**
     * Promise that resolves when git history has been loaded.
     * null means git history loading hasn't been triggered yet.
     */
    private gitHistoryPromise;
    /**
     * The highest version number from git history, per entity ID.
     * Used to assign version numbers to new in-memory versions that continue
     * after the git history.
     */
    private gitVersionCounts;
    constructor(config: FilesystemVersionedConfig);
    /**
     * Check if a version ID represents a git-based version.
     */
    static isGitVersion(id: string): boolean;
    /**
     * Hydrate in-memory state from the on-disk JSON file.
     * For each entry on disk, creates an in-memory entity (status: 'published')
     * and a synthetic version with the snapshot config.
     *
     * Also kicks off async git history loading in the background.
     * Version numbers for hydrated entities are assigned as 1 initially,
     * but will be reassigned after git history loads.
     */
    hydrate(): void;
    /**
     * Ensure git history has been loaded before proceeding.
     * Call this in version-related methods to ensure git versions are available.
     */
    private ensureGitHistory;
    /**
     * Load git commit history for the domain's JSON file.
     * Creates read-only version records (metadata + snapshot config) for each
     * commit where an entity existed. Reassigns version numbers for
     * hydrated (current disk) versions to sit on top of git history.
     */
    private loadGitHistory;
    /**
     * Write the published snapshot config for an entity to disk.
     * Strips all entity metadata and version metadata fields, leaving only
     * the clean primitive configuration.
     */
    private persistToDisk;
    /**
     * Extract the snapshot config from a version, stripping version metadata fields.
     */
    private extractSnapshotConfig;
    getById(id: string): Promise<TEntity | null>;
    createEntity(id: string, entity: TEntity): Promise<TEntity>;
    updateEntity(id: string, updates: Record<string, unknown>): Promise<TEntity>;
    deleteEntity(id: string): Promise<void>;
    listEntities(args: {
        page?: number;
        perPage?: number | false;
        orderBy?: StorageOrderBy;
        filters?: Record<string, unknown>;
        listKey: string;
    }): Promise<Record<string, unknown>>;
    createVersion(input: TVersion): Promise<TVersion>;
    getVersion(id: string): Promise<TVersion | null>;
    getVersionByNumber(entityId: string, versionNumber: number): Promise<TVersion | null>;
    getLatestVersion(entityId: string): Promise<TVersion | null>;
    listVersions(input: ListVersionsInputBase, parentIdField: string): Promise<ListVersionsOutputBase<TVersion>>;
    deleteVersion(id: string): Promise<void>;
    deleteVersionsByParentId(entityId: string): Promise<void>;
    countVersions(entityId: string): Promise<number>;
    getNextVersionNumber(entityId: string): Promise<number>;
    private _getNextVersionNumber;
    dangerouslyClearAll(): Promise<void>;
}
//# sourceMappingURL=filesystem-versioned.d.ts.map