inferred-types 0.35.0 → 0.36.0

package/dist/index.d.ts

@@ -146,13 +146,13 @@ type Length<T extends readonly any[]> = T["length"];
  *
  * Type utility which tests whether two types -- `X` and `Y` -- are exactly the same type
  */
-type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+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 Equal<X, Y> ? false : true;
+type NotEqual<X, Y> = true extends IsEqual<X, Y> ? false : true;
 
 /**
  * **AfterFirst**`<T>`
@@ -243,7 +243,7 @@ type Contains<T extends Narrowable, A extends readonly any[]> = First<A> extends
  * `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[]> = Equal<First<A>, T> extends true ? true : [] extends AfterFirst<A> ? false : NarrowlyContains<T, AfterFirst<A>>;
+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
@@ -270,159 +270,191 @@ type LastInUnion<U> = UnionToIntersection<U extends unknown ? (x: U) => 0 : neve
  */
 type UnionToTuple<U, Last = LastInUnion<U>> = [U] extends [never] ? [] : [...UnionToTuple<Exclude<U, Last>>, Last];
 
-type Widen<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
-
-type IsBoolean<T> = T extends boolean ? true : false;
+declare function createFnWithProps<F extends Function, P extends {}>(fn: F, props: P): F & P;
 /**
- * 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">;
- * ```
+ * Adds a dictionary of key/value pairs to a function.
  */
-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;
+declare function fnWithProps<A extends any[], R extends any, P extends {}>(fn: ((...args: A) => R), props: P): ((...args: A) => R) & P;
 /**
- * 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`
+ * Adds read-only (and narrowly typed) key/value pairs to a function
  */
-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;
+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>;
+
 /**
- * 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`
+ * Provides the _keys_ of an object with the `keyof T` made explicit.
  */
-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;
+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>>[];
+
 /**
- * **IsBooleanLiteral**
+ * **ruleSet**
  *
- * 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**
+ * Defines a ruleset composed of _dynamic_ and _static_ boolean operators.
  *
- * Branch utility which returns `IF` type when `T` is a boolean literal and `ELSE` otherwise
+ * - 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 }
+ * );
+ * ```
  */
-type IfBooleanLiteral<T extends boolean, IF extends Narrowable, ELSE extends Narrowable> = IsBooleanLiteral<T> extends true ? IF : ELSE;
+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;
 
 /**
- * **IsStringLiteral**
+ * A type utility which looks at a chain for functions and reduces the type
+ * to the final `ReturnType` of the chain.
  *
- * Type utility which returns true/false if the string a _string literal_ versus
- * just the _string_ type.
+ * ```ts
+ * // number
+ * type T = FinalReturn<() => (foo: string) => (bar: string) => () => number>;
+ * ```
  */
-type IsStringLiteral<T extends Narrowable> = [T] extends [string] ? string extends T ? false : true : false;
+type FinalReturn<T extends any> = T extends (...args: any[]) => any ? FinalReturn<ReturnType<T>> : T;
+
 /**
- * **IfStringLiteral**
- *
- * Branch utility which returns `IF` type when `T` is a string literal and `ELSE` otherwise
+ * A function which returns a boolean value
  */
-type IfStringLiteral<T extends string, IF extends Narrowable, ELSE extends Narrowable> = [
-    IsStringLiteral<T>
-] extends [true] ? IF : ELSE;
+type LogicFunction<T extends readonly any[]> = (...args: T) => boolean;
+
 /**
- * **IsNumericLiteral**
+ * Groups a number of "logic functions" together by combining their results using
+ * the logical **AND** operator.
  *
- * Type utility which returns true/false if the numeric value a _numeric literal_ versus
- * just the _number_ type.
+ * **Note:** a "logic function" is any function which returns a boolean
  */
-type IsNumericLiteral<T extends number> = number extends T ? false : true;
+declare const and: <T extends any[]>(...ops: readonly LogicFunction<T>[]) => LogicFunction<T>;
+
 /**
- * **IfNumericLiteral**
+ * **Or**`<T>`
  *
- * Branch utility which returns `IF` type when `T` is a numeric literal and `ELSE` otherwise
+ * Takes an array of boolean values and produces a boolean OR across these values
  */
-type IfNumericLiteral<T extends number, IF extends Narrowable, ELSE extends Narrowable> = IsNumericLiteral<T> extends true ? IF : ELSE;
+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>;
+
 /**
- * **IsLiteral**
+ * Groups a number of "logic functions" together by combining their results using
+ * the logical **NOT** operator.
  *
- * 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).
+ * **Note:** a "logic function" is any function which returns a boolean
  */
-type IsLiteral<T> = [T] extends [string] ? IsStringLiteral<T> : [T] extends [boolean] ? IsBooleanLiteral<T> : [T] extends [number] ? IsNumericLiteral<T> : false;
+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";
 /**
- * **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).
+ * **FilterFn**
  *
- * 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.
+ * 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 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;
+type FilterFn<T extends StringFilter | NumericFilter> = T extends StringFilter ? <V extends string | undefined>(input: V) => boolean : <V extends number | undefined>(input: V) => boolean;
 /**
- * **IfLiteral**
- *
- * Branch type utility with return `IF` when `T` is a _literal_ value and `ELSE` otherwise
+ * Defines a logical function for each condition type
  */
-type IfLiteral<T, IF extends Narrowable, ELSE extends Narrowable> = IsLiteral<T> extends true ? IF : ELSE;
+type ConditionFilter<T extends StringFilter | NumericFilter> = T extends StringFilter ? (input: string) => boolean : (input: number) => boolean;
 /**
- * **IfOptionalLiteral**
+ * **filter**
  *
- * 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;
-
-/**
- * **Includes**`<TSource, TValue>`
+ * A higher order helper utility which builds a boolean _filter_ function based on a simple
+ * configuration object. Support either _string_ or _numeric_ filters.
  *
- * 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.
+ * ```ts
+ * const str = filter({startsWith: ["_", "."], endsWith: ".md"});
+ * const num = filter({ greaterThan: 55, notEqual: [66, 77]});
+ * ```
  *
- * **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>`
+ * 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.
  *
- * Branch type utility which returns `IF` when `T` is a scalar value (aka, string, number, or boolean) and `ELSE` otherwise
+ * 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.
  */
-type IfScalar<T extends Narrowable, IF extends Narrowable, ELSE extends Narrowable> = IsScalar<T> extends true ? IF : ELSE;
+declare const filter: <F extends FilterDefn | NotFilter, U extends boolean | "no-impact", C extends LogicalCombinator>(config: F, logicCombinator?: C, ifUndefined?: U) => FilterFn<UnwrapNot<F>>;
 
 /**
- * **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>`
+ * 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);
  *
- * Type utility which returns `IF` type when `T` is an _undefined_
- * otherwise returns `ELSE` type.
+ * const fooBar = arrayToKeyLookup("foo", "bar");
+ * ```
  */
-type IfUndefined<T, IF extends Narrowable, ELSE extends Narrowable> = IsUndefined<T> extends true ? IF : ELSE;
+declare function arrayToKeyLookup<T extends readonly string[]>(...keys: T): Record<T[number], true>;
 
-/**
- * **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;
+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
@@ -433,2037 +465,1789 @@ type IfExtends<T extends Narrowable, EXTENDS extends Narrowable, IF extends Narr
 type SimplifyObject<T extends {}> = ExpandRecursively<UnionToIntersection<ExpandRecursively<T>>>;
 
 /**
- * **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`
+ * 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
- * 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 }`
+ * 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 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>>>;
-
-/**
- * **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;
+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]>;
 
 /**
- * **StartsWith**<TValue, TStartsWith>
+ * 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`.
  *
- * A type utility which checks whether `T` _starts with_ the string literal `U`.
+ * If `V` is not specified then it defaults to _any_ and therefore all KVs are preserved.
  *
- * 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..
+ * ```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 StartsWith<TValue extends string, TStartsWith extends string> = IsStringLiteral<TStartsWith> extends true ? IsStringLiteral<TValue> extends true ? TValue extends `${TStartsWith}${string}` ? true : false : boolean : boolean;
+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, 
 /**
- * **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.
+ *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
  */
-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;
+V extends any = any> = SimplifyObject<{
+    [K in keyof I]: I[K] extends V ? Record<K, T> : never;
+}[keyof I]>;
 
 /**
- * **EndsWith**<T,U>
- *
- * A type utility which checks whether `T` _ends with_ the string literal `U`.
+ * **DictPrependWithFn**
  *
- * 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>
+ * 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.
  *
- * 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.
+ * 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 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;
+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]>;
 
 /**
- * **Or**`<T>`
+ * **DictReturnValues**
  *
- * Takes an array of boolean values and produces a boolean OR across these values
+ * 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 Or<T extends readonly boolean[]> = NarrowlyContains<true, T> extends true ? true : NarrowlyContains<boolean, T> extends true ? boolean : false;
+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]>;
 
 /**
- * Makes a readonly structure mutable
+ * Expresses whether an option is "opt" (optional) or "req" (required)
  */
