@resulted/results 0.0.0

package/LICENSE.md

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Josh <josh@bashed.sh>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# `@resulted/results`
+
+[![npm version](https://img.shields.io/npm/v/@resulted/results.svg)](https://www.npmjs.com/package/@resulted/results)
+[![JSR](https://jsr.io/badges/@resulted/results)](https://jsr.io/@resulted/results)
+[![ISC License](https://img.shields.io/badge/license-ISC-blue.svg)](LICENSE.md)
+
+A TypeScript library for handling results and errors in a functional programming style.
+
+## Installation
+
+NPM:
+```bash
+npm install @resulted/results
+yarn add @resulted/results
+pnpm add @resulted/results
+```
+
+JSR:
+```bash
+deno add jsr:@resulted/results
+pnpm add jsr:@resulted/results
+```
+
+## Usage
+
+```typescript
+import { Result } from '@resulted/results';
+
+function divide(a: number, b: number): Result<number, 'ZeroDivisionError'> {
+    if (b === 0) {
+        return Result.err('ZeroDivisionError');
+    }
+    return Result.ok(a / b);
+}
+
+function doMath(): Result<number, 'DivisionError'> {
+    const randomNum = Math.floor(Math.random() * 10);
+    return divide(10, randomNum).mapErr(() => 'DivisionError');
+}
+
+function main() {
+    const result = doMath();
+    if (result.isOk()) {
+        console.log('Result:', result.value);
+    } else {
+        console.error('Error:', result.error);
+    }
+}
+```
+
+## Contributing
+
+Contributions are welcome! This project uses [pnpm](https://pnpm.io/) as its package manager.
+
+### Setup
+
+```bash
+git clone https://github.com/resulted-io/results.git
+cd results
+pnpm install
+```
+
+### Scripts
+
+- `pnpm run build`: Build CJS and ESM outputs
+- `pnpm run typecheck`: Run TypeScript type checking
+- `pnpm run lint`: Run Biome linter
+- `pnpm run format`: Auto-fix lint and formatting issues
+
+### Submitting Changes
+
+1. Fork the repository and create a feature branch.
+2. Make your changes and ensure `pnpm run lint` and `pnpm run typecheck` pass.
+3. Open a pull request with a clear description of your changes.
+
+## License
+
+This project is licensed under the ISC License. See [LICENSE.md](LICENSE.md) for details.

package/dist/index.cjs

@@ -0,0 +1,88 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Result: () => Result
+});
+module.exports = __toCommonJS(index_exports);
+var resultProto = Object.freeze({
+  isErr() {
+    return this.type === "err";
+  },
+  isOk() {
+    return this.type === "ok";
+  },
+  map(fn) {
+    if (this.type === "ok")
+      return createResult({
+        type: "ok",
+        value: fn(this.value)
+      });
+    else
+      return createResult({ error: this.error, type: "err" });
+  },
+  mapErr(fn) {
+    if (this.type === "err")
+      return createResult({
+        error: fn(this.error),
+        type: "err"
+      });
+    else return createResult({ type: "ok", value: this.value });
+  }
+});
+var createResult = (res) => {
+  const obj = Object.create(resultProto);
+  if (res.type === "ok") {
+    obj.type = "ok";
+    obj.value = res.value;
+  } else {
+    obj.type = "err";
+    obj.error = res.error;
+  }
+  return obj;
+};
+var ok = (value) => createResult({ type: "ok", value });
+var err = (error) => createResult({ error, type: "err" });
+var trySync = (fn) => {
+  try {
+    return ok(fn());
+  } catch (e) {
+    return err(e);
+  }
+};
+var tryAsync = async (promise) => {
+  try {
+    const value = await promise;
+    return ok(value);
+  } catch (e) {
+    return err(e);
+  }
+};
+var Result = {
+  err,
+  ok,
+  try: tryAsync,
+  trySync
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Result
+});

package/dist/index.d.cts

@@ -0,0 +1,51 @@
+/**
+ * An Ok type representing a successful result.
+ */
+type OkBase<Ok> = {
+    type: 'ok';
+    value: Ok;
+};
+/**
+ * An Err type representing a failed result.
+ */
+type ErrBase<Err> = {
+    type: 'err';
+    error: Err;
+};
+/**
+ * A simple ResultBase type to represent success or failure.
+ */
+type ResultBase<Ok, Err> = OkBase<Ok> | ErrBase<Err>;
+/**
+ * A Result type that includes utility methods.
+ */
+type ResultProto<Ok, Err> = {
+    isOk(): this is {
+        type: 'ok';
+        value: Ok;
+    };
+    isErr(): this is {
+        type: 'err';
+        error: Err;
+    };
+    map<NewOk>(fn: (value: Ok) => NewOk): Result<NewOk, Err>;
+    mapErr<NewErr>(fn: (error: Err) => NewErr): Result<Ok, NewErr>;
+};
+/**
+ * A Result type that can represent either a successful value or an error.
+ *
+ * When the `type` is 'ok', the `value` property will contain the successful result.
+ * When the `type` is 'err', the `error` property will contain the error information.
+ */
+type Result<Ok, Err> = (OkBase<Ok> & ResultProto<Ok, never>) | (ErrBase<Err> & ResultProto<never, Err>);
+/**
+ * Result functions.
+ */
+declare const Result: {
+    err: <Ok, Err>(error: Err) => Result<Ok, Err>;
+    ok: <Ok, Err>(value: Ok) => Result<Ok, Err>;
+    try: <Ok, Err = unknown>(promise: Promise<Ok>) => Promise<Result<Ok, Err>>;
+    trySync: <Ok, Err = unknown>(fn: () => Ok) => Result<Ok, Err>;
+};
+
+export { Result, type ResultBase, type ResultProto };

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * An Ok type representing a successful result.
+ */
+type OkBase<Ok> = {
+    type: 'ok';
+    value: Ok;
+};
+/**
+ * An Err type representing a failed result.
+ */
+type ErrBase<Err> = {
+    type: 'err';
+    error: Err;
+};
+/**
+ * A simple ResultBase type to represent success or failure.
+ */
+type ResultBase<Ok, Err> = OkBase<Ok> | ErrBase<Err>;
+/**
+ * A Result type that includes utility methods.
+ */
+type ResultProto<Ok, Err> = {
+    isOk(): this is {
+        type: 'ok';
+        value: Ok;
+    };
+    isErr(): this is {
+        type: 'err';
+        error: Err;
+    };
+    map<NewOk>(fn: (value: Ok) => NewOk): Result<NewOk, Err>;
+    mapErr<NewErr>(fn: (error: Err) => NewErr): Result<Ok, NewErr>;
+};
+/**
+ * A Result type that can represent either a successful value or an error.
+ *
+ * When the `type` is 'ok', the `value` property will contain the successful result.
+ * When the `type` is 'err', the `error` property will contain the error information.
+ */
+type Result<Ok, Err> = (OkBase<Ok> & ResultProto<Ok, never>) | (ErrBase<Err> & ResultProto<never, Err>);
+/**
+ * Result functions.
+ */
+declare const Result: {
+    err: <Ok, Err>(error: Err) => Result<Ok, Err>;
+    ok: <Ok, Err>(value: Ok) => Result<Ok, Err>;
+    try: <Ok, Err = unknown>(promise: Promise<Ok>) => Promise<Result<Ok, Err>>;
+    trySync: <Ok, Err = unknown>(fn: () => Ok) => Result<Ok, Err>;
+};
+
+export { Result, type ResultBase, type ResultProto };

package/dist/index.js

@@ -0,0 +1,63 @@
+// src/index.ts
+var resultProto = Object.freeze({
+  isErr() {
+    return this.type === "err";
+  },
+  isOk() {
+    return this.type === "ok";
+  },
+  map(fn) {
+    if (this.type === "ok")
+      return createResult({
+        type: "ok",
+        value: fn(this.value)
+      });
+    else
+      return createResult({ error: this.error, type: "err" });
+  },
+  mapErr(fn) {
+    if (this.type === "err")
+      return createResult({
+        error: fn(this.error),
+        type: "err"
+      });
+    else return createResult({ type: "ok", value: this.value });
+  }
+});
+var createResult = (res) => {
+  const obj = Object.create(resultProto);
+  if (res.type === "ok") {
+    obj.type = "ok";
+    obj.value = res.value;
+  } else {
+    obj.type = "err";
+    obj.error = res.error;
+  }
+  return obj;
+};
+var ok = (value) => createResult({ type: "ok", value });
+var err = (error) => createResult({ error, type: "err" });
+var trySync = (fn) => {
+  try {
+    return ok(fn());
+  } catch (e) {
+    return err(e);
+  }
+};
+var tryAsync = async (promise) => {
+  try {
+    const value = await promise;
+    return ok(value);
+  } catch (e) {
+    return err(e);
+  }
+};
+var Result = {
+  err,
+  ok,
+  try: tryAsync,
+  trySync
+};
+export {
+  Result
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "author": "Josh <josh@bashed.sh>",
+  "description": "A TypeScript library for handling results and errors in a functional programming style.",
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "default": "./dist/index.js",
+        "types": "./dist/index.d.ts"
+      },
+      "require": {
+        "default": "./dist/index.cjs",
+        "types": "./dist/index.d.cts"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE.md"
+  ],
+  "keywords": [
+    "result",
+    "error-handling",
+    "typescript",
+    "functional",
+    "monad"
+  ],
+  "license": "ISC",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "name": "@resulted/results",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JoshBashed/resulted-results.git"
+  },
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "version": "0.0.0",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "format": "biome check --write",
+    "lint": "biome check",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,138 @@
+/**
+ * An Ok type representing a successful result.
+ */
+type OkBase<Ok> = { type: 'ok'; value: Ok };
+
+/**
+ * An Err type representing a failed result.
+ */
+type ErrBase<Err> = { type: 'err'; error: Err };
+
+/**
+ * A simple ResultBase type to represent success or failure.
+ */
+export type ResultBase<Ok, Err> = OkBase<Ok> | ErrBase<Err>;
+
+/**
+ * A Result type that can represent either a successful value or an error.
+ *
+ * When the `type` is 'ok', the `value` property will contain the successful result.
+ * When the `type` is 'err', the `error` property will contain the error information.
+ */
+export type Result<Ok, Err> =
+    | (OkBase<Ok> & ResultProto<Ok, never>)
+    | (ErrBase<Err> & ResultProto<never, Err>);
+
+/**
+ * A Result type that includes utility methods.
+ */
+export type ResultProto<Ok, Err> = {
+    isOk(): this is { type: 'ok'; value: Ok };
+    isErr(): this is { type: 'err'; error: Err };
+    map<NewOk>(fn: (value: Ok) => NewOk): Result<NewOk, Err>;
+    mapErr<NewErr>(fn: (error: Err) => NewErr): Result<Ok, NewErr>;
+};
+
+const resultProto = Object.freeze({
+    isErr<Ok, Err>(this: Result<Ok, Err>): this is { type: 'err'; error: Err } {
+        return this.type === 'err';
+    },
+    isOk<Ok, Err>(this: Result<Ok, Err>): this is { type: 'ok'; value: Ok } {
+        return this.type === 'ok';
+    },
+    map<Ok, Err, NewOk>(
+        this: Result<Ok, Err>,
+        fn: (value: Ok) => NewOk,
+    ): Result<NewOk, Err> {
+        if (this.type === 'ok')
+            return createResult<NewOk, Err>({
+                type: 'ok',
+                value: fn(this.value),
+            });
+        else
+            return createResult<NewOk, Err>({ error: this.error, type: 'err' });
+    },
+    mapErr<Ok, Err, NewErr>(
+        this: Result<Ok, Err>,
+        fn: (error: Err) => NewErr,
+    ): Result<Ok, NewErr> {
+        if (this.type === 'err')
+            return createResult<Ok, NewErr>({
+                error: fn(this.error),
+                type: 'err',
+            });
+        else return createResult<Ok, NewErr>({ type: 'ok', value: this.value });
+    },
+});
+
+/**
+ * Helper function to create a Result object with the appropriate prototype.
+ * @param res The base result object containing either an Ok value or an Err error.
+ * @returns A Result object with utility methods attached.
+ */
+const createResult = <Ok, Err>(res: ResultBase<Ok, Err>): Result<Ok, Err> => {
+    const obj = Object.create(resultProto) as Result<Ok, Err>;
+    if (res.type === 'ok') {
+        obj.type = 'ok';
+        (obj as OkBase<Ok>).value = res.value;
+    } else {
+        obj.type = 'err';
+        (obj as ErrBase<Err>).error = res.error;
+    }
+    return obj;
+};
+
+/**
+ * Create an Ok result.
+ * @param value The value to wrap in an Ok result.
+ * @returns A Result object representing success.
+ */
+const ok = <Ok, Err>(value: Ok): Result<Ok, Err> =>
+    createResult({ type: 'ok', value });
+
+/**
+ * Create an Err result.
+ * @param error The error to wrap in an Err result.
+ * @returns A Result object representing failure.
+ */
+const err = <Ok, Err>(error: Err): Result<Ok, Err> =>
+    createResult({ error, type: 'err' });
+
+/**
+ * Execute a synchronous function and capture its result as a Result type.
+ * @param fn The function to execute, which may throw an error.
+ * @returns The result of Ok or Err.
+ */
+const trySync = <Ok, Err = unknown>(fn: () => Ok): Result<Ok, Err> => {
+    try {
+        return ok<Ok, Err>(fn());
+    } catch (e) {
+        return err<Ok, Err>(e as Err);
+    }
+};
+
+/**
+ * Execute an asynchronous function and capture its result as a Result type.
+ * @param promise The promise to execute, which may reject with an error.
+ * @returns The result of Ok or Err depending.
+ */
+const tryAsync = async <Ok, Err = unknown>(
+    promise: Promise<Ok>,
+): Promise<Result<Ok, Err>> => {
+    try {
+        const value = await promise;
+        return ok<Ok, Err>(value);
+    } catch (e) {
+        return err<Ok, Err>(e as Err);
+    }
+};
+
+/**
+ * Result functions.
+ */
+export const Result = {
+    err,
+    ok,
+    try: tryAsync,
+    trySync,
+};