inferred-types 0.26.0 → 0.27.0

package/.vscode/settings.json

@@ -5,6 +5,7 @@
     "Aint",
     "Dasherize",
     "dasherized",
+    "fooy",
     "ruleset",
     "tokei",
     "Uncapitalize"

package/dist/index.d.ts

@@ -579,26 +579,52 @@ 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";
+
+/**
+ * Expresses relationship between inputs/outputs:
+ */
+declare enum MapDirection {
+    /** 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 MapDirectionVal = EnumValues<MapDirection>;
+declare type MapInput<I, IR, D extends MapDirectionVal> = D extends MapDirection.OneToMany | "I -> O[]" ? IR extends "opt" ? I | undefined : I : D extends MapDirection.OneToOne | "I -> O" ? IR extends "opt" ? I | undefined : I : D extends MapDirection.ManyToOne | "I[] -> O" ? IR extends "opt" ? I[] | undefined : I[] : never;
+declare type MapOutput<O, OR, D extends MapDirectionVal> = D extends MapDirection.OneToMany | "I -> O[]" ? OR extends "opt" ? O[] : [O, ...O[]] : D extends MapDirection.OneToOne | "I -> O" ? OR extends "opt" ? O | null : O : D extends MapDirection.ManyToOne | "I[] -> O" ? OR extends "opt" ? O | null : O : never;
+/**
+ * **MapTo<I, O>**
  *
- * Maps from one type `I` to another `O[]`
+ * A mapping function between an input type `I` and output type `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.
+ * **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 extends {}, O extends {}> = (i: I) => O[];
+declare type MapTo<I, O, IR extends OptRequired = "req", D extends MapDirectionVal = MapDirection.OneToMany, OR extends OptRequired = "opt"> = IR extends "opt" ? (source?: MapInput<I, IR, D>) => MapOutput<O, OR, D> : (source: MapInput<I, IR, D>) => MapOutput<O, OR, D>;
+declare type MapFnOutput<I, O, S, OR extends OptRequired, D extends MapDirectionVal> = D extends "I -> O[]" | MapDirection.OneToMany ? S extends I[] ? OR extends "opt" ? O[] : [O, ...O[]] : OR extends "opt" ? O[] | null : O[] : D extends MapDirection.OneToOne | "I -> O" ? S extends I[] ? OR extends "opt" ? O[] : [O, ...O[]] : OR extends "opt" ? O | null : O : D extends MapDirection.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 MapDirectionVal> = D extends "I -> O[]" | MapDirection.OneToMany ? IR extends "opt" ? I | I[] | undefined : I | I[] : D extends MapDirection.OneToOne | "I -> O" ? IR extends "opt" ? I | I[] | undefined : I | I[] : D extends MapDirection.ManyToOne | "I[] -> O" ? IR extends "opt" ? I[] | I[][] | undefined : I[] | I[][] : never;
 /**
- * **MapToWithFiltering**
+ * The mapping function provided by the `mapFn()` utility. This _fn_
+ * is intended to be used in two ways:
  *
- * Maps from one type `I` to another `(O | null)[]`
- *
- * **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 approp)
+ *    const out2 = m(inputs);
+ *    ```
  */
-declare type MapToWithFiltering<I extends {}, O extends {}> = (i: I) => O[] | null;
+declare type MapFn<I, O, IR extends OptRequired = "req", D extends MapDirectionVal = MapDirection.OneToMany, OR extends OptRequired = "opt"> = IR extends "opt" ? <S extends MapFnInput<I, IR, D>>(source?: S) => MapFnOutput<I, O, S, OR, D> : <S extends MapFnInput<I, IR, D>>(source: S) => MapFnOutput<I, O, S, OR, D>;
 
 /**
  * Given a dictionary of type `<T>`, this utility function will
@@ -1061,6 +1087,77 @@ 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>}` : "";
 
+/**
+ * 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;
+
+/**
+ * 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;
+
+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.
  *
@@ -1277,15 +1374,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 +1402,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.
@@ -1624,32 +1700,74 @@ 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; };
 
+interface MapConfig<IR extends OptRequired = "req", D extends MapDirectionVal = "I -> O[]", OR extends OptRequired = "opt"> {
+    input?: IR;
+    output?: OR;
+    direction?: D;
+}
 /**
- * **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
- * );
- * ```
+ * Provides a mapper function using the default configuration
+ */
+declare type MapperApiDefault = <I, O>(map: MapTo<I, O>) => MapFn<I, O>;
+/**
+ * Provides opportunity to configure _input_ and _output_ relationships
+ * prior to providing a mapping function.
+ */
+declare type MapperApiConfigured = <IR extends OptRequired = "req", D extends MapDirectionVal = "I -> O[]", OR extends OptRequired = "opt">(config: MapConfig<IR, D, OR>) => <I, O>(map: MapTo<I, O, IR, D, OR>) => MapFn<I, O, IR, D, OR>;
+/**
+ * **mapTo** _utility_
  *
- * and now you'll have a _mapper_ variable will be assigned as a mapping fn:
+ * This utility creates a strongly typed data mapper which maps from one
+ * known source `I` to another `O`:
  * ```ts
- * function (source: I | I[]): O[]
+ * const mapper = mapTo<I, O>(i => [{
+ *    foo: i.bar
+ * }]);
  * ```
  */
-declare const mapTo: <I extends {}, O extends {}>(cb: MapToWithFiltering<I, O>) => (source: I | I[]) => O[];
+declare const mapToFn: <I, O>(map: (source: I) => O[]) => <S extends I | I[]>(source: S) => S extends I[] ? O[] : O[] | null;
+/**
+ * Provides a `config` method which allows the relationships between _inputs_
+ * and _outputs_ to be configured.
+ */
+declare const mapToDict: {
+    /** configure the relationship between the _inputs_ and _outputs_ */
+    config: <IR extends OptRequired = "req", D extends "I -> O[]" | "I -> O" | "I[] -> O" = "I -> O[]", OR extends OptRequired = "opt">(c?: MapConfig<IR, D, OR>) => {
+        /**
+         * create your mapping with your recently setup configuration:
+         * ```ts
+         * const mapper = mapTo
+         *  .config({ ... })
+         *  .map<I, O>(i => [{
+         *    foo: i.bar
+         * }]);
+         * ```
+         */
+        map<I, O>(map: MapTo<I, O, IR, D, OR>): MapFn<I, O, IR, D, OR>;
+    };
+};
+/**
+ * **mapTo** _utility_
+ *
+ * This utility creates a strongly typed data mapper which maps from one
+ * known source `I` to another `O`.
+ */
+declare const mapTo: (<I, O>(map: (source: I) => O[]) => <S extends I | I[]>(source: S) => S extends I[] ? O[] : O[] | null) & {
+    /** configure the relationship between the _inputs_ and _outputs_ */
+    config: <IR extends OptRequired = "req", D extends "I -> O[]" | "I -> O" | "I[] -> O" = "I -> O[]", OR extends OptRequired = "opt">(c?: MapConfig<IR, D, OR>) => {
+        /**
+         * create your mapping with your recently setup configuration:
+         * ```ts
+         * const mapper = mapTo
+         *  .config({ ... })
+         *  .map<I, O>(i => [{
+         *    foo: i.bar
+         * }]);
+         * ```
+         */
+        map<I, O>(map: MapTo<I, O, IR, D, OR>): MapFn<I, O, IR, D, OR>;
+    };
+};
 
 /**
  * converts an array of strings `["a", "b", "c"]` into a more type friendly
@@ -1927,4 +2045,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, AssertExtends, Bracket, Break, CamelCase, CapitalizeWords, Cardinality, Cardinality0, Cardinality1, CardinalityExplicit, CardinalityFilter0, CardinalityFilter1, CardinalityIn, CardinalityInput, CardinalityNode, CardinalityOut, CardinalityTuple, 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, ManyToMany, ManyToOne, ManyToZero, MapConfig, MapDirection, MapDirectionVal, MapFn, MapFnInput, MapFnOutput, MapInput, MapOutput, MapTo, MapperApiConfigured, MapperApiDefault, 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, 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 };

package/dist/index.js

@@ -23,6 +23,7 @@ __export(src_exports, {
   Configurator: () => Configurator,
   ExplicitFunction: () => ExplicitFunction,
   FluentConfigurator: () => FluentConfigurator,
+  MapDirection: () => MapDirection,
   Model: () => Model,
   MutationIdentity: () => MutationIdentity,
   and: () => and,
@@ -67,6 +68,8 @@ __export(src_exports, {
   kvToDict: () => kvToDict,
   literal: () => literal,
   mapTo: () => mapTo,
+  mapToDict: () => mapToDict,
+  mapToFn: () => mapToFn,
   mapValues: () => mapValues,
   nameLiteral: () => nameLiteral,
   not: () => not,
@@ -126,6 +129,14 @@ var valueTypes = {
   literalArray: (arr) => [arr, true]
 };
 
+// src/types/dictionary/MapTo.ts
+var MapDirection = /* @__PURE__ */ ((MapDirection2) => {
+  MapDirection2["OneToMany"] = "I -> O[]";
+  MapDirection2["OneToOne"] = "I -> O";
+  MapDirection2["ManyToOne"] = "I[] -> O";
+  return MapDirection2;
+})(MapDirection || {});
+
 // src/utility/keys.ts
 function keys(obj, ...without) {
   const v = without.length > 0 ? Object.keys(obj).filter((k) => !without.includes(k)) : Object.keys(obj);
@@ -579,14 +590,34 @@ function mapValues(obj, valueMapper) {
 }
 
 // src/utility/dictionary/mapTo.ts
-var mapTo = (cb) => (source) => {
-  if (Array.isArray(source)) {
-    return source.flatMap((i) => cb(i)).filter((i) => i !== null);
-  } else {
-    const result = cb(source);
-    return result ? result : [];
-  }
+var mapper = (config = {}) => (map) => {
+  config = {
+    input: "req",
+    output: "opt",
+    direction: "I -> O[]",
+    ...config
+  };
+  const fn = (source) => {
+    const isArray2 = config.direction === "I -> O[]" && Array.isArray(source) ? true : config.direction === "I[] -> O" && Array.isArray(source) && Array.isArray(source[0]) ? true : false;
+    if (isArray2) {
+      return source.flatMap(map);
+    } else {
+      return map(source);
+    }
+  };
+  return fn;
+};
+var mapToFn = (map) => {
+  return mapper()(map);
+};
+var mapToDict = {
+  config: (c = { input: "req", output: "opt", direction: "I -> O[]" }) => ({
+    map(map) {
+      return mapper(c)(map);
+    }
+  })
 };
+var mapTo = createFnWithProps(mapToFn, mapToDict);
 
 // src/utility/dictionary/strArrayToDict.ts
 function strArrayToDict(...strings) {
@@ -754,6 +785,7 @@ function Model(name) {
   Configurator,
   ExplicitFunction,
   FluentConfigurator,
+  MapDirection,
   Model,
   MutationIdentity,
   and,
@@ -798,6 +830,8 @@ function Model(name) {
   kvToDict,
   literal,
   mapTo,
+  mapToDict,
+  mapToFn,
   mapValues,
   nameLiteral,
   not,

package/dist/index.mjs

@@ -41,6 +41,14 @@ var valueTypes = {
   literalArray: (arr) => [arr, true]
 };
 
+// src/types/dictionary/MapTo.ts
+var MapDirection = /* @__PURE__ */ ((MapDirection2) => {
+  MapDirection2["OneToMany"] = "I -> O[]";
+  MapDirection2["OneToOne"] = "I -> O";
+  MapDirection2["ManyToOne"] = "I[] -> O";
+  return MapDirection2;
+})(MapDirection || {});
+
 // src/utility/keys.ts
 function keys(obj, ...without) {
   const v = without.length > 0 ? Object.keys(obj).filter((k) => !without.includes(k)) : Object.keys(obj);
@@ -494,14 +502,34 @@ function mapValues(obj, valueMapper) {
 }
 
 // src/utility/dictionary/mapTo.ts
-var mapTo = (cb) => (source) => {
-  if (Array.isArray(source)) {
-    return source.flatMap((i) => cb(i)).filter((i) => i !== null);
-  } else {
-    const result = cb(source);
-    return result ? result : [];
-  }
+var mapper = (config = {}) => (map) => {
+  config = {
+    input: "req",
+    output: "opt",
+    direction: "I -> O[]",
+    ...config
+  };
+  const fn = (source) => {
+    const isArray2 = config.direction === "I -> O[]" && Array.isArray(source) ? true : config.direction === "I[] -> O" && Array.isArray(source) && Array.isArray(source[0]) ? true : false;
+    if (isArray2) {
+      return source.flatMap(map);
+    } else {
+      return map(source);
+    }
+  };
+  return fn;
+};
+var mapToFn = (map) => {
+  return mapper()(map);
+};
+var mapToDict = {
+  config: (c = { input: "req", output: "opt", direction: "I -> O[]" }) => ({
+    map(map) {
+      return mapper(c)(map);
+    }
+  })
 };
+var mapTo = createFnWithProps(mapToFn, mapToDict);
 
 // src/utility/dictionary/strArrayToDict.ts
 function strArrayToDict(...strings) {
@@ -668,6 +696,7 @@ export {
   Configurator,
   ExplicitFunction,
   FluentConfigurator,
+  MapDirection,
   Model,
   MutationIdentity,
   and,
@@ -712,6 +741,8 @@ export {
   kvToDict,
   literal,
   mapTo,
+  mapToDict,
+  mapToFn,
   mapValues,
   nameLiteral,
   not,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inferred-types",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Functions which provide useful type inference on TS projects",
   "license": "MIT",
   "author": "Ken Snyder<ken@ken.net>",

package/src/types/alphabetic/Cardinality.ts

@@ -0,0 +1,80 @@
+import { UnionToTuple } from "../type-conversion";
+
+export type OneToOne = `1:1`;
+export type OneToMany = `1:M`;
+export type OneToZero = `1:0`;
+export type ZeroToOne = `0:1`;
+export type ZeroToMany = `0:M`;
+export type ZeroToZero = `0:0`;
+export type ManyToMany = "M:M";
+export type ManyToOne = "M:1";
+export type ManyToZero = "M:0";
+
+export 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.
+ */
+export type Cardinality1 = OneToOne | OneToMany;
+
+/**
+ * Cardinality which expects a singular input and maps to 0,
+ * 1, or many outputs.
+ */
+export type CardinalityFilter1 = OneToOne | OneToMany | OneToZero;
+
+/**
+ * Cardinality which expects a singular input which is allowed to be
+ * _undefined_ or the expected type.
+ */
+export 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.
+ */
+export type CardinalityFilter0 =
+  | ZeroToOne
+  | ZeroToMany
+  | OneToOne
+  | OneToMany
+  | OneToZero
+  | ZeroToZero;
+
+export type CardinalityExplicit = `${number}:${number}`;
+
+/**
+ * Cardinality of any sort between two types
+ */
+export type Cardinality =
+  | CardinalityFilter0
+  | CardinalityFilter1
+  | ManyToMany
+  | ManyToOne
+  | ManyToZero
+  | CardinalityExplicit;
+
+export type CardinalityTuple<T extends Cardinality> = UnionToTuple<T>;
+
+/**
+ * The first or _input_ part of the Cardinality relationship
+ */
+export type CardinalityIn<T extends Cardinality> = T extends `${infer IN}:${string}` ? IN : never;
+
+/**
+ * The second or _output_ part of the Cardinality relationship
+ */
+export type CardinalityOut<T extends Cardinality> = T extends `${string}:${infer OUT}`
+  ? OUT
+  : never;
+
+export type CardinalityInput<T, C extends Cardinality> = CardinalityTuple<C>[0] extends 0
+  ? T | undefined
+  : CardinalityTuple<C>[0] extends 1
+  ? T
+  : T[];

package/src/types/alphabetic/index.ts

@@ -9,6 +9,7 @@ export * from "./CamelCase";
 export * from "./CapitalizeWords";
 export * from "./DashToSnake";
 export * from "./DashUppercase";
+export * from "./Cardinality";
 export * from "./Dasherize";
 export * from "./HasUppercase";
 export * from "./IsCapitalized";

package/src/types/dictionary/MapTo.ts

@@ -1,23 +1,136 @@
+import { OptRequired } from "src/types/literal-unions";
+import { EnumValues } from "../EnumValues";
+
 /**
- * **MapTo**
- *
- * Maps from one type `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.
+ * Expresses relationship between inputs/outputs:
  */
-export type MapTo<I extends {}, O extends {}> = (i: I) => O[];
+export enum MapDirection {
+  /** 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",
+}
+
+export type MapDirectionVal = EnumValues<MapDirection>;
+
+export type MapInput<I, IR, D extends MapDirectionVal> = D extends
+  | MapDirection.OneToMany
+  | "I -> O[]"
+  ? IR extends "opt"
+    ? I | undefined
+    : I
+  : D extends MapDirection.OneToOne | "I -> O"
+  ? IR extends "opt"
+    ? I | undefined
+    : I
+  : D extends MapDirection.ManyToOne | "I[] -> O"
+  ? IR extends "opt"
+    ? I[] | undefined
+    : I[]
+  : never;
+
+export type MapOutput<O, OR, D extends MapDirectionVal> = D extends
+  | MapDirection.OneToMany
+  | "I -> O[]"
+  ? OR extends "opt"
+    ? O[]
+    : [O, ...O[]]
+  : D extends MapDirection.OneToOne | "I -> O"
+  ? OR extends "opt"
+    ? O | null
+    : O
+  : D extends MapDirection.ManyToOne | "I[] -> O"
+  ? OR extends "opt"
+    ? O | null
+    : O
+  : never;
 
 /**
- * **MapToWithFiltering**
+ * **MapTo<I, O>**
  *
- * Maps from one type `I` to another `(O | null)[]`
+ * A mapping function between an input type `I` and output type `O`.
  *
- * **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.
+ * **Note:** this type is designed to guide the userland mapping; refer
+ * to `MapFn` if you want the type output by the `mapFn()` utility.
  */
+export type MapTo<
+  I,
+  O,
+  IR extends OptRequired = "req",
+  D extends MapDirectionVal = MapDirection.OneToMany,
+  OR extends OptRequired = "opt"
+> = IR extends "opt"
+  ? (source?: MapInput<I, IR, D>) => MapOutput<O, OR, D>
+  : (source: MapInput<I, IR, D>) => MapOutput<O, OR, D>;
 
-export type MapToWithFiltering<I extends {}, O extends {}> = (i: I) => O[] | null;
+export type MapFnOutput<I, O, S, OR extends OptRequired, D extends MapDirectionVal> = D extends
+  | "I -> O[]"
+  | MapDirection.OneToMany
+  ? S extends I[]
+    ? OR extends "opt"
+      ? O[]
+      : [O, ...O[]]
+    : OR extends "opt"
+    ? O[] | null
+    : O[]
+  : D extends MapDirection.OneToOne | "I -> O"
+  ? S extends I[]
+    ? OR extends "opt"
+      ? O[]
+      : [O, ...O[]]
+    : OR extends "opt"
+    ? O | null
+    : O
+  : D extends MapDirection.ManyToOne | "I[] -> O"
+  ? S extends I[][]
+    ? OR extends "opt"
+      ? O[]
+      : [O, ...O[]]
+    : OR extends "opt"
+    ? O | null
+    : O
+  : never;
+
+export type MapFnInput<I, IR extends OptRequired, D extends MapDirectionVal> = D extends
+  | "I -> O[]"
+  | MapDirection.OneToMany
+  ? IR extends "opt"
+    ? I | I[] | undefined
+    : I | I[]
+  : D extends MapDirection.OneToOne | "I -> O"
+  ? IR extends "opt"
+    ? I | I[] | undefined
+    : I | I[]
+  : D extends MapDirection.ManyToOne | "I[] -> O"
+  ? IR extends "opt"
+    ? I[] | I[][] | undefined
+    : I[] | I[][]
+  : never;
+
+/**
+ * The mapping function provided by the `mapFn()` utility. This _fn_
+ * is intended to be used in two ways:
+ *
+ * 1. Iterative:
+ *    ```ts
+ *    const m = mapTo<I,O>(i => [ ... ]);
+ *    // maps inputs to outputs
+ *    const out = inputs.map(m);
+ *    ```
+ * 2. Block:
+ *    ```ts
+ *    // maps inputs to outputs (filtering or splitting where approp)
+ *    const out2 = m(inputs);
+ *    ```
+ */
+export type MapFn<
+  I,
+  O,
+  IR extends OptRequired = "req",
+  D extends MapDirectionVal = MapDirection.OneToMany,
+  OR extends OptRequired = "opt"
+> = IR extends "opt"
+  ? <S extends MapFnInput<I, IR, D>>(source?: S) => MapFnOutput<I, O, S, OR, D>
+  : <S extends MapFnInput<I, IR, D>>(source: S) => MapFnOutput<I, O, S, OR, D>;

package/src/types/index.ts

@@ -37,6 +37,7 @@ export * from "./fluent/index";
 export * from "./functions/index";
 export * from "./kv/index";
 export * from "./lists/index";
+export * from "./literal-unions/index";
 export * from "./string-literals/index";
 export * from "./tuples/index";
 export * from "./type-conversion/index";

package/src/types/literal-unions/OptRequired.ts

@@ -0,0 +1,4 @@
+/**
+ * Expresses whether an option is "opt" (optional) or "req" (required)
+ */
+export type OptRequired = "opt" | "req";

package/src/types/literal-unions/index.ts

@@ -0,0 +1 @@
+export * from "./OptRequired";

package/src/types/string-literals/Replace.ts

@@ -5,9 +5,13 @@
  * // "Foo"
  * type Foo = Replace<typeof fooy, "y", "">;
  * ```
- * 
+ *
  * Note: _the first match is replaced and all subsequent matches are ignored_
  */
-export 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;
+export 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;

package/src/utility/dictionary/mapTo.ts

@@ -1,37 +1,124 @@
-import { MapToWithFiltering } from "src/types/dictionary";
+import { MapDirectionVal, MapFn, MapFnInput, MapTo } from "src/types/dictionary";
+import { OptRequired } from "src/types/literal-unions";
+import { createFnWithProps } from "../createFnWithProps";
+
+export interface MapConfig<
+  IR extends OptRequired = "req",
+  D extends MapDirectionVal = "I -> O[]",
+  OR extends OptRequired = "opt"
+> {
+  input?: IR;
+  output?: OR;
+  direction?: D;
+}
 
 /**
- * **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`)
+ * Provides a mapper function using the default configuration
+ */
+export type MapperApiDefault = <I, O>(map: MapTo<I, O>) => MapFn<I, O>;
+
+/**
+ * Provides opportunity to configure _input_ and _output_ relationships
+ * prior to providing a mapping function.
+ */
+export type MapperApiConfigured = <
+  IR extends OptRequired = "req",
+  D extends MapDirectionVal = "I -> O[]",
+  OR extends OptRequired = "opt"
+>(
+  config: MapConfig<IR, D, OR>
+) => <I, O>(map: MapTo<I, O, IR, D, OR>) => MapFn<I, O, IR, D, OR>;
+
+/**
+ * The single implementation for all mapping
+ */
+const mapper =
+  <
+    IR extends OptRequired = "req",
+    D extends MapDirectionVal = "I -> O[]",
+    OR extends OptRequired = "opt"
+  >(
+    config: MapConfig<IR, D, OR> = {}
+  ) =>
+  <I, O>(map: MapTo<I, O, IR, D, OR>) => {
+    // TODO
+    config = {
+      input: "req",
+      output: "opt",
+      direction: "I -> O[]",
+      ...config,
+    } as Required<MapConfig<IR, D, OR>>;
+
+    const fn = <S extends MapFnInput<I, IR, D>>(source?: S) => {
+      const isArray =
+        config.direction === "I -> O[]" && Array.isArray(source)
+          ? true
+          : config.direction === "I[] -> O" && Array.isArray(source) && Array.isArray(source[0])
+          ? true
+          : false;
+
+      if (isArray) {
+        return (source as any).flatMap(map);
+      } else {
+        return map(source as any);
+      }
+    };
+
+    return fn as unknown as MapFn<I, O, IR, D, OR>;
+  };
+
+/**
+ * **mapTo** _utility_
  *
- * This higher order function first asks for the mapping criteria:
+ * This utility creates a strongly typed data mapper which maps from one
+ * known source `I` to another `O`:
  * ```ts
- * const mapper = mapTo<I,O>(i => i.name
- *  ? [
- *      { name: i.name, a: "static text", b: i.products.length }
- *    ]
- *  : null
- * );
+ * const mapper = mapTo<I, O>(i => [{
+ *    foo: i.bar
+ * }]);
  * ```
+ */
+export const mapToFn = <I, O>(map: MapTo<I, O>) => {
+  return mapper()<I, O>(map);
+};
+
+/**
+ * Provides a `config` method which allows the relationships between _inputs_
+ * and _outputs_ to be configured.
+ */
+export const mapToDict = {
+  /** configure the relationship between the _inputs_ and _outputs_ */
+  config: <
+    IR extends OptRequired = "req",
+    D extends MapDirectionVal = "I -> O[]",
+    OR extends OptRequired = "opt"
+  >(
+    c: MapConfig<IR, D, OR> = { input: "req", output: "opt", direction: "I -> O[]" } as MapConfig<
+      IR,
+      D,
+      OR
+    >
+  ) => ({
+    /**
+     * create your mapping with your recently setup configuration:
+     * ```ts
+     * const mapper = mapTo
+     *  .config({ ... })
+     *  .map<I, O>(i => [{
+     *    foo: i.bar
+     * }]);
+     * ```
+     */
+    map<I, O>(map: MapTo<I, O, IR, D, OR>): MapFn<I, O, IR, D, OR> {
+      return mapper(c)(map);
+    },
+  }),
+};
+
+/**
+ * **mapTo** _utility_
  *
- * and now you'll have a _mapper_ variable will be assigned as a mapping fn:
- * ```ts
- * function (source: I | I[]): O[]
- * ```
+ * This utility creates a strongly typed data mapper which maps from one
+ * known source `I` to another `O`.
  */
-export const mapTo =
-  <I extends {}, O extends {}>(cb: MapToWithFiltering<I, O>) =>
-  (source: I | I[]) => {
-    if (Array.isArray(source)) {
-      return source.flatMap((i) => cb(i)).filter((i) => i !== null) as O[];
-    } else {
-      const result = cb(source);
-      return result ? result : ([] as O[]);
-    }
-  };
+export const mapTo = createFnWithProps(mapToFn, mapToDict);

package/tests/createFnWithProps.spec.ts

@@ -5,6 +5,7 @@ describe("createFnWithProps()", () => {
   it("simple fn and prop are combined, type is retained", () => {
     const fn = () => "hi";
     const props = { foo: "bar" };
+    /** combo */
     const combo = createFnWithProps(fn, props);
 
     expect(combo.foo).toBe("bar");

package/tests/dictionary/mapTo.test.ts

@@ -1,4 +1,4 @@
-import { MapTo } from "src/types/dictionary";
+import { MapDirection, MapFn, MapTo } from "src/types/dictionary";
 import { describe, expect, it } from "vitest";
 
 import type { Expect, Equal } from "@type-challenges/utils";
@@ -10,115 +10,182 @@ const i2: I = { title: "i2", color: "green", products: ["foo", "bar", "baz"] };
 
 type O = { title: string; count: number; unnecessary?: number };
 
-describe("MapTo<T> type util", () => {
-  it("1:1 conversion", () => {
-    const m: MapTo<I, O> = (i) => [
-      {
-        title: i.title,
-        count: i.products.length,
-      },
+describe("MapTo<I,O> and MapToFn<I,O>", () => {
+  it("MapTo with 0:M, 0:M cardinality", () => {
+    type Fn = MapTo<I, O>;
+    type Fn2 = MapTo<I, O, "req", MapDirection.OneToMany, "opt">;
+    type WFn = MapFn<I, O>;
+    type WFn2 = MapFn<I, O, "req", MapDirection.OneToMany, "opt">;
+
+    /** userland mapping function */
+    type T = (source: I) => O[];
+    /** exposed via mapTo() util */
+    type WT = <S extends I | I[]>(source: S) => S extends I[] ? O[] : O[] | null;
+
+    type cases = [
+      Expect<Equal<Fn, Fn2>>, // implicit default = explicit values
+      Expect<Equal<WFn, WFn2>>, // implicit default = explicit values
+      Expect<Equal<Fn, T>>,
+      Expect<Equal<WFn, WT>>
     ];
-    type M = typeof m;
-    type cases = [Expect<Equal<M, MapTo<I, O>>>];
-    const cases: cases = [true];
-    expect(cases).toBe(cases);
+    const cases: cases = [true, true, true, true];
   });
 
-  it("1:1 conversion with non-required", () => {
-    const m: MapTo<I, O> = (i) => [
-      {
-        title: i.title,
-        count: i.products.length,
-        unnecessary: 42,
-      },
+  it("MapTo<X> with I -> O[] variable config", () => {
+    type Fn0 = MapTo<I, O, "req", MapDirection.OneToMany, "opt">;
+    type Fn1 = MapTo<I, O, "req", MapDirection.OneToMany, "req">;
+    type Fn2 = MapTo<I, O, "opt", MapDirection.OneToMany, "opt">;
+    type Fn3 = MapTo<I, O, "opt", "I -> O[]", "req">;
+
+    type T0 = (source: I) => O[];
+    type T1 = (source: I) => [O, ...O[]];
+    type T2 = (source?: I) => O[];
+    type T3 = (source?: I) => [O, ...O[]];
+
+    type cases = [
+      Expect<Equal<Fn0, T0>>, //
+      Expect<Equal<Fn1, T1>>, //
+      Expect<Equal<Fn2, T2>>, //
+      Expect<Equal<Fn3, T3>> //
     ];
-    type M = typeof m;
-    type cases = [Expect<Equal<M, MapTo<I, O>>>];
-    const cases: cases = [true];
-    expect(cases).toBe(cases);
+    const cases: cases = [true, true, true, true];
   });
 
-  it("1:M conversion", () => {
-    const m: MapTo<I, O> = (i) => [
-      {
-        title: i.title,
-        count: i.products.length,
-        unnecessary: 1,
-      },
-      {
-        title: i.title,
-        count: i.products.length + 1,
-        unnecessary: 2,
-      },
+  it("MapTo<X> with I[] -> O variable config", () => {
+    type Fn0 = MapTo<I, O, "req", "I[] -> O", "opt">;
+    type Fn1 = MapTo<I, O, "req", "I[] -> O", "req">;
+    type Fn2 = MapTo<I, O, "opt", "I[] -> O", "opt">;
+    type Fn3 = MapTo<I, O, "opt", "I[] -> O", "req">;
+
+    type T0 = (source: I[]) => O | null;
+    type T1 = (source: I[]) => O;
+    type T2 = (source?: I[]) => O | null;
+    type T3 = (source?: I[]) => O;
+
+    type cases = [
+      Expect<Equal<Fn0, T0>>, //
+      Expect<Equal<Fn1, T1>>, //
+      Expect<Equal<Fn2, T2>>, //
+      Expect<Equal<Fn3, T3>> //
     ];
-    type M = typeof m;
-    type cases = [Expect<Equal<M, MapTo<I, O>>>];
-    const cases: cases = [true];
-    expect(cases).toBe(cases);
+    const cases: cases = [true, true, true, true];
   });
 
-  it("filter input as 1:0 cardinality", () => {
-    const m: MapTo<I, O> = (_i) => [];
-    type M = typeof m;
-    type cases = [Expect<Equal<M, MapTo<I, O>>>];
-    const cases: cases = [true];
-    expect(cases).toBe(cases);
+  it("MapFn<X> with I -> O[] variable config", () => {
+    type Fn0 = MapFn<I, O, "req", "I -> O[]", "opt">;
+    type Fn1 = MapFn<I, O, "req", "I -> O[]", "req">;
+    type Fn2 = MapFn<I, O, "opt", "I -> O[]", "opt">;
+    type Fn3 = MapFn<I, O, "opt", "I -> O[]", "req">;
+
+    type T0 = <S extends I | I[]>(source: S) => S extends I[] ? O[] : O[] | null;
+    type T1 = <S extends I | I[]>(source: S) => S extends I[] ? [O, ...O[]] : O[];
+    type T2 = <S extends I | I[] | undefined>(source?: S) => S extends I[] ? O[] : O[] | null;
+    type T3 = <S extends I | I[] | undefined>(source?: S) => S extends I[] ? [O, ...O[]] : O[];
+
+    type cases = [
+      Expect<Equal<Fn0, T0>>, //
+      Expect<Equal<Fn1, T1>>, //
+      Expect<Equal<Fn2, T2>>, //
+      Expect<Equal<Fn3, T3>> //
+    ];
+    const cases: cases = [true, true, true, true];
+  });
+
+  it("MapFn<X> with I[] -> O variable config", () => {
+    type Fn0 = MapFn<I, O, "req", "I[] -> O", "opt">;
+    type Fn1 = MapFn<I, O, "req", "I[] -> O", "req">;
+    type Fn2 = MapFn<I, O, "opt", "I[] -> O", "opt">;
+    type Fn3 = MapFn<I, O, "opt", "I[] -> O", "req">;
+
+    type T0 = <S extends I[] | I[][]>(source: S) => S extends I[][] ? O[] : O | null;
+    type T1 = <S extends I[] | I[][]>(source: S) => S extends I[][] ? [O, ...O[]] : O;
+    type T2 = <S extends I[] | I[][] | undefined>(source?: S) => S extends I[][] ? O[] : O | null;
+    type T3 = <S extends I[] | I[][] | undefined>(source?: S) => S extends I[][] ? [O, ...O[]] : O;
+
+    type cases = [
+      Expect<Equal<Fn0, T0>>, //
+      Expect<Equal<Fn1, T1>>, //
+      Expect<Equal<Fn2, T2>>, //
+      Expect<Equal<Fn3, T3>> //
+    ];
+    const cases: cases = [true, true, true, true];
+  });
+
+  it("walk through of mapTo types", () => {
+    const t1 = mapTo<I, O>((i) => [{ title: i.title, count: i.products.length }]);
+    type T1 = typeof t1;
+
+    const a1 = mapTo
+      .config({ input: "req" })
+      .map<I, O>((i) => [{ title: i.title, count: i.products.length }]);
+    type A1 = typeof a1;
+
+    type cases = [
+      Expect<Equal<T1, MapFn<I, O>>>, //
+      Expect<Equal<T1, A1>>
+    ];
+    const cases: cases = [true, true];
   });
 });
 
 describe("mapTo() utility function", () => {
-  it("test 1:1 mapping", () => {
-    const m = mapTo<I, O>((i) => [
-      {
-        title: i.title,
-        count: i.products.length,
-      },
-    ]);
-    type M = typeof m;
-    type R = ReturnType<M>;
-
-    // runtime
-    expect(m(i)).toEqual([{ title: i.title, count: i.products.length }]);
-    // types
-    type cases = [Expect<Equal<R, O[]>>];
-    const cases: cases = [true];
-    expect(cases).toBe(cases);
+  it("M:1 conversion", () => {
+    const m = mapTo
+      .config({
+        direction: "I[] -> O",
+        output: "req",
+      })
+      .map<I, O>((i) => ({
+        title: "count of products",
+        count: i.reduce((acc, i) => (acc = acc + i.products.length), 0),
+      }));
+
+    const summary = m([i, i2]);
+    expect(summary.title).toBe("count of products");
+    expect(summary.count).toBe(6);
+  });
+
+  it("1:1 conversion", () => {
+    const m = mapTo
+      .config({ output: "req", direction: MapDirection.OneToOne })
+      .map<I, O>((i) => ({ title: i.title, count: i.products.length }));
+    const o = m(i);
+
+    expect(o?.title).toBe(i.title);
+    expect(o?.count).toBe(3);
   });
 
-  it("test 1:1 mapping with extraneous prop", () => {
-    const m = mapTo<I, O>((i) => [
-      {
-        title: i.title,
-        count: i.products.length,
-        extraneous: 42,
-      },
-    ]);
-    type M = typeof m;
-    type R = ReturnType<M>;
-
-    // runtime
-    // TODO: extraneous props are cut out of the type but still allows us to return `O` values with extraneous props!
-    // expect(m(i)).toEqual([{ title: i.title, count: i.products.length }]);
-    // types
-    type cases = [Expect<Equal<R, O[]>>];
-    const cases: cases = [true];
-    expect(cases).toBe(cases);
+  it("1:1 with 1:M conversion setting", () => {
+    const m = mapTo
+      .config({ output: "req", direction: MapDirection.OneToMany })
+      .map<I, O>((i) => [{ title: i.title, count: i.products.length }]);
+    const o = m(i);
+
+    expect(o.length).toBe(1);
+    expect(o[0]?.title).toBe(i.title);
+    expect(o[0]?.count).toBe(3);
+  });
+
+  it("1:M conversion ", () => {
+    const m = mapTo
+      .config({ output: "req", direction: MapDirection.OneToMany })
+      .map<I, O>((i) => [{ title: i.title, count: i.products.length }]);
+    const o = m([i, i2]);
+
+    expect(o.length).toBe(2);
+    o.map((item) => expect("title" in item).toBeTruthy());
   });
 
-  it("test input filtering", () => {
-    const m = mapTo<I, O>((x) => {
-      return x.title === "i2"
-        ? null
-        : [
-            {
-              title: i.title,
-              count: i.products.length,
-            },
-          ];
+  it("M:1 conversion", () => {
+    const m = mapTo.config({ output: "req", direction: MapDirection.ManyToOne }).map<I, O>((i) => {
+      return {
+        title: "summary",
+        count: i.reduce((acc, i) => (acc = acc + i.products.length), 0),
+      };
     });
-    const results = m([i, i2]);
+    const o = m([i, i2]);
 
-    expect(results).toHaveLength(1);
-    expect(results[0].title).toBe("Test");
+    expect(o.title).toBe("summary");
+    expect(o.count).toBe(6);
   });
 });