-type Mutable<T> = {
-    -readonly [K in keyof T]: IsObject<T[K]> extends true ? Mutable<T[K]> : T[K];
-};
+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;
 /**
- * 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>;
- * ```
+ * **mapTo** _utility_
  *
- * 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
+ * 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
- * // 0
- * type Zero = Numeric<"0">;
- * // 10
- * type Ten = Numeric<"10">;
+ * const mapper = mapTo<I, O>(i => [{
+ *    foo: i.bar
+ * }]);
  * ```
  */
-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"];
-
+declare const mapToFn: ConfiguredMap<DefaultOneToManyMapping>["map"];
 /**
- * **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.
+ * Provides a `config` method which allows the relationships between _inputs_
+ * and _outputs_ to be configured.
  */
-type Opaque<Type, Token = unknown> = Type & {
-    readonly __opaque__: Token;
-};
-
+declare const mapToDict: MapperApi;
 /**
- * **Retain<T, K>**
+ * **mapTo** _utility_
  *
- * 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.
+ * This utility creates a strongly typed data mapper which maps from one
+ * known source `I` to another `O`.
  *
+ * Signatures:
  * ```ts
- * type Obj = { foo: 1, bar: number, baz: string };
- * // { foo: 1, bar: number }
- * type Retained = Retain<Obj, "foo" | "bar">;
+ * 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>( ... );
  * ```
- *
- * **Note:** in essence this is the _opposite_ of `Exclude<T,K>`
- */
-type Retain<T, K extends keyof T> = Pick<T, Include<keyof T, K>>;
-
-/**
- * **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;
-};
+declare const mapTo: (<I, O>(map: (source: I) => O[]) => Mapper<I, O, FinalizedMapConfig<"req", "I -> O[]", "opt">>) & MapperApi;
 
 /**
- * **Transformer**
- *
- * A function responsible for transforming the _values_ of
- * dictionary `I` into different _values_ for dictionary `O`.
+ * **Extends**`<T, EXTENDS>`
  *
- * This type utility assumes that _keys_ of both dictionaries
- * are the same.
+ * Boolean type utility which returns `true` if `T` _extends_ `EXTENDS`.
  */
-type Transformer<I extends object, O extends SameKeys<I>, K extends keyof I = keyof I> = (input: I, key: K) => O[K];
-
+type Extends<T extends Narrowable, EXTENDS extends Narrowable> = T extends EXTENDS ? true : false;
 /**
- * **TypeGuard**
+ * **IfExtends**
  *
- * a typing for a **TS** type-guard which evaluates an _unknown_ input
- * and determines if it is of type `T`.
+ * Branching type utility which returns type `IF` when `E` _extends_ `T`; otherwise
+ * it will return the type `ELSE`.
  */
-type TypeGuard<T> = (thing: unknown) => thing is T;
+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;
 /**
- * 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.
+ * Type utility which returns `true` or `false` based on
+ * whether the type holds the narrow "true" type.
  * ```ts
- * const arr = ["foo", "bar", "baz"];
- * // "bar" | "baz"
- * type BA = Where<typeof arr, `ba${string}`>;
+ * // true
+ * type T = IsTrue<true>;
+ * // boolean
+ * type U = IsTrue<boolean>;
+ * // false
+ * type F = IsTrue<false>;
+ * type F2 = IsTrue<"false">;
  * ```
  */
-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];
+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;
 /**
- * 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 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 MaybeFalse = false | undefined;
-
+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;
 /**
- * A conditional clause used in the application of the `ifTypeOf` utility
+ * 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 ExtendsClause<N extends Narrowable, TValue extends Record<keyof TValue, N> | number | string | boolean | symbol> = <TBase extends any>(base: TBase) => TValue extends TBase ? true : false;
+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;
 /**
- * A conditional clause used in the application of the `ifTypeOf` utility
+ * **IsBooleanLiteral**
+ *
+ * Type utility which returns true/false if the boolean value is a _boolean literal_ versus
+ * just the wider _boolean_ type.
  */
-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;
+type IsBooleanLiteral<T extends Narrowable> = IsTrue<T> extends true ? true : IsFalse<T> extends true ? 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.
+ * **IfBooleanLiteral**
  *
- * - `extends` - compares with _wide_ types
- * - `narrowlyExtends` - compares with _narrow_ / _literal_ types
+ * Branch utility which returns `IF` type when `T` is a boolean literal and `ELSE` otherwise
  */
-type TypeCondition<N extends Narrowable, TValue extends Record<keyof TValue, N> | number | string | boolean | symbol> = {
-    extends: ExtendsClause<N, TValue>;
-    narrowlyExtends: ExtendsNarrowlyClause<N, TValue>;
-};
+type IfBooleanLiteral<T extends boolean, IF extends Narrowable, ELSE extends Narrowable> = IsBooleanLiteral<T> extends true ? IF : ELSE;
 
-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)
+ * **IsStringLiteral**
+ *
+ * Type utility which returns true/false if the string a _string literal_ versus
+ * just the _string_ type.
  */
-type Alpha = UpperAlpha | LowerAlpha;
-type Whitespace = " " | "\n" | "\t";
-type Punctuation = "." | "," | ";" | "!" | "?";
+type IsStringLiteral<T extends Narrowable> = [T] extends [string] ? string extends T ? false : true : false;
 /**
- * Characters which typically are used to separate words (but not including a space)
+ * **IfStringLiteral**
+ *
+ * Branch utility which returns `IF` type when `T` is a string literal and `ELSE` otherwise
  */
-type StringDelimiter = "_" | "-" | "/" | "\\";
-type OpeningBracket = "(" | "[" | "{";
-type ClosingBracket = ")" | "]" | "}";
+type IfStringLiteral<T extends string, IF extends Narrowable, ELSE extends Narrowable> = [
+    IsStringLiteral<T>
+] extends [true] ? IF : ELSE;
 /**
- * Opening and closing parenthesis
+ * **IsNumericLiteral**
+ *
+ * Type utility which returns true/false if the numeric value a _numeric literal_ versus
+ * just the _number_ type.
  */
-type Parenthesis = "(" | ")";
+type IsNumericLiteral<T extends number> = number extends T ? false : true;
 /**
- * Opening and closing brackets
+ * **IfNumericLiteral**
+ *
+ * Branch utility which returns `IF` type when `T` is a numeric literal and `ELSE` otherwise
  */
-type Bracket = OpeningBracket | ClosingBracket;
+type IfNumericLiteral<T extends number, IF extends Narrowable, ELSE extends Narrowable> = IsNumericLiteral<T> extends true ? IF : ELSE;
 /**
- * Numeric string characters
+ * **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 NumericString = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+type IsLiteral<T> = [T] extends [string] ? IsStringLiteral<T> : [T] extends [boolean] ? IsBooleanLiteral<T> : [T] extends [number] ? IsNumericLiteral<T> : false;
 /**
- * Any alphabetic or numeric string character
+ * **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 AlphaNumeric = Alpha | NumericString;
+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;
 /**
- * Allows alphanumeric characters and some special characters typically allowed
- * in variable names.
+ * **IfLiteral**
+ *
+ * Branch type utility with return `IF` when `T` is a _literal_ value and `ELSE` otherwise
  */
-type VariableName = AlphaNumeric | "_" | "." | "-";
-type SpecialCharacters = "@" | "~" | "^" | "#" | "&" | "*";
+type IfLiteral<T, IF extends Narrowable, ELSE extends Narrowable> = IsLiteral<T> extends true ? IF : ELSE;
 /**
- * Non-alphabetic characters including whitespace, string numerals, and
+ * **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 NonAlpha = Whitespace | Punctuation | NumericString | Bracket | SpecialCharacters;
-type Ipv4 = `${number}.${number}.${number}.${number}`;
+type IfOptionalLiteral<T, IF extends Narrowable, ELSE extends Narrowable> = IsOptionalLiteral<T> extends true ? IF : ELSE;
 
 /**
- * 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
+ * **IsUndefined**
+ *
+ * Boolean type utility returns `true` if `T` is undefined; `false` otherwise
  */
-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];
+type IsUndefined<T extends Narrowable> = T extends undefined ? true : false;
 /**
- * Extracts the _optional_ keys in the object's type. You also may
- * optionally filter by the _value_ of the key.
+ * **IfUndefined**`<T, IF, ELSE>`
+ *
+ * Type utility which returns `IF` type when `T` is an _undefined_
+ * otherwise returns `ELSE` type.
  */
