rivo/helpers-fn.d.ts

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

import type { TypeCastError } from "./Error";
import type { Args, Fn } from "./HKT";
import type { Err, Ok, Result } from "./Result";
import type { All, Any, Eq as EqImpl, Extends, IsAny, IsNever, IsUnknown } from "./helpers";
import type { Show as ShowT } from "./typeclass";
import type { Show } from "./typeclass/Show/Show";

type ShowW<T> = T extends ShowT ? Show<T> : "<<type>>";

/**
 * [Fn] Cast a value to type `T`.
 *
 * Sig: `<T>(x: unknown) => Result<T, TypeCastError>`
 */
export interface As<T> extends Fn<[unknown], Result<T, TypeCastError>> {
  def: ([x]: Args<this>) => typeof x extends T ? Ok<typeof x>
  : Err<
      TypeCastError<// @ts-ignore - Type instantiation is excessively deep and possibly infinite.
      `Expected value of type '${ShowW<T>}', but got '${ShowW<typeof x>}' instead.`>
    >;
}

/**
 * [Fn] Force cast a value to type `T`. Return `never` if the cast fails.
 *
 * Type safety is **not guaranteed**.
 *
 * Sig: `<T>(x: unknown) => T`
 */
export interface AsUnsafe<T> extends Fn<[unknown], T> {
  def: ([x]: Args<this>) => typeof x extends T ? typeof x : never;
}

/**
 * [Fn] Ask for a value of type `T`.
 */
export interface Ask<T> extends Fn<[T], T> {
  def: ([x]: Args<this>) => typeof x;
}

export interface IsAnyFn extends Fn<[unknown], boolean> {
  def: ([x]: Args<this>) => IsAny<typeof x>;
}

export interface IsNeverFn extends Fn<[unknown], boolean> {
  def: ([x]: Args<this>) => IsNever<typeof x>;
}

export interface IsUnknownFn extends Fn<[unknown], boolean> {
  def: ([x]: Args<this>) => IsUnknown<typeof x>;
}

export interface AllFn extends Fn<[readonly boolean[]], boolean> {
  def: ([bs]: Args<this>) => All<typeof bs>;
}

export interface AnyFn extends Fn<[readonly boolean[]], boolean> {
  def: ([bs]: Args<this>) => Any<typeof bs>;
}

export interface EqFn extends Fn<[unknown, unknown], boolean> {
  def: ([x, y]: Args<this>) => EqImpl<typeof x, typeof y>;
}

export interface ExtendsFn extends Fn<[unknown, unknown], boolean> {
  def: ([y, x]: Args<this>) => Extends<typeof x, typeof y>;
}

/**
 * [Fn] Checks whether `T` exactly equals `U`.
 *
 * @example
 * ```typescript
 * type R1 = Eq<1, 1>;
 * //   ^?: true
 * type R2 = Eq<1, number>;
 * //   ^?: false
 * type R3 = Eq<1, 1 | 2>;
 * //   ^?: false
 * ```
 */
export interface Eq<U> extends Fn<[unknown], boolean> {
  def: ([x]: Args<this>) => EqImpl<typeof x, U>;
}