@oatscenter/result 0.100.0-rc.1

package/README.md

@@ -0,0 +1,32 @@
+# @oatscenter/result
+
+Class-based `Result<T, E>` and `AsyncResult<T, E>` types for TypeScript,
+inspired by Rust.
+
+The npm package contains ESM JavaScript and TypeScript declarations. Use
+`import`; CommonJS output and `require()` support have intentionally been
+removed. JSR publication remains supported.
+
+Provides explicit error handling with method chaining and the `take()` pattern
+for early returns, without relying on exceptions.
+
+```typescript
+import { AsyncResult, Result } from "@oatscenter/result";
+
+const user = await fetchUser(id).take();
+if (Result.isErr(user)) return user;
+```
+
+Key surface area:
+
+- `Result.ok(value)` / `Result.err(error)` — construction
+- `Result.try(() => ...)` / `AsyncResult.try(async () => ...)` — wrap throwing
+  code
+- `.map()`, `.mapErr()`, `.andThen()` — transforms
+- `.take()` — early return pattern (Rust's `?` operator equivalent)
+- `.match({ ok, err })` — pattern matching
+- `Result.all()` / `Result.any()` — combinators
+- `MaybeAsync<T, E>` — flexible sync/async return type
+- `BaseError` — base class for all Trellis error types
+
+See the source and inline JSDoc for full API details.

package/error.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Base error types for use with Result<T, E>
+ * @module error
+ */
+import Type, { type Static } from "typebox";
+/**
+ * Base error serialization schema.
+ * All errors serialize to this structure with optional additional fields.
+ */
+export declare const BaseErrorSchema: Type.TObject<{
+    id: Type.TString;
+    type: Type.TString;
+    message: Type.TString;
+    context: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+    traceId: Type.TOptional<Type.TString>;
+}>;
+export type BaseErrorSchema = Static<typeof BaseErrorSchema>;
+export type BaseErrorOptions = ErrorOptions & {
+    context?: Record<string, unknown>;
+    id?: string;
+    traceId?: string;
+};
+/**
+ * Base class for all errors used in Result<T, E>.
+ * @template TData - The serialized data type for this error
+ */
+export declare abstract class BaseError<TData extends BaseErrorSchema = BaseErrorSchema> extends Error {
+    #private;
+    /**
+     * Optional callback to provide a trace ID from ambient context (e.g. OpenTelemetry).
+     *
+     * Trellis (or other consumers) can set this once at startup so all BaseError
+     * instances capture a traceId automatically unless explicitly provided.
+     */
+    static traceIdGetter: (() => string | undefined) | undefined;
+    /** Unique identifier for this error instance */
+    readonly id: string;
+    /** Error type name (used for discrimination) */
+    abstract readonly name: string;
+    constructor(message: string, options?: BaseErrorOptions);
+    /**
+     * Add contextual information to this error.
+     * Useful for adding runtime context like request IDs, user IDs, etc.
+     *
+     * @param context - Key-value pairs to add to the error context
+     * @returns This error instance for chaining
+     *
+     * @example
+     * ```typescript
+     * const error = new UnauthorizedError({ reason: "Invalid token" })
+     *   .withContext({ userId: "123", requestId: "req-456" });
+     * ```
+     */
+    withContext(context?: Record<string, unknown>): this;
+    /**
+     * Get the current context object.
+     * @returns The context object
+     */
+    getContext(): Record<string, unknown>;
+    /**
+     * Get the trace ID for this error.
+     * Returns the trace ID captured at error creation time.
+     *
+     * @returns The trace ID string or undefined
+     */
+    protected getTraceId(): string | undefined;
+    /**
+     * Attach a trace ID if one was not captured when the error was created.
+     *
+     * @param traceId - Trace ID to attach to serialized error data.
+     * @returns This error instance for chaining.
+     */
+    withTraceId(traceId: string | undefined): this;
+    /**
+     * Helper method to get base serializable fields.
+     * Subclasses should use this to build their complete serializable object.
+     *
+     * @returns Base error fields (id, type, message, context, traceId)
+     */
+    protected baseSerializable(): BaseErrorSchema;
+    /**
+     * Serializes error to a plain object.
+     * Subclasses must implement this to return their specific data type.
+     *
+     * @returns Plain object representation of the error
+     */
+    abstract toSerializable(): TData;
+    /**
+     * Serializes error to JSON string.
+     *
+     * @returns JSON string representation of the error
+     */
+    toJSON(): string;
+}
+/**
+ * Schema for UnexpectedError serialization.
+ */
+export declare const UnexpectedErrorDataSchema: Type.TObject<{
+    id: Type.TString;
+    type: Type.TLiteral<"UnexpectedError">;
+    message: Type.TString;
+    context: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+    traceId: Type.TOptional<Type.TString>;
+}>;
+export type UnexpectedErrorData = Static<typeof UnexpectedErrorDataSchema>;
+/**
+ * Represents an unexpected error.
+ * Use this for wrapping unknown errors or for truly unexpected conditions.
+ */
+export declare class UnexpectedError extends BaseError<UnexpectedErrorData> {
+    readonly name: "UnexpectedError";
+    constructor(options?: BaseErrorOptions);
+    /**
+     * Serializes error to a plain object.
+     *
+     * @returns Plain object representation of the error
+     */
+    toSerializable(): UnexpectedErrorData;
+}

package/error.js

@@ -0,0 +1,164 @@
+/**
+ * Base error types for use with Result<T, E>
+ * @module error
+ */
+import { ulid } from "ulid";
+import Type, {} from "typebox";
+/**
+ * Base error serialization schema.
+ * All errors serialize to this structure with optional additional fields.
+ */
+export const BaseErrorSchema = Type.Object({
+    id: Type.String(),
+    type: Type.String(),
+    message: Type.String(),
+    context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+    traceId: Type.Optional(Type.String()),
+});
+/**
+ * Base class for all errors used in Result<T, E>.
+ * @template TData - The serialized data type for this error
+ */
+export class BaseError extends Error {
+    /**
+     * Optional callback to provide a trace ID from ambient context (e.g. OpenTelemetry).
+     *
+     * Trellis (or other consumers) can set this once at startup so all BaseError
+     * instances capture a traceId automatically unless explicitly provided.
+     */
+    static traceIdGetter;
+    /** Unique identifier for this error instance */
+    id;
+    /** Runtime contextual information */
+    #context;
+    /** Trace ID captured at error creation time */
+    #traceId;
+    constructor(message, options) {
+        const { context, id, traceId, ...errorOptions } = options ?? {};
+        super(message, errorOptions);
+        this.id = id ?? ulid();
+        this.#context = context ?? {};
+        this.#traceId = traceId ?? BaseError.traceIdGetter?.();
+        const constructor = this.constructor;
+        if ("prototype" in constructor) {
+            Object.setPrototypeOf(this, constructor.prototype);
+        }
+        const captureStackTrace = Error
+            .captureStackTrace;
+        if (captureStackTrace) {
+            captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Add contextual information to this error.
+     * Useful for adding runtime context like request IDs, user IDs, etc.
+     *
+     * @param context - Key-value pairs to add to the error context
+     * @returns This error instance for chaining
+     *
+     * @example
+     * ```typescript
+     * const error = new UnauthorizedError({ reason: "Invalid token" })
+     *   .withContext({ userId: "123", requestId: "req-456" });
+     * ```
+     */
+    withContext(context) {
+        if (context) {
+            Object.assign(this.#context, context);
+        }
+        return this;
+    }
+    /**
+     * Get the current context object.
+     * @returns The context object
+     */
+    getContext() {
+        return this.#context;
+    }
+    /**
+     * Get the trace ID for this error.
+     * Returns the trace ID captured at error creation time.
+     *
+     * @returns The trace ID string or undefined
+     */
+    getTraceId() {
+        return this.#traceId;
+    }
+    /**
+     * Attach a trace ID if one was not captured when the error was created.
+     *
+     * @param traceId - Trace ID to attach to serialized error data.
+     * @returns This error instance for chaining.
+     */
+    withTraceId(traceId) {
+        if (this.#traceId === undefined && traceId !== undefined) {
+            this.#traceId = traceId;
+        }
+        return this;
+    }
+    /**
+     * Helper method to get base serializable fields.
+     * Subclasses should use this to build their complete serializable object.
+     *
+     * @returns Base error fields (id, type, message, context, traceId)
+     */
+    baseSerializable() {
+        const traceId = this.getTraceId();
+        return {
+            id: this.id,
+            type: this.name,
+            message: this.message,
+            context: this.#context,
+            ...(traceId !== undefined && { traceId }),
+        };
+    }
+    /**
+     * Serializes error to JSON string.
+     *
+     * @returns JSON string representation of the error
+     */
+    toJSON() {
+        return JSON.stringify(this.toSerializable());
+    }
+}
+/**
+ * Schema for UnexpectedError serialization.
+ */
+export const UnexpectedErrorDataSchema = Type.Object({
+    id: Type.String(),
+    type: Type.Literal("UnexpectedError"),
+    message: Type.String(),
+    context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+    traceId: Type.Optional(Type.String()),
+});
+/**
+ * Represents an unexpected error.
+ * Use this for wrapping unknown errors or for truly unexpected conditions.
+ */
+export class UnexpectedError extends BaseError {
+    name = "UnexpectedError";
+    constructor(options) {
+        super("An unexpected error has occurred", options);
+        if (options?.cause) {
+            let root = options.cause;
+            while (root instanceof Error && root.cause) {
+                root = root.cause;
+            }
+            const causeMessage = root instanceof Error
+                ? root.message
+                : typeof root === "object"
+                    ? JSON.stringify(root)
+                    : String(root);
+            const causeStack = root instanceof Error ? root.stack : undefined;
+            this.withContext({ causeMessage, causeStack });
+        }
+    }
+    /**
+     * Serializes error to a plain object.
+     *
+     * @returns Plain object representation of the error
+     */
+    toSerializable() {
+        return this.baseSerializable();
+    }
+}

package/mod.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @oatscenter/result - Class-based Result type for TypeScript/Deno
+ *
+ * A class-based Result<T, E> system inspired by Rust's Result type,
+ * providing elegant error handling with method chaining and the `take()`
+ * pattern for early returns.
+ *
+ * This library provides two main classes:
+ * - `Result<T, E>`: Synchronous result type with method chaining
+ * - `AsyncResult<T, E>`: Asynchronous result type that implements PromiseLike
+ *
+ * @example Basic usage with static methods
+ * ```typescript
+ * import { Result } from "@oatscenter/result";
+ *
+ * function divide(a: number, b: number): Result<number, ValidationError> {
+ *   if (b === 0) {
+ *     return Result.err(new ValidationError("Division by zero"));
+ *   }
+ *   return Result.ok(a / b);
+ * }
+ *
+ * const result = divide(10, 2)
+ *   .map(x => x * 2)
+ *   .map(x => x + 1);
+ *
+ * const value = result.take();
+ * if (Result.isErr(value)) return value;
+ * console.log(value); // 11
+ * ```
+ *
+ * @example Async operations
+ * ```typescript
+ * import { AsyncResult, Result } from "@oatscenter/result";
+ *
+ * const user = AsyncResult.try(async () => {
+ *   const response = await fetch(`/api/users/123`);
+ *   return await response.json();
+ * });
+ *
+ * const result = user
+ *   .map(user => user.name)
+ *   .map(name => name.toUpperCase());
+ *
+ * const value = await result.take();
+ * if (Result.isErr(value)) return value;
+ * console.log(value); // "ALICE"
+ * ```
+ *
+ * @module
+ */
+import { Result as ResultClass } from "./result.ts";
+export { AsyncResult, Result } from "./result.ts";
+export type { ErrValue, Infer, InferErr, MaybeAsync, OkValue, } from "./result.ts";
+export declare const ok: typeof ResultClass.ok;
+export declare const err: typeof ResultClass.err;
+export declare const isOk: typeof ResultClass.isOk;
+export declare const isErr: typeof ResultClass.isErr;
+export { BaseError, UnexpectedError, UnexpectedErrorDataSchema, } from "./error.ts";
+export type { BaseErrorOptions, BaseErrorSchema, UnexpectedErrorData, } from "./error.ts";

package/mod.js

@@ -0,0 +1,58 @@
+/**
+ * @oatscenter/result - Class-based Result type for TypeScript/Deno
+ *
+ * A class-based Result<T, E> system inspired by Rust's Result type,
+ * providing elegant error handling with method chaining and the `take()`
+ * pattern for early returns.
+ *
+ * This library provides two main classes:
+ * - `Result<T, E>`: Synchronous result type with method chaining
+ * - `AsyncResult<T, E>`: Asynchronous result type that implements PromiseLike
+ *
+ * @example Basic usage with static methods
+ * ```typescript
+ * import { Result } from "@oatscenter/result";
+ *
+ * function divide(a: number, b: number): Result<number, ValidationError> {
+ *   if (b === 0) {
+ *     return Result.err(new ValidationError("Division by zero"));
+ *   }
+ *   return Result.ok(a / b);
+ * }
+ *
+ * const result = divide(10, 2)
+ *   .map(x => x * 2)
+ *   .map(x => x + 1);
+ *
+ * const value = result.take();
+ * if (Result.isErr(value)) return value;
+ * console.log(value); // 11
+ * ```
+ *
+ * @example Async operations
+ * ```typescript
+ * import { AsyncResult, Result } from "@oatscenter/result";
+ *
+ * const user = AsyncResult.try(async () => {
+ *   const response = await fetch(`/api/users/123`);
+ *   return await response.json();
+ * });
+ *
+ * const result = user
+ *   .map(user => user.name)
+ *   .map(name => name.toUpperCase());
+ *
+ * const value = await result.take();
+ * if (Result.isErr(value)) return value;
+ * console.log(value); // "ALICE"
+ * ```
+ *
+ * @module
+ */
+import { Result as ResultClass } from "./result.js";
+export { AsyncResult, Result } from "./result.js";
+export const ok = ResultClass.ok;
+export const err = ResultClass.err;
+export const isOk = ResultClass.isOk;
+export const isErr = ResultClass.isErr;
+export { BaseError, UnexpectedError, UnexpectedErrorDataSchema, } from "./error.js";

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@oatscenter/result",
+  "description": "Class-based Result and AsyncResult types for Trellis TypeScript applications.",
+  "exports": {
+    ".": {
+      "types": "./mod.d.ts",
+      "import": "./mod.js"
+    }
+  },
+  "dependencies": {
+    "typebox": "^1.1.33",
+    "ulid": "^3.0.2"
+  },
+  "version": "0.100.0-rc.1",
+  "type": "module",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OATS-Center/trellis.git"
+  }
+}