inferred-types 0.26.0 → 0.28.0

package/dist/index.d.ts

@@ -215,11 +215,213 @@ declare type Keys<T extends Record<string, any> | readonly string[], W extends s
  */
 declare type Length<T extends readonly any[]> = T["length"];
 
+/**
+ * Converts a Tuple type into a _union_ of the tuple elements
+ * ```ts
+ * const arr = [1, 3, 5] as const;
+ * // 1 | 3 | 5
+ * type U = TupleToUnion<typeof arr>;
+ * ```
+ */
+declare type TupleToUnion<T> = Mutable<T> extends any[] ? Mutable<T>[number] : never;
+
+/**
+ * UnionToIntersection<{ foo: string } | { bar: string }> =
+ *  { foo: string } & { bar: string }.
+ */
+declare type UnionToIntersection<U> = (U extends unknown ? (arg: U) => 0 : never) extends (arg: infer I) => 0 ? I : never;
+
+/**
+ * LastInUnion<1 | 2> = 2.
+ */
+declare type LastInUnion<U> = UnionToIntersection<U extends unknown ? (x: U) => 0 : never> extends (x: infer L) => 0 ? L : never;
+/**
+ * UnionToTuple<1 | 2> = [1, 2].
+ */
+declare type UnionToTuple<U, Last = LastInUnion<U>> = [U] extends [never] ? [] : [...UnionToTuple<Exclude<U, Last>>, Last];
+
+declare type Widen<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
+
+/**
+ * **IsBooleanLiteral**
+ *
+ * Type utility which returns true/false if the boolean value is a _boolean literal_ versus
+ * just the wider _boolean_ type.
+ */
+declare type IsBooleanLiteral<T extends boolean> = boolean extends T ? false : true;
+/**
+ * **IfBooleanLiteral**
+ *
+ * Branch utility which returns `IF` type when `T` is a boolean literal and `ELSE` otherwise
+ */
+declare type IfBooleanLiteral<T extends boolean, IF, ELSE> = IsBooleanLiteral<T> extends true ? IF : ELSE;
+
+/**
+ * **IsStringLiteral**
+ *
+ * Type utility which returns true/false if the string a _string literal_ versus
+ * just the _string_ type.
+ */
+declare type IsStringLiteral<T extends string> = string extends T ? false : true;
+/**
+ * **IfStringLiteral**
+ *
+ * Branch utility which returns `IF` type when `T` is a string literal and `ELSE` otherwise
+ */
+declare type IfStringLiteral<T extends string, IF, ELSE> = IsStringLiteral<T> extends true ? IF : ELSE;
+
+/**
+ * **IsNumericLiteral**
+ *
+ * Type utility which returns true/false if the numeric value a _numeric literal_ versus
+ * just the _number_ type.
+ */
+declare type IsNumericLiteral<T extends number> = number extends T ? false : true;
+/**
+ * **IfNumericLiteral**
+ *
+ * Branch utility which returns `IF` type when `T` is a numeric literal and `ELSE` otherwise
+ */
+declare type IfNumericLiteral<T extends number, IF, ELSE> = IsNumericLiteral<T> extends true ? IF : ELSE;
+
+/**
+ * **IsLiteral**
+ *
+ * Type utility which returns true/false if the value passed -- a form of a
+ * string, number, or boolean -- is a _literal_ value of that type (true) or
+ * the more generic wide type (false).
+ */
+declare type IsLiteral<T> = [T] extends [string] ? IsStringLiteral<T> : [T] extends [boolean] ? IsBooleanLiteral<T> : [T] extends [number] ? IsNumericLiteral<T> : false;
+/**
+ * **IsOptionalLiteral**
+ *
+ * Type utility which returns true/false if the value passed -- a form of a
+ * string, number, or boolean -- is a _literal_ value of that type (true) or
+ * the more generic wide type (false).
+ *
+ * This type also strips off _undefined_ from any possible union type to evaluate
+ * to `true` even when a literal value is in union with _undefined_. If you don't
+ * want to test for the union with _undefined_ use the `IsOptional` utility instead.
+ */
+declare type IsOptionalLiteral<T> = [Exclude<T, undefined>] extends [string] ? IsStringLiteral<Exclude<T, undefined>> : [Exclude<T, undefined>] extends [boolean] ? IsBooleanLiteral<Exclude<T, undefined>> : [Exclude<T, undefined>] extends [number] ? IsNumericLiteral<Exclude<T, undefined>> : false;
+/**
+ * **IfLiteral**
+ *
+ * Branch type utility with return `IF` when `T` is a _literal_ value and `ELSE` otherwise
+ */
+declare type IfLiteral<T, IF, ELSE> = IsLiteral<T> extends true ? IF : ELSE;
+/**
+ * **IfOptionalLiteral**
+ *
+ * Branch type utility with return `IF` when `T` is a _literal_ value (with possibly
+ * the inclusion of _undefined_); otherwise returns the type `ELSE`
+ */
+declare type IfOptionalLiteral<T, IF, ELSE> = IsOptionalLiteral<T> extends true ? IF : ELSE;
+
+/**
+ * **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`.
+ */
+declare type Includes<TSource extends string | 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;
+
+declare type IsScalar<T> = [T] extends [string] ? true : [T] extends [number] ? true : [T] extends [boolean] ? true : false;
+/**
+ * **IfScalar**
+ *
+ * Branch type utility which returns `IF` when `T` is a scalar value and `ELSE` otherwise
+ */
+declare type IfScalar<T, IF, ELSE> = IsScalar<T> extends true ? IF : ELSE;
+
+/**
+ * **Extends**
+ *
+ * Boolean type utility which returns `true` if `E` _extends_ `T`.
+ */
+declare type Extends<E, T> = E extends T ? true : false;
+/**
+ * **IfExtends**
+ *
+ * Branching type utility which returns type `IF` when `E` _extends_ `T`; otherwise
+ * it will return the type `ELSE`.
+ */
+declare type IfExtends<E, T, IF, ELSE> = Extends<E, T> extends true ? IF : ELSE;
+
+/**
+ * Often when mutating the shape of an object you will end up with the union of a number of
+ * `Record<string, x>` and `Record<string, y>` which is messy to look at and take away meaning.
+ *
+ * This type utility will cleanup an object and return a simple dictionary definition for it.
+ */
+declare type SimplifyObject<T extends {}> = ExpandRecursively<UnionToIntersection<ExpandRecursively<T>>>;
+
+/**
+ * **IsUndefined**
+ *
+ * Boolean type utility returns `true` if `T` is undefined; `false` otherwise
+ */
+declare type IsUndefined<T> = T extends undefined ? true : false;
+/**
+ * **IfUndefined**
+ *
+ * Branch utility which returns `IF` type when `T` is an _undefined_ value
+ * otherwise returns `ELSE` type
+ */
+declare type IfUndefined<T, IF, ELSE> = IsUndefined<T> extends true ? IF : ELSE;
+
+/**
+ * **TypeDefault**
+ *
+ * A type utility designed to help maintain strong and narrow types where
+ * you have a value `T` which _might_ be **undefined** and a type `D` which
+ * defines all the _default_ type for `T`.
+ *
+ * - In all cases we compare first whether `T` is undefined and replace it's
+ * type with `D` 1-for-1 if it is
+ * - To address a larger set of use cases, when `D` _extends_ an object we will
+ * compare each property of `D` against `T`
+ * ```ts
+ * type I = { foo?: "foo" |  undefined; bar?: 42 | 53 | undefined };
+ * type D = { foo: "foo"; bar: 53 };
+ * type DF = TypeDefault<I,D>; // `D`
+ * const i = { foo: undefined, bar: 99 } as const;
+ * type DF2 = TypeDefault<typeof i, D>; // `{ foo: "foo"; bar: 99 }`
+ * ```
+ */
+declare 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
+ */
+declare 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
+ */
+declare type IfObject<T, IF, ELSE> = IsObject<T> extends true ? IF : ELSE;
+
 /**
  * Makes a readonly structure mutable
  */
 declare type Mutable<T> = {
-    -readonly [K in keyof T]: T[K];
+    -readonly [K in keyof T]: IsObject<T[K]> extends true ? Mutable<T[K]> : T[K];
 };
 
 /**
@@ -279,20 +481,6 @@ declare type Opaque<Type, Token = unknown> = Type & {
  */
 declare type Retain<T, K extends keyof T> = Pick<T, Include<keyof T, K>>;
 
