@jamx/http 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2026 Joshua Amaju
+
+Permission is hereby granted, free
+of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice
+(including the next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# `@jamx/http`
+
+Composable HTTP helpers built around `fetch`, interceptors, and `Either`-style
+results.
+
+## Install
+
+```bash
+pnpm add @jamx/http
+```
+
+## Quick Start
+
+```ts
+import {
+  composeInterceptors,
+  createMemoryCacheStore,
+  defaultFetch,
+  withAuth,
+  withCache,
+  withHeaders,
+  withRetry,
+  withTimeout,
+} from "@jamx/http";
+
+const cache = createMemoryCacheStore();
+
+const handler = composeInterceptors(
+  withTimeout(250),
+  withHeaders({ accept: "application/json" }),
+  withAuth("demo-token"),
+  withJsonBody({ tenant: "team-a" }),
+  withCache({ store: cache }),
+  withRetry({ retries: 1 }),
+)(defaultFetch);
+```
+
+## Core APIs
+
+```ts
+import {
+  createFetchHandler,
+  decodeJson,
+  defaultContext,
+  defaultFetch,
+  expectStatus,
+} from "@jamx/http";
+
+const customFetch = createFetchHandler(defaultContext);
+
+const response = await defaultFetch("https://api.example.com/users/42");
+const user = await decodeJson(expectStatus(response, 200), decodeUser);
+```
+
+- `defaultContext` is a reusable `Context` backed by `globalThis.fetch`.
+- `defaultFetch` is `createFetchHandler(defaultContext)`.
+- `createFetchHandler(...)` is useful when you want to inject a mocked or custom
+  fetch implementation.
+- `composeInterceptors(...)` returns an executable handler with a composed result.
+
+## Decoder Helpers
+
+Decoder helpers accept either a plain `Response` or an `Either<..., Response>`.
+
+```ts
+import { decodeJson, json, text, validate } from "@jamx/http";
+import { z } from "zod";
+
+const rawResponse = await fetch("https://api.example.com/users/42");
+const userSchema = z.object({ id: z.number(), name: z.string() });
+
+const bodyText = await text(rawResponse);
+const bodyJson = await json(rawResponse);
+const user = await decodeJson(rawResponse, decodeUser);
+const userWithSchema = await validate(bodyJson, userSchema);
+```
+
+When you already have an `Either`, upstream errors are preserved in the helper
+result type.
+
+## Notes
+
+- `withBaseUrl` rebases request paths onto a configured base URL.
+- Put request-shaping interceptors like `withHeaders` and `withAuth` before
+  `withCache` so cache keys can include the final request headers.
+- `withRetry` only retries idempotent methods by default. Pass
+  `methods: ["POST"]` if you need to opt a write request into replay.
+- `validate(result, schema)` accepts an `Either` plus a Standard Schema
+  compatible validator such as Zod.
+- `withTimeout` aborts the underlying request and returns a `TimeoutError`
+  when the timeout elapses. `TimeoutError` extends `FetchError`.

package/build/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./internal/core.js";
+export * from "./internal/either.js";
+export * from "./internal/decoders.js";
+export * from "./internal/interceptors.js";
+export * from "./internal/statuses/statuses.js";
+export * from "./internal/statuses/validators.js";
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC"}

package/build/index.js

@@ -0,0 +1,6 @@
+export * from "./internal/core.js";
+export * from "./internal/either.js";
+export * from "./internal/decoders.js";
+export * from "./internal/interceptors.js";
+export * from "./internal/statuses/statuses.js";
+export * from "./internal/statuses/validators.js";

package/build/internal/core.d.ts

@@ -0,0 +1,115 @@
+import { type Either } from "./either.js";
+import type { AnyEither } from "./types.js";
+export interface Context {
+    fetch: typeof globalThis.fetch;
+}
+/**
+ * Default HTTP context backed by the platform `fetch` implementation.
+ *
+ * @example
+ * ```ts
+ * import { createFetchHandler, defaultContext } from "@jamx/http";
+ *
+ * const fetcher = createFetchHandler(defaultContext);
+ * ```
+ */
+export declare const defaultContext: Context;
+export interface Input {
+    input: RequestInfo | URL;
+    init?: RequestInit;
+}
+export type Result = Either<FetchError, Response>;
+export type Handler = (request: Request) => Promise<Result>;
+export type Next<R extends AnyEither> = (request?: Request) => Promise<R>;
+export interface InterceptorContext<T extends AnyEither> {
+    request: Request;
+    next: Next<T>;
+}
+export interface Chain extends InterceptorContext<Result> {
+}
+export type Interceptor<AddedResult extends AnyEither = never, DownstreamResult extends AnyEither = Result> = (ctx: InterceptorContext<DownstreamResult>) => Promise<DownstreamResult | AddedResult>;
+type AnyInterceptor = (args: InterceptorContext<any>) => Promise<AnyEither>;
+type InterceptorResult<TInterceptor extends AnyInterceptor> = Awaited<ReturnType<TInterceptor>>;
+/**
+ * Type helper for the final `Either` result produced by a composed interceptor chain.
+ *
+ * @example
+ * ```ts
+ * import type { ComposeInterceptorsResult, Result } from "@jamx/http";
+ *
+ * type FinalResult = ComposeInterceptorsResult<[], Result>;
+ * ```
+ */
+export type ComposeInterceptorsResult<TInterceptors extends readonly AnyInterceptor[], TResult extends AnyEither = Result> = TInterceptors extends readonly [
+    infer THead extends AnyInterceptor,
+    ...infer TTail extends readonly AnyInterceptor[]
+] ? InterceptorResult<THead> | ComposeInterceptorsResult<TTail, TResult> : TResult;
+export interface ExecutableHandler<TResult extends AnyEither> {
+    (input: RequestInfo | URL): Promise<TResult>;
+    (input: RequestInfo | URL, init?: RequestInit): Promise<TResult>;
+}
+/**
+ * Base error returned when a request fails before a response is produced.
+ */
+export declare class FetchError extends Error {
+    name: string;
+    constructor(message?: string, cause?: unknown);
+}
+export declare class TimeoutError extends FetchError {
+    name: string;
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, cause?: unknown);
+}
+/**
+ * Creates a `fetch`-backed handler that returns `Either<FetchError, Response>`.
+ *
+ * @example
+ * ```ts
+ * import { createFetchHandler, defaultContext } from "@jamx/http";
+ *
+ * const fetcher = createFetchHandler(defaultContext);
+ * const result = await fetcher(new Request("https://example.com"));
+ * ```
+ */
+export declare const createFetchHandler: (context: Context) => Handler;
+/**
+ * Ready-to-use HTTP handler backed by `globalThis.fetch`.
+ *
+ * @example
+ * ```ts
+ * import { defaultFetch } from "@jamx/http";
+ *
+ * const result = await defaultFetch("https://example.com/users");
+ * ```
+ */
+export declare const defaultFetch: Handler;
+/**
+ * Composes one or more interceptors into an executable HTTP handler.
+ *
+ * @example
+ * ```ts
+ * import { composeInterceptors, defaultFetch, withAuth, withTimeout } from "@jamx/http";
+ *
+ * const handler = composeInterceptors(
+ *   withTimeout(250),
+ *   withAuth("demo-token"),
+ * )(defaultFetch);
+ * ```
+ */
+export declare const composeInterceptors: <const TInterceptors extends readonly AnyInterceptor[]>(...interceptors: TInterceptors) => <THandler extends Handler>(handler: THandler) => ExecutableHandler<ComposeInterceptorsResult<TInterceptors>>;
+/**
+ * Defines an interceptor while preserving its inferred result type.
+ *
+ * @example
+ * ```ts
+ * import { defineInterceptor, ok } from "@jamx/http";
+ *
+ * const interceptor = defineInterceptor(async ({ next }) => {
+ *   const result = await next();
+ *   return result.ok ? ok(result.value) : result;
+ * });
+ * ```
+ */
+export declare const defineInterceptor: <TInterceptor extends (args: Chain) => Promise<AnyEither>>(interceptor: TInterceptor) => TInterceptor;
+export {};
+//# sourceMappingURL=core.d.ts.map

