micro509/result

Canonical shared result surface. Owns the stable micro509/result entrypoint.

ErrorResult

Failed result with a flattened code/message/details surface for ergonomic matching.

interface ErrorResult<TCode extends string, TDetails, TError extends Micro509Error<TCode, TDetails>> {
	readonly ok: false;
	readonly error: TError;
	readonly code: TCode;
	readonly message: string;
	readonly details?: TDetails;
}

Properties

• readonly ok: false — Always false for failures.
• readonly error: TError — Structured error payload.
• readonly code: TCode — Machine-readable failure reason, mirrored from error.code.
• readonly message: string — Human-readable diagnostic, mirrored from error.message.
• readonly details?: TDetails — Optional structured context for the failure.

IndexedErrorResult

Like ErrorResult but also carries an index into the collection that was being processed.

interface IndexedErrorResult<TCode extends string, TDetails, TError extends IndexedMicro509Error<TCode, TDetails>> extends ErrorResult<TCode, TDetails, TError> {
	readonly index?: number;
}

Properties

• readonly index?: number — Zero-based position of the failing item in the input collection.

IndexedMicro509Error

Like Micro509Error but includes a positional index for collection-processing APIs.

interface IndexedMicro509Error<TCode extends string, TDetails> extends Micro509Error<TCode, TDetails> {
	readonly index?: number;
}

Properties

• readonly index?: number — Zero-based position of the failing item in the input collection.

Micro509Error

Base error shape carried by all failure results in the library.

interface Micro509Error<TCode extends string, TDetails> {
	readonly code: TCode;
	readonly message: string;
	readonly details?: TDetails;
}

Properties

• readonly code: TCode — Machine-readable failure reason (e.g. 'malformed', 'expired').
• readonly message: string — Human-readable diagnostic message.
• readonly details?: TDetails — Optional structured context for the failure.

Result

Discriminated ok union: either { ok: true; value } or { ok: false; error }.

Every fallible public API in micro509 returns a specialization of this type.

type Result<TValue, TError> = {
  readonly ok: true;
  readonly value: TValue
} | {
  readonly ok: false;
  readonly error: TError
}

ResultError

Error thrown by unwrap when a result is a failure.

Carries the structured Micro509Error payload so callers using the throwing escape hatch still get the machine-readable code and any details.

interface ResultError<TError extends Micro509Error<string, unknown>> extends Error {
	readonly code: TError[code];
	readonly error: TError;
}

Properties

• readonly code: TError[code] — Machine-readable failure reason, mirrored from error.code.
• readonly error: TError — The structured error payload that produced this exception.

UnwrappableResult

A minimal fallible-result shape: { ok: true, value } or { ok: false, error }.

type UnwrappableResult<TValue, TError> = {
  readonly ok: true;
  readonly value: TValue
} | {
  readonly ok: false;
  readonly error: TError
}

errorResult

Wraps a Micro509Error in a flattened ErrorResult.

function errorResult<TCode extends string, TDetails, TError extends Micro509Error<TCode, TDetails>>(
	error: TError,
): ErrorResult<TCode, TDetails, TError>

Parameters

• error: TError

failureResult

Builds a flattened failure result in one step.

Single source of truth for the { ok: false, error, code, message } shape: modules should construct failures with this instead of hand-rolling the object literal. The error payload carries the redundant ok: false discriminant so it matches the per-operation *Failure interfaces (interface XFailure extends Micro509Error<…> { ok: false }).

function failureResult<TCode extends string, TDetails>(
	code: TCode,
	message: string,
	details?: TDetails,
): ErrorResult<TCode, TDetails, Micro509Error<TCode, TDetails> & {
  readonly ok: false
}>

Parameters

• code: TCode
• message: string
• details?: TDetails

indexedErrorResult

Wraps an IndexedMicro509Error in a flattened IndexedErrorResult.

function indexedErrorResult<TCode extends string, TDetails, TError extends IndexedMicro509Error<TCode, TDetails>>(
	error: TError,
): IndexedErrorResult<TCode, TDetails, TError>

Parameters

• error: TError

indexedMicro509Error

Constructs an IndexedMicro509Error payload with an optional collection index.

function indexedMicro509Error<TCode extends string, TDetails>(
	code: TCode,
	message: string,
	index?: number,
	details?: TDetails,
): IndexedMicro509Error<TCode, TDetails>

Parameters

• code: TCode
• message: string
• index?: number
• details?: TDetails

isResultError

Type guard: was value thrown by unwrap? Narrows to ResultError.

function isResultError(
	value: unknown,
): value is ResultError

Parameters

• value: unknown

micro509Error

Constructs a Micro509Error payload.

function micro509Error<TCode extends string, TDetails>(
	code: TCode,
	message: string,
	details?: TDetails,
): Micro509Error<TCode, TDetails>

Parameters

• code: TCode
• message: string
• details?: TDetails

successResult

Wraps a value in a success result ({ ok: true, value }).

function successResult<TValue>(
	value: TValue,
): {
  readonly ok: true;
  readonly value: TValue
}

Parameters

• value: TValue

unwrap

Explicit escape hatch: returns the success value, or throws a ResultError carrying the structured failure.

Use when you have already validated the input (or prefer exceptions) and the Result ceremony is noise. Accepts any of the library's *Result types.

function unwrap<TValue, TError extends Micro509Error<string, unknown>>(
	result: UnwrappableResult<TValue, TError>,
): TValue

Parameters

• result: UnwrappableResult<TValue, TError>

unwrapOr

Returns the success value, or fallback when the result is a failure.

function unwrapOr<TValue>(
	result: UnwrappableResult<TValue, unknown>,
	fallback: TValue,
): TValue

Parameters

• result: UnwrappableResult<TValue, unknown>
• fallback: TValue