inferred-types 0.37.0 → 0.37.2

package/src/types/dictionary/MapTo.ts

@@ -1,428 +0,0 @@
-/* eslint-disable no-use-before-define */
-import { OptRequired } from "src/types/literal-unions";
-import {
-  DefaultManyToOneMapping,
-  DefaultOneToManyMapping,
-  DefaultOneToOneMapping,
-} from "src/runtime/dictionary/mapTo";
-import { EnumValues } from "../EnumValues";
-import { TypeDefault } from "../boolean-logic/TypeDefault";
-
-/**
- * Expresses relationship between inputs/outputs:
- */
-export enum MapCardinality {
-  /** every input results in 0:M outputs */
-  OneToMany = "I -> O[]",
-  /** every input results in 0:1 outputs */
-  OneToOne = "I -> O",
-  /** every input is an array of type I and reduced to a single O  */
-  ManyToOne = "I[] -> O",
-}
-
-export type MapCardinalityIllustrated = EnumValues<MapCardinality>;
-
-/**
- * The _user_ configuration of a **mapTo** mapper function
- * which will be finalized by merging it with the appropriate
- * default mapping type.
- */
-export interface MapConfig<
-  IR extends OptRequired | undefined = undefined,
-  D extends MapCardinalityIllustrated | undefined = undefined,
-  OR extends OptRequired | undefined = undefined
-> {
-  input?: IR;
-  output?: OR;
-  cardinality?: D;
-  /**
-   * Whether calls to the final `MapFn` will be logged to stderr
-   * for debugging purposes. Defaults to false; if you specify
-   * a _string_ for a value that will be sent to stderr along
-   * with other debugging info.
-   */
-  debug?: boolean | string;
-}
-
-/**
- * A finalized configuration of a **mapTo** mapper functions cardinality
- * relationships between _inputs_ and _outputs_.
- *
- * Note: _this configuration does _not_ yet include the actual mapping
- * configuration between the input and output._
- */
-export type FinalizedMapConfig<
-  IR extends OptRequired = MapIR<DefaultOneToManyMapping>,
-  D extends MapCardinalityIllustrated = MapCard<DefaultOneToManyMapping>,
-  OR extends OptRequired = MapOR<DefaultOneToManyMapping>
-> = Required<Omit<MapConfig<IR, D, OR>, "debug">> & { finalized: true; debug: boolean | string };
-
-/**
- * User configuration exposed by a config function which specifies the
- * cardinality already (e.g., `oneToMany()`, `manyToOne()`)
- */
-type MapCardinalityConfig<
-  IR extends OptRequired | undefined,
-  OR extends OptRequired | undefined
-> = {
-  /** whether we the input can _optionally_ be an `undefined` value or not */
-  input?: IR;
-  /** whether we the output can _optionally_ be an `undefined` value or not */
-  output?: OR;
-  /**
-   * Whether calls to the final `MapFn` will be logged to stderr
-   * for debugging purposes. Defaults to false; if you set to a string
-   * value than this will be echoed out with stderr.
-   */
-  debug?: boolean | string;
-};
-
-/**
- * **ConfiguredMap**
- *
- * A partial application of the mapTo() utility which has expressed the
- * configuration of the _inputs_ and _outputs_ and provides a `.map()`
- * method which allows the user configure the specifics of the mapping.
- */
-export type ConfiguredMap<
-  C extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>
-> = {
-  map: <I, O>(map: MapTo<I, O, C>) => Mapper<I, O, C>;
-  input: MapIR<C>;
-  cardinality: MapCard<C>;
-  output: MapOR<C>;
-  debug: boolean | string;
-};
-
-/**
- * Extracts the IR, Cardinality, and OR generics from a FinalizedMapConfig
- */
-export type DecomposeMapConfig<
-  M extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>
-> = M extends MapConfig<infer IR, infer D, infer OR>
-  ? IR extends OptRequired | undefined
-    ? D extends MapCardinalityIllustrated | undefined
-      ? OR extends OptRequired | undefined
-        ? [IR, D, OR]
-        : never
-      : never
-    : never
-  : M extends FinalizedMapConfig<infer IR, infer D, infer OR>
-  ? IR extends OptRequired
-    ? D extends MapCardinalityIllustrated
-      ? OR extends OptRequired
-        ? [IR, D, OR]
-        : never
-      : never
-    : never
-  : never;
-
-/** extracts IR from a `FinalizedMapConfig` */
-export type MapIR<
-  T extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>
-> = DecomposeMapConfig<T>[0];
-
-/**
- * extracts the MapCardinality from a `FinalizedMapConfig`
- */
-export type MapCard<
-  T extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>
-> = DecomposeMapConfig<T>[1];
-
-/** extracts OR from a `FinalizedMapConfig` */
-export type MapOR<
-  T extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>
-> = DecomposeMapConfig<T>[2];
-
-/**
- * Merges the types of a userland configuration with a default configuration
- */
-export type AsFinalizedConfig<
-  U extends MapConfig<
-    OptRequired | undefined,
-    MapCardinalityIllustrated | undefined,
-    OptRequired | undefined
-  >,
-  D extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>
-> = TypeDefault<U, D> extends FinalizedMapConfig<infer IR, infer C, infer OR>
-  ? FinalizedMapConfig<IR, C, OR>
-  : never;
-
-export type MapperApi = {
-  /**
-   * Provides opportunity to configure _input_, _output_, and _cardinality_
-   * prior to providing a mapping function.
-   *
-   * Note: _the defaults for configuration are defined by the_ `DEFAULT_ONE_TO_MANY_MAPPING`
-   * _constant made available as a symbol from this library._
-   */
-  config: <
-    C extends MapConfig<
-      OptRequired, //
-      MapCardinalityIllustrated,
-      OptRequired
-    >
-  >(
-    config: C
-  ) => ConfiguredMap<
-    AsFinalizedConfig<
-      C, //
-      DefaultOneToManyMapping
-    >
-  >;
-
-  /**
-   * Provides a nice 1:1 ratio between the input and output.
-   *
-   * By default the input and output are considered to be _required_
-   * properties but this can be changed with the options hash provided.
-   * ```ts
-   * const mapper = mapTo.oneToOne().map(...);
-   * // add in ability to filter out some inputs
-   * const mapAndFilter = mapTo.oneToOne({ output: "opt" })
-   * ```
-   */
-  oneToOne: <C extends MapCardinalityConfig<OptRequired, OptRequired>>(
-    config?: C
-  ) => ConfiguredMap<
-    AsFinalizedConfig<
-      C, //
-      DefaultOneToOneMapping
-    >
-  >;
-
-  /**
-   * **manyToOne** _mapping_
-   *
-   * Provides a configuration where multiple inputs `I[]` will be mapped to a
-   * single output `O`.
-   *
-   * Choosing this configuration will, by default, set both input and output
-   * to be "required" but you can change this default if you so choose.
-   */
-  manyToOne: <
-    C extends MapCardinalityConfig<
-      OptRequired | undefined, //
-      OptRequired | undefined
-    >
-  >(
-    config?: C
-  ) => ConfiguredMap<
-    AsFinalizedConfig<
-      C, //
-      DefaultManyToOneMapping
-    >
-  >;
-
-  oneToMany: <
-    C extends MapCardinalityConfig<
-      OptRequired | undefined, //
-      OptRequired | undefined
-    >
-  >(
-    config?: C
-  ) => ConfiguredMap<
-    AsFinalizedConfig<
-      C, //
-      DefaultOneToManyMapping
-    >
-  >;
-};
-
-export type MapInput<
-  I, //
-  IR extends OptRequired,
-  C extends MapCardinalityIllustrated
-> = C extends MapCardinality.OneToMany | "I -> O[]"
-  ? IR extends "opt"
-    ? I | undefined
-    : I
-  : C extends MapCardinality.OneToOne | "I -> O"
-  ? IR extends "opt"
-    ? I | undefined
-    : I
-  : C extends MapCardinality.ManyToOne | "I[] -> O"
-  ? IR extends "opt"
-    ? I[] | undefined
-    : I[]
-  : never;
-
-export type MapOutput<
-  O, //
-  OR extends OptRequired,
-  C extends MapCardinalityIllustrated
-> = C extends MapCardinality.OneToMany | "I -> O[]"
-  ? OR extends "opt"
-    ? O[]
-    : [O, ...O[]]
-  : C extends MapCardinality.OneToOne | "I -> O"
-  ? OR extends "opt"
-    ? O | null
-    : O
-  : C extends MapCardinality.ManyToOne | "I[] -> O"
-  ? OR extends "opt"
-    ? O | null
-    : O
-  : never;
-
-/**
- * **MapTo<I, O>**
- *
- * A mapping function between an input type `I` and output type `O`. Defaults to using
- * the _default_ OneToMany mapping config.
- *
- * **Note:** this type is designed to guide the userland mapping; refer
- * to `MapFn` if you want the type output by the `mapFn()` utility.
- */
-export type MapTo<
-  I,
-  O,
-  C extends FinalizedMapConfig<
-    OptRequired,
-    MapCardinalityIllustrated,
-    OptRequired
-  > = DefaultOneToManyMapping
-> = MapIR<C> extends "opt"
-  ? (source?: MapInput<I, MapIR<C>, MapCard<C>>) => MapOutput<O, MapOR<C>, MapCard<C>>
-  : (source: MapInput<I, MapIR<C>, MapCard<C>>) => MapOutput<O, MapOR<C>, MapCard<C>>;
-
-export type MapFnOutput<
-  I,
-  O,
-  S,
-  OR extends OptRequired,
-  C extends MapCardinalityIllustrated
-> = C extends "I -> O[]" | MapCardinality.OneToMany
-  ? S extends I[]
-    ? OR extends "opt"
-      ? O[]
-      : [O, ...O[]]
-    : OR extends "opt"
-    ? O[] | null
-    : O[]
-  : C extends MapCardinality.OneToOne | "I -> O"
-  ? S extends I[]
-    ? OR extends "opt"
-      ? O[]
-      : [O, ...O[]]
-    : OR extends "opt"
-    ? O | null
-    : O
-  : C extends MapCardinality.ManyToOne | "I[] -> O"
-  ? S extends I[][]
-    ? OR extends "opt"
-      ? O[]
-      : [O, ...O[]]
-    : OR extends "opt"
-    ? O | null
-    : O
-  : never;
-
-export type MapFnInput<I, IR extends OptRequired, D extends MapCardinalityIllustrated> = D extends
-  | "I -> O[]"
-  | MapCardinality.OneToMany
-  ? IR extends "opt"
-    ? I | I[] | undefined
-    : I | I[]
-  : D extends MapCardinality.OneToOne | "I -> O"
-  ? IR extends "opt"
-    ? I | I[] | undefined
-    : I | I[]
-  : D extends MapCardinality.ManyToOne | "I[] -> O"
-  ? IR extends "opt"
-    ? I[] | I[][] | undefined
-    : I[] | I[][]
-  : never;
-
-/**
- * The mapping function provided by the `mapFn()` utility. This _fn_
- * is intended to be used in two ways:
- *
- * 1. Iterative:
- *    ```ts
- *    const m = mapTo<I,O>(i => [ ... ]);
- *    // maps inputs to outputs
- *    const out = inputs.map(m);
- *    ```
- * 2. Block:
- *    ```ts
- *    // maps inputs to outputs (filtering or splitting where appr.)
- *    const out2 = m(inputs);
- *    ```
- */
-export type MapFn<
-  I,
-  O,
-  C extends FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>
-> = MapIR<C> extends "opt"
-  ? <S extends MapFnInput<I, MapIR<C>, MapCard<C>>>(
-      source?: S
-    ) => MapFnOutput<I, O, S, MapOR<C>, MapCard<C>>
-  : <S extends MapFnInput<I, MapIR<C>, MapCard<C>>>(
-      source: S
-    ) => MapFnOutput<I, O, S, MapOR<C>, MapCard<C>>;
-
-/**
- * **Mapper**
- *
- * A fully configured _mapper_ stemming from the **mapTo()** utility. It is both a mapping
- * function and a dictionary which describes the mapper's properties.
- * ```ts
- * const m = mapTo.oneToOne().map( ... );
- * const mapped = m(inputs);
- * const mappedOver = inputs.map(m);
- * ```
- *
- * Note: the root of a `Mapper` is the mapper function but
- * this is combined with a dictionary of settings and types
- * which you can use. For instance, look at the `fnSignature`
- * property to get the _type_ signature of the map function.
- */
-export type Mapper<
-  I = unknown,
-  O = unknown,
-  C extends FinalizedMapConfig<
-    OptRequired,
-    MapCardinalityIllustrated,
-    OptRequired
-  > = FinalizedMapConfig<OptRequired, MapCardinalityIllustrated, OptRequired>
-> = {
-  input: MapIR<C>;
-  output: MapOR<C>;
-  cardinality: MapCard<C>;
-  debug: boolean | string;
-  inputType: I;
-  outputType: O;
-  /**
-   * Provides the _type_ information for mapper function.
-   *
-   * Note: _this is just a **type**_ not the actual function which positioned
-   * at the root of the Mapper type
-   */
-  fnSignature: MapFn<I, O, C>;
-} & MapFn<I, O, C>;
-
-/**
- * **MapInputFrom**
- *
- * Type utility which extracts the `I` type from a fully configured `Mapper`
- */
-export type MapInputFrom<T extends Mapper> = T extends Mapper<infer I> ? I : never;
-
-/**
- * **MapOutputFrom**
- *
- * Type utility which extracts the output [`O`] type from a fully configured `Mapper`
- */
-export type MapOutputFrom<T extends Mapper> = T extends Mapper<any, infer O> ? O : never;
-
-/**
- * **MapCardinalityFrom**
- *
- * Type utility which extracts _cardinality_ of a `Mapper`'s inputs to outputs
- */
-export type MapCardinalityFrom<T extends Mapper> = T extends Mapper<any, any, infer C>
-  ? C extends FinalizedMapConfig<OptRequired, infer Cardinality, OptRequired>
-    ? Cardinality
-    : never
-  : never;