-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];
+type IfUndefined<T, IF extends Narrowable, ELSE extends Narrowable> = IsUndefined<T> extends true ? IF : ELSE;
+
 /**
- * The _keys_ on a given object `T` which have a literal value of `W`.
+ * **TypeDefault**
  *
- * Optionally, you may provide a generic `E` to exclude certain keys in
- * result set.
+ * 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
- * // "foo"
- * type Str = KeysWithValue<{ foo: "hi"; bar: 5 }>;
+ * 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 KeysWithValue<W extends any, T extends object> = {
-    [K in keyof T]: T[K] extends W ? Readonly<K> : never;
-}[keyof T];
+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>>>;
+
 /**
- * A `PrivateKey` must start with a `_` character and then follow with
- * an alphabetic character
+ * Expresses relationship between inputs/outputs:
  */
-type PrivateKey = `_${Alpha}${string}`;
+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>;
 /**
- * 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.
+ * The _user_ configuration of a **mapTo** mapper function
+ * which will be finalized by merging it with the appropriate
+ * default mapping type.
  */
-type PrivateKeys<T extends object> = {
-    [K in keyof T]: K extends `_${string}` ? K : never;
-}[keyof T];
+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;
+}
 /**
- * **PublicKeys**
+ * A finalized configuration of a **mapTo** mapper functions cardinality
+ * relationships between _inputs_ and _outputs_.
  *
- * Builds a union type of all keys which are "public" where a public
- * key is any key which _does not_ start with the `_` character.
+ * Note: _this configuration does _not_ yet include the actual mapping
+ * configuration between the input and output._
  */
-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];
+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;
+};
 /**
- * The keys of an object which _are not_ a string type
+ * User configuration exposed by a config function which specifies the
+ * cardinality already (e.g., `oneToMany()`, `manyToOne()`)
  */
-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>>;
+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;
+};
 /**
- * **WithValue**
+ * **ConfiguredMap**
  *
- * 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>
- * ```
+ * 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 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 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;
+};
 /**
- * Reduces an object to only the key/value pairs where the key is a
- * string.
+ * Extracts the IR, Cardinality, and OR generics from a FinalizedMapConfig
  */
-type WithStringKeys<T extends object> = Omit<T, NonStringKeys<T>>;
+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];
 /**
- * Reduces an object to only the key/value pairs where the key is numeric.
+ * extracts the MapCardinality from a `FinalizedMapConfig`
  */
-type WithNumericKeys<T extends object> = Omit<T, NonNumericKeys<T>>;
-
+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];
 /**
- * **RuleDefinition**
- *
- * A rule definition is the typing for the fluent API surface that is built up
- * with the **ruleset** utility.
+ * Merges the types of a userland configuration with a default configuration
  */
-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>> = {}> = {
+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 = {
     /**
-     * sets up a true/false check that a given property is defined; this
-     * condition can only be applied to _optional_ properties.
+     * 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._
      */
-    has(optProp: OptionalKeys<T>): RuleDefinition<T, H & typeof optProp, E, N>;
+    config: <C extends MapConfig<OptRequired, //
+    MapCardinalityIllustrated, OptRequired>>(config: C) => ConfiguredMap<AsFinalizedConfig<C, //
+    DefaultOneToManyMapping>>;
     /**
-     * Validates that a given property extends a certain value's type; comparison
-     * is made assuming "wide types".
+     * 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" })
+     * ```
      */
-    equals<K extends keyof T, V extends Pick<T, K>>(prop: K, value: V): RuleDefinition<T, H, E & Record<K, V>, N>;
+    oneToOne: <C extends MapCardinalityConfig<OptRequired, OptRequired>>(config?: C) => ConfiguredMap<AsFinalizedConfig<C, //
+    DefaultOneToOneMapping>>;
     /**
-     * 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
+     * **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.
      */
-    narrowlyEquals<K extends keyof T, V extends Pick<T, K>>(prop: K, value: V): RuleDefinition<T, H, E, N & Record<K, V>>;
+    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;
 /**
- * **DynamicRule**
+ * **MapTo<I, O>**
  *
- * 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`.
+ * A mapping function between an input type `I` and output type `O`. Defaults to using
+ * the _default_ OneToMany mapping config.
  *
- * ```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");
- * ```
+ * **Note:** this type is designed to guide the userland mapping; refer
+ * to `MapFn` if you want the type output by the `mapFn()` utility.
  */
-type DynamicRule<TState extends any, TResult extends true | false> = (rule: TypeCondition<any, TState>) => TResult;
+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;
 /**
- * **DynamicRuleSet**
+ * The mapping function provided by the `mapFn()` utility. This _fn_
+ * is intended to be used in two ways:
  *
- * A function which accepts the agreed `TState` generic as input and returns a discrete
- * `true` or `false` value.
+ * 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 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"]>;
+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_ to the type system when used with `typeof`.
-     *
-     * ```ts
-     * const t = number();
-     * // number
-     * type T = typeof t.type;
-     * ```
+     * Provides the _type_ information for mapper function.
      *
-     * **Note:** _the runtime system will get a string equivalent name:_
-     * ```ts
-     * const t = number();
-     * // "number"
-     * console.log(t.type);
-     * ```
+     * Note: _this is just a **type**_ not the actual function which positioned
+     * at the root of the Mapper 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;
-
+    fnSignature: MapFn<I, O, C>;
+} & MapFn<I, O, C>;
 /**
- * Validates that a given type extends another and returns `true` or `false` type
+ * **MapInputFrom**
+ *
+ * Type utility which extracts the `I` type from a fully configured `Mapper`
  */
-type ExpectExtends<VALUE, EXPECTED> = EXPECTED extends VALUE ? true : false;
+type MapInputFrom<T extends Mapper> = T extends Mapper<infer I> ? I : never;
 /**
- * Validates that a given type extends another and returns `any` or `never` as a type
+ * **MapOutputFrom**
+ *
+ * Type utility which extracts the output [`O`] type from a fully configured `Mapper`
  */
-type AssertExtends<VALUE, EXPECTED> = EXPECTED extends VALUE ? any : never;
+type MapOutputFrom<T extends Mapper> = T extends Mapper<any, infer O> ? O : never;
 /**
- * Give a type `TValue` and a comparison type `TExtends`
+ * **MapCardinalityFrom**
+ *
+ * Type utility which extracts _cardinality_ of a `Mapper`'s inputs to outputs
  */
-type IfExtendsThen<VALUE, EXPECTED, THEN> = EXPECTED extends VALUE ? THEN : never;
+type MapCardinalityFrom<T extends Mapper> = T extends Mapper<any, any, infer C> ? C extends FinalizedMapConfig<OptRequired, infer Cardinality, OptRequired> ? Cardinality : never : never;
 
 /**
- * Indicates whether `T` has _all_ uppercase characters in it.
+ * Given a dictionary of type `<T>`, this utility function will
+ * make the `<M>` generic property _mutable_ and all other _read-only_.
+ *
  * ```ts
- * // true
- * type T = AllCaps<"FOOBAR">;
- * // false
- * type T = AllCaps<"FooBar">;
- * // "unknown"
- * type T = AllCaps<string>;
+ * // { foo: string, bar?: Readonly<number> }
+ * type Example = MutableProps<{
+ *    foo: Readonly<string>,
+ *    bar?: number
+ * }, "foo">;
  * ```
  */
-type AllCaps<T extends string> = string extends T ? "unknown" : T extends Uppercase<T> ? true : false;
+type MutableProps<T extends {}, M extends keyof T & string> = ExpandRecursively<Mutable<Pick<T, M>> & Readonly<Pick<T, Keys<T, M>>>>;
 
 /**
- * **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).
+ * 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", "bar", "baz" ]
- * type T = ArrConcat<["foo"], ["bar", "baz"]>;
+ * // { foo: string, bar?: number }
+ * type Example = RequireProps<{foo?: string, bar?: number}, "foo">;
  * ```
  */
-type ArrConcat<A extends any[], B extends any[]> = [...A, ...B];
+type RequireProps<T extends {}, R extends keyof T> = ExpandRecursively<Required<Pick<T, R>> & T>;
 
 /**
- * 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", "">;
- * ```
+ * **SameKeys**
  *
- * Note: _the first match is replaced and all subsequent matches are ignored_
+ * 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 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;
+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>;
 /**
- * Trims off whitespace on left of string
- * ```ts
- * // "foobar "
- * type T = TrimLeft<"\n\t  foobar ">;
- * // string
- * type T = TrimLeft<string>;
- * ```
+ * Alphabetical characters (upper and lower)
  */
-type TrimLeft<S extends string> = string extends S ? string : S extends `${Whitespace}${infer Right}` ? TrimLeft<Right> : S;
-
+type Alpha = UpperAlpha | LowerAlpha;
+type Whitespace = " " | "\n" | "\t";
+type Punctuation = "." | "," | ";" | "!" | "?";
 /**
- * Provides the _left_ whitespace of a string
- * ```ts
- * // "\n\t "
- * type T = LeftWhitespace<"\n\t foobar">;
- * ```
+ * Characters which typically are used to separate words (but not including a space)
  */
-type LeftWhitespace<S extends string> = string extends S ? string : Replace<S, TrimLeft<S>, "">;
-
+type StringDelimiter = "_" | "-" | "/" | "\\";
+type OpeningBracket = "(" | "[" | "{";
+type ClosingBracket = ")" | "]" | "}";
 /**
- * Trims off whitespace on left of string
- * ```ts
- * // "\n foobar"
- * type T = TrimRight<"\n foobar \t">;
- * // string
- * type T = TrimRight<string>;
- * ```
+ * Opening and closing parenthesis
  */
-type TrimRight<S extends string> = string extends S ? string : S extends `${infer Right}${Whitespace}` ? TrimRight<Right> : S;
-
+type Parenthesis = "(" | ")";
 /**
- * Provides the _left_ whitespace of a string
- * ```ts
- * // "\n\t "
- * type T = LeftWhitespace<"\n\t foobar">;
- * ```
+ * Opening and closing brackets
  */
-type RightWhitespace<S extends string> = string extends S ? string : Replace<S, TrimRight<S>, "">;
-
+type Bracket = OpeningBracket | ClosingBracket;
 /**
- * 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">;
- * ```
+ * Numeric string characters
  */
-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"];
-
+type NumericString = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
 /**
- * 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>;
- * ```
+ * Any alphabetic or numeric string character
  */
-type Trim<S extends string> = string extends S ? string : S extends `${Whitespace}${infer Right}` ? Trim<Right> : S extends `${infer Left}${Whitespace}` ? Trim<Left> : S;
-
+type AlphaNumeric = Alpha | NumericString;
 /**
- * An email address
+ * Allows alphanumeric characters and some special characters typically allowed
+ * in variable names.
  */
-type Email = `${string}@${string}.${string}`;
-type Zip5 = `${NumericString}${NumericString}${string}${NumericString}`;
-type Zip4 = `${NumericString}${string}`;
+type VariableName = AlphaNumeric | "_" | "." | "-";
+type SpecialCharacters = "@" | "~" | "^" | "#" | "&" | "*";
 /**
- * A relatively strong type for Zip5 or Zip5+4 zip codes
+ * Non-alphabetic characters including whitespace, string numerals, and
  */
-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 NonAlpha = Whitespace | Punctuation | NumericString | Bracket | SpecialCharacters;
+type Ipv4 = `${number}.${number}.${number}.${number}`;
 
-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">;
- * ```
+ * Extracts the _required_ keys in the object's type. You also may
+ * optionally filter by the _value_ of the key.
  */
-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>>;
-
+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];
 /**
- * Capitalize all words in a string
+ * Extracts the intersecting/common keys to two objects
  */
-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;
-
+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];
 /**
- * Indicates whether `T` has uppercase characters in it.
- * ```ts
- * // true
- * type T = HasUppercase<"Foobar">;
- * // false
- * type T = HasUppercase<"foobar">;
- * // "unknown"
- * type T = HasUppercase<string>;
- * ```
+ * Extracts the _optional_ keys in the object's type. You also may
+ * optionally filter by the _value_ of the key.
  */
-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>}`;
+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];
 /**
- * Converts uppercase characters to a dash and then the lowercase equivalent
+ * 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
- * // "one-two-three"
- * type T = DashUppercase<"oneTwoThree">;
+ * // "foo"
+ * type Str = KeysWithValue<{ foo: "hi"; bar: 5 }>;
  * ```
- *
- * _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";
+type KeysWithValue<W extends any, T extends object> = {
+    [K in keyof T]: T[K] extends W ? Readonly<K> : never;
+}[keyof T];
 /**
- * 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.
+ * A `PrivateKey` must start with a `_` character and then follow with
+ * an alphabetic character
  */
-type Cardinality1 = OneToOne | OneToMany;
+type PrivateKey = `_${Alpha}${string}`;
 /**
- * Cardinality which expects a singular input and maps to 0,
- * 1, or many outputs.
+ * 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 CardinalityFilter1 = OneToOne | OneToMany | OneToZero;
+type PrivateKeys<T extends object> = {
+    [K in keyof T]: K extends `_${string}` ? K : never;
+}[keyof T];
 /**
- * Cardinality which expects a singular input which is allowed to be
- * _undefined_ or the expected type.
+ * **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 Cardinality0 = ZeroToOne | ZeroToMany | OneToOne | OneToMany;
+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];
 /**
- * Cardinality which expects a singular input -- which is allowed to be
- * _undefined_ -- and maps to 0,
- * 1, or many outputs.
+ * The keys of an object which _are not_ a string type
  */
-type CardinalityFilter0 = ZeroToOne | ZeroToMany | OneToOne | OneToMany | OneToZero | ZeroToZero;
-type CardinalityExplicit = `${number}:${number}`;
+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];
 /**
- * Cardinality of any sort between two types
+ * **RequiredProps**
+ *
+ * Reduces an object type to only key/value pairs where the key is required
  */
