inferred-types 0.51.0 → 0.51.1

package/src/runtime/dictionary/get.ts

@@ -0,0 +1,168 @@
+import type {
+  Narrowable,
+  DotPathFor,
+  Get,
+  Suggest,
+  Tuple,
+  Dictionary,
+} from "inferred-types/dist/types/index";
+import {
+  NO_DEFAULT_VALUE,
+  NoDefaultValue,
+  NotDefined,
+  NOT_DEFINED
+} from "inferred-types/dist/constants/index";
+import {
+  createErrorCondition,
+  isTruthy,
+  hasIndexOf,
+  isSpecificConstant,
+  hasDefaultValue,
+  isContainer,
+  isRef,
+  indexOf
+} from "inferred-types/dist/runtime/index";
+
+/** updates based on whether segment is a Ref or not */
+function updatedDotPath<
+  TValue,
+  TDotPath extends string,
+  TSegment extends string
+>(value: TValue, dotpath: TDotPath, segment: TSegment) {
+  return isRef(value)
+  ? dotpath.replace(segment, `Ref(${segment})`)
+  : dotpath;
+}
+
+/**
+ * **getValue**(value, dotpath, defaultValue, handler, fullDotPath)
+ */
+function getValue<
+  TValue,
+  TDotPath extends string,
+  TDefVal extends Narrowable,
+  TInvalid extends Narrowable,
+  TFullDotPath extends string,
+>(
+  value: TValue,
+  dotPath: TDotPath,
+  defaultValue: TDefVal,
+  handleInvalid: TInvalid,
+  fullDotPath: TFullDotPath
+) {
+
+  /** the remaining segments that need processing */
+  const pathSegments: string[] = isTruthy(dotPath)
+    ? dotPath.split(".")
+    : [];
+
+  /** current index property */
+  const idx = pathSegments[0];
+
+  /**
+   * dotpath _will_ need to recurse further to
+   * reach destination
+   **/
+  const hasMoreSegments = pathSegments.length > 1;
+
+  /** whether or not the value is indexable or not */
+  const valueIsIndexable = isContainer(value) && hasIndexOf(value, idx);
+
+  /** has handler for invalid dotpath */
+  const hasHandler = !isSpecificConstant("not-defined")(handleInvalid);
+
+
+
+  const invalidDotPath = createErrorCondition(
+    "invalid-dot-path",
+    `The segment "${idx}" in the dotpath "${fullDotPath}" was not indexable and no default value existed on: ${JSON.stringify(value)}`
+  );
+
+  const current = (
+    hasMoreSegments
+    ? isContainer(value) && idx in value
+      ? getValue(
+          indexOf(value, idx) ,
+          pathSegments.join(".").replace(`${idx}.`, ""),
+          defaultValue,
+          handleInvalid,
+          updatedDotPath(value,fullDotPath, idx)
+        )
+      : hasHandler
+        ? handleInvalid
+        : invalidDotPath
+    : valueIsIndexable
+      ? hasDefaultValue(hasDefaultValue)
+        ? (indexOf(value, idx) as any || defaultValue) as any
+        : indexOf(value, idx)
+      : hasHandler ? handleInvalid : invalidDotPath
+  ) as unknown as Get<TValue, TDotPath>;
+
+  return current;
+}
+
+export interface GetOptions<
+  TDefVal extends Narrowable,
+  TInvalid extends Narrowable
+> {
+  /**
+   * Typically when getting a valid dotpath and the value evaluates to _undefined_
+   * then the value returned is _undefined_ but if you'd prefer to put something else
+   * in here you may.
+   */
+  defaultValue?: TDefVal;
+  /**
+   * Typically when a dotpath is invalid for a given item then this item
+   * is set as a `ErrorCondition<'invalid-dot-path'>` but if you'd like
+   * to set it to something else you may.
+   *
+   * Note: a common replacement would be the `Never` constant from this library
+   * as it "reports" as being `never` but allows for a more sophisticated
+   * handling process to follow.
+   */
+  handleInvalidDotpath?: TInvalid;
+}
+
+
+/**
+ * **get**(obj, dotPath, [defVal])
+ *
+ * Gets a value in a deeply nested object while attempting to preserve type information
+ * (a default value is allowed as optional param).
+ *
+ * - if the dot-path is invalid then an `ErrorCondition` will be returned, unless
+ * a defaultValue is provided in which case this will be returned instead
+ * - this function is also VueJS _aware_ in the sense that it can also traverse
+ * VueJS `ref` properties when encountered
+ *
+ * ```ts
+ * const prop = get(obj, "foo.bar.baz", "nothing there chief!");
+ * ```
+ */
+export function get<
+  TValue extends Narrowable | readonly unknown[],
+  TDotPath extends Suggest<DotPathFor<TValue>>,
+  TDefVal extends Narrowable = NoDefaultValue,
+  TInvalid extends Narrowable = NotDefined
+>(
+    value: TValue,
+    dotPath: TDotPath | null,
+    options: GetOptions<TDefVal, TInvalid> = {
+      defaultValue: NO_DEFAULT_VALUE,
+      handleInvalidDotpath: NOT_DEFINED
+    } as GetOptions<TDefVal, TInvalid>
+) {
+  const outcome: unknown = (
+    dotPath === null || dotPath === ""
+      ? value
+      : getValue(
+          value as Dictionary | Tuple,
+          dotPath,
+          options?.defaultValue || NO_DEFAULT_VALUE,
+          options?.handleInvalidDotpath || NOT_DEFINED,
+          String(dotPath)
+        ) as unknown
+  );
+
+  return outcome as unknown as Get<TValue,TDotPath>
+}

