@quenk/preconditions/lib/index.d.ts

Make data satisfy constraints before using.

import { Object, Value } from '@quenk/noni/lib/data/jsonx';
import { Type } from '@quenk/noni/lib/data/type';
import { Result } from './result';
/**
 * Precondition represents some condition that must be satisfied
 * in order for data to be considered a valid type.
 *
 * A Precondition accepts a value of type <A> and returns an Either
 * where the left side contains information about why the precondition
 * failed or the right the resulting type and value.
 */
export type Precondition<A, B> = (value: A) => Result<A, B>;
/**
 * A map of key precondition pairs.
 */
export interface Preconditions<A, B> {
    [key: string]: Precondition<A, B>;
}
/**
 * constant forces the value to be the supplied value.
 */
export declare const constant: <A, B>(b: B) => Precondition<A, B>;
export { constant as const };
/**
 * when conditionally applies one of two preconditions depending
 * on the outcome of a test function.
 */
export declare const when: <A, B>(test: (a: A) => boolean, applied: Precondition<A, B>, otherwise: Precondition<A, B>) => Precondition<A, B>;
/**
 * whenTrue conditionally applies "applied" or "otherwise" depending
 * on whether "condition" is true or not.
 */
export declare const whenTrue: <A, B>(condition: boolean, applied: Precondition<A, B>, otherwise: Precondition<A, B>) => Precondition<A, B>;
/**
 * whenFalse (opposite of whenTrue).
 */
export declare const whenFalse: <A, B>(condition: boolean, applied: Precondition<A, B>, otherwise: Precondition<A, B>) => Precondition<A, B>;
/**
 * eq tests if the value is equal (strictly) to the target.
 */
export declare const eq: <A, B>(target: B) => Precondition<A, B>;
/**
 * neq tests if the value is not equal (strictly) to the target.
 */
export declare const neq: <A, B>(target: B) => Precondition<A, B>;
/**
 * notNull will fail if the value is null or undefined.
 */
export declare const notNull: <A>(value: A) => Result<A, A>;
/**
 * optional applies the precondition given only if the value is not null
 * or undefined.
 */
export declare const optional: <A, B>(p: Precondition<A, A | B>) => Precondition<A, A | B>;
/**
 * defaultValue assigns a default value if the value to the precondition is
 * nullable.
 */
export declare const defaultValue: <A>(fallback: A) => Precondition<A, A>;
export { defaultValue as default };
/**
 * identity always succeeds with the value it is applied to.
 */
export declare const identity: <A>(value: A) => Result<A, A>;
/**
 * discard throws away a value by assigning it ot undefined.
 */
export declare const discard: <A>(_: A) => Result<A, undefined>;
/**
 * reject always fails with reason no matter the value supplied.
 */
export declare const reject: <A, B>(reason: string) => Precondition<A, B>;
/**
 * or performs the equivalent of a logical 'or' between two preconditions.
 */
export declare const or: <A, B>(left: Precondition<A, B>, right: Precondition<A, B>) => Precondition<A, B>;
/**
 * and performs the equivalent of a logical 'and' between two preconditions.
 */
export declare const and: <A, B, C>(l: Precondition<A, B>, r: Precondition<B, C>) => Precondition<A, C>;
/**
 * every takes a set of preconditions and attempts to apply each
 * one after the other to the input.
 */
export declare const every: <A, B>(p: Precondition<A, B>, ...list: Precondition<B, B>[]) => Precondition<A, B>;
/**
 * anyOf applies all of the preconditions provided until one succeeds.
 */
export declare const anyOf: <A, B>(...list: Precondition<A, B>[]) => Precondition<A, B>;
/**
 * exists requires the value to be enumerated in the supplied list.
 */
export declare const exists: <A>(list: A[]) => Precondition<A, A>;
/**
 * isin requires the value passed to be a member of a provided list.
 */
export declare const isin: <A>(list: A[]) => Precondition<A, A>;
export { isin as enum };
/**
 * match preforms a type/structure matching on the input
 * value in order to decide which precondition to apply.
 *
 * Preconditions must be wrapped in a 'caseOf' precondition.
 */
export declare const match: <A, B>(p: Precondition<A, B>, ...list: Precondition<A, B>[]) => Precondition<A, B>;
/**
 * caseOf allows for the selective application of a precondition
 * based on the type or structure of the value.
 *
 * Pattern matching works as follows:
 * string -> Matches on the value of the string.
 * number -> Matches on the value of the number.
 * boolean -> Matches on the value of the boolean.
 * object -> Each key of the object is matched on the value, all must match.
 * function -> Treated as a constructor and results in an instanceof check.
 *             For String,Number and Boolean, this uses the typeof check.
 */
export declare const caseOf: <A, B>(t: Type, p: Precondition<A, B>) => Precondition<A, B>;
/**
 * log the value to the console.
 */
export declare const log: <A>(value: A) => Result<A, A>;
/**
 * JSTypeString corresponds to one of the basic JS types.
 */
export type JSTypeString = 'object' | 'array' | 'string' | 'boolean' | 'number';
/**
 * typeOf tests whether the value has the specified type.
 */
export declare function typeOf<A>(type: 'object'): Precondition<A, Object>;
export declare function typeOf<A>(type: 'array'): Precondition<A, Value[]>;
export declare function typeOf<A>(type: 'string'): Precondition<A, string>;
export declare function typeOf<A>(type: 'boolean'): Precondition<A, boolean>;
export declare function typeOf<A>(type: 'number'): Precondition<A, number>;
export { typeOf as type };
/**
 * cast a value into a jsonx primitive value indicated by the "type".
 */
export declare function cast<A>(type: 'object'): Precondition<A, Object>;
export declare function cast<A>(type: 'array'): Precondition<A, Value[]>;
export declare function cast<A>(type: 'string'): Precondition<A, string>;
export declare function cast<A>(type: 'number'): Precondition<A, number>;
export declare function cast<A>(type: 'boolean'): Precondition<A, boolean>;
/**
 * tee applies each of the provided preconditions to a single value.
 *
 * This results in a list of values each corresponding to a value in the array
 * upon success. This precondition fails on the first failed precondition
 * encountered.
 */
export declare const tee: <A, B>(precs: Precondition<A, B>[]) => Precondition<A, B[]>;