pure-parse/dist/parsers/ParseResult.d.ts

Strongly typed validation library that decouples type aliases from validation logic

/**
 * The data adheres to the schema. The `value` is equal to the parsed data
 */
export type ParseSuccess<T> = {
    tag: 'success';
    value: T;
    error?: never;
};
/**
 * The parsing failed.
 */
export type ParseFailure = {
    tag: 'failure';
    error: Failure;
};
export type Failure = {
    message: string;
    path: PathSegment[];
};
/**
 * Describes the path in a data structure where parsing failed.
 */
export type PathSegment = {
    tag: 'object';
    key: string;
} | {
    tag: 'array';
    index: number;
};
/**
 * Describes the result of a parsing operation.
 * The `tag` and `error` properties can be used to distinguish between success and failure.
 * @example
 * Use `error` to distinguish between success and failure:
 * ```ts
 * const result = parseNumber(data)
 * if(result.error) {
 *   console.error(formatResult(result))
 *   return
 * }
 * console.log(result.value)
 * ```
 * @example
 * Use `tag` to distinguish between success and failure:
 * ```ts
 * const result = parseNumber(data)
 * switch (result.tag) {
 *   case 'failure':
 *    console.error(formatResult(result))
 *    break
 *   case 'success':
 *    console.log(result.value)
 *    break
 */
export type ParseResult<T> = ParseSuccess<T> | ParseFailure;
/**
 * *****************************
 * Utilities
 * *****************************
 */
/**
 * Create a successful parsing result.
 * @example
 * ```ts
 * const customParser: Parser<number> = (data) => {
 *   if (typeof data === 'number') {
 *    return success(data)
 *   }
 *   return failure('Expected a number')
 * }
 * @param value
 */
export declare const success: <T>(value: T) => ParseSuccess<T>;
/**
 * Create a failure parsing result.
 * @example
 * ```ts
 * const customParser: Parser<number> = (data) => {
 *   if (typeof data === 'number') {
 *    return success(data)
 *   }
 *   return failure('Expected a number')
 * }
 * ```
 * @param message
 */
export declare const failure: (message: string) => ParseFailure;
/**
 * Check if the result is a success
 * @param result
 */
export declare const isSuccess: <T>(result: ParseResult<T>) => result is ParseSuccess<T>;
/**
 * Check if the result is a failure
 * @param result
 */
export declare const isFailure: <T>(result: ParseResult<T>) => result is ParseFailure;
/**
 * Propagate a failure result in a nested structure.
 * When parsing objects and arrays with nested values, the failure at the root level should convey where in the hierarchy the failure occurred.
 * @param failureRes
 * @param pathSegment
 */
export declare const propagateFailure: (failureRes: ParseFailure, pathSegment: PathSegment) => ParseFailure;