package/src/types/dictionary/MutableProps.ts

@@ -1,19 +0,0 @@
-import { ExpandRecursively } from "../ExpandRecursively";
-import { Keys } from "../Keys";
-import { Mutable } from "../Mutable";
-
-/**
- * Given a dictionary of type `<T>`, this utility function will
- * make the `<M>` generic property _mutable_ and all other _read-only_.
- *
- * ```ts
- * // { foo: string, bar?: Readonly<number> }
- * type Example = MutableProps<{
- *    foo: Readonly<string>,
- *    bar?: number
- * }, "foo">;
- * ```
- */
-export type MutableProps<T extends {}, M extends keyof T & string> = ExpandRecursively<
-  Mutable<Pick<T, M>> & Readonly<Pick<T, Keys<T, M>>>
->;

package/src/types/dictionary/RequireProps.ts

@@ -1,15 +0,0 @@
-import { ExpandRecursively } from "../ExpandRecursively";
-
-/**
- * Given a dictionary of type `<T>`, this utility function will
- * make the `<R>` generic property _required_ (use a union to make
- * more than one prop required).
- *
- * ```ts
- * // { foo: string, bar?: number }
- * type Example = RequireProps<{foo?: string, bar?: number}, "foo">;
- * ```
- */
-export type RequireProps<T extends {}, R extends keyof T> = ExpandRecursively<
-  Required<Pick<T, R>> & T
->;

