inferred-types 0.37.0 → 0.37.2

package/dist/index.d.ts

@@ -0,0 +1,2745 @@
+type ApiFunction<P extends any[], R extends any> = (...args: P) => R;
+type FluentFunction<P extends any[], R extends any> = (...args: P) => R;
+type ApiValue<V extends any> = V;
+/**
+ * Expresses the API in a structured manner while making distinction
+ * between a function endpoint and a _fluent_ function endpoint.
+ */
+type Api<T extends object> = {
+    [K in keyof T]: T[K] extends (...args: any) => T ? FluentFunction<Parameters<T[K]>, ReturnType<T[K]>> : T[K] extends (...args: any) => any ? ApiFunction<Parameters<T[K]>, ReturnType<T[K]>> : ApiValue<T[K]>;
+};
+
+/**
+ * Define a class constructor; allowing strong typing for constructor's parameters
+ * and the returned class structure.
+ */
+type Constructor<Ctor extends any[], Klass extends any> = new (...props: Ctor) => Klass;
+
+/**
+ * Provides the values of an Typescript **enum**:
+ * ```ts
+ * enum Foo { foo, bar, baz };
+ * // "0" | "1" | "2"
+ * type NumerericEnum = EnumValues<Foo>;
+ * enum Bar { foo = "foey", bar = "barred" };
+ * // "foey" | "barred"
+ * type StringEnum = EnumValues<Bar>;
+ * ```
+ *
+ * **Note:** combine with `Numeric` to get number based indexes
+ */
+type EnumValues<T extends string | number> = `${T}`;
+
+/**
+ * Recursively goes over an object based structure and tries to reduce
+ * it down to just a simple key/value type.
+ */
+type ExpandRecursively<T> = T extends object ? T extends (...args: any[]) => any ? T : {
+    [K in keyof T]: ExpandRecursively<T[K]>;
+} : T;
+
+/**
+ * Returns the first values type in an array of values
+ */
+type First<T extends readonly any[]> = T[0] extends T[number] ? T[0] : never;
+type FirstOrUndefined<T extends unknown> = T extends [unknown, ...[unknown]] ? First<T> : undefined;
+
+/**
+ * **FunctionType**
+ *
+ * Provides a way to correctly match for regular functions _and_ functions which
+ * also have a dictionary hash alongside the root function.
+ *
+ * - without the generic `T` specified it simply matches correctly on both plain functions as well as functions which also have properties on them (this is consistent to how runtime's `typeof` operator works)
+ * - with the generic you can specify the shape of the key/values
+ */
+type FunctionType<T extends {} = {}> = {} extends T ? Function | (Function & {
+    [key: string]: any;
+}) : Function | (Function & T);
+/**
+ * **FnShape**
+ *
+ * Simple way to express the shape of a function's arguments and return type.
+ */
+type FnShape<A extends any[] = any[], R extends any = any> = (...args: A) => R;
+
+/**
+ * Provides a unary condition for the type system:
+ * ```ts
+ * // "a"
+ * type T = If<true, "a", "b'>;
+ * // "b"
+ * type F = If<false, "a", "b">;
+ * ```
+ */
+type If<C extends boolean, T, F> = C extends T ? C | F : never;
+
+/**
+ * **Include<T, U, L>**
+ *
+ * _Allows_ any value `T` which extends `U` otherwise sets type to `never`. Normally, you'll just ignore
+ * the `L` generic but if need the comparison to be literal you can set to `true`:
+ *
+ * ```ts
+ * const foo: "foo" = "foo";
+ * // "foo"
+ * type Normal = Include<typeof foo, string>;
+ * // L1 is never, L2 is "foo"
+ * type L1 = Include<typeof foo, string, true>;
+ * type L2 = Include<typeof foo, "foo", true>;
+ * ```
+ */
+type Include<T, U, L extends boolean = false> = L extends true ? T extends U ? U extends T ? T : never : never : T extends U ? T : never;
+
+/**
+ * A "KeyedRecord" is intended to store a value without
+ * losing any ability to infer type information later.
+ *
+ * The structure is always represented as a two-key
+ * dictionary, where one key is always `__key` and the value
+ * of this key points to the second key.
+ *
+ * For example:
+ * ```ts
+ * const song: KeyedRecord = { __key: "song", song: XXX }
+ * ```
+ */
+type KeyedRecord<K extends string, V extends any, T extends {
+    __key: K;
+} = {
+    __key: K;
+}, U extends keyof T = keyof T & K> = {
+    [X in U]: T[X];
+} & {
+    K: V;
+};
+
+/**
+ * A Utility class that provides the same functionality as the built-in
+ * `keyof` TS operator but can also:
+ *
+ * - receive an array of strings and convert that into a union type.
+ * - you can exclude literal string from the returned result
+ *
+ * ```ts
+ * const t1 = { foo: 1, bar: 2 };
+ * // "foo" | "bar"
+ * type K = Keys<typeof t1>;
+ * const t2 = ["foo", "bar"] as const;
+ * // "foo" | "bar"
+ * type K = Keys<typeof t2>;
+ * ```
+ */
+type Keys<T extends Record<string, any> | readonly string[], W extends string | undefined = undefined> = T extends readonly string[] ? W extends string ? Exclude<T[number], W> : T[number] : W extends string ? Exclude<keyof T & string, W> : keyof T & string;
+
+/**
+ * Utility type which returns the length of an array literal
+ *
+ * ```ts
+ * type Three = Length<[ "a", "b", "c" ]>;
+ * ```
+ */
+type Length<T extends readonly any[]> = T["length"];
+
+/**
+ * **Equal**`<X,Y>`
+ *
+ * Type utility which tests whether two types -- `X` and `Y` -- are exactly the same type
+ */
+type IsEqual<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+/**
+ * **NotEqual**`<X,Y>`
+ *
+ * Type utility which tests whether two types -- `X` and `Y` -- are _not_ exactly the same type
+ */
+type NotEqual<X, Y> = true extends IsEqual<X, Y> ? false : true;
+
+/**
+ * **AfterFirst**`<T>`
+ *
+ * returns the elements in an array _after_ the first element
+ */
+type AfterFirst<T extends readonly any[]> = T extends readonly [any, ...any[]] ? T extends readonly [any, ...infer Rest] ? Rest : never : T;
+
+/**
+ * returns the first `string` value from an array of values
+ */
+type FirstString<T> = T extends [infer S extends string, ...unknown[]] ? S : never;
+
+/**
+ * **FilterTuple**
+ *
+ * Allows a known tuple `T` to be _filtered down_ by eliminating all items
+ * in the Tuple that _extend_ type `F`
+ * ```ts
+ * type T = [1,"foo",3];
+ * // [1,3]
+ * type T2 = FilterTuple<T, string>;
+ * ```
+ */
+type FilterTuple<TTuple extends any[] | readonly any[], TFilter, Result extends any[] = []> = TTuple extends [infer A, ...infer R] ? [A] extends [TFilter] ? FilterTuple<R, TFilter, Result> : FilterTuple<R, TFilter, [...Result, A]> : Result;
+
+/**
+ * **Split**`<T, SEP>`
+ *
+ * Splits a string literal `T` by string literal _separator_ `SEP`. The result is an array
+ * of string literals.
+ */
+type Split<T extends string, SEP extends string, ANSWER extends string[] = []> = string extends T ? string[] : T extends SEP ? ANSWER : T extends `${infer HEAD}${SEP}${infer TAIL}` ? Split<TAIL, SEP, [...ANSWER, HEAD]> : [...ANSWER, T];
+
+/**
+ * Get the type of a property of an object:
+ * ```ts
+ * const car = { make: "Chevy", model: "Malibu", }
+ * ```
+ */
+type Get<T, K> = K extends `${infer FK}.${infer L}` ? FK extends keyof T ? Get<T[FK], L> : never : K extends keyof T ? T[K] : never;
+
+/**
+ * A union of types used in conjunction with the `literalValues()` function
+ * to produce a _narrow_ type definition of a passed in dictionary object.
+ */
+type Narrowable = string | number | boolean | symbol | object | undefined | void | null | {};
+
+/**
+ * Create a union type based on a given property in an array of objects
+ * ```ts
+ * const data = [
+ *    { id: 123, color: "blue" },
+ *    { id: 456, color: "red" },
+ *  ] as const;
+ * // 123 | 456
+ * type U = UniqueForProp<typeof data, "id">;
+ * ```
+ */
+type UniqueForProp<T extends readonly Record<string, Narrowable>[], P extends string> = Readonly<Get<T[number], P>>;
+
+type IsArray<T> = [T] extends [any[]] ? true : [T] extends [readonly any[]] ? true : false;
+type IsReadonlyArray<T> = T extends readonly any[] ? true : false;
+/**
+ * **IfArray**`<T, IF, ELSE>`
+ *
+ * Type utility which convert to type `IF` or `ELSE` based on whether `T` is an array
+ */
+type IfArray<T extends Narrowable, IF extends Narrowable, ELSE extends Narrowable> = IsArray<T> extends true ? IF : ELSE;
+/**
+ * **IfArray**`<T, IF, ELSE>`
+ *
+ * Type utility which convert to type `IF` or `ELSE` based on whether `T` is a readonly array
+ */
+type IfReadonlyArray<T extends Narrowable, IF extends Narrowable, ELSE extends Narrowable> = IsReadonlyArray<T> extends true ? IF : ELSE;
+/**
+ * **Contains**`<T, A>`
+ *
+ * Type utility which checks whether a type `T` exists within an array `A`. Result is
+ * `true` if `T` _extends_ any element in `A` making it match widely against `A`. If you
+ * prefer a narrower match you can use `NarrowlyContains<T,A>` instead.
+ */
+type Contains<T extends Narrowable, A extends readonly any[]> = First<A> extends T ? true : [] extends AfterFirst<A> ? false : Contains<T, AfterFirst<A>>;
+/**
+ * **NarrowlyContains**`<T, A>`
+ *
+ * Type utility which checks whether a type `T` exists within an array `A`. Result is
+ * `true` if `T` _extends_ any element in `A` making it match widely against `A`. If you
+ * prefer a wider match you can use `Contains<T,A>` instead.
+ */
+type NarrowlyContains<T extends Narrowable, A extends readonly any[]> = IsEqual<First<A>, T> extends true ? true : [] extends AfterFirst<A> ? false : NarrowlyContains<T, AfterFirst<A>>;
+
+/**
+ * Converts a Tuple type into a _union_ of the tuple elements
+ * ```ts
+ * const arr = [1, 3, 5] as const;
+ * // 1 | 3 | 5
+ * type U = TupleToUnion<typeof arr>;
+ * ```
+ */
+type TupleToUnion<T> = T extends readonly any[] ? T[number] : never;
+
+/**
+ * UnionToIntersection<{ foo: string } | { bar: string }> =
+ *  { foo: string } & { bar: string }.
+ */
+type UnionToIntersection<U> = (U extends unknown ? (arg: U) => 0 : never) extends (arg: infer I) => 0 ? I : never;
+
+/**
+ * LastInUnion<1 | 2> = 2.
+ */
+type LastInUnion<U> = UnionToIntersection<U extends unknown ? (x: U) => 0 : never> extends (x: infer L) => 0 ? L : never;
+/**
+ * UnionToTuple<1 | 2> = [1, 2].
+ */
+type UnionToTuple<U, Last = LastInUnion<U>> = [U] extends [never] ? [] : [...UnionToTuple<Exclude<U, Last>>, Last];
+
+declare function createFnWithProps<F extends Function, P extends {}>(fn: F, props: P): F & P;
+/**
+ * Adds a dictionary of key/value pairs to a function.
+ */
+declare function fnWithProps<A extends any[], R extends any, P extends {}>(fn: ((...args: A) => R), props: P): ((...args: A) => R) & P;
+/**
+ * Adds read-only (and narrowly typed) key/value pairs to a function
+ */
+declare function readonlyFnWithProps<A extends any[], R extends any, N extends Narrowable, P extends Record<keyof P, N>>(fn: ((...args: A) => R), props: P): ((...args: A) => R) & Readonly<P>;
+
+/**
+ * Provides the _keys_ of an object with the `keyof T` made explicit.
+ */
+declare function keys<T extends {}, W extends readonly string[]>(obj: T, ...without: W): Length<W> extends 0 ? (keyof T)[] : Exclude<keyof T, Keys<W, undefined>>[];
+
+/**
+ * **ruleSet**
+ *
+ * Defines a ruleset composed of _dynamic_ and _static_ boolean operators.
+ *
+ * - the first function call defines _dynamic_ props (_optional_)
+ * - the second function call defines static values
+ *
+ * ```ts
+ * const rs = ruleSet(
+ *    r => r.state()( { maybe: r => r.extends({ foo: 1 }) })
+ * )(
+ *    { color: true, age: false }
+ * );
+ * ```
+ */
+declare function ruleSet<N extends Narrowable, TState extends Record<keyof TState, N>>(defn?: TState): TState | undefined;
+
+declare const api: <N extends Narrowable, TPrivate extends Readonly<Record<any, N>>>(priv: TPrivate) => <TPublic extends object>(pub: TPublic) => () => TPublic;
+
+/**
+ * A type utility which looks at a chain for functions and reduces the type
+ * to the final `ReturnType` of the chain.
+ *
+ * ```ts
+ * // number
+ * type T = FinalReturn<() => (foo: string) => (bar: string) => () => number>;
+ * ```
+ */
+type FinalReturn<T extends any> = T extends (...args: any[]) => any ? FinalReturn<ReturnType<T>> : T;
+
+/**
+ * A function which returns a boolean value
+ */
+type LogicFunction<T extends readonly any[]> = (...args: T) => boolean;
+
+/**
+ * Groups a number of "logic functions" together by combining their results using
+ * the logical **AND** operator.
+ *
+ * **Note:** a "logic function" is any function which returns a boolean
+ */
+declare const and: <T extends any[]>(...ops: readonly LogicFunction<T>[]) => LogicFunction<T>;
+
+/**
+ * **Or**`<T>`
+ *
+ * Takes an array of boolean values and produces a boolean OR across these values
+ */
+type Or<T extends readonly boolean[]> = NarrowlyContains<true, T> extends true ? true : NarrowlyContains<boolean, T> extends true ? boolean : false;
+
+declare function or<O extends readonly boolean[]>(...conditions: O): Or<O>;
+
+/**
+ * Groups a number of "logic functions" together by combining their results using
+ * the logical **NOT** operator.
+ *
+ * **Note:** a "logic function" is any function which returns a boolean
+ */
+declare const not: <T extends any[]>(op: LogicFunction<T>) => LogicFunction<T>;
+
+type FilterStarts = {
+    /** one or more string which the value is allowed to start with */
+    startsWith: string | string[];
+};
+type FilterIs = {
+    /** whether a string _**is**_ of a particular value */
+    is: string | string[];
+};
+type FilterEnds = {
+    endsWith: string | string[];
+};
+type FilterContains = {
+    /** whether any of the strings specified are _contained_ in the value */
+    contains: string | string[];
+};
+type FilterEquals = {
+    /** one or more values which _equal_ the value passed in */
+    equals: number | number[];
+};
+type FilterNotEqual = {
+    /** one or more values which ALL _do not equal_ the value passed in */
+    notEqual: number | number[];
+};
+type FilterGreaterThan = {
+    /** the incoming value is greater than this value */
+    greaterThan: number;
+};
+type FilterLessThan = {
+    /** the incoming value is less than this value */
+    lessThan: number;
+};
+type StringFilter = FilterIs | FilterStarts | FilterEnds | FilterContains | (FilterStarts & FilterEnds) | (FilterStarts & FilterContains) | (FilterEnds & FilterContains) | (FilterStarts & FilterEnds & FilterContains);
+type NumericFilter = FilterEquals | FilterNotEqual | FilterGreaterThan | FilterLessThan | (FilterEquals & FilterNotEqual) | (FilterEquals & FilterGreaterThan) | (FilterEquals & FilterLessThan) | (FilterNotEqual & FilterGreaterThan) | (FilterNotEqual & FilterLessThan) | (FilterGreaterThan & FilterLessThan) | (FilterEquals & FilterGreaterThan & FilterLessThan) | (FilterNotEqual & FilterGreaterThan & FilterLessThan) | (FilterEquals & FilterNotEqual & FilterGreaterThan & FilterLessThan);
+type FilterDefn = StringFilter | NumericFilter;
+type NotFilter = {
+    /**
+     * **not**
+     *
+     * If you want to build a filter who's conditions being met results in _filtering_
+     * the value rather than accepting it then choose this.
+     */
+    not: FilterDefn;
+};
+declare function isNotFilter(f: FilterDefn | NotFilter): f is NotFilter;
+type UnwrapNot<T extends FilterDefn | NotFilter> = T extends NotFilter ? T["not"] extends StringFilter ? StringFilter : NumericFilter : T;
+declare function isNumericFilter(filter: FilterDefn): filter is NumericFilter;
+type UndefinedValue<U extends boolean> = true extends U ? "undefined treated as 'true'" : U extends "no-impact" ? "undefined treated in no-impact fashion" : "undefined treated as 'false'";
+type UndefinedTreatment = "undefined treated as 'true'" | "undefined treated as 'false'";
+type LogicalCombinator = "AND" | "OR";
+/**
+ * **FilterFn**
+ *
+ * A filter function derived from the `filter()` configurator. This function is intended to provide a type-strong _filter_ function which can be used like so:
+ * be used like:
+ * ```ts
+ * const onlyPrivate = filter({ startsWith: "_" });
+ * const privateFiles = files.filter(onlyPrivate);
+ * ```
+ */
+type FilterFn<T extends StringFilter | NumericFilter> = T extends StringFilter ? <V extends string | undefined>(input: V) => boolean : <V extends number | undefined>(input: V) => boolean;
+/**
+ * Defines a logical function for each condition type
+ */
+type ConditionFilter<T extends StringFilter | NumericFilter> = T extends StringFilter ? (input: string) => boolean : (input: number) => boolean;
+/**
+ * **filter**
+ *
+ * A higher order helper utility which builds a boolean _filter_ function based on a simple
+ * configuration object. Support either _string_ or _numeric_ filters.
+ *
+ * ```ts
+ * const str = filter({startsWith: ["_", "."], endsWith: ".md"});
+ * const num = filter({ greaterThan: 55, notEqual: [66, 77]});
+ * ```
+ *
+ * All conditions (e.g., `startsWith`, `contains`, `notEqual`, etc.) that a particular filter
+ * is defined as having -- if there is more than one -- will be logically combined using AND
+ * unless specified otherwise in the third parameter.
+ *
+ * How a value of _undefined_ will be treated is stated in the second parameter but defaults
+ * to "no-impact" which means it's `false` when the logicCombinator is OR but defaults
+ * to `true` when the logicCombinator is AND.
+ */
+declare const filter: <F extends FilterDefn | NotFilter, U extends boolean | "no-impact", C extends LogicalCombinator>(config: F, logicCombinator?: C, ifUndefined?: U) => FilterFn<UnwrapNot<F>>;
+
+/**
+ * Passing in an array of strings, you are passed back a dictionary with
+ * all the keys being the strings and values set to `true`.
+ * ```ts
+ * // { bar: true, bar: true } as const;
+ * const d - dictArr(arr);
+ *
+ * const fooBar = arrayToKeyLookup("foo", "bar");
+ * ```
+ */
+declare function arrayToKeyLookup<T extends readonly string[]>(...keys: T): Record<T[number], true>;
+
+interface DefinePropertiesApi<T extends {}> {
+    /**
+     * Makes a property on the object **readonly** on the Javascript runtime
+     */
+    ro<K extends keyof T>(prop: K, errorMsg?: (p: K, v: any) => string): Omit<T, K> & Record<K, Readonly<T[K]>>;
+    /**
+     * Makes a property on the object **read/writeable** on the Javascript runtime;
+     * this is the default so only use this where it is needed.
+     */
+    rw<K extends keyof T>(prop: K): Omit<T, K> & Record<K, Readonly<T[K]>>;
+}
+declare function defineProperties<T extends {}>(obj: T): DefinePropertiesApi<T>;
+
+/**
+ * Often when mutating the shape of an object you will end up with the union of a number of
+ * `Record<string, x>` and `Record<string, y>` which is messy to look at and take away meaning.
+ *
+ * This type utility will cleanup an object and return a simple dictionary definition for it.
+ */
+type SimplifyObject<T extends {}> = ExpandRecursively<UnionToIntersection<ExpandRecursively<T>>>;
+
+/**
+ * Given a dictionary of key/values, where the value is a function, this
+ * type utility will maintain the keys but change the values to whatever
+ * the `ReturnType` of the function was.
+ * ```ts
+ * const api = {
+ *    val: 42,
+ *    hi: (name: string) => `hi ${name}`,
+ *    bye: (name: string) => `bye ${name}`
+ * };
+ * // { hi: string; bye: string }
+ * type Test = UnwrapValue<typeof api>
+ * // { val: number; foo: string; bar: string }
+ * type Test2 = UnwrapValue<typeof api, false>
+ * ```
+ */
+type DictPartialApplication<T extends Record<string, any>, I extends boolean = true> = SimplifyObject<{
+    [K in keyof T]: T[K] extends (...args: any[]) => any ? Record<K, ReturnType<T[K]>> : true extends I ? never : Record<K, T[K]>;
+}[keyof T]>;
+
+/**
+ * Allow a dictionary have it's value's type changed to `T` while maintaining the keys in
+ * the original object `I` so long as the original value for the KV pair extends `V`.
+ *
+ * If `V` is not specified then it defaults to _any_ and therefore all KVs are preserved.
+ *
+ * ```ts
+ * type Obj = { foo: "hello", bar: 42, baz: () => "world" };
+ * // { foo: number, bar: number, baz: number };
+ * type AllNumbers = DictChangeValue<Obj, number>;
+ * // { foo: number }
+ * type StringToBool = DictChangeValue<Obj, boolean, string>
+ * ```
+ */
+type DictChangeValue<
+/** the object who's value-type we're changing */
+I extends Record<string, any>, 
+/** the return type that functions should be modified to have */
+T extends any, 
+/**
+ *The type we expect in the value; if the value extends type `V` then the value will
+ * be converted to type `O`; if not then the KV pair will be discarded
+ */
+V extends any = any> = SimplifyObject<{
+    [K in keyof I]: I[K] extends V ? Record<K, T> : never;
+}[keyof I]>;
+
+/**
+ * **DictPrependWithFn**
+ *
+ * Given a strongly typed object `<T>`, this utility will inject a function call with
+ * arguments `<A>` and then return what had subsequently been the value of the property.
+ *
+ * Should you only want to apply this treatment to _some_ of the properties you can
+ * pass in a value `<E>` which will ensure that only properties which _extend_ `E` will be
+ * modified.
+ */
+type DictPrependWithFn<T extends Record<string, any>, A extends any[], E extends any = any> = SimplifyObject<{
+    [K in keyof T]: T[K] extends E ? Record<K, (...args: A) => T[K]> : Record<K, T[K]>;
+}[keyof T]>;
+
+/**
+ * **DictReturnValues**
+ *
+ * A type utility which receives an object `<T>` and then modifies
+ * the return type of any properties which are a function to have this
+ * new **ReturnType** `<R>`. Optionally you can specify a particular return type which
+ * you are targeting and then
+ */
+type DictReturnValues<
+/** the object which we expect to have props with function values */
+T extends Record<string, any>, 
+/** the return type that functions should be modified to have */
+R extends any, 
+/** optionally this utility can target only functions with a certain existing return value */
+O extends (...args: any[]) => any = (...args: any[]) => any> = SimplifyObject<{
+    [K in keyof T]: T[K] extends O ? T[K] extends (...args: infer A) => any ? Record<K, (...args: A) => R> : Record<K, T[K]> : Record<K, T[K]>;
+}[keyof T]>;
+
+/**
+ * Expresses whether an option is "opt" (optional) or "req" (required)
+ */
+type OptRequired = "opt" | "req";
+
+declare const DEFAULT_ONE_TO_MANY_MAPPING: FinalizedMapConfig<"req", "I -> O[]", "opt">;
+declare const DEFAULT_ONE_TO_ONE_MAPPING: FinalizedMapConfig<"req", "I -> O", "req">;
+declare const DEFAULT_MANY_TO_ONE_MAPPING: FinalizedMapConfig<"req", "I[] -> O", "req">;
+type DefaultOneToManyMapping = typeof DEFAULT_ONE_TO_MANY_MAPPING;
+type DefaultOneToOneMapping = typeof DEFAULT_ONE_TO_ONE_MAPPING;
+type DefaultManyToOneMapping = typeof DEFAULT_MANY_TO_ONE_MAPPING;
+/**
+ * **mapTo** _utility_
+ *
+ * This utility -- by default -- creates a strongly typed 1:M data mapper which maps from one
+ * known source `I` to any array of another `O[]`:
+ * ```ts
+ * const mapper = mapTo<I, O>(i => [{
+ *    foo: i.bar
+ * }]);
+ * ```
+ */
+declare const mapToFn: ConfiguredMap<DefaultOneToManyMapping>["map"];
+/**
+ * Provides a `config` method which allows the relationships between _inputs_
+ * and _outputs_ to be configured.
+ */
+declare const mapToDict: MapperApi;
+/**
+ * **mapTo** _utility_
+ *
+ * This utility creates a strongly typed data mapper which maps from one
+ * known source `I` to another `O`.
+ *
+ * Signatures:
+ * ```ts
+ * const defMap = mapTo<I,O>( ... );
+ * const configured = mapTo.config({ output: "req" }).map<I,O>( ... );
+ * const one2one = mapTo.oneToOne().map<I,O>( ... );
+ * const many2one = mapTo.manyToOne().map<I,O>( ... );
+ * ```
+ */
+declare const mapTo: (<I, O>(map: (source: I) => O[]) => Mapper<I, O, FinalizedMapConfig<"req", "I -> O[]", "opt">>) & MapperApi;
+
+/**
+ * **Extends**`<T, EXTENDS>`
+ *
+ * Boolean type utility which returns `true` if `T` _extends_ `EXTENDS`.
+ */
+type Extends<T extends Narrowable, EXTENDS extends Narrowable> = T extends EXTENDS ? true : false;
+/**
+ * **IfExtends**
+ *
+ * Branching type utility which returns type `IF` when `E` _extends_ `T`; otherwise
+ * it will return the type `ELSE`.
+ */
+type IfExtends<T extends Narrowable, EXTENDS extends Narrowable, IF extends Narrowable, ELSE extends Narrowable> = Extends<T, EXTENDS> extends true ? IF : ELSE;
+
+type IsBoolean<T> = [T] extends [boolean] ? true : false;
+/**
+ * Type utility which returns `true` or `false` based on
+ * whether the type holds the narrow "true" type.
+ * ```ts
+ * // true
+ * type T = IsTrue<true>;
+ * // boolean
+ * type U = IsTrue<boolean>;
+ * // false
+ * type F = IsTrue<false>;
+ * type F2 = IsTrue<"false">;
+ * ```
+ */
+type IsTrue<T extends Narrowable> = IsBoolean<T> extends true ? T extends true ? true : T extends false ? false : unknown : false;
+type IsFalse<T extends Narrowable> = IsBoolean<T> extends true ? T extends false ? true : true extends T ? false : unknown : false;
+/**
+ * Type utility which checks for literal `true` value and then switches type
+ * to the IF, ELSE, or MAYBE generic types passed in where _maybe_ is when T
+ * is the wide type of `boolean`
+ */
+type IfTrue<T extends boolean, IF extends Narrowable, ELSE extends Narrowable, MAYBE extends Narrowable> = IsTrue<T> extends true ? IF : IsTrue<T> extends false ? ELSE : MAYBE;
+/**
+ * Type utility which checks for literal `false` value and then switches type
+ * to the IF, ELSE, or MAYBE generic types passed in where _maybe_ is when T
+ * is the wide type of `boolean`
+ */
+type IfFalse<T extends Narrowable, IF extends Narrowable, ELSE extends Narrowable, MAYBE extends Narrowable> = IsFalse<T> extends true ? IF : IsTrue<T> extends false ? ELSE : MAYBE;
+/**
+ * **IsBooleanLiteral**
+ *
+ * Type utility which returns true/false if the boolean value is a _boolean literal_ versus
+ * just the wider _boolean_ type.
+ */
+type IsBooleanLiteral<T extends Narrowable> = IsTrue<T> extends true ? true : IsFalse<T> extends true ? true : false;
+/**
+ * **IfBooleanLiteral**
+ *
+ * Branch utility which returns `IF` type when `T` is a boolean literal and `ELSE` otherwise
+ */
+type IfBooleanLiteral<T extends boolean, IF extends Narrowable, ELSE extends Narrowable> = IsBooleanLiteral<T> extends true ? IF : ELSE;
+
+/**
+ * **IsStringLiteral**
+ *
+ * Type utility which returns true/false if the string a _string literal_ versus
+ * just the _string_ type.
+ */
+type IsStringLiteral<T extends Narrowable> = [T] extends [string] ? string extends T ? false : true : false;
+/**
+ * **IfStringLiteral**
+ *
+ * Branch utility which returns `IF` type when `T` is a string literal and `ELSE` otherwise
+ */
+type IfStringLiteral<T extends string, IF extends Narrowable, ELSE extends Narrowable> = [
+    IsStringLiteral<T>
+] extends [true] ? IF : ELSE;
+/**
+ * **IsNumericLiteral**
+ *
+ * Type utility which returns true/false if the numeric value a _numeric literal_ versus
+ * just the _number_ type.
+ */
+type IsNumericLiteral<T extends number> = number extends T ? false : true;
+/**
+ * **IfNumericLiteral**
+ *
+ * Branch utility which returns `IF` type when `T` is a numeric literal and `ELSE` otherwise
+ */
+type IfNumericLiteral<T extends number, IF extends Narrowable, ELSE extends Narrowable> = IsNumericLiteral<T> extends true ? IF : ELSE;
+/**
+ * **IsLiteral**
+ *
+ * Type utility which returns true/false if the value passed -- a form of a
+ * string, number, or boolean -- is a _literal_ value of that type (true) or
+ * the more generic wide type (false).
+ */
+type IsLiteral<T> = [T] extends [string] ? IsStringLiteral<T> : [T] extends [boolean] ? IsBooleanLiteral<T> : [T] extends [number] ? IsNumericLiteral<T> : false;
+/**
+ * **IsOptionalLiteral**
+ *
+ * Type utility which returns true/false if the value passed -- a form of a
+ * string, number, or boolean -- is a _literal_ value of that type (true) or
+ * the more generic wide type (false).
+ *
+ * This type also strips off _undefined_ from any possible union type to evaluate
+ * to `true` even when a literal value is in union with _undefined_. If you don't
+ * want to test for the union with _undefined_ use the `IsOptional` utility instead.
+ */
+type IsOptionalLiteral<T> = [Exclude<T, undefined>] extends [string] ? IsStringLiteral<Exclude<T, undefined>> : [Exclude<T, undefined>] extends [boolean] ? IsBooleanLiteral<Exclude<T, undefined>> : [Exclude<T, undefined>] extends [number] ? IsNumericLiteral<Exclude<T, undefined>> : false;
+/**
+ * **IfLiteral**
+ *
+ * Branch type utility with return `IF` when `T` is a _literal_ value and `ELSE` otherwise
+ */
+type IfLiteral<T, IF extends Narrowable, ELSE extends Narrowable> = IsLiteral<T> extends true ? IF : ELSE;
+/**
+ * **IfOptionalLiteral**
+ *
+ * Branch type utility with return `IF` when `T` is a _literal_ value (with possibly
+ * the inclusion of _undefined_); otherwise returns the type `ELSE`
+ */
+type IfOptionalLiteral<T, IF extends Narrowable, ELSE extends Narrowable> = IsOptionalLiteral<T> extends true ? IF : ELSE;
+
+/**
+ * **IsUndefined**
+ *
+ * Boolean type utility returns `true` if `T` is undefined; `false` otherwise
+ */
+type IsUndefined<T extends Narrowable> = T extends undefined ? true : false;
+/**
+ * **IfUndefined**`<T, IF, ELSE>`
+ *
+ * Type utility which returns `IF` type when `T` is an _undefined_
+ * otherwise returns `ELSE` type.
+ */
+type IfUndefined<T, IF extends Narrowable, ELSE extends Narrowable> = IsUndefined<T> extends true ? IF : ELSE;
+
+/**
+ * **TypeDefault**
+ *
+ * A type utility designed to help maintain strong and narrow types where
+ * you have a value `T` which _might_ be **undefined** and a type `D` which
+ * defines all the _default_ type for `T`.
+ *
+ * - In all cases we compare first whether `T` is undefined and replace it's
+ * type with `D` 1-for-1 if it is
+ * - To address a larger set of use cases, when `D` _extends_ an object we will
+ * compare each property of `D` against `T`
+ * ```ts
+ * type I = { foo?: "foo" |  undefined; bar?: 42 | 53 | undefined };
+ * type D = { foo: "foo"; bar: 53 };
+ * type DF = TypeDefault<I,D>; // `D`
+ * const i = { foo: undefined, bar: 99 } as const;
+ * type DF2 = TypeDefault<typeof i, D>; // `{ foo: "foo"; bar: 99 }`
+ * ```
+ */
+type TypeDefault<T, D> = IsObject<D> extends true ? IsObject<T> extends true ? SimplifyObject<{
+    [K in keyof D]: K extends keyof T ? TypeDefault<T[K], D[K]> : D[K];
+}> : IfUndefined<T, // check if T is undefined
+D, // use D as the type
+Exclude<T, undefined>> : IfUndefined<T, // check whether is T is undefined
+D, // assign to D if it is
+IfOptionalLiteral<T, // if T is a literal
+IfExtends<D, T, D, // use D since it extends the value of T
+Exclude<T, undefined>>, Exclude<T, undefined>>>;
+
+/**
+ * Expresses relationship between inputs/outputs:
+ */
+declare enum MapCardinality {
+    /** every input results in 0:M outputs */
+    OneToMany = "I -> O[]",
+    /** every input results in 0:1 outputs */
+    OneToOne = "I -> O",
+    /** every input is an array of type I and reduced to a single O  */
+    ManyToOne = "I[] -> O"
+}
+type MapCardinalityIllustrated = EnumValues<MapCardinality>;
+/**
+ * The _user_ configuration of a **mapTo** mapper function
+ * which will be finalized by merging it with the appropriate
+ * default mapping type.
+ */
+interface MapConfig<IR extends OptRequired | undefined = undefined, D extends MapCardinalityIllustrated | undefined = undefined, OR extends OptRequired | undefined = undefined> {
+    input?: IR;
+    output?: OR;
+    cardinality?: D;
+    /**
+     * Whether calls to the final `MapFn` will be logged to stderr
+     * for debugging purposes. Defaults to false; if you specify
+     * a _string_ for a value that will be sent to stderr along
+     * with other debugging info.
+     */
+    debug?: boolean | string;
+}
+/**
+ * A finalized configuration of a **mapTo** mapper functions cardinality
+ * relationships between _inputs_ and _outputs_.
+ *
+ * Note: _this configuration does _not_ yet include the actual mapping
+ * configuration between the input and output._
+ */
+type FinalizedMapConfig<IR extends OptRequired = MapIR<DefaultOneToManyMapping>, D extends MapCardinalityIllustrated = MapCard<DefaultOneToManyMapping>, OR extends OptRequired = MapOR<DefaultOneToManyMapping>> = Required<Omit<MapConfig<IR, D, OR>, "debug">> & {
+    finalized: true;
+    debug: boolean | string;
+};
+/**
+ * User configuration exposed by a config function which specifies the
+ * cardinality already (e.g., `oneToMany()`, `manyToOne()`)
+ */
+type MapCardinalityConfig<IR extends OptRequired | undefined, OR extends OptRequired | undefined> = {
+    /** whether we the input can _optionally_ be an `undefined` value or not */
+    input?: IR;
+    /** whether we the output can _optionally_ be an `undefined` value or not */
+    output?: OR;
+    /**
+     * Whether calls to the final `MapFn` will be logged to stderr
+     * for debugging purposes. Defaults to false; if you set to a string
+     * value than this will be echoed out with stderr.
+     */
+    debug?: boolean | string;
+};
+/**
+ * **ConfiguredMap**
+ *
+ * A partial application of the mapTo() utility which has expressed the
+ * configuration of the _inputs_ and _outputs_ and provides a `.map()`
+ * method which allows the user configure the specifics of the mapping.
+ */
+type ConfiguredMap<C extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>> = {
+    map: <I, O>(map: MapTo<I, O, C>) => Mapper<I, O, C>;
+    input: MapIR<C>;
+    cardinality: MapCard<C>;
+    output: MapOR<C>;
+    debug: boolean | string;
+};
+/**
+ * Extracts the IR, Cardinality, and OR generics from a FinalizedMapConfig
+ */
+type DecomposeMapConfig<M extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>> = M extends MapConfig<infer IR, infer D, infer OR> ? IR extends OptRequired | undefined ? D extends MapCardinalityIllustrated | undefined ? OR extends OptRequired | undefined ? [IR, D, OR] : never : never : never : M extends FinalizedMapConfig<infer IR, infer D, infer OR> ? IR extends OptRequired ? D extends MapCardinalityIllustrated ? OR extends OptRequired ? [IR, D, OR] : never : never : never : never;
+/** extracts IR from a `FinalizedMapConfig` */
+type MapIR<T extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>> = DecomposeMapConfig<T>[0];
+/**
+ * extracts the MapCardinality from a `FinalizedMapConfig`
+ */
+type MapCard<T extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>> = DecomposeMapConfig<T>[1];
+/** extracts OR from a `FinalizedMapConfig` */
+type MapOR<T extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>> = DecomposeMapConfig<T>[2];
+/**
+ * Merges the types of a userland configuration with a default configuration
+ */
+type AsFinalizedConfig<U extends MapConfig<OptRequired | undefined, MapCardinalityIllustrated | undefined, OptRequired | undefined>, D extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>> = TypeDefault<U, D> extends FinalizedMapConfig<infer IR, infer C, infer OR> ? FinalizedMapConfig<IR, C, OR> : never;
+type MapperApi = {
+    /**
+     * Provides opportunity to configure _input_, _output_, and _cardinality_
+     * prior to providing a mapping function.
+     *
+     * Note: _the defaults for configuration are defined by the_ `DEFAULT_ONE_TO_MANY_MAPPING`
+     * _constant made available as a symbol from this library._
+     */
+    config: <C extends MapConfig<OptRequired, //
+    MapCardinalityIllustrated, OptRequired>>(config: C) => ConfiguredMap<AsFinalizedConfig<C, //
+    DefaultOneToManyMapping>>;
+    /**
+     * Provides a nice 1:1 ratio between the input and output.
+     *
+     * By default the input and output are considered to be _required_
+     * properties but this can be changed with the options hash provided.
+     * ```ts
+     * const mapper = mapTo.oneToOne().map(...);
+     * // add in ability to filter out some inputs
+     * const mapAndFilter = mapTo.oneToOne({ output: "opt" })
+     * ```
+     */
+    oneToOne: <C extends MapCardinalityConfig<OptRequired, OptRequired>>(config?: C) => ConfiguredMap<AsFinalizedConfig<C, //
+    DefaultOneToOneMapping>>;
+    /**
+     * **manyToOne** _mapping_
+     *
+     * Provides a configuration where multiple inputs `I[]` will be mapped to a
+     * single output `O`.
+     *
+     * Choosing this configuration will, by default, set both input and output
+     * to be "required" but you can change this default if you so choose.
+     */
+    manyToOne: <C extends MapCardinalityConfig<OptRequired | undefined, //
+    //
+    OptRequired | undefined>>(config?: C) => ConfiguredMap<AsFinalizedConfig<C, //
+    DefaultManyToOneMapping>>;
+    oneToMany: <C extends MapCardinalityConfig<OptRequired | undefined, //
+    //
+    OptRequired | undefined>>(config?: C) => ConfiguredMap<AsFinalizedConfig<C, //
+    DefaultOneToManyMapping>>;
+};
+type MapInput<I, //
+IR extends OptRequired, C extends MapCardinalityIllustrated> = C extends MapCardinality.OneToMany | "I -> O[]" ? IR extends "opt" ? I | undefined : I : C extends MapCardinality.OneToOne | "I -> O" ? IR extends "opt" ? I | undefined : I : C extends MapCardinality.ManyToOne | "I[] -> O" ? IR extends "opt" ? I[] | undefined : I[] : never;
+type MapOutput<O, //
+OR extends OptRequired, C extends MapCardinalityIllustrated> = C extends MapCardinality.OneToMany | "I -> O[]" ? OR extends "opt" ? O[] : [O, ...O[]] : C extends MapCardinality.OneToOne | "I -> O" ? OR extends "opt" ? O | null : O : C extends MapCardinality.ManyToOne | "I[] -> O" ? OR extends "opt" ? O | null : O : never;
+/**
+ * **MapTo<I, O>**
+ *
+ * A mapping function between an input type `I` and output type `O`. Defaults to using
+ * the _default_ OneToMany mapping config.
+ *
+ * **Note:** this type is designed to guide the userland mapping; refer
+ * to `MapFn` if you want the type output by the `mapFn()` utility.
+ */
+type MapTo<I, O, C extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired> = DefaultOneToManyMapping> = MapIR<C> extends "opt" ? (source?: MapInput<I, MapIR<C>, MapCard<C>>) => MapOutput<O, MapOR<C>, MapCard<C>> : (source: MapInput<I, MapIR<C>, MapCard<C>>) => MapOutput<O, MapOR<C>, MapCard<C>>;
+type MapFnOutput<I, O, S, OR extends OptRequired, C extends MapCardinalityIllustrated> = C extends "I -> O[]" | MapCardinality.OneToMany ? S extends I[] ? OR extends "opt" ? O[] : [O, ...O[]] : OR extends "opt" ? O[] | null : O[] : C extends MapCardinality.OneToOne | "I -> O" ? S extends I[] ? OR extends "opt" ? O[] : [O, ...O[]] : OR extends "opt" ? O | null : O : C extends MapCardinality.ManyToOne | "I[] -> O" ? S extends I[][] ? OR extends "opt" ? O[] : [O, ...O[]] : OR extends "opt" ? O | null : O : never;
+type MapFnInput<I, IR extends OptRequired, D extends MapCardinalityIllustrated> = D extends "I -> O[]" | MapCardinality.OneToMany ? IR extends "opt" ? I | I[] | undefined : I | I[] : D extends MapCardinality.OneToOne | "I -> O" ? IR extends "opt" ? I | I[] | undefined : I | I[] : D extends MapCardinality.ManyToOne | "I[] -> O" ? IR extends "opt" ? I[] | I[][] | undefined : I[] | I[][] : never;
+/**
+ * The mapping function provided by the `mapFn()` utility. This _fn_
+ * is intended to be used in two ways:
+ *
+ * 1. Iterative:
+ *    ```ts
+ *    const m = mapTo<I,O>(i => [ ... ]);
+ *    // maps inputs to outputs
+ *    const out = inputs.map(m);
+ *    ```
+ * 2. Block:
+ *    ```ts
+ *    // maps inputs to outputs (filtering or splitting where appr.)
+ *    const out2 = m(inputs);
+ *    ```
+ */
+type MapFn<I, O, C extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>> = MapIR<C> extends "opt" ? <S extends MapFnInput<I, MapIR<C>, MapCard<C>>>(source?: S) => MapFnOutput<I, O, S, MapOR<C>, MapCard<C>> : <S extends MapFnInput<I, MapIR<C>, MapCard<C>>>(source: S) => MapFnOutput<I, O, S, MapOR<C>, MapCard<C>>;
+/**
+ * **Mapper**
+ *
+ * A fully configured _mapper_ stemming from the **mapTo()** utility. It is both a mapping
+ * function and a dictionary which describes the mapper's properties.
+ * ```ts
+ * const m = mapTo.oneToOne().map( ... );
+ * const mapped = m(inputs);
+ * const mappedOver = inputs.map(m);
+ * ```
+ *
+ * Note: the root of a `Mapper` is the mapper function but
+ * this is combined with a dictionary of settings and types
+ * which you can use. For instance, look at the `fnSignature`
+ * property to get the _type_ signature of the map function.
+ */
+type Mapper<I = unknown, O = unknown, C extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired> = FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>> = {
+    input: MapIR<C>;
+    output: MapOR<C>;
+    cardinality: MapCard<C>;
+    debug: boolean | string;
+    inputType: I;
+    outputType: O;
+    /**
+     * Provides the _type_ information for mapper function.
+     *
+     * Note: _this is just a **type**_ not the actual function which positioned
+     * at the root of the Mapper type
+     */
+    fnSignature: MapFn<I, O, C>;
+} & MapFn<I, O, C>;
+/**
+ * **MapInputFrom**
+ *
+ * Type utility which extracts the `I` type from a fully configured `Mapper`
+ */
+type MapInputFrom<T extends Mapper> = T extends Mapper<infer I> ? I : never;
+/**
+ * **MapOutputFrom**
+ *
+ * Type utility which extracts the output [`O`] type from a fully configured `Mapper`
+ */
+type MapOutputFrom<T extends Mapper> = T extends Mapper<any, infer O> ? O : never;
+/**
+ * **MapCardinalityFrom**
+ *
+ * Type utility which extracts _cardinality_ of a `Mapper`'s inputs to outputs
+ */
+type MapCardinalityFrom<T extends Mapper> = T extends Mapper<any, any, infer C> ? C extends FinalizedMapConfig<OptRequired, infer Cardinality, OptRequired> ? Cardinality : never : never;
+
+/**
+ * Given a dictionary of type `<T>`, this utility function will
+ * make the `<M>` generic property _mutable_ and all other _read-only_.
+ *
+ * ```ts
+ * // { foo: string, bar?: Readonly<number> }
+ * type Example = MutableProps<{
+ *    foo: Readonly<string>,
+ *    bar?: number
+ * }, "foo">;
+ * ```
+ */
+type MutableProps<T extends {}, M extends keyof T & string> = ExpandRecursively<Mutable<Pick<T, M>> & Readonly<Pick<T, Keys<T, M>>>>;
+
+/**
+ * Given a dictionary of type `<T>`, this utility function will
+ * make the `<R>` generic property _required_ (use a union to make
+ * more than one prop required).
+ *
+ * ```ts
+ * // { foo: string, bar?: number }
+ * type Example = RequireProps<{foo?: string, bar?: number}, "foo">;
+ * ```
+ */
+type RequireProps<T extends {}, R extends keyof T> = ExpandRecursively<Required<Pick<T, R>> & T>;
+
+/**
+ * **SameKeys**
+ *
+ * Creates a _type_ with the same _keys_ as `T` but sets all values of these keys to `A` (which is
+ * **any** by default).
+ *
+ * Note: meant to be used as part of an _extends_ clause in most cases.
+ */
+type SameKeys<T extends object, A extends any = any> = {
+    [P in keyof T]: A;
+};
+
+type LowerAlpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
+/** Uppercase alphabetic character */
+type UpperAlpha = Uppercase<LowerAlpha>;
+/**
+ * Alphabetical characters (upper and lower)
+ */
+type Alpha = UpperAlpha | LowerAlpha;
+type Whitespace = " " | "\n" | "\t";
+type Punctuation = "." | "," | ";" | "!" | "?";
+/**
+ * Characters which typically are used to separate words (but not including a space)
+ */
+type StringDelimiter = "_" | "-" | "/" | "\\";
+type OpeningBracket = "(" | "[" | "{";
+type ClosingBracket = ")" | "]" | "}";
+/**
+ * Opening and closing parenthesis
+ */
+type Parenthesis = "(" | ")";
+/**
+ * Opening and closing brackets
+ */
+type Bracket = OpeningBracket | ClosingBracket;
+/**
+ * Numeric string characters
+ */
+type NumericString = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+/**
+ * Any alphabetic or numeric string character
+ */
+type AlphaNumeric = Alpha | NumericString;
+/**
+ * Allows alphanumeric characters and some special characters typically allowed
+ * in variable names.
+ */
+type VariableName = AlphaNumeric | "_" | "." | "-";
+type SpecialCharacters = "@" | "~" | "^" | "#" | "&" | "*";
+/**
+ * Non-alphabetic characters including whitespace, string numerals, and
+ */
+type NonAlpha = Whitespace | Punctuation | NumericString | Bracket | SpecialCharacters;
+type Ipv4 = `${number}.${number}.${number}.${number}`;
+
+/**
+ * Extracts the _required_ keys in the object's type. You also may
+ * optionally filter by the _value_ of the key.
+ */
+type RequiredKeys<T extends object, V extends any = any> = {
+    [K in keyof T]-?: {} extends {
+        [P in K]: T[K];
+    } ? never : T[K] extends V ? K : never;
+}[keyof T];
+/**
+ * Extracts the intersecting/common keys to two objects
+ */
+type IntersectingKeys<T extends Record<string, any> | readonly string[], U extends Record<string, any> | readonly string[]> = {
+    [K in keyof T]: K extends Keys<U> ? K : never;
+}[keyof T];
+/**
+ * Extracts the _optional_ keys in the object's type. You also may
+ * optionally filter by the _value_ of the key.
+ */
+type OptionalKeys<T extends object, V extends any = any> = {
+    [K in keyof T]-?: {} extends {
+        [P in K]: T[K];
+    } ? V extends T[K] ? K : never : never;
+}[keyof T];
+/**
+ * The _keys_ on a given object `T` which have a literal value of `W`.
+ *
+ * Optionally, you may provide a generic `E` to exclude certain keys in
+ * result set.
+ * ```ts
+ * // "foo"
+ * type Str = KeysWithValue<{ foo: "hi"; bar: 5 }>;
+ * ```
+ */
+type KeysWithValue<W extends any, T extends object> = {
+    [K in keyof T]: T[K] extends W ? Readonly<K> : never;
+}[keyof T];
+/**
+ * A `PrivateKey` must start with a `_` character and then follow with
+ * an alphabetic character
+ */
+type PrivateKey = `_${Alpha}${string}`;
+/**
+ * Keys on an object which have a `_` character as first part of the
+ * name are considered private and this utility will create a union
+ * of all the keys in this category.
+ */
+type PrivateKeys<T extends object> = {
+    [K in keyof T]: K extends `_${string}` ? K : never;
+}[keyof T];
+/**
+ * **PublicKeys**
+ *
+ * Builds a union type of all keys which are "public" where a public
+ * key is any key which _does not_ start with the `_` character.
+ */
+type PublicKeys<T extends object> = {
+    [K in keyof T]: K extends `_${string}` ? never : K;
+}[keyof T];
+type StringKeys<T extends object> = {
+    [K in keyof T]: K extends string ? Readonly<K> : never;
+}[keyof T];
+/**
+ * The keys of an object which _are not_ a string type
+ */
+type NonStringKeys<T extends object> = {
+    [K in keyof T]: K extends string ? never : Readonly<K>;
+}[keyof T];
+type NumericKeys<T extends object> = {
+    [K in keyof T]: K extends number ? Readonly<K> : never;
+}[keyof T];
+type NonNumericKeys<T extends object> = {
+    [K in keyof T]: K extends number ? never : Readonly<K>;
+}[keyof T];
+/**
+ * **RequiredProps**
+ *
+ * Reduces an object type to only key/value pairs where the key is required
+ */
+type RequiredProps<T extends object> = Pick<T, RequiredKeys<T>>;
+/**
+ * **OptionalProps**
+ *
+ * Reduces an object to only key/value pairs where the key is optional
+ */
+type OptionalProps<T extends object> = Pick<T, OptionalKeys<T>>;
+/**
+ * **WithValue**
+ *
+ * Reduces an object's type down to only those key/value pairs where the
+ * value is of type `W`.
+ * ```ts
+ * const foo = { a: 1, b: "hi", c: () => "hello" }
+ * // { c: () => "hello" }
+ * type W = WithValue<Function, typeof foo>
+ * ```
+ */
+type WithValue<W extends any, T extends object, E extends any = undefined> = undefined extends E ? Pick<T, KeysWithValue<W, T>> : Omit<Pick<T, KeysWithValue<W, T>>, KeysWithValue<E, T>>;
+type DictionaryWithoutValue<TDict extends object, TWithoutValue> = Omit<TDict, KeysWithValue<TWithoutValue, TDict>>;
+/**
+ * Reduces an object to only the key/value pairs where the key is a
+ * string.
+ */
+type WithStringKeys<T extends object> = Omit<T, NonStringKeys<T>>;
+/**
+ * Reduces an object to only the key/value pairs where the key is numeric.
+ */
+type WithNumericKeys<T extends object> = Omit<T, NonNumericKeys<T>>;
+
+/**
+ * **Transformer**
+ *
+ * A function responsible for transforming the _values_ of
+ * dictionary `I` into different _values_ for dictionary `O`.
+ *
+ * This type utility assumes that _keys_ of both dictionaries
+ * are the same.
+ */
+type Transformer<I extends object, O extends SameKeys<I>, K extends keyof I = keyof I> = (input: I, key: K) => O[K];
+
+/**
+ * Takes a dictionary of type `I` and converts it to a dictionary of type `O` where
+ * they _keys_ used in both dictionaries are the same.
+ *
+ * The _transform_ function passed in must be able to recieve the full input object
+ * and key, and then return expected value of `O` for the given key.
+ */
+declare function dictionaryTransform<I extends object, O extends SameKeys<I>>(input: I, transform: Transformer<I, O>): O;
+
+interface Uniqueness<T> {
+    /** boolean flag to indicate whether the property was unique across all records */
+    isUnique: boolean;
+    /** the overall number of records which contained the property */
+    size: number;
+    /** specifies if undefined values were encountered for this property */
+    includedUndefined: boolean;
+    /** the unique values for the property across all records */
+    values: readonly T[];
+}
+type DictArrApi<T extends Record<string, Narrowable>, A extends readonly T[]> = {
+    length: number;
+    toLookup<PL extends RequiredKeys<T, string> & keyof T & string>(prop: PL): UniqueForProp<A, PL> extends string ? Record<UniqueForProp<A, PL>, T> : Record<string, T>;
+    sum<PS extends RequiredKeys<T, number> | OptionalKeys<T, number>>(prop: PS): number;
+    count<PC extends OptionalKeys<T>>(prop: PC): number;
+    unique<PU extends Keys<T> & keyof T>(prop: PU): Uniqueness<T[PU]>;
+};
+/**
+ * converts an array of objects to a dictionary with keys formed from a given property
+ * of the object and the value being the object itself.
+ */
+declare const dictArr: <T extends Record<string, Narrowable>>(...dicts: readonly T[]) => DictArrApi<T, readonly T[]>;
+
+type DictFromKv<T extends readonly {
+    key: string;
+    value: unknown;
+}[]> = {
+    [R in T[number] as R["key"]]: R["value"];
+};
+
+/**
+ * Provides a strongly typed _key_ and _value_ for a dictionary `T`
+ *
+ * ```ts
+ * type Obj = { foo: 1, bar: "hi" };
+ * // ["foo", 1 ]
+ * type Foo = KeyValue<Obj, "foo">;
+ * ```
+ */
+type KeyValue<T extends object, K extends keyof T> = [K & keyof T, ExpandRecursively<T[K]>];
+
+/**
+ * Type utility which takes an object type and converts to an array of KV objects:
+ * ```ts
+ * // [ {key: "id", value: 123 } | {key: "foo", value: "bar" } ][]
+ * type Arr = KvFrom<{ id: 123, foo: "bar" }>;
+ * ```
+ */
+type KvFrom<T extends object> = Array<{
+    [K in keyof T]: {
+        key: K;
+        value: T[K];
+    };
+}[keyof T]>;
+
+/**
+ * **KvTuple**
+ *
+ * a key/value of type `T` represented as `[key, kv]`
+ *
+ * ```ts
+ * type Obj = { foo: 1, bar: "hi" };
+ * // ["foo", { foo: 1 } ]
+ * type Foo = KvTuple<Obj, "foo">;
+ * ```
+ *
+ * **Note:** _consider use of `KeyValue<T,K>` as an alternate representation_
+ */
+type KvTuple<T, K extends keyof T> = [K, Record<K, T[K]>];
+
+/**
+ * **entries**
+ *
+ * Provides an _iterable_ over the passed in dictionary object where each iteration
+ * provides a tuple of `[ key, value ]` which preserve type literals.
+ *
+ * For example:
+ * ```ts
+ * const obj = { foo: 1, bar: "hi" };
+ * // k type is "foo" then "bar"; v type is 1 then "hi"
+ * for (const [k, v] of entries(obj)) { ... }
+ * ```
+ */
+declare function entries<N extends Narrowable, T extends Record<string, N>, I extends KeyValue<T, keyof T>>(obj: T): {
+    [Symbol.iterator](): Generator<I, void, unknown>;
+};
+
+/**
+ * **mapValues**
+ *
+ * Maps over a dictionary, preserving the keys but allowing the values to be mutated.
+ *
+ * ```ts
+ * const colors = { red: 4, blue: 2, green: 3 };
+ * // { red: 8, blue: 4, green: 6 }
+ * const twoX = mapValues(colors, v => v * 2);
+ * ```
+ */
+declare function mapValues<N extends Narrowable, T extends Record<string, N>, V>(obj: T, valueMapper: (k: T[keyof T]) => V): { [K in keyof T]: V; };
+
+/**
+ * converts an array of strings `["a", "b", "c"]` into a more type friendly
+ * dictionary of the type `{ a: true, b: true, c: true }`
+ */
+declare function strArrayToDict<T extends readonly string[]>(...strings: T): ExpandRecursively<Record<T[number], true>>;
+
+/**
+ * Converts a dictionary object into an array of dictionaries with `key` and `value` properties
+ * ```ts
+ * // [ { key: "id", value: 123 }, { key: "foo", value: "bar" } ]
+ * const arr = dictToKv({ id: 123, foo: "bar" });
+ * ```
+ */
+declare function dictToKv<N extends Narrowable, T extends {
+    [key: string]: N;
+}, U extends boolean>(obj: T, _makeTuple?: U): U extends true ? UnionToTuple<(Mutable<T> extends infer T_1 extends object ? { [K in keyof T_1]: {
+    key: K;
+    value: Mutable<T>[K];
+}; } : never)[keyof T], LastInUnion<(Mutable<T> extends infer T_1 extends object ? { [K in keyof T_1]: {
+    key: K;
+    value: Mutable<T>[K];
+}; } : never)[keyof T]>> : KvFrom<Mutable<T>>;
+
+type DictArrayFilterCallback<K extends keyof T, T extends object, R extends true | false> = (key: K, value: Pick<T, K>) => R;
+/**
+ * An element in a `DictArray` shaped as a two element tuple: `[key, kv]`.
+ */
+type DictArrayKv<K extends keyof T, T> = [K, Pick<T, K>];
+type DictKvTuple<K extends string> = [K, Record<K, unknown>];
+/**
+ * A an array of `DictArrayKv` tuples which can be reconstructed
+ * to a strongly typed dictionary object.
+ * ```ts
+ * const example: DictArray<{ foo: 1, bar: "hi" }> = [
+ *   [ "foo", { foo: 1 }],
+ *   [ "bar", { bar: "hi" }]
+ * ]
+ * ```
+ */
+type DictArray<T> = Array<{
+    [K in keyof T]: DictArrayKv<K, T>;
+}[keyof T]>;
+
+/**
+ * Returns the _first_ key in an object.
+ *
+ * **Note:** key order is not guarenteed so typically this is used
+ * for a key/value pair where only one key is expected
+ */
+type FirstKey<T extends object> = UnionToTuple<Keys<T>>[0];
+
+/**
+ * Utility type which operates on a dictionary and provides the **value** of the
+ * `First<T>` key of the dictionary. Because dictionary's don't provide assurances
+ * about key order, this is typically only used in cases where it's known there is
+ * a single key on the object.
+ */
+type FirstKeyValue<T extends object> = FirstKey<T> extends keyof T ? T[FirstKey<T>] : never;
+
+/**
+ * For a two-dimensional array, returns a _union type_ which combines the first element of the interior
+ * array.
+ *
+ * ```ts
+ * const test = [ ["foo", 1], ["bar", 2] ];
+ * // "foo" | "bar"
+ * type F = FirstOfEach<typeof test>;
+ * ```
+ */
+type FirstOfEach<T extends readonly any[][]> = T[number][0] extends T[number][number] ? T[number][0] : never;
+
+/**
+ * Typescript utility which receives `T` as shape which resembles `DictArray<D>`
+ * and if the type `D` can be inferred it is returned.
+ * ```ts
+ * // { foo: 1; bar: "hi" }
+ * type Dict = FromDictArray<[["foo", { foo: 1 }], ["bar", { bar: "hi" }]]>;
+ * ```
+ */
+type FromDictArray<T extends [string, Record<string, unknown>][]> = ExpandRecursively<UnionToIntersection<T[number][1]>>;
+
+/**
+ * For a two-dimensional array, returns a _union type_ which combines the first element of the interior
+ * array.
+ *
+ * ```ts
+ * // 1 | 2
+ * type F = SecondOfEach<[ ["foo", 1], ["bar", 2] ]>;
+ * ```
+ */
+type SecondOfEach<T extends any[][]> = T[number][1] extends T[number][number] ? T[number][1] : never;
+
+interface Array$1<T> {
+    filter<U extends T>(pred: (a: T) => a is U): U[];
+}
+/**
+ * Accepts a `DictArray` and a callback which receives each key
+ * value pair.
+ */
+declare function filterDictArray<T extends object, C extends DictArrayFilterCallback<keyof T, T, true | false>>(dictArr: DictArray<T>, cb: C): DictArray<Omit<T, "">>;
+
+/**
+ * Build a key-value pair where both _key_ and _value_ are inferred. This
+ * includes ensuring that the _key_ is a type literal not just a "string".
+ *
+ * > note: the value will be inferred but if you need to constrain it
+ * > to a narrower type then both inferences will break and you should
+ * > instead use `KV2` to get this capability.
+ */
+declare function kv<K extends string, N extends Narrowable, V extends Record<any, N> | boolean | number | string | null | undefined>(key: K, value: V): ExpandRecursively<Record<K, V>>;
+
+/**
+ * Converts an array of dictionaries with `key` and `value` properties to a singular dictionary.
+ * ```ts
+ * // { id: 123, foo: "bar" }
+ * const arr = kvToDict([{ key: "id", value: 123 }, { key: "foo", value: "bar" }]);
+ * ```
+ *
+ * Note: this is the inverse of `dictToKv()` function
+ */
+declare function kvToDict<K extends string, V extends Narrowable, T extends readonly Readonly<{
+    key: K;
+    value: V;
+}>[]>(kvArr: T): DictFromKv<T>;
+
+/**
+ * Type utility which converts `undefined[]` to `unknown[]`
+ */
+type UndefinedArrayIsUnknown<T extends any[]> = undefined[] extends T ? unknown[] : T;
+type AsArray<T, W extends boolean = false> = T extends any[] ? W extends true ? Widen<T> : T : W extends true ? UndefinedArrayIsUnknown<Widen<T>[]> : UndefinedArrayIsUnknown<T[]>;
+/**
+ * Ensures that any input passed in is passed back as an array:
+ *
+ * - if it was already an array than this just serves as an _identity_ function
+ * - if it was not then it wraps the element into a one element array of the
+ * given type
+ *
+ * Note: by default the _type_ of values will be intentionally widened so that the value "abc"
+ * is of type `string` not the literal `abc`. If you want to keep literal types then
+ * change the optional _widen_ parameter to _false_.
+ */
+declare const asArray: <T extends Narrowable, W extends boolean = true>(thing: T, _widen?: W | undefined) => AsArray<T, W>;
+
+/**
+ * Groups an array of data based on the value of a property
+ * in the objects within the array.
+ * ```ts
+ * const data = [ {}, {}, {} ];
+ *
+ * ```
+ *
+ * @ignore not implemented
+ */
+declare function groupBy<T extends Record<string, Narrowable>>(_data: Readonly<T[]>): void;
+
+/**
+ * The basic shape of a `Converter`
+ */
+type ConverterShape<S extends Narrowable, N extends Narrowable, B extends Narrowable, O extends Narrowable> = {
+    string: <T extends string>(v: T) => S;
+    number: <T extends number>(v: T) => N;
+    boolean: <T extends boolean>(v: T) => B;
+    object: <T extends Record<string, any>>(v: T) => O;
+};
+type ConverterKeys<S, N, B, O> = UnionToTuple<Keys<DictionaryWithoutValue<{
+    string: S;
+    number: N;
+    boolean: B;
+    object: O;
+}, undefined>>>;
+type ConverterInputType<T extends string> = T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : T extends "object" ? Record<string, any> : unknown;
+type ConverterInputUnion<TConverted extends readonly any[], TRemaining extends readonly string[]> = [] extends TRemaining ? TConverted : ConverterInputUnion<[
+    ...TConverted,
+    ConverterInputType<First<TRemaining>>
+], AfterFirst<TRemaining>>;
+/**
+ * **AvailableConverters**
+ *
+ * Type utility which will produce the correct union type for a "converter"
+ */
+type AvailableConverters<S, N, B, O> = ConverterKeys<S, N, B, O> extends readonly string[] ? TupleToUnion<ConverterInputUnion<[], ConverterKeys<S, N, B, O>>> : never;
+
+/**
+ * **createConverter**(mapper)
+ *
+ * A runtime utility which allows for the creation of a function which
+ * receives multiple wide types (string, number, boolean, object) and then transform it
+ * based on the "wide type" but while retaining the potentially narrow values passed in.
+ *
+ * The number of wide types which the converter will accept is based on how it configured
+ * as there are discrete functions which must be passed in for handling: strings, numbers,
+ * booleans, and "objects" (aka, Record<string,any>).
+ *
+ * ```ts
+ * // handles strings and numbers
+ * const convert = createConverter({
+ *    string: s => `the string was ${s}`,
+ *    number: n => `the number was ${n}`,
+ * });
+ * ```
+ */
+declare function createConverter<S extends Narrowable = undefined, N extends Narrowable = undefined, B extends Narrowable = undefined, O extends Narrowable = undefined>(mapper: Partial<ConverterShape<S, N, B, O>>): <T extends AvailableConverters<S, N, B, O>>(input: T) => Widen<T> extends string ? S : Widen<Not<T, string>> extends number ? N : Widen<Not<Not<T, string>, number>> extends boolean ? B : Widen<Not<Not<Not<T, string>, number>, boolean>> extends {} ? O : unknown;
+
+type ExplicitFunction<P extends any[], R extends any> = (...args: P) => R;
+/**
+ * Takes a given function and converts it to an explicit representation
+ * where the generics represent the _parameter_ and _return_ typings.
+ */
+declare function ExplicitFunction<T extends (...args: any[]) => any>(fn: T): ExplicitFunction<Parameters<T>, ReturnType<T>>;
+
+/**
+ * **UniqueDictionary**
+ *
+ * A dictionary converted by `arrayToObject()` which expects each key `S` to have a only a
+ * single/unique value.
+ */
+type UniqueDictionary<S extends PropertyKey, N extends Narrowable, T extends Record<keyof T, N> & Record<S, any>> = {
+    [V in T as V[S]]: V;
+};
+/**
+ * **GeneralDictionary**
+ *
+ * A dictionary converted by `arrayToObject()` which expects each key `S` to have an
+ * array of values.
+ */
+type GeneralDictionary<S extends PropertyKey, N extends Narrowable, T extends Record<keyof T, N> & Record<S, any>> = {
+    [V in T as V[S]]: V[];
+};
+type ArrayConverter<S extends PropertyKey, U extends boolean> = 
+/**
+ * An `ArrayConverter` is the partial application of the `arrayToObject()`
+ * utility. At this point, the configuration is setup already and all that's
+ * left is to pass in an array of objects.
+ */
+<N extends Narrowable, T extends Record<keyof T, N> & Record<S, any>>(arr: readonly T[]) => true extends U ? UniqueDictionary<S, N, T> : GeneralDictionary<S, N, T>;
+/**
+ * Converts an array of objects into a dictionary by picking a property name contained
+ * by all objects and using that as the key to the dictionary.
+ *
+ * ```ts
+ * const arr = [
+ *   { kind: "color", favorite: "blue", likes: 100 },
+ *   { kind: "song", favorite: "some song", likes: 25 }
+ * ];
+ * const dict = arrayToObject("kind")(arr);
+ * ```
+ *
+ * This will produce a dictionary with keys of `color` and `song`.
+ */
+declare function arrayToObject<S extends PropertyKey, U extends boolean>(prop: S, unique?: U): ArrayConverter<S, true extends U ? true : false>;
+
+declare function ifSameType<TValue extends Narrowable, TType extends string | number | boolean | object, IF extends Narrowable, ELSE extends Narrowable>(value: TValue, comparisonType: TType, ifExtends: <T extends TType & TValue>(v: T) => IF, doesNotExtend: (v: Not<TValue, TType>) => ELSE): Widen<TValue> extends Widen<TType> ? IF : ELSE;
+
+declare function isArray<T>(i: T): IsArray<T>;
+/**
+ * **ifArray**(T, IF, ELSE)
+ *
+ * A utility which evaluates a type `T` for whether it is an array and then
+ */
+declare function ifArray<T extends Narrowable, IF extends Narrowable, ELSE extends Narrowable>(val: T, isAnArray: <N extends T & readonly any[]>(arr: N) => IF, isNotAnArray: <N extends Exclude<T, any[]>>(nonArr: N) => ELSE): IfArray<T, IF, ELSE>;
+declare function ifArrayPartial<T extends Narrowable>(): <IF extends Narrowable, ELSE extends Narrowable>(isAnArray: <N extends T & readonly any[]>(arr: N) => IF, isNotAnArray: <N_1 extends Exclude<T, any[]>>(nonArr: N_1) => ELSE) => <V extends T>(val: V) => IfArray<V, IF, ELSE>;
+
+/**
+ * Runtime and type checks whether a variable is a boolean value.
+ */
+declare function isBoolean<T extends Narrowable>(i: T): IsBoolean<T>;
+/**
+ * **ifBoolean**
+ *
+ * Strongly type-aware conditional statement which checks whether a value is
+ * a _boolean_ and returns one of two values (strongly typed) based on the evaluation
+ * of this criteria.
+ *
+ * @param val the value being tested
+ * @param ifVal the value (strongly typed) returned if val is _boolean_
+ * @param elseVal the value (strongly typed) returned if val is NOT a _boolean
+ */
+declare function ifBoolean<T, IF, ELSE>(val: T, ifVal: IF, elseVal: ELSE): IsBoolean<T> extends true ? IF : ELSE;
+
+declare function isFalse<T>(i: T): IsFalse<T>;
+/**
+ * **ifTrue**
+ *
+ * Strongly type-aware conditional statement which checks whether a value is
+ * a _true_ and returns one of two values (strongly typed) based on the evaluation
+ * of this criteria.
+ *
+ * @param val the value being tested
+ * @param ifVal the value (strongly typed) returned if val is _true_ value
+ * @param elseVal the value (strongly typed) returned if val is NOT a _true_ value
+ *
+ * Note: at runtime there's no way to distinguish if the value was widely or loosely
+ * typed so unlike the type utility there is no "MAYBE" state but if a wide type if
+ * encountered the _type_ will the union of `IF` and `ELSE`.
+ */
+declare function ifFalse<T extends boolean, IF extends Narrowable, ELSE extends Narrowable>(val: T, ifVal: IF, elseVal: ELSE): IfFalse<T, IF, ELSE, IF | ELSE>;
+
+type IsFunction<T> = T extends FunctionType ? true : false;
+type HybridFunction<TProps extends {}> = (<TArgs extends any[]>(...args: TArgs) => any) & TProps;
+type SimpleFunction = (...args: any[]) => any;
+type AnyFunction<TProps extends {} = {}> = SimpleFunction | HybridFunction<TProps>;
+/**
+ * Checks whether a passed in value is a function and ensures run-time and types
+ * are consistent.
+ * ```ts
+ * // true
+ * const yup = isFunction(() => "hello world");
+ * ```
+ *
+ * Note: the runtime `typeof [variable]` will correctly say "function" when a function is
+ * encountered but if that function also has object types defined then the type will be a big
+ * and ugly union type. This function will give you a proper boolean value in both cases.
+ */
+declare function isFunction<T>(input: T): IsFunction<T>;
+
+type IsNull<T> = T extends null ? true : false;
+declare function isNull<T extends Narrowable>(i: T): T extends null ? true : false;
+/**
+ * **ifNull**
+ *
+ * Strongly type-aware conditional statement which checks whether a value is
+ * Null and returns one of two values (strongly typed) based on the evaluation
+ * of this criteria.
+ *
+ * @param val the value being tested
+ * @param ifVal the value (strongly typed) returned if val is `null`
+ * @param elseVal the value (strongly typed) returned if val is NOT `null`
+ */
+declare function ifNull<T extends Narrowable, IF extends Narrowable, ELSE extends Narrowable>(val: T, ifVal: IF, elseVal: ELSE): IsNull<T> extends true ? IF : ELSE;
+
+type IsNumber<T> = T extends number ? true : false;
+declare function isNumber<T>(i: T): T extends number ? true : false;
+/**
+ * **ifNumber**
+ *
+ * Strongly type-aware conditional statement which checks whether a value is
+ * a _number_ and returns one of two values (strongly typed) based on the evaluation
+ * of this criteria.
+ *
+ * @param val the value being tested
+ * @param ifVal the value (strongly typed) returned if val is number
+ * @param elseVal the value (strongly typed) returned if val is NOT a number
+ */
+declare function ifNumber<T, IF, ELSE>(val: T, ifVal: IF, elseVal: ELSE): IsNumber<T> extends true ? IF : ELSE;
+
+type ObjectType = Not<Record<string, Narrowable>, FunctionType>;
+/**
+ * Detects whether the passed in `v` is of type "object" where an object
+ * is defined to be a string keyed dictionary style object. This means that
+ * arrays are excluded, as well as functions which also have properties hanging
+ * off of them.
+ */
+declare function isObject<T extends Narrowable>(i: T): IsObject<T>;
+declare function ifObject<T extends Narrowable, IF extends Narrowable, ELSE extends Narrowable>(val: T, ifObj: IF, notObj: ELSE): IfObject<T, IF, ELSE>;
+
+/**
+ * **IsString**
+ *
+ * Type utility which returns true/false based on whether `T` is a
+ * string (wide or narrow).
+ */
+type IsString<T> = T extends string ? true : false;
+/**
+ * **IfString**
+ *
+ * Type utility which determines if `T` is a _string_ (wide or narrow) and
+ * returns `IF` type if it is, otherwise returns the type `ELSE`.
+ */
+type IfString<T extends Narrowable, //
+IF extends Narrowable, ELSE extends Narrowable> = IsString<T> extends true ? IF : IsString<T> extends false ? ELSE : IF | ELSE;
+
+/**
+ * **isString**
+ *
+ * Returns true or false on whether the passed in parameter is a
+ * string (either a wide string or a string literal).
+ *
+ * The boolean return is traceable by the type system as well as the
+ * runtime system.
+ */
+declare function isString<T>(i: T): IsString<T>;
+/**
+ * **ifString**
+ *
+ * Strongly type-aware conditional statement which checks whether a value is
+ * a _string_ and returns one of two values (strongly typed) based on the evaluation
+ * of this criteria.
+ *
+ * @param val the value being tested for being a string
+ * @param ifVal the value (strongly typed) returned if val is _string_
+ * @param elseVal the value (strongly typed) returned if val is NOT a _string
+ */
+declare function ifString<T extends Narrowable, IF extends Narrowable, ELSE extends Narrowable>(val: T, ifVal: <E extends string>(t: E & T) => IF, elseVal: ELSE): IfString<T, IF, ELSE>;
+
+declare function isSymbol<T>(i: T): T extends symbol ? true : false;
+
+/**
+ * Run-time and type checking of whether a variable is `true`.
+ */
+declare function isTrue<T extends Narrowable>(i: T): IsTrue<T>;
+/**
+ * **ifTrue**
+ *
+ * Strongly type-aware conditional statement which checks whether a value is
+ * _true_.
+ *
+ * @param val the value being tested
+ * @param ifVal the value (strongly typed) returned if val is _true_ value
+ * @param elseVal the value (strongly typed) returned if val is NOT a _true_ value
+ *
+ * Note: at runtime there's no way to distinguish if the value was widely or loosely
+ * typed so unlike the type utility there is no "MAYBE" state but if a wide type if
+ * encountered the _type_ will the union of `IF` and `ELSE`.
+ */
+declare function ifTrue<T extends boolean, IF extends Narrowable, ELSE extends Narrowable>(val: T, ifVal: IF, elseVal: ELSE): IfTrue<T, IF, ELSE, IF | ELSE>;
+
+declare function isUndefined<T extends Narrowable>(i: T): undefined extends T ? true : false;
+/**
+ * **ifUndefined**
+ *
+ * Strongly type-aware conditional statement which checks whether a value is
+ * _undefined_ and returns one of two values (strongly typed) based on the evaluation
+ * of this criteria.
+ *
+ * @param val the value being tested
+ * @param ifVal the value (strongly typed) returned if val is `undefined`
+ * @param elseVal the value (strongly typed) returned if val is NOT `undefined`
+ */
+declare function ifUndefined<T extends Narrowable, IF extends Narrowable, ELSE extends Narrowable>(val: T, ifVal: IF, elseVal: ELSE): IsUndefined<T> extends true ? IF : ELSE;
+declare function ifDefined<T extends Narrowable, IF extends Narrowable, ELSE extends Narrowable>(val: T, ifVal: <V extends Exclude<T, undefined>>(v: V) => IF, elseVal: ELSE): IsUndefined<T> extends true ? IF : ELSE;
+
+interface Box<T> {
+    __kind: "box";
+    value: T;
+    /**
+     * Unbox the boxed value in the narrowest possible type.
+     *
+     * **note:** if the boxed value is a function with parameters you
+     * can pass the parameters directly into the `b.unbox(params)` call.
+     */
+    unbox: HasParameters<Box<T>["value"]> extends true ? Box<T>["value"] extends AnyFunction ? Box<T>["value"] extends (...args: infer A) => infer R ? <N extends A>(...args: N) => R : () => ReturnType<T> : () => T : () => T;
+}
+type BoxValue<T extends Box<any>> = T extends Box<infer V> ? V : never;
+type BoxedFnParams<T extends Box<any>> = T extends Box<infer V> ? V extends (...args: infer A) => any ? A : [] : [];
+type BoxedReturn<T extends Box<any>> = T extends Box<infer V> ? V extends Function ? ReturnType<T["value"]> : T["value"] : never;
+type NarrowBox<T> = <N extends BoxedFnParams<Box<T>> | First<BoxedFnParams<Box<T>>>>() => N extends BoxedFnParams<Box<T>> ? T extends (...args: any[]) => any ? (...args: N) => Box<T>["unbox"] : never : (first: N, ...rest: AfterFirst<BoxedFnParams<Box<T>>>) => BoxedReturn<Box<T>>;
+/**
+ * Allows a value with an inner-type to be boxed into a dictionary
+ * so that this type inference is preserved with the help of
+ * [instantiation expressions](https://devblogs.microsoft.com/typescript/announcing-typescript-4-7-beta/#instantiation-expressions).
+ *
+ * NOTE: this feature is immature at best right now
+ */
+declare function box<T extends Narrowable>(value: T): Box<T>;
+declare function isBox(thing: Narrowable): thing is Box<any>;
+/**
+ * **boxDictionaryValues**(dict)
+ *
+ * Runtime utility which boxes each value in a dictionary
+ */
+declare function boxDictionaryValues<T extends {}>(dict: T): { [K in keyof T]: Box<T[K]>; };
+type Unbox<T> = T extends Box<infer U> ? U : T;
+/**
+ * **unbox**(maybeBox)
+ *
+ * Unboxes a value if it was a box; otherwise it leaves _as is_.
+ */
+declare function unbox<T>(val: T): Unbox<T>;
+
+/**
+ * Build a _type_ from two run-time dictionaries.
+ *
+ * 1. The _first_ -- which is optional -- is interpreted as a _literal_ type definition
+ * 2. The _second_ dictionary is interpreted as a "wide" definition of prop types
+ */
+declare function defineType<N extends Narrowable, TLiteral extends Record<string, N>>(literal?: TLiteral): <TWide extends object>(wide?: TWide) => ExpandRecursively<TWide & TLiteral>;
+
+/**
+ * An identity function for any type, with the goal of preserving literal type information
+ * whereever possible.
+ */
+declare const identity: <N extends Narrowable, T extends string | number | boolean | symbol | Record<any, N> | null | undefined>(v: T) => T;
+
+/**
+ * Takes an object as input --which has an `id` property and returns it as the same
+ * run-time content but with the _type_ of the `id` property being forced to a literal type
+ */
+declare function idLiteral<T extends {
+    id: I;
+}, I extends PropertyKey>(o: T): T & {
+    id: T["id"];
+};
+/**
+ * Takes an object as input --which has an `name` property and returns it as the same
+ * run-time content but with the _type_ of the `name` property being forced to a literal type
+ */
+declare function nameLiteral<T extends {
+    name: I;
+}, I extends PropertyKey>(o: T): T & {
+    name: T["name"];
+};
+/**
+ * Takes an object as input --which has an `kind` property and returns it as the same
+ * run-time content but with the _type_ of the `kind` property being forced to a literal type
+ */
+declare function kindLiteral<T extends {
+    kind: I;
+}, I extends PropertyKey>(o: T): T & {
+    kind: T["kind"];
+};
+declare function idTypeGuard<T extends {
+    id: I;
+}, I extends PropertyKey>(_o: T): _o is T & {
+    id: I;
+};
+/**
+ * Takes an object as input and infers the narrow literal types of the property
+ * values on the object.
+ *
+ * > Note: this addresses this [a known TS gap](https://github.com/microsoft/TypeScript/issues/30680).
+ * > Hopefully at some point this will be addressed in the language.
+ */
+declare function literal<N extends Narrowable, T extends Record<keyof T, N>>(obj: T): T;
+
+/**
+ * **StripEnding**`<T, U>`
+ *
+ * Will strip off of `T` the ending defined by `U` when
+ * both are string literals.
+ * ```ts
+ * type T = "Hello World";
+ * type U = " World";
+ * // "Hello"
+ * type R = StripEnding<T,U>;
+ * ```
+ */
+type StripTrailing<T extends string, U extends string> = IfLiteral<T, string extends U ? never : T extends `${infer Before}${U}` ? Before : T, string>;
+
+/**
+ * **stripTrailing**(content, strip)
+ *
+ * Runtime utility which ensures that last part of a string has substring
+ * removed if it exists and that strong typing is preserved.
+ */
+declare function stripTrailing<T extends string, U extends string>(content: T, strip: U): StripTrailing<T, U>;
+
+/**
+ * **EnsureTrailing**`<T, U>`
+ *
+ * Will ensure that `T` ends with the substring `U` when
+ * both are string literals.
+ *
+ * ```ts
+ * type T = "Hello";
+ * type U = " World";
+ * // "Hello World"
+ * type R = EnsureTrailing<T,U>;
+ * ```
+ */
+type EnsureTrailing<T extends string, U extends string> = IfLiteral<T, string extends U ? never : T extends `${string}${U}` ? T : `${T}${U}`, string>;
+
+/**
+ * **ensureTrailing**(content, strip)
+ *
+ * Runtime utility which ensures that last part of a string -- `content` -- has the
+ * substring `ensure` at the end and adds it if not present.
+ */
+declare function ensureTrailing<T extends string, U extends string>(content: T, ensure: U): EnsureTrailing<T, U>;
+
+/**
+ * Indicates whether `T` has _all_ uppercase characters in it.
+ * ```ts
+ * // true
+ * type T = AllCaps<"FOOBAR">;
+ * // false
+ * type T = AllCaps<"FooBar">;
+ * // "unknown"
+ * type T = AllCaps<string>;
+ * ```
+ */
+type AllCaps<T extends string> = string extends T ? "unknown" : T extends Uppercase<T> ? true : false;
+
+/**
+ * **Break<T,D>**
+ *
+ * Takes a string `T`, and splits it into a tuple of the form `[F, R]`.
+ * ```ts
+ * // ["the", " long and winding road"]
+ * type T1 = Break<"the long and winding road", " ">;
+ * // ["there", " I was, there I was"]
+ * type T2 = Break<"there I was, there I was", " ">;
+ * ```
+ */
+type Break<T extends string, D extends string> = (string extends T ? [string, string] : (T extends `${infer F}${D}${infer _R}` ? (F extends `${infer _X}${D}${infer _Y}` ? never : (T extends `${F}${infer R}` ? [F, R] : never)) : [T, ""]));
+
+/**
+ * Concatenates two arrays (of literals).
+ * ```ts
+ * // [ "foo", "bar", "baz" ]
+ * type T = ArrConcat<["foo"], ["bar", "baz"]>;
+ * ```
+ */
+type ArrConcat<A extends any[], B extends any[]> = [...A, ...B];
+
+/**
+ * Type utility which takes a string `S` and replaces the substring `W` with `P`.
+ * ```ts
+ * const fooy = "fooy";
+ * // "Foo"
+ * type Foo = Replace<typeof fooy, "y", "">;
+ * ```
+ *
+ * Note: _the first match is replaced and all subsequent matches are ignored_
+ */
+type Replace<S extends string, W extends string, P extends string> = S extends "" ? "" : W extends "" ? S : S extends `${infer F}${W}${infer E}` ? `${F}${P}${E}` : S;
+
+/**
+ * Trims off whitespace on left of string
+ * ```ts
+ * // "foobar "
+ * type T = TrimLeft<"\n\t  foobar ">;
+ * // string
+ * type T = TrimLeft<string>;
+ * ```
+ */
+type TrimLeft<S extends string> = string extends S ? string : S extends `${Whitespace}${infer Right}` ? TrimLeft<Right> : S;
+
+/**
+ * Provides the _left_ whitespace of a string
+ * ```ts
+ * // "\n\t "
+ * type T = LeftWhitespace<"\n\t foobar">;
+ * ```
+ */
+type LeftWhitespace<S extends string> = string extends S ? string : Replace<S, TrimLeft<S>, "">;
+
+/**
+ * Trims off whitespace on left of string
+ * ```ts
+ * // "\n foobar"
+ * type T = TrimRight<"\n foobar \t">;
+ * // string
+ * type T = TrimRight<string>;
+ * ```
+ */
+type TrimRight<S extends string> = string extends S ? string : S extends `${infer Right}${Whitespace}` ? TrimRight<Right> : S;
+
+/**
+ * Provides the _left_ whitespace of a string
+ * ```ts
+ * // "\n\t "
+ * type T = LeftWhitespace<"\n\t foobar">;
+ * ```
+ */
+type RightWhitespace<S extends string> = string extends S ? string : Replace<S, TrimRight<S>, "">;
+
+/**
+ * Type utility that provides the _length_ of a given string type in a way which
+ * is _not_ limited to TS's recursive string length of roughly 48.
+ *
+ * ```ts
+ * // 3
+ * type Three = StringLength<"foo">;
+ * ```
+ */
+type StringLength<S extends string, R extends number[] = []> = S extends `${infer _First}${infer _Second}${infer _Third}${infer _Fourth}${infer _Fifth}${infer _Sixth}${infer _Sevebnth}${infer _Eighth}${infer _Ninth}${infer _Tenth}${infer Rest}` ? StringLength<Rest, [...R, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]> : S extends `${infer _First}${infer _Second}${infer _Third}${infer _Fourth}${infer _Fifth}${infer _Sixth}${infer _Sevebnth}${infer _Eighth}${infer _Ninth}${infer Rest}` ? StringLength<Rest, [...R, 1, 1, 1, 1, 1, 1, 1, 1, 1]> : S extends `${infer _First}${infer _Second}${infer _Third}${infer _Fourth}${infer _Fifth}${infer _Sixth}${infer _Sevebnth}${infer _Eighth}${infer Rest}` ? StringLength<Rest, [...R, 1, 1, 1, 1, 1, 1, 1, 1]> : S extends `${infer _First}${infer _Second}${infer _Third}${infer _Fourth}${infer _Fifth}${infer _Sixth}${infer _Sevebnth}${infer Rest}` ? StringLength<Rest, [...R, 1, 1, 1, 1, 1, 1, 1]> : S extends `${infer _First}${infer _Second}${infer _Third}${infer _Fourth}${infer _Fifth}${infer _Sixth}${infer Rest}` ? StringLength<Rest, [...R, 1, 1, 1, 1, 1, 1]> : S extends `${infer _First}${infer _Second}${infer _Third}${infer _Fourth}${infer _Fifth}}${infer Rest}` ? StringLength<Rest, [...R, 1, 1, 1, 1, 1]> : S extends `${infer _First}${infer _Second}${infer _Third}${infer _Fourth}${infer Rest}` ? StringLength<Rest, [...R, 1, 1, 1, 1]> : S extends `${infer _First}${infer _Second}${infer _Third}${infer Rest}` ? StringLength<Rest, [...R, 1, 1, 1]> : S extends `${infer _First}${infer _Second}${infer Rest}` ? StringLength<Rest, [...R, 1, 1]> : S extends `${infer _First}${infer Rest}` ? StringLength<Rest, [...R, 1]> : [...R]["length"];
+
+/**
+ * Trims off blank spaces, `\n` and `\t` characters from both sides of a _string literal_.
+ * ```ts
+ * // "foobar"
+ * type T = Trim<"\n\t  foobar ">;
+ * // string
+ * type T = Trim<string>;
+ * ```
+ */
+type Trim<S extends string> = string extends S ? string : S extends `${Whitespace}${infer Right}` ? Trim<Right> : S extends `${infer Left}${Whitespace}` ? Trim<Left> : S;
+
+/**
+ * An email address
+ */
+type Email = `${string}@${string}.${string}`;
+type Zip5 = `${NumericString}${NumericString}${string}${NumericString}`;
+type Zip4 = `${NumericString}${string}`;
+/**
+ * A relatively strong type for Zip5 or Zip5+4 zip codes
+ */
+type ZipCode = Zip5 | `${Zip5}-${Zip4}`;
+
+/**
+ * If **ALL CAPS** it converts to all lowercase; if not then it does nothing */
+type LowerAllCaps<T extends string> = AllCaps<T> extends true ? Lowercase<T> : T;
+
+type Delimiter = "_" | "-" | " ";
+/** convert all delimiters to dashes */
+type DashDelim<T extends string> = T extends `${infer Begin}${" "}${infer Rest}` ? DashDelim<`${Begin}-${Rest}`> : T extends `${infer Begin}${"_"}${infer Rest}` ? DashDelim<`${Begin}-${Rest}`> : T;
+/**
+ * Converts a string literal type to a **PascalCase** representation.
+ * ```ts
+ * // "FooBar"
+ * type T = PascalCase<"fooBar">;
+ * type T = PascalCase<"foo-bar">;
+ * type T = PascalCase<"foo_bar">;
+ * type T = PascalCase<"\n foo_bar \t">;
+ * ```
+ */
+type PascalCase<S extends string> = string extends S ? string : Trim<DashDelim<LowerAllCaps<S>>> extends `${infer Begin}${Delimiter}${infer Rest}` ? PascalCase<`${Capitalize<Begin>}${Capitalize<Rest>}`> : Capitalize<Trim<LowerAllCaps<S>>>;
+
+type CamelCase<S extends string> = string extends S ? string : Uncapitalize<PascalCase<S>>;
+
+/**
+ * Capitalize all words in a string
+ */
+type CapitalizeWords<S extends string> = S extends `${infer L} ${infer R}` ? `${CapitalizeWords<L>} ${CapitalizeWords<R>}` : S extends `${infer L},${infer R}` ? `${CapitalizeWords<L>},${CapitalizeWords<R>}` : S extends `${infer L}.${infer R}` ? `${CapitalizeWords<L>}.${CapitalizeWords<R>}` : Capitalize<S>;
+
+type DashToSnake<T extends string> = T extends `${infer HEAD}-${infer TAIL}` ? DashToSnake<`${HEAD}_${TAIL}`> : T;
+
+/**
+ * Indicates whether `T` has uppercase characters in it.
+ * ```ts
+ * // true
+ * type T = HasUppercase<"Foobar">;
+ * // false
+ * type T = HasUppercase<"foobar">;
+ * // "unknown"
+ * type T = HasUppercase<string>;
+ * ```
+ */
+type HasUppercase<T extends string> = string extends T ? "unknown" : T extends `${string}${UpperAlpha}${string}` ? true : false;
+
+type _DU<T extends string> = T extends Lowercase<T> ? T : `-${Lowercase<T>}`;
+/**
+ * Converts uppercase characters to a dash and then the lowercase equivalent
+ * ```ts
+ * // "one-two-three"
+ * type T = DashUppercase<"oneTwoThree">;
+ * ```
+ *
+ * _Intended to be used as a lower level utility; prefer `Dasherize<T>` for more full-fledged
+ * dash solution_.
+ */
+type DashUppercase<T extends string> = HasUppercase<T> extends false ? T : T extends `${infer C0}${infer C1}${infer R}` ? `${_DU<C0>}${_DU<C1>}${DashUppercase<R>}` : T extends `${infer C0}${infer R}` ? `${_DU<C0>}${DashUppercase<R>}` : "";
+
+type OneToOne = `1:1`;
+type OneToMany = `1:M`;
+type OneToZero = `1:0`;
+type ZeroToOne = `0:1`;
+type ZeroToMany = `0:M`;
+type ZeroToZero = `0:0`;
+type ManyToMany = "M:M";
+type ManyToOne = "M:1";
+type ManyToZero = "M:0";
+type CardinalityNode = "0" | "1" | "M";
+/**
+ * Cardinality which expects a singular input and requires
+ * 1 or many outputs.
+ *
+ * Note: choose `CardinalityFilter1` if you want to allow output
+ * to have no outputs.
+ */
+type Cardinality1 = OneToOne | OneToMany;
+/**
+ * Cardinality which expects a singular input and maps to 0,
+ * 1, or many outputs.
+ */
+type CardinalityFilter1 = OneToOne | OneToMany | OneToZero;
+/**
+ * Cardinality which expects a singular input which is allowed to be
+ * _undefined_ or the expected type.
+ */
+type Cardinality0 = ZeroToOne | ZeroToMany | OneToOne | OneToMany;
+/**
+ * Cardinality which expects a singular input -- which is allowed to be
+ * _undefined_ -- and maps to 0,
+ * 1, or many outputs.
+ */
+type CardinalityFilter0 = ZeroToOne | ZeroToMany | OneToOne | OneToMany | OneToZero | ZeroToZero;
+type CardinalityExplicit = `${number}:${number}`;
+/**
+ * Cardinality of any sort between two types
+ */
+type Cardinality = CardinalityFilter0 | CardinalityFilter1 | ManyToMany | ManyToOne | ManyToZero | CardinalityExplicit;
+type CardinalityTuple<T extends Cardinality> = UnionToTuple<T>;
+/**
+ * The first or _input_ part of the Cardinality relationship
+ */
+type CardinalityIn<T extends Cardinality> = T extends `${infer IN}:${string}` ? IN : never;
+/**
+ * The second or _output_ part of the Cardinality relationship
+ */
+type CardinalityOut<T extends Cardinality> = T extends `${string}:${infer OUT}` ? OUT : never;
+type CardinalityInput<T, C extends Cardinality> = CardinalityTuple<C>[0] extends 0 ? T | undefined : CardinalityTuple<C>[0] extends 1 ? T : T[];
+
+/**
+ * Converts a string literal into a _dasherized_ format while ignoring _exterior_ whitespace.
+ *
+ * ```ts
+ * // "foo-bar"
+ * type Dash = Dasherize<"foo_bar">;
+ * type Dash = Dasherize<"fooBar">;
+ * type Dash = Dasherize<"FooBar">;
+ * // "\n  foo-bar \t"
+ * type Dash = Dasherize<"\n  foo bar \t">;
+ * ```
+ */
+type Dasherize<S extends string> = string extends S ? string : DashUppercase<Trim<LowerAllCaps<S>>> extends `${infer Begin}${"_" | " "}${infer Rest}` ? Dasherize<`${Lowercase<Begin>}-${Rest}`> : Lowercase<DashUppercase<Uncapitalize<Trim<LowerAllCaps<S>>>>>;
+
+/**
+ * **EnsureLeading**`<T, U>`
+ *
+ * Will ensure that `T` ends with the _substring_ `U` when
+ * both are string literals.
+ *
+ * ```ts
+ * type T = " World";
+ * type U = "Hello";
+ * // "Hello World"
+ * type R = EnsureLeading<T,U>;
+ * ```
+ */
+type EnsureLeading<T extends string, U extends string> = IfLiteral<T, string extends U ? never : T extends `${U}${string}` ? T : `${U}${T}`, string>;
+
+/**
+ * Returns true or false value based on whether the string literal is capitalized.
+ * ```ts
+ * // true
+ * type T2 = IsCapitalized<"One">;
+ * // false
+ * type T1 = IsCapitalized<"one">;
+ * // "unknown"
+ * const a: string = "Hi";
+ * type T3 = IsCapitalized<typeof a>;
+ * ```
+ *
+ * Note: _if the value passed in is a "string" then the result will be "unknown"_
+ */
+type IsCapitalized<T extends string> = string extends T ? "unknown" : T extends Capitalize<T> ? true : false;
+
+/**
+ * **KebabCase<T>** is an _alias_ for **Dasherize<T>**.
+ * ```ts
+ * // "foo-bar"
+ * type Kebab = KebabCase<"foo_bar">;
+ * type Kebab = KebabCase<"fooBar">;
+ * type Kebab = KebabCase<"FooBar">;
+ * // "\n  foo-bar \t"
+ * type Kebab = KebabCase<"\n  foo bar \t">;
+ * ``` */
+type KebabCase<T extends string> = Dasherize<T>;
+
+/**
+ * **StripStarting**`<T, U>`
+ *
+ * Will strip off of `T` the starting string defined by `U` when
+ * both are string literals.
+ * ```ts
+ * type T = "Hello World";
+ * type U = "Hello ";
+ * // "World"
+ * type R = StripStarting<T,U>;
+ * ```
+ */
+type StripLeading<T extends string, U extends string> = IfLiteral<T, string extends U ? never : T extends `${U}${infer After}` ? After : T, string>;
+
+/**
+ * **PathJoin**`<T,U>`
+ *
+ * Type utility meant to bring 2 or more "path" strings together into
+ * a valid "path". Where a "path" is represented as nothing more than
+ * string characters delimited by a Posix `\` character.
+ *
+ * Note that the first part of the path will retain it's `\` if present
+ * and the last one will preserve it's `\` character if present. You can
+ * combine this utility with `EnsureTrailing<T>`, `StripTrailing<T>`,
+ * `EnsureStarting<T>`, and `StripStarting<T>` to further shape
+ * the type.
+ */
+type PathJoin<T extends string, U extends string | readonly string[]> = [] extends U ? T : U extends readonly string[] ? PathMultiJoin<PathJoin<T, "">, [...U]> : U extends string ? IfLiteral<T, IfLiteral<U, `${StripTrailing<T, "/">}/${StripLeading<U, "/">}`, `${StripTrailing<T, "/">}/${string}`>, IfLiteral<U, `${string}${U}`, string>> : never;
+type PathMultiJoin<TProcessed extends string, TRemaining extends readonly string[]> = [] extends TRemaining ? TProcessed : PathMultiJoin<PathJoin<TProcessed, First<TRemaining>>, AfterFirst<TRemaining>>;
+
+type Consonant = "b" | "c" | "d" | "f" | "g" | "h" | "j" | "k" | "l" | "m" | "n" | "p" | "q" | "r" | "s" | "t" | "v" | "w" | "x" | "z" | "y";
+type Exceptions = "photo => photos" | "piano => pianos" | "halo => halos" | "foot => feet" | "man => men" | "woman => women" | "person => people" | "mouse => mice" | "series => series" | "sheep => sheep" | "money => monies" | "deer => deer";
+type SingularException<T = Exceptions> = T extends `${infer SINGULAR} => ${infer PLURAL}` ? SINGULAR : never;
+type PluralException<T extends SingularException, E extends Exceptions = Exceptions> = E extends `${T} => ${infer PLURAL}` ? PLURAL : never;
+type SingularNoun = "s" | "sh" | "ch" | "x" | "z" | "o";
+type F = "f" | "fe";
+type Y = `${Consonant}y`;
+type RemoveTrailingY<T> = T extends `${infer HEAD}y` ? HEAD : T;
+/** validates that a word ends with a pluralization exception */
+type isException<T extends string> = T extends SingularException ? T : never;
+/** validates that a string literal ends in "is" */
+type EndsIn_IS<T extends string> = T extends `${infer HEAD}is` ? T : never;
+/** validates that a string literal is a singular noun */
+type EndsInSingularNoun<T extends string> = T extends `${infer HEAD}${SingularNoun}` ? T : never;
+/** validates that a string literal ends in "f" or "fe" */
+type EndsIn_F<T extends string> = T extends `${infer HEAD}${F}` ? T : never;
+/** validates that a string literal ends a consonant followed by "y" */
+type EndsIn_Y<T extends string> = T extends `${infer HEAD}${Y}` ? T : never;
+/**
+ * strings which end in the letters "is" should have an "es" added to the end
+ */
+type PluralizeEndingIn_IS<T extends string> = T extends `${infer HEAD}is` ? `${HEAD}ises` : T;
+/**
+ * singular nouns should have "es" added to the end
+ */
+type PluralizeEndingSingularNoun<T extends string> = T extends `${infer HEAD}${SingularNoun}` ? `${T}es` : T;
+/**
+ * strings which end in the letters "f" or "fe" should have "ves" replace the ending
+ */
+type PluralizeEnding_F<T extends string> = T extends `${infer HEAD}${F}` ? `${HEAD}ves` : T;
+/**
+ * singular nouns should have "es" added to the end
+ */
+type PluralizeEndingIn_Y<T extends string> = T extends `${infer HEAD}${Y}` ? `${RemoveTrailingY<T>}ies` : T;
+type Pluralize<T extends string> = T extends isException<T> ? PluralException<T> : T extends EndsIn_IS<T> ? PluralizeEndingIn_IS<T> : T extends EndsInSingularNoun<T> ? PluralizeEndingSingularNoun<T> : T extends EndsIn_F<T> ? PluralizeEnding_F<T> : T extends EndsIn_Y<T> ? PluralizeEndingIn_Y<T> : `${T}s`;
+
+/** convert space to dash */
+type SpaceToDash<T extends string> = T extends `${infer Begin}${" "}${infer Rest}` ? SpaceToDash<`${Begin}-${Rest}`> : T;
+/**
+ * Converts a string literal type to _snake_case_.
+ * ```ts
+ * // "foo_bar"
+ * type T = SnakeCase<"fooBar">;
+ * type T = SnakeCase<"FooBar">;
+ * type T = SnakeCase<"foo-bar">;
+ * type T = SnakeCase<"\n foo bar \t">;
+ * ``` */
+type SnakeCase<S extends string> = string extends S ? string : DashUppercase<Uncapitalize<SpaceToDash<Trim<LowerAllCaps<S>>>>> extends `${infer Begin}${"-"}${infer Rest}` ? SnakeCase<`${Lowercase<Begin>}_${Rest}`> : Lowercase<DashUppercase<Uncapitalize<Trim<LowerAllCaps<S>>>>>;
+
+type NetworkProtocol = "http" | "https" | "file" | "ws" | "wss";
+/**
+ * A literal variant of _string_ which is meant to represent a domain name
+ * (e.g., `www.someplace.com`, etc.)
+ */
+type DomainName = `${AlphaNumeric}${string}.${AlphaNumeric}${string}` | `${AlphaNumeric}${string}.${AlphaNumeric}${string}.${string}` | `${AlphaNumeric}${string}.${AlphaNumeric}${string}.${string}.${string}`;
+type RelativeUrl = `${VariableName | "/"}`;
+/**
+ * A literal variant of _string_ which forces a string to follow conventions
+ * for a fully qualified URL like `https://google.com`. It can't ensure the
+ * type is fully valid but does help to avoid some typos.
+ */
+type FullyQualifiedUrl = `${NetworkProtocol}://${Ipv4 | DomainName}/${string}`;
+type UrlBuilder = (<P extends NetworkProtocol, D extends DomainName, B extends RelativeUrl>(protocol: P, domain: D, basePath: B) => `${P}://${D}/${B}`) | (<U extends RelativeUrl>(url: U) => U);
+
+/**
+ * **ensureLeading**(content, strip)
+ *
+ * Runtime utility which ensures that last part of a string -- `content` -- has the
+ * substring `ensure` at the end and adds it if not present.
+ */
+declare function ensureLeading<T extends string, U extends string>(content: T, ensure: U): EnsureLeading<T, U>;
+
+/**
+ * **pathJoin**`<T,U>(begin, ...rest)`
+ *
+ * Run time utility which joins two strings together with
+ * the intent to have them be divided by a Posix `/` character
+ * appropriate for Unix file paths and URLs.
+ *
+ * **note:** to support more than two paths being joined there
+ * is now the ability to add a tuple of paths into the _rest_
+ * parameter
+ */
+declare function pathJoin<T extends string, U extends readonly string[]>(begin: T, ...rest: U): PathJoin<T, U>;
+
+/**
+ * **Suggest**
+ *
+ * Type utility that helps to build a enumerated set
+ * of string literals which _could_ be the value for
+ * a string based property but _allows_ a string that
+ * is not part of the suggestion to be typed in too.
+ */
+type Suggest<T extends string> = T | (string & {});
+/**
+ * **SuggestNumeric**`<T>`
+ *
+ * Type utility that helps to build a enumerated set
+ * of numeric literals which _could_ be the value for
+ * a number based property but _allows_ a number that
+ * is not part of the suggestion to be typed in too.
+ */
+type SuggestNumeric<T extends number> = T | (number & {});
+
+/**
+ * **wide**
+ *
+ * Provides a dictionary of _wide_ types
+ */
+declare const wide: {
+    readonly boolean: boolean;
+    readonly string: string;
+    readonly number: number;
+    readonly symbol: Symbol;
+    readonly null: null;
+    readonly undefined: undefined;
+};
+
+type Condition<TInput extends Narrowable, TResult extends boolean> = (input: TInput) => TResult;
+declare const condition: <TInput extends Narrowable, C extends Condition<Narrowable, boolean>>(c: C, input: TInput) => boolean;
+
+/**
+ * **TypeGuard**
+ *
+ * a typing for a **TS** type-guard which evaluates an _unknown_ input
+ * and determines if it is of type `T`.
+ */
+type TypeGuard<T> = (thing: unknown) => thing is T;
+
+type Type<T extends any, V extends Function> = {
+    name: string;
+    type: T;
+    typeGuard: TypeGuard<T>;
+    is: V;
+};
+declare const typeApi: () => {
+    readonly string: Type<string, typeof isString>;
+    readonly boolean: Type<boolean, typeof isBoolean>;
+    readonly number: Type<number, typeof isNumber>;
+    readonly function: Type<Function | (Function & {
+        [key: string]: any;
+    }), typeof isFunction>;
+    readonly null: Type<null, typeof isNull>;
+    readonly symbol: Type<symbol, typeof isSymbol>;
+    readonly undefined: Type<undefined, typeof isUndefined>;
+    readonly true: Type<true, typeof isTrue>;
+    readonly false: Type<false, typeof isFalse>;
+    readonly object: Type<Record<string, Narrowable>, typeof isObject>;
+    readonly array: Type<any[], typeof isArray>;
+};
+type TypeApi = ReturnType<typeof typeApi>;
+declare function isType<T extends any, V extends Function>(t: unknown): t is Type<T, V>;
+type TypeDefinition<T extends any, V extends Function> = (defn: TypeApi) => Type<T, V>;
+declare function type<T extends any, V extends Function>(fn: TypeDefinition<T, V>): Type<T, V>;
+
+/**
+ * **withValue**
+ *
+ * Reduces a dictionary object -- in both _type_ and _run-time_ structure -- to only those
+ * key/value pairs which have a specified value. For instance:
+ *
+ * ```ts
+ * const obj = { foo: 1, bar: 2, message: "hi there" };
+ * // { message: "hi there" }
+ * const onlyStrings = withValue(t => t.string)(obj);
+ * // { foo: 1 }
+ * const justOne = withValue(t => t.literal(1))(obj);
+ * ```
+ *
+ * Note: _often useful to provide run-time type profiles with the_ `inferredType` _utility_
+ */
+declare function withValue<T extends any, V extends Function>(td: TypeDefinition<T, V>): <N extends Narrowable, R extends Record<string, N>>(obj: R) => ExpandRecursively<Pick<R, KeysWithValue<T, R>>>;
+
+type Omit$1<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
+interface IConfigurator<C = {}> {
+    set<V, K extends string, KV = {
+        [U in K]: V;
+    }>(key: K, value: V): asserts this is IConfigurator<ExpandRecursively<C & KV>>;
+    remove<K extends string & keyof C>(key: K): asserts this is IConfigurator<ExpandRecursively<Omit$1<C, K>>>;
+    done(): C;
+}
+/**
+ * **Configurator**
+ *
+ * This function provides a configurator which uses TypeScript assertions
+ * to narrow the scope of variables. Using type assertions though means we
+ * can't also return values and therefore a _fluent_ API style is not possible.
+ *
+ * Note: this approach does require, that you explicitly use the `IConfigurator`
+ * interface exported by this library. Without it you'd getting annoying TS errors
+ * on every call to `set()` but adding it is simple enough:
+ *
+ * ```ts
+ * import { Configurator, IConfigurator } from "inferred-types";
+ * const config: IConfigurator = Configurator();
+ * ```
+ *
+ * If you want to specify some guideline params which you expect to be set, you
+ * can add them like so:
+ *
+ * ```ts
+ * export type IExpected = { foo: number, bar: string };
+ * const config: IConfigurator<IExpected> = Configurator<IExpected>();
+ * ```
+ *
+ * This configuration will ensure that `foo` and `bar` will be seen as optional
+ * parameters. If you set them they will stop being optional.
+ */
+declare function Configurator(): IConfigurator<{}>;
+
+interface IFluentConfigurator<C> {
+    /**
+     * **set**
+     *
+     * Sets a new key/value pair to the configurator.
+     *
+     * @param key the key to put this new configuration item
+     * @param value the value of the configuration item
+     */
+    set<V, K extends string, KV = {
+        [U in K]: V;
+    }>(key: K, value: V): IFluentConfigurator<C & KV>;
+    done(): ExpandRecursively<C>;
+}
+/**
+ * This function will return a basic _configurator_ API surface which allows
+ * you to add name/value pairs to a growing dictionary of strongly typed data.
+ *
+ * When configuration is complete, you call the `done()` endpoint and the typed
+ * configuration will be returned with the API removed.
+ *
+ * > **Note:** the approach taken here requires that you configure using a **fluent style**
+ * exclusively. If you don't the non-fluent properties set will not show up
+ * in the typing or the run-time object.
+ */
+declare function FluentConfigurator<I>(initial?: I): IFluentConfigurator<{}>;
+
+type Widen<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T extends readonly string[] ? string[] : T extends readonly number[] ? number[] : T extends readonly boolean[] ? boolean[] : T extends readonly AnyFunction[] ? AnyFunction[] : T extends readonly any[] ? TupleToUnion<T>[] : T extends {} ? {} : T;
+
+/**
+ * **Includes**`<TSource, TValue>`
+ *
+ * Type utility which returns `true` or `false` based on whether `TValue` is found
+ * in `TSource`. Where `TSource` can be a string literal or an array of string literals.
+ *
+ * **Note:** if the source is a _wide_ type (aka, `string` or `string[]`) then there is
+ * no way to know at design-time whether the value includes `TValue` and so it will return
+ * a type of `boolean`.
+ */
+type Includes<TSource extends string | readonly string[], TValue extends string> = TSource extends string[] ? IsStringLiteral<TupleToUnion<TSource>> extends true ? IsLiteral<TValue> extends true ? TValue extends TupleToUnion<TSource> ? true : false : boolean : boolean : TSource extends string ? IsLiteral<TSource> extends true ? IsLiteral<TValue> extends true ? TSource extends `${string}${TValue}${string}` ? true : false : boolean : boolean : boolean;
+
+type IsScalar<T extends Narrowable> = [T] extends [string] ? true : [T] extends [number] ? true : [T] extends [boolean] ? true : false;
+/**
+ * **IfScalar**`<T, IF, ELSE>`
+ *
+ * Branch type utility which returns `IF` when `T` is a scalar value (aka, string, number, or boolean) and `ELSE` otherwise
+ */
+type IfScalar<T extends Narrowable, IF extends Narrowable, ELSE extends Narrowable> = IsScalar<T> extends true ? IF : ELSE;
+
+/**
+ * **HasParameters**`<T>`
+ *
+ * Type utility which detects if `T` is both a function and whether that
+ * function has at least one type parameter.
+ * ```ts
+ * const fn = (foo: string) => `${foo}bar`;
+ * // true
+ * type P = HasParameters<typeof fn>;
+ * ```
+ */
+type HasParameters<T extends Narrowable> = T extends AnyFunction ? IsEqual<Length<Parameters<T>>, 0> extends true ? false : true : false;
+
+/**
+ * **IsObject**
+ *
+ * Boolean type utility used to check whether a type `T` is an object
+ */
+type IsObject<T> = Mutable<T> extends Record<string, any> ? T extends FunctionType ? false : Mutable<T> extends any[] ? false : true : false;
+/**
+ * **IfObject**
+ *
+ * Branch type utility with return `IF` when `T` extends an object type
+ * and `ELSE` otherwise
+ */
+type IfObject<T, IF extends Narrowable, ELSE extends Narrowable> = IsObject<T> extends true ? IF : ELSE;
+
+/**
+ * **StartsWith**<TValue, TStartsWith>
+ *
+ * A type utility which checks whether `T` _starts with_ the string literal `U`.
+ *
+ * If both `T` and `U` are string literals then the type system will resolve
+ * to a literal `true` or `false` but if either is not a literal that it will
+ * just resolve to `boolean` as the value can not be known at design time..
+ */
+type StartsWith<TValue extends string, TStartsWith extends string> = IsStringLiteral<TStartsWith> extends true ? IsStringLiteral<TValue> extends true ? TValue extends `${TStartsWith}${string}` ? true : false : boolean : boolean;
+/**
+ * **IfStartsWith**<TValue, TStartsWith, IF, ELSE, MAYBE>
+ *
+ * Type utility which converts type to `IF` type _if_ TValue _starts with_ `TStartsWith` but
+ * otherwise converts type to `ELSE`.
+ *
+ * Note, that there is also an optional `MAYBE` type
+ * which can be stated for cases where TValue or TStartsWith _might_ be the wider `string`
+ * type and therefore the type is unknown at design time.
+ */
+type IfStartsWith<TValue extends string, TStartsWith extends string, IF extends Narrowable, ELSE extends Narrowable> = StartsWith<TValue, TStartsWith> extends true ? IF : StartsWith<TValue, TStartsWith> extends false ? ELSE : IF | ELSE;
+
+/**
+ * **EndsWith**<T,U>
+ *
+ * A type utility which checks whether `T` _ends with_ the string literal `U`.
+ *
+ * If both `T` and `U` are string literals then the type system will resolve
+ * to a literal `true` or `false` but if either is not a literal that it will
+ * just resolve to `boolean` as the value can not be known at design time..
+ */
+type EndsWith<TValue extends string, TEndsWith extends string> = IsStringLiteral<TEndsWith> extends true ? IsStringLiteral<TValue> extends true ? TValue extends `${string}${TEndsWith}` ? true : false : boolean : boolean;
+/**
+ * **IfEndsWith**<TValue, TEndsWith, IF, ELSE, MAYBE>
+ *
+ * Type utility which converts type to `IF` type _if_ `TValue` _ends with_ `TEndsWith` but
+ * otherwise converts type to `ELSE`. If there are wide types in the mix then the type will
+ * result in the union of IF and ELSE.
+ */
+type IfEndsWith<TValue extends string, TEndsWith extends string, IF extends Narrowable, ELSE extends Narrowable> = EndsWith<TValue, TEndsWith> extends true ? IF : EndsWith<TValue, TEndsWith> extends false ? ELSE : IF | ELSE;
+
+/**
+ * Makes a readonly structure mutable
+ */
+type Mutable<T> = {
+    -readonly [K in keyof T]: IsObject<T[K]> extends true ? Mutable<T[K]> : T[K];
+};
+
+/**
+ * Provides a negation of a type of the type `T` _not_ `U`.
+ * ```ts
+ * const foo = 42;
+ * // 33
+ * type NotTheMeaningOfLife = Not<33, 42>;
+ * // never
+ * type NotTheMeaningOfLife = Not<42, 42>;
+ * ```
+ *
+ * Note: same as `Exclude`
+ */
+type Not<T, U> = T extends U ? never : T;
+
+type Digital = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+type MakeArray<S extends string, T extends any[] = []> = S extends `${T["length"]}` ? T : MakeArray<S, [...T, 0]>;
+type Multiply10<T extends any[]> = [...T, ...T, ...T, ...T, ...T, ...T, ...T, ...T, ...T, ...T];
+/**
+ * Converts a string literal to a numeric literal
+ * ```ts
+ * // 0
+ * type Zero = Numeric<"0">;
+ * // 10
+ * type Ten = Numeric<"10">;
+ * ```
+ */
+type Numeric<S extends string, T extends any[] = []> = S extends `${infer S1}${infer S2}` ? S1 extends Digital ? Numeric<S2, [...Multiply10<T>, ...MakeArray<S1>]> : never : T["length"];
+
+/**
+ * **Opaque**
+ *
+ * Create an opaque type, which hides its internal details from the public, and
+ * can only be created by being used explicitly.
+ *
+ * Note: taken from [type-fest](https://github.com/sindresorhus/type-fest/blob/main/source/opaque.d.ts)
+ * repo.
+ */
+type Opaque<Type, Token = unknown> = Type & {
+    readonly __opaque__: Token;
+};
+
+/**
+ * **Retain<T, K>**
+ *
+ * Reduces the type system to just the key/values which are represented in `K`.
+ * The `L` generic can largely be ignored unless you need _literal_ equality.
+ *
+ * ```ts
+ * type Obj = { foo: 1, bar: number, baz: string };
+ * // { foo: 1, bar: number }
+ * type Retained = Retain<Obj, "foo" | "bar">;
+ * ```
+ *
+ * **Note:** in essence this is the _opposite_ of `Exclude<T,K>`
+ */
+type Retain<T, K extends keyof T> = Pick<T, Include<keyof T, K>>;
+
+/**
+ * Allows filtering down `T` to those which extend a given type `U`.
+ *
+ * - `T` is either a dictionary (where keys will be used to compare) or
+ * a readonly sting array.
+ * ```ts
+ * const arr = ["foo", "bar", "baz"];
+ * // "bar" | "baz"
+ * type BA = Where<typeof arr, `ba${string}`>;
+ * ```
+ */
+type Where<T extends Record<string, any> | readonly string[], U> = T extends readonly string[] ? Include<T[number], U> : {
+    [K in keyof T]: K extends U ? K : never;
+}[keyof T];
+/**
+ * Allows filtering down `T` to those which extend a given type `U`.
+ *
+ * - `T` is either a dictionary (where keys will be used to compare) or
+ * a readonly sting array.
+ * ```ts
+ * const arr = ["foo", "bar", "baz"];
+ * // "foo"
+ * type F = WhereNot<typeof arr, `ba${string}`>;
+ * ```
+ */
+type WhereNot<T extends Record<string, any> | readonly string[], U> = T extends readonly string[] ? Exclude<T[number], U> : {
+    [K in keyof T]: K extends U ? never : K;
+}[keyof T];
+
+type AppendToObject<T, U extends keyof any, V> = {
+    [K in keyof T | U]: K extends keyof T ? T[K] : V;
+};
+/**
+ * Appends a new Key/Value to an existing dictionary <T>
+ */
+type AppendToDictionary<TDict, TKey extends string, TValue> = {
+    [K in keyof TDict | TKey]: K extends keyof TDict ? TDict[K] : TValue;
+};
+
+/**
+ * Accepts the `true` literal or _undefined_.
+ */
+type MaybeTrue = true | undefined;
+/**
+ * Accepts the `false` literal or _undefined_.
+ */
+type MaybeFalse = false | undefined;
+
+/**
+ * A conditional clause used in the application of the `ifTypeOf` utility
+ */
+type ExtendsClause<N extends Narrowable, TValue extends Record<keyof TValue, N> | number | string | boolean | symbol> = <TBase extends any>(base: TBase) => TValue extends TBase ? true : false;
+/**
+ * A conditional clause used in the application of the `ifTypeOf` utility
+ */
+type ExtendsNarrowlyClause<N extends Narrowable, TValue extends Record<keyof TValue, N> | number | string | boolean | symbol> = <NB extends Narrowable, TBase extends Record<keyof TBase, NB> | number | string | boolean | symbol>(base: TBase) => TValue extends TBase ? true : false;
+/**
+ * **TypeCondition**
+ *
+ * A partially applied type from the `ifTypeOf` utility where the base type has been
+ * defined and we now need to express the type which is intended to extend it.
+ *
+ * - `extends` - compares with _wide_ types
+ * - `narrowlyExtends` - compares with _narrow_ / _literal_ types
+ */
+type TypeCondition<N extends Narrowable, TValue extends Record<keyof TValue, N> | number | string | boolean | symbol> = {
+    extends: ExtendsClause<N, TValue>;
+    narrowlyExtends: ExtendsNarrowlyClause<N, TValue>;
+};
+
+/**
+ * **RuleDefinition**
+ *
+ * A rule definition is the typing for the fluent API surface that is built up
+ * with the **ruleset** utility.
+ */
+type RuleDefinition<
+/** the data which will be evaluated on rule execution */
+T extends object, 
+/** the optional props -- as a union type -- which must be defined per the rule */
+H extends string = "", 
+/** the key/values which will be evaluated on execution (wide type) */
+E extends Partial<SameKeys<T>> = {}, 
+/** the key/values which will be evaluated on execution (narrow type) */
+N extends Partial<SameKeys<T>> = {}> = {
+    /**
+     * sets up a true/false check that a given property is defined; this
+     * condition can only be applied to _optional_ properties.
+     */
+    has(optProp: OptionalKeys<T>): RuleDefinition<T, H & typeof optProp, E, N>;
+    /**
+     * Validates that a given property extends a certain value's type; comparison
+     * is made assuming "wide types".
+     */
+    equals<K extends keyof T, V extends Pick<T, K>>(prop: K, value: V): RuleDefinition<T, H, E & Record<K, V>, N>;
+    /**
+     * Validates that a given property extends a certain value's type; comparison
+     * is made assuming "narrow types". This is only available for props which
+     * expose a
+     */
+    narrowlyEquals<K extends keyof T, V extends Pick<T, K>>(prop: K, value: V): RuleDefinition<T, H, E, N & Record<K, V>>;
+};
+/**
+ * **DynamicRule**
+ *
+ * A dynamic rule allows type and runtime validation of a data structure
+ * which extends a known `State`. It then returns the literal type `true`
+ * or `false`.
+ *
+ * ```ts
+ * type State = { id?: string; favorite: boolean; color: string };
+ * // type-safe way to check whether optional prop is actually set
+ * const rule: DynamicRule<State> = s => s
+ *  .has("id")
+ *  .equals("favorite", true)
+ *  .equals("color", "red");
+ * ```
+ */
+type DynamicRule<TState extends any, TResult extends true | false> = (rule: TypeCondition<any, TState>) => TResult;
+/**
+ * **DynamicRuleSet**
+ *
+ * A function which accepts the agreed `TState` generic as input and returns a discrete
+ * `true` or `false` value.
+ */
+type DynamicRuleSet<TState extends any, TRules extends Record<string, TypeCondition<any, TState>>> = (rules: TRules) => true | false;
+
+type RuntimeType<T> = {
+    __kind: "type";
+    type: T;
+    is: TypeGuard<T>;
+};
+type RuntimeProp<P extends Readonly<PropertyKey>, T extends RuntimeType<any>> = {
+    __kind: "prop";
+    key: Readonly<P>;
+    valueType: Readonly<T["type"]>;
+    /**
+     * Provides the _type_ to the type system when used with `typeof`.
+     *
+     * ```ts
+     * const t = number();
+     * // number
+     * type T = typeof t.type;
+     * ```
+     *
+     * **Note:** _the runtime system will get a string equivalent name:_
+     * ```ts
+     * const t = number();
+     * // "number"
+     * console.log(t.type);
+     * ```
+     */
+    type: Record<P, T["type"]>;
+    is: TypeGuard<Record<P, T["type"]>>;
+};
+type TypeOptions<T extends Partial<object> = {}> = {
+    /** each type has a default type guard but you can override if you need to be more specific */
+    typeGuard?: TypeGuard<T>;
+} & T;
+
+/**
+ * Validates that a given type extends another and returns `true` or `false` type
+ */
+type ExpectExtends<VALUE, EXPECTED> = EXPECTED extends VALUE ? true : false;
+/**
+ * Validates that a given type extends another and returns `any` or `never` as a type
+ */
+type AssertExtends<VALUE, EXPECTED> = EXPECTED extends VALUE ? any : never;
+/**
+ * Give a type `TValue` and a comparison type `TExtends`
+ */
+type IfExtendsThen<VALUE, EXPECTED, THEN> = EXPECTED extends VALUE ? THEN : never;
+
+/**
+ * **ToFluent**
+ *
+ * Converts the typing of a dictionary of functions into the same
+ * function signatures but changes the return type to be the Fluent API.
+ *
+ * **Note:** this utility also allows a non-fluent API surface `X` to be included as
+ * part of the API surface if this is desired.
+ */
+type ToFluent<T extends {
+    [key: string]: (...args: any[]) => any;
+}, X extends object = {}> = {
+    [K in keyof T]: (...args: Parameters<T[K]>) => ToFluent<T, X> & X;
+} & X;
+/**
+ * A _pure_ Fluent API which promotes an API surface where _every_ API endpoint must be a function
+ * which returns the same API surface.
+ *
+ * To provide value, this style of Fluent API will need to perform useful _side effects_ when functions
+ * on the API surface are called as this structure does not provide any means to maintain an internal state
+ * which can be returned later.
+ *
+ * **Note:** _if you prefer a Fluent API with means to _escape_ with an internally managed state then
+ * you should prefer the use of the `FluentApi` type._
+ */
+type PureFluentApi<TApi extends Record<string, (...args: any[]) => PureFluentApi<TApi, any>>, TExclude extends string = ""> = {
+    [P in keyof TApi]: (...args: Parameters<TApi[P]>) => PureFluentApi<Omit<TApi, TExclude>>;
+};
+
+export { AfterFirst, AllCaps, Alpha, AlphaNumeric, AnyFunction, Api, ApiFunction, ApiValue, AppendToDictionary, AppendToObject, ArrConcat, Array$1 as Array, ArrayConverter, AsArray, AsFinalizedConfig, AssertExtends, Box, BoxValue, BoxedFnParams, BoxedReturn, Bracket, Break, CamelCase, CapitalizeWords, Cardinality, Cardinality0, Cardinality1, CardinalityExplicit, CardinalityFilter0, CardinalityFilter1, CardinalityIn, CardinalityInput, CardinalityNode, CardinalityOut, CardinalityTuple, ClosingBracket, Condition, ConditionFilter, Configurator, ConfiguredMap, Constructor, Contains, DEFAULT_MANY_TO_ONE_MAPPING, DEFAULT_ONE_TO_MANY_MAPPING, DEFAULT_ONE_TO_ONE_MAPPING, DashToSnake, DashUppercase, Dasherize, DecomposeMapConfig, DefaultManyToOneMapping, DefaultOneToManyMapping, DefaultOneToOneMapping, DefinePropertiesApi, DictArrApi, DictArray, DictArrayFilterCallback, DictArrayKv, DictChangeValue, DictFromKv, DictKvTuple, DictPartialApplication, DictPrependWithFn, DictReturnValues, DictionaryWithoutValue, DomainName, DynamicRule, DynamicRuleSet, Email, EndsWith, EnsureLeading, EnsureTrailing, EnumValues, ExpandRecursively, ExpectExtends, ExplicitFunction, Extends, FilterContains, FilterDefn, FilterEnds, FilterEquals, FilterFn, FilterGreaterThan, FilterIs, FilterLessThan, FilterNotEqual, FilterStarts, FilterTuple, FinalReturn, FinalizedMapConfig, First, FirstKey, FirstKeyValue, FirstOfEach, FirstOrUndefined, FirstString, FluentConfigurator, FluentFunction, FnShape, FromDictArray, FullyQualifiedUrl, FunctionType, GeneralDictionary, Get, HasParameters, HasUppercase, HybridFunction, IConfigurator, IFluentConfigurator, If, IfArray, IfBooleanLiteral, IfEndsWith, IfExtends, IfExtendsThen, IfFalse, IfLiteral, IfNumericLiteral, IfObject, IfOptionalLiteral, IfReadonlyArray, IfScalar, IfStartsWith, IfStringLiteral, IfTrue, IfUndefined, Include, Includes, IntersectingKeys, Ipv4, IsArray, IsBoolean, IsBooleanLiteral, IsCapitalized, IsEqual, IsFalse, IsFunction, IsLiteral, IsNull, IsNumber, IsNumericLiteral, IsObject, IsOptionalLiteral, IsReadonlyArray, IsScalar, IsStringLiteral, IsTrue, IsUndefined, KebabCase, KeyValue, KeyedRecord, Keys, KeysWithValue, KvFrom, KvTuple, LastInUnion, LeftWhitespace, Length, LogicFunction, LogicalCombinator, LowerAllCaps, LowerAlpha, ManyToMany, ManyToOne, ManyToZero, MapCard, MapCardinality, MapCardinalityFrom, MapCardinalityIllustrated, MapConfig, MapFn, MapFnInput, MapFnOutput, MapIR, MapInput, MapInputFrom, MapOR, MapOutput, MapOutputFrom, MapTo, Mapper, MapperApi, MaybeFalse, MaybeTrue, Mutable, MutableProps, NarrowBox, Narrowable, NarrowlyContains, NetworkProtocol, NonAlpha, NonNumericKeys, NonStringKeys, Not, NotEqual, NotFilter, Numeric, NumericFilter, NumericKeys, NumericString, ObjectType, OneToMany, OneToOne, OneToZero, Opaque, OpeningBracket, OptRequired, OptionalKeys, OptionalProps, Or, Parenthesis, PascalCase, PathJoin, Pluralize, PrivateKey, PrivateKeys, PublicKeys, Punctuation, PureFluentApi, RelativeUrl, Replace, RequireProps, RequiredKeys, RequiredProps, Retain, RightWhitespace, RuleDefinition, RuntimeProp, RuntimeType, SameKeys, SecondOfEach, SimpleFunction, SimplifyObject, SnakeCase, SpecialCharacters, Split, StartsWith, StringDelimiter, StringFilter, StringKeys, StringLength, StripLeading, StripTrailing, Suggest, SuggestNumeric, ToFluent, Transformer, Trim, TrimLeft, TrimRight, TupleToUnion, Type, TypeApi, TypeDefault, TypeDefinition, TypeGuard, TypeOptions, Unbox, UndefinedArrayIsUnknown, UndefinedTreatment, UndefinedValue, UnionToIntersection, UnionToTuple, UniqueDictionary, UniqueForProp, Uniqueness, UnwrapNot, UpperAlpha, UrlBuilder, VariableName, Where, WhereNot, Whitespace, Widen, WithNumericKeys, WithStringKeys, WithValue, ZeroToMany, ZeroToOne, ZeroToZero, ZipCode, and, api, arrayToKeyLookup, arrayToObject, asArray, box, boxDictionaryValues, condition, createConverter, createFnWithProps, defineProperties, defineType, dictArr, dictToKv, dictionaryTransform, ensureLeading, ensureTrailing, entries, filter, filterDictArray, fnWithProps, groupBy, idLiteral, idTypeGuard, identity, ifArray, ifArrayPartial, ifBoolean, ifDefined, ifFalse, ifNull, ifNumber, ifObject, ifSameType, ifString, ifTrue, ifUndefined, isArray, isBoolean, isBox, isFalse, isFunction, isNotFilter, isNull, isNumber, isNumericFilter, isObject, isString, isSymbol, isTrue, isType, isUndefined, keys, kindLiteral, kv, kvToDict, literal, mapTo, mapToDict, mapToFn, mapValues, nameLiteral, not, or, pathJoin, readonlyFnWithProps, ruleSet, strArrayToDict, stripTrailing, type, typeApi, unbox, wide, withValue };