inferred-types 0.51.1 → 0.51.2

package/src/types/lists/FilterByProp.ts

@@ -1,87 +0,0 @@
-import {
-  ComparatorOperation,
-  Compare,
-  IfNever,
-  RemoveNever,
-  IsDotPath,
-  Throw,
-  Get,
-} from "inferred-types/dist/types/index";
-
-
-/**
- * Iterates over each element of the Tuple
- */
-type SingleFilter<
-  TList extends readonly unknown[],
-  TComparator,
-  TProp extends string,
-  TOp extends ComparatorOperation,
-  Result extends unknown[] = []
-> = TList extends [infer Head, ...infer Rest]
-  ? [
-      Compare<
-        Get<Head, TProp>,
-        TOp,
-        TComparator
-      >
-    ] extends [true]
-    ? SingleFilter<Rest, TComparator, TProp, TOp, Result> // filter out
-    : SingleFilter<Rest, TComparator, TProp, TOp, [...Result, Head]>
-  : Result;
-
-
-
-type Process<
-  TList extends readonly unknown[],
-  TComparator,
-  TProp extends string,
-  TOp extends ComparatorOperation
-> =  TList extends unknown[]
-? SingleFilter<TList, TComparator, TProp, TOp>
-: // readonly only tuples
-  TList extends readonly unknown[]
-    ? Readonly<
-        SingleFilter<[...TList], TComparator, TProp, TOp>
-      >
-    : never;
-
-/**
- * **FilterByProp**`<TList, TComparator, TProp, [TOp]>`
- *
- * Allows a known tuple `TList` to be reduced to a subset with the value `TComparator`
- * being compared to each element in TList[TProp]; if comparison resolves to a `true`
- * value then the element `TList[TProp]` is removed but otherwise retained.
- *
- * - How the list is _compared_ depends on `TOp` which defaults to "extends"
- * - other values include "equals", "does-not-extend", "does-not-equal"
- *
- * **Related:** `RetainByProp`, `Filter`, `RetainFromList`, `RemoveFromList`, `FilterProps`
- */
-export type FilterByProp<
-  TList extends readonly unknown[],
-  TComparator,
-  TProp extends string,
-  TOp extends ComparatorOperation = "extends"
-> = IsDotPath<TProp> extends false
-? Throw<"invalid-dot-path", `the property value TProp must be a valid dotpath but "${TProp}" is not valid!`>
-
-: TList extends readonly unknown[]
-? IfNever<
-    TComparator,
-    RemoveNever<TList>,
-    TComparator extends any[]
-      ? Process<
-          TList,
-          TComparator[number],
-          TProp,
-          TOp
-        >
-      : Process<
-          TList,
-          TComparator,
-          TProp,
-          TOp
-        >
-    >
-: never;

package/src/types/lists/FilterLiterals.ts

@@ -1,29 +0,0 @@
-import { Constant } from "inferred-types/dist/constants/index";
-import { IsLiteral, RemoveMarked } from "inferred-types/dist/types/index";
-
-
-type Process<
-T extends readonly unknown[]
-> = RemoveMarked<{
-  [K in keyof T]: IsLiteral<T[K]> extends true
-    ? Constant<"Marked">
-    : T[K]
-}>
-
-
-/**
- * **FilterLiterals**`<T>`
- *
- * Receives a tuple of items and filters out all literal items
- * (e.g., object literals, tuple literals, string literals,
- * numeric literals, and boolean literals).
- *
- * Elements like _undefined_ and `null` are kept in the tuple.
- *
- * **Related:** `Filter`, `FilterWideTypes`, `RetainLiterals`
- */
-export type FilterLiterals<
-  T extends readonly unknown[]
-> = Process<T> extends readonly unknown[]
-? Process<T>
-: never;

package/src/types/lists/FilterWideTypes.ts

@@ -1,24 +0,0 @@
-import { Constant } from "inferred-types/dist/constants/index";
-import { IsWideType } from "../boolean-logic";
-import { If } from "../boolean-logic/branching/If";
-import { RemoveMarked } from "../containers";
-
-/**
- * **FilterWideTypes**`<T>`
- *
- * Receives a tuple of items and filters out all "wide types"
- * (e.g., object, number, string, Record<string, string>, boolean, etc.).
- *
- * All literal types and elements such as _undefined_ and `null` are kept in the tuple.
- *
- * **Related:** `Filter`, `FilterLiterals`, `RetainWideTypes`
- */
-export type FilterWideTypes<
-  T extends readonly unknown[]
-> = RemoveMarked<{
-  [K in keyof T]: If<
-    IsWideType<T[K]>,
-    Constant<"Marked">,
-    T[K]
-  >
-}>

