@sanity/export/dist/types.d.ts

Export Sanity documents and assets

import type { Writable } from 'node:stream';
/**
 * The mode to use when exporting documents.
 *
 * - `"stream"` mode uses a continuous stream of documents from the source and will
 *   give a consistent snapshot of the dataset at the time the export started, but
 *   will struggle with very large datasets.
 * - `"cursor"` mode uses paginated requests to fetch documents using a cursor, and
 *   will handle very large datasets better, but may give an inconsistent snapshot if
 *   the dataset is being modified during the export.
 *
 * @public
 */
export type ExportMode = 'stream' | 'cursor';
/**
 * Minimal representation of a Sanity document.
 *
 * @public
 */
export interface SanityDocument {
    _id: string;
    _type: string;
    _rev?: string;
    _createdAt?: string;
    _updatedAt?: string;
    [key: string]: unknown;
}
/**
 * @public
 */
export interface ExportProgress {
    /** Description of the current export step */
    step: string;
    /** Number of documents processed so far */
    current?: number;
    /** Total number of documents, if known - otherwise `?` */
    total?: number | '?';
    /** Set to `true` if the progress update is a repeat of a previous one but with new values */
    update?: boolean;
}
/**
 * @public
 */
export interface SanityClientLike {
    getUrl: (path: string) => string;
    config: () => {
        token?: string;
    };
}
/**
 * The options used to configure an export operation.
 *
 * @public
 */
export type ExportOptions = {
    /**
     * An instance of `@sanity/client`, configured with the project ID and authentication
     * token to be used for the export operation.
     */
    client: SanityClientLike;
    /**
     * Either a filesystem path to write the output `tar.gz` file to, or a writable stream
     */
    outputPath: string | Writable;
    /**
     * Whether or not to include asset files in the export
     */
    assets?: boolean;
    /**
     * Whether or not to export the documents "raw", meaning asset documents will be
     * included as-is, referencing asset file URLs in the source dataset and project ID or
     * media library ID. Also skips downloading assets. Generally this is only useful if
     * importing to the same source and you do not want to download the assets and
     * re-upload them to the same source.
     *
     * @note This will usually cause undesirable results if imported into another project
     * or media library!
     */
    raw?: boolean;
    /**
     * Whether or not to include draft documents in the export.
     */
    drafts?: boolean;
    /**
     * An array of document type names to include in the export. If not specified, all types
     * will be included.
     */
    types?: string[] | undefined;
    /**
     * How many asset downloads to perform concurrently. Must be between 1 and 24 if specified.
     */
    assetConcurrency?: number;
    /**
     * Maximum number of times to retry downloading a failed asset.
     *
     * @note Only certain errors are retried (like network errors and 5xx responses).
     */
    maxAssetRetries?: number;
    /**
     * Maximum number of times to retry fetching documents from the source.
     *
     * @note Only certain errors are retried (like network errors and 5xx responses).
     */
    maxRetries?: number;
    /**
     * Delay between retry attempts in milliseconds.
     */
    retryDelayMs?: number;
    /**
     * Timeout for read operations in milliseconds.
     */
    readTimeout?: number;
    /**
     * The mode to use when exporting documents, either `"stream"` or `"cursor"`.
     */
    mode?: ExportMode;
    /**
     * Whether or not to compress the output tarball (gzip). Note that the output will
     * still be a gzipped tarball even if this is set to `false`, setting it to `false`
     * only sets the gzip compression level to 0 (no compression).
     */
    compress?: boolean;
    /**
     * Whether or not to include an `assets.json` file in the export, mapping asset IDs to
     * their custom metadata (like original filename, etc).
     */
    assetsMap?: boolean;
    /**
     * Optional filter function to determine whether or not a document should be included
     * in the export. Note that this is run after any built-in document filtering such as
     * draft exclusion, document type filtering, etc.
     *
     * @param doc - The document to evaluate
     * @returns Whether or not to include the document in the export
     */
    filterDocument?: (doc: SanityDocument) => boolean;
    /**
     * Optional transform function to modify a document before it is included in the export.
     * Note that this is run post-filtering, and post asset document processing.
     *
     * @param doc - The document to transform
     * @returns The transformed document
     */
    transformDocument?: (doc: SanityDocument) => Partial<SanityDocument>;
    /**
     * Optional progress callback that will be called periodically during the export.
     *
     * @param progress - The current export progress
     */
    onProgress?: (progress: ExportProgress) => void;
} & ExportSource;
/**
 * The source of data to export, either a dataset name or a media library ID.
 *
 * @public
 */
export type ExportSource = {
    /**
     * The name of the dataset to export from.
     */
    dataset: string;
} | {
    /**
     * The ID of the media library to export from.
     */
    mediaLibraryId: string;
};
/**
 * @public
 */
export interface ExportResult<T = string | Writable> {
    /**
     * The filesystem path or writable stream that was passed as `options.outputPath`.
     */
    outputPath: T;
    /**
     * The number of documents exported.
     */
    documentCount: number;
    /**
     * The number of assets exported.
     */
    assetCount: number;
}
/**
 * @internal
 */
export type NormalizedExportOptions = ExportOptions & {
    assets: boolean;
    raw: boolean;
    drafts: boolean;
    maxAssetRetries: number;
    maxRetries: number;
    readTimeout: number;
    mode: ExportMode;
    compress: boolean;
    assetsMap: boolean;
    filterDocument: (doc: SanityDocument) => boolean;
    transformDocument: (doc: SanityDocument) => Partial<SanityDocument>;
};
/**
 * @internal
 */
export interface AssetMetadata {
    [key: string]: unknown;
}
/**
 * @internal
 */
export interface AssetMap {
    [assetId: string]: AssetMetadata;
}
/**
 * @internal
 */
export interface RequestStreamOptions {
    url: string;
    headers?: Record<string, string>;
    maxRetries?: number;
    retryDelayMs?: number;
    readTimeout?: number;
}
/**
 * @internal
 */
export interface ResponseStream extends NodeJS.ReadableStream {
    statusCode?: number;
    headers?: Record<string, string | string[] | undefined>;
}
/**
 * @internal
 */
export interface AssetDocument extends SanityDocument {
    _type: 'sanity.imageAsset' | 'sanity.fileAsset';
    url?: string;
    path?: string;
    assetId?: string;
    extension?: string;
    mimeType?: string;
}
//# sourceMappingURL=types.d.ts.map