inferred-types 0.51.0 → 0.51.1

package/src/runtime/literals/box.ts

@@ -0,0 +1,75 @@
+import type {
+  Narrowable,
+  Box,
+  AnyObject,
+} from "inferred-types/dist/types/index";
+
+
+export type BoxValue<T extends Box<unknown>> = T extends Box<infer V> ? V : never;
+
+export type BoxedFnParams<T extends Box<unknown>> = T extends Box<infer V>
+  ? V extends (...args: infer A) => unknown
+    ? A
+    : []
+  : [];
+
+
+/**
+ * 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> = {
+    __type: "box",
+    value,
+    unbox: (<P extends unknown[], R extends Narrowable>(...p: P): R => {
+      return typeof value === "function" ? value(...p) : value;
+    }) as Box<T>["unbox"],
+  };
+
+  return rtn;
+}
+
+export function isBox(thing: Narrowable): thing is Box<unknown> {
+  return (
+
+    typeof thing === "object" && "__type" in (thing as object) && (thing as any).__type === "box"
+  );
+}
+
+/**
+ * **boxDictionaryValues**(dict)
+ *
+ * Runtime utility which boxes each value in a dictionary
+ */
+export function boxDictionaryValues<T extends AnyObject>(dict: T) {
+  const keys = Object.keys(dict) as (string & keyof T)[] ;
+
+  return keys.reduce(
+    (acc, key) => ({ ...acc, [key]: box(dict[key] as Narrowable) }),
+    {} as {
+      [K in keyof T]: Box<T[K]>;
+    }
+  );
+}
+
+export type Unbox<T> = T extends Box<infer U> ? U : T;
+
+//TODO: it would make sense in the future to use `b.unbox` instead
+// of `b.value` to keep consistent but currently value behaves more
+// consistently and with somewhat stronger typing
+
+/**
+ * **unbox**(maybeBox)
+ *
+ * Unboxes a value if it was a box; otherwise it leaves _as is_.
+ */
+export function unbox<T extends Narrowable>(val: T): Unbox<T> {
+  return (isBox(val)
+    ? val.value
+    : val
+  ) as Unbox<T>;
+}

package/src/runtime/literals/capitalize.ts

@@ -0,0 +1,9 @@
+/**
+ * **capitalize**()
+ * 
+ * Run time utility which _un_-capitalizes a word/string and preserves
+ * string literal types.
+ */
+export function capitalize<T extends string>(str: T): Capitalize<T> {
+  return `${str?.slice(0,1).toUpperCase()}${str?.slice(1)}` as Capitalize<T>;
+}

package/src/runtime/literals/color/cssColor.ts

@@ -0,0 +1,31 @@
+import { ColorFnOptOpacity, ColorFnValue, CssColorFn, CssColorSpace} from "inferred-types/dist/types/index";
+
+/**
+ * **cssColor**`(colorspace, v1, v2, v3, [opacity]) -> CssColorFn`
+ *
+ * Produces a string literal for a CSS v4 `color()` function.
+ */
+export const cssColor = <
+  TColorSpace extends CssColorSpace,
+  TV1 extends ColorFnValue,
+  TV2 extends ColorFnValue,
+  TV3 extends ColorFnValue,
+  TOp extends undefined | ColorFnOptOpacity
+  >(
+    color: TColorSpace,
+    v1: TV1,
+    v2: TV2,
+    v3: TV3,
+    opacity?: TOp
+  ) => {
+    return `color(${color} ${v1} ${v2} ${v3}${opacity ? ` / ${opacity}`: ""}` as CssColorFn<
+      TColorSpace,
+      TV1,
+      TV2,
+      TV3,
+      TOp extends ` / ${number}`
+      ? TOp
+      : ""
+    >
+  }
+

package/src/runtime/literals/color/index.ts

@@ -0,0 +1,2 @@
+export * from "./twColor";
+export * from "./cssColor";

package/src/runtime/literals/color/twColor.ts