package/src/runtime/dictionary/index.ts

@@ -0,0 +1,23 @@
+// #autoindex
+// #region auto-indexed files
+// index last changed at: 8th Aug, 2022, 09:51 AM ( GMT-7 )
+// hash-code: b0051c37
+
+// file exports
+export * from "./entries";
+export * from "./get";
+export * from "./keysOf";
+export * from "./omit";
+export * from "./retain";
+export * from "./sharedKeys";
+export * from "./takeProp";
+export * from "./withKeys";
+export * from "./withoutKeys";
+export * from "./withoutValue";
+export * from "./withDefaults";
+export * from "./valuesOf";
+
+// #endregion auto-indexed files
+
+// see https://github.com/inocan-group/do-devops/docs/autoindex.md
+// for more info

package/src/runtime/dictionary/keysOf.ts

@@ -0,0 +1,28 @@
+import type { Container, Keys } from "inferred-types/dist/types/index";
+import { isObject, isRef } from "src/runtime/index";
+
+
+/**
+ * **keysOf**(container)
+ *
+ * Provides a read-only array of the _keys_ an object (or array) contains.
+ *
+ * **Note:** this function is aware of Ref<T> types from VueJS and will return
+ * `readonly ["value"]` as the keys array when detected rather than reporting
+ * on props like `__v_isRef`, etc.
+ */
+export function keysOf<TContainer extends Container>(
+  container: TContainer
+) {
+
+  const keys: unknown = (
+    Array.isArray(container)
+      ? Object.keys(container).map(i => Number(i))
+      : isObject(container)
+        ? isRef(container)
+          ? ["value"]
+          : Object.keys(container)
+        : []
+  );
+  return keys as Keys<TContainer> & (keyof TContainer)[]
+}

package/src/runtime/dictionary/omit.ts

@@ -0,0 +1,40 @@
+/* eslint-disable no-use-before-define */
+
+import type { Narrowable, WithoutKeys,  ObjectKey } from "inferred-types/dist/types/index";
+
+
+/**
+ * **omit**(obj, excluding)
+ *
+ * Runtime utility which _excludes_ certain **keys** from an object.
+ *
+ * - this utility is meant to mimic the type utility `Omit<T,U>` provided
+ * by Typescript in runtime
+ * - attempts will be made to extract the narrowest possible type from
+ * the passed in object.
+ *
+ * ```ts
+ * // { baz: 3 }
+ * const obj = omit({ foo: 1, bar: 2: baz: 3 }, "foo", "bar");
+ * ```
+ *
+ * **Related:** `createOmission`, `withoutKeys`
+ */
+export function omit<
+  TObj extends Record<ObjectKey, N>,
+  N extends Narrowable,
+  TKeys extends readonly ObjectKey[] = readonly []
+>(obj: TObj, ...removeKeys: TKeys) {
+  const keys = Object.keys(obj);
+
+  return keys.reduce(
+    (acc, key) => removeKeys.includes(key as any)
+      ? acc
+      : {
+        ...acc,
+        [key]: obj[key as keyof TObj]
+      },
+    {}
+  ) as unknown as WithoutKeys<TObj, TKeys>;
+
+}

package/src/runtime/dictionary/retain.ts

