/**
 * KHAELOR
 * File: src/shared/result.ts
 * Description: Result primitive and Unsubscribe type — the shared success/failure vocabulary.
 *
 * Author: Simon-Pierre Boucher
 * Contact: contact@spboucher.ai
 */

import type { KhaelorError } from "./errors.js";

/** Discriminated success/failure result (ARCHITECTURE.md §2.2). */
export type Result<T, E = KhaelorError> = { ok: true; value: T } | { ok: false; error: E };

/** Construct a success result. */
export function ok<T>(value: T): { ok: true; value: T } {
  return { ok: true, value };
}

/** Construct a failure result. */
export function err<E>(error: E): { ok: false; error: E } {
  return { ok: false, error };
}

/** Unwrap a result or throw its error (for boundaries where throwing is correct). */
export function unwrap<T, E>(result: Result<T, E>): T {
  if (result.ok) return result.value;
  throw result.error instanceof Error
    ? result.error
    : new Error(String(result.error));
}

/** Returned by every subscription — calling it detaches the handler. */
export type Unsubscribe = () => void;