-type Cardinality = CardinalityFilter0 | CardinalityFilter1 | ManyToMany | ManyToOne | ManyToZero | CardinalityExplicit;
-type CardinalityTuple<T extends Cardinality> = UnionToTuple<T>;
+type RequiredProps<T extends object> = Pick<T, RequiredKeys<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
+ * **OptionalProps**
+ *
+ * Reduces an object to only key/value pairs where the key is optional
  */
-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[];
-
+type OptionalProps<T extends object> = Pick<T, OptionalKeys<T>>;
 /**
- * Converts a string literal into a _dasherized_ format while ignoring _exterior_ whitespace.
+ * **WithValue**
  *
+ * Reduces an object's type down to only those key/value pairs where the
+ * value is of type `W`.
  * ```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">;
+ * const foo = { a: 1, b: "hi", c: () => "hello" }
+ * // { c: () => "hello" }
+ * type W = WithValue<Function, typeof foo>
  * ```
  */
-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>>>>>;
-
+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>>;
 /**
- * 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"_
+ * Reduces an object to only the key/value pairs where the key is a
+ * string.
  */
-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>;
-
-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;
+type WithStringKeys<T extends object> = Omit<T, NonStringKeys<T>>;
 /**
- * strings which end in the letters "is" should have an "es" added to the end
+ * Reduces an object to only the key/value pairs where the key is numeric.
  */
-type PluralizeEndingIn_IS<T extends string> = T extends `${infer HEAD}is` ? `${HEAD}ises` : T;
+type WithNumericKeys<T extends object> = Omit<T, NonNumericKeys<T>>;
+
 /**
- * singular nouns should have "es" added to the end
+ * **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 PluralizeEndingSingularNoun<T extends string> = T extends `${infer HEAD}${SingularNoun}` ? `${T}es` : T;
+type Transformer<I extends object, O extends SameKeys<I>, K extends keyof I = keyof I> = (input: I, key: K) => O[K];
+
 /**
- * strings which end in the letters "f" or "fe" should have "ves" replace the ending
+ * 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.
  */
-type PluralizeEnding_F<T extends string> = T extends `${infer HEAD}${F}` ? `${HEAD}ves` : T;
+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]>;
+};
 /**
- * singular nouns should have "es" added to the end
+ * 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.
  */
-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`;
+declare const dictArr: <T extends Record<string, Narrowable>>(...dicts: readonly T[]) => DictArrApi<T, readonly T[]>;
 
-/** 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 DictFromKv<T extends readonly {
+    key: string;
+    value: unknown;
+}[]> = {
+    [R in T[number] as R["key"]]: R["value"];
+};
 
 /**
- * **StripStarting**`<T, U>`
+ * Provides a strongly typed _key_ and _value_ for a dictionary `T`
  *
- * 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 Obj = { foo: 1, bar: "hi" };
+ * // ["foo", 1 ]
+ * type Foo = KeyValue<Obj, "foo">;
  * ```
  */
