inferred-types 0.25.0 → 0.26.0

package/src/utility/boolean-logic/filter.ts

@@ -0,0 +1,268 @@
+import { asArray } from "../lists/asArray";
+
+// string filters
+export type FilterStarts = {
+  /** one or more string which the value is allowed to start with */
+  startsWith: string | string[];
+};
+export type FilterIs = {
+  /** whether a string _**is**_ of a particular value */
+  is: string | string[];
+};
+export type FilterEnds = { endsWith: string | string[] };
+export type FilterContains = {
+  /** whether any of the strings specified are _contained_ in the value */
+  contains: string | string[];
+};
+
+// numeric filters
+export type FilterEquals = {
+  /** one or more values which _equal_ the value passed in */
+  equals: number | number[];
+};
+export type FilterNotEqual = {
+  /** one or more values which ALL _do not equal_ the value passed in */
+  notEqual: number | number[];
+};
+export type FilterGreaterThan = {
+  /** the incoming value is greater than this value */
+  greaterThan: number;
+};
+export type FilterLessThan = {
+  /** the incoming value is less than this value */
+  lessThan: number;
+};
+
+export type StringFilter =
+  | FilterIs
+  | FilterStarts
+  | FilterEnds
+  | FilterContains
+  | (FilterStarts & FilterEnds)
+  | (FilterStarts & FilterContains)
+  | (FilterEnds & FilterContains)
+  | (FilterStarts & FilterEnds & FilterContains);
+
+export type NumericFilter =
+  | FilterEquals
+  | FilterNotEqual
+  | FilterGreaterThan
+  | FilterLessThan
+  | (FilterEquals & FilterNotEqual)
+  | (FilterEquals & FilterGreaterThan)
+  | (FilterEquals & FilterLessThan)
+  | (FilterNotEqual & FilterGreaterThan)
+  | (FilterNotEqual & FilterLessThan)
+  | (FilterGreaterThan & FilterLessThan)
+  | (FilterEquals & FilterGreaterThan & FilterLessThan)
+  | (FilterNotEqual & FilterGreaterThan & FilterLessThan)
+  | (FilterEquals & FilterNotEqual & FilterGreaterThan & FilterLessThan);
+
+export type FilterDefn = StringFilter | NumericFilter;
+
+// NOT filter
+export type NotFilter = {
+  /**
+   * **not**
+   *
+   * If you want to build a filter who's conditions being met results in _filtering_
+   * the value rather than accepting it then choose this.
+   */
+  not: FilterDefn;
+};
+
+export function isNotFilter(f: FilterDefn | NotFilter): f is NotFilter {
+  return typeof f === "object" && "not" in f;
+}
+
+export type UnwrapNot<T extends FilterDefn | NotFilter> = T extends NotFilter
+  ? T["not"] extends StringFilter
+    ? StringFilter
+    : NumericFilter
+  : T;
+
+export function isNumericFilter(filter: FilterDefn): filter is NumericFilter {
+  return "equals" in filter ||
+    "notEqual" in filter ||
+    "greaterThan" in filter ||
+    "lessThan" in filter
+    ? true
+    : false;
+}
+
+export type UndefinedValue<U extends boolean> = true extends U
+  ? "undefined treated as 'true'"
+  : U extends "no-impact"
+  ? "undefined treated in no-impact fashion"
+  : "undefined treated as 'false'";
+
+export type UndefinedTreatment = "undefined treated as 'true'" | "undefined treated as 'false'";
+
+export type LogicalCombinator = "AND" | "OR";
+
+/**
+ * **FilterFn**
+ *
+ * A filter function derived from the `filter()` configurator. This function is intended to provide a type-strong _filter_ function which can be used like so:
+ * be used like:
+ * ```ts
+ * const onlyPrivate = filter({ startsWith: "_" });
+ * const privateFiles = files.filter(onlyPrivate);
+ * ```
+ *
+ */
+export type FilterFn<T extends StringFilter | NumericFilter> = T extends StringFilter
+  ? <V extends string | undefined>(input: V) => boolean
+  : <V extends number | undefined>(input: V) => boolean;
+
+/**
+ * Defines a logical function for each condition type
+ */
+export type ConditionFilter<T extends StringFilter | NumericFilter> = T extends StringFilter
+  ? (input: string) => boolean
+  : (input: number) => boolean;
+
+/**
+ * Wraps numeric filter's configuration into a logic filter
+ */
+const numericOps = <L extends LogicalCombinator>(config: NumericFilter, boolLogic: L) => {
+  const equals = (n: number | number[]): [ConditionFilter<NumericFilter>] | [] => {
+    const f = asArray(n);
+    return f.length === 0 ? [] : [(input?: number) => f.some((i) => i === input)];
+  };
+  const notEqual = (n: number | number[]): [ConditionFilter<NumericFilter>] | [] => {
+    const f = asArray(n);
+    return f.length === 0 ? [] : [(input?: number) => f.every((i) => i !== input)];
+  };
+
+  /** returns 1 FilterFn's */
+  const greaterThan = <V extends number>(n: V) => {
+    const val = [(input?: V) => input !== undefined && input > n] as [(input: V) => boolean];
+    return val as [ConditionFilter<NumericFilter>];
+  };
+
+  /** returns 0 or 1 FilterFn's */
+  const lessThan = <V extends number>(n: V) => {
+    const val = [(input: V) => input !== undefined && input < n];
+    return val as [ConditionFilter<NumericFilter>] | [];
+  };
+
+  const conditions = [
+    //
+    ...("equals" in config ? equals(config.equals) : []),
+    ...("notEqual" in config ? notEqual(config.notEqual) : []),
+    ...("greaterThan" in config ? greaterThan(config.greaterThan) : []),
+    ...("lessThan" in config ? lessThan(config.lessThan) : []),
+  ];
+
+  const combined =
+    boolLogic === "AND"
+      ? <N extends number>(input: N) => conditions.every((c) => c(input))
+      : <N extends number>(input: N) => conditions.some((c) => c(input));
+
+  return combined;
+};
+
+/** wraps configuration along with boolean logic  */
+const stringOps = <L extends LogicalCombinator>(
+  config: StringFilter,
+  boolLogic: L
+): ConditionFilter<StringFilter> => {
+  const startsWith = (n: string | string[]): [ConditionFilter<StringFilter>] | [] => {
+    const f = asArray(n);
+    return f.length === 0 ? [] : [(input?: string) => f.some((i) => input?.startsWith(i))];
+  };
+  const endsWith = (n: string | string[]): [ConditionFilter<StringFilter>] | [] => {
+    const f = asArray(n);
+    return f.length === 0 ? [] : [(input?: string) => f.some((i) => input?.endsWith(i))];
+  };
+  const contains = (n: string | string[]): [ConditionFilter<StringFilter>] | [] => {
+    const f = asArray(n);
+    return f.length === 0 ? [] : [(input: string) => f.some((i) => input?.includes(i))];
+  };
+
+  const conditions = [
+    ...("startsWith" in config ? startsWith(config.startsWith) : []),
+    ...("endsWith" in config ? endsWith(config.endsWith) : []),
+    ...("contains" in config ? contains(config.contains) : []),
+  ];
+
+  const combined =
+    boolLogic === "AND"
+      ? (input: string) => conditions.every((c) => c(input))
+      : (input: string) => conditions.some((c) => c(input));
+
+  return combined as ConditionFilter<StringFilter>;
+};
+
+const filterFn = <
+  F extends FilterDefn | NotFilter,
+  C extends LogicalCombinator,
+  U extends boolean | "no-impact"
+>(
+  defn: F,
+  logicCombinator: C,
+  ifUndefined: U = "no-impact" as U
+): FilterFn<UnwrapNot<F>> => {
+  type D = UnwrapNot<F>;
+  const config: D = isNotFilter(defn) ? (defn["not"] as D) : (defn as D);
+
+  const filter: FilterFn<D> = (
+    //
+    input: Parameters<FilterFn<D>>[0]
+  ) => {
+    const undefValue =
+      ifUndefined === "no-impact"
+        ? logicCombinator === "AND"
+          ? true
+          : false
+        : (ifUndefined as true | false);
+
+    let flag: boolean;
+
+    if (typeof input === "undefined") {
+      flag = undefValue;
+    } else if (isNumericFilter(config)) {
+      const fn = numericOps(config, logicCombinator);
+      flag = isNotFilter(defn) ? !fn(input as number) : fn(input as number);
+    } else {
+      const fn = stringOps(config, logicCombinator);
+      flag = isNotFilter(defn) ? !fn(input as string) : fn(input as string);
+    }
+
+    return flag;
+  };
+
+  return filter;
+};
+
+/**
+ * **filter**
+ *
+ * A higher order helper utility which builds a boolean _filter_ function based on a simple
+ * configuration object. Support either _string_ or _numeric_ filters.
+ *
+ * ```ts
+ * const str = filter({startsWith: ["_", "."], endsWith: ".md"});
+ * const num = filter({ greaterThan: 55, notEqual: [66, 77]});
+ * ```
+ *
+ * All conditions (e.g., `startsWith`, `contains`, `notEqual`, etc.) that a particular filter
+ * is defined as having -- if there is more than one -- will be logically combined using AND
+ * unless specified otherwise in the third parameter.
+ *
+ * How a value of _undefined_ will be treated is stated in the second parameter but defaults
+ * to "no-impact" which means it's `false` when the logicCombinator is OR but defaults
+ * to `true` when the logicCombinator is AND.
+ */
+export const filter = <
+  F extends FilterDefn | NotFilter,
+  U extends boolean | "no-impact",
+  C extends LogicalCombinator
+>(
+  config: F,
+  logicCombinator: C = "AND" as C,
+  ifUndefined: U = "no-impact" as U
+) => {
+  return filterFn(config, logicCombinator, ifUndefined);
+};