-/**
- * UnionToIntersection<{ foo: string } | { bar: string }> =
- *  { foo: string } & { bar: string }.
- */
-declare type UnionToIntersection<U> = (U extends unknown ? (arg: U) => 0 : never) extends (arg: infer I) => 0 ? I : never;
-
-/**
- * Often when mutating the shape of an object you will end up with the union of a number of
- * `Record<string, x>` and `Record<string, y>` which is messy to look at and take away meaning.
- *
- * This type utility will cleanup an object and return a simple dictionary definition for it.
- */
-declare type SimplifyObject<T extends {}> = ExpandRecursively<UnionToIntersection<ExpandRecursively<T>>>;
-
 /**
  * **SameKeys**
  *
@@ -429,7 +617,6 @@ declare function isNull<T>(i: T): T extends null ? true : false;
 
 declare function isNumber<T>(i: T): T extends number ? true : false;
 
-declare type IsObject<T> = Mutable<T> extends Record<string, any> ? T extends FunctionType ? false : Mutable<T> extends any[] ? false : true : false;
 declare type ObjectType = Not<Record<string, Narrowable>, FunctionType>;
 /**
  * Detects whether the passed in `v` is of type "object" where an object
@@ -579,26 +766,192 @@ O extends (...args: any[]) => any = (...args: any[]) => any> = SimplifyObject<{
 declare type Get<T, K> = K extends `${infer FK}.${infer L}` ? FK extends keyof T ? Get<T[FK], L> : never : K extends keyof T ? T[K] : never;
 
 /**
- * **MapTo**
+ * Expresses whether an option is "opt" (optional) or "req" (required)
+ */
+declare 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">;
+declare type DefaultOneToManyMapping = typeof DEFAULT_ONE_TO_MANY_MAPPING;
+declare type DefaultOneToOneMapping = typeof DEFAULT_ONE_TO_ONE_MAPPING;
+declare type DefaultManyToOneMapping = typeof DEFAULT_MANY_TO_ONE_MAPPING;
+/**
+ * **mapTo** _utility_
+ *
+ * This utility -- by default -- creates a strongly typed 1:M data mapper which maps from one
+ * known source `I` to any array of another `O[]`:
+ * ```ts
+ * const mapper = mapTo<I, O>(i => [{
+ *    foo: i.bar
+ * }]);
+ * ```
+ */
+declare const mapToFn: ConfiguredMap<DefaultOneToManyMapping>["map"];
+/**
+ * Provides a `config` method which allows the relationships between _inputs_
+ * and _outputs_ to be configured.
+ */
+declare const mapToDict: MapperApi;
+/**
+ * **mapTo** _utility_
  *
- * Maps from one type `I` to another `O[]`
+ * This utility creates a strongly typed data mapper which maps from one
+ * known source `I` to another `O`.
  *
- * **Note:** because the output is an array you can easily support `1:1` and `1:M` mappings
- * but not a filtering operation (e.g., `1:0`); if you need this then use `MapToWithFiltering`
- * instead.
+ * Signatures:
+ * ```ts
+ * const defMap = mapTo<I,O>( ... );
+ * const configured = mapTo.config({ output: "req" }).map<I,O>( ... );
+ * const one2one = mapTo.oneToOne().map<I,O>( ... );
+ * const many2one = mapTo.manyToOne().map<I,O>( ... );
+ * ```
+ */
+declare const mapTo: (<I, O>(map: (source: I) => O[]) => <S extends I | I[]>(source: S) => S extends I[] ? O[] : O[] | null) & MapperApi;
+
+/**
+ * Expresses relationship between inputs/outputs:
  */
