inferred-types 0.33.0 → 0.33.2

package/src/{utility → runtime}/dictionary/kv/dictToKv.ts

@@ -2,7 +2,7 @@ import { KvFrom } from "src/types/kv";
 import { Mutable } from "src/types/Mutable";
 import { Narrowable } from "src/types/Narrowable";
 import { UnionToTuple } from "src/types/type-conversion";
-import { keys } from "src/utility/keys";
+import { keys } from "src/runtime/keys";
 
 /**
  * Converts a dictionary object into an array of dictionaries with `key` and `value` properties

package/src/{utility → runtime}/dictionary/kv/filterDictArray.ts

@@ -1,5 +1,5 @@
 import { DictArray, DictArrayFilterCallback } from "src/types/tuples";
-import { Configurator, IConfigurator } from "src/utility/state";
+import { Configurator, IConfigurator } from "src/runtime/state";
 
 export interface Array<T> {
   filter<U extends T>(pred: (a: T) => a is U): U[];

package/src/{utility → runtime}/index.ts

@@ -10,12 +10,10 @@ export * from "./keys";
 export * from "./ruleset";
 // directory exports
 export * from "./api/index";
-export * from "./boolean-logic/index";
+export * from "./combinators/index";
 export * from "./dictionary/index";
-export * from "./errors/index";
 export * from "./lists/index";
 export * from "./literals/index";
-export * from "./modelling/index";
 export * from "./runtime/index";
 export * from "./state/index";
 

package/src/runtime/literals/Suggest.ts

@@ -0,0 +1,19 @@
+/**
+ * **Suggest**
+ *
+ * Type utility that helps to build a enumerated set
+ * of string literals which _could_ be the value for
+ * a string based property but _allows_ a string that
+ * is not part of the suggestion to be typed in too.
+ */
+export type Suggest<T extends string> = T | (string & {});
+
+/**
+ * **SuggestNumeric**`<T>`
+ *
+ * Type utility that helps to build a enumerated set
+ * of numeric literals which _could_ be the value for
+ * a number based property but _allows_ a number that
+ * is not part of the suggestion to be typed in too.
+ */
+export type SuggestNumeric<T extends number> = T | (number & {});

package/src/runtime/literals/box.ts

@@ -0,0 +1,77 @@
+import { AfterFirst, Narrowable } from "src/types";
+import { First } from "src/types/lists/First";
+
+export interface Box<T> {
+  __kind: "box";
+  value: T;
+  /**
+   * Unbox the boxed value in the narrowest possible type.
+   *
+   * **Note:** _if you want a wider type definition use `wide()`
+   * instead._
+   */
+  unbox(): T;
+  // /**
+  //  * If the boxed value is a function with generics then you have opportunity to
+  //  * _narrow_ the type definition over time. This is achieved in a type strong manner,
+  //  * so you can't change the fundamental type but this example will work as expected:
+  //  * ```ts
+  //  * const fn = <T extends string>(name: T) => `Hello ${name}` as const;
+  //  * const b = box(fn);
+  //  * // later
+  //  * const b2 = b.narrow<"foo" | "bar">();
+  //  * ```
+  //  */
+  // narrow: NarrowBox<T>;
+}
+
+export type BoxValue<T extends Box<any>> = T extends Box<infer V> ? V : never;
+
+export type BoxedFnParams<T extends Box<any>> = T extends Box<infer V>
+  ? V extends (...args: infer A) => any
+    ? A
+    : []
+  : [];
+
+export type BoxedReturn<T extends Box<any>> = T extends Box<infer V>
+  ? V extends Function
+    ? ReturnType<T["value"]>
+    : T["value"]
+  : never;
+
+export type NarrowBox<T> = <
+  N extends BoxedFnParams<Box<T>> | First<BoxedFnParams<Box<T>>>
+>() => N extends BoxedFnParams<Box<T>>
+  ? T extends (...args: any[]) => any
+    ? (...args: N) => Box<T>["unbox"]
+    : never
+  : (first: N, ...rest: AfterFirst<BoxedFnParams<Box<T>>>) => BoxedReturn<Box<T>>;
+
+/**
+ * Allows a value with an inner-type to be boxed into a dictionary
+ * so that this type inference is preserved with the help of
+ * [instantiation expressions](https://devblogs.microsoft.com/typescript/announcing-typescript-4-7-beta/#instantiation-expressions).
+ *
+ * NOTE: this feature is immature at best right now
+ */
+export function box<T extends Narrowable>(value: T): Box<T> {
+  const rtn: Box<T> = {
+    __kind: "box",
+    value,
+    unbox: () => value,
+  };
+
+  return rtn;
+}
+
+export function isBox(thing: unknown): thing is Box<any> {
+  return (
+    typeof thing === "object" && "__kind" in (thing as object) && (thing as any).__kind === "box"
+  );
+}
+
+export type Unbox<T> = T extends Box<infer U> ? U : T;
+
+export function unbox<T>(thing: T): Unbox<T> {
+  return isBox(thing) ? thing.unbox() : thing;
+}