package/build/internal/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/internal/core.ts"],"names":[],"mappings":"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"}

package/build/internal/core.js

@@ -0,0 +1,119 @@
+import { err, ok } from "./either.js";
+/**
+ * Default HTTP context backed by the platform `fetch` implementation.
+ *
+ * @example
+ * ```ts
+ * import { createFetchHandler, defaultContext } from "@jamx/http";
+ *
+ * const fetcher = createFetchHandler(defaultContext);
+ * ```
+ */
+export const defaultContext = {
+    fetch: globalThis.fetch,
+};
+/**
+ * Base error returned when a request fails before a response is produced.
+ */
+export class FetchError extends Error {
+    constructor(message = "Fetch request failed.", cause) {
+        super(message, { cause });
+        this.name = "FetchError";
+    }
+}
+export class TimeoutError extends FetchError {
+    constructor(timeoutMs, cause) {
+        super(`Fetch request timed out after ${timeoutMs}ms.`, cause);
+        this.name = "TimeoutError";
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * Creates a `fetch`-backed handler that returns `Either<FetchError, Response>`.
+ *
+ * @example
+ * ```ts
+ * import { createFetchHandler, defaultContext } from "@jamx/http";
+ *
+ * const fetcher = createFetchHandler(defaultContext);
+ * const result = await fetcher(new Request("https://example.com"));
+ * ```
+ */
+export const createFetchHandler = (context) => {
+    return async (request) => {
+        try {
+            const response = await context.fetch(request);
+            return ok(response);
+        }
+        catch (error) {
+            return err(normalizeError(error));
+        }
+    };
+};
+/**
+ * Ready-to-use HTTP handler backed by `globalThis.fetch`.
+ *
+ * @example
+ * ```ts
+ * import { defaultFetch } from "@jamx/http";
+ *
+ * const result = await defaultFetch("https://example.com/users");
+ * ```
+ */
+export const defaultFetch = createFetchHandler(defaultContext);
+/**
+ * Composes one or more interceptors into an executable HTTP handler.
+ *
+ * @example
+ * ```ts
+ * import { composeInterceptors, defaultFetch, withAuth, withTimeout } from "@jamx/http";
+ *
+ * const handler = composeInterceptors(
+ *   withTimeout(250),
+ *   withAuth("demo-token"),
+ * )(defaultFetch);
+ * ```
+ */
+export const composeInterceptors = (...interceptors) => (handler) => {
+    const execute = async (input, init) => {
+        const request = new Request(input, init);
+        const dispatch = async (index, currentRequest) => {
+            const interceptor = interceptors[index];
+            if (!interceptor) {
+                return handler(currentRequest);
+            }
+            return interceptor({
+                request: currentRequest,
+                next: (nextRequest = currentRequest) => dispatch(index + 1, nextRequest),
+            });
+        };
+        return dispatch(0, request);
+    };
+    return execute;
+};
+/**
+ * Defines an interceptor while preserving its inferred result type.
+ *
+ * @example
+ * ```ts
+ * import { defineInterceptor, ok } from "@jamx/http";
+ *
+ * const interceptor = defineInterceptor(async ({ next }) => {
+ *   const result = await next();
+ *   return result.ok ? ok(result.value) : result;
+ * });
+ * ```
+ */
+export const defineInterceptor = (interceptor) => interceptor;
+function normalizeError(error) {
+    if (error instanceof FetchError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new FetchError(error.message, error);
+    }
+    if (typeof error === "string") {
+        return new FetchError(error, error);
+    }
+    return new FetchError("Fetch request failed.", error);
+}

package/build/internal/decoders.d.ts

@@ -0,0 +1,107 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { type Either } from "./either.js";
+export interface DecodeError {
+    message: string;
+    cause?: unknown;
+}
+export type Decoder<TValue, TError extends DecodeError = DecodeError> = (input: unknown) => Either<TError, TValue>;
+/**
+ * Defines a decoder while preserving inferred input, output, and error types.
+ *
+ * @example
+ * ```ts
+ * import { defineDecoder, err, ok } from "@jamx/http";
+ *
+ * const decodeUser = defineDecoder((input) => {
+ *   return typeof input === "object" && input !== null
+ *     ? ok(input)
+ *     : err({ message: "invalid-user", cause: input });
+ * });
+ * ```
+ */
+export declare const defineDecoder: <TValue, TDecodeError extends DecodeError = DecodeError>(decoder: Decoder<TValue, TDecodeError>) => Decoder<TValue, TDecodeError>;
+/**
+ * Error returned when schema validation fails after decoding succeeds.
+ */
+export declare class SchemaError extends Error {
+    name: string;
+    readonly vendor: string;
+    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+    constructor(vendor: string, issues: ReadonlyArray<StandardSchemaV1.Issue>, cause?: unknown);
+}
+/**
+ * Validates a decoded `Either` value with a Standard Schema compatible validator.
+ *
+ * @example
+ * ```ts
+ * import { json, validate } from "@jamx/http";
+ * import { z } from "zod";
+ *
+ * const schema = z.object({ id: z.number(), name: z.string() });
+ * const parsed = await json(new Response('{"id":1,"name":"Ada"}'));
+ * const result = await validate(parsed, schema);
+ * ```
+ */
+export declare const validate: <TError, TDecodedValue, TSchema extends StandardSchemaV1<TDecodedValue, any>>(result: Either<TError, TDecodedValue>, schema: TSchema) => Promise<Either<TError | SchemaError, StandardSchemaV1.InferOutput<TSchema>>>;
+/**
+ * Error returned when a body helper cannot parse a response payload.
+ */
+export declare class ParseError extends Error {
+    name: string;
+    readonly response: Response;
+    readonly operation: "json" | "text" | "empty";
+    constructor(response: Response, operation: "json" | "text" | "empty", cause?: unknown);
+}
+/**
+ * Parses a response body as JSON.
+ *
+ * @example
+ * ```ts
+ * import { json } from "@jamx/http";
+ *
+ * const result = await json(new Response('{"ok":true}'));
+ * ```
+ */
+export declare function json(response: Response): Promise<Either<ParseError, unknown>>;
+export declare function json<TError>(result: Either<TError, Response>): Promise<Either<TError | ParseError, unknown>>;
+/**
+ * Parses a response body as text.
+ *
+ * @example
+ * ```ts
+ * import { text } from "@jamx/http";
+ *
+ * const result = await text(new Response("hello"));
+ * ```
+ */
+export declare function text(response: Response): Promise<Either<ParseError, string>>;
+export declare function text<TError>(result: Either<TError, Response>): Promise<Either<TError | ParseError, string>>;
+/**
+ * Validates that a response body is empty.
+ *
+ * @example
+ * ```ts
+ * import { empty } from "@jamx/http";
+ *
+ * const result = await empty(new Response(null, { status: 204 }));
+ * ```
+ */
+export declare function empty(response: Response): Promise<Either<ParseError, void>>;
+export declare function empty<TError>(result: Either<TError, Response>): Promise<Either<TError | ParseError, void>>;
+/**
+ * Parses a response body as JSON and then decodes the parsed payload.
+ *
+ * @example
+ * ```ts
+ * import { decodeJson, err, ok } from "@jamx/http";
+ *
+ * const result = await decodeJson(new Response('{"id":1}'), (input) =>
+ *   typeof input === "object" && input !== null
+ *     ? ok(input)
+ *     : err({ message: "invalid-json", cause: input }),
+ * );
+ * ```
+ */
+export declare function decodeJson<TValue, TDecodeError extends DecodeError = DecodeError>(response: Response, decoder: Decoder<TValue, TDecodeError>): Promise<Either<ParseError | TDecodeError, TValue>>;
+export declare function decodeJson<TError, TValue, TDecodeError extends DecodeError = DecodeError>(result: Either<TError, Response>, decoder: Decoder<TValue, TDecodeError>): Promise<Either<TError | ParseError | TDecodeError, TValue>>;
+//# sourceMappingURL=decoders.d.ts.map

package/build/internal/decoders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoders.d.ts","sourceRoot":"","sources":["../../src/internal/decoders.ts"],"names":[],"mappings":"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"}

package/build/internal/decoders.js

@@ -0,0 +1,110 @@
+import { chain, err, isErr, ok } from "./either.js";
+/**
+ * Defines a decoder while preserving inferred input, output, and error types.
+ *
+ * @example
+ * ```ts
+ * import { defineDecoder, err, ok } from "@jamx/http";
+ *
+ * const decodeUser = defineDecoder((input) => {
+ *   return typeof input === "object" && input !== null
+ *     ? ok(input)
+ *     : err({ message: "invalid-user", cause: input });
+ * });
+ * ```
+ */
+export const defineDecoder = (decoder) => decoder;
+/**
+ * Error returned when schema validation fails after decoding succeeds.
+ */
+export class SchemaError extends Error {
+    constructor(vendor, issues, cause) {
+        super(formatSchemaIssues(issues), { cause });
+        this.name = "SchemaError";
+        this.vendor = vendor;
+        this.issues = issues;
+    }
+}
+/**
+ * Validates a decoded `Either` value with a Standard Schema compatible validator.
+ *
+ * @example
+ * ```ts
+ * import { json, validate } from "@jamx/http";
+ * import { z } from "zod";
+ *
+ * const schema = z.object({ id: z.number(), name: z.string() });
+ * const parsed = await json(new Response('{"id":1,"name":"Ada"}'));
+ * const result = await validate(parsed, schema);
+ * ```
+ */
+export const validate = (result, schema) => (async () => {
+    if (isErr(result)) {
+        return result;
+    }
+    const validated = await schema["~standard"].validate(result.value);
+    if (validated.issues) {
+        return err(new SchemaError(schema["~standard"].vendor, validated.issues, validated));
+    }
+    return ok(validated.value);
+})();
+/**
+ * Error returned when a body helper cannot parse a response payload.
+ */
+export class ParseError extends Error {
+    constructor(response, operation, cause) {
+        super(`Failed to parse response body as ${operation}.`, { cause });
+        this.name = "ParseError";
+        this.response = response;
+        this.operation = operation;
+    }
+}
+export async function json(input) {
+    const result = toResponseEither(input);
+    if (isErr(result))
+        return result;
+    try {
+        return ok(await result.value.json());
+    }
+    catch (cause) {
+        return err(new ParseError(result.value, "json", cause));
+    }
+}
+export async function text(input) {
+    const result = toResponseEither(input);
+    if (isErr(result))
+        return result;
+    try {
+        return ok(await result.value.text());
+    }
+    catch (cause) {
+        return err(new ParseError(result.value, "text", cause));
+    }
+}
+export async function empty(input) {
+    const result = toResponseEither(input);
+    if (isErr(result))
+        return result;
+    try {
+        const value = await result.value.text();
+        return value.length === 0
+            ? ok(undefined)
+            : err(new ParseError(result.value, "empty"));
+    }
+    catch (cause) {
+        return err(new ParseError(result.value, "empty", cause));
+    }
+}
+export async function decodeJson(input, decoder) {
+    const parsed = await json(toResponseEither(input));
+    return chain(parsed, decoder);
+}
+function toResponseEither(input) {
+    return input instanceof Response ? ok(input) : input;
+}
+function formatSchemaIssues(issues) {
+    if (issues.length === 0) {
+        return "Schema validation failed.";
+    }
+    return issues.map((issue) => issue.message).join("; ");
+}

package/build/internal/either.d.ts

@@ -0,0 +1,25 @@
+import { AnyEither } from "./types.js";
+export type Right<T> = {
+    ok: true;
+    value: T;
+};
+export type Left<T> = {
+    ok: false;
+    error: T;
+};
+export type Either<E, A> = Right<A> | Left<E>;
+export declare const ok: <T>(value: T) => Right<T>;
+export declare const err: <T>(error: T) => Left<T>;
+export declare function isOk<T extends AnyEither>(_: T): _ is Extract<T, Right<any>>;
+export declare function isErr<T extends AnyEither>(_: T): _ is Extract<T, Left<any>>;
+type ErrorOf<TResult extends AnyEither> = TResult extends Left<infer TError> ? TError : never;
+type ValueOf<TResult extends AnyEither> = TResult extends Right<infer TValue> ? TValue : never;
+export declare function mapOk<TResult extends AnyEither, TValue>(result: TResult, mapper: (value: ValueOf<TResult>) => TValue): Either<ErrorOf<TResult>, TValue>;
+export declare function mapErr<TResult extends AnyEither, TError>(result: TResult, mapper: (error: ErrorOf<TResult>) => TError): Either<TError, ValueOf<TResult>>;
+export declare function chain<TResult extends AnyEither, TNext extends AnyEither>(result: TResult, mapper: (value: ValueOf<TResult>) => TNext): Either<ErrorOf<TResult> | ErrorOf<TNext>, ValueOf<TNext>>;
+export declare function match<TResult extends AnyEither, TOutput>(result: TResult, branches: {
+    ok: (value: ValueOf<TResult>) => TOutput;
+    err: (error: ErrorOf<TResult>) => TOutput;
+}): TOutput;
+export {};
+//# sourceMappingURL=either.d.ts.map

package/build/internal/either.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"either.d.ts","sourceRoot":"","sources":["../../src/internal/either.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAE9C,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAE9C,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;AAE9C,eAAO,MAAM,EAAE,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,KAAK,CAAC,CAAC,CAA0B,CAAC;AAEnE,eAAO,MAAM,GAAG,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,IAAI,CAAC,CAAC,CAA2B,CAAC;AAEpE,wBAAgB,IAAI,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAE3E;AAED,wBAAgB,KAAK,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAE3E;AAED,KAAK,OAAO,CAAC,OAAO,SAAS,SAAS,IACpC,OAAO,SAAS,IAAI,CAAC,MAAM,MAAM,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC;AAEtD,KAAK,OAAO,CAAC,OAAO,SAAS,SAAS,IACpC,OAAO,SAAS,KAAK,CAAC,MAAM,MAAM,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC;AAEvD,wBAAgB,KAAK,CAAC,OAAO,SAAS,SAAS,EAAE,MAAM,EACrD,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,MAAM,GAC1C,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAGlC;AAED,wBAAgB,MAAM,CAAC,OAAO,SAAS,SAAS,EAAE,MAAM,EACtD,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,MAAM,GAC1C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAGlC;AAED,wBAAgB,KAAK,CAAC,OAAO,SAAS,SAAS,EAAE,KAAK,SAAS,SAAS,EACtE,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,KAAK,GACzC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAG3D;AAED,wBAAgB,KAAK,CAAC,OAAO,SAAS,SAAS,EAAE,OAAO,EACtD,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE;IACR,EAAE,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC;IACzC,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC;CAC3C,GACA,OAAO,CAGT"}

package/build/internal/either.js

@@ -0,0 +1,28 @@
+export const ok = (value) => ({ ok: true, value });
+export const err = (error) => ({ ok: false, error });
+export function isOk(_) {
+    return _.ok;
+}
+export function isErr(_) {
+    return !_.ok;
+}
+export function mapOk(result, mapper) {
+    if (!result.ok)
+        return result;
+    return ok(mapper(result.value));
+}
+export function mapErr(result, mapper) {
+    if (!result.ok)
+        return err(mapper(result.error));
+    return result;
+}
+export function chain(result, mapper) {
+    if (!result.ok)
+        return result;
+    return mapper(result.value);
+}
+export function match(result, branches) {
+    if (!result.ok)
+        return branches.err(result.error);
+    return branches.ok(result.value);
+}