-declare type MapTo<I extends {}, O extends {}> = (i: I) => O[];
+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"
+}
+declare type MapCardinalityIllustrated = EnumValues<MapCardinality>;
+/**
+ * The _user_ configuration of a **mapTo** mapper function
+ * which will be finalized by merging it with the appropriate
+ * default mapping type.
+ */
+interface MapConfig<IR extends OptRequired | undefined = undefined, D extends MapCardinalityIllustrated | undefined = undefined, OR extends OptRequired | undefined = undefined> {
+    input?: IR;
+    output?: OR;
+    cardinality?: D;
+}
+/**
+ * A finalized configuration of a **mapTo** mapper functions cardinality
+ * relationships between _inputs_ and _outputs_.
+ *
+ * Note: _this configuration does _not_ yet include the actual mapping
+ * configuration between the input and output._
+ */
+declare type FinalizedMapConfig<IR extends OptRequired, D extends MapCardinalityIllustrated, OR extends OptRequired> = Required<MapConfig<IR, D, OR>> & {
+    finalized: true;
+};
+/**
+ * User configuration exposed by a config function which specifies the
+ * cardinality already (e.g., `oneToMany()`, `manyToOne()`)
+ */
+declare type MapCardinalityConfig<IR extends OptRequired | undefined, OR extends OptRequired | undefined> = {
+    input?: IR;
+    output?: OR;
+};
+/**
+ * **ConfiguredMap**
+ *
+ * A partial application of the mapTo() utility which has expressed the
+ * configuration of the _inputs_ and _outputs_ and provides a `.map()`
+ * method which allows the user configure the specifics of the mapping.
+ */
+declare type ConfiguredMap<C extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>> = {
+    map: <I, O>(map: MapTo<I, O, C>) => MapFn<I, O, C>;
+    input: MapIR<C>;
+    cardinality: MapCard<C>;
+    output: MapOR<C>;
+};
+/**
+ * Extracts the IR, Cardinality, and OR generics from a FinalizedMapConfig
+ */
+declare 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` */
+declare type MapIR<T extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>> = DecomposeMapConfig<T>[0];
+/**
+ * extracts the MapCardinality from a `FinalizedMapConfig`
+ */
+declare type MapCard<T extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>> = DecomposeMapConfig<T>[1];
+/** extracts OR from a `FinalizedMapConfig` */
+declare type MapOR<T extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>> = DecomposeMapConfig<T>[2];
+/**
+ * Merges the types of a userland configuration with a default configuration
+ */
+declare 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;
+declare 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>>;
+};
+declare 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;
+declare 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;
 /**
- * **MapToWithFiltering**
+ * **MapTo<I, O>**
+ *
+ * A mapping function between an input type `I` and output type `O`.
  *
- * Maps from one type `I` to another `(O | null)[]`
+ * **Note:** this type is designed to guide the userland mapping; refer
+ * to `MapFn` if you want the type output by the `mapFn()` utility.
+ */
+declare type MapTo<I, O, C extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>> = 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>>;
+declare 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;
+declare type MapFnInput<I, IR extends OptRequired, D extends MapCardinalityIllustrated> = D extends "I -> O[]" | MapCardinality.OneToMany ? IR extends "opt" ? I | I[] | undefined : I | I[] : D extends MapCardinality.OneToOne | "I -> O" ? IR extends "opt" ? I | I[] | undefined : I | I[] : D extends MapCardinality.ManyToOne | "I[] -> O" ? IR extends "opt" ? I[] | I[][] | undefined : I[] | I[][] : never;
+/**
+ * The mapping function provided by the `mapFn()` utility. This _fn_
+ * is intended to be used in two ways:
  *
- * **Note:** because the output is an array you can easily support `1:1` and `1:M` mappings
- * and the allowance of the conversion to result in a `null` value also means that filter
- * out an input value entirely is possible. If you don't need _filtering_ then use the
- * `MapTo` type instead.
+ * 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);
+ *    ```
  */