package/src/types/lists/Find.ts

@@ -1,52 +0,0 @@
-import { IsEqual, If, AfterFirst, First, Or, NumberLike, Compare } from "inferred-types/dist/types/index";
-
-type FindAcc<
-  TList extends readonly unknown[],
-  TOp extends "extends" | "equals" | "startsWith" | "endsWith" | "lessThan" | "greaterThan",
-  TComparator,
-  TDeref extends string | number | null
-> = [] extends TList
-  ? undefined
-  : TDeref extends keyof First<TList>
-    ? If<
-        Compare<First<TList>[TDeref], TOp, TComparator>,
-        First<TList>,
-        FindAcc<AfterFirst<TList>, TOp,TComparator, TDeref>
-      >
-    : If<
-        Compare<First<TList>, TOp, TComparator>,
-        First<TList>,
-        FindAcc<AfterFirst<TList>, TOp,TComparator, TDeref>
-      >;
-
-/**
- * **Find**`<TList,TOp,TComparator,[TDeref]>`
- *
- * Type utility used to find the first value in `TList` which _equals_ `TValue`.
- * Will return _undefined_ if no matches found.
- *
- * - use **FindExtends** if you want a more permissive match
- * - by default, values in `TList` will be compared directly but you can _dereference_
- * array and object properties with `TIndex` if you want to compare on a child property
- *
- * ```ts
- * type List = [ { id: 1, value: "hi" }, { id: 2, value: "bye" } ]
- * // { id: 1; value: "hi" }
- * type T = Find<List, 1, "id">
- * ```
- *
- * **Related**: `FindExtends`
- */
-export type Find<
-  TList extends readonly unknown[],
-  TOp extends "extends" | "equals" | "startsWith" | "endsWith" | "lessThan" | "greaterThan",
-  TComparator extends Or<[
-    IsEqual<TOp,"startsWith">, IsEqual<TOp,"endsWith">,
-  ]> extends true
-  ? string
-  : Or<[IsEqual<TOp,"lessThan">, IsEqual<TOp,"greaterThan">]> extends true
-  ? NumberLike
-  : unknown,
-  TDeref extends string | number | null = null,
-> = FindAcc<TList, TOp, TComparator, TDeref>;
-

package/src/types/lists/First.ts

@@ -1,21 +0,0 @@
-
-
-/**
- * **First**`<T>`
- * 
- * Returns the _first_ type in a list. If `TElse` is provided it will set 
- * the type to `TElse` when:
- * - `T` is a Tuple type
- * - `T[1]` is not a valid index of `T`
- * - by default `TElse` is set to _never_
- * 
- * **Related:** `Second`, `Last`
- */
-export type First<
-  T,
-  ELSE = never
-> = T extends readonly unknown[]
-  ? T[0] extends T[number] ? T[0] : ELSE
-  : never;
-
-

package/src/types/lists/FirstOrElse.ts

@@ -1,15 +0,0 @@
-import { Tuple, First} from "inferred-types/dist/types/index";
-
-
-/**
- * **FirstOrElse**`<T,E>`
- *
- * Returns the _first_ type in a list but if there are no elements then
- * it will return `E` (which defaults to _undefined_).
- */
-export type FirstOrElse<
-  T extends Tuple,
-  E = undefined
-> = T extends Tuple<unknown, "1+">
-  ? First<T>
-  : E;

package/src/types/lists/FirstString.ts

@@ -1,7 +0,0 @@
-/**
- * Returns the first `string` value from an array of values
- */
-export type FirstString<T extends readonly unknown[]> = 
-T extends [infer S, ...unknown[]]
-  ? S extends string ? S : never
-  : never;

package/src/types/lists/Flatten.ts