-type StripStarting<T extends string, U extends string> = IfLiteral<T, string extends U ? never : T extends `${U}${infer After}` ? After : T, string>;
+type KeyValue<T extends object, K extends keyof T> = [K & keyof T, ExpandRecursively<T[K]>];
 
 /**
- * **StripEnding**`<T, U>`
- *
- * Will strip off of `T` the ending defined by `U` when
- * both are string literals.
+ * Type utility which takes an object type and converts to an array of KV objects:
  * ```ts
- * type T = "Hello World";
- * type U = " World";
- * // "Hello"
- * type R = StripEnding<T,U>;
+ * // [ {key: "id", value: 123 } | {key: "foo", value: "bar" } ][]
+ * type Arr = KvFrom<{ id: 123, foo: "bar" }>;
  * ```
  */
-type StripEnding<T extends string, U extends string> = IfLiteral<T, string extends U ? never : T extends `${infer Before}${U}` ? Before : T, string>;
-
-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);
+type KvFrom<T extends object> = Array<{
+    [K in keyof T]: {
+        key: K;
+        value: T[K];
+    };
+}[keyof 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.
+ * **KvTuple**
+ *
+ * a key/value of type `T` represented as `[key, kv]`
+ *
  * ```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 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 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]>;
+type KvTuple<T, K extends keyof T> = [K, Record<K, T[K]>];
 
 /**
- * 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`.
+ * **entries**
  *
- * If `V` is not specified then it defaults to _any_ and therefore all KVs are preserved.
+ * 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
- * 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>
+ * 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)) { ... }
  * ```
  */
-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]>;
+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>;
+};
 
 /**
- * **DictPrependWithFn**
+ * **mapValues**
  *
- * 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.
+ * Maps over a dictionary, preserving the keys but allowing the values to be mutated.
  *
- * 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.
+ * ```ts
+ * const colors = { red: 4, blue: 2, green: 3 };
+ * // { red: 8, blue: 4, green: 6 }
+ * const twoX = mapValues(colors, v => v * 2);
+ * ```
  */
-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]>;
+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; };
 
 /**
- * **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
+ * converts an array of strings `["a", "b", "c"]` into a more type friendly
+ * dictionary of the type `{ a: true, b: true, c: true }`
  */
-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]>;
+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]>;
 
 /**
- * Expresses whether an option is "opt" (optional) or "req" (required)
+ * 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 OptRequired = "opt" | "req";
+type FirstKey<T extends object> = UnionToTuple<Keys<T>>[0];
 
-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_
+ * 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.
  *
- * 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
- * }]);
+ * const test = [ ["foo", 1], ["bar", 2] ];
+ * // "foo" | "bar"
+ * type F = FirstOfEach<typeof test>;
  * ```
  */
-declare const mapToFn: ConfiguredMap<DefaultOneToManyMapping>["map"];
+type FirstOfEach<T extends readonly any[][]> = T[number][0] extends T[number][number] ? T[number][0] : never;
+
 /**
- * Provides a `config` method which allows the relationships between _inputs_
- * and _outputs_ to be configured.
+ * 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" }]]>;
+ * ```
  */
-declare const mapToDict: MapperApi;
+type FromDictArray<T extends [string, Record<string, unknown>][]> = ExpandRecursively<UnionToIntersection<T[number][1]>>;
+
 /**
- * **mapTo** _utility_
+ * For a two-dimensional array, returns a _union type_ which combines the first element of the interior
+ * array.
  *
- * This utility creates a strongly typed data mapper which maps from one
- * known source `I` to another `O`.
+ * ```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".
  *
- * Signatures:
+ * > 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
- * 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>( ... );
+ * // { id: 123, foo: "bar" }
+ * const arr = kvToDict([{ key: "id", value: 123 }, { key: "foo", value: "bar" }]);
  * ```
+ *
+ * Note: this is the inverse of `dictToKv()` function
  */
-declare const mapTo: (<I, O>(map: (source: I) => O[]) => Mapper<I, O, FinalizedMapConfig<"req", "I -> O[]", "opt">>) & MapperApi;
+declare function kvToDict<K extends string, V extends Narrowable, T extends readonly Readonly<{
+    key: K;
+    value: V;
+}>[]>(kvArr: T): DictFromKv<T>;
 
 /**
- * Expresses relationship between inputs/outputs:
+ * Type utility which converts `undefined[]` to `unknown[]`
  */
-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>;
+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[]>;
 /**
- * The _user_ configuration of a **mapTo** mapper function
- * which will be finalized by merging it with the appropriate
- * default mapping type.
+ * 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_.
  */
-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;
-}
+declare const asArray: <T extends Narrowable, W extends boolean = true>(thing: T, _widen?: W | undefined) => AsArray<T, W>;
+
 /**
- * A finalized configuration of a **mapTo** mapper functions cardinality
- * relationships between _inputs_ and _outputs_.
+ * Groups an array of data based on the value of a property
+ * in the objects within the array.
+ * ```ts
+ * const data = [ {}, {}, {} ];
  *
- * Note: _this configuration does _not_ yet include the actual mapping
- * configuration between the input and output._
+ * ```
+ *
+ * @ignore not implemented
  */
-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;
-};
+declare function groupBy<T extends Record<string, Narrowable>>(_data: Readonly<T[]>): void;
+
 /**
- * User configuration exposed by a config function which specifies the
- * cardinality already (e.g., `oneToMany()`, `manyToOne()`)
+ * The basic shape of a `Converter`
  */
-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;
+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>>;
 /**
- * **ConfiguredMap**
+ * **AvailableConverters**
  *
- * 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 utility which will produce the correct union type for a "converter"
  */
-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;
-};
+type AvailableConverters<S, N, B, O> = ConverterKeys<S, N, B, O> extends readonly string[] ? TupleToUnion<ConverterInputUnion<[], ConverterKeys<S, N, B, O>>> : never;
+
 /**
- * Extracts the IR, Cardinality, and OR generics from a FinalizedMapConfig
+ * **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}`,
+ * });
+ * ```
  */
-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];
+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;
 /**
- * extracts the MapCardinality from a `FinalizedMapConfig`
+ * Takes a given function and converts it to an explicit representation
+ * where the generics represent the _parameter_ and _return_ typings.
  */
-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];
+declare function ExplicitFunction<T extends (...args: any[]) => any>(fn: T): ExplicitFunction<Parameters<T>, ReturnType<T>>;
+
 /**
- * Merges the types of a userland configuration with a default configuration
+ * **UniqueDictionary**
+ *
+ * A dictionary converted by `arrayToObject()` which expects each key `S` to have a only a
+ * single/unique value.
  */
-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 UniqueDictionary<S extends PropertyKey, N extends Narrowable, T extends Record<keyof T, N> & Record<S, any>> = {
+    [V in T as V[S]]: V;
 };
-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.
+ * **GeneralDictionary**
  *
- * **Note:** this type is designed to guide the userland mapping; refer
- * to `MapFn` if you want the type output by the `mapFn()` utility.
+ * A dictionary converted by `arrayToObject()` which expects each key `S` to have an
+ * array of values.
  */
-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;
+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> = 
 /**
- * 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);
- *    ```
+ * 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.
  */
-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>>;
+<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>;
 /**
- * **Mapper**
+ * 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.
  *
- * 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);
+ * const arr = [
+ *   { kind: "color", favorite: "blue", likes: 100 },
+ *   { kind: "song", favorite: "some song", likes: 25 }
+ * ];
+ * const dict = arrayToObject("kind")(arr);
  * ```
  *
- * 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.
+ * This will produce a dictionary with keys of `color` and `song`.
  */
-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>;
+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>;
 /**
- * **MapInputFrom**
+ * **ifArray**(T, IF, ELSE)
  *
- * Type utility which extracts the `I` type from a fully configured `Mapper`
+ * A utility which evaluates a type `T` for whether it is an array and then
  */
-type MapInputFrom<T extends Mapper> = T extends Mapper<infer I> ? I : never;
+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>;
+
 /**
- * **MapOutputFrom**
- *
- * Type utility which extracts the output [`O`] type from a fully configured `Mapper`
+ * Runtime and type checks whether a variable is a boolean value.
  */
-type MapOutputFrom<T extends Mapper> = T extends Mapper<any, infer O> ? O : never;
+declare function isBoolean<T extends Narrowable>(i: T): IsBoolean<T>;
 /**
- * **MapCardinalityFrom**
+ * **ifBoolean**
  *
- * Type utility which extracts _cardinality_ of a `Mapper`'s inputs to outputs
+ * 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
  */
-type MapCardinalityFrom<T extends Mapper> = T extends Mapper<any, any, infer C> ? C extends FinalizedMapConfig<OptRequired, infer Cardinality, OptRequired> ? Cardinality : never : never;
+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>;
 /**
- * Given a dictionary of type `<T>`, this utility function will
- * make the `<M>` generic property _mutable_ and all other _read-only_.
+ * **ifTrue**
  *
- * ```ts
- * // { foo: string, bar?: Readonly<number> }
- * type Example = MutableProps<{
- *    foo: Readonly<string>,
- *    bar?: number
- * }, "foo">;
- * ```
+ * 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`.
  */