-declare type MapToWithFiltering<I extends {}, O extends {}> = (i: I) => O[] | null;
+declare 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>>;
 
 /**
  * Given a dictionary of type `<T>`, this utility function will
@@ -672,6 +1025,12 @@ declare type RequiredKeys<T extends object, V extends any = any> = {
         [P in K]: T[K];
     } ? never : T[K] extends V ? K : never;
 }[keyof T];
+/**
+ * Extracts the intersecting/common keys to two objects
+ */
+declare type IntersectingKeys<T extends Record<string, any> | readonly string[], U extends Record<string, any> | readonly string[]> = {
+    [K in keyof T]: K extends Keys<U> ? K : never;
+}[keyof T];
 /**
  * Extracts the _optional_ keys in the object's type. You also may
  * optionally filter by the _value_ of the key.
@@ -881,7 +1240,6 @@ declare type ExpectExtends<VALUE, EXPECTED> = EXPECTED extends VALUE ? true : fa
  * Validates that a given type extends another and returns `any` or `never` as a type
  */
 declare type AssertExtends<VALUE, EXPECTED> = EXPECTED extends VALUE ? any : never;
-declare type IfExtends<VALUE, EXPECTED> = EXPECTED extends VALUE ? VALUE : never;
 /**
  * Give a type `TValue` and a comparison type `TExtends`
  */
