inferred-types 0.25.0 → 0.27.0

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/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

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