@@ -0,0 +1,40 @@
+import {
+  TwColor,
+  TwLuminosity,
+  TwLuminosityLookup,
+  TwChromaLookup,
+  TwHue
+} from "inferred-types/dist/types/index";
+import { TW_CHROMA, TW_LUMINOSITY, TW_HUE } from "inferred-types/dist/constants/index"
+
+
+
+type Rtn<
+  TColor extends TwColor,
+  TLum extends TwLuminosity
+> =
+TLum extends keyof TwLuminosityLookup
+? TLum extends keyof TwChromaLookup
+  ? TColor extends keyof TwHue
+    ? `oklch(${TwLuminosityLookup[TLum]} ${TwChromaLookup[TLum]} ${TwHue[TColor]}) `
+    : never
+  : never
+: never;
+
+/**
+ * Provides a Tailwind Color using the `oklch` color
+ * specification. The output is intended to put into
+ * a CSS property.
+ */
+export const twColor = <
+  TColor extends TwColor,
+  TLum extends TwLuminosity
+>(
+  color: TColor,
+  luminosity: TLum
+) => {
+  const lum = TW_LUMINOSITY[luminosity];
+  const chroma = TW_CHROMA[luminosity];
+  const hue = TW_HUE[color];
+  return `oklch(${lum} ${chroma} ${hue})` as unknown as Rtn<TColor,TLum>
+}

package/src/runtime/literals/ensureLeading.ts

@@ -0,0 +1,27 @@
+import {  EnsureLeading } from "inferred-types/dist/types/index";
+import { isString } from "../type-guards/isString";
+
+/**
+ * **ensureLeading**(content, strip)
+ *
+ * Runtime utility which ensures that last part of a string -- `content` -- has the
+ * substring `ensure` at the end and adds it if not present.
+ */
+export function ensureLeading<
+  T extends string | number,
+  U extends string | number
+>(
+  content: T,
+  ensure: U
+) {
+  let output: string = String(content);
+
+  return (
+    output.startsWith(String(ensure))
+      ? content
+      : isString(content)
+        ? `${ensure}${content}`
+        : Number(`${ensure}${content}`)
+  )  as EnsureLeading<T,U>
+
+}

package/src/runtime/literals/ensureSurround.ts

@@ -0,0 +1,32 @@
+import { EnsureSurround } from "inferred-types/dist/types/index";
+import { ensureLeading, ensureTrailing } from "src/runtime/index";
+
+/**
+ * **ensureSurround**(prefix, postfix) -> (input) -> `${prefix}${input}${postfix}`
+ *
+ * A higher order runtime utility which receives a prefix and postfix string
+ * on it's first call. This returns a secondary function which will _ensure_
+ * the given prefix/postfix's surround the input (without duplicating the
+ * prefix/postfix characters if they were already there).
+ *
+ * **Related:** `surround()`
+ */
+export function ensureSurround<
+  TPrefix extends string,
+  TPostfix extends string
+>(prefix: TPrefix, postfix: TPostfix) {
+
+  const fn = <TInput extends string>(
+    input: TInput
+  ): EnsureSurround<TInput, TPrefix, TPostfix> => {
+    let result: string = input;
+
+    result = ensureLeading(result, prefix);
+    result = ensureTrailing(result, postfix);
+
+    return result as EnsureSurround<TInput, TPrefix, TPostfix>;
+  }
+
+  return fn;
+}
+

package/src/runtime/literals/ensureTrailing.ts

@@ -0,0 +1,20 @@
+import { EnsureTrailing } from "inferred-types/dist/types/index";
+
+/**
+ * **ensureTrailing**(content, strip)
+ *
+ * Runtime utility which ensures that last part of a string -- `content` -- has the
+ * substring `ensure` at the end and adds it if not present.
+ */
+export function ensureTrailing<
+  T extends string,
+  U extends string
+>(
+  content: T,
+  ensure: U
+): EnsureTrailing<T, U> {
+  return (
+    //
+    (content.endsWith(ensure) ? content : `${content}${ensure}`) as EnsureTrailing<T, U>
+  );
+}

package/src/runtime/literals/identity.ts

@@ -0,0 +1,22 @@
+import { Narrowable } from "inferred-types/dist/types/index";
+
+
+/**
+ * An identity function for any type, with the goal of preserving literal type information
+ * where ever possible.
+ */
+export const identity = <
+N extends Narrowable,
+K extends PropertyKey,
+T extends readonly (Record<K,N> | N)[]
+>(...values: T) => (
+  values.length === 1
+  ? values[0]
+  : values.length === 0
+    ? undefined
+    : values
+ ) as T["length"] extends 1
+  ? T[0]
+  : T["length"] extends 0
+    ? undefined
+    : T;

package/src/runtime/literals/ifLowercase.ts

