inferred-types 0.27.0 → 0.28.2

package/src/types/dictionary/MapTo.ts

@@ -1,10 +1,17 @@
+/* eslint-disable no-use-before-define */
 import { OptRequired } from "src/types/literal-unions";
+import {
+  DefaultManyToOneMapping,
+  DefaultOneToManyMapping,
+  DefaultOneToOneMapping,
+} from "src/utility/dictionary/mapTo";
 import { EnumValues } from "../EnumValues";
+import { TypeDefault } from "../TypeInfo/TypeDefault";
 
 /**
  * Expresses relationship between inputs/outputs:
  */
-export enum MapDirection {
+export enum MapCardinality {
   /** every input results in 0:M outputs */
   OneToMany = "I -> O[]",
   /** every input results in 0:1 outputs */
@@ -13,35 +20,230 @@ export enum MapDirection {
   ManyToOne = "I[] -> O",
 }
 
-export type MapDirectionVal = EnumValues<MapDirection>;
+export type MapCardinalityIllustrated = EnumValues<MapCardinality>;
 
-export type MapInput<I, IR, D extends MapDirectionVal> = D extends
-  | MapDirection.OneToMany
-  | "I -> O[]"
+/**
+ * The _user_ configuration of a **mapTo** mapper function
+ * which will be finalized by merging it with the appropriate
+ * default mapping type.
+ */
+export 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._
+ */
+export 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()`)
+ */
+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.
+ */
+export 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
+ */
+export 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` */
+export type MapIR<
+  T extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>
+> = DecomposeMapConfig<T>[0];
+
+/**
+ * extracts the MapCardinality from a `FinalizedMapConfig`
+ */
+export type MapCard<
+  T extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>
+> = DecomposeMapConfig<T>[1];
+
+/** extracts OR from a `FinalizedMapConfig` */
+export type MapOR<
+  T extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>
+> = DecomposeMapConfig<T>[2];
+
+/**
+ * Merges the types of a userland configuration with a default configuration
+ */
+export 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;
+
+export 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
+    >
+  >;
+};
+
+export type MapInput<
+  I, //
+  IR extends OptRequired,
+  C extends MapCardinalityIllustrated
+> = C extends MapCardinality.OneToMany | "I -> O[]"
   ? IR extends "opt"
     ? I | undefined
     : I
-  : D extends MapDirection.OneToOne | "I -> O"
+  : C extends MapCardinality.OneToOne | "I -> O"
   ? IR extends "opt"
     ? I | undefined
     : I
-  : D extends MapDirection.ManyToOne | "I[] -> O"
+  : C extends MapCardinality.ManyToOne | "I[] -> O"
   ? IR extends "opt"
     ? I[] | undefined
     : I[]
   : never;
 
-export type MapOutput<O, OR, D extends MapDirectionVal> = D extends
-  | MapDirection.OneToMany
-  | "I -> O[]"
+export type MapOutput<
+  O, //
+  OR extends OptRequired,
+  C extends MapCardinalityIllustrated
+> = C extends MapCardinality.OneToMany | "I -> O[]"
   ? OR extends "opt"
     ? O[]
     : [O, ...O[]]
-  : D extends MapDirection.OneToOne | "I -> O"
+  : C extends MapCardinality.OneToOne | "I -> O"
   ? OR extends "opt"
     ? O | null
     : O
-  : D extends MapDirection.ManyToOne | "I[] -> O"
+  : C extends MapCardinality.ManyToOne | "I[] -> O"
   ? OR extends "opt"
     ? O | null
     : O
@@ -50,7 +252,8 @@ export type MapOutput<O, OR, D extends MapDirectionVal> = D extends
 /**
  * **MapTo<I, O>**
  *
- * A mapping function between an input type `I` and output type `O`.
+ * A mapping function between an input type `I` and output type `O`. Defaults to using
+ * the _default_ OneToMany mapping config.
  *
  * **Note:** this type is designed to guide the userland mapping; refer
  * to `MapFn` if you want the type output by the `mapFn()` utility.
@@ -58,16 +261,22 @@ export type MapOutput<O, OR, D extends MapDirectionVal> = D extends
 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 MapFnOutput<I, O, S, OR extends OptRequired, D extends MapDirectionVal> = D extends
-  | "I -> O[]"
-  | MapDirection.OneToMany
+  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>>;
+
+export type MapFnOutput<
+  I,
+  O,
+  S,
+  OR extends OptRequired,
+  C extends MapCardinalityIllustrated
+> = C extends "I -> O[]" | MapCardinality.OneToMany
   ? S extends I[]
     ? OR extends "opt"
       ? O[]
@@ -75,7 +284,7 @@ export type MapFnOutput<I, O, S, OR extends OptRequired, D extends MapDirectionV
     : OR extends "opt"
     ? O[] | null
     : O[]
-  : D extends MapDirection.OneToOne | "I -> O"
+  : C extends MapCardinality.OneToOne | "I -> O"
   ? S extends I[]
     ? OR extends "opt"
       ? O[]
@@ -83,7 +292,7 @@ export type MapFnOutput<I, O, S, OR extends OptRequired, D extends MapDirectionV
     : OR extends "opt"
     ? O | null
     : O
-  : D extends MapDirection.ManyToOne | "I[] -> O"
+  : C extends MapCardinality.ManyToOne | "I[] -> O"
   ? S extends I[][]
     ? OR extends "opt"
       ? O[]
@@ -93,17 +302,17 @@ export type MapFnOutput<I, O, S, OR extends OptRequired, D extends MapDirectionV
     : O
   : never;
 
-export type MapFnInput<I, IR extends OptRequired, D extends MapDirectionVal> = D extends
+export type MapFnInput<I, IR extends OptRequired, D extends MapCardinalityIllustrated> = D extends
   | "I -> O[]"
-  | MapDirection.OneToMany
+  | MapCardinality.OneToMany
   ? IR extends "opt"
     ? I | I[] | undefined
     : I | I[]
-  : D extends MapDirection.OneToOne | "I -> O"
+  : D extends MapCardinality.OneToOne | "I -> O"
   ? IR extends "opt"
     ? I | I[] | undefined
     : I | I[]
-  : D extends MapDirection.ManyToOne | "I[] -> O"
+  : D extends MapCardinality.ManyToOne | "I[] -> O"
   ? IR extends "opt"
     ? I[] | I[][] | undefined
     : I[] | I[][]
@@ -121,16 +330,18 @@ export type MapFnInput<I, IR extends OptRequired, D extends MapDirectionVal> = D
  *    ```
  * 2. Block:
  *    ```ts
- *    // maps inputs to outputs (filtering or splitting where approp)
+ *    // maps inputs to outputs (filtering or splitting where appr.)
  *    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>;
+  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>>;

package/src/types/dictionary/props.ts

@@ -1,4 +1,5 @@
 import { Alpha } from "../alphabetic/alpha-characters";
+import { Keys } from "../Keys";
 
 /**
  * Extracts the _required_ keys in the object's type. You also may
@@ -12,6 +13,16 @@ export type RequiredKeys<T extends object, V extends any = any> = {
     : never;
 }[keyof T];
 
+/**
+ * Extracts the intersecting/common keys to two objects
+ */
+export 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.

package/src/types/kv/DictFromKv.ts

@@ -1,3 +1,3 @@
-export type DictFromKv<T extends readonly Readonly<{ key: string; value: unknown }>[]> = {
+export type DictFromKv<T extends readonly { key: string; value: unknown }[]> = {
   [R in T[number] as R["key"]]: R["value"];
 };

package/src/types/type-testing.ts

@@ -8,10 +8,7 @@ export type ExpectExtends<VALUE, EXPECTED> = EXPECTED extends VALUE ? true : fal
  */
 export type AssertExtends<VALUE, EXPECTED> = EXPECTED extends VALUE ? any : never;
 
-
-export type IfExtends<VALUE, EXPECTED> = EXPECTED extends VALUE ? VALUE : never;
-
 /**
- * Give a type `TValue` and a comparison type `TExtends` 
+ * Give a type `TValue` and a comparison type `TExtends`
  */
-export type IfExtendsThen<VALUE, EXPECTED, THEN> = EXPECTED extends VALUE ? THEN : never;
+export type IfExtendsThen<VALUE, EXPECTED, THEN> = EXPECTED extends VALUE ? THEN : never;

package/src/utility/dictionary/kv/kvToDict.ts

@@ -1,5 +1,4 @@
 import { DictFromKv } from "src/types/kv";
-import { Mutable } from "src/types/Mutable";
 import { Narrowable } from "src/types/Narrowable";
 
 /**
@@ -21,5 +20,5 @@ export function kvToDict<
     out[kv.key as keyof DictFromKv<T>] = kv.value;
   }
 
-  return out as DictFromKv<Mutable<T>>;
+  return out as DictFromKv<T>;
 }

package/src/utility/dictionary/mapTo.ts

@@ -1,118 +1,155 @@
-import { MapDirectionVal, MapFn, MapFnInput, MapTo } from "src/types/dictionary";
+import {
+  FinalizedMapConfig,
+  MapCardinalityIllustrated,
+  MapFnInput,
+  MapperApi,
+  MapTo,
+  AsFinalizedConfig,
+  MapConfig,
+  ConfiguredMap,
+  MapFnOutput,
+  MapIR,
+  MapCard,
+  MapOR,
+} 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;
-}
-
 /**
- * Provides a mapper function using the default configuration
+ * utility function to take a fully-qualified _user_ config
+ * and make it into a FinalizedMapConfig
  */
-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"
+const toFinalizedConfig = <
+  IR extends OptRequired,
+  D extends MapCardinalityIllustrated,
+  OR extends OptRequired
 >(
   config: MapConfig<IR, D, OR>
-) => <I, O>(map: MapTo<I, O, IR, D, OR>) => MapFn<I, O, IR, D, OR>;
+) => {
+  return { ...config, finalized: true } as FinalizedMapConfig<IR, D, OR>;
+};
+
+export const DEFAULT_ONE_TO_MANY_MAPPING = toFinalizedConfig({
+  input: "req",
+  output: "opt",
+  cardinality: "I -> O[]",
+});
+export const DEFAULT_ONE_TO_ONE_MAPPING = toFinalizedConfig({
+  input: "req",
+  output: "req",
+  cardinality: "I -> O",
+});
+export const DEFAULT_MANY_TO_ONE_MAPPING = toFinalizedConfig({
+  input: "req",
+  output: "req",
+  cardinality: "I[] -> O",
+});
+
+export type DefaultOneToManyMapping = typeof DEFAULT_ONE_TO_MANY_MAPPING;
+export type DefaultOneToOneMapping = typeof DEFAULT_ONE_TO_ONE_MAPPING;
+export type DefaultManyToOneMapping = typeof DEFAULT_MANY_TO_ONE_MAPPING;
 
 /**
  * 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) => {
+  <C extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>>(config: C) =>
+  <I, O>(map: MapTo<I, O, C>) => {
+    return <S extends MapFnInput<I, MapIR<C>, MapCard<C>>>(
+      source?: S
+    ): MapFnOutput<I, O, S, MapOR<C>, MapCard<C>> => {
+      /**
+       * Determine whether input is an array; this will be true
+       */
       const isArray =
-        config.direction === "I -> O[]" && Array.isArray(source)
+        config.cardinality === "I -> O[]" && Array.isArray(source)
           ? true
-          : config.direction === "I[] -> O" && Array.isArray(source) && Array.isArray(source[0])
+          : config.cardinality === "I[] -> O" && Array.isArray(source) && Array.isArray(source[0])
           ? true
           : false;
 
       if (isArray) {
-        return (source as any).flatMap(map);
+        // iterate over inputs with flatMap to return mapped values as
+        // well as supporting filtering functionality. We could achieve
+        // the same results by simply passing in all inputs to our mapper
+        // in most cardinalities but when cardinality is M:1 we need to
+        // make sure that the first array of elements is passed as a single
+        // item and this approach achieves this.
+        // TODO: we should check that the approach below doesn't work for M:1 here
+        // as well
+        return (source as any).flatMap(map) as MapFnOutput<I, O, S, MapOR<C>, MapCard<C>>;
       } else {
-        return map(source as any);
+        // receive _all_ inputs provided as pass into ; this is just a single input unless the
+        // cardinality is
+        return map(source as any) as MapFnOutput<I, O, S, MapOR<C>, MapCard<C>>;
       }
     };