@@ -0,0 +1,35 @@
+import { Throw, HasUnionType, NarrowObject, Narrowable,  ObjectKey,  WithKeys } from "inferred-types/dist/types/index";
+
+/**
+ * **retain**(obj,...keys)
+ *
+ * Reduces the key/value pairs in an object to those keys
+ * explicitly stated.
+ *
+ * **Related:** `createRetainer`, `omit`
+ */
+export const retain = <
+  N extends Narrowable,
+  TObj extends NarrowObject<N>,
+  TKeys extends readonly (ObjectKey & keyof TObj)[]
+>(
+  dict: TObj,
+  ...keys: TKeys
+) => {
+  let output: Record<string, unknown> = {};
+  for (const k of keys) {
+    output = {
+      ...output,
+      [k]: dict[k]
+    };
+  }
+
+  return output as unknown as HasUnionType<TKeys> extends true
+  ? Throw<
+      "invalid-union",
+      "the retain(obj, keys) function was called with keys which included a value which was a union type; this would make the typing inconsistent with the runtime type and should be avoided. Note that at runtime this will not produce an error but rather produce the valid runtime value.",
+      "retain()",
+      { keys: TKeys }
+    >
+  : WithKeys<TObj, TKeys>;
+};

package/src/runtime/dictionary/sharedKeys.ts

@@ -0,0 +1,16 @@
+import { AnyObject, AsRecord, ObjectKey, SharedKeys } from "inferred-types/dist/types/index";
+
+/**
+ * **sharedKeys**
+ *
+ * Runtime utility which provides the _shared_ keys between two objects.
+ */
+export const sharedKeys = <
+  A extends AnyObject | object,
+  B extends AnyObject | object
+>(a: A, b: B): SharedKeys<AsRecord<A>, AsRecord<B>> => {
+  const ka = Object.keys(a) as ObjectKey[];
+  const kb = Object.keys(b) as ObjectKey[];
+
+  return ka.filter(k => kb.includes(k)) as unknown as SharedKeys<AsRecord<A>, AsRecord<B>>;
+};

package/src/runtime/dictionary/takeProp.ts

@@ -0,0 +1,28 @@
+
+import { Narrowable, TakeProp, Something } from "inferred-types/dist/types/index";
+import { isArray, isObject } from "src/runtime/index";
+
+/**
+ * **takeProp**(val, prop, otherwise)
+ *
+ * Takes a property from a value if it is a _container_ and "prop"
+ * is a valid index of the container. If not then it returns the
+ * value provided in "otherwise".
+ *
+ * **Related:** `get`
+ */
+export const takeProp = <
+  T extends Something,
+  P extends PropertyKey,
+  E extends Narrowable
+>(
+  val: T,
+  prop: P,
+  otherwise: E
+) => {
+  return (
+    (isObject(val) || isArray(val)) && prop in val
+      ? val[prop as keyof typeof val]
+      : otherwise
+  ) as TakeProp<T, P, E>
+}

package/src/runtime/dictionary/valuesOf.ts

@@ -0,0 +1,21 @@
+/* eslint-disable no-use-before-define */
+import { AsRecord,  Narrowable, ObjectKey, Values } from "inferred-types/dist/types/index";
+
+/**
+ * **valuesOf**(obj) -> readonly values[]
+ *
+ * Runtime utility to convert an object into a tuple of
+ * values while preserving as much type information as
+ * possible.
+ */
+export const valuesOf = <
+  TObj extends Record<ObjectKey, N>,
+  N extends Narrowable
+>(obj: TObj): Values<AsRecord<TObj>> => {
+  const values = [];
+  for (const k of Object.keys(obj)) {
+    values.push(obj[k as keyof typeof obj]);
+  }
+
+  return values as Values<AsRecord<TObj>>
+}

package/src/runtime/dictionary/withDefaults.ts

@@ -0,0 +1,27 @@
+/* eslint-disable no-use-before-define */
+import {  MergeObjects, Narrowable, ObjectKey } from "inferred-types/dist/types/index";
+
+/**
+ * **withDefaults**(defaults) → (obj) → _merged_
+ *
+ * Merges in default values to an existing object and maintains
+ * narrow typing.
+ */
+export const withDefaults = <
+  TDefaults extends Record<ObjectKey,N>,
+  N extends Narrowable
+>(
+  with_defaults: TDefaults
+) => <
+  TObj extends Record<ObjectKey, W>,
+  W extends Narrowable
+>(obj: TObj) => {
+
+  const merged = {
+    ...with_defaults,
+    ...obj
+  };
+
+  return merged as unknown as MergeObjects<Required<TDefaults>,TObj>;
+}
+

package/src/runtime/dictionary/withKeys.ts