@@ -0,0 +1,57 @@
+
+import { LOWER_ALPHA_CHARS } from "inferred-types/dist/constants/index";
+import { AfterFirst, If, Extends, LowerAlphaChar } from "inferred-types/dist/types/index";
+
+
+type _Index<
+  T extends readonly string[],
+  IF,
+  ELSE,
+  Results extends readonly unknown[] = []
+> = [] extends T
+  ? Results
+  : _Index<
+      AfterFirst<T>,
+      IF,
+      ELSE,
+      [
+        ...Results,
+        If<Extends<T, LowerAlphaChar>, IF, ELSE>
+      ]
+    >;
+
+type Returns<
+  T extends string | readonly string[],
+  IF,
+  ELSE
+> = T extends string
+  ? If<Extends<T, LowerAlphaChar>, IF, ELSE>
+  : T extends readonly string[]
+    ? _Index<T, IF, ELSE>
+    : never;
+
+
+/**
+ * **ifLowercaseChar**(ch)
+ *
+ * Tests whether a passed in character is lowercase and then uses the appropriate callback to
+ * mutate the value.
+ */
+export function ifLowercaseChar<
+  T extends string,
+  IF,
+  ELSE
+>(
+  ch: T,
+  callbackForMatch: <V extends T>(v: V) => IF,
+  callbackForNoMatch: <V extends T>(v: V) => ELSE
+  ): Returns<T, IF, ELSE> {
+    if (ch.length !== 1) {
+      throw new Error(`call to ifUppercaseChar received ${ch.length} characters but is only valid when one character is passed in!`);
+    }
+    return (
+      LOWER_ALPHA_CHARS.includes(ch as any)
+      ? callbackForMatch(ch)
+      : callbackForNoMatch(ch)
+    ) as Returns<T, IF, ELSE>;
+  }

package/src/runtime/literals/ifUppercase.ts

@@ -0,0 +1,34 @@
+
+import { LOWER_ALPHA_CHARS } from "inferred-types/dist/constants/index";
+import { Extends, If, IsSingleChar, Narrowable,  UpperAlphaChar, ValueCallback } from "inferred-types/dist/types/index";
+
+type Convert<T, IF, ELSE> = If<Extends<T, UpperAlphaChar>, IF, ELSE>;
+
+/**
+ * **ifUppercaseChar**(ch, callbackForMatch, callbackForNoMatch)
+ *
+ * Tests whether a passed in _character_ is an uppercase character and uses appropriate callback
+ * to mutate the value.
+ *
+ * **Related:** `ifUppercase()`
+ */
+export function ifUppercaseChar<
+  T extends string,
+  IF extends Narrowable,
+  ELSE extends Narrowable
+>(
+  /** the character to be tested */
+  ch: T & IsSingleChar<T> extends true ? T : never,
+  callbackForMatch: ValueCallback<T, IF>,
+  callbackForNoMatch: ValueCallback<T, ELSE>
+): Convert<T,IF,ELSE> {
+  if(ch.length !== 1) {
+    throw new Error(`Invalid string length passed to ifUppercaseChar(ch); this function requires a single character but ${ch.length} were received`);
+  }
+  return (
+    LOWER_ALPHA_CHARS.includes(ch as any)
+      ? callbackForMatch(ch)
+      : callbackForNoMatch(ch)
+  ) as Convert<T,IF,ELSE>;
+}
+

package/src/runtime/literals/index.ts

@@ -0,0 +1,58 @@
+// #autoindex
+// #region auto-indexed files
+// index last changed at: 8th Aug, 2022, 09:51 AM ( GMT-7 )
+// hash-code: 7a22bbbc
+
+// file exports
+export * from "./box";
+export * from "./identity";
+export * from "./literal";
+export * from "./stripTrailing";
+export * from "./stripLeading";
+export * from "./ensureTrailing";
+export * from "./ensureLeading";
+export * from "./ensureSurround";
+export * from "./ifUppercase";
+export * from "./pathJoin";
+export * from "./narrow";
+export * from "./split";
+export * from "./tuple";
+export * from "./capitalize";
+export * from "./uncapitalize";
+export * from "./uppercase";
+export * from "./lowercase";
+export * from "./widen";
+export * from "./toCamelCase";
+export * from "./toKebabCase";
+export * from "./ifLowercase";
+export * from "./toSnakeCase";
+export * from "./toString";
+export * from "./pluralize";
+export * from "./retainAfter";
+export * from "./surround";
+export * from "./stripAfter";
+export * from "./stripBefore";
+export * from "./stripSurround";
+export * from "./stripUntil";
+export * from "./trim";
+export * from "./toPascalCase";
+export * from "./toUppercase";
+export * from "./toNumericArray";
+export * from "./truncate";
+export * from "./takeNumericCharacters";
+export * from "./retainChars";
+export * from "./stripChars";
+export * from "./retainWhile";
+export * from "./rightWhitespace";
+export * from "./retainUntil";
+export * from "./stripWhile";
+
+
+export * from "./phone/index";
+export * from "./color/index";
+
+
+// #endregion auto-indexed files
+
+// see https://github.com/inocan-group/do-devops/docs/autoindex.md
+// for more info

