@qlever-llc/result 0.6.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@qlever-llc/result",
+  "version": "0.6.0",
+  "description": "Class-based Result and AsyncResult types for Trellis TypeScript applications.",
+  "homepage": "https://github.com/Qlever-LLC/trellis#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Qlever-LLC/trellis"
+  },
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/Qlever-LLC/trellis/issues"
+  },
+  "main": "./script/mod.js",
+  "module": "./esm/mod.js",
+  "exports": {
+    ".": {
+      "import": "./esm/mod.js",
+      "require": "./script/mod.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "typebox": "^1.0.15",
+    "ulid": "^3.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.9.0"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/script/_dnt.polyfills.d.ts

@@ -0,0 +1,7 @@
+declare global {
+    interface Error {
+        cause?: unknown;
+    }
+}
+export {};
+//# sourceMappingURL=_dnt.polyfills.d.ts.map

package/script/_dnt.polyfills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dnt.polyfills.d.ts","sourceRoot":"","sources":["../src/_dnt.polyfills.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,KAAK;QACb,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CACF;AAED,OAAO,EAAE,CAAC"}

package/script/_dnt.polyfills.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/script/error.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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;
+    /**
+     * 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;
+}
+//# sourceMappingURL=error.d.ts.map

package/script/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,IAAI,EAAE,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;EAM1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE7D,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,EAAE,CAAC,EAAE,MAAM,CAAC;IAKZ,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,8BAAsB,SAAS,CAC7B,KAAK,SAAS,eAAe,GAAG,eAAe,CAC/C,SAAQ,KAAK;;IACb;;;;;OAKG;IACH,MAAM,CAAC,aAAa,EAAE,CAAC,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;IAE7D,gDAAgD;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,gDAAgD;IAChD,kBAA2B,IAAI,EAAE,MAAM,CAAC;gBAQ5B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB;IAcvD;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAOpD;;;OAGG;IACH,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAIrC;;;;;OAKG;IACH,SAAS,CAAC,UAAU,IAAI,MAAM,GAAG,SAAS;IAI1C;;;;;OAKG;IACH,SAAS,CAAC,gBAAgB,IAAI,eAAe;IAW7C;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,IAAI,KAAK;IAEhC;;;;OAIG;IACH,MAAM,IAAI,MAAM;CAGjB;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB;;;;;;EAMpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE3E;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,SAAS,CAAC,mBAAmB,CAAC;IACjE,SAAkB,IAAI,oBAA8B;gBAExC,OAAO,CAAC,EAAE,gBAAgB;IAiBtC;;;;OAIG;IACM,cAAc,IAAI,mBAAmB;CAG/C"}

package/script/error.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * Base error types for use with Result<T, E>
+ * @module error
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var _BaseError_context, _BaseError_traceId;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnexpectedError = exports.UnexpectedErrorDataSchema = exports.BaseError = exports.BaseErrorSchema = void 0;
+const ulid_1 = require("ulid");
+const typebox_1 = __importDefault(require("typebox"));
+/**
+ * Base error serialization schema.
+ * All errors serialize to this structure with optional additional fields.
+ */
+exports.BaseErrorSchema = typebox_1.default.Object({
+    id: typebox_1.default.String(),
+    type: typebox_1.default.String(),
+    message: typebox_1.default.String(),
+    context: typebox_1.default.Optional(typebox_1.default.Record(typebox_1.default.String(), typebox_1.default.Unknown())),
+    traceId: typebox_1.default.Optional(typebox_1.default.String()),
+});
+/**
+ * Base class for all errors used in Result<T, E>.
+ * @template TData - The serialized data type for this error
+ */
+class BaseError extends Error {
+    constructor(message, options) {
+        const { context, id, traceId, ...errorOptions } = options ?? {};
+        super(message, errorOptions);
+        /** Unique identifier for this error instance */
+        Object.defineProperty(this, "id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Runtime contextual information */
+        _BaseError_context.set(this, void 0);
+        /** Trace ID captured at error creation time */
+        _BaseError_traceId.set(this, void 0);
+        this.id = id ?? (0, ulid_1.ulid)();
+        __classPrivateFieldSet(this, _BaseError_context, context ?? {}, "f");
+        __classPrivateFieldSet(this, _BaseError_traceId, traceId ?? BaseError.traceIdGetter?.(), "f");
+        Object.setPrototypeOf(this, new.target.prototype);
+        if (Error.captureStackTrace) {
+            Error.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(__classPrivateFieldGet(this, _BaseError_context, "f"), context);
+        }
+        return this;
+    }
+    /**
+     * Get the current context object.
+     * @returns The context object
+     */
+    getContext() {
+        return __classPrivateFieldGet(this, _BaseError_context, "f");
+    }
+    /**
+     * 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 __classPrivateFieldGet(this, _BaseError_traceId, "f");
+    }
+    /**
+     * 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: __classPrivateFieldGet(this, _BaseError_context, "f"),
+            ...(traceId !== undefined && { traceId }),
+        };
+    }
+    /**
+     * Serializes error to JSON string.
+     *
+     * @returns JSON string representation of the error
+     */
+    toJSON() {
+        return JSON.stringify(this.toSerializable());
+    }
+}
+exports.BaseError = BaseError;
+_BaseError_context = new WeakMap(), _BaseError_traceId = new WeakMap();
+/**
+ * Schema for UnexpectedError serialization.
+ */
+exports.UnexpectedErrorDataSchema = typebox_1.default.Object({
+    id: typebox_1.default.String(),
+    type: typebox_1.default.Literal("UnexpectedError"),
+    message: typebox_1.default.String(),
+    context: typebox_1.default.Optional(typebox_1.default.Record(typebox_1.default.String(), typebox_1.default.Unknown())),
+    traceId: typebox_1.default.Optional(typebox_1.default.String()),
+});
+/**
+ * Represents an unexpected error.
+ * Use this for wrapping unknown errors or for truly unexpected conditions.
+ */
+class UnexpectedError extends BaseError {
+    constructor(options) {
+        super("An unexpected error has occurred", options);
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "UnexpectedError"
+        });
+        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();
+    }
+}
+exports.UnexpectedError = UnexpectedError;

package/script/mod.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @qlever-llc/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 "@qlever-llc/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 "@qlever-llc/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 "./_dnt.polyfills.js";
+import { Result as ResultClass } from "./result.js";
+export { Result, AsyncResult } from "./result.js";
+export type { OkValue, ErrValue, Infer, InferErr, MaybeAsync } from "./result.js";
+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.js";
+export type { BaseErrorSchema, BaseErrorOptions } from "./error.js";
+//# sourceMappingURL=mod.d.ts.map

package/script/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,OAAO,qBAAqB,CAAC;AAG7B,OAAO,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAElF,eAAO,MAAM,EAAE,uBAAiB,CAAC;AACjC,eAAO,MAAM,GAAG,wBAAkB,CAAC;AACnC,eAAO,MAAM,IAAI,yBAAmB,CAAC;AACrC,eAAO,MAAM,KAAK,0BAAoB,CAAC;AAEvC,OAAO,EACL,SAAS,EACT,eAAe,EACf,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/script/mod.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnexpectedErrorDataSchema = exports.UnexpectedError = exports.BaseError = exports.isErr = exports.isOk = exports.err = exports.ok = exports.AsyncResult = exports.Result = void 0;
+/**
+ * @qlever-llc/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 "@qlever-llc/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 "@qlever-llc/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
+ */
+require("./_dnt.polyfills.js");
+const result_js_1 = require("./result.js");
+var result_js_2 = require("./result.js");
+Object.defineProperty(exports, "Result", { enumerable: true, get: function () { return result_js_2.Result; } });
+Object.defineProperty(exports, "AsyncResult", { enumerable: true, get: function () { return result_js_2.AsyncResult; } });
+exports.ok = result_js_1.Result.ok;
+exports.err = result_js_1.Result.err;
+exports.isOk = result_js_1.Result.isOk;
+exports.isErr = result_js_1.Result.isErr;
+var error_js_1 = require("./error.js");
+Object.defineProperty(exports, "BaseError", { enumerable: true, get: function () { return error_js_1.BaseError; } });
+Object.defineProperty(exports, "UnexpectedError", { enumerable: true, get: function () { return error_js_1.UnexpectedError; } });
+Object.defineProperty(exports, "UnexpectedErrorDataSchema", { enumerable: true, get: function () { return error_js_1.UnexpectedErrorDataSchema; } });

package/script/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}