retuple 1.0.0-next.1 → 1.0.0-next.3

package/dist/index.d.cts

@@ -1,57 +1,103 @@
+export type nonNullable = typeof nonNullable;
+export type truthy = typeof truthy;
+export type safe = typeof safe;
+export type safeAsync = typeof safeAsync;
+export type safePromise = typeof safePromise;
 export type Ok<T> = OkTuple<T> & Retuple<T, never>;
 export type Err<E> = ErrTuple<E> & Retuple<never, E>;
 export type Result<T, E> = (OkTuple<T> | ErrTuple<E>) & Retuple<T, E>;
 export { type ResultAsync };
-export declare class RetupleUnwrapFailed<E = unknown> extends Error {
+/**
+ * ## Retuple Unwrap Failed
+ *
+ * An error which occurs when calling `$unwrap` on `Err`.
+ */
+export declare class RetupleUnwrapFailed<const E = unknown> extends Error {
     value: E;
     constructor(value: E, msg?: string);
 }
-export declare class RetupleUnwrapErrFailed<T = unknown> extends Error {
+/**
+ * ## Retuple Unwrap Err Failed
+ *
+ * An error which occurs when calling `$unwrapErr` on `Ok`.
+ */
+export declare class RetupleUnwrapErrFailed<const T = unknown> extends Error {
     value: T;
     constructor(value: T, msg?: string);
 }
-export declare class RetupleExpectFailed<E = unknown> extends Error {
+/**
+ * ## Retuple Expect Failed
+ *
+ * An error which occurs when calling `$expect` on `Err`, and when the value
+ * contained in the `Err` is not an instance of `Error`.
+ */
+export declare class RetupleExpectFailed<const E = unknown> extends Error {
     value: E;
     constructor(value: E);
 }
+/**
+ * ## Retuple Thrown Value Error
+ *
+ * An error constructed when a safe function call throws or rejects, when the
+ * thrown error or rejected value is not an instance of `Error`, and when no
+ * map error function is provided.
+ */
 export declare class RetupleThrownValueError extends Error {
     value: unknown;
     constructor(value: unknown);
 }
+/**
+ * ## Retuple Invalid Result Error
+ *
+ * An error constructed when a safe function call throws or rejects, when the
+ * thrown error or rejected value is not an instance of `Error`, and when no
+ * map error function is provided.
+ */
+export declare class RetupleInvalidResultError extends Error {
+    value: unknown[];
+    constructor(value: unknown[]);
+}
 /**
  * ## Result
  *
  * @TODO
  */
-export declare const Result: {
-    Ok: typeof Ok;
-    Err: typeof Err;
-    from: typeof from;
-    safe: typeof safe;
-    safeAsync: typeof safeAsync;
-    safePromise: typeof safePromise;
-};
-export default Result;
+export declare function Result<R extends [err: null | undefined, value: unknown] | [err: unknown, value: null | undefined]>(resultLike: R): (R extends [null | undefined, infer T] ? Ok<T> : R extends [infer E, null | undefined] ? Err<E> : never) extends Ok<infer T> | Err<infer E> ? Result<T, NonNullable<E>> : never;
+export declare namespace Result {
+    var Ok: typeof import(".").Ok;
+    var Err: typeof import(".").Err;
+    var nonNullable: typeof import(".").nonNullable;
+    var truthy: typeof import(".").truthy;
+    var safe: typeof import(".").safe;
+    var safeAsync: typeof import(".").safeAsync;
+    var safePromise: typeof import(".").safePromise;
+}
 /**
  * ## Ok
  *
  * @TODO
  */
 export declare function Ok(): Ok<void>;
-export declare function Ok<T>(val: T): Ok<T>;
+export declare function Ok<const T>(val: T): Ok<T>;
 /**
  * ## Err
  *
  * @TODO
  */
 export declare function Err(): Err<void>;
-export declare function Err<E>(err: E): Err<E>;
+export declare function Err<const E>(err: E): Err<E>;
+/**
+ * Construct a {@link Result} from a value. If the value is neither null or
+ * undefined, the result is `Ok`.
+ */
+export declare function nonNullable<const T>(value: T): Result<NonNullable<T>, true>;
+export declare function nonNullable<const T, const E>(value: T, error: () => E): Result<NonNullable<T>, E>;
 /**
  * Construct a {@link Result} from a value. If the value is truthy, the result
  * is `Ok`.
  */
-export declare function from<T>(value: T): Result<Truthy<T>, true>;
-export declare function from<T, E>(value: T, error: () => E): Result<Truthy<T>, E>;
+export declare function truthy<const T>(value: T): Result<Truthy<T>, true>;
+export declare function truthy<const T, const E>(value: T, error: () => E): Result<Truthy<T>, E>;
 /**
  * Construct a {@link Result} from a synchronous function call. If the function
  * returns without throwing, the result is `Ok`.
@@ -78,7 +124,7 @@ export declare function safePromise<T, E>(promise: PromiseLike<T>, mapError: (er
 declare class ResultAsync<T, E> {
     #private;
     constructor(inner: PromiseLike<Result<T, E>>);
-    then<TResult1 = Result<T, E>, TResult2 = never>(onfulfilled?: ((result: Result<T, E>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: (reason: any) => TResult2 | PromiseLike<TResult2>): PromiseLike<TResult1 | TResult2>;
+    then<U = Result<T, E>, F = never>(onfulfilled?: ((value: Result<T, E>) => U | PromiseLike<U>) | null | undefined, onrejected?: ((reason: any) => F | PromiseLike<F>) | null | undefined): PromiseLike<U | F>;
     /**
      * @TODO
      */
@@ -102,7 +148,7 @@ declare class ResultAsync<T, E> {
     /**
      * @TODO
      */
-    $unwrapOrElse<U = T>(this: ResultAsync<T, E>, f: () => U): Promise<T | U>;
+    $unwrapOrElse<U>(this: ResultAsync<T, E>, f: () => U): Promise<T | U>;
     /**
      * @TODO
      */
@@ -114,39 +160,52 @@ declare class ResultAsync<T, E> {
     /**
      * @TODO
      */
-    $mapOr<U>(this: ResultAsync<T, E>, def: U, f: (val: T) => U): ResultAsync<U, E>;
+    $mapOr<U, V>(this: ResultAsync<T, E>, def: U, f: (val: T) => V): ResultAsync<U | V, E>;
     /**
      * @TODO
      */
-    $mapOrElse<U>(this: ResultAsync<T, E>, def: (err: E) => U, f: (val: T) => U): ResultAsync<U, E>;
+    $mapOrElse<U, V>(this: ResultAsync<T, E>, def: (err: E) => U, f: (val: T) => V): ResultAsync<U | V, E>;
+    /**
+     * ## $assertOr
+     *
+     * {@link Retuple.$assertOr|$assertOr}
+     */
+    $assertOr<U, F>(this: ResultAsync<T, E>, def: Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<Truthy<T>, E | F>;
+    $assertOr<U, F, A extends T>(this: ResultAsync<T, E>, def: Result<U, F> | PromiseLike<Result<U, F>>, predicate: (val: T) => val is A): ResultAsync<U | A, E | F>;
+    $assertOr<U, F>(this: ResultAsync<T, E>, def: Result<U, F> | PromiseLike<Result<U, F>>, condition: (val: T) => unknown): ResultAsync<T | U, E | F>;
+    $assertOrElse<U, F>(this: ResultAsync<T, E>, def: () => Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<Truthy<T>, E | F>;
+    $assertOrElse<U, F, A extends T>(this: ResultAsync<T, E>, def: () => Result<U, F> | PromiseLike<Result<U, F>>, predicate: (val: T) => val is A): ResultAsync<U | A, E | F>;
+    $assertOrElse<U, F>(this: ResultAsync<T, E>, def: () => Result<U, F> | PromiseLike<Result<U, F>>, condition: (val: T) => unknown): ResultAsync<T | U, E | F>;
     /**
      * @TODO
      */
-    $or<U = T, F = E>(this: ResultAsync<T, E>, or: Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<T | U, E | F>;
+    $or<U, F>(this: ResultAsync<T, E>, or: Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<T | U, E | F>;
     /**
      * @TODO
      */
-    $orElse<U = T, F = E>(this: ResultAsync<T, E>, f: (err: E) => Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<T | U, E | F>;
+    $orElse<U, F>(this: ResultAsync<T, E>, f: (err: E) => Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<T | U, E | F>;
     /**
      * @TODO
      */
-    $orSafe<U = T, F = Error>(this: ResultAsync<T, E>, f: (err: E) => U | PromiseLike<U>, mapError?: (err: unknown) => F): ResultAsync<T | U, E | F>;
+    $orSafe<U>(this: ResultAsync<T, E>, f: (err: E) => U | PromiseLike<U>): ResultAsync<T | U, E | Error>;
+    $orSafe<U, F>(this: ResultAsync<T, E>, f: (err: E) => U | PromiseLike<U>, mapError: (err: unknown) => F): ResultAsync<T | U, E | F>;
     /**
      * @TODO
      */
-    $and<U = T, F = E>(this: ResultAsync<T, E>, and: Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<U, E | F>;
+    $and<U, F>(this: ResultAsync<T, E>, and: Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<U, E | F>;
     /**
      * @TODO
      */
-    $andThen<U = T, F = E>(this: ResultAsync<T, E>, f: (val: T) => Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<U, E | F>;
+    $andThen<U, F>(this: ResultAsync<T, E>, f: (val: T) => Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<U, E | F>;
     /**
      * @TODO
      */
-    $andThrough<F = E>(this: ResultAsync<T, E>, f: (val: T) => Result<any, F> | PromiseLike<Result<any, F>>): ResultAsync<T, E | F>;
+    $andThrough<F>(this: ResultAsync<T, E>, f: (val: T) => Result<any, F> | PromiseLike<Result<any, F>>): ResultAsync<T, E | F>;
     /**
      * @TODO
      */
-    $andSafe<U = T, F = Error>(this: ResultAsync<T, E>, f: (val: T) => U | PromiseLike<U>, mapError?: (err: unknown) => F): ResultAsync<U, E | F>;
+    $andSafe<U>(this: ResultAsync<T, E>, f: (val: T) => U | PromiseLike<U>): ResultAsync<T | U, E | Error>;
+    $andSafe<U, F>(this: ResultAsync<T, E>, f: (val: T) => U | PromiseLike<U>, mapError: (err: unknown) => F): ResultAsync<T | U, E | F>;
     /**
      * @TODO
      */
@@ -166,6 +225,7 @@ declare class ResultAsync<T, E> {
 }
 type OkTuple<T> = [err: undefined, value: T];
 type ErrTuple<E> = [err: E, value: undefined];
+type Truthy<T> = Exclude<T, false | null | undefined | 0 | 0n | "">;
 /**
  * @TODO - Result.all / Result.any
  */
@@ -173,23 +233,29 @@ interface Retuple<T, E> {
     /**
      * @TODO
      */
-    $isOk(this: Result<T, E>): this is Ok<T>;
+    $toNativeTuple(this: Result<T, E>): OkTuple<T> | ErrTuple<E>;
     /**
      * @TODO
      */
-    $isOkAnd<U extends T = T>(this: Result<T, E>, f: ((val: T) => val is U) | ((val: T) => boolean)): this is Ok<U>;
+    $value(this: Result<T, E>): T | E;
     /**
      * @TODO
      */
-    $isErr(this: Result<T, E>): this is Err<E>;
+    $isOk(this: Result<T, E>): this is Ok<T>;
     /**
      * @TODO
      */
-    $isErrAnd<F extends E = E>(this: Result<T, E>, f: ((err: E) => err is F) | ((err: E) => boolean)): this is Err<F>;
+    $isOkAnd<U extends T>(this: Result<T, E>, predicate: (val: T) => val is U): this is Ok<U>;
+    $isOkAnd(this: Result<T, E>, predicate: (val: T) => unknown): this is Ok<T>;
     /**
      * @TODO
      */
-    $value(this: Result<T, E>): T | E;
+    $isErr(this: Result<T, E>): this is Err<E>;
+    /**
+     * @TODO
+     */
+    $isErrAnd<F extends E>(this: Result<T, E>, prediacte: (val: E) => val is F): this is Err<F>;
+    $isErrAnd(this: Result<T, E>, predicate: (val: E) => unknown): this is Err<E>;
     /**
      * @TODO
      */
@@ -205,11 +271,11 @@ interface Retuple<T, E> {
     /**
      * @TODO
      */
-    $unwrapOr<U = T>(this: Result<T, E>, def: U): T | U;
+    $unwrapOr<const U>(this: Result<T, E>, def: U): T | U;
     /**
      * @TODO
      */
-    $unwrapOrElse<U = T>(this: Result<T, E>, f: () => U): T | U;
+    $unwrapOrElse<U>(this: Result<T, E>, f: () => U): T | U;
     /**
      * @TODO
      */
@@ -221,43 +287,53 @@ interface Retuple<T, E> {
     /**
      * @TODO
      */
-    $mapOr<U>(this: Result<T, E>, def: U, f: (val: T) => U): Result<U, E>;
+    $mapOr<U, V = U>(this: Result<T, E>, def: U, f: (val: T) => V): Result<U | V, E>;
     /**
      * @TODO
      */
-    $mapOrElse<U>(this: Result<T, E>, def: (err: E) => U, f: (val: T) => U): Result<U, E>;
+    $mapOrElse<U, V = U>(this: Result<T, E>, def: (err: E) => U, f: (val: T) => V): Result<U | V, E>;
     /**
      * @TODO
      */
-    $or<U = T, F = E>(this: Result<T, E>, or: Result<U, F>): Result<T | U, E | F>;
+    $or<U, F>(this: Result<T, E>, or: Result<U, F>): Result<T | U, E | F>;
     /**
      * @TODO
      */
-    $orElse<U = never, F = never>(this: Result<T, E>, f: (err: E) => Result<U, F>): Result<T | U, E | F>;
+    $orElse<U, F>(this: Result<T, E>, f: (err: E) => Result<U, F>): Result<T | U, E | F>;
     /**
      * @TODO
      */
-    $orSafe<U = T>(this: Result<T, E>, f: (err: E) => U): Result<T | U, E | Error>;
-    $orSafe<U = T, F = E>(this: Result<T, E>, f: (err: E) => U, mapError: (err: unknown) => F): Result<T | U, E | F>;
-    $orSafe<U = T, F = Error>(this: Result<T, E>, f: (err: E) => U, mapError: (err: unknown) => F): Result<T | U, E | F>;
+    $orSafe<U>(this: Result<T, E>, f: (err: E) => U): Result<T | U, E | Error>;
+    $orSafe<U, F>(this: Result<T, E>, f: (err: E) => U, mapError: (err: unknown) => F): Result<T | U, E | F>;
     /**
      * @TODO
      */
-    $and<U = T, F = E>(this: Result<T, E>, and: Result<U, F>): Result<U, E | F>;
+    $and<U, F>(this: Result<T, E>, and: Result<U, F>): Result<U, E | F>;
     /**
      * @TODO
      */
-    $andThen<U = never, F = never>(this: Result<T, E>, f: (val: T) => Result<U, F>): Result<U, E | F>;
+    $andThen<U, F>(this: Result<T, E>, f: (val: T) => Result<U, F>): Result<U, E | F>;
     /**
      * @TODO
      */
-    $andThrough<F = never>(this: Result<T, E>, f: (val: T) => Result<any, F>): Result<T, E | F>;
+    $andThrough<F>(this: Result<T, E>, f: (val: T) => Result<any, F>): Result<T, E | F>;
     /**
      * @TODO
      */
-    $andSafe<U = T>(this: Result<T, E>, f: (val: T) => U): Result<T | U, E | Error>;
-    $andSafe<U = T, F = E>(this: Result<T, E>, f: (val: T) => U, mapError: (err: unknown) => F): Result<T | U, E | F>;
-    $andSafe<U, F = Error>(this: Result<T, E>, f: (val: T) => U, mapError: (err: unknown) => F): Result<T | U, E | F>;
+    $andSafe<U>(this: Result<T, E>, f: (val: T) => U): Result<T | U, E | Error>;
+    $andSafe<U, F>(this: Result<T, E>, f: (val: T) => U, mapError: (err: unknown) => F): Result<T | U, E | F>;
+    /**
+     * @TODO
+     */
+    $assertOr<U, F>(this: Result<T, E>, def: Result<U, F>): Result<Truthy<T>, E | F>;
+    $assertOr<U, F, A extends T>(this: Result<T, E>, def: Result<U, F>, predicate: (val: T) => val is A): Result<U | A, E | F>;
+    $assertOr<U, F>(this: Result<T, E>, def: Result<U, F>, condition: (val: T) => unknown): Result<T | U, E | F>;
+    /**
+     * @TODO
+     */
+    $assertOrElse<U, F>(this: Result<T, E>, def: () => Result<U, F>): Result<Truthy<T>, E | F>;
+    $assertOrElse<U, F, A extends T>(this: Result<T, E>, def: () => Result<U, F>, predicate: (val: T) => val is A): Result<U | A, E | F>;
+    $assertOrElse<U, F>(this: Result<T, E>, def: () => Result<U, F>, condition: (val: T) => unknown): Result<T | U, E | F>;
     /**
      * @TODO
      */
@@ -282,5 +358,135 @@ interface Retuple<T, E> {
      * @TODO
      */
     $promise(this: Result<T, E>): Promise<Result<T, E>>;
+    /**
+     * Mark standard array methods as deprecated, to assist with type hinting.
+     */
+    /**
+     * @deprecated
+     */
+    at(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    concat(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    copyWithin(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    entries(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    every(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    fill(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    filter(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    find(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    findIndex(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    flat(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    flatMap(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    forEach(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    includes(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    indexOf(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    join(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    keys(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    lastIndexOf(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    map(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    pop(...args: unknown[]): any;
+    /**
+     * @deprecated
+     */
+    push(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    reduce(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    reduceRight(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    reverse(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    shift(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    slice(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    some(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    sort(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    splice(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    toString(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    toLocaleString(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    unshift(...args: unknown[]): unknown;
+    /**
+     * @deprecated
+     */
+    values(...args: unknown[]): unknown;
 }
-type Truthy<T> = Exclude<T, false | null | undefined | 0 | 0n | "">;