@mastra/core/dist/storage/domains/versioned.d.ts

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

import type { StorageOrderBy, ThreadOrderBy, ThreadSortDirection } from '../types.js';
import { StorageDomain } from './base.js';
/**
 * Options for resolving which version of an entity to use.
 * Either pick by status (draft/published/archived) or by a specific version ID — not both.
 */
export type VersionResolutionOptions = {
    status?: 'draft' | 'published' | 'archived';
    versionId?: never;
} | {
    versionId: string;
    status?: never;
};
/**
 * Base interface for version metadata fields that exist on every version row.
 * The `TFkField` parameter controls the name of the foreign key field.
 */
export interface VersionBase {
    /** UUID identifier for this version */
    id: string;
    /** Sequential version number (1, 2, 3, ...) */
    versionNumber: number;
    /** Array of field names that changed from the previous version */
    changedFields?: string[];
    /** Optional message describing the changes */
    changeMessage?: string;
    /** When this version was created */
    createdAt: Date;
}
/**
 * Base interface for version creation input.
 * Same as VersionBase but without the server-assigned `createdAt` timestamp.
 */
export interface CreateVersionInputBase extends Omit<VersionBase, 'createdAt'> {
}
/**
 * Sort direction for version listings.
 */
export type VersionSortDirectionGeneric = ThreadSortDirection;
/**
 * Fields that can be used for ordering version listings.
 */
export type VersionOrderByGeneric = 'versionNumber' | 'createdAt';
/**
 * Input for listing versions with pagination and sorting.
 */
export interface ListVersionsInputBase {
    /** Page number (0-indexed) */
    page?: number;
    /**
     * Number of items per page, or `false` to fetch all records without pagination limit.
     * Defaults to 20 if not specified.
     */
    perPage?: number | false;
    /** Sorting options */
    orderBy?: {
        field?: VersionOrderByGeneric;
        direction?: VersionSortDirectionGeneric;
    };
}
/**
 * Output for listing versions with pagination info.
 */
export interface ListVersionsOutputBase<TVersion> {
    /** Array of versions for the current page */
    versions: TVersion[];
    /** Total number of versions */
    total: number;
    /** Current page number */
    page: number;
    /** Items per page */
    perPage: number | false;
    /** Whether there are more pages */
    hasMore: boolean;
}
export interface VersionedEntityBase {
    id: string;
    activeVersionId?: string;
}
/**
 * Generic base class for versioned storage domains (agents, prompt blocks, scorer definitions).
 *
 * Type parameters:
 * - `TEntity`       — Thin record type (e.g. StorageAgentType)
 * - `TSnapshot`     — Snapshot config type (e.g. StorageAgentSnapshotType)
 * - `TResolved`     — Entity + snapshot merged (e.g. StorageResolvedAgentType)
 * - `TVersion`      — Version row (e.g. AgentVersion)
 * - `TCreateVersion` — Input for creating a version
 * - `TListVersionsInput` — Input for listing versions
 * - `TListVersionsOutput` — Output for listing versions
 * - `TCreateInput`  — Input for creating an entity
 * - `TUpdateInput`  — Input for updating an entity
 * - `TListInput`    — Input for listing entities
 * - `TListOutput`   — Output for listing entities (paginated thin records)
 * - `TListResolvedOutput` — Output for listing resolved entities
 */
export declare abstract class VersionedStorageDomain<TEntity extends VersionedEntityBase, TSnapshot, TResolved extends TEntity, TVersion extends VersionBase, TCreateVersion extends CreateVersionInputBase, TListVersionsInput extends ListVersionsInputBase, TListVersionsOutput extends ListVersionsOutputBase<TVersion>, TCreateInput, TUpdateInput, TListInput, TListOutput, TListResolvedOutput> extends StorageDomain {
    /**
     * The key name used in list outputs (e.g. 'agents', 'promptBlocks', 'scorerDefinitions').
     * Subclasses must provide this so the generic resolution logic can build the correct output shape.
     */
    protected abstract readonly listKey: string;
    /**
     * The set of version metadata field names (including the FK field) to strip
     * when extracting snapshot config from a version row.
     * e.g. ['id', 'agentId', 'versionNumber', 'changedFields', 'changeMessage', 'createdAt']
     */
    protected abstract readonly versionMetadataFields: string[];
    abstract getById(id: string): Promise<TEntity | null>;
    abstract create(input: TCreateInput): Promise<TEntity>;
    abstract update(input: TUpdateInput): Promise<TEntity>;
    abstract delete(id: string): Promise<void>;
    abstract list(args?: TListInput): Promise<TListOutput>;
    abstract createVersion(input: TCreateVersion): Promise<TVersion>;
    abstract getVersion(id: string): Promise<TVersion | null>;
    abstract getVersionByNumber(entityId: string, versionNumber: number): Promise<TVersion | null>;
    abstract getLatestVersion(entityId: string): Promise<TVersion | null>;
    abstract listVersions(input: TListVersionsInput): Promise<TListVersionsOutput>;
    abstract deleteVersion(id: string): Promise<void>;
    abstract deleteVersionsByParentId(entityId: string): Promise<void>;
    abstract countVersions(entityId: string): Promise<number>;
    /**
     * Strips version metadata fields from a version row, leaving only snapshot config fields.
     */
    protected extractSnapshotConfig(version: TVersion): Partial<TSnapshot>;
    /**
     * Resolves an entity by merging its thin record with the active or latest version config.
     * - `{ status: 'draft' }` — resolve with the latest version.
     * - `{ status: 'published' }` (default) — resolve with the active version, falling back to latest.
     * - `{ versionId: '...' }` — resolve with a specific version by ID.
     */
    getByIdResolved(id: string, options?: VersionResolutionOptions): Promise<TResolved | null>;
    /**
     * Lists entities with version resolution.
     * When `status` is `'draft'`, each entity is resolved with its latest version.
     * When `status` is `'published'` (default), each entity is resolved with its active version.
     */
    listResolved(args?: TListInput): Promise<TListResolvedOutput>;
    /**
     * Resolves a single entity by merging it with its active or latest version.
     * - `{ versionId: '...' }` — resolve with a specific version by ID.
     * - `{ status: 'published' }` (default) — use activeVersionId, fall back to latest.
     * - `{ status: 'draft' }` — always use the latest version.
     */
    protected resolveEntity(entity: TEntity, options?: VersionResolutionOptions): Promise<TResolved>;
    protected parseOrderBy(orderBy?: StorageOrderBy, defaultDirection?: ThreadSortDirection): {
        field: ThreadOrderBy;
        direction: ThreadSortDirection;
    };
    protected parseVersionOrderBy(orderBy?: TListVersionsInput['orderBy'], defaultDirection?: VersionSortDirectionGeneric): {
        field: VersionOrderByGeneric;
        direction: VersionSortDirectionGeneric;
    };
}
//# sourceMappingURL=versioned.d.ts.map