@@ -1,149 +0,0 @@
-/* eslint-disable no-use-before-define */
-import {
-  AfterFirst,
-  First,
-  IsUnion,
-  UnionToTuple,
-  TupleToUnion,
-  IsTuple,
-  Or,
-  Decrement,
-  HasUnionType,
-  HasArray,
-  IsArray,
-  As,
-  UnionHasArray
-} from "inferred-types/dist/types/index";
-
-type ToFlat<T> = IsArray<T> extends true
-? As<T, readonly unknown[]>
-: IsUnion<T> extends true
-  ? UnionHasArray<T> extends true
-    ? [FlattenUnion<T>]
-    : [T]
-: [T];
-
-
-type FlatPass<
-  TList extends readonly unknown[],
-  TResult extends readonly unknown[] = []
-> = [] extends TList
-? TResult
-: FlatPass<
-    AfterFirst<TList>,
-    [
-      ...TResult,
-      ...ToFlat<First<TList>>
-    ]
-  >;
-
-
-/**
- * Processes Tuple structures.
- *
- * - Each pass will start by validating that `TList` still has
- * either Tuples within it or values which are Tuples
- * - Assuming it does
- */
-type FlattenTuple<
-  TList extends readonly unknown[],
-  TLevel extends 0 | 1 | 2 | 3,
-> = TLevel extends 0
-? TList // we've processed the agreed number of levels
-: Or<[ HasUnionType<TList>, HasArray<TList>  ]> extends true
-  ? FlattenTuple<
-      FlatPass<TList>,
-      Decrement<TLevel>
-    >
-  : TList;
-
-
-type Iterate<
-  T extends readonly unknown[],
-  TDepth extends 1 | 2 | 3
-> = TupleToUnion<{
-  [K in keyof T]: T[K] extends readonly unknown[]
-    ? Flatten<T[K], TDepth>
-    : T[K]
-}>;
-
-export type FlattenUnion<
-  TValue,
-> = IsUnion<TValue> extends true
-? Iterate<UnionToTuple<TValue>, 1>
-: TValue;
-
-type WideFlatten<T> = T extends (infer Type)[]
-  ? Type extends unknown[]
-    ? Type
-    : T
-  : never
-
-/**
- * Responsible for branching the flattening operation
- * to either `_Flat`, `WideFlatten` for Tuples or Arrays
- * and `FlattenUnion` for a union type.
- *
- * Just returns `TList` "as is" if it's not a a Tuple or
- * Union type.
- */
-type Process<
-  TList,
-  TLevel extends 1 | 2 | 3 = 1
-> = TList extends readonly unknown[]
-? IsTuple<TList> extends true
-? FlattenTuple<TList, TLevel>
-: WideFlatten<TList>
-: IsUnion<TList> extends true
-? FlattenUnion<TList>
-: TList;
-
-/**
- * converts a wide array to a scalar and tuple
- * to a union type
- */
-type ToScalar<
-  TList,
-  TLevel extends 1 | 2 | 3
-> = [IsTuple<Process<TList>>] extends [true]
-? TupleToUnion<Process<TList,TLevel>>
-: Process<TList,TLevel> extends (infer Type)[]
-  ? Type
-  : never;
-
-type IterateScalar<
-  T extends readonly unknown[],
-  TLevel extends 1 | 2 | 3
-> = TupleToUnion<{
-  [K in keyof T]: T[K] extends unknown[]
-    ? ToScalar<T[K], TLevel>
-    : T[K]
-}>;
-
-/**
- * **Flatten**`<TList, [TLevel], [ToScalar]>`
- *
- * - where `TList` is an array, this utility will flatten the array to a depth of
- * `TLevel` (by default one level).
- * - where `TList` is a _union type_ it will flatten any of it's elements
- * - where `TList is neither an array nor has a union type which is, this utility
- * simply proxies the value `TList` through
- * - in most cases you would not _flatten_ below a single dimensional array but
- * if you set `ToScalar` to `true` then it will flatten right out of being an array
- * into a union type
- */
-export type Flatten<
-  TList,
-  TLevel extends 1 | 2 | 3 = 1,
-  ToScalar extends boolean = false
-> = [ToScalar] extends [false]
-? // normal operation when ToScalar is false
-  Process<TList,TLevel>
-: // prep work when ToScalar is activated
-  [IsUnion<Process<TList,TLevel>>] extends [true]
-  ? IterateScalar<UnionToTuple<Process<TList,TLevel>>, TLevel>
-  :  [IsTuple<Process<TList,TLevel>>] extends [true]
-  ? TupleToUnion<Process<TList,TLevel>>
-  : Process<TList,TLevel> extends (infer Type)[]
-    ? Type
-    : never

package/src/types/lists/GetEach.ts