@@ -0,0 +1,22 @@
+/* eslint-disable no-use-before-define */
+import type { Dictionary, Narrowable, ObjectKey } from "inferred-types/dist/types/index";
+import { retain } from "./retain";
+
+
+/**
+ * **withKeys**(obj,keys)
+ *
+ * Reduces the key/value pairs in an object to those keys
+ * explicitly stated.
+ *
+ * - note: this function is an alias for `retain()`
+ */
+export const withKeys = <
+  TObj extends Dictionary<string | symbol, N>,
+  N extends Narrowable,
+  TKeys extends readonly (ObjectKey & keyof TObj)[]
+>(
+  dict: TObj,
+  ...keys: TKeys
+) => retain(dict, ...keys);
+

package/src/runtime/dictionary/withoutKeys.ts

@@ -0,0 +1,23 @@
+/* eslint-disable no-use-before-define */
+import type { NarrowObject, Narrowable } from "inferred-types/dist/types/index";
+import { omit } from "src/runtime/index";
+
+
+/**
+ * **withoutKeys**(obj,...keys)
+ *
+ * Reduces the key/value pairs in an object with the expressed
+ * keys excluded.
+ *
+ * - this is an alias to the `omit()` utility
+ *
+ * **Related**: `omit`, `createOmission`
+ */
+export const withoutKeys = <
+  TObj extends NarrowObject<N>,
+  N extends Narrowable,
+  TKeys extends readonly (string & keyof TObj)[]
+>(
+  dict: TObj,
+  ...exclude: TKeys
+) => omit(dict, ...exclude);

package/src/runtime/dictionary/withoutValue.ts

@@ -0,0 +1,26 @@
+import { AnyObject, Narrowable, WithoutValue } from "inferred-types/dist/types/index";
+
+/**
+ * **withoutValue**
+ *
+ * Reduces a dictionary object -- in both _type_ and _run-time_ structure -- to only those
+ * key/value pairs which _do not have_ a specified value. For instance:
+ *
+ * ```ts
+ * const obj = { foo: 1, bar: 2, message: "hi there" };
+ * // { message: "hi there" }
+ * const onlyStrings = withoutValue(t => kind.string())(obj);
+ * // { foo: 1 }
+ * const justOne = withoutValue(t => kind.literal(1))(obj);
+ * ```
+ */
+export function withoutValue<TVal extends Narrowable>(val: TVal) {
+  return <TObj extends AnyObject>(obj: TObj): WithoutValue<TObj,TVal> => {
+    return Object.keys(obj).reduce(
+      (acc, key) => val === obj[key as keyof TObj]
+        ? acc
+        : ({...acc, [key]: obj[key as keyof TObj]}),
+      {} as WithoutValue<TObj,TVal>
+    );
+  };
+}

package/src/runtime/errors/KindError.ts

@@ -0,0 +1,59 @@
+import {
+  EmptyObject,
+  If,
+  IsUndefined,
+  KindError,
+  KindErrorDefn,
+  Unset
+} from "inferred-types/dist/types/index";
+import { toKebabCase, toPascalCase } from "src/runtime/index";
+
+/**
+ * **KindError**
+ *
+ * An error which:
+ *
+ * - must have a "kind" type defined which can be used to categorize the error
+ * - is allowed to express other key/value pairs in the `context` property
+ *
+ * This error is generated with the `kindError(kind, _defineContext) => (msg, ctx)`
+ * higher order function.
+ *
+ * ```ts
+ * // Defines the Error
+ * const BadJuju = kindError("bad-juju", { flavor?: "" });
+ * // BadJuju {
+ * //     name: BadJuju;
+ * //     kind: "bad-juju";
+ * //     msg: "oh my god!";
+ * //     context: { flavor?: string}
+ * // }
+ * BadJuju("oh my god!");
+ * BadJuju("oh my god!", { flavor: "strawberry"})
+ * ```
+ */
+export const kindError = <
+  K extends string,
+  C extends Record<string, unknown> | Unset = Unset
+>(
+  kind: K,
+  _defineContext?: C
+): KindErrorDefn<K,C> =>
+(
+  msg: string,
+  context?: C
+) => {
+
+  const err = new Error(msg) as Partial<
+    KindError<
+      typeof kind,
+      If<IsUndefined<C>, EmptyObject, C>
+    >
+  >;
+  err.name = toPascalCase(kind);
+  err.kind = toKebabCase(kind);
+  err.__kind = "KindError";
+  err.context = context as any;
+
+  return err as unknown as KindError<K,C>
+}

package/src/runtime/errors/TypedError.ts

