@jungvonmatt/sb-migrate/dist/src/utils/migration.d.ts

CLI tool for managing Storyblok schema and content migrations

import { IComponent, IComponentSchemaItem } from "../types/IComponent";
import { IStoryContent } from "../types/stories/IStoryContent";
import { IStory } from "../types/stories";
import { StringKeyOf } from "type-fest";
import { MigrationType } from "../types/migration";
import { Migration } from "../types/migration";
export type RunMigrationOptions = {
    isDryrun?: boolean;
    migrationPath?: string;
    publishLanguages?: string;
    publish?: "all" | "published" | "published-with-changes";
};
/**
 * @method isStoryPublishedWithoutChanges
 * @param  {Object} story
 * @return {Boolean}
 */
export declare const isStoryPublishedWithoutChanges: (story: IStory) => boolean;
/**
 * @method isStoryWithUnpublishedChanges
 * @param  {Object} story
 * @return {Boolean}
 */
export declare const isStoryWithUnpublishedChanges: (story: IStory) => boolean;
/**
 * @method MigrationFn
 * @param  {Object} blok
 * @return {void}
 */
export type MigrationFn = (blok: IStoryContent) => void;
/**
 * Executes a migration function on all stories containing a specific component.
 *
 * This function:
 * 1. Retrieves all stories containing the specified component
 * 2. Applies the migration function to each story's content
 * 3. Updates stories with changes and handles publishing based on options
 * 4. Creates rollback data for successful changes
 * 5. Tracks and reports statistics on the migration execution
 *
 * @param {string} component - The component name to migrate
 * @param {MigrationFn} migrationFn - Function that performs the actual content migration
 * @param {RunMigrationOptions} [options] - Optional configuration for the migration
 * @param {boolean} [options.isDryrun] - If true, only simulate changes without saving
 * @param {string} [options.migrationPath] - Path to the migration file
 * @param {string} [options.publishLanguages] - Languages to publish changes for
 * @param {"all"|"published"|"published-with-changes"} [options.publish] - Publishing strategy
 *
 * @returns {Promise<{executed: boolean, motive?: string}>} Result of the migration execution
 * @throws {Error} If migration function is missing or execution fails
 *
 * @example
 * ```ts
 * await runMigration('my-component', (content) => {
 *   content.title = 'New Title';
 * }, { publish: 'all' });
 * ```
 */
export declare const runMigration: (component: string, migrationFn: MigrationFn, options?: RunMigrationOptions) => Promise<{
    executed: boolean;
    motive?: string;
}>;
/**
 * @method showMigrationChanges
 * @param  {String} path      field name
 * @param  {unknown} value    updated value
 * @param  {unknown} oldValue previous value
 */
export declare const showMigrationChanges: (path: string, value: unknown, oldValue: unknown) => Promise<void>;
type Tabs<K extends string = string> = {
    general: K[];
    settings?: K[];
    form?: K[];
    disclaimer?: K[];
    confirmation?: K[];
    "Details Page"?: K[];
    tracking?: K[];
    deprecated?: string[];
};
export declare class Component {
    instance: IComponent;
    create(name: string): Promise<void>;
    load(name: string): Promise<void>;
    addOrUpdateFields<T extends Record<string, IComponentSchemaItem> = Record<string, IComponentSchemaItem>>(fields: T, tabConfig?: Tabs<StringKeyOf<T>>): void;
    getPos(fieldId: string): number | undefined;
    transformEntries(migrationFn: MigrationFn, options?: RunMigrationOptions): Promise<{
        executed: boolean;
        motive?: string;
    }>;
    save(): Promise<void>;
}
export declare const helper: {
    ensureDatasource: (ds: string | import("../types/IDataSource").IPendingDataSource, dsEntries: Omit<import("../types/IDataSource").IPendingDataSourceEntry, "datasource_id">[]) => Promise<[import("../types/IDataSource").IDataSource, import("../types/IDataSource").IDataSourceEntry[]]>;
    updateComponent(name: string): Promise<Component>;
};
/**
 * Define a type-safe migration object for Storyblok schema changes.
 * This helper function provides compile-time type checking for different migration types.
 *
 * @param migration A strongly-typed migration object that must match one of the following types:
 *                 - ComponentGroupMigration (create/update/delete component groups)
 *                 - ComponentMigration (create/update/delete components)
 *                 - DatasourceMigration (create/update/delete datasources)
 *                 - StoryMigration (create/update/delete stories)
 *                 - TransformEntriesMigration (bulk transform content entries)
 *
 * @returns The provided migration object without any transformation
 * @example
 * ```ts
 * const migration = defineMigration({
 *   type: 'create-component',
 *   name: 'my-component',
 *   component: {
 *     name: 'My Component',
 *     // ... component definition
 *   }
 * });
 * ```
 */
export declare function defineMigration<T extends MigrationType>(migration: Extract<Migration, {
    type: T;
}>): Extract<Migration, {
    type: T;
}>;
/**
 * Finds all migration files (.js and .ts) in the migrations directory and its subdirectories
 * @returns Array of relative paths to migration files
 */
export declare function findMigrations(): Promise<string[]>;
export {};