@@ -1,62 +0,0 @@
-
-import {
-  Get,
-  IsReadonlyArray,
-  IsValidDotPath,
-  IndexOf,
-  Mutable,
-  RemoveNever,
-  TypedFunction,
-  FnProps,
-} from "inferred-types/dist/types/index";
-/**
- * extract props from functions
- */
-type F<T> = T extends TypedFunction
-  ? FnProps<T>
-  : T;
-
-type Process<
-  TList extends readonly unknown[],
-  TKey extends string
->= RemoveNever<{
-  [K in keyof TList]: [TKey] extends [keyof F<TList[K]>]
-    ? [IndexOf<F<TList[K]>, TKey>] extends [undefined]
-      ? never
-      : IndexOf<F<TList[K]>, TKey>
-    : [IsValidDotPath<F<TList[K]>, TKey>] extends [true]
-      ? Mutable<Get<F<TList[K]>, TKey, never>> // valid
-  :  never // TKey does not extends TList[K]
-}>;
-
-
-/**
-* **GetEach**`<TList, TKey, [THandleErrors]>`
-*
-* Type utility which receives a list of types -- `TList` -- and then _gets_ a
-* key `TKey` (using dot syntax) from each element in the array.
-*
-* - if a given element is not an object then it is excluded from the result set
-* - values which evaluate to _undefined_ are also removed from the result set
-* - if either `null` or "" are used for `TKey` then this simply proxies `TList`
-* through
-*
-* ```ts
-* // ["Bob", "Wendy"]
-* type T = GetEach<[
-*    { name: "Bob", age: 12 },
-*    { name: "Wendy", age: 24 }
-* ], "name">
-* ```
-*/
-export type GetEach<
-  TList extends readonly unknown[],
-  TKey extends string | null,
-> = TKey extends null
-? TList
-: TKey extends ""
-? TList
-: IsReadonlyArray<TList> extends true
-  ? Readonly<Process<[...TList], Exclude<TKey, null>>>
-  : Process<TList, Exclude<TKey, null>>;
-

package/src/types/lists/IndexOf.ts

@@ -1,151 +0,0 @@
-import {
-  IsNull,
-  IsNegativeNumber,
-  Abs,
-  Decrement,
-  Reverse,
-  ToString,
-  Dictionary,
-  ObjectKey,
-  If,
-  AsString,
-  IsValidIndex,
-  AsPropertyKey,
-  Throw,
-  ErrorCondition,
-  Concat
-} from "inferred-types/dist/types/index";
-import { Constant } from "inferred-types/dist/constants/index";
-
-type Override<
-  TValue,
-  TOverride
-> = TOverride extends Constant<"no-override">
-? TValue
-: TValue extends ErrorCondition<"invalid-index">
-  ? TOverride
-  : TValue;
-
-type NegativeIndex<
-  TValue extends readonly unknown[],
-  TIdx extends number
-> = Decrement<Abs<TIdx>> extends number
-  ? If<
-      IsValidIndex<TValue, Decrement<Abs<TIdx>>>,
-      TValue[Decrement<Abs<TIdx>>],
-      Throw<
-        "invalid-index",
-        `Use of a negative index [${AsString<TIdx>}] was unsuccessful in matching a valid index`,
-        "IndexOf",
-        {
-          container: TValue;
-          key: TIdx;
-          context: {
-            revIndex: Decrement<Abs<TIdx>>;
-            revContainer: Reverse<TValue>;
-          };
-        }
-      >
-    >
-  : never;
-
-
-type HandleArr<
-  TValue extends readonly unknown[],
-  TIdx extends PropertyKey
-> = TIdx extends number
-? IsNegativeNumber<TIdx> extends true
-  ? NegativeIndex<Reverse<TValue>,TIdx>
-  : If<
-      IsValidIndex<TValue,TIdx>,
-      TValue[TIdx],
-      Throw<
-        "invalid-index",
-        Concat<["Attempt to index [", ToString<TIdx>, "] into a non-container type!"]>,
-        "IndexOf",
-        { container: TValue; key: TIdx; library: "inferred-types" }
-      >
-    >
-: Throw<
-    "invalid-index",
-    `IndexOf<Tuple,${AsString<TIdx>}> failed because a tuple container must use numeric indexes!`,
-    "IndexOf",
-    { container: TValue; key: TIdx; library: "inferred-types" }
-  >;
-
-type HandleObj<
-TValue extends Dictionary,
-TIdx extends PropertyKey
-> = TIdx extends keyof TValue
-? TValue[TIdx]
-: Throw<
-  "invalid-index",
-  Concat<["Attempt to index [", ToString<TIdx>, "] into a non-container type!"]>,
-  "IndexOf",
-  { container: TValue; key: TIdx; library: "inferred-types" }
->;
-
-type Process<
-TValue,
-TIdx extends PropertyKey | null
-> = If<
-IsNull<TIdx>,
-// return "as is"
-TValue,
-// dereference where valid index
-TValue extends readonly unknown[]
-  ? If<
-      IsValidIndex<TValue, AsPropertyKey<TIdx>>,
-      HandleArr<TValue, AsPropertyKey<TIdx>>,
-      Throw<
-      "invalid-index",
-        `Call to IndexOf<DescribeType<TValue>,${AsString<TIdx>}> is not allowed as an tuple based container must receive either null or numeric index value.`,
-        "IndexOf",
-        { library: "inferred-types"; container: TValue; key: TIdx }
-      >
-    >
-  : TValue extends Dictionary
-    ? TIdx extends ObjectKey
-      ? HandleObj<TValue,TIdx>
-      : Throw<
-          "invalid-index",
-          `Call to IndexOf<DescribeType<TValue>,${AsString<TIdx>}> is not allowed as an object based container must receive either null, a string, or a symbol index value.`,
-          "IndexOf",
-          {library: "inferred-types"; container: TValue; key: TIdx }
-        >
-    : Throw<
-        "invalid-index",
-        `IndexOf<ToString<TValue>},${AsString<TIdx>}> was called but the a non-null value was used to index a non-container which will never work!`,
-        "IndexOf",
-        { library: "inferred-types"; container: TValue; key: TIdx }
-      >
->;
-
-
-
-/**
- * **IndexOf**<TValue, TIdx, [TOverride]>
- *
- * A type utility which _dereferences_ a property/index item on an array
- * or object.
- *
- * - if `TIdx` is passed in as `null` then this will act as an identity
- * function and return `TValue`.
- * - if `TIdx` is a negative number it will index in reverse for tuple based
- * containers
- *
- * **Related:** `Get`, `IsValidIndex`
- *
- * **Errors:** produces an `ErrorCondition<"invalid-index">` when an a bad index value
- * is passed in for the given container
- */
-export type IndexOf<
-  TValue,
-  TIdx extends PropertyKey | null,
-  TOverride = Constant<"no-override">
-> = TIdx extends null
-? TValue
-: Override<
-    Process<TValue,TIdx>,
-    TOverride
-  >

