inferred-types 0.26.0 → 0.28.0

package/dist/index.js

@@ -21,8 +21,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   Configurator: () => Configurator,
+  DEFAULT_MANY_TO_ONE_MAPPING: () => DEFAULT_MANY_TO_ONE_MAPPING,
+  DEFAULT_ONE_TO_MANY_MAPPING: () => DEFAULT_ONE_TO_MANY_MAPPING,
+  DEFAULT_ONE_TO_ONE_MAPPING: () => DEFAULT_ONE_TO_ONE_MAPPING,
   ExplicitFunction: () => ExplicitFunction,
   FluentConfigurator: () => FluentConfigurator,
+  MapCardinality: () => MapCardinality,
   Model: () => Model,
   MutationIdentity: () => MutationIdentity,
   and: () => and,
@@ -67,6 +71,8 @@ __export(src_exports, {
   kvToDict: () => kvToDict,
   literal: () => literal,
   mapTo: () => mapTo,
+  mapToDict: () => mapToDict,
+  mapToFn: () => mapToFn,
   mapValues: () => mapValues,
   nameLiteral: () => nameLiteral,
   not: () => not,
@@ -126,6 +132,14 @@ var valueTypes = {
   literalArray: (arr) => [arr, true]
 };
 
+// src/types/dictionary/MapTo.ts
+var MapCardinality = /* @__PURE__ */ ((MapCardinality2) => {
+  MapCardinality2["OneToMany"] = "I -> O[]";
+  MapCardinality2["OneToOne"] = "I -> O";
+  MapCardinality2["ManyToOne"] = "I[] -> O";
+  return MapCardinality2;
+})(MapCardinality || {});
+
 // src/utility/keys.ts
 function keys(obj, ...without) {
   const v = without.length > 0 ? Object.keys(obj).filter((k) => !without.includes(k)) : Object.keys(obj);
@@ -579,14 +593,68 @@ function mapValues(obj, valueMapper) {
 }
 
 // src/utility/dictionary/mapTo.ts
-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 : [];
+var toFinalizedConfig = (config) => {
+  return { ...config, finalized: true };
+};
+var DEFAULT_ONE_TO_MANY_MAPPING = toFinalizedConfig({
+  input: "req",
+  output: "opt",
+  cardinality: "I -> O[]"
+});
+var DEFAULT_ONE_TO_ONE_MAPPING = toFinalizedConfig({
+  input: "req",
+  output: "req",
+  cardinality: "I -> O"
+});
+var DEFAULT_MANY_TO_ONE_MAPPING = toFinalizedConfig({
+  input: "req",
+  output: "req",
+  cardinality: "I[] -> O"
+});
+var mapper = (config) => (map) => {
+  return (source) => {
+    const isArray2 = config.cardinality === "I -> O[]" && Array.isArray(source) ? true : config.cardinality === "I[] -> O" && Array.isArray(source) && Array.isArray(source[0]) ? true : false;
+    if (isArray2) {
+      return source.flatMap(map);
+    } else {
+      return map(source);
+    }
+  };
+};
+var setMapper = (config = { input: void 0, output: void 0, cardinality: void 0 }, defaultValue) => ({
+  map: (source) => {
+    const c = {
+      ...defaultValue,
+      ...config
+    };
+    return mapper(c)(source);
+  },
+  input: (config == null ? void 0 : config.input) || defaultValue.input,
+  output: (config == null ? void 0 : config.output) || defaultValue.output,
+  cardinality: (config == null ? void 0 : config.cardinality) || defaultValue.cardinality
+});
+var mapToFn = (map) => {
+  return mapper(DEFAULT_ONE_TO_MANY_MAPPING)(map);
+};
+var mapToDict = {
+  config(config) {
+    const c = { ...DEFAULT_ONE_TO_MANY_MAPPING, ...config };
+    return setMapper(c, DEFAULT_ONE_TO_MANY_MAPPING);
+  },
+  oneToOne(config) {
+    const c = { ...DEFAULT_ONE_TO_ONE_MAPPING, ...config };
+    return setMapper(c, DEFAULT_ONE_TO_ONE_MAPPING);
+  },
+  manyToOne(config) {
+    const c = { ...DEFAULT_MANY_TO_ONE_MAPPING, ...config };
+    return setMapper(c, DEFAULT_MANY_TO_ONE_MAPPING);
+  },
+  oneToMany(config) {
+    const c = { ...DEFAULT_ONE_TO_MANY_MAPPING, ...config };
+    return setMapper(c, DEFAULT_ONE_TO_MANY_MAPPING);
   }
 };
+var mapTo = createFnWithProps(mapToFn, mapToDict);
 
 // src/utility/dictionary/strArrayToDict.ts
 function strArrayToDict(...strings) {
@@ -752,8 +820,12 @@ function Model(name) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Configurator,
+  DEFAULT_MANY_TO_ONE_MAPPING,
+  DEFAULT_ONE_TO_MANY_MAPPING,
+  DEFAULT_ONE_TO_ONE_MAPPING,
   ExplicitFunction,
   FluentConfigurator,
+  MapCardinality,
   Model,
   MutationIdentity,
   and,
@@ -798,6 +870,8 @@ function Model(name) {
   kvToDict,
   literal,
   mapTo,
+  mapToDict,
+  mapToFn,
   mapValues,
   nameLiteral,
   not,

package/dist/index.mjs

@@ -41,6 +41,14 @@ var valueTypes = {
   literalArray: (arr) => [arr, true]
 };
 
+// src/types/dictionary/MapTo.ts
+var MapCardinality = /* @__PURE__ */ ((MapCardinality2) => {
+  MapCardinality2["OneToMany"] = "I -> O[]";
+  MapCardinality2["OneToOne"] = "I -> O";
+  MapCardinality2["ManyToOne"] = "I[] -> O";
+  return MapCardinality2;
+})(MapCardinality || {});
+
 // src/utility/keys.ts
 function keys(obj, ...without) {
   const v = without.length > 0 ? Object.keys(obj).filter((k) => !without.includes(k)) : Object.keys(obj);
@@ -494,14 +502,68 @@ function mapValues(obj, valueMapper) {
 }
 
 // src/utility/dictionary/mapTo.ts
-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 : [];
+var toFinalizedConfig = (config) => {
+  return { ...config, finalized: true };
+};
+var DEFAULT_ONE_TO_MANY_MAPPING = toFinalizedConfig({
+  input: "req",
+  output: "opt",
+  cardinality: "I -> O[]"
+});
+var DEFAULT_ONE_TO_ONE_MAPPING = toFinalizedConfig({
+  input: "req",
+  output: "req",
+  cardinality: "I -> O"
+});
+var DEFAULT_MANY_TO_ONE_MAPPING = toFinalizedConfig({
+  input: "req",
+  output: "req",
+  cardinality: "I[] -> O"
+});
+var mapper = (config) => (map) => {
+  return (source) => {
+    const isArray2 = config.cardinality === "I -> O[]" && Array.isArray(source) ? true : config.cardinality === "I[] -> O" && Array.isArray(source) && Array.isArray(source[0]) ? true : false;
+    if (isArray2) {
+      return source.flatMap(map);
+    } else {
+      return map(source);
+    }
+  };
+};
+var setMapper = (config = { input: void 0, output: void 0, cardinality: void 0 }, defaultValue) => ({
+  map: (source) => {
+    const c = {
+      ...defaultValue,
+      ...config
+    };
+    return mapper(c)(source);
+  },
+  input: (config == null ? void 0 : config.input) || defaultValue.input,
+  output: (config == null ? void 0 : config.output) || defaultValue.output,
+  cardinality: (config == null ? void 0 : config.cardinality) || defaultValue.cardinality
+});
+var mapToFn = (map) => {
+  return mapper(DEFAULT_ONE_TO_MANY_MAPPING)(map);
+};
+var mapToDict = {
+  config(config) {
+    const c = { ...DEFAULT_ONE_TO_MANY_MAPPING, ...config };
+    return setMapper(c, DEFAULT_ONE_TO_MANY_MAPPING);
+  },
+  oneToOne(config) {
+    const c = { ...DEFAULT_ONE_TO_ONE_MAPPING, ...config };
+    return setMapper(c, DEFAULT_ONE_TO_ONE_MAPPING);
+  },
+  manyToOne(config) {
+    const c = { ...DEFAULT_MANY_TO_ONE_MAPPING, ...config };
+    return setMapper(c, DEFAULT_MANY_TO_ONE_MAPPING);
+  },
+  oneToMany(config) {
+    const c = { ...DEFAULT_ONE_TO_MANY_MAPPING, ...config };
+    return setMapper(c, DEFAULT_ONE_TO_MANY_MAPPING);
   }
 };
+var mapTo = createFnWithProps(mapToFn, mapToDict);
 
 // src/utility/dictionary/strArrayToDict.ts
 function strArrayToDict(...strings) {
@@ -666,8 +728,12 @@ function Model(name) {
 }
 export {
   Configurator,
+  DEFAULT_MANY_TO_ONE_MAPPING,
+  DEFAULT_ONE_TO_MANY_MAPPING,
+  DEFAULT_ONE_TO_ONE_MAPPING,
   ExplicitFunction,
   FluentConfigurator,
+  MapCardinality,
   Model,
   MutationIdentity,
   and,
@@ -712,6 +778,8 @@ export {
   kvToDict,
   literal,
   mapTo,
+  mapToDict,
+  mapToFn,
   mapValues,
   nameLiteral,
   not,

package/package.json

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

package/src/types/Mutable.ts

@@ -1,6 +1,8 @@
+import { IsObject } from "./TypeInfo";
+
 /**
  * Makes a readonly structure mutable
  */
 export type Mutable<T> = {
-  -readonly [K in keyof T]: T[K];
+  -readonly [K in keyof T]: IsObject<T[K]> extends true ? Mutable<T[K]> : T[K];
 };

package/src/types/TypeInfo/Extends.ts

@@ -0,0 +1,14 @@
+/**
+ * **Extends**
+ *
+ * Boolean type utility which returns `true` if `E` _extends_ `T`.
+ */
+export type Extends<E, T> = E extends T ? true : false;
+
+/**
+ * **IfExtends**
+ *
+ * Branching type utility which returns type `IF` when `E` _extends_ `T`; otherwise
+ * it will return the type `ELSE`.
+ */
+export type IfExtends<E, T, IF, ELSE> = Extends<E, T> extends true ? IF : ELSE;

package/src/types/TypeInfo/IsBooleanLiteral.ts

@@ -5,3 +5,12 @@
  * just the wider _boolean_ type.
  */
 export type IsBooleanLiteral<T extends boolean> = boolean extends T ? false : true;
+
+/**
+ * **IfBooleanLiteral**
+ *
+ * Branch utility which returns `IF` type when `T` is a boolean literal and `ELSE` otherwise
+ */
+export type IfBooleanLiteral<T extends boolean, IF, ELSE> = IsBooleanLiteral<T> extends true
+  ? IF
+  : ELSE;

package/src/types/TypeInfo/IsLiteral.ts

@@ -11,10 +11,44 @@ import { IsNumericLiteral } from "./IsNumericLiteral";
  * 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]
+export type IsLiteral<T> = [T] extends [string]
   ? IsStringLiteral<T>
   : [T] extends [boolean]
   ? IsBooleanLiteral<T>
   : [T] extends [number]
   ? IsNumericLiteral<T>
-  : never;
+  : false;
+
+/**
+ * **IsOptionalLiteral**
+ *
+ * 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).
+ *
+ * This type also strips off _undefined_ from any possible union type to evaluate
+ * to `true` even when a literal value is in union with _undefined_. If you don't
+ * want to test for the union with _undefined_ use the `IsOptional` utility instead.
+ */
+export type IsOptionalLiteral<T> = [Exclude<T, undefined>] extends [string]
+  ? IsStringLiteral<Exclude<T, undefined>>
+  : [Exclude<T, undefined>] extends [boolean]
+  ? IsBooleanLiteral<Exclude<T, undefined>>
+  : [Exclude<T, undefined>] extends [number]
+  ? IsNumericLiteral<Exclude<T, undefined>>
+  : false;
+
+/**
+ * **IfLiteral**
+ *
+ * Branch type utility with return `IF` when `T` is a _literal_ value and `ELSE` otherwise
+ */
+export type IfLiteral<T, IF, ELSE> = IsLiteral<T> extends true ? IF : ELSE;
+
+/**
+ * **IfOptionalLiteral**
+ *
+ * Branch type utility with return `IF` when `T` is a _literal_ value (with possibly
+ * the inclusion of _undefined_); otherwise returns the type `ELSE`
+ */
+export type IfOptionalLiteral<T, IF, ELSE> = IsOptionalLiteral<T> extends true ? IF : ELSE;

package/src/types/TypeInfo/IsNumericLiteral.ts

@@ -5,3 +5,12 @@
  * just the _number_ type.
  */
 export type IsNumericLiteral<T extends number> = number extends T ? false : true;
+
+/**
+ * **IfNumericLiteral**
+ *
+ * Branch utility which returns `IF` type when `T` is a numeric literal and `ELSE` otherwise
+ */
+export type IfNumericLiteral<T extends number, IF, ELSE> = IsNumericLiteral<T> extends true
+  ? IF
+  : ELSE;

package/src/types/TypeInfo/IsObject.ts

@@ -0,0 +1,27 @@
+import { FunctionType } from "../FunctionType";
+import { Mutable } from "../Mutable";
+
+/**
+ * **IsObject**
+ *
+ * Boolean type utility used to check whether a type `T` is an object
+ */
+export type IsObject<T> = Mutable<T> extends Record<string, any>
+  ? // an object of some type
+    T extends FunctionType
+    ? // when a function with props is found, categorize as a function not object
+      false
+    : Mutable<T> extends any[]
+    ? // Array's are objects too but in our narrower definition we're looking only
+      // dictionary based arrays.
+      false
+    : true
+  : false;
+
+/**
+ * **IfObject**
+ *
+ * Branch type utility with return `IF` when `T` extends an object type
+ * and `ELSE` otherwise
+ */
+export type IfObject<T, IF, ELSE> = IsObject<T> extends true ? IF : ELSE;

package/src/types/TypeInfo/IsScalar.ts

@@ -0,0 +1,14 @@
+export type IsScalar<T> = [T] extends [string]
+  ? true
+  : [T] extends [number]
+  ? true
+  : [T] extends [boolean]
+  ? true
+  : false;
+
+/**
+ * **IfScalar**
+ *
+ * Branch type utility which returns `IF` when `T` is a scalar value and `ELSE` otherwise
+ */
+export type IfScalar<T, IF, ELSE> = IsScalar<T> extends true ? IF : ELSE;

package/src/types/TypeInfo/IsStringLiteral.ts

@@ -5,3 +5,12 @@
  * just the _string_ type.
  */
 export type IsStringLiteral<T extends string> = string extends T ? false : true;
+
+/**
+ * **IfStringLiteral**
+ *
+ * Branch utility which returns `IF` type when `T` is a string literal and `ELSE` otherwise
+ */
+export type IfStringLiteral<T extends string, IF, ELSE> = IsStringLiteral<T> extends true
+  ? IF
+  : ELSE;

package/src/types/TypeInfo/IsUndefined.ts

@@ -0,0 +1,14 @@
+/**
+ * **IsUndefined**
+ *
+ * Boolean type utility returns `true` if `T` is undefined; `false` otherwise
+ */
+export type IsUndefined<T> = T extends undefined ? true : false;
+
+/**
+ * **IfUndefined**
+ *
+ * Branch utility which returns `IF` type when `T` is an _undefined_ value
+ * otherwise returns `ELSE` type
+ */
+export type IfUndefined<T, IF, ELSE> = IsUndefined<T> extends true ? IF : ELSE;

package/src/types/TypeInfo/TypeDefault.ts

@@ -0,0 +1,58 @@
+import { IsObject } from "src/types/TypeInfo";
+import { SimplifyObject } from "../SimplifyObject";
+import { IfExtends } from "./Extends";
+import { IfOptionalLiteral } from "./IsLiteral";
+import { IfUndefined } from "./IsUndefined";
+
+/**
+ * **TypeDefault**
+ *
+ * A type utility designed to help maintain strong and narrow types where
+ * you have a value `T` which _might_ be **undefined** and a type `D` which
+ * defines all the _default_ type for `T`.
+ *
+ * - In all cases we compare first whether `T` is undefined and replace it's
+ * type with `D` 1-for-1 if it is
+ * - To address a larger set of use cases, when `D` _extends_ an object we will
+ * compare each property of `D` against `T`
+ * ```ts
+ * type I = { foo?: "foo" |  undefined; bar?: 42 | 53 | undefined };
+ * type D = { foo: "foo"; bar: 53 };
+ * type DF = TypeDefault<I,D>; // `D`
+ * const i = { foo: undefined, bar: 99 } as const;
+ * type DF2 = TypeDefault<typeof i, D>; // `{ foo: "foo"; bar: 99 }`
+ * ```
+ */
+export type TypeDefault<T, D> = //
+  IsObject<D> extends true //
+    ? IsObject<T> extends true
+      ? // both T and D are objects; start by iterating over D
+        SimplifyObject<{
+          [K in keyof D]: K extends keyof T
+            ? // both D[T] and K[T] are present
+              TypeDefault<T[K], D[K]>
+            : // only D[K] present
+              D[K];
+        }>
+      : // T is not an object, but D is
+        IfUndefined<
+          T, // check if T is undefined
+          D, // use D as the type
+          Exclude<T, undefined> // use T as the type but remove "undefined"
+        >
+    : // neither D or T is an object
+      IfUndefined<
+        T, // check whether is T is undefined
+        D, // assign to D if it is
+        IfOptionalLiteral<
+          T, // if T is a literal
+          IfExtends<
+            D,
+            T,
+            D, // use D since it extends the value of T
+            Exclude<T, undefined> // use T's literal value minus "undefined"
+          >,
+          // T is a wide type
+          Exclude<T, undefined>
+        >
+      >;

package/src/types/TypeInfo/index.ts

@@ -1,5 +1,9 @@
 export * from "./Includes";
 export * from "./IsBooleanLiteral";
 export * from "./IsNumericLiteral";
+export * from "./IsScalar";
 export * from "./IsStringLiteral";
 export * from "./IsLiteral";
+export * from "./Extends";
+export * from "./TypeDefault";
+export * from "./IsObject";

package/src/types/alphabetic/Cardinality.ts

@@ -0,0 +1,80 @@
+import { UnionToTuple } from "../type-conversion";
+
+export type OneToOne = `1:1`;
+export type OneToMany = `1:M`;
+export type OneToZero = `1:0`;
+export type ZeroToOne = `0:1`;
+export type ZeroToMany = `0:M`;
+export type ZeroToZero = `0:0`;
+export type ManyToMany = "M:M";
+export type ManyToOne = "M:1";
+export type ManyToZero = "M:0";
+
+export type CardinalityNode = "0" | "1" | "M";
+
+/**
+ * Cardinality which expects a singular input and requires
+ * 1 or many outputs.
+ *
+ * Note: choose `CardinalityFilter1` if you want to allow output
+ * to have no outputs.
+ */
+export type Cardinality1 = OneToOne | OneToMany;
+
+/**
+ * Cardinality which expects a singular input and maps to 0,
+ * 1, or many outputs.
+ */
+export type CardinalityFilter1 = OneToOne | OneToMany | OneToZero;
+
+/**
+ * Cardinality which expects a singular input which is allowed to be
+ * _undefined_ or the expected type.
+ */
+export type Cardinality0 = ZeroToOne | ZeroToMany | OneToOne | OneToMany;
+
+/**
+ * Cardinality which expects a singular input -- which is allowed to be
+ * _undefined_ -- and maps to 0,
+ * 1, or many outputs.
+ */
+export type CardinalityFilter0 =
+  | ZeroToOne
+  | ZeroToMany
+  | OneToOne
+  | OneToMany
+  | OneToZero
+  | ZeroToZero;
+
+export type CardinalityExplicit = `${number}:${number}`;
+
+/**
+ * Cardinality of any sort between two types
+ */
+export type Cardinality =
+  | CardinalityFilter0
+  | CardinalityFilter1
+  | ManyToMany
+  | ManyToOne
+  | ManyToZero
+  | CardinalityExplicit;
+
+export type CardinalityTuple<T extends Cardinality> = UnionToTuple<T>;
+
+/**
+ * The first or _input_ part of the Cardinality relationship
+ */
+export type CardinalityIn<T extends Cardinality> = T extends `${infer IN}:${string}` ? IN : never;
+
+/**
+ * The second or _output_ part of the Cardinality relationship
+ */
+export type CardinalityOut<T extends Cardinality> = T extends `${string}:${infer OUT}`
+  ? OUT
+  : never;
+
+export type CardinalityInput<T, C extends Cardinality> = CardinalityTuple<C>[0] extends 0
+  ? T | undefined
+  : CardinalityTuple<C>[0] extends 1
+  ? T
+  : T[];

package/src/types/alphabetic/index.ts

@@ -9,6 +9,7 @@ export * from "./CamelCase";
 export * from "./CapitalizeWords";
 export * from "./DashToSnake";
 export * from "./DashUppercase";
+export * from "./Cardinality";
 export * from "./Dasherize";
 export * from "./HasUppercase";
 export * from "./IsCapitalized";