@lesto/errors 0.1.0

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@lesto/errors",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Lesto's shared error foundation — the LestoError base every package error extends, plus a Result type.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:cov": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint src test",
+    "format": "oxfmt src test",
+    "format:check": "oxfmt --check src test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lesto-run/lesto.git",
+    "directory": "packages/errors"
+  },
+  "homepage": "https://lesto.run",
+  "bugs": {
+    "url": "https://github.com/lesto-run/lesto/issues"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,32 @@
+/**
+ * Errors carry codes, not just prose.
+ *
+ * Every failure in Lesto surfaces a stable, machine-readable `code`. Logs,
+ * tests, API responses, and the MCP surface branch on the code — never on a
+ * message string, which is free to change for humans without breaking machines.
+ */
+
+/** The root of every Lesto error. Generic over its code union for exhaustiveness. */
+export class LestoError<Code extends string = string> extends Error {
+  readonly code: Code;
+
+  readonly details: Readonly<Record<string, unknown>>;
+
+  constructor(code: Code, message: string, details: Record<string, unknown> = {}) {
+    super(message);
+
+    this.name = "LestoError";
+    this.code = code;
+    this.details = Object.freeze({ ...details });
+  }
+}
+
+/** True iff `value` is a `LestoError` (or a subclass of one). */
+export function isLestoError(value: unknown): value is LestoError {
+  return value instanceof LestoError;
+}
+
+/** True iff `value` is a `LestoError` whose code matches exactly. */
+export function hasCode(value: unknown, code: string): boolean {
+  return isLestoError(value) && value.code === code;
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @lesto/errors — the shared error foundation every Lesto package builds on.
+ *
+ *   class QueueError extends LestoError<"QUEUE_HANDLER_NOT_FOUND"> { ... }
+ *
+ *   const result = mightFail();
+ *   if (isErr(result)) return result.error;
+ *   use(unwrap(result));
+ */
+
+export { hasCode, isLestoError, LestoError } from "./errors";
+
+export { err, isErr, isOk, ok, unwrap } from "./result";
+export type { Result } from "./result";

package/src/result.ts

@@ -0,0 +1,52 @@
+/**
+ * Result — the explicit success-or-failure value.
+ *
+ * A function that can fail returns a `Result` instead of throwing, so the
+ * failure is visible in the type and the caller is forced to handle it. The
+ * two arms are discriminated by `ok`, narrowable with `isOk` / `isErr`.
+ */
+
+import { LestoError } from "./errors";
+
+export type Result<T, E = LestoError> = { ok: true; value: T } | { ok: false; error: E };
+
+/** Wrap a value as a successful result. */
+export function ok<T>(value: T): Result<T, never> {
+  return { ok: true, value };
+}
+
+/** Wrap an error as a failed result. */
+export function err<E>(error: E): Result<never, E> {
+  return { ok: false, error };
+}
+
+/** Narrow a result to its success arm. */
+export function isOk<T, E>(result: Result<T, E>): result is { ok: true; value: T } {
+  return result.ok;
+}
+
+/** Narrow a result to its failure arm. */
+export function isErr<T, E>(result: Result<T, E>): result is { ok: false; error: E } {
+  return !result.ok;
+}
+
+/**
+ * Pull the value out of a result, throwing on failure.
+ *
+ * If the error is already an `Error`, it is thrown as-is so its stack and type
+ * survive. Otherwise it is wrapped in a `LestoError` so callers always catch an
+ * `Error`, never a bare string or object.
+ */
+export function unwrap<T, E>(result: Result<T, E>): T {
+  if (result.ok) {
+    return result.value;
+  }
+
+  const { error } = result;
+
+  if (error instanceof Error) {
+    throw error;
+  }
+
+  throw new LestoError("UNWRAP_NON_ERROR", "Tried to unwrap a failed result.", { error });
+}