inferred-types 0.22.6 → 0.22.8

package/dist/index.d.ts

@@ -522,6 +522,14 @@ declare type DictPartialApplication<T extends Record<string, any>, I extends boo
  * the original object `I` so long as the original value for the KV pair extends `V`.
  *
  * If `V` is not specified then it defaults to _any_ and therefore all KVs are preserved.
+ *
+ * ```ts
+ * type Obj = { foo: "hello", bar: 42, baz: () => "world" };
+ * // { foo: number, bar: number, baz: number };
+ * type AllNumbers = DictChangeValue<Obj, number>;
+ * // { foo: number }
+ * type StringToBool = DictChangeValue<Obj, boolean, string>
+ * ```
  */
 declare type DictChangeValue<
 /** the object who's value-type we're changing */
@@ -576,6 +584,25 @@ O extends (...args: any[]) => any = (...args: any[]) => any> = SimplifyObject<{
  */
 declare type Get<T, K> = K extends `${infer FK}.${infer L}` ? FK extends keyof T ? Get<T[FK], L> : never : K extends keyof T ? T[K] : never;
 
+/**
+ * Maps from one type `I` to another `O`, where:
+ *
+ * - a **null** value indicates that there is no valid mapping for the given input
+ * - you can either return a 1:1 or 1:M output as `O` or `O[]` when there is a mapping
+ *
+ * This type utility will ensure both `I` and `O` are honoured but if the runtime only
+ * uses the type utility it's worth bearing in mind that while _typing_ will be as expected
+ * the output parameter can assume properties that in fact do not reside
+ *
+ * ```ts
+ * const mapper: ModelMapper<{title: string}, {title: string, kind: string}> = i => {
+ *    title: i.title,
+ *    kind: "markdown"
+ * }
+ * ```
+ */
+declare type MapTo<I extends {}, O extends {}> = (i: I) => O[];
+
 /**
  * Given a dictionary of type `<T>`, this utility function will
  * make the `<M>` generic property _mutable_ and all other _read-only_.
@@ -1694,4 +1721,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, 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, 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, UpperAlpha, ValueTuple, ValueTypeFunc, ValueTypes, Where, WhereNot, Whitespace, WithNumericKeys, WithStringKeys, WithValue, ZipCode, and, api, arrayToKeyLookup, arrayToObject, condition, createFnWithProps, createMutationFunction, defineProperties, defineType, 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, 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, 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, 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, UpperAlpha, ValueTuple, ValueTypeFunc, ValueTypes, Where, WhereNot, Whitespace, WithNumericKeys, WithStringKeys, WithValue, ZipCode, and, api, arrayToKeyLookup, arrayToObject, condition, createFnWithProps, createMutationFunction, defineProperties, defineType, 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, mapValues, nameLiteral, or, randomString, readonlyFnWithProps, ruleSet, strArrayToDict, type, typeApi, uuid, valueTypes, withValue };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inferred-types",
-  "version": "0.22.6",
+  "version": "0.22.8",
   "description": "Functions which provide useful type inference on TS projects",
   "license": "MIT",
   "author": "Ken Snyder<ken@ken.net>",

package/src/types/dictionary/DictChangeValue.ts

@@ -5,6 +5,14 @@ import { SimplifyObject } from "../SimplifyObject";
  * the original object `I` so long as the original value for the KV pair extends `V`.
  *
  * If `V` is not specified then it defaults to _any_ and therefore all KVs are preserved.
+ *
+ * ```ts
+ * type Obj = { foo: "hello", bar: 42, baz: () => "world" };
+ * // { foo: number, bar: number, baz: number };
+ * type AllNumbers = DictChangeValue<Obj, number>;
+ * // { foo: number }
+ * type StringToBool = DictChangeValue<Obj, boolean, string>
+ * ```
  */
 export type DictChangeValue<
   /** the object who's value-type we're changing */

package/src/types/dictionary/MapTo.ts

@@ -0,0 +1,18 @@
+/**
+ * Maps from one type `I` to another `O`, where:
+ *
+ * - a **null** value indicates that there is no valid mapping for the given input
+ * - you can either return a 1:1 or 1:M output as `O` or `O[]` when there is a mapping
+ *
+ * This type utility will ensure both `I` and `O` are honoured but if the runtime only
+ * uses the type utility it's worth bearing in mind that while _typing_ will be as expected
+ * the output parameter can assume properties that in fact do not reside
+ *
+ * ```ts
+ * const mapper: ModelMapper<{title: string}, {title: string, kind: string}> = i => {
+ *    title: i.title,
+ *    kind: "markdown"
+ * }
+ * ```
+ */
+export type MapTo<I extends {}, O extends {}> = (i: I) => O[];

package/src/types/dictionary/index.ts

@@ -9,6 +9,7 @@ export * from "./DictChangeValue";
 export * from "./DictPrependWithFn";
 export * from "./DictReturnValues";
 export * from "./Get";
+export * from "./MapTo";
 export * from "./MutableProps";
 export * from "./RequireProps";
 export * from "./SameKeys";

package/src/utility/dictionary/mapTo.ts

@@ -0,0 +1,22 @@
+import { MapTo } from "src/types/dictionary";
+
+/**
+ * **mapTo**
+ *
+ * A utility function which maps one dictionary structure `I` to another `O`; where:
+ *
+ * - `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
+ *
+ * ```ts
+ * type I = { title: string; color: string; products: Product[] };
+ * type O = { title: string; count: number };
+ * const summarize: mapTo<I,O>()
+ *  .map();
+ * ```
+ */
+export const mapTo =
+  <I extends {}, O extends {}>(cb: MapTo<I, O>) =>
+  (source: I) =>
+    cb(source);

package/tests/dictionary/mapTo.test.ts

@@ -0,0 +1,106 @@
+import { MapTo } from "src/types/dictionary";
+import { describe, expect, it } from "vitest";
+
+import type { Expect, Equal } from "@type-challenges/utils";
+import { mapTo } from "src/utility/dictionary/mapTo";
+
+type I = { title: string; color: string; products: string[] };
+const i: I = { title: "Test", color: "green", products: ["foo", "bar", "baz"] };
+
+type O = { title: string; count: number; unnecessary?: number };
+
+describe("MapTo<T> type util", () => {
+  it("1:1 conversion", () => {
+    const m: MapTo<I, O> = (i) => [
+      {
+        title: i.title,
+        count: i.products.length,
+      },
+    ];
+    type M = typeof m;
+    type cases = [Expect<Equal<M, MapTo<I, O>>>];
+    const cases: cases = [true];
+    expect(cases).toBe(cases);
+  });
+
+  it("1:1 conversion with non-required", () => {
+    const m: MapTo<I, O> = (i) => [
+      {
+        title: i.title,
+        count: i.products.length,
+        unnecessary: 42,
+      },
+    ];
+    type M = typeof m;
+    type cases = [Expect<Equal<M, MapTo<I, O>>>];
+    const cases: cases = [true];
+    expect(cases).toBe(cases);
+  });
+
+  it("1:M conversion", () => {
+    const m: MapTo<I, O> = (i) => [
+      {
+        title: i.title,
+        count: i.products.length,
+        unnecessary: 1,
+      },
+      {
+        title: i.title,
+        count: i.products.length + 1,
+        unnecessary: 2,
+      },
+    ];
+    type M = typeof m;
+    type cases = [Expect<Equal<M, MapTo<I, O>>>];
+    const cases: cases = [true];
+    expect(cases).toBe(cases);
+  });
+
+  it("filter input as 1:0 cardinality", () => {
+    const m: MapTo<I, O> = (_i) => [];
+    type M = typeof m;
+    type cases = [Expect<Equal<M, MapTo<I, O>>>];
+    const cases: cases = [true];
+    expect(cases).toBe(cases);
+  });
+});
+
+describe("mapTo() utility function", () => {
+  it("test 1:1 mapping", () => {
+    const m = mapTo<I, O>((i) => [
+      {
+        title: i.title,
+        count: i.products.length,
+      },
+    ]);
+    type M = typeof m;
+    type R = ReturnType<M>;
+
+    // runtime
+    expect(m(i)).toEqual([{ title: i.title, count: i.products.length }]);
+    // types
+    type cases = [Expect<Equal<R, O[]>>];
+    const cases: cases = [true];
+    expect(cases).toBe(cases);
+  });
+
+  it("test 1:1 mapping with extraneous prop", () => {
+    const m = mapTo<I, O>((i) => [
+      {
+        title: i.title,
+        count: i.products.length,
+        extraneous: 42,
+      },
+    ]);
+    type M = typeof m;
+    type R = ReturnType<M>;
+
+    // runtime
+    // TODO: extraneous props are cut out of the type but still allows us to return `O` values with extraneous props!
+    // expect(m(i)).toEqual([{ title: i.title, count: i.products.length }]);
+    // types
+    type cases = [Expect<Equal<R, O[]>>];
+    const cases: cases = [true];
+    expect(cases).toBe(cases);
+  });
+});