@@ -1061,6 +1419,56 @@ declare type _DU<T extends string> = T extends Lowercase<T> ? T : `-${Lowercase<
  */
 declare 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>}` : "";
 
+declare type OneToOne = `1:1`;
+declare type OneToMany = `1:M`;
+declare type OneToZero = `1:0`;
+declare type ZeroToOne = `0:1`;
+declare type ZeroToMany = `0:M`;
+declare type ZeroToZero = `0:0`;
+declare type ManyToMany = "M:M";
+declare type ManyToOne = "M:1";
+declare type ManyToZero = "M:0";
+declare type CardinalityNode = "0" | "1" | "M";
+/**
+ * Cardinality which expects a singular input and requires
+ * 1 or many outputs.
+ *
+ * Note: choose `CardinalityFilter1` if you want to allow output
+ * to have no outputs.
+ */
+declare type Cardinality1 = OneToOne | OneToMany;
+/**
+ * Cardinality which expects a singular input and maps to 0,
+ * 1, or many outputs.
+ */
+declare type CardinalityFilter1 = OneToOne | OneToMany | OneToZero;
+/**
+ * Cardinality which expects a singular input which is allowed to be
+ * _undefined_ or the expected type.
+ */
+declare type Cardinality0 = ZeroToOne | ZeroToMany | OneToOne | OneToMany;
+/**
+ * Cardinality which expects a singular input -- which is allowed to be
+ * _undefined_ -- and maps to 0,
+ * 1, or many outputs.
+ */
+declare type CardinalityFilter0 = ZeroToOne | ZeroToMany | OneToOne | OneToMany | OneToZero | ZeroToZero;
+declare type CardinalityExplicit = `${number}:${number}`;
+/**
+ * Cardinality of any sort between two types
+ */
+declare type Cardinality = CardinalityFilter0 | CardinalityFilter1 | ManyToMany | ManyToOne | ManyToZero | CardinalityExplicit;
+declare type CardinalityTuple<T extends Cardinality> = UnionToTuple<T>;
+/**
+ * The first or _input_ part of the Cardinality relationship
+ */
+declare type CardinalityIn<T extends Cardinality> = T extends `${infer IN}:${string}` ? IN : never;
+/**
+ * The second or _output_ part of the Cardinality relationship
+ */
+declare type CardinalityOut<T extends Cardinality> = T extends `${string}:${infer OUT}` ? OUT : never;
+declare type CardinalityInput<T, C extends Cardinality> = CardinalityTuple<C>[0] extends 0 ? T | undefined : CardinalityTuple<C>[0] extends 1 ? T : T[];
+
 /**
  * Converts a string literal into a _dasherized_ format while ignoring _exterior_ whitespace.
  *
@@ -1197,10 +1605,10 @@ declare type FinalReturn<T extends any> = T extends (...args: any[]) => any ? Fi
  */
 declare type LogicFunction<T extends any[]> = (...args: T) => boolean;
 
