inferred-types 0.51.0 → 0.51.1

package/src/runtime/literals/pluralize.ts

@@ -0,0 +1,74 @@
+import {
+  ALPHA_CHARS,
+  PLURAL_EXCEPTIONS,
+  SINGULAR_NOUN_ENDINGS
+} from "inferred-types/dist/constants/index";
+import { Pluralize } from "inferred-types/dist/types/index";
+import { stripTrailing, split, rightWhitespace } from "src/runtime/index";
+
+const isException = <T extends string>(word: T) => Object.keys(PLURAL_EXCEPTIONS).includes(word);
+
+const _END_IN = [
+  "is",
+  "y",
+  "f",
+  "singular-noun"
+] as const;
+
+type EndsIn = (typeof _END_IN)[number];
+
+/**
+ * pluralize based on how word ends
+ */
+const endingIn = <
+  T extends string,
+  U extends EndsIn
+>(word: T, postfix: U) => {
+  switch (postfix) {
+    case "is":
+      return word.endsWith(postfix) ? `${word}es` : undefined;
+    case "singular-noun":
+      return SINGULAR_NOUN_ENDINGS.some(i => word.endsWith(i))
+        ? split(word).every((i) => [...ALPHA_CHARS].includes(i as any))
+          ? `${word}es`
+          : undefined
+        : undefined;
+    case "f":
+      return word.endsWith("f")
+        ? stripTrailing(word, "f") + "ves"
+        : word.endsWith("fe")
+          ? stripTrailing(word, "fe") + "ves"
+          : undefined;
+    case "y":
+      return word.endsWith("y")
+        // ? CONSONANTS.includes(word.slice(-2, 1) as any)
+          ? stripTrailing(word, "y") + "ies"
+          // : undefined
+        : undefined;
+    default:
+      throw new Error(`endingIn received "${postfix}" as a postfix but this ending is not known!`);
+  }
+};
+
+/**
+ * **pluralize(** word **)**
+ *
+ * Pluralizes the word using _language rules_ on pluralization for English as well as
+ * leveraging many known exceptions to the linguistic rules.
+ *
+ * **Note:** _if the string passed into this function is a literal string then the **type**
+ * will be pluralized along with the runtime value._
+ */
+export const pluralize = <T extends string>(word: T): Pluralize<T> => {
+  const right = rightWhitespace(word);
+  const w = word.trimEnd();
+  const result: unknown = isException(w)
+    ? PLURAL_EXCEPTIONS[w as keyof typeof PLURAL_EXCEPTIONS]
+    : endingIn(w, "is") ||
+      endingIn(w, "singular-noun") ||
+      endingIn(w, "f") ||
+      endingIn(w, "y") ||
+      `${w}s`; // add "s" if no other patterns match
+
+  return `${result}${right}` as unknown as Pluralize<T>;
+};

package/src/runtime/literals/retainAfter.ts

@@ -0,0 +1,71 @@
+import { RetainAfter } from "inferred-types/dist/types/index";
+
+/**
+ * **retainAfter**`(content, ...find)`
+ *
+ * Runtime utility which removes all characters in a given string _until_
+ * it finds the first instance of a substring defined in **find** variable.
+ *
+ * ### Example
+ * ```ts
+ * // "world"
+ * const world = retainAfter("hello world", " ");
+ * ```
+ *
+ * **Related:** `retainAfterInclusive()`
+ */
+export function retainAfter<
+  TContent extends string,
+  TFind extends readonly string[]
+>(content: TContent, ...find: TFind) {
+  const idx = Math.min(
+    ...find.map(i => content.indexOf(i)).filter(i => i > -1)
+  );
+  const min = Math.min(...find.map(i => i.length));
+  let len = Math.max(...find.map(i => i.length));
+
+  if (min!==len) {
+    if(!find.includes(content.slice(idx,len))) {
+      len = min;
+    }
+  }
+
+  return (
+    idx && idx > 0
+    ? content.slice(idx+len)
+    : ""
+  ) as RetainAfter<TContent, TFind[number]>
+}
+
+/**
+ * **retainAfterInclusive**`(content, ...find)`
+ *
+ * Runtime utility which removes all characters in a given string _until_
+ * it finds the first instance of a substring defined in **find** variable.
+ *
+ * ### Example
+ * ```ts
+ * // " world"
+ * const world = retainAfter("hello world", " ");
+ * ```
+ *
+ * **Related:** `retainAfter()`
+ */
+export function retainAfterInclusive<
+TContent extends string,
+TFind extends readonly string[]
+>(
+  content: TContent,
+  ...find: TFind
+) {
+
+const minFound = Math.min(
+  ...find.map(i => content.indexOf(i)).filter(i => i > -1)
+);
+
+return (
+  minFound > 0
+  ? content.slice(minFound)
+  : ""
+) as RetainAfter<TContent, TFind[number], true>
+}