@@ -0,0 +1,69 @@
+
+
+import { AnyObject, EmptyObject, Narrowable, } from "inferred-types/dist/types/index";
+import { addFnToProps } from "src/runtime/index";
+
+export interface TypedError<
+  TKind extends string = string,
+  TMsg extends string = string,
+  TContext extends AnyObject = AnyObject
+> extends Error {
+  kind: TKind;
+  msg: TMsg;
+  context: TContext;
+  stack?: string;
+}
+
+/**
+ * **KindedApi**
+ *
+ * An error builder where the `kind` property has already been set.
+ */
+export type KindedApi<TKind extends string> = <
+  TMsg extends string,
+  K extends PropertyKey,
+  V extends Narrowable,
+  TContext extends Record<K, V>
+>(msg: TMsg, context?: TContext) => TypedError<TKind, TMsg, TContext>;
+
+export type ErrorApi = {
+  /**
+   * A simple API surface to create an error with a `kind` and `msg` type.
+   */
+  kinded<TKind extends string, TMsg extends string>(
+    kind: TKind,
+    msg: TMsg): TypedError<TMsg, TKind>;
+
+  /**
+   * Allows expressing the `kind` of error initially
+   * and then provides a function to supply specific
+   * errors.
+   */
+  asKind<TKind extends string>(kind: TKind): KindedApi<TKind>;
+};
+
+
+const fn = <TKind extends string>(kind: TKind) =>
+  <TMsg extends string>(msg: TMsg) => ({
+    kind,
+    msg,
+    context: {}
+  } as TypedError<TKind, TMsg, EmptyObject>);
+
+
+
+const api: ErrorApi = {
+  kinded: (kind, msg) => fn(kind)(msg),
+  asKind: (kind) => (msg, context) => ({ kind, msg, context: context || ({} as EmptyObject) })
+
+} as ErrorApi;
+
+const basic = <TMsg extends string>(msg: TMsg) => ({
+  kind: "unknown" as const,
+  msg,
+  context: {}
+});
+
+
+export const TypedError = addFnToProps(api)(basic);
+

package/src/runtime/errors/createErrorCondition.ts

@@ -0,0 +1,35 @@
+import { Throw } from "inferred-types/dist/types/index";
+
+
+/**
+ * **createErrorConditionTemplate**`(kind,[msg],[utility]) => ErrorCondition`
+ *
+ * A higher order runtime utility for generating reusable `ErrorCondition`'s at
+ * runtime.
+ */
+export const createErrorCondition = <
+  TKind extends string,
+  TMsg extends string = never,
+  TUtility extends string = never
+>(
+  kind: TKind,
+  msg: TMsg = "" as never,
+  utility: TUtility = "" as never
+) => {
+  return {
+    __kind: "ErrorCondition",
+    kind,
+    msg,
+    utility,
+  } as unknown as Throw<TKind, TMsg, TUtility>;
+};
+
+
+export const errCondition = (
+  kind: string,
+  msg?: string
+) => ({
+  __kind: "ErrorCondition",
+  kind,
+  msg
+})

package/src/runtime/errors/index.ts

@@ -0,0 +1,2 @@
+export * from "./createErrorCondition";
+export * from "./kindedError";

package/src/runtime/errors/kindedError.ts

@@ -0,0 +1,59 @@
+import { toKebabCase, toPascalCase } from "../literals";
+import {
+  EmptyObject,
+  Handle,
+  KindError,
+  KindErrorDefn
+} from "inferred-types/dist/types/index";
+
+/**
+ * **KindError**
+ *
+ * An error which:
+ *
+ * - must have a "kind" type defined which can be used to categorize the error
+ * - is allowed to express other key/value pairs in the `context` property
+ *
+ * This error is generated with the `kindError(kind, _defineContext) => (msg, ctx)`
+ * higher order function.
+ *
+ * ```ts
+ * // Defines the Error
+ * const BadJuju = kindError("bad-juju", { flavor?: "" });
+ * // BadJuju {
+ * //     name: BadJuju;
+ * //     kind: "bad-juju";
+ * //     msg: "oh my god!";
+ * //     context: { flavor?: string}
+ * // }
+ * BadJuju("oh my god!");
+ * BadJuju("oh my god!", { flavor: "strawberry"})
+ * ```
+ */
+export const kindError = <
+  K extends string,
+  C extends Record<string, unknown> = EmptyObject
+>(
+  kind: K,
+  _defineContext?: C
+): KindErrorDefn<K,C> =>
+(
+  msg: string,
+  context?: C
+): KindError<K,C> => {
+
+  const err = new Error(msg) as Partial<
+    KindError<
+      typeof kind,
+      Handle<C, undefined, EmptyObject, "equals">
+    >
+  >;
+  err.name = toPascalCase(kind);
+  err.kind = toKebabCase(kind);
+  err.__kind = "KindError";
+  err.context = context as unknown as Handle<C, undefined, EmptyObject, "equals">;
+
+  return err as unknown as KindError<K,C>
+}
+
+