package/src/types/lists/Intersect.ts

@@ -1,19 +0,0 @@
-import { Tuple } from "../base-types";
-import { AfterFirst } from "./AfterFirst";
-import { First } from "./First";
-
-type Process<
-  TTup extends Tuple,
-  TResult = First<TTup>
-> = [] extends TTup
-? TResult
-: Process<AfterFirst<TTup>, TResult & First<TTup>>
-
-/**
- * **Intersect**`<TList>`
- *
- * Intersects all items in the list.
- *
- * **Related:** `Intersection`, `IntersectAll`
- */
-export type Intersect<TList extends Tuple> = Process<TList>;

package/src/types/lists/IntersectAll.ts

@@ -1,26 +0,0 @@
-import { ExpandRecursively, Narrowable, AfterFirst, First } from "inferred-types/dist/types/index";
-
-type Intersect<
-  TList extends readonly unknown[],
-  TIntersect extends Narrowable,
-  TResults extends unknown[] = []
-> = [] extends TList
-  ? TResults
-  : Intersect<
-      AfterFirst<TList>,
-      TIntersect,
-      [...TResults, ExpandRecursively<First<TList> & TIntersect> ]
-    >;
-
-/**
- * **IntersectAll**`<TList, TIntersect>`
- *
- * Type utility which adds an _intersection_ with each element in `TList`
- * with `TIntersect`.
- */
-export type IntersectAll<
-  TList extends readonly unknown[],
-  TIntersect extends Narrowable
-> = TList extends readonly unknown[]
-? Readonly<Intersect<TList, TIntersect>>
-: [...Intersect<TList, TIntersect>];

package/src/types/lists/Last.ts

@@ -1,29 +0,0 @@
-import { AfterFirst, IfLength,  Tuple } from "inferred-types/dist/types/index";
-
-/**
- * **Last**`<TList, [TEmpty]>`
- *
- * Returns the _last_ element in a list of elements.
- *
- * - by default `TEmpty` is _never_ but this can be changed.
- */
-export type Last<
-  TContent extends Tuple,
-  TEmpty = never
-> = IfLength<
-  TContent, 1,
-  // If only one array element then return it
-  TContent[0],
-  IfLength<
-    TContent, 0,
-    // no array element results in `never` type
-    TEmpty,
-    // otherwise
-    AfterFirst<TContent> extends readonly unknown[]
-      ? TContent[AfterFirst<TContent>["length"]] extends TContent[number]
-        ? TContent[AfterFirst<TContent>["length"]]
-        : TEmpty
-      : TEmpty
-  >
->;
-