package/src/runtime/literals/retainChars.ts

@@ -0,0 +1,30 @@
+import { RetainChars, TupleToUnion } from "inferred-types/dist/types/index";
+import { asChars } from "../type-conversion/asChars";
+
+/**
+ * **retainChars**`(content, ...retain)`
+ *
+ * Retains the characters from `retain[]` which are
+ * found in `content` while discarding the rest.
+ *
+ * ```ts
+ * // "42"
+ * const num = retainChars("4foobar2", ...NUMERIC_CHAR);
+ * ```
+ *
+ * **Related:** `stripChars()`, `retainWhile()`, `retainUntil()`
+ */
+export const retainChars = <
+  TContent extends string,
+  TRetain extends readonly string[]
+>(
+  content: TContent,
+  ...retain: TRetain
+): RetainChars<TContent, TupleToUnion<TRetain>> => {
+  let chars: readonly string[] = asChars(content);
+
+
+  return chars.filter(c => retain.includes(c)).join("") as unknown as RetainChars<TContent, TupleToUnion<TRetain>>
+}
+
+

package/src/runtime/literals/retainUntil.ts

@@ -0,0 +1,67 @@
+import { RetainUntil } from "inferred-types/dist/types/index";
+import { asChars } from "../type-conversion";
+
+/**
+ * **retainUntil**`(content, ...find)`
+ *
+ * Runtime utility which retains all characters in a given string _until_
+ * it finds the first instance of a substring defined in **find** variable.
+ *
+ * ### Example
+ * ```ts
+ * // "hello"
+ * const world = retainUntil("hello world", " ");
+ * ```
+ *
+ * **Related:** `retainUntilInclusive()`
+ */
+export function retainUntil<
+  TContent extends string,
+  TFind extends readonly string[]
+>(content: TContent, ...find: TFind) {
+  const chars = asChars(content) as readonly string[];
+
+  let idx = 0;
+  while (!find.includes(chars[idx]) && idx <= chars.length) {
+    idx = idx+1;
+  }
+
+  return (
+    idx === 0
+    ? ""
+    : content.slice(0,idx)
+  ) as unknown as RetainUntil<TContent, TFind[number]>;
+}
+
+
+/**
+ * **retainUntil**`(content, ...find)`
+ *
+ * Runtime utility which retains all characters in a given string _until_
+ * it finds the first instance of a substring defined in **find** variable.
+ *
+ * ### Example
+ * ```ts
+ * // "hello "
+ * const world = retainUntilInclusive("hello world", " ");
+ * ```
+ *
+ * **Related:** `retainUntil()`
+ */
+export function retainUntilInclusive<
+  TContent extends string,
+  TFind extends readonly string[]
+>(content: TContent, ...find: TFind) {
+  const chars = asChars(content) as readonly string[];
+
+  let idx = 0;
+  while (!find.includes(chars[idx]) && idx <= chars.length) {
+    idx = idx+1;
+  }
+
+  return (
+    idx === 0
+    ? content.slice(0,1)
+    : content.slice(0,idx+1)
+  ) as unknown as RetainUntil<TContent, TFind[number], true>;
+}

package/src/runtime/literals/retainWhile.ts

@@ -0,0 +1,23 @@
+import {  RetainWhile, TupleToUnion } from "inferred-types/dist/types/index";
+import { asChars } from "../type-conversion"
+
+
+/**
+ * **retainWhile**`(content, ...retain)`
+ *
+ * Retains the characters at the start of the string
+ * so long as they are part of the character values
+ * passed in for `retain[]`
+ */
+export const retainWhile = <
+  TContent extends string,
+  TRetain extends readonly string[]
+>(
+  content: TContent,
+  ...retain: TRetain
+) => {
+  const stopIdx = asChars(content)
+    .findIndex(c => !retain.includes(c));
+
+  return content.slice(0,stopIdx) as unknown as RetainWhile<TContent, TupleToUnion<TRetain>>;
+}

package/src/runtime/literals/rightWhitespace.ts

