inferred-types 0.25.0 → 0.27.0

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/src/utility/index.ts

@@ -10,11 +10,11 @@ export * from "./keys";
 export * from "./ruleset";
 // directory exports
 export * from "./api/index";
+export * from "./boolean-logic/index";
 export * from "./dictionary/index";
 export * from "./errors/index";
 export * from "./lists/index";
 export * from "./literals/index";
-export * from "./map-reduce/index";
 export * from "./modelling/index";
 export * from "./runtime/index";
 export * from "./state/index";

package/src/utility/lists/asArray.ts

@@ -0,0 +1,34 @@
+import { Narrowable, Widen } from "src/types";
+import { isArray } from "../runtime";
+
+/**
+ * Type utility which converts `undefined[]` to `unknown[]`
+ */
+export type UndefinedArrayIsUnknown<T extends any[]> = undefined[] extends T ? unknown[] : T;
+
+export type AsArray<T, W extends boolean = false> = T extends any[]
+  ? W extends true
+    ? Widen<T>
+    : T
+  : W extends true
+  ? UndefinedArrayIsUnknown<Widen<T>[]>
+  : UndefinedArrayIsUnknown<T[]>;
+
+/**
+ * Ensures that any input passed in is passed back as an array:
+ *
+ * - if it was already an array than this just serves as an _identity_ function
+ * - if it was not then it wraps the element into a one element array of the
+ * given type
+ *
+ * Note: by default the _type_ of values will be intentionally widened so that the value "abc"
+ * is of type `string` not the literal `abc`. If you want to keep literal types then
+ * change the optional _widen_ parameter to _false_.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export const asArray = <T extends Narrowable, W extends boolean = true>(thing: T, _widen?: W) => {
+  return (isArray(thing) ? thing : typeof thing === "undefined" ? ([] as T[]) : [thing]) as AsArray<
+    T,
+    W
+  >;
+};

package/src/utility/lists/index.ts

@@ -5,6 +5,7 @@
 // hash-code: bf4a6791
 
 // file exports
+export * from "./asArray";
 export * from "./groupBy";
 
 // #endregion auto-indexed files

package/tests/boolean-logic/boolean.spec.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect } from "vitest";
+// import type { Equal, Expect } from "@type-challenges/utils";
+import { and, filter } from "src/utility";
+
+describe("boolean logic", () => {
+  it("AND operation", () => {
+    const a1 = and(
+      () => true,
+      () => false
+    );
+    const a2 = and(
+      () => true,
+      () => true
+    );
+    const md = and(filter({ endsWith: ".md" }), filter({ not: { startsWith: "_" } }));
+
+    expect(a1()).toBe(false);
+    expect(a2()).toBe(true);
+    expect(["foo.md", "bar.html", "_baz.md"].filter(md)).toEqual(["foo.md"]);
+  });
+});

package/tests/boolean-logic/filter.spec.ts

@@ -0,0 +1,52 @@
+import { filter } from "src/utility";
+import { Equal, Expect } from "@type-challenges/utils";
+import { describe, it, expect } from "vitest";
+
+describe("filter() utility function", () => {
+  it("string filter built and gives proper types", () => {
+    const f = filter({ startsWith: "th" });
+    type P = Parameters<typeof f>;
+    type R = ReturnType<typeof f>;
+    const notPrivate = filter({ not: { startsWith: ["_", "."] } });
+
+    // runtime
+    expect(typeof f).toEqual("function");
+    expect(["one", "two", "three"].filter(f)).toEqual(["three"]);
+    expect(["foo.md", "bar.html", "_private.md", ".bobs-your-uncle.txt"].filter(notPrivate)) //
+      .toEqual(["foo.md", "bar.html"]);
+
+    // design time
+    type cases = [
+      Expect<Equal<P[0], string | undefined>>, //
+      Expect<Equal<R, boolean>>
+    ];
+    const cases: cases = [true, true];
+  });
+
+  it("numeric filter built and gives proper types", () => {
+    const f = filter({ equals: 42 });
+    type P = Parameters<typeof f>;
+    type R = ReturnType<typeof f>;
+
+    // runtime
+    expect(typeof f).toEqual("function");
+    expect([1, 2, 3, 4, 5].filter(filter({ greaterThan: 3 }))) //
+      .toEqual([4, 5]);
+    expect([1, 2, 3, 4, 5].filter(filter({ not: { greaterThan: 3 } }))) //
+      .toEqual([1, 2, 3]);
+
+    // design time
+    type cases = [
+      Expect<Equal<P[0], number | undefined>>, //
+      Expect<Equal<R, boolean>>
+    ];
+    const cases: cases = [true, true];
+  });
+
+  it("string filter's startsWith", () => {
+    const f = filter({ startsWith: "." });
+    const remaining = ["foo", "bar", ".baz"].filter(f);
+
+    expect(remaining).toEqual([".baz"]);
+  });
+});

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);
   });
 });

package/tests/lists/asArray.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from "vitest";
+import { asArray } from "src/utility";
+import { Equal, Expect } from "@type-challenges/utils";
+
+describe("asArray() function", () => {
+  it("non-array is returned as an array", () => {
+    const i = "a";
+    const o = asArray(i);
+    type O = typeof o;
+
+    // run-time
+    expect(o).toEqual(["a"]);
+    // design-time
+    type cases = [Expect<Equal<O, string[]>>];
+    const cases: cases = [true];
+  });
+
+  it("array is returned as an array", () => {
+    const i = ["a"];
+    const o = asArray(i);
+    type O = typeof o;
+
+    // run-time
+    expect(o).toEqual(["a"]);
+    // design-time
+    type cases = [Expect<Equal<O, string[]>>];
+    const cases: cases = [true];
+  });
+
+  it("non-array literal is returned as an array", () => {
+    const i = "a" as const;
+    const o = asArray(i, false);
+    const o2 = asArray(i, true);
+
+    type O = typeof o;
+    type O2 = typeof o2;
+
+    // run-time
+    expect(o).toEqual(["a"]);
+    // design-time
+    type cases = [
+      Expect<Equal<O, "a"[]>>, //
+      Expect<Equal<O2, string[]>>
+    ];
+    const cases: cases = [true, true];
+  });
+
+  it("handling non-array element which presents as undefined", () => {
+    type T = string | undefined;
+    const i = undefined;
+    const i2: T = undefined;
+    const o = asArray(i);
+    const o2 = asArray(i2 as T);
+    const o3 = asArray(i2 as T, false);
+    type O = typeof o;
+    type O2 = typeof o2;
+    type O3 = typeof o3;
+
+    // run-time
+    expect(o).toEqual([]);
+    expect(o2).toEqual([]);
+    // design-time
+    type cases = [
+      Expect<Equal<O, unknown[]>>, //
+      // TODO: would be nice to extract the unknown[] part of the union
+      Expect<Equal<O2, unknown[] | string[]>>,
+      Expect<Equal<O3, unknown[] | string[]>>
+    ];
+    const cases: cases = [true, true, true];
+  });
+
+  it("handling array element which contains undefined is unaffected", () => {
+    type T = string | undefined;
+    const i = [undefined, "foobar"];
+    const i2: T[] = [undefined, "foobar"];
+    const o = asArray(i);
+    const o2 = asArray(i2 as T[]);
+    type O = typeof o;
+    type O2 = typeof o2;
+
+    // run-time
+    expect(o).toEqual([undefined, "foobar"]);
+    expect(o2).toEqual([undefined, "foobar"]);
+    // design-time
+    type cases = [
+      Expect<Equal<O, (string | undefined)[]>>, //
+      Expect<Equal<O2, T[]>>
+    ];
+    const cases: cases = [true, true];
+  });
+});