-
-    return fn as unknown as MapFn<I, O, IR, D, OR>;
   };
 
+/**
+ * Takes a userland configuration and a default configuration and then produces
+ * the appropriately typed `ConfiguredMap` API surface.
+ */
+const setMapper = <
+  U extends MapConfig<
+    OptRequired | undefined,
+    MapCardinalityIllustrated | undefined,
+    OptRequired | undefined
+  >,
+  D extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>
+>(
+  config: U = { input: undefined, output: undefined, cardinality: undefined } as U,
+  defaultValue: D
+): ConfiguredMap<AsFinalizedConfig<U, D>> => ({
+  map: (source) => {
+    // merge userland config with defaults for a cardinality
+    const c = {
+      ...defaultValue,
+      ...config,
+    } as unknown as AsFinalizedConfig<U, D>;
+    return mapper(c)(source);
+  },
+  input: config?.input || defaultValue.input,
+  output: config?.output || defaultValue.output,
+  cardinality: config?.cardinality || defaultValue.cardinality,
+});
+
 /**
  * **mapTo** _utility_
  *
- * This utility creates a strongly typed data mapper which maps from one
- * known source `I` to another `O`:
+ * 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
  * }]);
  * ```
  */
-export const mapToFn = <I, O>(map: MapTo<I, O>) => {
-  return mapper()<I, O>(map);
+export const mapToFn: ConfiguredMap<DefaultOneToManyMapping>["map"] = (map) => {
+  return mapper(DEFAULT_ONE_TO_MANY_MAPPING)(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);
-    },
-  }),
+export const mapToDict: MapperApi = {
+  config(config) {
+    const c = { ...DEFAULT_ONE_TO_MANY_MAPPING, ...config };
+    return setMapper(c, DEFAULT_ONE_TO_MANY_MAPPING);
+  },
+  oneToOne(config) {
+    const c = { ...DEFAULT_ONE_TO_ONE_MAPPING, ...config };
+    return setMapper(c, DEFAULT_ONE_TO_ONE_MAPPING);
+  },
+  manyToOne(config) {
+    const c = { ...DEFAULT_MANY_TO_ONE_MAPPING, ...config };
+    return setMapper(c, DEFAULT_MANY_TO_ONE_MAPPING);
+  },
+  oneToMany(config) {
+    const c = { ...DEFAULT_ONE_TO_MANY_MAPPING, ...config };
+    return setMapper(c, DEFAULT_ONE_TO_MANY_MAPPING);
+  },
 };
 
 /**
@@ -120,5 +157,13 @@ export const mapToDict = {
  *
  * This utility creates a strongly typed data mapper which maps from one
  * known source `I` to another `O`.
+ *
+ * Signatures:
+ * ```ts
+ * const defMap = mapTo<I,O>( ... );
+ * const configured = mapTo.config({ output: "req" }).map<I,O>( ... );
+ * const one2one = mapTo.oneToOne().map<I,O>( ... );
+ * const many2one = mapTo.manyToOne().map<I,O>( ... );
+ * ```
  */
 export const mapTo = createFnWithProps(mapToFn, mapToDict);