inferred-types 0.24.1 → 0.24.3

package/dist/index.d.ts

@@ -585,23 +585,26 @@ 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:
+ * **MapTo**
  *
- * - 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
+ * Maps from one type `I` to another `O[]`
  *
- * 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"
- * }
- * ```
+ * **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.
  */
 declare type MapTo<I extends {}, O extends {}> = (i: I) => O[];
+/**
+ * **MapToWithFiltering**
+ *
+ * Maps from one type `I` to another `(O | null)[]`
+ *
+ * **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.
+ */
+declare type MapToWithFiltering<I extends {}, O extends {}> = (i: I) => O[] | null;
 
 /**
  * Given a dictionary of type `<T>`, this utility function will
@@ -1470,20 +1473,29 @@ 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: MapTo<I, O>) => (source: I) => O[];
+declare const mapTo: <I extends {}, O extends {}>(cb: MapToWithFiltering<I, O>) => (source: I | I[]) => O[];
 
 /**
  * converts an array of strings `["a", "b", "c"]` into a more type friendly
@@ -1770,4 +1782,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, 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, 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 };

package/dist/index.js

@@ -262,7 +262,14 @@ function mapValues(obj, valueMapper) {
 }
 
 // src/utility/dictionary/mapTo.ts
-var mapTo = (cb) => (source) => cb(source);
+var mapTo = (cb) => (source) => {
+  if (Array.isArray(source)) {
+    return source.flatMap((i) => cb(i)).filter((i) => i !== null);
+  } else {
+    const result = cb(source);
+    return result ? result : [];
+  }
+};
 
 // src/utility/dictionary/strArrayToDict.ts
 function strArrayToDict(...strings) {

package/dist/index.mjs

@@ -179,7 +179,14 @@ function mapValues(obj, valueMapper) {
 }
 
 // src/utility/dictionary/mapTo.ts
-var mapTo = (cb) => (source) => cb(source);
+var mapTo = (cb) => (source) => {
+  if (Array.isArray(source)) {
+    return source.flatMap((i) => cb(i)).filter((i) => i !== null);
+  } else {
+    const result = cb(source);
+    return result ? result : [];
+  }
+};
 
 // src/utility/dictionary/strArrayToDict.ts
 function strArrayToDict(...strings) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inferred-types",
-  "version": "0.24.1",
+  "version": "0.24.3",
   "description": "Functions which provide useful type inference on TS projects",
   "license": "MIT",
   "author": "Ken Snyder<ken@ken.net>",
@@ -32,19 +32,19 @@
   },
   "devDependencies": {
     "@type-challenges/utils": "~0.1.1",
-    "@types/node": "16",
-    "@typescript-eslint/eslint-plugin": "^5.40.1",
-    "@typescript-eslint/parser": "^5.40.1",
+    "@types/node": "^16.18.0",
+    "@typescript-eslint/eslint-plugin": "^5.41.0",
+    "@typescript-eslint/parser": "^5.41.0",
     "bumpp": "^8.2.1",
     "common-types": "^1.31.1",
     "cross-env": "^7.0.3",
     "dd": "^0.24.0",
     "dotenv": "^16.0.3",
-    "eslint": "^8.25.0",
+    "eslint": "^8.26.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-import": "^2.26.0",
     "eslint-plugin-prettier": "^4.2.1",
-    "eslint-plugin-promise": "^6.1.0",
+    "eslint-plugin-promise": "^6.1.1",
     "npm-run-all": "~4.1.5",
     "prettier": "~2.7.1",
     "rimraf": "^3.0.2",

package/src/types/dictionary/MapTo.ts

@@ -1,18 +1,23 @@
 /**
- * Maps from one type `I` to another `O`, where:
+ * **MapTo**
  *
- * - 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
+ * Maps from one type `I` to another `O[]`
  *
- * 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"
- * }
- * ```
+ * **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.
  */
 export type MapTo<I extends {}, O extends {}> = (i: I) => O[];
+
+/**
+ * **MapToWithFiltering**
+ *
+ * Maps from one type `I` to another `(O | null)[]`
+ *
+ * **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.
+ */
+
+export type MapToWithFiltering<I extends {}, O extends {}> = (i: I) => O[] | null;

package/src/utility/dictionary/mapTo.ts

@@ -1,22 +1,37 @@
-import { MapTo } from "src/types/dictionary";
+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 =
-  <I extends {}, O extends {}>(cb: MapTo<I, O>) =>
-  (source: I) =>
-    cb(source);
+  <I extends {}, O extends {}>(cb: MapToWithFiltering<I, O>) =>
+  (source: I | I[]) => {
+    if (Array.isArray(source)) {
+      return source.flatMap((i) => cb(i)).filter((i) => i !== null) as O[];
+    } else {
+      const result = cb(source);
+      return result ? result : ([] as O[]);
+    }
+  };

package/tests/dictionary/mapTo.test.ts

@@ -6,6 +6,7 @@ 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"] };
+const i2: I = { title: "i2", color: "green", products: ["foo", "bar", "baz"] };
 
 type O = { title: string; count: number; unnecessary?: number };
 
@@ -103,4 +104,21 @@ describe("mapTo() utility function", () => {
     const cases: cases = [true];
     expect(cases).toBe(cases);
   });
+
+  it("test input filtering", () => {
+    const m = mapTo<I, O>((x) => {
+      return x.title === "i2"
+        ? null
+        : [
+            {
+              title: i.title,
+              count: i.products.length,
+            },
+          ];
+    });
+    const results = m([i, i2]);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].title).toBe("Test");
+  });
 });