inferred-types 0.24.2 → 0.25.0

package/dist/index.d.ts

@@ -165,12 +165,6 @@ declare type If<C extends boolean, T, F> = C extends T ? C | F : never;
  */
 declare type Include<T, U, L extends boolean = false> = L extends true ? T extends U ? U extends T ? T : never : never : T extends U ? T : never;
 
-/**
- * A type takes the two arguments. The first is an array of string values, the second is the value
- * which is being tested as it whether or not it's _included_ in the array. Result is true or false.
- */
-declare type Includes<T extends readonly any[], U> = U extends T[number] ? true : false;
-
 /**
  * A "KeyedRecord" is intended to store a value without
  * losing any ability to infer type information later.
@@ -1348,6 +1342,51 @@ declare type FromDictArray<T extends [string, Record<string, unknown>][]> = Expa
  */
 declare type SecondOfEach<T extends any[][]> = T[number][1] extends T[number][number] ? T[number][1] : never;
 
+/**
+ * **IsBooleanLiteral**
+ *
+ * Type utility which returns true/false if the boolean value is a _boolean literal_ versus
+ * just the wider _boolean_ type.
+ */
+declare type IsBooleanLiteral<T extends boolean> = boolean extends T ? false : true;
+
+/**
+ * **IsStringLiteral**
+ *
+ * Type utility which returns true/false if the string a _string literal_ versus
+ * just the _string_ type.
+ */
+declare type IsStringLiteral<T extends string> = string extends T ? false : true;
+
+/**
+ * **IsNumericLiteral**
+ *
+ * Type utility which returns true/false if the numeric value a _numeric literal_ versus
+ * just the _number_ type.
+ */
+declare type IsNumericLiteral<T extends number> = number extends T ? false : true;
+
+/**
+ * **IsLiteral**
+ *
+ * Type utility which returns true/false if the value passed -- a form of a
+ * string, number, or boolean -- is a _literal_ value of that type (true) or
+ * the more generic wide type (false).
+ */
+declare type IsLiteral<T extends string | number | boolean> = [T] extends [string] ? IsStringLiteral<T> : [T] extends [boolean] ? IsBooleanLiteral<T> : [T] extends [number] ? IsNumericLiteral<T> : never;
+
+/**
+ * **Includes<TSource, TValue>**
+ *
+ * Type utility which returns `true` or `false` based on whether `TValue` is found
+ * in `TSource`. Where `TSource` can be a string literal or an array of string literals.
+ *
+ * **Note:** if the source is a _wide_ type (aka, `string` or `string[]`) then there is
+ * no way to know at design-time whether the value includes `TValue` and so it will return
+ * a type of `boolean`.
+ */
+declare type Includes<TSource extends string | string[], TValue extends string> = TSource extends string[] ? IsStringLiteral<TupleToUnion<TSource>> extends true ? IsLiteral<TValue> extends true ? TValue extends TupleToUnion<TSource> ? true : false : boolean : boolean : TSource extends string ? IsLiteral<TSource> extends true ? IsLiteral<TValue> extends true ? TSource extends `${string}${TValue}${string}` ? true : false : boolean : boolean : boolean;
+
 declare function createFnWithProps<F extends Function, P extends {}>(fn: F, props: P): F & P;
 /**
  * Adds a dictionary of key/value pairs to a function.
@@ -1473,17 +1512,26 @@ declare function mapValues<N extends Narrowable, T extends Record<string, N>, V>
 /**
  * **mapTo**
  *
- * A utility function which maps one dictionary structure `I` to another `O`; where:
+ * A utility function which maps one dictionary structure `I` to another `O`; which allows
+ * the transform to:
+ *
+ * - _split_ inputs into multiple outputs
+ * - _map_ 1:1 between input and output
+ * - _filter_ inputs which don't meet certain criteria (by returning `null`)
  *
- * - `I` maps to `O[ ]` so this allows a cardinality of 0:M
- * - In other words ... values from `I` can be filtered, translated 1:1 or split into multiple outputs
- * - Type constrains laid out by `I` and `O` will be enforced by type system
+ * This higher order function first asks for the mapping criteria:
+ * ```ts
+ * const mapper = mapTo<I,O>(i => i.name
+ *  ? [
+ *      { name: i.name, a: "static text", b: i.products.length }
+ *    ]
+ *  : null
+ * );
+ * ```
  *
+ * and now you'll have a _mapper_ variable will be assigned as a mapping fn:
  * ```ts
- * type I = { title: string; color: string; products: Product[] };
- * type O = { title: string; count: number };
- * const summarize: mapTo<I,O>()
- *  .map();
+ * function (source: I | I[]): O[]
  * ```
  */
 declare const mapTo: <I extends {}, O extends {}>(cb: MapToWithFiltering<I, O>) => (source: I | I[]) => O[];