package/src/runtime/literals/literal.ts

@@ -0,0 +1,48 @@
+/* eslint-disable no-use-before-define */
+
+import { Narrowable } from "inferred-types/dist/types/index";
+
+/**
+ * Takes an object as input --which has an `id` property and returns it as the same
+ * run-time content but with the _type_ of the `id` property being forced to a literal type
+ */
+export function idLiteral<T extends { id: I }, I extends PropertyKey>(o: T): T & { id: T["id"] } {
+  return { ...o, id: o.id };
+}
+
+/**
+ * Takes an object as input --which has an `name` property and returns it as the same
+ * run-time content but with the _type_ of the `name` property being forced to a literal type
+ */
+export function nameLiteral<T extends { name: I }, I extends PropertyKey>(
+  o: T
+): T & { name: T["name"] } {
+  return o;
+}
+
+/**
+ * Takes an object as input --which has an `kind` property and returns it as the same
+ * run-time content but with the _type_ of the `kind` property being forced to a literal type
+ */
+export function kindLiteral<T extends { kind: I }, I extends PropertyKey>(
+  o: T
+): T & { kind: T["kind"] } {
+  return o;
+}
+
+export function idTypeGuard<T extends { id: I }, I extends PropertyKey>(
+  _o: T
+): _o is T & { id: I } {
+  return true;
+}
+
+/**
+ * Takes an object as input and infers the narrow literal types of the property
+ * values on the object.
+ *
+ * > Note: this addresses this [a known TS gap](https://github.com/microsoft/TypeScript/issues/30680).
+ * > Hopefully at some point this will be addressed in the language.
+ */
+export function literal<N extends Narrowable, T extends Record<keyof T, N>>(obj: T) {
+  return obj;
+}

package/src/runtime/literals/lowercase.ts

@@ -0,0 +1,11 @@
+
+
+/**
+ * **lowercase**()
+ * 
+ * Run time utility which ensures all letters are lowercase while preserving
+ * string literal types.
+ */
+export function lowercase<T extends string>(str: T): Lowercase<T> {
+  return str.toLowerCase() as Lowercase<T>;
+}

package/src/runtime/literals/narrow.ts

@@ -0,0 +1,44 @@
+import {
+  First,
+  IsUnion,
+  Length,
+  Narrowable,
+  UnionToTuple,
+} from "inferred-types/dist/types/index";
+
+/**
+ * **narrow**(value)
+ *
+ * An identity function which provides the input in as narrow a form
+ * as possible.
+ * ```ts
+ * const s = narrow("foo"); // "foo"
+ * const n = narrow(42); // 42
+ * // ["foo", "bar"]
+ * const t1 = narrow(["foo", "bar"] as const);
+ * const t2 = narrow("foo", "bar");
+ * // string`[]
+ * const t3 = narrow(["foo", "bar"]);
+ * ```
+ */
+export function narrow<
+  N extends Narrowable,
+  K extends PropertyKey,
+  T extends readonly (Record<K,N> | N)[]
+>(...values: T) {
+  return (
+    values.length === 1
+      ? values[0]
+      : values
+  ) as unknown as Length<T> extends 1
+    ? T[0] extends readonly unknown[]
+      ? T[0] extends infer Arr
+        ? [IsUnion<First<Arr & readonly unknown[]>>] extends [true]
+            ? Readonly<UnionToTuple<First<T[0]>>>
+            : T[0]
+
+        : Readonly<T[0]>
+      : T[0]
+    : Readonly<T>;
+}
+

package/src/runtime/literals/pathJoin.ts

@@ -0,0 +1,25 @@
+import { PathJoin } from "inferred-types/dist/types/index";
+import { stripTrailing, stripLeading } from "src/runtime/index";
+
+
+/**
+ * **pathJoin**`<T,U>(begin, ...rest)`
+ *
+ * Run time utility which joins two strings together with
+ * the intent to have them be divided by a Posix `/` character
+ * appropriate for Unix file paths and URLs.
+ *
+ * **note:** to support more than two paths being joined there
+ * is now the ability to add a tuple of paths into the _rest_
+ * parameter
+ */
+export function pathJoin<T extends readonly string[]>(
+  ...segments: T
+): PathJoin<T> {
+  const clean_path = segments.map(i => stripTrailing(stripLeading(i, "/"), "/")).join("/");
+  const original_path = segments.join("/");
+  const pre = original_path.startsWith("/") ? "/" : "";
+  const post = original_path.endsWith("/") ? "/" : "";
+
+  return `${pre}${clean_path}${post}` as PathJoin<T>
+}