@@ -0,0 +1,17 @@
+import { WHITESPACE_CHARS } from "inferred-types/dist/constants/index"
+import {  retainAfterInclusive } from "./retainAfter"
+import { TrimLeft } from"inferred-types/dist/types/index"
+import { RetainAfter, Whitespace } from "inferred-types/dist/types/index"
+
+/**
+ * **rightWhitespace**`(content)`
+ *
+ * Extracts and returns the whitespace on the _right_ part of the string.
+ */
+export const rightWhitespace = <T extends string>(content: T) => {
+  const trimmed = content.trimStart() as string;
+  return retainAfterInclusive(
+    trimmed,
+    ...WHITESPACE_CHARS
+  ) as unknown as RetainAfter<TrimLeft<T>, Whitespace, true>
+}

package/src/runtime/literals/split.ts

@@ -0,0 +1,19 @@
+import {  Chars, IsEqual } from "inferred-types/dist/types/index";
+
+/**
+ * **split**(str, sep)
+ *
+ * Splits a string on a given separator while preserving string literal typing
+ * where available. Behavior with non-string types is:
+ *
+ * - `number` - converted to string and then split
+ *
+ * All are other types are disallowed.
+ */
+export function split<
+  T extends string,
+  S extends string
+>(str: T, sep: S = "" as S) {
+  return str.split(sep) as unknown as IsEqual<S,""> extends true  ? Chars<T> : readonly string[];
+}
+

package/src/runtime/literals/stripAfter.ts

@@ -0,0 +1,20 @@
+import { StripAfter } from "inferred-types/dist/types/index";
+
+/**
+ * **stripAfter**(content, find)
+ *
+ * Runtime utility which strips out all characters after (and including)
+ * the "find" string while returning a strong type.
+ *
+ * ### Example
+ * ```ts
+ * // "hello"
+ * const hello = stripAfter("hello world", " ");
+ * ```
+ */
+export function stripAfter<
+  TContent extends string,
+  TBreak extends string
+>(content: TContent, find: TBreak) {
+  return content.split(find).shift() as unknown as StripAfter<TContent, TBreak>;
+}

package/src/runtime/literals/stripBefore.ts

@@ -0,0 +1,23 @@
+import { StripBefore } from "inferred-types/dist/types/index";
+
+/**
+ * **stripBefore**(content, find)
+ *
+ * Runtime utility which strips out all characters Before (and including)
+ * the "find" string while returning a strong type.
+ *
+ * ### Example
+ * ```ts
+ * // "hello"
+ * const hello = stripBefore("hello world", " ");
+ * ```
+ */
+export function stripBefore<
+  TContent extends string,
+  TBreak extends string
+>(content: TContent, find: TBreak) {
+  return content
+    .split(find)
+    .slice(1)
+    .join(find)  as StripBefore<TContent, TBreak>;
+}

package/src/runtime/literals/stripChars.ts

@@ -0,0 +1,25 @@
+import {  StripChars, TupleToUnion } from "inferred-types/dist/types/index";
+import { asChars } from "src/runtime/index";
+
+/**
+ * **stripChars**`(content, ...strip)`
+ *
+ * Strips out characters found in `content`.
+ *
+ * **Related:** `retainChars()`
+ */
+export const stripChars = <
+  TContent extends string,
+  TRetain extends readonly string[]
+>(
+  content: TContent,
+  ...strip: TRetain
+): StripChars<TContent, TupleToUnion<TRetain>> => {
+  let chars: readonly string[] = asChars(content);
+
+  return (
+    chars.filter(c => !strip.includes(c)).join("")
+   ) as unknown as StripChars<TContent, TupleToUnion<TRetain>>
+}
+
+

package/src/runtime/literals/stripLeading.ts

@@ -0,0 +1,28 @@
+import { StripLeading, TupleToUnion } from "inferred-types/dist/types/index";
+import { isNumber } from "../type-guards/isNumber";
+
+/**
+ * **stripLeading**(content, ...strip)
+ *
+ * Runtime utility which strips of a leading substring from the
+ * primary content if it exists and leaves content unchanged otherwise.
+ */
+export function stripLeading<
+  T extends string | number,
+  U extends readonly (string | number)[]
+>(
+  content: T,
+  ...strip: U
+) {
+  let output: string = String(content);
+
+  for (const s of strip) {
+    if (output.startsWith(String(s))) {
+      output = output.slice(String(s).length);
+    }
+  }
+
+  return (
+    isNumber(content) ? Number(output) : output
+  ) as unknown as StripLeading<T, TupleToUnion<U>>
+}

package/src/runtime/literals/stripSurround.ts