@@ -1773,4 +1821,4 @@ interface IFluentConfigurator<C> {
  */
 declare function FluentConfigurator<I>(initial?: I): IFluentConfigurator<{}>;
 
-export { AllCaps, Alpha, AlphaNumeric, Api, ApiFunction, ApiValue, AppendToDictionary, AppendToObject, ArrConcat, Array$1 as Array, ArrayConverter, AssertExtends, Bracket, Break, CamelCase, CapitalizeWords, ClosingBracket, Condition, Configurator, Constructor, DashToSnake, DashUppercase, Dasherize, DefinePropertiesApi, DictArrApi, DictArray, DictArrayFilterCallback, DictArrayKv, DictChangeValue, DictFromKv, DictKvTuple, DictPartialApplication, DictPrependWithFn, DictReturnValues, DynamicRule, DynamicRuleSet, Email, EnumValues, ExpandRecursively, ExpectExtends, ExplicitFunction, ExtendsClause, ExtendsNarrowlyClause, Filter, FinalReturn, First, FirstKey, FirstKeyValue, FirstOfEach, FluentConfigurator, FluentFunction, FromDictArray, FunctionType, GeneralDictionary, Get, HasUppercase, IConfigurator, IFluentConfigurator, If, IfExtends, IfExtendsThen, Include, Includes, IsArray, IsBoolean, IsCapitalized, IsFalse, IsFunction, IsObject, IsString, IsTrue, KebabCase, KeyValue, KeyedRecord, Keys, KeysWithValue, KvFrom, KvTuple, LastInUnion, LeftWhitespace, Length, LowerAllCaps, LowerAlpha, MapTo, MapToWithFiltering, MaybeFalse, MaybeTrue, Model, Mutable, MutableProps, MutationFunction, MutationIdentity, Narrowable, NonAlpha, NonNumericKeys, NonStringKeys, Not, Numeric, NumericKeys, NumericString, ObjectType, Opaque, OpeningBracket, OptionalKeys, OptionalProps, Parenthesis, PascalCase, Pluralize, PrivateKey, PrivateKeys, PublicKeys, Punctuation, PureFluentApi, Replace, RequireProps, RequiredKeys, RequiredProps, Retain, RightWhitespace, RuleDefinition, RuntimeProp, RuntimeType, SameKeys, SecondOfEach, SimplifyObject, SnakeCase, SpecialCharacters, StringDelimiter, StringKeys, StringLength, ToFluent, Transformer, Trim, TrimLeft, TrimRight, TupleToUnion, Type, TypeApi, TypeCondition, TypeDefinition, TypeGuard, TypeOptions, UnionToIntersection, UnionToTuple, UniqueDictionary, UniqueForProp, Uniqueness, UpperAlpha, ValueTuple, ValueTypeFunc, ValueTypes, Where, WhereNot, Whitespace, Widen, WithNumericKeys, WithStringKeys, WithValue, ZipCode, and, api, arrayToKeyLookup, arrayToObject, condition, createFnWithProps, createMutationFunction, defineProperties, defineType, dictArr, dictToKv, dictionaryTransform, entries, equals, filterDictArray, fnWithProps, greater, groupBy, idLiteral, idTypeGuard, identity, ifTypeOf, isArray, isBoolean, isFalse, isFunction, isNull, isNumber, isObject, isString, isSymbol, isTrue, isType, isUndefined, keys, kindLiteral, kv, kvToDict, less, literal, mapTo, mapValues, nameLiteral, or, randomString, readonlyFnWithProps, ruleSet, strArrayToDict, type, typeApi, uuid, valueTypes, withValue };
+export { AllCaps, Alpha, AlphaNumeric, Api, ApiFunction, ApiValue, AppendToDictionary, AppendToObject, ArrConcat, Array$1 as Array, ArrayConverter, AssertExtends, Bracket, Break, CamelCase, CapitalizeWords, ClosingBracket, Condition, Configurator, Constructor, DashToSnake, DashUppercase, Dasherize, DefinePropertiesApi, DictArrApi, DictArray, DictArrayFilterCallback, DictArrayKv, DictChangeValue, DictFromKv, DictKvTuple, DictPartialApplication, DictPrependWithFn, DictReturnValues, DynamicRule, DynamicRuleSet, Email, EnumValues, ExpandRecursively, ExpectExtends, ExplicitFunction, ExtendsClause, ExtendsNarrowlyClause, Filter, FinalReturn, First, FirstKey, FirstKeyValue, FirstOfEach, FluentConfigurator, FluentFunction, FromDictArray, FunctionType, GeneralDictionary, Get, HasUppercase, IConfigurator, IFluentConfigurator, If, IfExtends, IfExtendsThen, Include, Includes, IsArray, IsBoolean, IsBooleanLiteral, IsCapitalized, IsFalse, IsFunction, IsLiteral, IsNumericLiteral, IsObject, IsString, IsStringLiteral, IsTrue, KebabCase, KeyValue, KeyedRecord, Keys, KeysWithValue, KvFrom, KvTuple, LastInUnion, LeftWhitespace, Length, LowerAllCaps, LowerAlpha, MapTo, MapToWithFiltering, MaybeFalse, MaybeTrue, Model, Mutable, MutableProps, MutationFunction, MutationIdentity, Narrowable, NonAlpha, NonNumericKeys, NonStringKeys, Not, Numeric, NumericKeys, NumericString, ObjectType, Opaque, OpeningBracket, OptionalKeys, OptionalProps, Parenthesis, PascalCase, Pluralize, PrivateKey, PrivateKeys, PublicKeys, Punctuation, PureFluentApi, Replace, RequireProps, RequiredKeys, RequiredProps, Retain, RightWhitespace, RuleDefinition, RuntimeProp, RuntimeType, SameKeys, SecondOfEach, SimplifyObject, SnakeCase, SpecialCharacters, StringDelimiter, StringKeys, StringLength, ToFluent, Transformer, Trim, TrimLeft, TrimRight, TupleToUnion, Type, TypeApi, TypeCondition, TypeDefinition, TypeGuard, TypeOptions, UnionToIntersection, UnionToTuple, UniqueDictionary, UniqueForProp, Uniqueness, UpperAlpha, ValueTuple, ValueTypeFunc, ValueTypes, Where, WhereNot, Whitespace, Widen, WithNumericKeys, WithStringKeys, WithValue, ZipCode, and, api, arrayToKeyLookup, arrayToObject, condition, createFnWithProps, createMutationFunction, defineProperties, defineType, dictArr, dictToKv, dictionaryTransform, entries, equals, filterDictArray, fnWithProps, greater, groupBy, idLiteral, idTypeGuard, identity, ifTypeOf, isArray, isBoolean, isFalse, isFunction, isNull, isNumber, isObject, isString, isSymbol, isTrue, isType, isUndefined, keys, kindLiteral, kv, kvToDict, less, literal, mapTo, mapValues, nameLiteral, or, randomString, readonlyFnWithProps, ruleSet, strArrayToDict, type, typeApi, uuid, valueTypes, withValue };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inferred-types",
-  "version": "0.24.2",
+  "version": "0.25.0",
   "description": "Functions which provide useful type inference on TS projects",
   "license": "MIT",
   "author": "Ken Snyder<ken@ken.net>",
@@ -46,6 +46,7 @@
     "eslint-plugin-prettier": "^4.2.1",
     "eslint-plugin-promise": "^6.1.1",
     "npm-run-all": "~4.1.5",
+    "pathe": "^0.3.9",
     "prettier": "~2.7.1",
     "rimraf": "^3.0.2",
     "sharp": "^0.31.1",

package/src/types/TypeInfo/Includes.ts

@@ -0,0 +1,34 @@
+import { TupleToUnion } from "../type-conversion";
+import { IsLiteral } from "./IsLiteral";
+import { IsStringLiteral } from "./IsStringLiteral";
+
+/**
+ * **Includes<TSource, TValue>**
+ *
+ * Type utility which returns `true` or `false` based on whether `TValue` is found
+ * in `TSource`. Where `TSource` can be a string literal or an array of string literals.
+ *
+ * **Note:** if the source is a _wide_ type (aka, `string` or `string[]`) then there is
+ * no way to know at design-time whether the value includes `TValue` and so it will return
+ * a type of `boolean`.
+ */
+export type Includes<
+  TSource extends string | string[],
+  TValue extends string
+> = TSource extends string[]
+  ? IsStringLiteral<TupleToUnion<TSource>> extends true
+    ? IsLiteral<TValue> extends true
+      ? TValue extends TupleToUnion<TSource>
+        ? true
+        : false
+      : boolean
+    : boolean
+  : TSource extends string
+  ? IsLiteral<TSource> extends true
+    ? IsLiteral<TValue> extends true
+      ? TSource extends `${string}${TValue}${string}`
+        ? true
+        : false
+      : boolean
+    : boolean
+  : boolean;

package/src/types/TypeInfo/IsBooleanLiteral.ts

@@ -0,0 +1,7 @@
+/**
+ * **IsBooleanLiteral**
+ *
+ * Type utility which returns true/false if the boolean value is a _boolean literal_ versus
+ * just the wider _boolean_ type.
+ */
+export type IsBooleanLiteral<T extends boolean> = boolean extends T ? false : true;

package/src/types/TypeInfo/IsLiteral.ts

@@ -0,0 +1,20 @@
+import { IsBooleanLiteral } from "./IsBooleanLiteral";
+import { IsStringLiteral } from "./IsStringLiteral";
+import { IsNumericLiteral } from "./IsNumericLiteral";
+
+// [note on handling of boolean](https://stackoverflow.com/questions/74213646/detecting-type-literals-works-in-isolation-but-not-when-combined-with-other-lite/74213713#74213713)
+
+/**
+ * **IsLiteral**
+ *
+ * Type utility which returns true/false if the value passed -- a form of a
+ * string, number, or boolean -- is a _literal_ value of that type (true) or
+ * the more generic wide type (false).
+ */
+export type IsLiteral<T extends string | number | boolean> = [T] extends [string]
+  ? IsStringLiteral<T>
+  : [T] extends [boolean]
+  ? IsBooleanLiteral<T>
+  : [T] extends [number]
+  ? IsNumericLiteral<T>
+  : never;

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/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/dictionary/mapTo.ts

@@ -3,17 +3,26 @@ import { MapToWithFiltering } from "src/types/dictionary";
 /**
  * **mapTo**
  *
- * A utility function which maps one dictionary structure `I` to another `O`; where:
+ * A utility function which maps one dictionary structure `I` to another `O`; which allows
+ * the transform to:
  *
- * - `I` maps to `O[ ]` so this allows a cardinality of 0:M
- * - In other words ... values from `I` can be filtered, translated 1:1 or split into multiple outputs
- * - Type constrains laid out by `I` and `O` will be enforced by type system
+ * - _split_ inputs into multiple outputs
+ * - _map_ 1:1 between input and output
+ * - _filter_ inputs which don't meet certain criteria (by returning `null`)
  *
+ * This higher order function first asks for the mapping criteria:
  * ```ts
- * type I = { title: string; color: string; products: Product[] };
- * type O = { title: string; count: number };
- * const summarize: mapTo<I,O>()
- *  .map();
+ * const mapper = mapTo<I,O>(i => i.name
+ *  ? [
+ *      { name: i.name, a: "static text", b: i.products.length }
+ *    ]
+ *  : null
+ * );
+ * ```
+ *
+ * and now you'll have a _mapper_ variable will be assigned as a mapping fn:
+ * ```ts
+ * function (source: I | I[]): O[]
  * ```
  */
 export const mapTo =

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/tsconfig.json

@@ -16,6 +16,14 @@
     "lib": [
       "ES2020"
     ],
+    "paths": {
+      "src/*": [
+        "src/*"
+      ],
+      "test/*": [
+        "test/*"
+      ]
+    },
     "baseUrl": ".",
     "declaration": true,
     "outDir": "dist",

package/vitest.config.ts

@@ -1,8 +1,15 @@
 /// <reference types="vitest" />
 import { defineConfig } from "vite";
+import { resolve } from "pathe";
 
 // used for testing, library code uses TSUP to build exports
 export default defineConfig({
+  resolve: {
+    alias: {
+      src: resolve(__dirname, "./src"),
+      test: resolve(__dirname, "./test"),
+    },
+  },
   test: {
     dir: "tests",
     api: {

package/src/types/Includes.ts

@@ -1,5 +0,0 @@
-/**
- * A type takes the two arguments. The first is an array of string values, the second is the value
- * which is being tested as it whether or not it's _included_ in the array. Result is true or false.
- */
-export type Includes<T extends readonly any[], U> = U extends T[number] ? true : false;