-type MutableProps<T extends {}, M extends keyof T & string> = ExpandRecursively<Mutable<Pick<T, M>> & Readonly<Pick<T, Keys<T, M>>>>;
+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>;
 /**
- * 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).
- *
+ * Checks whether a passed in value is a function and ensures run-time and types
+ * are consistent.
  * ```ts
- * // { foo: string, bar?: number }
- * type Example = RequireProps<{foo?: string, bar?: number}, "foo">;
+ * // 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.
  */
-type RequireProps<T extends {}, R extends keyof T> = ExpandRecursively<Required<Pick<T, R>> & T>;
+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;
 /**
- * **ToFluent**
+ * **ifNull**
  *
- * Converts the typing of a dictionary of functions into the same
- * function signatures but changes the return type to be the Fluent API.
+ * 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.
  *
- * **Note:** this utility also allows a non-fluent API surface `X` to be included as
- * part of the API surface if this is desired.
+ * @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`
  */
-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;
+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;
 /**
- * A _pure_ Fluent API which promotes an API surface where _every_ API endpoint must be a function
- * which returns the same API surface.
+ * **ifNumber**
  *
- * 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.
+ * 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.
  *
- * **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._
+ * @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
  */
-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>>;
-};
+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>;
 /**
- * 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>;
- * ```
+ * 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.
  */
-type FinalReturn<T extends any> = T extends (...args: any[]) => any ? FinalReturn<ReturnType<T>> : T;
+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>;
 
 /**
- * A function which returns a boolean value
+ * **IsString**
+ *
+ * Type utility which returns true/false based on whether `T` is a
+ * string (wide or narrow).
  */
-type LogicFunction<T extends readonly any[]> = (...args: T) => boolean;
-
-type DictFromKv<T extends readonly {
-    key: string;
-    value: unknown;
-}[]> = {
-    [R in T[number] as R["key"]]: R["value"];
-};
-
+type IsString<T> = T extends string ? true : false;
 /**
- * Provides a strongly typed _key_ and _value_ for a dictionary `T`
+ * **IfString**
  *
- * ```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 utility which determines if `T` is a _string_ (wide or narrow) and
+ * returns `IF` type if it is, otherwise returns the type `ELSE`.
  */
-type KvFrom<T extends object> = Array<{
-    [K in keyof T]: {
-        key: K;
-        value: T[K];
-    };
-}[keyof T]>;
+type IfString<T extends Narrowable, //
+IF extends Narrowable, ELSE extends Narrowable> = IsString<T> extends true ? IF : IsString<T> extends false ? ELSE : IF | ELSE;
 
 /**
- * **KvTuple**
+ * **isString**
  *
- * a key/value of type `T` represented as `[key, kv]`
+ * Returns true or false on whether the passed in parameter is a
+ * string (either a wide string or a string literal).
  *
- * ```ts
- * type Obj = { foo: 1, bar: "hi" };
- * // ["foo", { foo: 1 } ]
- * type Foo = KvTuple<Obj, "foo">;
- * ```
+ * The boolean return is traceable by the type system as well as the
+ * runtime system.
+ */
+declare function isString<T>(i: T): IsString<T>;
+/**
+ * **ifString**
  *
- * **Note:** _consider use of `KeyValue<T,K>` as an alternate representation_
+ * 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
  */
-type KvTuple<T, K extends keyof T> = [K, Record<K, T[K]>];
+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;
 
-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]`.
+ * Run-time and type checking of whether a variable is `true`.
  */
-type DictArrayKv<K extends keyof T, T> = [K, Pick<T, K>];
-type DictKvTuple<K extends string> = [K, Record<K, unknown>];
+declare function isTrue<T extends Narrowable>(i: T): IsTrue<T>;
 /**
- * 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" }]
- * ]
- * ```
+ * **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`.
  */
-type DictArray<T> = Array<{
-    [K in keyof T]: DictArrayKv<K, T>;
-}[keyof T]>;
+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;
 /**
- * Returns the _first_ key in an object.
+ * **ifUndefined**
  *
- * **Note:** key order is not guarenteed so typically this is used
- * for a key/value pair where only one key is expected
+ * 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`
  */
-type FirstKey<T extends object> = UnionToTuple<Keys<T>>[0];
+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>>;
 /**
- * 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.
+ * 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
  */
-type FirstKeyValue<T extends object> = FirstKey<T> extends keyof T ? T[FirstKey<T>] : never;
-
+declare function box<T extends Narrowable>(value: T): Box<T>;
+declare function isBox(thing: Narrowable): thing is Box<any>;
 /**
- * For a two-dimensional array, returns a _union type_ which combines the first element of the interior
- * array.
+ * **boxDictionaryValues**(dict)
  *
- * ```ts
- * const test = [ ["foo", 1], ["bar", 2] ];
- * // "foo" | "bar"
- * type F = FirstOfEach<typeof test>;
- * ```
+ * Runtime utility which boxes each value in a dictionary
  */
-type FirstOfEach<T extends readonly any[][]> = T[number][0] extends T[number][number] ? T[number][0] : never;
-
+declare function boxDictionaryValues<T extends {}>(dict: T): { [K in keyof T]: Box<T[K]>; };
+type Unbox<T> = T extends Box<infer U> ? U : T;
 /**
- * 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" }]]>;
- * ```
+ * **unbox**(maybeBox)
+ *
+ * Unboxes a value if it was a box; otherwise it leaves _as is_.
  */
-type FromDictArray<T extends [string, Record<string, unknown>][]> = ExpandRecursively<UnionToIntersection<T[number][1]>>;
+declare function unbox<T>(val: T): Unbox<T>;
 
 /**
- * For a two-dimensional array, returns a _union type_ which combines the first element of the interior
- * array.
+ * Build a _type_ from two run-time dictionaries.
  *
- * ```ts
- * // 1 | 2
- * type F = SecondOfEach<[ ["foo", 1], ["bar", 2] ]>;
- * ```
+ * 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
  */
-type SecondOfEach<T extends any[][]> = T[number][1] extends T[number][number] ? T[number][1] : never;
+declare function defineType<N extends Narrowable, TLiteral extends Record<string, N>>(literal?: TLiteral): <TWide extends object>(wide?: TWide) => ExpandRecursively<TWide & TLiteral>;
 
-declare function createFnWithProps<F extends Function, P extends {}>(fn: F, props: P): F & P;
 /**
- * Adds a dictionary of key/value pairs to a function.
+ * An identity function for any type, with the goal of preserving literal type information
+ * whereever possible.
  */
-declare function fnWithProps<A extends any[], R extends any, P extends {}>(fn: ((...args: A) => R), props: P): ((...args: A) => R) & P;
+declare const identity: <N extends Narrowable, T extends string | number | boolean | symbol | Record<any, N> | null | undefined>(v: T) => T;
+
 /**
- * Adds read-only (and narrowly typed) key/value pairs to a function
+ * 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 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>;
+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;
 
 /**
- * Provides the _keys_ of an object with the `keyof T` made explicit.
+ * **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>;
+ * ```
  */
-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>>[];
+type StripTrailing<T extends string, U extends string> = IfLiteral<T, string extends U ? never : T extends `${infer Before}${U}` ? Before : T, string>;
 
 /**
- * **ruleSet**
+ * **stripTrailing**(content, strip)
  *
- * Defines a ruleset composed of _dynamic_ and _static_ boolean operators.
+ * 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>`
  *
- * - the first function call defines _dynamic_ props (_optional_)
- * - the second function call defines static values
+ * Will ensure that `T` ends with the substring `U` when
+ * both are string literals.
  *
  * ```ts
- * const rs = ruleSet(
- *    r => r.state()( { maybe: r => r.extends({ foo: 1 }) })
- * )(
- *    { color: true, age: false }
- * );
+ * type T = "Hello";
+ * type U = " World";
+ * // "Hello World"
+ * type R = EnsureTrailing<T,U>;
  * ```
  */
-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;
+type EnsureTrailing<T extends string, U extends string> = IfLiteral<T, string extends U ? never : T extends `${string}${U}` ? T : `${T}${U}`, string>;
 
 /**
- * Groups a number of "logic functions" together by combining their results using
- * the logical **AND** operator.
+ * **ensureTrailing**(content, strip)
  *
- * **Note:** a "logic function" is any function which returns a boolean
+ * 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 const and: <T extends any[]>(...ops: readonly LogicFunction<T>[]) => LogicFunction<T>;
+declare function ensureTrailing<T extends string, U extends string>(content: T, ensure: U): EnsureTrailing<T, U>;
 
-declare function or<O extends readonly boolean[]>(...conditions: O): Or<O>;
+/**
+ * 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;
 
 /**
- * Groups a number of "logic functions" together by combining their results using
- * the logical **NOT** operator.
+ * **Break<T,D>**
  *
- * **Note:** a "logic function" is any function which returns a boolean
+ * 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", " ">;
+ * ```
  */
