inferred-types 0.35.0 → 0.36.1

package/src/runtime/type-checks/isString.ts

@@ -27,7 +27,7 @@ export function isString<T>(i: T) {
  */
 export function ifString<T extends Narrowable, IF extends Narrowable, ELSE extends Narrowable>(
   val: T,
-  ifVal: IF,
+  ifVal: <E extends string>(t: E & T) => IF,
   elseVal: ELSE
 ) {
   return (isString(val) ? ifVal : elseVal) as IfString<T, IF, ELSE>;

package/src/runtime/type-checks/isUndefined.ts

@@ -23,3 +23,11 @@ export function ifUndefined<T extends Narrowable, IF extends Narrowable, ELSE ex
 ) {
   return (isUndefined(val) ? ifVal : elseVal) as IsUndefined<T> extends true ? IF : ELSE;
 }
+
+export function ifDefined<T extends Narrowable, IF extends Narrowable, ELSE extends Narrowable>(
+  val: T,
+  ifVal: <V extends Exclude<T, undefined>>(v: V) => IF,
+  elseVal: ELSE
+) {
+  return (isUndefined(val) ? ifVal : elseVal) as IsUndefined<T> extends true ? IF : ELSE;
+}

package/src/types/alphabetic/EnsureLeading.ts

@@ -0,0 +1,24 @@
+import { IfLiteral } from "../boolean-logic/IsLiteral";
+
+/**
+ * **EnsureLeading**`<T, U>`
+ *
+ * Will ensure that `T` ends with the _substring_ `U` when
+ * both are string literals.
+ *
+ * ```ts
+ * type T = " World";
+ * type U = "Hello";
+ * // "Hello World"
+ * type R = EnsureLeading<T,U>;
+ * ```
+ */
+export type EnsureLeading<T extends string, U extends string> = IfLiteral<
+  // can only operate on literal strings
+  T,
+  // this path represents successful strip opp
+  // but we must never accept `U` being wide
+  string extends U ? never : T extends `${U}${string}` ? T : `${U}${T}`,
+  // here we must stay wide
+  string
+>;

package/src/types/alphabetic/EnsureTrailing.ts

@@ -0,0 +1,24 @@
+import { IfLiteral } from "../boolean-logic/IsLiteral";
+
+/**
+ * **EnsureTrailing**`<T, U>`
+ *
+ * Will ensure that `T` ends with the substring `U` when
+ * both are string literals.
+ *
+ * ```ts
+ * type T = "Hello";
+ * type U = " World";
+ * // "Hello World"
+ * type R = EnsureTrailing<T,U>;
+ * ```
+ */
+export type EnsureTrailing<T extends string, U extends string> = IfLiteral<
+  // can only operate on literal strings
+  T,
+  // this path represents successful strip opp
+  // but we must never accept `U` being wide
+  string extends U ? never : T extends `${string}${U}` ? T : `${T}${U}`,
+  // here we must stay wide
+  string
+>;

package/src/types/alphabetic/PathJoin.ts

@@ -1,40 +1,52 @@
 import { IfLiteral } from "../boolean-logic";
-import { StripEnding } from "./StripEnding";
-import { StripStarting } from "./StripStarting";
+import { AfterFirst, First } from "../lists";
+import { StripTrailing } from "./StripTrailing";
+import { StripLeading } from "./StripLeading";
+
 /**
  * **PathJoin**`<T,U>`
  *
- * Type utility which joins two strings together with the
- * goal of making it a valid file or URI path (based on the
- * Posix standard for file paths).
+ * Type utility meant to bring 2 or more "path" strings together into
+ * a valid "path". Where a "path" is represented as nothing more than
+ * string characters delimited by a Posix `\` character.
  *
- * Primarily, this means that it ensures that both `T` and `U`
- * are separated by a single `/` character. Of course if either
- * `T` or `U` are _wide_ string types then the resulting type
- * will be more limited.
- *
- * **Note:** that in the case that both `T` and `U` are wide,
- * we opt to type the result as just a _string_ rather than
- * `${string}/${string}` which might be more precise 99% of
- * the time but where `T` is an empty string there actually
- * is no guarantee of a `/` character. Similarly we must
- * type the case where `U` is narrow but `T` is wide as
- * being `${string}${U}` instead of `${string}/${U}`.
+ * Note that the first part of the path will retain it's `\` if present
+ * and the last one will preserve it's `\` character if present. You can
+ * combine this utility with `EnsureTrailing<T>`, `StripTrailing<T>`,
+ * `EnsureStarting<T>`, and `StripStarting<T>` to further shape
+ * the type.
  */
 export type PathJoin<
   // leading string
   T extends string,
-  // trailing string
-  U extends string
-> = IfLiteral<
-  T,
-  // Literal T guaranteed
-  IfLiteral<
-    // conditional
-    U,
-    `${StripEnding<T, "/">}/${StripStarting<U, "/">}`,
-    `${StripEnding<T, "/">}/${string}`
-  >,
-  // wide `T` encountered
-  IfLiteral<U, `${string}${U}`, string>
->;
+  // trailing string or strings
+  U extends string | readonly string[]
+> = U extends readonly string[]
+  ? // eslint-disable-next-line no-use-before-define
+    PathMultiJoin<PathJoin<T, "">, [...U]>
+  : U extends string
+  ? IfLiteral<
+      T,
+      // Literal T guaranteed
+      IfLiteral<
+        // conditional
+        U,
+        `${StripTrailing<T, "/">}/${StripLeading<U, "/">}`,
+        `${StripTrailing<T, "/">}/${string}`
+      >,
+      // wide `T` encountered
+      IfLiteral<U, `${string}${U}`, string>
+    >
+  : never;
+
+type PathMultiJoin<
+  TProcessed extends string,
+  TRemaining extends readonly string[]
+> = [] extends TRemaining
+  ? TProcessed
+  : PathMultiJoin<
+      // add to the TProcessed string
+      PathJoin<TProcessed, First<TRemaining>>,
+      // remaining elements after extracting head element
+      AfterFirst<TRemaining>
+    >;

package/src/types/alphabetic/{StripStarting.ts → StripLeading.ts}

@@ -12,7 +12,7 @@ import { IfLiteral } from "../boolean-logic/IsLiteral";
  * type R = StripStarting<T,U>;
  * ```
  */
-export type StripStarting<T extends string, U extends string> = IfLiteral<
+export type StripLeading<T extends string, U extends string> = IfLiteral<
   // can only operate on literal strings
   T,
   // this path represents successful strip opp

package/src/types/alphabetic/{StripEnding.ts → StripTrailing.ts}

@@ -12,7 +12,7 @@ import { IfLiteral } from "../boolean-logic/IsLiteral";
  * type R = StripEnding<T,U>;
  * ```
  */
-export type StripEnding<T extends string, U extends string> = IfLiteral<
+export type StripTrailing<T extends string, U extends string> = IfLiteral<
   // can only operate on literal strings
   T,
   // this path represents successful strip opp

package/src/types/alphabetic/index.ts

@@ -12,14 +12,17 @@ export * from "./DashUppercase";
 export * from "./Cardinality";
 export * from "./Dasherize";
 export * from "./HasUppercase";
+export * from "./EnsureLeading";
+export * from "./EnsureTrailing";
 export * from "./IsCapitalized";
 export * from "./KebabCase";
 export * from "./LowerAllCaps";
 export * from "./PascalCase";
+export * from "./PathJoin";
 export * from "./Pluralize";
 export * from "./SnakeCase";
-export * from "./StripStarting";
-export * from "./StripEnding";
+export * from "./StripLeading";
+export * from "./StripTrailing";
 export * from "./alpha-characters";
 export * from "./Url";
 

package/src/types/boolean-logic/HasParameters.ts

@@ -0,0 +1,21 @@
+import { AnyFunction } from "src/runtime";
+import { Length } from "../Length";
+import { Narrowable } from "../Narrowable";
+import { IsEqual } from "./equivalency";
+
+/**
+ * **HasParameters**`<T>`
+ *
+ * Type utility which detects if `T` is both a function and whether that
+ * function has at least one type parameter.
+ * ```ts
+ * const fn = (foo: string) => `${foo}bar`;
+ * // true
+ * type P = HasParameters<typeof fn>;
+ * ```
+ */
+export type HasParameters<T extends Narrowable> = T extends AnyFunction
+  ? IsEqual<Length<Parameters<T>>, 0> extends true
+    ? false
+    : true
+  : false;

package/src/types/boolean-logic/array.ts

@@ -1,4 +1,4 @@
-import { Equal } from "./equivalency";
+import { IsEqual } from "./equivalency";
 import { AfterFirst, First } from "../lists";
 import { Narrowable } from "../Narrowable";
 
@@ -47,7 +47,7 @@ export type Contains<T extends Narrowable, A extends readonly any[]> = First<A>
  * `true` if `T` _extends_ any element in `A` making it match widely against `A`. If you
  * prefer a wider match you can use `Contains<T,A>` instead.
  */
-export type NarrowlyContains<T extends Narrowable, A extends readonly any[]> = Equal<
+export type NarrowlyContains<T extends Narrowable, A extends readonly any[]> = IsEqual<
   First<A>,
   T
 > extends true

package/src/types/boolean-logic/boolean.ts

@@ -1,6 +1,6 @@
 import { Narrowable } from "../Narrowable";
 
-export type IsBoolean<T> = T extends boolean ? true : false;
+export type IsBoolean<T> = [T] extends [boolean] ? true : false;
 
 /**
  * Type utility which returns `true` or `false` based on

package/src/types/boolean-logic/equivalency.ts

@@ -3,7 +3,7 @@
  *
  * Type utility which tests whether two types -- `X` and `Y` -- are exactly the same type
  */
-export type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2
+export type IsEqual<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2
   ? true
   : false;
 
@@ -12,4 +12,4 @@ export type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T exte
  *
  * Type utility which tests whether two types -- `X` and `Y` -- are _not_ exactly the same type
  */
-export type NotEqual<X, Y> = true extends Equal<X, Y> ? false : true;
+export type NotEqual<X, Y> = true extends IsEqual<X, Y> ? false : true;

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

@@ -5,6 +5,7 @@ export * from "./IsScalar";
 export * from "./IsLiteral";
 export * from "./IsUndefined";
 export * from "./Extends";
+export * from "./HasParameters";
 export * from "./TypeDefault";
 export * from "./object";
 export * from "./StartsWith";

package/src/types/dictionary/props.ts

@@ -128,6 +128,11 @@ export type WithValue<
   : // Exclude using E
     Omit<Pick<T, KeysWithValue<W, T>>, KeysWithValue<E, T>>;
 
+export type DictionaryWithoutValue<TDict extends object, TWithoutValue> = Omit<
+  TDict,
+  KeysWithValue<TWithoutValue, TDict>
+>;
+
 /**
  * Reduces an object to only the key/value pairs where the key is a
  * string.

package/src/types/lists/ConvertAndMap.ts

@@ -0,0 +1,151 @@
+import { TupleToUnion, UnionToTuple } from "../type-conversion";
+import { Narrowable } from "../Narrowable";
+import { First } from "./First";
+import { AfterFirst } from "./AfterFirst";
+import { Keys } from "../Keys";
+
+import { DictionaryWithoutValue } from "../dictionary/props";
+
+// [Mapped Tuple Types](https://github.com/Microsoft/TypeScript/issues/25947)
+
+/**
+ * The basic shape of a `Converter`
+ */
+export type ConverterShape<
+  S extends Narrowable,
+  N extends Narrowable,
+  B extends Narrowable,
+  O extends Narrowable
+> = {
+  string: <T extends string>(v: T) => S;
+  number: <T extends number>(v: T) => N;
+  boolean: <T extends boolean>(v: T) => B;
+  object: <T extends Record<string, any>>(v: T) => O;
+};
+
+type ConverterKeys<S, N, B, O> = UnionToTuple<
+  Keys<
+    DictionaryWithoutValue<
+      {
+        string: S;
+        number: N;
+        boolean: B;
+        object: O;
+      },
+      undefined
+    >
+  >
+>;
+
+type ConverterInputType<T extends string> = T extends "string"
+  ? string
+  : T extends "number"
+  ? number
+  : T extends "boolean"
+  ? boolean
+  : T extends "object"
+  ? Record<string, any>
+  : unknown;
+
+type ConverterInputUnion<
+  TConverted extends readonly any[],
+  TRemaining extends readonly string[]
+> = [] extends TRemaining
+  ? // we're done iterating
+    TConverted
+  : // recurse
+    ConverterInputUnion<
+      [...TConverted, ConverterInputType<First<TRemaining>>],
+      AfterFirst<TRemaining>
+    >;
+
+/**
+ * **AvailableConverters**
+ *
+ * Type utility which will produce the correct union type for a "converter"
+ */
+export type AvailableConverters<S, N, B, O> = ConverterKeys<S, N, B, O> extends readonly string[]
+  ? TupleToUnion<ConverterInputUnion<[], ConverterKeys<S, N, B, O>>>
+  : never;
+
+/**
+ * **Converter**
+ *
+ * A type converter coming from the `createConverter()` utility. It receives
+ * one or more broad types (e.g., number, string, etc.) -- what it can take
+ * is based on what is configured -- and then converts based on the value
+ * passed in.
+ *
+ * The primary goal is to preserve as many _narrow_ types as possible in this process.
+ */
+export type Converter<
+  S extends Narrowable,
+  N extends Narrowable,
+  B extends Narrowable,
+  O extends Narrowable
+> = <T extends AvailableConverters<S, N, B, O>>(input: T) => ConverterShape<S, N, B, O>;
+
+export type Conversion<TInput extends Narrowable, TOutput extends Narrowable> = <T extends TInput>(
+  input: T
+) => TOutput;
+
+export type ConverterCoverage = "string" | "number" | "boolean" | "object";
+
+/**
+ * Extracts the coverage provided by a `StrongMap` as a Tuple
+ */
+export type MapCoverage<T extends StrongMap<ConverterCoverage>> = T extends StrongMap<
+  infer Coverage
+>
+  ? UnionToTuple<Coverage>
+  : never;
+
+export type StrongMapTypes<K extends readonly any[]> = [] extends K
+  ? never
+  : TupleToUnion<
+      [
+        First<K> extends "string"
+          ? TupleToUnion<[string, ...UnionToTuple<StrongMapTypes<AfterFirst<K>>>]>
+          : First<K> extends "number"
+          ? TupleToUnion<[number, ...UnionToTuple<StrongMapTypes<AfterFirst<K>>>]>
+          : First<K> extends "boolean"
+          ? TupleToUnion<[boolean, ...UnionToTuple<StrongMapTypes<AfterFirst<K>>>]>
+          : First<K> extends "object"
+          ? TupleToUnion<[Record<string, any>, ...UnionToTuple<StrongMapTypes<AfterFirst<K>>>]>
+          : never,
+        ...UnionToTuple<StrongMapTypes<AfterFirst<K>>>
+      ]
+    >;
+
+export type StrongMap<TDefined = ConverterCoverage> = {
+  string: TDefined extends "string" ? <T extends string, R extends any>(v: T) => R : never;
+  number: TDefined extends "number" ? <T extends number, R extends any>(v: T) => R : never;
+  boolean: TDefined extends "boolean" ? <T extends boolean, R extends any>(v: T) => R : never;
+  object: TDefined extends "object"
+    ? <T extends Record<string, any>, R extends any>(v: T) => R
+    : never;
+};
+
+export type StrongMapTransformer<M extends StrongMap> = <
+  T extends readonly StrongMapTypes<MapCoverage<M>>[]
+>(
+  tuple: T
+) => {
+  [K in keyof T]: T[K] extends string
+    ? M["string"] extends (...args: any[]) => any
+      ? ReturnType<M["string"]>
+      : never
+    : T[K] extends number
+    ? M["number"] extends (...args: any[]) => any
+      ? ReturnType<M["number"]>
+      : never
+    : T[K] extends boolean
+    ? M["boolean"] extends (...args: any[]) => any
+      ? ReturnType<M["boolean"]>
+      : never
+    : T[K] extends Record<string, any>
+    ? M["object"] extends (...args: any[]) => any
+      ? ReturnType<M["object"]>
+      : never
+    : never;
+}[keyof T];

package/src/types/type-conversion/Widen.ts

@@ -1,7 +1,22 @@
+import { AnyFunction } from "src/runtime";
+import { TupleToUnion } from "./TupleToUnion";
+
 export type Widen<T> = T extends string
   ? string
   : T extends number
   ? number
   : T extends boolean
   ? boolean
+  : T extends readonly string[]
+  ? string[]
+  : T extends readonly number[]
+  ? number[]
+  : T extends readonly boolean[]
+  ? boolean[]
+  : T extends readonly AnyFunction[]
+  ? AnyFunction[]
+  : T extends readonly any[]
+  ? TupleToUnion<T>[]
+  : T extends {}
+  ? {}
   : T;

package/tests/boolean-logic/HasParameters.ts

@@ -0,0 +1,29 @@
+import { Equal, Expect } from "@type-challenges/utils";
+import { HasParameters } from "src/types";
+import { describe, it } from "vitest";
+
+// Note: type tests fail visible inspection but pass from Vitest
+// standpoint so always be sure to run `tsc --noEmit` over your test files to
+// gain validation that no new type vulnerabilities have cropped up.
+
+describe("HasParameters<T>", () => {
+  it("happy path", () => {
+    const fn1 = (foo: string) => `${foo}bar`;
+    const fn2 = (foo: string) => `${foo}bar` as const;
+    const fn3 = () => `hello world`;
+    const fn4 = () => `hello world` as const;
+    const fn5 = (r: string, g: string, b: string) => `${r},${g},${b}` as const;
+
+    type cases = [
+      // single
+      Expect<Equal<HasParameters<typeof fn1>, true>>,
+      Expect<Equal<HasParameters<typeof fn2>, true>>,
+      // none
+      Expect<Equal<HasParameters<typeof fn3>, false>>,
+      Expect<Equal<HasParameters<typeof fn4>, false>>,
+      // multiple
+      Expect<Equal<HasParameters<typeof fn5>, true>>
+    ];
+    const cases: cases = [true, true, true, true, true];
+  });
+});

package/tests/lists/asArray.test.ts

@@ -1,7 +1,25 @@
 import { describe, it, expect } from "vitest";
-import { asArray } from "src/runtime";
+import { AsArray, asArray } from "src/runtime";
 import { Equal, Expect } from "@type-challenges/utils";
 
+describe("AsArray<T>", () => {
+  it("happy path", () => {
+    type T1 = AsArray<4>;
+    type T2 = AsArray<4, true>;
+    type T3 = AsArray<[4, 5, 6]>;
+    type T4 = AsArray<[4, 5, 6], true>;
+
+    type cases = [
+      //
+      Expect<Equal<T1, 4[]>>,
+      Expect<Equal<T2, number[]>>,
+      Expect<Equal<T3, [4, 5, 6]>>,
+      Expect<Equal<T4, number[]>>
+    ];
+    const cases: cases = [true, true, true, true];
+  });
+});
+
 describe("asArray() function", () => {
   it("non-array is returned as an array", () => {
     const i = "a";

package/tests/literals/EnsureStripLeadingTrailing.test.ts

@@ -0,0 +1,79 @@
+import { Equal, Expect } from "@type-challenges/utils";
+import { ensureLeading } from "src/runtime/literals/ensureLeading";
+import { ensureTrailing } from "src/runtime/literals/ensureTrailing";
+import { stripLeading } from "src/runtime/literals/stripLeading";
+import { stripTrailing } from "src/runtime/literals/stripTrailing";
+import { EnsureLeading, EnsureTrailing, StripLeading, StripTrailing } from "src/types/alphabetic";
+import { describe, expect, it } from "vitest";
+
+// Note: while type tests clearly fail visible inspection, they pass from Vitest
+// standpoint so always be sure to run `tsc --noEmit` over your test files to
+// gain validation that no new type vulnerabilities have cropped up.
+
+describe("EnsureLeading", () => {
+  it("EnsureLeading<T,U>", () => {
+    type T1 = EnsureLeading<"bar", "foo">;
+    type T2 = EnsureLeading<"foobar", "foo">;
+
+    type cases = [Expect<Equal<T1, "foobar">>, Expect<Equal<T2, "foobar">>];
+    const cases: cases = [true, true];
+  });
+
+  it("ensureLeading()", () => {
+    const t1 = ensureLeading("bar", "foo");
+    const t2 = ensureLeading("foobar", "foo");
+    expect(t1).toBe("foobar");
+    expect(t2).toBe("foobar");
+  });
+});
+
+describe("EnsureTrailing", () => {
+  it("EnsureTrailing<T,U>", () => {
+    type T1 = EnsureTrailing<"foo", "bar">;
+    type T2 = EnsureTrailing<"foobar", "bar">;
+
+    type cases = [Expect<Equal<T1, "foobar">>, Expect<Equal<T2, "foobar">>];
+    const cases: cases = [true, true];
+  });
+
+  it("ensureTrailing()", () => {
+    const t1 = ensureTrailing("foo", "bar");
+    const t2 = ensureTrailing("foobar", "bar");
+    expect(t1).toBe("foobar");
+    expect(t2).toBe("foobar");
+  });
+});
+
+describe("StripLeading", () => {
+  it("StripLeading<T,U>", () => {
+    type T1 = StripLeading<"foobar", "foo">;
+    type T2 = StripLeading<"bar", "foo">;
+
+    type cases = [Expect<Equal<T1, "bar">>, Expect<Equal<T2, "bar">>];
+    const cases: cases = [true, true];
+  });
+
+  it("stripLeading()", () => {
+    const t1 = stripLeading("foobar", "foo");
+    const t2 = stripLeading("bar", "foo");
+    expect(t1).toBe("bar");
+    expect(t2).toBe("bar");
+  });
+});
+
+describe("StripTrailing", () => {
+  it("StripTrailing<T,U>", () => {
+    type T1 = StripTrailing<"foobar", "bar">;
+    type T2 = StripTrailing<"foo", "bar">;
+
+    type cases = [Expect<Equal<T1, "foo">>, Expect<Equal<T2, "foo">>];
+    const cases: cases = [true, true];
+  });
+
+  it("stripTrailing()", () => {
+    const t1 = stripTrailing("foobar", "bar");
+    const t2 = stripTrailing("foo", "bar");
+    expect(t1).toBe("foo");
+    expect(t2).toBe("foo");
+  });
+});