@semyonf/kamchazky 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,340 @@
+/** A successful result containing a value of type `T`. */
+type OkResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+    map<U>(fn: (value: T) => U): OkResult<U>;
+    flatMap<U, F extends Error = never>(fn: (value: T) => Result<U, F>): Result<U, F>;
+    mapError<F extends Error>(fn: (error: never) => F): OkResult<T>;
+    inspect(fn: (value: T) => void): OkResult<T>;
+    inspectError(fn: (error: never) => void): OkResult<T>;
+    match<R>(handlers: {
+        ok: (value: T) => R;
+        err: (error: never) => R;
+    }): R;
+    unwrap(): T;
+    unwrapOr(fallback: T): T;
+    unwrapOrElse(fn: () => T): T;
+    expect(message: string): T;
+};
+/** A failed result containing an error of type `E`. */
+type ErrResult<E extends Error = Error> = {
+    readonly ok: false;
+    readonly error: E;
+    map<U>(fn: (value: never) => U): ErrResult<E>;
+    flatMap<U, F extends Error = never>(fn: (value: never) => Result<U, F>): ErrResult<E>;
+    mapError<F extends Error>(fn: (error: E) => F): ErrResult<F>;
+    inspect(fn: (value: never) => void): ErrResult<E>;
+    inspectError(fn: (error: E) => void): ErrResult<E>;
+    match<R>(handlers: {
+        ok: (value: never) => R;
+        err: (error: E) => R;
+    }): R;
+    unwrap(): never;
+    unwrapOr<T>(fallback: T): T;
+    unwrapOrElse<T>(fn: () => T): T;
+    expect(message: string): never;
+};
+type AnyResult = Result<unknown, Error>;
+type ValueOf<R> = R extends OkResult<infer T> ? T : never;
+type ErrorOf<R> = R extends ErrResult<infer E> ? E : never;
+type TupleValues<R extends readonly AnyResult[]> = {
+    [K in keyof R]: ValueOf<R[K]>;
+};
+type TupleErrors<R extends readonly AnyResult[]> = ErrorOf<R[number]>;
+/** Create a successful `Result` containing `value`. */
+declare function ok<T>(value: T): OkResult<T>;
+/** Create a failed `Result` containing `error`. */
+declare function err<E extends Error>(error: E): ErrResult<E>;
+/** Narrow a `Result` to `OkResult`. */
+declare function isOk<T, E extends Error>(result: Result<T, E>): result is OkResult<T>;
+/** Narrow a `Result` to `ErrResult`. */
+declare function isErr<T, E extends Error>(result: Result<T, E>): result is ErrResult<E>;
+/** Transform the value inside an `Ok`, leaving `Err` unchanged. */
+declare function map<T, U>(result: OkResult<T>, fn: (value: T) => U): OkResult<U>;
+declare function map<T, U, E extends Error>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+/** Transform the error inside an `Err`, leaving `Ok` unchanged. */
+declare function mapError<T>(result: OkResult<T>, fn: (error: never) => Error): OkResult<T>;
+declare function mapError<T, E extends Error, F extends Error>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
+/** Run a side-effect on the `Ok` value without transforming the result. */
+declare function inspect<T>(result: OkResult<T>, fn: (value: T) => void): OkResult<T>;
+declare function inspect<T, E extends Error>(result: Result<T, E>, fn: (value: T) => void): Result<T, E>;
+/** Run a side-effect on the `Err` error without transforming the result. */
+declare function inspectError<E extends Error>(result: ErrResult<E>, fn: (error: E) => void): ErrResult<E>;
+declare function inspectError<T, E extends Error>(result: Result<T, E>, fn: (error: E) => void): Result<T, E>;
+/** Chain a `Result`-returning function on the `Ok` value. */
+declare function flatMap<T, U, E extends Error, F extends Error = never>(result: Result<T, E>, fn: (value: T) => Result<U, F>): Result<U, E | F>;
+/**
+ * Recover from an error by applying `fn` to produce a new `Result`.
+ * Alias: `flatMapErr`.
+ */
+declare function orElse<T, E extends Error, F extends Error>(result: Result<T, E>, fn: (error: E) => Result<T, F>): Result<T, F>;
+/**
+ * Recover from an error by applying `fn` to produce a new `Result`.
+ * Alias for `orElse`.
+ */
+declare function flatMapErr<T, E extends Error, F extends Error>(result: Result<T, E>, fn: (error: E) => Result<T, F>): Result<T, F>;
+/** Flatten a nested `Result<Result<T, E>, F>` into `Result<T, E | F>`. */
+declare function flatten<T, E extends Error, F extends Error>(result: Result<Result<T, E>, F>): Result<T, E | F>;
+/** Exhaustively handle both `Ok` and `Err` branches, returning `R`. */
+declare function match<T, E extends Error, R>(result: Result<T, E>, handlers: {
+    ok: (value: T) => R;
+    err: (error: E) => R;
+}): R;
+/** Compile-time exhaustiveness guard — only accepts `never`. */
+declare function exhaustive(value: never): never;
+/** Return the `Ok` value or throw the contained error. */
+declare function unwrap<T, E extends Error>(result: Result<T, E>): T;
+/**
+ * Return the `Ok` value or `fallback`.
+ *
+ * The fallback must be the same type `T` as the success value.  This is
+ * intentional — use `match` when you need a different return type.
+ */
+declare function unwrapOr<T, E extends Error>(result: Result<T, E>, fallback: T): T;
+/** Return the `Ok` value, or compute a fallback from `fn`. */
+declare function unwrapOrElse<T, E extends Error>(result: Result<T, E>, fn: () => T): T;
+/** Return the `Ok` value or throw with a custom `message`. */
+declare function expect<T, E extends Error>(result: Result<T, E>, message: string): T;
+/** Convert a nullable value to a `Result`. */
+declare function fromNullable<T, E extends Error>(value: T | null | undefined, errorFactory: () => E): Result<NonNullable<T>, E>;
+/** Convert a predicate check to a `Result`.  Supports type-guard predicates. */
+declare function fromPredicate<T, S extends T, E extends Error>(value: T, predicate: (value: T) => value is S, errorFactory: () => E): Result<S, E>;
+declare function fromPredicate<T, E extends Error>(value: T, predicate: (value: T) => boolean, errorFactory: () => E): Result<T, E>;
+/** Convert an unknown thrown value to an `Error` instance. */
+declare function normalizeError(error: unknown): Error;
+/** Wrap a synchronous function that may throw into a `Result`. */
+declare function tryCatch<T>(fn: () => T): Result<T, Error>;
+declare function tryCatch<T, E extends Error>(fn: () => T, onError: (error: unknown) => E): Result<T, E>;
+/** Wrap an asynchronous function that may reject into a `Result`. */
+declare function tryCatchAsync<T>(fn: () => Promise<T>): Promise<Result<T, Error>>;
+declare function tryCatchAsync<T, E extends Error>(fn: () => Promise<T>, onError: (error: unknown) => E): Promise<Result<T, E>>;
+/** Wrap a `Promise` that may reject into a `Result`. */
+declare function fromPromise<T>(promise: Promise<T>): Promise<Result<T, Error>>;
+declare function fromPromise<T, E extends Error>(promise: Promise<T>, onError: (error: unknown) => E): Promise<Result<T, E>>;
+/**
+ * Combine multiple `Result`s into a single `Result` containing a tuple of
+ * values.  Returns the first `Err` encountered (fail-fast).
+ *
+ * Pass results as individual arguments — spreading an array loses tuple
+ * inference and degrades value types to `unknown[]`.
+ */
+declare function all<const R extends readonly AnyResult[]>(...results: R): Result<TupleValues<R>, TupleErrors<R>>;
+/**
+ * Like `all`, but accepts promises of `Result`s.  All promises are resolved
+ * concurrently via `Promise.allSettled` before checking for errors.
+ *
+ * Promises are expected to resolve to `Result`s — not reject.  If a promise
+ * does reject, the rejection is caught and wrapped as an `Err`.
+ *
+ * @breaking v0.2 — Uses `Promise.allSettled` instead of `Promise.all`. All
+ * promises are now always awaited to completion; the first error found during
+ * iteration is returned.
+ */
+declare function allAsync<const R extends readonly Promise<AnyResult>[]>(...promises: R): Promise<Result<{
+    [K in keyof R]: ValueOf<Awaited<R[K]>>;
+}, ErrorOf<Awaited<R[number]>> | Error>>;
+/**
+ * Like `collect`, but for promises of `Result`s.  Resolves all promises
+ * via `Promise.allSettled`, then collects all errors.  Returns an
+ * `AggregateError` containing every error found.
+ */
+declare function collectAsync<const R extends readonly Promise<AnyResult>[]>(...promises: R): Promise<Result<{
+    [K in keyof R]: ValueOf<Awaited<R[K]>>;
+}, AggregateError>>;
+/**
+ * Combine multiple `Result`s, collecting **all** errors instead of
+ * short-circuiting on the first one.  Returns an `AggregateError` whose
+ * `.errors` array contains every individual error.
+ */
+declare function collect<const R extends readonly AnyResult[]>(...results: R): Result<TupleValues<R>, AggregateError>;
+/** A `Maybe` that contains a value of type `T`. */
+type Some<T> = {
+    readonly some: true;
+    readonly value: T;
+    map<U>(fn: (value: T) => U): Some<U>;
+    flatMap<U>(fn: (value: T) => Maybe<U>): Maybe<U>;
+    filter(predicate: (value: T) => boolean): Maybe<T>;
+    inspect(fn: (value: T) => void): Some<T>;
+    match<R>(handlers: {
+        some: (value: T) => R;
+        none: () => R;
+    }): R;
+    unwrap(): T;
+    expect(message: string): T;
+    unwrapOr(fallback: T): T;
+    unwrapOrElse(fn: () => T): T;
+};
+/** A `Maybe` that contains no value. */
+type None = {
+    readonly some: false;
+    map<U>(fn: (value: never) => U): None;
+    flatMap<U>(fn: (value: never) => Maybe<U>): None;
+    filter(predicate: (value: never) => boolean): None;
+    inspect(fn: (value: never) => void): None;
+    match<R>(handlers: {
+        some: (value: never) => R;
+        none: () => R;
+    }): R;
+    unwrap(): never;
+    expect(message: string): never;
+    unwrapOr<T>(fallback: T): T;
+    unwrapOrElse<T>(fn: () => T): T;
+};
+type AnyMaybe = Maybe<unknown>;
+type MaybeValueOf<M> = M extends Some<infer T> ? T : never;
+type TupleMaybeValues<M extends readonly AnyMaybe[]> = {
+    [K in keyof M]: MaybeValueOf<M[K]>;
+};
+/** Create a `Maybe` containing `value`. */
+declare function some<T>(value: T): Some<T>;
+/** Create an empty `Maybe`. */
+declare function none(): None;
+/** Narrow a `Maybe` to `Some`. */
+declare function isSome<T>(maybe: Maybe<T>): maybe is Some<T>;
+/** Narrow a `Maybe` to `None`. */
+declare function isNone<T>(maybe: Maybe<T>): maybe is None;
+/** Transform the value inside a `Some`, leaving `None` unchanged. */
+declare function maybeMap<T, U>(maybe: Some<T>, fn: (value: T) => U): Some<U>;
+declare function maybeMap<T, U>(maybe: Maybe<T>, fn: (value: T) => U): Maybe<U>;
+/** Chain a `Maybe`-returning function on the `Some` value. */
+declare function maybeFlatMap<T, U>(maybe: Maybe<T>, fn: (value: T) => Maybe<U>): Maybe<U>;
+/** Flatten a nested `Maybe<Maybe<T>>` into `Maybe<T>`. */
+declare function maybeFlatten<T>(maybe: Maybe<Maybe<T>>): Maybe<T>;
+/** Keep the `Some` value only if `predicate` returns true. */
+declare function maybeFilter<T, S extends T>(maybe: Maybe<T>, predicate: (value: T) => value is S): Maybe<S>;
+declare function maybeFilter<T>(maybe: Maybe<T>, predicate: (value: T) => boolean): Maybe<T>;
+/** Run a side-effect on the `Some` value without transforming the maybe. */
+declare function maybeInspect<T>(maybe: Some<T>, fn: (value: T) => void): Some<T>;
+declare function maybeInspect<T>(maybe: Maybe<T>, fn: (value: T) => void): Maybe<T>;
+/** Exhaustively handle both `Some` and `None` branches, returning `R`. */
+declare function maybeMatch<T, R>(maybe: Maybe<T>, handlers: {
+    some: (value: T) => R;
+    none: () => R;
+}): R;
+/** Return the `Some` value or throw. */
+declare function maybeUnwrap<T>(maybe: Maybe<T>): T;
+/**
+ * Return the `Some` value or `fallback`.
+ *
+ * The fallback must be the same type `T` as the contained value.  This is
+ * intentional — use `match` when you need a different return type.
+ */
+declare function maybeUnwrapOr<T>(maybe: Maybe<T>, fallback: T): T;
+/** Return the `Some` value, or compute a fallback from `fn`. */
+declare function maybeUnwrapOrElse<T>(maybe: Maybe<T>, fn: () => T): T;
+/** Return the `Some` value or throw with a custom `message`. */
+declare function maybeExpect<T>(maybe: Maybe<T>, message: string): T;
+/** Convert a nullable value to a `Maybe`. */
+declare function maybeFromNullable<T>(value: T | null | undefined): Maybe<NonNullable<T>>;
+/** Convert a predicate check to a `Maybe`.  Supports type-guard predicates. */
+declare function maybeFromPredicate<T, S extends T>(value: T, predicate: (value: T) => value is S): Maybe<S>;
+declare function maybeFromPredicate<T>(value: T, predicate: (value: T) => boolean): Maybe<T>;
+/**
+ * Combine multiple `Maybe`s into a single `Maybe` containing a tuple of
+ * values.  Returns `None` if any input is `None` (fail-fast).
+ *
+ * Pass maybes as individual arguments — spreading an array loses tuple
+ * inference and degrades value types to `unknown[]`.
+ */
+declare function maybeAll<const M extends readonly AnyMaybe[]>(...maybes: M): Maybe<TupleMaybeValues<M>>;
+/** Return the first `Some` found, or `None` if all are `None`. */
+declare function maybeFirstSome<T>(...maybes: Maybe<T>[]): Maybe<T>;
+/** Like `all`, but for promises of `Maybe`s.  Resolves all promises
+ *  concurrently via `Promise.allSettled`. */
+declare function maybeAllAsync<const M extends readonly Promise<AnyMaybe>[]>(...promises: M): Promise<Maybe<{
+    [K in keyof M]: MaybeValueOf<Awaited<M[K]>>;
+}>>;
+/** Convert a `Maybe` to a `Result`, calling `errorFactory` only when `None`.
+ *
+ * @breaking v0.2 — The second argument changed from `error: E` to
+ * `errorFactory: () => E`. The factory is only called when the Maybe is
+ * None, avoiding unnecessary error construction for Some.
+ */
+declare function maybeToResult<T, E extends Error>(maybe: Maybe<T>, errorFactory: () => E): Result<T, E>;
+/** Convert a `Result` to a `Maybe`, discarding the error. */
+declare function maybeFromResult<T, E extends Error>(result: Result<T, E>): Maybe<T>;
+/** Convert a `Result` to a `Maybe`, discarding the error. */
+declare function resultToMaybe<T, E extends Error>(result: Result<T, E>): Maybe<T>;
+/** Convert a `Maybe` to a `Result`, calling `errorFactory` only when `None`.
+ * Alias for `maybeToResult`.
+ *
+ * @breaking v0.2 — The second argument changed from `error: E` to
+ * `errorFactory: () => E`.
+ */
+declare function resultFromMaybe<T, E extends Error>(maybe: Maybe<T>, errorFactory: () => E): Result<T, E>;
+/** Convert a `Result<Maybe<T>, E>` to `Maybe<Result<T, E>>`. */
+declare function resultTranspose<T, E extends Error>(result: Result<Maybe<T>, E>): Maybe<Result<T, E>>;
+/** Convert a `Maybe<Result<T, E>>` to `Result<Maybe<T>, E>`. */
+declare function maybeTranspose<T, E extends Error>(maybe: Maybe<Result<T, E>>): Result<Maybe<T>, E>;
+/**
+ * A value that is either present (`Some<T>`) or absent (`None`).
+ * Use `Maybe.some` / `Maybe.none` to construct, and the companion `Maybe.*`
+ * functions or instance methods to transform.
+ */
+type Maybe<T> = Some<T> | None;
+declare const Maybe: {
+    readonly some: typeof some;
+    readonly none: typeof none;
+    readonly isSome: typeof isSome;
+    readonly isNone: typeof isNone;
+    readonly map: typeof maybeMap;
+    readonly flatMap: typeof maybeFlatMap;
+    readonly flatten: typeof maybeFlatten;
+    readonly filter: typeof maybeFilter;
+    readonly inspect: typeof maybeInspect;
+    readonly match: typeof maybeMatch;
+    readonly unwrap: typeof maybeUnwrap;
+    readonly unwrapOr: typeof maybeUnwrapOr;
+    readonly unwrapOrElse: typeof maybeUnwrapOrElse;
+    readonly expect: typeof maybeExpect;
+    readonly fromNullable: typeof maybeFromNullable;
+    readonly fromPredicate: typeof maybeFromPredicate;
+    readonly all: typeof maybeAll;
+    readonly allAsync: typeof maybeAllAsync;
+    readonly collect: typeof maybeAll;
+    readonly firstSome: typeof maybeFirstSome;
+    readonly toResult: typeof maybeToResult;
+    readonly fromResult: typeof maybeFromResult;
+    readonly transpose: typeof maybeTranspose;
+};
+/**
+ * A value that is either a success (`OkResult<T>`) or a failure
+ * (`ErrResult<E>`).  Use `Result.ok` / `Result.err` to construct, and the
+ * companion `Result.*` functions or instance methods to transform.
+ */
+type Result<T, E extends Error = Error> = OkResult<T> | ErrResult<E>;
+declare const Result: {
+    readonly ok: typeof ok;
+    readonly err: typeof err;
+    readonly isOk: typeof isOk;
+    readonly isErr: typeof isErr;
+    readonly map: typeof map;
+    readonly mapError: typeof mapError;
+    readonly inspect: typeof inspect;
+    readonly inspectError: typeof inspectError;
+    readonly flatMap: typeof flatMap;
+    readonly flatMapErr: typeof flatMapErr;
+    readonly orElse: typeof orElse;
+    readonly flatten: typeof flatten;
+    readonly match: typeof match;
+    readonly exhaustive: typeof exhaustive;
+    readonly unwrap: typeof unwrap;
+    readonly unwrapOr: typeof unwrapOr;
+    readonly unwrapOrElse: typeof unwrapOrElse;
+    readonly expect: typeof expect;
+    readonly fromNullable: typeof fromNullable;
+    readonly fromPredicate: typeof fromPredicate;
+    readonly normalizeError: typeof normalizeError;
+    readonly tryCatch: typeof tryCatch;
+    readonly tryCatchAsync: typeof tryCatchAsync;
+    readonly fromPromise: typeof fromPromise;
+    readonly all: typeof all;
+    readonly allAsync: typeof allAsync;
+    readonly collect: typeof collect;
+    readonly collectAsync: typeof collectAsync;
+    readonly toMaybe: typeof resultToMaybe;
+    readonly fromMaybe: typeof resultFromMaybe;
+    readonly transpose: typeof resultTranspose;
+};
+
+export { type ErrResult, Maybe, type None, type OkResult, Result, type Some, err, isErr, isNone, isOk, isSome, none, normalizeError, ok, some };