@@ -0,0 +1,54 @@
+
+import {
+  StripSurround
+} from "inferred-types/dist/types/index";
+import { isNumber } from "../type-guards/isNumber";
+
+export type StripSurroundConfigured<
+  TStrip extends readonly (string | number)[]
+> = <TInput extends string | number>(input: TInput) => StripSurround<
+  TInput,
+  TStrip[number]
+>;
+
+
+/**
+ * **stripSurround**`(chars) => (input) => _stripped_`
+ *
+ * A higher order function which allows you to define a string literal
+ * stripping function for both the beginning and end of a string literal.
+ *
+ * ```ts
+ * // utility which will strip all starting and ending brackets
+ * const stripBrackets = stripSurround("(", ")", "[", "]", "{", "}");
+ * // " hello, world "
+ * const without = stripBrackets("[ hello, world ]")
+ * ```
+ *
+ * **Related**: `stripSurroundAndTrim`
+ */
+export const stripSurround = <
+  TChars extends readonly (number | string)[]
+>(
+  ...chars: TChars
+): StripSurroundConfigured<TChars> => {
+  return <TInput extends string | number>(input: TInput) => {
+    let output: string = String(input);
+
+    for (const s of chars) {
+      if (output.startsWith(String(s))) {
+        output = output.slice(String(s).length);
+      }
+      if (output.endsWith(String(s))) {
+        output = output.slice(0,-1 * String(s).length);
+      }
+    }
+
+    return (
+      isNumber(input) ? Number(output) : output
+    ) as unknown as StripSurround<TInput, TChars[number]>
+
+
+  }
+}
+

package/src/runtime/literals/stripTrailing.ts

@@ -0,0 +1,29 @@
+import { StripTrailing, TupleToUnion } from "inferred-types/dist/types/index";
+import { isNumber } from "../type-guards/index";
+
+/**
+ * **stripTrailing**(content, strip)
+ *
+ * Runtime utility which ensures that last part of a string has substring
+ * removed if it exists and that strong typing is preserved.
+ */
+export function stripTrailing<
+  T extends string | number,
+  U extends readonly (string | number)[]
+>(
+  content: T,
+  ...strip: U
+): StripTrailing<T, TupleToUnion<U>> {
+  let output: string = String(content);
+
+  for (const s of strip) {
+    if (output.endsWith(String(s))) {
+      output = output.slice(0,-1 * String(s).length);
+    }
+  }
+
+  return (
+    isNumber(content) ? Number(output) : output
+  ) as unknown as StripTrailing<T, TupleToUnion<U>>
+}
+

package/src/runtime/literals/stripUntil.ts

@@ -0,0 +1,18 @@
+import { asChars } from "../type-conversion/index";
+import { TupleToUnion,StripUntil } from "inferred-types/dist/types/index";
+
+/**
+ * **stripUntil**`(content, ...until)`
+ *
+ * Strips the characters at the start of the string
+ * until a character specified in `until` is found.
+ */
+export const stripUntil = <
+  TContent extends string,
+  TUntil extends readonly string[]
+>(content: TContent, ...until: TUntil) => {
+  const stopIdx = asChars(content)
+    .findIndex(c => until.includes(c));
+
+  return content.slice(stopIdx) as unknown as StripUntil<TContent, TupleToUnion<TUntil>>;
+}

package/src/runtime/literals/stripWhile.ts

@@ -0,0 +1,19 @@
+import { asChars } from "../type-conversion/index";
+import { StripWhile } from "inferred-types/dist/types/index";
+
+/**
+ * **stripWhile**`(content, ...until)`
+ *
+ * Strips the characters at the start of the string
+ * while they match the characters found in `match`
+ * parameter.
+ */
+export const stripWhile = <
+  TContent extends string,
+  TMatch extends readonly string[]
+>(content: TContent, ...match: TMatch) => {
+  const stopIdx = asChars(content)
+    .findIndex(c => !match.includes(c));
+
+  return content.slice(stopIdx) as unknown as StripWhile<TContent, TMatch[number]>;
+}

package/src/runtime/literals/surround.ts

@@ -0,0 +1,23 @@
+
+
+export type SurroundWith<
+TPrefix extends string,
+TPostfix extends string
+> = <TInput extends string>(input: TInput) => `${TPrefix}${TInput}${TPostfix}`;
+
+/**
+ * **surround**(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 _surround_
+ * the given input with the prefix and postfix strings.
+ * 
+ * **Related:** `ensureSurround()`
+ */
+export function surround<
+  TPrefix extends string,
+  TPostfix extends string
+>(prefix: TPrefix, postfix: TPostfix): SurroundWith<TPrefix, TPostfix> {
+  return (input) => `${prefix}${input}${postfix}`;
+}
+

package/src/runtime/literals/takeNumericCharacters.ts