package/src/runtime/literals/phone/asPhoneNumber.ts

@@ -0,0 +1,72 @@
+
+
+
+// const convert = (
+//   countryCode: string,
+//   phone: string,
+//   delimiter: string,
+//   para: boolean
+// ) => {
+//   const chars: string = stripChars(phone, "(", ")") as string;
+//   const parts: string[] = chars.trim().split(/[-. ]/);
+//   const isRegional = parts.length === 2 ? true : false;
+//   const isCountry = parts.length === 3 ? true : false;
+//   const isShortCode = parts.length === 1 && phone.split("").length < 7 ? true : false;
+
+//   const replacement = isShortCode
+//     ? phone
+//     : isRegional
+//     ? parts.join(delimiter)
+//     : isCountry && para
+//     ? `(${parts[0]}) ${parts.slice(1).join(delimiter)}`
+//     : isCountry
+//     ? parts.join(delimiter)
+//     : undefined;
+
+//   if (!replacement) {
+//     throw new Error(`invalid phone number: ${phone}. Unable to parse!`)
+//   }
+
+//   return countryCode === ""
+//     ? replacement
+//     : `+${countryCode} ${replacement}`;
+// }
+
+// /**
+//  * **asPhoneNumber**`(phone, format)`
+//  *
+//  * Receives a phone number and returns it as a well formatted version.
+//  */
+// export const asPhoneNumber = <
+//   T extends string,
+//   F extends PhoneFormat,
+// >(
+//   phone: T & PhoneNumber<T>,
+//   format: F = "Dotted (e.g., 456.555.1212)" as F
+// ) => {
+//   if (!isPhoneNumber(phone)) {
+//     throw new Error(`Invalid phone number presented to asPhoneNumber(phone,format)!`);
+//   }
+//   const countryCode = getPhoneCountryCode(phone) as unknown as string;
+//   const remaining = removePhoneCountryCode(phone) as unknown as string;
+//   let result: unknown;
+
+//   switch (format) {
+//     case "Dashed (e.g., 456-555-1212)":
+//       result = convert(countryCode, remaining, "-", false) as unknown;
+//       break;
+//     case "Dotted (e.g., 456.555.1212)":
+//       result = convert(countryCode, remaining, ".", false) as unknown;
+//       break;
+//     case "ParaDashed (e.g., (456) 555-1212)":
+//       result = convert(countryCode, remaining, "-", true) as unknown;
+//       break;
+//     case "ParaSpaced (e.g., (456) 555 1212)":
+//       result = convert(countryCode, remaining, " ", true) as unknown;
+//       break;
+//   }
+
+//   return result ;
+// }
+
+export const asPhoneFormat = () => `NOT IMPLEMENTED`

package/src/runtime/literals/phone/getPhoneCountryCode.ts

@@ -0,0 +1,16 @@
+import { NUMERIC_CHAR } from "inferred-types/dist/constants/index";
+import { GetPhoneCountryCode } from "inferred-types/dist/types/index";
+import { retainWhile, stripLeading } from "src/runtime/index";
+
+export const getPhoneCountryCode = <T extends string>(
+  phone: T
+) => {
+  return (
+    phone.trim().startsWith("+") || phone.trim().startsWith("00")
+      ? retainWhile(
+          stripLeading(stripLeading(phone.trim(),"+"), "00") as string,
+          ...NUMERIC_CHAR
+        ) as string
+      : "" as string
+  ) as unknown as GetPhoneCountryCode<T>;
+}

package/src/runtime/literals/phone/index.ts

@@ -0,0 +1,3 @@
+export * from "./getPhoneCountryCode";
+export * from "./removePhoneCountryCode";
+export * from "./asPhoneNumber";

package/src/runtime/literals/phone/removePhoneCountryCode.ts

@@ -0,0 +1,16 @@
+import { getPhoneCountryCode, stripLeading } from "src/runtime/index";
+import { RemovePhoneCountryCode } from "inferred-types/dist/types/index";
+
+export const removePhoneCountryCode = <
+  T extends string
+>(phone: T) => {
+  const countryCode = getPhoneCountryCode(phone) as unknown as string;
+  return (
+    countryCode !== ""
+      ? stripLeading(stripLeading(
+          phone.trim(),
+          "+","00"
+        ) as string, countryCode).trim()
+      : phone.trim()
+  ) as unknown as RemovePhoneCountryCode<T>
+}