@stackbit/utils/dist/field-path-utils.d.ts

Stackbit utilities

import type { Model, Field, FieldListItems, FieldPath, Document, DocumentWithSource, DocumentField, DocumentFieldNonLocalized, DocumentListFieldItems } from '@stackbit/types';
/**
 * Converts a FieldPath into a string.
 * Puts complex strings inside single quotes '',
 * and uses square brackets [] for number keys.
 */
export declare function fieldPathToString(fieldPath: FieldPath): string;
/**
 * Converts string into FieldPath
 *
 * ```js
 * stringToFieldPath("sections[0].button['button-label']")
 * =>
 * ["sections", 0, "button", "button-label"]
 * ```
 */
export declare function stringToFieldPath(fieldPath: string): FieldPath;
export declare function getModelFieldAtFieldPath({ document, fieldPath, modelMap, locale }: {
    document: Document;
    fieldPath: (string | number)[];
    modelMap: Record<string, Model>;
    locale?: string;
}): Field | FieldListItems;
export type GetDocumentFieldAtFieldPathOptions = {
    document: Document;
    fieldPath: FieldPath;
    locale?: string;
    isFullFieldPath?: boolean;
    returnUndefined?: boolean;
};
export type GetDocumentFieldAtFieldPathOptionsThrow = GetDocumentFieldAtFieldPathOptions & {
    returnUndefined?: false;
};
export type GetDocumentFieldAtFieldPathOptionsUndefined = GetDocumentFieldAtFieldPathOptions & {
    returnUndefined: true;
};
/**
 * This function receives a `document` and returns DocumentFieldNonLocalized at
 * the specified `fieldPath` while resolving any localized fields with the
 * specified `locale`.
 *
 * ```ts
 * getDocumentFieldAtFieldPath({
 *   document,
 *   locale,
 *   fieldPath: ['sections', 1, 'title']
 * })
 * ```
 *
 * For improved localization support, use the getModelAndDocumentFieldForLocalizedFieldPath
 * method instead.
 *
 * The `isFullFieldPath` flag specifies if the `fieldPath` includes container
 * specifiers such as "fields" and "items":
 *
 * ```ts
 * getDocumentFieldAtFieldPath({
 *   document,
 *   isFullFieldPath: false,
 *   fieldPath: ['sections', 1, 'title']
 * })
 * getDocumentFieldAtFieldPath({
 *   document,
 *   isFullFieldPath: true,
 *   fieldPath: ['fields', 'sections', 'items', 1, 'fields', 'title']
 * })
 * ```
 *
 * By default, if the document field at the specified `fieldPath` not found, this
 * function will throw exception. Setting `returnUndefined` to true will allow
 * the function to return `undefined` if the document field is not found.
 */
export declare function getDocumentFieldAtFieldPath(options: GetDocumentFieldAtFieldPathOptionsThrow): DocumentFieldNonLocalized;
export declare function getDocumentFieldAtFieldPath(options: GetDocumentFieldAtFieldPathOptionsUndefined): DocumentFieldNonLocalized | undefined;
/**
 * This function receives a `document` and a `modelMap` and returns an object
 * with DocumentFieldNonLocalized and a model Field at the specified `fieldPath`
 * while resolving any localized fields with the specified `locale`.
 *
 * @example
 * getDocumentAndModelFieldAtFieldPath({
 *   document,
 *   locale,
 *   modelMap,
 *   fieldPath: ['sections', 1, 'title']
 * })
 *
 * For improved localization support, use the getModelAndDocumentFieldForLocalizedFieldPath
 * method instead.
 *
 * The `isFullFieldPath` flag specifies if the `fieldPath` includes container
 * specifiers such as "fields" and "items".
 *
 * @example
 * isFullFieldPath: false => fieldPath: ['sections', 1, 'title']
 * isFullFieldPath: true => fieldPath: ['fields', 'sections', 'items', 1, 'fields', 'title']
 */
export declare function getDocumentAndModelFieldAtFieldPath({ document, fieldPath, modelMap, locale, isFullFieldPath }: {
    document: Document;
    fieldPath: (string | number)[];
    modelMap: Record<string, Model>;
    locale?: string;
    isFullFieldPath?: boolean;
}): {
    modelField: Field | FieldListItems;
    documentField: DocumentFieldNonLocalized;
};
/**
 * This function receives a `document` and a `modelMap` and returns an object
 * with DocumentField and a model Field at the specified `fieldPath`.
 *
 * If some fields along the fieldPath are localized, the `fieldPath` must
 * contain the locale of the field under the "locales" property. The locales
 * along the field path don't have to be the same.
 *
 * @example
 * fieldPath: ['fields', 'button', 'locales', 'en', 'fields', 'title', 'locales', 'es']
 *
 * If the provided `fieldPath` points to a list item, the returned model field
 * and document field will belong to a list item. In this case, the model field
 * will contain only field-specific properties and the document field will be
 * localized.
 *
 * @example
 * fieldPath: ['fields', 'buttons', 'items', 2]
 *
 * The `isFullFieldPath` flag specifies if the `fieldPath` includes container
 * specifiers such as "fields" and "items".
 *
 * @example
 * isFullFieldPath: false => fieldPath: ['sections', 1, 'title', 'es']
 * isFullFieldPath: true => fieldPath: ['fields', 'sections', 'items', 1, 'fields', 'title', 'locales', 'es']
 */
export declare function getModelAndDocumentFieldForLocalizedFieldPath({ document, fieldPath, modelMap, isFullFieldPath }: {
    document: Document;
    fieldPath: (string | number)[];
    modelMap: Record<string, Model>;
    isFullFieldPath?: boolean;
}): {
    modelField: Field | FieldListItems;
    documentField?: DocumentField | DocumentListFieldItems;
};
/**
 * This function returns the value of a field in the specified `document` at the
 * specified `fieldPath`.
 *
 * ```ts
 * getDocumentFieldValueAtFieldPath({
 *   document,
 *   fieldPath: 'sections[1].title'
 * })
 * ```
 *
 * The `fieldPath` can also contain locale specifiers for localized fields.
 *
 * ```ts
 * getDocumentFieldValueAtFieldPath({
 *   document,
 *   fieldPath: 'sections[1].title.es'
 * })
 * ```
 *
 * Note: getting a value of a localized field without using a locale specifier
 * will throw an exception.
 *
 * The `fieldPath` can be a string following the standard JavaScript notation
 * for getting nested properties and array values, or a {@link FieldPath}.
 *
 * If the document field at the specified `fieldPath` not found, undefined is returned.
 *
 * @param document The parent document
 * @param fieldPath The field path to the target field
 * @param getDocumentById A function
 * @param isFullFieldPath
 */
export declare function getDocumentFieldValueAtFieldPath({ document, fieldPath, getDocumentById, isFullFieldPath }: {
    document: DocumentWithSource;
    fieldPath: FieldPath | string;
    getDocumentById?: (options: {
        id: string;
        srcType?: string;
        srcProjectId?: string;
    }) => DocumentWithSource | undefined;
    isFullFieldPath?: boolean;
}): unknown;
//# sourceMappingURL=field-path-utils.d.ts.map