inferred-types 0.24.3 → 0.26.0

package/src/types/TypeInfo/IsNumericLiteral.ts

@@ -0,0 +1,7 @@
+/**
+ * **IsNumericLiteral**
+ *
+ * Type utility which returns true/false if the numeric value a _numeric literal_ versus
+ * just the _number_ type.
+ */
+export type IsNumericLiteral<T extends number> = number extends T ? false : true;

package/src/types/TypeInfo/IsStringLiteral.ts

@@ -0,0 +1,7 @@
+/**
+ * **IsStringLiteral**
+ *
+ * Type utility which returns true/false if the string a _string literal_ versus
+ * just the _string_ type.
+ */
+export type IsStringLiteral<T extends string> = string extends T ? false : true;

package/src/types/TypeInfo/index.ts

@@ -0,0 +1,5 @@
+export * from "./Includes";
+export * from "./IsBooleanLiteral";
+export * from "./IsNumericLiteral";
+export * from "./IsStringLiteral";
+export * from "./IsLiteral";

package/src/types/functions/LogicFunction.ts

@@ -0,0 +1,4 @@
+/**
+ * A function which returns a boolean value
+ */
+export type LogicFunction<T extends any[]> = (...args: T) => boolean;

package/src/types/functions/index.ts

@@ -5,6 +5,7 @@
 
 // file exports
 export * from "./FinalReturn";
+export * from "./LogicFunction";
 
 // #endregion auto-indexed files
 

package/src/types/index.ts

@@ -12,7 +12,6 @@ export * from "./First";
 export * from "./FunctionType";
 export * from "./If";
 export * from "./Include";
-export * from "./Includes";
 export * from "./KeyedRecord";
 export * from "./Keys";
 export * from "./Length";
@@ -41,6 +40,7 @@ export * from "./lists/index";
 export * from "./string-literals/index";
 export * from "./tuples/index";
 export * from "./type-conversion/index";
+export * from "./TypeInfo/index";
 
 // #endregion auto-indexed files
 

package/src/utility/boolean-logic/and.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 **AND** operator.
+ *
+ * **Note:** a "logic function" is any function which returns a boolean
+ */
+export const and = <T extends any[]>(...ops: readonly LogicFunction<T>[]): LogicFunction<T> => {
+  const fn: LogicFunction<T> = (...args: T) => {
+    return [...ops].every((i) => i(...args));
+  };
+
+  return fn;
+};

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/Includes-spec.ts

@@ -1,15 +1,36 @@
 import { describe, it, expect } from "vitest";
 
 import type { Includes } from "../src/types";
-import type { ExpectTrue, ExpectFalse } from "@type-challenges/utils";
+import type { Equal, Expect } from "@type-challenges/utils";
 
 describe("Includes type check", () => {
-  it("Includes tests whether string is contained within the string array", () => {
+  it("Includes works on a string source", () => {
+    type T = Includes<"Hello World", "Hello">;
+    type F = Includes<"Hello World", "nada">;
+    type U = Includes<string, "who cares">;
+    type N = Includes<"Hello World", string>;
     type cases = [
-      ExpectTrue<Includes<["foo", "bar", "baz"], "foo">>,
-      ExpectFalse<Includes<["foo", "bar", "baz"], "nada">>
+      Expect<Equal<T, true>>, //
+      Expect<Equal<F, false>>,
+      Expect<Equal<U, boolean>>,
+      Expect<Equal<N, boolean>>
     ];
-    const typeTests: cases = [true, false];
+    const typeTests: cases = [true, true, true, true];
+    expect(typeTests).toBe(typeTests);
+  });
+
+  it("Includes works on a string[] source", () => {
+    type T = Includes<["Hello", "World"], "Hello">;
+    type F = Includes<["Hello", "World"], "nada">;
+    type U = Includes<string[], "who cares">;
+    type N = Includes<["Hello", "World"], string>;
+    type cases = [
+      Expect<Equal<T, true>>, //
+      Expect<Equal<F, false>>,
+      Expect<Equal<U, boolean>>,
+      Expect<Equal<N, boolean>>
+    ];
+    const typeTests: cases = [true, true, true, true];
     expect(typeTests).toBe(typeTests);
   });
 });

package/tests/TypeInfo/IsLiteral.spec.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { Equal, Expect } from "@type-challenges/utils";
+import { IsBooleanLiteral, IsLiteral } from "src/types";
+
+describe("IsLiteral<T> type utility", () => {
+  it("string values", () => {
+    const s = "hi" as string;
+    const sl = "hi" as const;
+
+    type cases = [
+      Expect<Equal<IsLiteral<typeof s>, false>>,
+      Expect<Equal<IsLiteral<typeof sl>, true>>
+    ];
+    const cases: cases = [true, true];
+    expect(typeof s).toBe("string");
+    expect(typeof sl).toBe("string");
+  });
+
+  it("numeric values", () => {
+    const v = 42 as number;
+    const vl = 42 as const;
+
+    type cases = [
+      Expect<Equal<IsLiteral<typeof v>, false>>,
+      Expect<Equal<IsLiteral<typeof vl>, true>>
+    ];
+    const cases: cases = [true, true];
+
+    expect(typeof v).toBe("number");
+    expect(typeof vl).toBe("number");
+  });
+
+  it("boolean values", () => {
+    const v = true as boolean;
+    const vl = false as const;
+
+    type cases = [
+      // wide
+      Expect<Equal<IsBooleanLiteral<typeof v>, false>>,
+      Expect<Equal<IsLiteral<typeof v>, false>>,
+      // literal
+      Expect<Equal<IsBooleanLiteral<typeof vl>, true>>,
+      Expect<Equal<IsLiteral<typeof vl>, true>>
+    ];
+    const cases: cases = [true, true, true, true];
+    expect(typeof v).toBe("boolean");
+    expect(typeof vl).toBe("boolean");
+  });
+});

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