-declare type DictFromKv<T extends readonly Readonly<{
+declare type DictFromKv<T extends readonly {
     key: string;
     value: unknown;
-}>[]> = {
+}[]> = {
     [R in T[number] as R["key"]]: R["value"];
 };
 
@@ -1277,15 +1685,6 @@ declare type DictArray<T> = Array<{
     [K in keyof T]: DictArrayKv<K, T>;
 }[keyof T]>;
 
-/**
- * LastInUnion<1 | 2> = 2.
- */
-declare type LastInUnion<U> = UnionToIntersection<U extends unknown ? (x: U) => 0 : never> extends (x: infer L) => 0 ? L : never;
-/**
- * UnionToTuple<1 | 2> = [1, 2].
- */
-declare type UnionToTuple<U, Last = LastInUnion<U>> = [U] extends [never] ? [] : [...UnionToTuple<Exclude<U, Last>>, Last];
-
 /**
  * Returns the _first_ key in an object.
  *
@@ -1314,18 +1713,6 @@ declare type FirstKeyValue<T extends object> = FirstKey<T> extends keyof T ? T[F
  */
 declare type FirstOfEach<T extends readonly any[][]> = T[number][0] extends T[number][number] ? T[number][0] : never;
 
-/**
- * Converts a Tuple type into a _union_ of the tuple elements
- * ```ts
- * const arr = [1, 3, 5] as const;
- * // 1 | 3 | 5
- * type U = TupleToUnion<typeof arr>;
- * ```
- */
-declare type TupleToUnion<T> = Mutable<T> extends any[] ? Mutable<T>[number] : never;
-
-declare type Widen<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
-
 /**
  * Typescript utility which receives `T` as shape which resembles `DictArray<D>`
  * and if the type `D` can be inferred it is returned.
@@ -1347,51 +1734,6 @@ declare type FromDictArray<T extends [string, Record<string, unknown>][]> = Expa
  */
 declare type SecondOfEach<T extends any[][]> = T[number][1] extends T[number][number] ? T[number][1] : never;
 
-/**
- * **IsBooleanLiteral**
- *
- * Type utility which returns true/false if the boolean value is a _boolean literal_ versus
- * just the wider _boolean_ type.
- */
-declare type IsBooleanLiteral<T extends boolean> = boolean extends T ? false : true;
-
-/**
- * **IsStringLiteral**
- *
- * Type utility which returns true/false if the string a _string literal_ versus
- * just the _string_ type.
- */
-declare type IsStringLiteral<T extends string> = string extends T ? false : true;
-
-/**
- * **IsNumericLiteral**
- *
- * Type utility which returns true/false if the numeric value a _numeric literal_ versus
- * just the _number_ type.
- */
-declare type IsNumericLiteral<T extends number> = number extends T ? false : true;
-
-/**
- * **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).
- */
-declare type IsLiteral<T extends string | number | boolean> = [T] extends [string] ? IsStringLiteral<T> : [T] extends [boolean] ? IsBooleanLiteral<T> : [T] extends [number] ? IsNumericLiteral<T> : never;
-
-/**
- * **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`.
- */
-declare type Includes<TSource extends string | 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;
-
 declare function createFnWithProps<F extends Function, P extends {}>(fn: F, props: P): F & P;
 /**
  * Adds a dictionary of key/value pairs to a function.
@@ -1624,33 +1966,6 @@ declare function entries<N extends Narrowable, T extends Record<string, N>, I ex
  */
 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; };
 
-/**
- * **mapTo**
- *
- * A utility function which maps one dictionary structure `I` to another `O`; which allows
- * the transform to:
- *
- * - _split_ inputs into multiple outputs
- * - _map_ 1:1 between input and output
- * - _filter_ inputs which don't meet certain criteria (by returning `null`)
- *
- * This higher order function first asks for the mapping criteria:
- * ```ts
- * const mapper = mapTo<I,O>(i => i.name
- *  ? [
- *      { name: i.name, a: "static text", b: i.products.length }
- *    ]
- *  : null
- * );
- * ```
- *
- * and now you'll have a _mapper_ variable will be assigned as a mapping fn:
- * ```ts
- * function (source: I | I[]): O[]
- * ```
- */
-declare const mapTo: <I extends {}, O extends {}>(cb: MapToWithFiltering<I, O>) => (source: I | I[]) => O[];
-
 /**
  * converts an array of strings `["a", "b", "c"]` into a more type friendly
  * dictionary of the type `{ a: true, b: true, c: true }`
@@ -1927,4 +2242,4 @@ interface IFluentConfigurator<C> {
  */
 declare function FluentConfigurator<I>(initial?: I): IFluentConfigurator<{}>;
 