@@ -0,0 +1,16 @@
+import { NUMERIC_CHAR } from "inferred-types/dist/constants/index"
+import { asChars } from "src/runtime/index"
+import { NumericChar, RetainWhile } from "inferred-types/dist/types/index";
+
+
+/**
+ * **takeNumericCharacters**`(content)`
+ *
+ * Starts at the passed in content and extracts all numeric characters
+ * in the string until a non-numeric value arrives.
+ */
+export const takeNumericCharacters = <T extends string>(content: T) => {
+  let nonNumericIdx = asChars(content).findIndex(i => !NUMERIC_CHAR.includes(i as any));
+
+  return content.slice(0,nonNumericIdx) as unknown as RetainWhile<T, NumericChar>;
+}

package/src/runtime/literals/toCamelCase.ts

@@ -0,0 +1,28 @@
+import type { CamelCase } from "inferred-types/dist/types/index";
+import { toPascalCase } from "src/runtime/index";
+
+/**
+ * **toCamelCase**(str)
+ *
+ * Converts a string into `camelCase` while preserving literal strings.
+ *
+ * **Note:** _by default it also removes surrounding white space (if it exists) but it
+ * can be preserved if you change the `preserveWhitespace` flag._
+ *
+ * **Related:** `toKebabCase`, `toPascalCase`, `toSnakeCase`
+ */
+export function toCamelCase<
+  TString extends string,
+  TPreserve extends boolean = false
+>(input: TString, preserveWhitespace?: TPreserve): CamelCase<TString, TPreserve> {
+  const pascal = preserveWhitespace ? toPascalCase(input, preserveWhitespace) : toPascalCase(input);
+  const [_, preWhite, focus, postWhite] = /^(\s*)(.*?)(\s*)$/.exec(
+    pascal
+  ) as RegExpExecArray;
+
+  const camel = (preserveWhitespace ? preWhite : "") +
+    focus.replace(/^.*?([0-9]*?[a-z|A-Z]{1})/s, (_, p1) => p1.toLowerCase()) +
+    (preserveWhitespace ? postWhite : "") as unknown as CamelCase<TString, TPreserve>;
+
+  return camel;
+}

package/src/runtime/literals/toKebabCase.ts

@@ -0,0 +1,31 @@
+import { KebabCase } from "inferred-types/dist/types/index";
+
+/**
+ * **toKebabCase**(str)
+ *
+ * Converts a string into `kebab-case` while preserving literal strings.
+ *
+ * **Note:** _by default it also removes surrounding white space (if it exists) but it
+ * can be preserved if you change the `preserveWhitespace` flag._
+ *
+ * **Related:** `toPascalCase`, `toCamelCase`, `toSnakeCase`
+ */
+export function toKebabCase<
+  S extends string,
+  P extends boolean = false
+>(input: S, _preserveWhitespace?: P) {
+  const [_, preWhite, focus, postWhite] = /^(\s*)(.*?)(\s*)$/.exec(input) as RegExpExecArray;
+
+  const replaceWhitespace = (i: string) => i.replace(/\s/gs, "-");
+  const replaceUppercase = (i: string) => i.replace(/[A-Z]/g, (c) => `-${c[0].toLowerCase()}`);
+  const replaceLeadingDash = (i: string) => i.replace(/^-/s, "");
+  const replaceTrailingDash = (i: string) => i.replace(/-$/s, "");
+  const replaceUnderscore = (i: string) => i.replace(/_/g, "-");
+  const removeDupDashes = (i: string) => i.replace(/-+/g, "-");
+
+  return removeDupDashes(`${preWhite}${replaceUnderscore(
+    replaceTrailingDash(
+      replaceLeadingDash(removeDupDashes(replaceWhitespace(replaceUppercase(focus))))
+    )
+  )}${postWhite}`) as unknown as KebabCase<S,P>;
+}

package/src/runtime/literals/toLowercase.ts

@@ -0,0 +1,13 @@
+import { ifLowercaseChar, lowercase } from "src/runtime/index";
+
+/**
+ * Converts a string to the "all lowercase" equivalent.
+ * 
+ * Note: non-alpha characters are left "as is"
+ */
+export function toLowercase<T extends string>(str: T): Lowercase<T> {
+  return str
+    .split("")
+    .map(i => ifLowercaseChar(i, v => lowercase(v), v => v))
+    .join("") as Lowercase<T>;
+}

package/src/runtime/literals/toNumericArray.ts

@@ -0,0 +1,5 @@
+import { ToNumericArray, Tuple } from "inferred-types/dist/types/index";
+
+export const toNumericArray = <T extends Tuple>(arr: T) => {
+  return arr.map(i => Number(i)) as unknown as ToNumericArray<T>;
+};