package/src/{utility → runtime}/literals/index.ts

@@ -6,9 +6,11 @@
 // file exports
 export * from "./ExplicitFunction";
 export * from "./arrayToObject";
+export * from "./box";
 export * from "./defineType";
 export * from "./identity";
 export * from "./literal";
+export * from "./Suggest";
 
 // #endregion auto-indexed files
 

package/src/{utility → runtime}/runtime/index.ts

@@ -5,11 +5,10 @@
 
 // file exports
 export * from "./condition";
-export * from "./ifTypeOf";
 export * from "./type";
 export * from "./withValue";
 // directory exports
-export * from "./conditions/index";
+export * from "../type-checks/index";
 
 // #endregion auto-indexed files
 

package/src/{utility → runtime}/runtime/type.ts

@@ -14,7 +14,7 @@ import {
   isObject,
   isArray,
   ObjectType,
-} from "./conditions";
+} from "../type-checks";
 // import { isLiteral } from "./conditions/isLiteral";
 
 export type Type<T extends any, V extends Function> = {

package/src/{utility/runtime/conditions → runtime/type-checks}/isFunction.ts

@@ -2,6 +2,15 @@ import { FunctionType } from "src/types/FunctionType";
 
 export type IsFunction<T> = T extends FunctionType ? true : false;
 
+export type HybridFunction<TProps extends {}> = (<TArgs extends any[]>(...args: TArgs) => any) &
+  TProps;
+
+export type SimpleFunction = <TArgs extends any[]>(...args: TArgs) => any;
+
+export type AnyFunction<TProps extends {} | never = never> = TProps extends {}
+  ? HybridFunction<TProps>
+  : SimpleFunction;
+
 /**
  * Checks whether a passed in value is a function and ensures run-time and types
  * are consistent.
@@ -14,6 +23,6 @@ export type IsFunction<T> = T extends FunctionType ? true : false;
  * encountered but if that function also has object types defined then the type will be a big
  * and ugly union type. This function will give you a proper boolean value in both cases.
  */
-export function isFunction<T extends unknown>(input: T): IsFunction<T> {
-  return (typeof input === "function") as IsFunction<T>;
+export function isFunction<T>(input: T): IsFunction<T> {
+  return (typeof input === "function" ? true : false) as IsFunction<T>;
 }

package/src/{utility/runtime/conditions → runtime/type-checks}/isObject.ts

@@ -1,5 +1,5 @@
 import { FunctionType, Narrowable, Not } from "src/types";
-import { IsObject } from "src/types/TypeInfo";
+import { IsObject } from "src/types/type-checks";
 
 export type ObjectType = Not<Record<string, Narrowable>, FunctionType>;
 

package/src/{utility/runtime/conditions → runtime/type-checks}/isString.ts

@@ -1,7 +1,15 @@
-import { Narrowable } from "src/types";
-
-export type IsString<T> = T extends string ? true : false;
+import { Narrowable } from "src/types/Narrowable";
+import { IfString, IsString } from "src/types/type-checks/string";
 
+/**
+ * **isString**
+ *
+ * Returns true or false on whether the passed in parameter is a
+ * string (either a wide string or a string literal).
+ *
+ * The boolean return is traceable by the type system as well as the
+ * runtime system.
+ */
 export function isString<T>(i: T) {
   return (typeof i === "string") as IsString<T>;
 }
@@ -13,7 +21,7 @@ export function isString<T>(i: T) {
  * a _string_ and returns one of two values (strongly typed) based on the evaluation
  * of this criteria.
  *
- * @param val the value being tested
+ * @param val the value being tested for being a string
  * @param ifVal the value (strongly typed) returned if val is _string_
  * @param elseVal the value (strongly typed) returned if val is NOT a _string
  */
@@ -22,5 +30,5 @@ export function ifString<T extends Narrowable, IF extends Narrowable, ELSE exten
   ifVal: IF,
   elseVal: ELSE
 ) {
-  return (isString(val) ? ifVal : elseVal) as IsString<T> extends true ? IF : ELSE;
+  return (isString(val) ? ifVal : elseVal) as IfString<T, IF, ELSE>;
 }

package/src/{utility/runtime/conditions → runtime/type-checks}/isTrue.ts

@@ -42,6 +42,6 @@ export function isTrue<T extends Narrowable>(i: T) {
  * @param ifVal the value (strongly typed) returned if val is _true_ value
  * @param elseVal the value (strongly typed) returned if val is NOT a _true_ value
  */
-export function ifTrue<T, IF, ELSE>(val: T, ifVal: IF, elseVal: ELSE) {
+export function ifTrue<T extends Narrowable, IF, ELSE>(val: T, ifVal: IF, elseVal: ELSE) {
   return (isTrue(val) ? ifVal : elseVal) as IsTrue<T> extends true ? IF : ELSE;
 }

package/src/{utility/runtime/conditions → runtime/type-checks}/isUndefined.ts

@@ -1,5 +1,5 @@
 import { Narrowable } from "src/types";
-import { IsUndefined } from "src/types/TypeInfo/IsUndefined";
+import { IsUndefined } from "src/types/type-checks/IsUndefined";
 
 export function isUndefined<T extends Narrowable>(i: T) {
   return (typeof i === "undefined") as undefined extends T ? true : false;

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

@@ -0,0 +1,109 @@
+import { IfStartsWith, StartsWith } from "src/types/type-checks";
+import { IfUndefined } from "src/types/type-checks/IsUndefined";
+import { createFnWithProps } from "../createFnWithProps";
+import { box, Box } from "../literals";
+import { ifTrue } from "./isTrue";
+
+/**
+ * **startsWith**
+ *
+ * A higher-order and type strong way to checking whether a string literal `<T>` starts with
+ * another known string literal `<S>`:
+ * ```ts
+ * const answer = startsWith("foo")("foobar");
+ * ```
+ */
+export const startsWith =
+  <S extends string>(
+    /** The starting string you will test for */
+    start: S
+  ) =>
+  <T extends string>(
+    /** The text being tested */
+    input: T
+  ): StartsWith<T, S> => {
+    return input.startsWith(start) as StartsWith<T, S>;
+  };
+
+/**
+ * **IfStartsWithFn**
+ *
+ * A function which comes from a partial application of the `ifStartsWith()`
+ * utility. This type will receive a value `<T>` and _if_ this values starts
+ * with `<S>` then the callback function will executed in a type strong manner.
+ */
+export type IfStartsWith__Fn<
+  /** The "start with" constraint */
+  TStartsWith extends string,
+  TIf extends Box<<T extends string>(i: `${TStartsWith}${T}`) => any>,
+  TElse extends Box<(<T extends string>(i: T) => any) | undefined>
+> = <T extends string>(
+  val: T
+) => IfStartsWith<
+  T, //
+  TStartsWith,
+  // Condition Passes
+  ReturnType<TIf["value"]>,
+  // Condition Fails
+  IfUndefined<
+    TElse, //
+    undefined,
+    Exclude<TElse, undefined>
+  >
+>;
+
+export type NarrowFn<N extends string> = <F extends <T extends string>(input: T) => any>(
+  fn: F
+) => (input: N) => Box<F>["unbox"];
+
+export const stringLiteralFn = <F extends <T extends string>(input: T) => any>(fn: F) => {
+  const b = box(fn);
+  const api = {
+    narrow<N extends string>() {
+      return (input: N) => b.unbox()(input);
+    },
+  };
+
+  return createFnWithProps(fn, api);
+};
+
+export type StringLiteralFn<S extends string = string> = <T extends S>(input: T) => any;
+
+/**
+ * **ifStartsWith**
+ *
+ * Type strong way to move into a conditional execution block:
+ * ```ts
+ * // partial application
+ * const mutate = ifStartsWith(
+ *    "foo",
+ *    i => `${i} is a foo`,
+ *    i => `${i} ain't welcome in this town`
+ * );
+ * // type: `foobar is a foo`
+ * const outcome = mutate("foobar");
+ * ```
+ *
+ * Where the variable `i` will _extend_ a string and function which this utility
+ * returns is able to
+ */
+export const ifStartsWith =
+  <
+    TStartsWith extends string,
+    TIf extends <T extends string>(input: T) => any,
+    TElse extends <T extends string>(input: T) => any
+  >(
+    /** the string literal _start value_ which a string must begin with */
+    start: TStartsWith,
+    /** a mutation function when a value _does_ start with `TStartsWith` */
+    isTrue: TIf,
+    /** an optional mutation function */
+    isFalse: TElse
+  ) =>
+  <I extends string>(input: I) =>
+    ifTrue(
+      // condition
+      startsWith(start)(input),
+      isTrue(input),
+      isFalse(input)
+    ) as IfStartsWith<I, TStartsWith, ReturnType<TIf>, ReturnType<TElse>>;

package/src/types/FunctionType.ts

@@ -1,9 +1,19 @@
 /**
- * Defines a function type.
+ * **FunctionType**
+ *
+ * Provides a way to correctly match for regular functions _and_ functions which
+ * also have a dictionary hash alongside the root function.
  *
  * - without the generic `T` specified it simply matches correctly on both plain functions as well as functions which also have properties on them (this is consistent to how runtime's `typeof` operator works)
  * - with the generic you can specify the shape of the key/values
  */
 export type FunctionType<T extends {} = {}> = {} extends T
   ? Function | (Function & { [key: string]: any })
-  : Function | (Function & T);
+  : Function | (Function & T);
+
+/**
+ * **FnShape**
+ *
+ * Simple way to express the shape of a function's arguments and return type.
+ */
+export type FnShape<A extends any[] = any[], R extends any = any> = (...args: A) => R;

package/src/types/Mutable.ts

@@ -1,4 +1,4 @@
-import { IsObject } from "./TypeInfo";
+import { IsObject } from "./type-checks";
 
 /**
  * Makes a readonly structure mutable

package/src/types/alphabetic/Url.ts

@@ -0,0 +1,29 @@
+import { AlphaNumeric, Ipv4, VariableName } from "./alpha-characters";
+
+export type NetworkProtocol = "http" | "https" | "file" | "ws" | "wss";
+
+/**
+ * A literal variant of _string_ which is meant to represent a domain name
+ * (e.g., `www.someplace.com`, etc.)
+ */
+export type DomainName =
+  | `${AlphaNumeric}${string}.${AlphaNumeric}${string}`
+  | `${AlphaNumeric}${string}.${AlphaNumeric}${string}.${string}`
+  | `${AlphaNumeric}${string}.${AlphaNumeric}${string}.${string}.${string}`;
+
+export type RelativeUrl = `${VariableName | "/"}`;
+
+/**
+ * A literal variant of _string_ which forces a string to follow conventions
+ * for a fully qualified URL like `https://google.com`. It can't ensure the
+ * type is fully valid but does help to avoid some typos.
+ */
+export type FullyQualifiedUrl = `${NetworkProtocol}://${Ipv4 | DomainName}/${string}`;
+
+export type UrlBuilder =
+  | (<P extends NetworkProtocol, D extends DomainName, B extends RelativeUrl>(
+      protocol: P,
+      domain: D,
+      basePath: B
+    ) => `${P}://${D}/${B}`)
+  | (<U extends RelativeUrl>(url: U) => U);

package/src/types/alphabetic/alpha-characters.ts

@@ -65,9 +65,17 @@ export type NumericString = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8"
  */
 export type AlphaNumeric = Alpha | NumericString;
 
+/**
+ * Allows alphanumeric characters and some special characters typically allowed
+ * in variable names.
+ */
+export type VariableName = AlphaNumeric | "_" | "." | "-";
+
 export type SpecialCharacters = "@" | "~" | "^" | "#" | "&" | "*";
 
 /**
  * Non-alphabetic characters including whitespace, string numerals, and
  */
 export type NonAlpha = Whitespace | Punctuation | NumericString | Bracket | SpecialCharacters;
+
+export type Ipv4 = `${number}.${number}.${number}.${number}`;

package/src/types/alphabetic/index.ts

@@ -19,6 +19,7 @@ export * from "./PascalCase";
 export * from "./Pluralize";
 export * from "./SnakeCase";
 export * from "./alpha-characters";
+export * from "./Url";
 
 // #endregion auto-indexed files
 

package/src/types/dictionary/MapTo.ts

@@ -4,9 +4,9 @@ import {
   DefaultManyToOneMapping,
   DefaultOneToManyMapping,
   DefaultOneToOneMapping,
-} from "src/utility/dictionary/mapTo";
+} from "src/runtime/dictionary/mapTo";
 import { EnumValues } from "../EnumValues";
-import { TypeDefault } from "../TypeInfo/TypeDefault";
+import { TypeDefault } from "../type-checks/TypeDefault";
 
 /**
  * Expresses relationship between inputs/outputs:

package/src/types/index.ts

@@ -8,7 +8,7 @@ export * from "./Api";
 export * from "./Constructor";
 export * from "./EnumValues";
 export * from "./ExpandRecursively";
-export * from "./First";
+export * from "./lists/First";
 export * from "./FunctionType";
 export * from "./If";
 export * from "./Include";
@@ -41,7 +41,7 @@ export * from "./literal-unions/index";
 export * from "./string-literals/index";
 export * from "./tuples/index";
 export * from "./type-conversion/index";
-export * from "./TypeInfo/index";
+export * from "./type-checks/index";
 
 // #endregion auto-indexed files
 

package/src/types/lists/AfterFirst.ts

@@ -0,0 +1,10 @@
+/**
+ * **AfterFirst**`<T>`
+ *
+ * returns the elements in an array _after_ the first element
+ */
+export type AfterFirst<T extends readonly any[]> = T extends readonly [any, ...any[]]
+  ? T extends readonly [any, ...infer Rest]
+    ? Rest
+    : never
+  : T;

package/src/types/lists/First.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns the first values type in an array of values
+ */
+export type First<T extends readonly any[]> = T[0] extends T[number] ? T[0] : never;
+
+export type FirstOrUndefined<T extends unknown> = T extends [unknown, ...[unknown]]
+  ? First<T>
+  : undefined;

package/src/types/lists/FirstString.ts

@@ -0,0 +1,4 @@
+/**
+ * returns the first `string` value from an array of values
+ */
+export type FirstString<T> = T extends [infer S extends string, ...unknown[]] ? S : never;

package/src/types/lists/Split.ts

@@ -0,0 +1,21 @@
+/**
+ * **Split**`<T, SEP>`
+ *
+ * Splits a string literal `T` by string literal _separator_ `SEP`. The result is an array
+ * of string literals.
+ */
+export type Split<
+  T extends string,
+  SEP extends string,
+  ANSWER extends string[] = []
+> = string extends T
+  ? // wide string so we can only return wide string[]
+    string[]
+  : T extends SEP
+  ? // the string === separator results in empty array
+    ANSWER
+  : // test whether can recurse
+  T extends `${infer HEAD}${SEP}${infer TAIL}`
+  ? // recurse to produce strong literal type
+    Split<TAIL, SEP, [...ANSWER, HEAD]>
+  : [...ANSWER, T];

package/src/types/lists/index.ts

@@ -5,6 +5,10 @@
 // hash-code: 582c0cf0
 
 // file exports
+export * from "./AfterFirst";
+export * from "./First";
+export * from "./FirstString";
+export * from "./Split";
 export * from "./UniqueForProp";
 
 // #endregion auto-indexed files

package/src/types/ruleset-types.ts

@@ -1,4 +1,4 @@
-import { TypeCondition } from "src/utility/runtime";
+import { TypeCondition } from "src/runtime/type-checks/ifTypeOf";
 import { OptionalKeys } from "./dictionary/props";
 import { SameKeys } from "./dictionary/SameKeys";