rivo/Obj/index.d.ts

🤖 The ultimate library you need for composable type-level programming in TypeScript, powered by HKT.

import type CamelizeFn from "./Camelize";
import type FromEntriesFn from "./FromEntries";
import type GetFn from "./Get";
import type MapValuesFn from "./MapValues";
import type MergeFn from "./Merge";
import type MergeRFn from "./MergeR";
import type OmitFn from "./Omit";
import type OmitByFn from "./OmitBy";
import type OmitWFn from "./OmitW";
import type PickFn from "./Pick";
import type SimpleMergeFn from "./SimpleMerge";
import type SimpleMergeRFn from "./SimpleMergeR";
import type SnakeizeFn from "./Snakeize";
import type SpreadFn from "./Spread";
import type TryGetFn from "./TryGet";
import type ValueOfFn from "./ValueOf";
import type { Fn1, PartialApply } from "../HKT";
import type { List } from "../List";

/***********
 * Methods *
 ***********/
/**
 * Methods for `Obj`.
 */
export namespace Obj {
  /**
   * [Fn] Merge two objects together. Optional keys are considered.
   *
   * However, this can cause some performance issues and may break TS in rare cases,
   * so it is recommended to use {@link SimpleMerge} when you're sure that
   * the two objects have no optional properties.
   *
   * Sig: `(l: object, r: object) => object`
   *
   * @example
   * ```typescript
   * type A = { a: number; b?: string };
   * type B = { a: boolean; c: string };
   * type R = $<Obj.Merge, A, B>;
   * //   ^?: { a: boolean; b?: string; c: string }
   * ```
   *
   * @see {@link SimpleMerge}
   */
  export type Merge = MergeFn;
  /**
   * [Fn] The flipped version of {@link Merge}.
   *
   * Sig: `(r: object, l: object) => object`
   *
   * The `R` suffix (short for **R**ight or **R**everse) means that the arguments are flipped.
   *
   * @example
   * ```typescript
   * type A = { a: number; b?: string };
   * type B = { a: boolean; c: string };
   * type R = $<Obj.MergeR, B, A>;
   * //   ^?: { a: boolean; b?: string; c: string }
   * ```
   *
   * @see {@link Merge}
   */
  export type MergeR = MergeRFn;
  /**
   * [Fn] Merge two objects together. Optional keys are considered.
   *
   * However, this can cause some performance issues and may break TS in rare cases,
   * so it is recommended to use {@link SimpleMergeWith} when you're sure that
   * the two objects have no optional properties.
   *
   * Sig: `(l: object) => object`
   *
   * @example
   * ```typescript
   * type A = { a: number; b?: string };
   * type B = { a: boolean; c: string };
   * type R = $<Obj.MergeWith<B>, A>;
   * //   ^?: { a: boolean; b?: string; c: string }
   * ```
   *
   * @see {@link SimpleMergeWith}
   */
  export type MergeWith<R extends object> = PartialApply<MergeFn, [R], "_1">;

  /**
   * [Fn] Simply merge two objects together without considering optional properties.
   *
   * It is recommended to use to optimize performance when you're sure that
   * the two objects have no optional properties, otherwise use {@link Merge}.
   *
   * Sig: `(l: object, r: object) => object`
   *
   * @example
   * ```typescript
   * type A = { a: number; b: string };
   * type B = { a: boolean; c: string };
   * type R = $<Obj.SimpleMerge, A, B>;
   * //   ^?: { a: boolean; b: string; c: string }
   * ```
   *
   * @see {@link Merge}
   */
  export type SimpleMerge = SimpleMergeFn;
  /**
   * [Fn] The flipped version of {@link SimpleMerge}.
   *
   * The `R` suffix (short for **R**ight or **R**everse) means that the arguments are flipped.
   *
   * Sig: `(r: object, l: object) => object`
   *
   * @example
   * ```typescript
   * type A = { a: number; b: string };
   * type B = { a: boolean; c: string };
   * type R = $<Obj.SimpleMergeR, B, A>;
   * //   ^?: { a: boolean; b: string; c: string }
   * ```
   */
  export type SimpleMergeR = SimpleMergeRFn;
  /**
   * [Fn] Simply merge two objects together without considering optional properties.
   *
   * It is recommended to use to optimize performance when you're sure that
   * the two objects have no optional properties, otherwise use {@link MergeWith}.
   *
   * Sig: `(l: object) => object`
   *
   * @example
   * ```typescript
   * type A = { a: number; b: string };
   * type B = { a: boolean; c: string };
   * type R = $<Obj.SimpleMergeWith<B>, A>;
   * //   ^?: { a: boolean; b: string; c: string }
   * ```
   *
   * @see {@link MergeWith}
   */
  export type SimpleMergeWith<R extends object> = PartialApply<SimpleMergeFn, [R], "_1">;

  /**
   * [Fn] Spread a {@link List} of objects into one object.
   *
   * Sig: `(os: List<object>) => object`
   */
  export type Spread = SpreadFn;

  /**
   * [Fn] Omit properties from an object.
   *
   * Sig: `<K extends PropertyKey>[k: K](o: { [P in K]: unknown }) => object`
   */
  export type Omit<K extends PropertyKey> = PartialApply<OmitFn, [K]>;
  /**
   * [Fn] Less strict version of {@link Omit}.The **W** suffix (short for **W**idening) means that
   * the object type is widened to `object`.
   *
   * Sig: `[k: PropertyKey](o: object) => object`
   */
  export type OmitW<K extends PropertyKey> = PartialApply<OmitWFn, [K]>;
  /**
   * [Fn] Omit pairs from an object where the value satisfies the predicate.
   *
   * Sig: `<T, K extends PropertyKey>[f: (x: T) => boolean](o: Record<K, T>) => Record<K, T>`
   */
  export type OmitBy<F extends Fn1<never, boolean>> = PartialApply<OmitByFn, [F]>;

  /**
   * Pick properties from an object.
   *
   * Sig: `<K extends PropertyKey>[k: K](o: { [P in K]: unknown }) => object`
   */
  export type Pick<K extends PropertyKey> = PartialApply<PickFn, [K]>;
  /**
   * [Fn] Less strict version of {@link Pick}.The **W** suffix (short for **W**idening) means that
   * the object type is widened to `object`.
   *
   * Sig: `[k: PropertyKey](o: object) => object`
   */
  export type PickW<K extends PropertyKey> = PartialApply<PickFn, [K]>;

  export type ValueOf = ValueOfFn;

  export type Get<K extends PropertyKey> = PartialApply<GetFn, [K]>;
  export type GetFrom<O extends object> = PartialApply<GetFn, [O], "_1">;
  export type TryGet<K extends PropertyKey> = PartialApply<TryGetFn, [K]>;
  export type TryGetFrom<O extends object> = PartialApply<TryGetFn, [O], "_1">;

  /**
   * [Fn] Apply a function to each value in an object.
   *
   * Sig: `<T, U, K extends PropertyKey>[f: (x: T => U)](o: Record<K, T>) => Record<K, U>`
   */
  export type MapValues<F extends Fn1> = PartialApply<MapValuesFn, [F]>;

  export type Snakeize = SnakeizeFn;
  export type Camelize = CamelizeFn;
}

/******************
 * Static members *
 ******************/
/**
 * [Fn] Convert a {@link List} (i.e., fixed-length tuple) of key-value pairs into an
 * object.
 *
 * Sig: `<K extends PropertyKey, V>(entries: List<readonly [K, V]>) => Record<K, V>`
 */
export type Obj$$FromEntries = FromEntriesFn;