package/src/utility/boolean-logic/index.ts

@@ -0,0 +1,4 @@
+export * from "./and";
+export * from "./or";
+export * from "./not";
+export * from "./filter";

package/src/utility/boolean-logic/not.ts

@@ -0,0 +1,15 @@
+import { LogicFunction } from "src/types/functions";
+
+/**
+ * Groups a number of "logic functions" together by combining their results using
+ * the logical **NOT** operator.
+ *
+ * **Note:** a "logic function" is any function which returns a boolean
+ */
+export const not = <T extends any[]>(op: LogicFunction<T>): LogicFunction<T> => {
+  const fn: LogicFunction<T> = (...args: T) => {
+    return !op(...args);
+  };
+
+  return fn;
+};

package/src/utility/boolean-logic/or.ts

@@ -0,0 +1,15 @@
+import { LogicFunction } from "src/types/functions";
+
+/**
+ * Groups a number of "logic functions" together by combining their results using
+ * the logical **OR** operator.
+ *
+ * **Note:** a "logic function" is any function which returns a boolean
+ */
+export const or = <T extends any[]>(...ops: LogicFunction<T>[]): LogicFunction<T> => {
+  const fn: LogicFunction<T> = (...args: T) => {
+    return [...ops].some((i) => i(...args));
+  };
+
+  return fn;
+};

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/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];
+  });
+});