-declare const not: <T extends any[]>(op: LogicFunction<T>) => LogicFunction<T>;
+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, ""]));
 
-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:
+ * Concatenates two arrays (of literals).
  * ```ts
- * const onlyPrivate = filter({ startsWith: "_" });
- * const privateFiles = files.filter(onlyPrivate);
+ * // [ "foo", "bar", "baz" ]
+ * type T = ArrConcat<["foo"], ["bar", "baz"]>;
  * ```
- *
- */
-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;
+type ArrConcat<A extends any[], B extends any[]> = [...A, ...B];
+
 /**
- * **filter**
- *
- * A higher order helper utility which builds a boolean _filter_ function based on a simple
- * configuration object. Support either _string_ or _numeric_ filters.
- *
+ * Type utility which takes a string `S` and replaces the substring `W` with `P`.
  * ```ts
- * const str = filter({startsWith: ["_", "."], endsWith: ".md"});
- * const num = filter({ greaterThan: 55, notEqual: [66, 77]});
+ * const fooy = "fooy";
+ * // "Foo"
+ * type Foo = Replace<typeof fooy, "y", "">;
  * ```
  *
- * 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.
+ * Note: _the first match is replaced and all subsequent matches are ignored_
  */
-declare const filter: <F extends FilterDefn | NotFilter, U extends boolean | "no-impact", C extends LogicalCombinator>(config: F, logicCombinator?: C, ifUndefined?: U) => FilterFn<UnwrapNot<F>>;
+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;
 
 /**
- * Passing in an array of strings, you are passed back a dictionary with
- * all the keys being the strings and values set to `true`.
+ * Trims off whitespace on left of string
  * ```ts
- * // { bar: true, bar: true } as const;
- * const d - dictArr(arr);
- *
- * const fooBar = arrayToKeyLookup("foo", "bar");
+ * // "foobar "
+ * type T = TrimLeft<"\n\t  foobar ">;
+ * // string
+ * type T = TrimLeft<string>;
  * ```
  */
-declare function arrayToKeyLookup<T extends readonly string[]>(...keys: T): Record<T[number], true>;
+type TrimLeft<S extends string> = string extends S ? string : S extends `${Whitespace}${infer Right}` ? TrimLeft<Right> : S;
 
-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>;
+/**
+ * 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>, "">;
 
 /**
- * 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.
+ * Trims off whitespace on left of string
+ * ```ts
+ * // "\n foobar"
+ * type T = TrimRight<"\n foobar \t">;
+ * // string
+ * type T = TrimRight<string>;
+ * ```
  */
-declare function dictionaryTransform<I extends object, O extends SameKeys<I>>(input: I, transform: Transformer<I, O>): O;
+type TrimRight<S extends string> = string extends S ? string : S extends `${infer Right}${Whitespace}` ? TrimRight<Right> : S;
 
-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.
+ * Provides the _left_ whitespace of a string
+ * ```ts
+ * // "\n\t "
+ * type T = LeftWhitespace<"\n\t foobar">;
+ * ```
  */
-declare const dictArr: <T extends Record<string, Narrowable>>(...dicts: readonly T[]) => DictArrApi<T, readonly T[]>;
+type RightWhitespace<S extends string> = string extends S ? string : Replace<S, TrimRight<S>, "">;
 
 /**
- * **entries**
- *
- * Provides an _iterable_ over the passed in dictionary object where each iteration
- * provides a tuple of `[ key, value ]` which preserve type literals.
+ * 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.
  *
- * 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)) { ... }
+ * // 3
+ * type Three = StringLength<"foo">;
  * ```
  */
-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>;
-};
+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"];
 
 /**
- * **mapValues**
- *
- * Maps over a dictionary, preserving the keys but allowing the values to be mutated.
- *
+ * Trims off blank spaces, `\n` and `\t` characters from both sides of a _string literal_.
  * ```ts
- * const colors = { red: 4, blue: 2, green: 3 };
- * // { red: 8, blue: 4, green: 6 }
- * const twoX = mapValues(colors, v => v * 2);
+ * // "foobar"
+ * type T = Trim<"\n\t  foobar ">;
+ * // string
+ * type T = Trim<string>;
  * ```
  */
-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; };
+type Trim<S extends string> = string extends S ? string : S extends `${Whitespace}${infer Right}` ? Trim<Right> : S extends `${infer Left}${Whitespace}` ? Trim<Left> : S;
 
 /**
- * converts an array of strings `["a", "b", "c"]` into a more type friendly
- * dictionary of the type `{ a: true, b: true, c: true }`
+ * An email address
  */
-declare function strArrayToDict<T extends readonly string[]>(...strings: T): ExpandRecursively<Record<T[number], true>>;
+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}`;
 
 /**
- * Converts a dictionary object into an array of dictionaries with `key` and `value` properties
+ * 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
- * // [ { key: "id", value: 123 }, { key: "foo", value: "bar" } ]
- * const arr = dictToKv({ id: 123, foo: "bar" });
+ * // "FooBar"
+ * type T = PascalCase<"fooBar">;
+ * type T = PascalCase<"foo-bar">;
+ * type T = PascalCase<"foo_bar">;
+ * type T = PascalCase<"\n foo_bar \t">;
  * ```
  */
-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 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>>;
 
-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.
+ * Capitalize all words in a string
  */
-declare function filterDictArray<T extends object, C extends DictArrayFilterCallback<keyof T, T, true | false>>(dictArr: DictArray<T>, cb: C): DictArray<Omit<T, "">>;
+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;
 
 /**
- * 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.
+ * Indicates whether `T` has uppercase characters in it.
+ * ```ts
+ * // true
+ * type T = HasUppercase<"Foobar">;
+ * // false
+ * type T = HasUppercase<"foobar">;
+ * // "unknown"
+ * type T = HasUppercase<string>;
+ * ```
  */
-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>>;
+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 an array of dictionaries with `key` and `value` properties to a singular dictionary.
+ * Converts uppercase characters to a dash and then the lowercase equivalent
  * ```ts
- * // { id: 123, foo: "bar" }
- * const arr = kvToDict([{ key: "id", value: 123 }, { key: "foo", value: "bar" }]);
+ * // "one-two-three"
+ * type T = DashUppercase<"oneTwoThree">;
  * ```
  *
- * Note: this is the inverse of `dictToKv()` function
+ * _Intended to be used as a lower level utility; prefer `Dasherize<T>` for more full-fledged
+ * dash solution_.
  */
-declare function kvToDict<K extends string, V extends Narrowable, T extends readonly Readonly<{
-    key: K;
-    value: V;
-}>[]>(kvArr: T): DictFromKv<T>;
+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";
 /**
- * Type utility which converts `undefined[]` to `unknown[]`
+ * 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 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[]>;
+type Cardinality1 = OneToOne | OneToMany;
 /**
- * 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_.
+ * Cardinality which expects a singular input and maps to 0,
+ * 1, or many outputs.
  */
-declare const asArray: <T extends Narrowable, W extends boolean = true>(thing: T, _widen?: W | undefined) => AsArray<T, W>;
-
+type CardinalityFilter1 = OneToOne | OneToMany | OneToZero;
 /**
- * Groups an array of data based on the value of a property
- * in the objects within the array.
- * ```ts
- * const data = [ {}, {}, {} ];
- *
- * ```
- *
- * @ignore not implemented
+ * Cardinality which expects a singular input which is allowed to be
+ * _undefined_ or the expected type.
  */
-declare function groupBy<T extends Record<string, Narrowable>>(_data: Readonly<T[]>): void;
-
-type ExplicitFunction<P extends any[], R extends any> = (...args: P) => R;
+type Cardinality0 = ZeroToOne | ZeroToMany | OneToOne | OneToMany;
 /**
- * Takes a given function and converts it to an explicit representation
- * where the generics represent the _parameter_ and _return_ typings.
+ * Cardinality which expects a singular input -- which is allowed to be
+ * _undefined_ -- and maps to 0,
+ * 1, or many outputs.
  */
-declare function ExplicitFunction<T extends (...args: any[]) => any>(fn: T): ExplicitFunction<Parameters<T>, ReturnType<T>>;
-
+type CardinalityFilter0 = ZeroToOne | ZeroToMany | OneToOne | OneToMany | OneToZero | ZeroToZero;
+type CardinalityExplicit = `${number}:${number}`;
 /**
- * **UniqueDictionary**
- *
- * A dictionary converted by `arrayToObject()` which expects each key `S` to have a only a
- * single/unique value.
+ * Cardinality of any sort between two types
  */