-export { AllCaps, Alpha, AlphaNumeric, Api, ApiFunction, ApiValue, AppendToDictionary, AppendToObject, ArrConcat, Array$1 as Array, ArrayConverter, AsArray, AssertExtends, Bracket, Break, CamelCase, CapitalizeWords, ClosingBracket, Condition, ConditionFilter, Configurator, Constructor, DashToSnake, DashUppercase, Dasherize, DefinePropertiesApi, DictArrApi, DictArray, DictArrayFilterCallback, DictArrayKv, DictChangeValue, DictFromKv, DictKvTuple, DictPartialApplication, DictPrependWithFn, DictReturnValues, DynamicRule, DynamicRuleSet, Email, EnumValues, ExpandRecursively, ExpectExtends, ExplicitFunction, ExtendsClause, ExtendsNarrowlyClause, FilterContains, FilterDefn, FilterEnds, FilterEquals, FilterFn, FilterGreaterThan, FilterIs, FilterLessThan, FilterNotEqual, FilterStarts, FinalReturn, First, FirstKey, FirstKeyValue, FirstOfEach, FluentConfigurator, FluentFunction, FromDictArray, FunctionType, GeneralDictionary, Get, HasUppercase, IConfigurator, IFluentConfigurator, If, IfExtends, IfExtendsThen, Include, Includes, IsArray, IsBoolean, IsBooleanLiteral, IsCapitalized, IsFalse, IsFunction, IsLiteral, IsNumericLiteral, IsObject, IsString, IsStringLiteral, IsTrue, KebabCase, KeyValue, KeyedRecord, Keys, KeysWithValue, KvFrom, KvTuple, LastInUnion, LeftWhitespace, Length, LogicFunction, LogicalCombinator, LowerAllCaps, LowerAlpha, MapTo, MapToWithFiltering, MaybeFalse, MaybeTrue, Model, Mutable, MutableProps, MutationFunction, MutationIdentity, Narrowable, NonAlpha, NonNumericKeys, NonStringKeys, Not, NotFilter, Numeric, NumericFilter, NumericKeys, NumericString, ObjectType, Opaque, OpeningBracket, OptionalKeys, OptionalProps, Parenthesis, PascalCase, Pluralize, PrivateKey, PrivateKeys, PublicKeys, Punctuation, PureFluentApi, Replace, RequireProps, RequiredKeys, RequiredProps, Retain, RightWhitespace, RuleDefinition, RuntimeProp, RuntimeType, SameKeys, SecondOfEach, SimplifyObject, SnakeCase, SpecialCharacters, StringDelimiter, StringFilter, StringKeys, StringLength, ToFluent, Transformer, Trim, TrimLeft, TrimRight, TupleToUnion, Type, TypeApi, TypeCondition, TypeDefinition, TypeGuard, TypeOptions, UndefinedArrayIsUnknown, UndefinedTreatment, UndefinedValue, UnionToIntersection, UnionToTuple, UniqueDictionary, UniqueForProp, Uniqueness, UnwrapNot, UpperAlpha, ValueTuple, ValueTypeFunc, ValueTypes, Where, WhereNot, Whitespace, Widen, WithNumericKeys, WithStringKeys, WithValue, ZipCode, and, api, arrayToKeyLookup, arrayToObject, asArray, condition, createFnWithProps, createMutationFunction, defineProperties, defineType, dictArr, dictToKv, dictionaryTransform, entries, filter, filterDictArray, fnWithProps, groupBy, idLiteral, idTypeGuard, identity, ifTypeOf, isArray, isBoolean, isFalse, isFunction, isNotFilter, isNull, isNumber, isNumericFilter, isObject, isString, isSymbol, isTrue, isType, isUndefined, keys, kindLiteral, kv, kvToDict, literal, mapTo, mapValues, nameLiteral, not, or, randomString, readonlyFnWithProps, ruleSet, strArrayToDict, type, typeApi, uuid, valueTypes, withValue };
+export { AllCaps, Alpha, AlphaNumeric, Api, ApiFunction, ApiValue, AppendToDictionary, AppendToObject, ArrConcat, Array$1 as Array, ArrayConverter, AsArray, AsFinalizedConfig, AssertExtends, Bracket, Break, CamelCase, CapitalizeWords, Cardinality, Cardinality0, Cardinality1, CardinalityExplicit, CardinalityFilter0, CardinalityFilter1, CardinalityIn, CardinalityInput, CardinalityNode, CardinalityOut, CardinalityTuple, ClosingBracket, Condition, ConditionFilter, Configurator, ConfiguredMap, Constructor, 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, DynamicRule, DynamicRuleSet, Email, EnumValues, ExpandRecursively, ExpectExtends, ExplicitFunction, Extends, ExtendsClause, ExtendsNarrowlyClause, FilterContains, FilterDefn, FilterEnds, FilterEquals, FilterFn, FilterGreaterThan, FilterIs, FilterLessThan, FilterNotEqual, FilterStarts, FinalReturn, FinalizedMapConfig, First, FirstKey, FirstKeyValue, FirstOfEach, FluentConfigurator, FluentFunction, FromDictArray, FunctionType, GeneralDictionary, Get, HasUppercase, IConfigurator, IFluentConfigurator, If, IfBooleanLiteral, IfExtends, IfExtendsThen, IfLiteral, IfNumericLiteral, IfObject, IfOptionalLiteral, IfScalar, IfStringLiteral, Include, Includes, IntersectingKeys, IsArray, IsBoolean, IsBooleanLiteral, IsCapitalized, IsFalse, IsFunction, IsLiteral, IsNumericLiteral, IsObject, IsOptionalLiteral, IsScalar, IsString, IsStringLiteral, IsTrue, KebabCase, KeyValue, KeyedRecord, Keys, KeysWithValue, KvFrom, KvTuple, LastInUnion, LeftWhitespace, Length, LogicFunction, LogicalCombinator, LowerAllCaps, LowerAlpha, ManyToMany, ManyToOne, ManyToZero, MapCard, MapCardinality, MapCardinalityIllustrated, MapConfig, MapFn, MapFnInput, MapFnOutput, MapIR, MapInput, MapOR, MapOutput, MapTo, MapperApi, MaybeFalse, MaybeTrue, Model, Mutable, MutableProps, MutationFunction, MutationIdentity, Narrowable, NonAlpha, NonNumericKeys, NonStringKeys, Not, NotFilter, Numeric, NumericFilter, NumericKeys, NumericString, ObjectType, OneToMany, OneToOne, OneToZero, Opaque, OpeningBracket, OptRequired, OptionalKeys, OptionalProps, Parenthesis, PascalCase, Pluralize, PrivateKey, PrivateKeys, PublicKeys, Punctuation, PureFluentApi, Replace, RequireProps, RequiredKeys, RequiredProps, Retain, RightWhitespace, RuleDefinition, RuntimeProp, RuntimeType, SameKeys, SecondOfEach, SimplifyObject, SnakeCase, SpecialCharacters, StringDelimiter, StringFilter, StringKeys, StringLength, ToFluent, Transformer, Trim, TrimLeft, TrimRight, TupleToUnion, Type, TypeApi, TypeCondition, TypeDefault, TypeDefinition, TypeGuard, TypeOptions, UndefinedArrayIsUnknown, UndefinedTreatment, UndefinedValue, UnionToIntersection, UnionToTuple, UniqueDictionary, UniqueForProp, Uniqueness, UnwrapNot, UpperAlpha, ValueTuple, ValueTypeFunc, ValueTypes, Where, WhereNot, Whitespace, Widen, WithNumericKeys, WithStringKeys, WithValue, ZeroToMany, ZeroToOne, ZeroToZero, ZipCode, and, api, arrayToKeyLookup, arrayToObject, asArray, condition, createFnWithProps, createMutationFunction, defineProperties, defineType, dictArr, dictToKv, dictionaryTransform, entries, filter, filterDictArray, fnWithProps, groupBy, idLiteral, idTypeGuard, identity, ifTypeOf, isArray, isBoolean, isFalse, isFunction, isNotFilter, isNull, isNumber, isNumericFilter, isObject, isString, isSymbol, isTrue, isType, isUndefined, keys, kindLiteral, kv, kvToDict, literal, mapTo, mapToDict, mapToFn, mapValues, nameLiteral, not, or, randomString, readonlyFnWithProps, ruleSet, strArrayToDict, type, typeApi, uuid, valueTypes, withValue };