package/src/types/dictionary/SameKeys.ts

@@ -1,11 +0,0 @@
-/**
- * **SameKeys**
- *
- * Creates a _type_ with the same _keys_ as `T` but sets all values of these keys to `A` (which is
- * **any** by default).
- * 
- * Note: meant to be used as part of an _extends_ clause in most cases.
- */
-export type SameKeys<T extends object, A extends any = any> = {
-  [P in keyof T]: A;
-};

package/src/types/dictionary/index.ts

@@ -1,21 +0,0 @@
-// #autoindex
-// #region auto-indexed files
-// index last changed at: 8th Aug, 2022, 09:51 AM ( GMT-7 )
-// hash-code: 55881f7d
-
-// file exports
-export * from "./DictPartialApplication";
-export * from "./DictChangeValue";
-export * from "./DictPrependWithFn";
-export * from "./DictReturnValues";
-export * from "./Get";
-export * from "./MapTo";
-export * from "./MutableProps";
-export * from "./RequireProps";
-export * from "./SameKeys";
-export * from "./props";
-
-// #endregion auto-indexed files
-
-// see https://github.com/inocan-group/do-devops/docs/autoindex.md
-// for more info

package/src/types/dictionary/props.ts

@@ -1,145 +0,0 @@
-import { Alpha } from "../alphabetic/alpha-characters";
-import { Keys } from "../Keys";
-
-/**
- * Extracts the _required_ keys in the object's type. You also may
- * optionally filter by the _value_ of the key.
- */
-export type RequiredKeys<T extends object, V extends any = any> = {
-  [K in keyof T]-?: {} extends { [P in K]: T[K] }
-    ? never //
-    : T[K] extends V
-    ? K
-    : never;
-}[keyof T];
-
-/**
- * Extracts the intersecting/common keys to two objects
- */
-export type IntersectingKeys<
-  T extends Record<string, any> | readonly string[],
-  U extends Record<string, any> | readonly string[]
-> = {
-  [K in keyof T]: K extends Keys<U> ? K : never;
-}[keyof T];
-
-/**
- * Extracts the _optional_ keys in the object's type. You also may
- * optionally filter by the _value_ of the key.
- */
-export type OptionalKeys<T extends object, V extends any = any> = {
-  [K in keyof T]-?: {} extends { [P in K]: T[K] }
-    ? V extends T[K]
-      ? K
-      : never //
-    : never;
-}[keyof T];
-
-/**
- * The _keys_ on a given object `T` which have a literal value of `W`.
- *
- * Optionally, you may provide a generic `E` to exclude certain keys in
- * result set.
- * ```ts
- * // "foo"
- * type Str = KeysWithValue<{ foo: "hi"; bar: 5 }>;
- * ```
- */
-export type KeysWithValue<W extends any, T extends object> = {
-  [K in keyof T]: T[K] extends W ? Readonly<K> : never;
-}[keyof T];
-
-/**
- * A `PrivateKey` must start with a `_` character and then follow with
- * an alphabetic character
- */
-export type PrivateKey = `_${Alpha}${string}`;
-
-/**
- * Keys on an object which have a `_` character as first part of the
- * name are considered private and this utility will create a union
- * of all the keys in this category.
- */
-export type PrivateKeys<T extends object> = {
-  [K in keyof T]: K extends `_${string}` ? K : never;
-}[keyof T];
-
-/**
- * **PublicKeys**
- *
- * Builds a union type of all keys which are "public" where a public
- * key is any key which _does not_ start with the `_` character.
- */
-export type PublicKeys<T extends object> = {
-  [K in keyof T]: K extends `_${string}` ? never : K;
-}[keyof T];
-
-export type StringKeys<T extends object> = {
-  [K in keyof T]: K extends string ? Readonly<K> : never;
-}[keyof T];
-
-/**
- * The keys of an object which _are not_ a string type
- */
-export type NonStringKeys<T extends object> = {
-  [K in keyof T]: K extends string ? never : Readonly<K>;
-}[keyof T];
-
-export type NumericKeys<T extends object> = {
-  [K in keyof T]: K extends number ? Readonly<K> : never;
-}[keyof T];
-
-export type NonNumericKeys<T extends object> = {
-  [K in keyof T]: K extends number ? never : Readonly<K>;
-}[keyof T];
-
-/**
- * **RequiredProps**
- *
- * Reduces an object type to only key/value pairs where the key is required
- */
-export type RequiredProps<T extends object> = Pick<T, RequiredKeys<T>>;
-
-/**
- * **OptionalProps**
- *
- * Reduces an object to only key/value pairs where the key is optional
- */
-export type OptionalProps<T extends object> = Pick<T, OptionalKeys<T>>;
-
-/**
- * **WithValue**
- *
- * Reduces an object's type down to only those key/value pairs where the
- * value is of type `W`.
- * ```ts
- * const foo = { a: 1, b: "hi", c: () => "hello" }
- * // { c: () => "hello" }
- * type W = WithValue<Function, typeof foo>
- * ```
- */
-export type WithValue<
-  W extends any,
-  T extends object,
-  E extends any = undefined
-> = undefined extends E
-  ? // no exclusion provided
-    Pick<T, KeysWithValue<W, T>>
-  : // Exclude using E
-    Omit<Pick<T, KeysWithValue<W, T>>, KeysWithValue<E, T>>;
-
-export type DictionaryWithoutValue<TDict extends object, TWithoutValue> = Omit<
-  TDict,
-  KeysWithValue<TWithoutValue, TDict>
->;
-
-/**
- * Reduces an object to only the key/value pairs where the key is a
- * string.
- */
-export type WithStringKeys<T extends object> = Omit<T, NonStringKeys<T>>;
-
-/**
- * Reduces an object to only the key/value pairs where the key is numeric.
- */
-export type WithNumericKeys<T extends object> = Omit<T, NonNumericKeys<T>>;