-type UniqueDictionary<S extends PropertyKey, N extends Narrowable, T extends Record<keyof T, N> & Record<S, any>> = {
-    [V in T as V[S]]: V;
-};
+type Cardinality = CardinalityFilter0 | CardinalityFilter1 | ManyToMany | ManyToOne | ManyToZero | CardinalityExplicit;
+type CardinalityTuple<T extends Cardinality> = UnionToTuple<T>;
 /**
- * **GeneralDictionary**
- *
- * A dictionary converted by `arrayToObject()` which expects each key `S` to have an
- * array of values.
+ * The first or _input_ part of the Cardinality relationship
  */
-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> = 
+type CardinalityIn<T extends Cardinality> = T extends `${infer IN}:${string}` ? IN : never;
 /**
- * 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.
+ * The second or _output_ part of the Cardinality relationship
  */
-<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>;
+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 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.
+ * Converts a string literal into a _dasherized_ format while ignoring _exterior_ whitespace.
  *
  * ```ts
- * const arr = [
- *   { kind: "color", favorite: "blue", likes: 100 },
- *   { kind: "song", favorite: "some song", likes: 25 }
- * ];
- * const dict = arrayToObject("kind")(arr);
+ * // "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">;
  * ```
- *
- * 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>;
+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>>>>>;
 
-interface Box<T> {
-    __kind: "box";
-    value: T;
-    /**
-     * Unbox the boxed value in the narrowest possible type.
-     *
-     * **Note:** _if you want a wider type definition use `wide()`
-     * instead._
-     */
-    unbox(): 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).
+ * **EnsureLeading**`<T, U>`
  *
- * NOTE: this feature is immature at best right now
+ * 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>;
+ * ```
  */
-declare function box<T extends Narrowable>(value: T): Box<T>;
-declare function isBox(thing: unknown): thing is Box<any>;
-type Unbox<T> = T extends Box<infer U> ? U : T;
-declare function unbox<T>(thing: T): Unbox<T>;
+type EnsureLeading<T extends string, U extends string> = IfLiteral<T, string extends U ? never : T extends `${U}${string}` ? T : `${U}${T}`, string>;
 
 /**
- * Build a _type_ from two run-time dictionaries.
+ * 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>;
+ * ```
  *
- * 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
+ * Note: _if the value passed in is a "string" then the result will be "unknown"_
  */
-declare function defineType<N extends Narrowable, TLiteral extends Record<string, N>>(literal?: TLiteral): <TWide extends object>(wide?: TWide) => ExpandRecursively<TWide & TLiteral>;
+type IsCapitalized<T extends string> = string extends T ? "unknown" : T extends Capitalize<T> ? true : false;
 
 /**
- * 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;
+ * **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>;
 
+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;
 /**
- * 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
+ * strings which end in the letters "is" should have an "es" added to the end
  */
-declare function idLiteral<T extends {
-    id: I;
-}, I extends PropertyKey>(o: T): T & {
-    id: T["id"];
-};
+type PluralizeEndingIn_IS<T extends string> = T extends `${infer HEAD}is` ? `${HEAD}ises` : T;
 /**
- * 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
+ * singular nouns should have "es" added to the end
  */
-declare function nameLiteral<T extends {
-    name: I;
-}, I extends PropertyKey>(o: T): T & {
-    name: T["name"];
-};
+type PluralizeEndingSingularNoun<T extends string> = T extends `${infer HEAD}${SingularNoun}` ? `${T}es` : T;
 /**
- * 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
+ * strings which end in the letters "f" or "fe" should have "ves" replace the ending
  */
-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;
-};
+type PluralizeEnding_F<T extends string> = T extends `${infer HEAD}${F}` ? `${HEAD}ves` : T;
 /**
- * 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.
+ * singular nouns should have "es" added to the end
  */
-declare function literal<N extends Narrowable, T extends Record<keyof T, N>>(obj: T): T;
-
-declare function stripEnding<T extends string, U extends string>(content: T, strip: U): StripEnding<T, U>;
+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`;
 
-declare function stripStarting<T extends string, U extends string>(content: T, strip: U): StripStarting<T, U>;
+/** 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>>>>>;
 
 /**
- * **Suggest**
+ * **StripStarting**`<T, U>`
  *
- * 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.
+ * 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 Suggest<T extends string> = T | (string & {});
+type StripLeading<T extends string, U extends string> = IfLiteral<T, string extends U ? never : T extends `${U}${infer After}` ? After : T, string>;
+
+type NetworkProtocol = "http" | "https" | "file" | "ws" | "wss";
 /**
- * **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 & {});
-
-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;
-
-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 any>(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 = <TArgs extends any[]>(...args: TArgs) => any;
-type AnyFunction<TProps extends {} | never = never> = TProps extends {} ? HybridFunction<TProps> : SimpleFunction;
-/**
- * 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.
+ * A literal variant of _string_ which is meant to represent a domain name
+ * (e.g., `www.someplace.com`, etc.)
  */
-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;
+type DomainName = `${AlphaNumeric}${string}.${AlphaNumeric}${string}` | `${AlphaNumeric}${string}.${AlphaNumeric}${string}.${string}` | `${AlphaNumeric}${string}.${AlphaNumeric}${string}.${string}.${string}`;
+type RelativeUrl = `${VariableName | "/"}`;
 /**
- * **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`
+ * 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.
  */
-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 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);
 
-type IsNumber<T> = T extends number ? true : false;
-declare function isNumber<T>(i: T): T extends number ? true : false;
 /**
- * **ifNumber**
+ * **ensureLeading**(content, strip)
  *
- * 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.
+ * 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 isObject<T extends unknown>(i: T): IsObject<T>;
+declare function ensureLeading<T extends string, U extends string>(content: T, ensure: U): EnsureLeading<T, U>;
 
 /**
- * **IsString**
+ * **Suggest**
  *
- * Type utility which returns true/false based on whether `T` is a
- * string (wide or narrow).
+ * 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 IsString<T> = T extends string ? true : false;
+type Suggest<T extends string> = T | (string & {});
 /**
- * **IfString**
+ * **SuggestNumeric**`<T>`
  *
- * 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 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 IfString<T extends Narrowable, //
-IF extends Narrowable, ELSE extends Narrowable> = IsString<T> extends true ? IF : IsString<T> extends false ? ELSE : IF | ELSE;
+type SuggestNumeric<T extends number> = T | (number & {});
 
 /**
- * **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**
+ * **wide**
  *
- * 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
+ * Provides a dictionary of _wide_ types
  */
-declare function ifString<T extends Narrowable, IF extends Narrowable, ELSE extends Narrowable>(val: T, ifVal: IF, elseVal: ELSE): IfString<T, IF, ELSE>;
-
-declare function isSymbol<T>(i: T): T extends symbol ? true : false;
+declare const wide: {
+    readonly boolean: boolean;
+    readonly string: string;
+    readonly number: number;
+    readonly symbol: Symbol;
+    readonly null: null;
+    readonly undefined: undefined;
+};
 
-/**
- * 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>;
+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;
 
-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.
+ * **TypeGuard**
  *
- * @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`
+ * a typing for a **TS** type-guard which evaluates an _unknown_ input
+ * and determines if it is of type `T`.
  */
-declare function ifUndefined<T extends Narrowable, IF extends Narrowable, ELSE extends Narrowable>(val: T, ifVal: IF, elseVal: ELSE): IsUndefined<T> extends true ? IF : ELSE;
+type TypeGuard<T> = (thing: unknown) => thing is T;
 
 type Type<T extends any, V extends Function> = {
     name: string;
@@ -2573,4 +2357,360 @@ interface IFluentConfigurator<C> {
  */
 declare function FluentConfigurator<I>(initial?: I): IFluentConfigurator<{}>;
 
-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, DomainName, DynamicRule, DynamicRuleSet, Email, EndsWith, EnumValues, Equal, 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, 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, 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, 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, StripEnding, StripStarting, 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, condition, createFnWithProps, defineProperties, defineType, dictArr, dictToKv, dictionaryTransform, entries, filter, filterDictArray, fnWithProps, groupBy, idLiteral, idTypeGuard, identity, ifArray, ifArrayPartial, ifBoolean, ifFalse, ifNull, ifNumber, 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, readonlyFnWithProps, ruleSet, strArrayToDict, stripEnding, stripStarting, type, typeApi, unbox, withValue };
+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, 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, readonlyFnWithProps, ruleSet, strArrayToDict, stripTrailing, type, typeApi, unbox, wide, withValue };