package/src/utility/map-reduce/filter.ts

@@ -1,35 +0,0 @@
-// inspired by [article](https://medium.com/@reidev275/creating-a-type-safe-dsl-for-filtering-in-typescript-53fe68a7942e)]
-
-
-export type Filter<A> =
-  | { kind: "Equals"; field: keyof A; val: A[keyof A] }
-  | { kind: "Greater"; field: keyof A; val: A[keyof A] }
-  | { kind: "Less"; field: keyof A; val: A[keyof A] }
-  | { kind: "And"; a: Filter<A>; b: Filter<A> }
-  | { kind: "Or"; a: Filter<A>; b: Filter<A> };
-
-export const equals = <A, K extends keyof A>(field: K, val: A[K]): Filter<A> => ({
-  kind: "Equals",
-  field,
-  val
-});
-export const greater = <A, K extends keyof A>(field: K, val: A[K]): Filter<A> => ({
-  kind: "Greater",
-  field,
-  val
-});
-export const less = <A, K extends keyof A>(field: K, val: A[K]): Filter<A> => ({
-  kind: "Less",
-  field,
-  val
-});
-export const and = <A>(a: Filter<A>, b: Filter<A>): Filter<A> => ({
-  kind: "And",
-  a,
-  b
-});
-export const or = <A>(a: Filter<A>, b: Filter<A>): Filter<A> => ({
-  kind: "Or",
-  a,
-  b
-});

package/src/utility/map-reduce/index.ts

@@ -1,12 +0,0 @@
-// #autoindex
-// #region auto-indexed files
-// index last changed at: 8th Aug, 2022, 09:51 AM ( GMT-7 )
-// hash-code: 5ffc538b
-
-// file exports
-export * from "./filter";
-
-// #endregion auto-indexed files
-
-// see https://github.com/inocan-group/do-devops/docs/autoindex.md
-// for more info