package/src/types/fluent/fluent.ts

@@ -1,61 +0,0 @@
-/* eslint-disable no-use-before-define */
-
-/**
- * **ToFluent**
- *
- * Converts the typing of a dictionary of functions into the same
- * function signatures but changes the return type to be the Fluent API.
- *
- * **Note:** this utility also allows a non-fluent API surface `X` to be included as
- * part of the API surface if this is desired.
- */
-export type ToFluent<
-  T extends { [key: string]: (...args: any[]) => any },
-  X extends object = {}
-> = {
-  [K in keyof T]: (...args: Parameters<T[K]>) => ToFluent<T, X> & X;
-} & X;
-
-/**
- * A _pure_ Fluent API which promotes an API surface where _every_ API endpoint must be a function
- * which returns the same API surface.
- *
- * To provide value, this style of Fluent API will need to perform useful _side effects_ when functions
- * on the API surface are called as this structure does not provide any means to maintain an internal state
- * which can be returned later.
- *
- * **Note:** _if you prefer a Fluent API with means to _escape_ with an internally managed state then
- * you should prefer the use of the `FluentApi` type._
- */
-export type PureFluentApi<
-  TApi extends Record<string, (...args: any[]) => PureFluentApi<TApi, any>>,
-  TExclude extends string = ""
-> = { [P in keyof TApi]: (...args: Parameters<TApi[P]>) => PureFluentApi<Omit<TApi, TExclude>> };
-
-/**
- * Represents a **Fluent API** which exposes a API as a dictionary of functions. These functions will:
- *
- * 1. mutate an internal state or cause useful side-effects
- * 2. return the same API surface
- *
- * While in the case where the Fluent API is used to cause useful side effects, you might only
- * need the Fluent API surface to achieve your objectives but if instead it is used to
- * build up a useful _internal state_, then we must allow for
- * If this were 100% pure, however, the internal state would be unreachable and this pattern would
- * not be very valuable. Therefore, a secondary API, is expressed which allows for non-fluent
- *
- * At some point the internal state will be configured "enough" and the API will be extended to allow
- * the extraction of this state. This functional goal is expressed with the following generics:
- *
- * - `TFluent` is the fluent API which exposes a dictionary of functions
- * - `TEscape` is a non-fluent API used to do whatever you like but often is the means to
- * pass out the interior state which has been configured by the fluent parts of the API
- * - `TExclude` represents part of the API which -- due to the internal state -- should be hidden
- */
-// export type FluentApi<
-//   TFluent extends {
-//     [K in keyof TFluent]: (...args: Parameters<TFluent[K]>) => FluentApi<TFluent, TEscape>;
-//   },
-//   TEscape extends object = {},
-//   TExclude extends string = ""
-// > = Omit<TFluent & TEscape, TExclude>;