@mkvlrn/result 4.0.3 → 4.0.4

package/README.md

@@ -1,54 +1,94 @@
-# template-node
-
-A sane, opinionated template for esm node projects written in typescript.
-
-For new, node 24+ projects.
-
-Uses:
-
-- [biome](https://github.com/biomejs/biome) for linting and formatting
-- [commitlint](https://github.com/conventional-changelog/commitlint) for linting commit messages
-- [husky](https://github.com/typicode/husky) for git hooks
-- [vite](https://github.com/vitejs/vite) for building
-- [vitest](https://github.com/vitest-dev/vitest) for testing
-- [tsx](https://github.com/privatenumber/tsx) for dev time typescript
-
-## running
-
-### `npm run dev`
-
-Runs the project in watch mode.
-
-### `npm run build`
-
-Builds/transpiles the code to `./build`.
-
-### `npm start`
-
-Runs the built project.
-
-### `npm test`
-
-Runs tests.
-
-### `npm run biome-fix`
-
-Runs biome in fix mode (only [safe fixes](https://biomejs.dev/linter/#safe-fixes)) to lint and format the project.
-
-### `npm run typecheck`
-
-Runs type checking using tsc.
-
-## that tsconfig.json seems very strict and opinionated
-
-Yup.
-
-## vscode
-
-You might want to install the recommended extensions in vscode. Search for **@recommended** in the extensions tab, they'll show up as _"workspace recommendations"_.
-
-If you have been using eslint and prettier and their extensions, you might want to disable eslint entirely and keep prettier as the formatter only for certain types of files.
-
-This is done by the `.vscode/settings.json` file.
-
-Debug configurations are also included (for source using tsx and for bundle using the generated source maps).
+# @mkvlrn/result
+
+Type-safe Result pattern for TypeScript representing success or error. Anything to avoid try/catch hell.
+
+## Installation
+
+```bash
+npm add @mkvlrn/result
+```
+
+## Usage
+
+```typescript
+import { Result, AsyncResult, R } from "@mkvlrn/result";
+
+// Success
+const success = R.ok(42);
+
+// Error
+const failure = R.error(new Error("Something went wrong"));
+
+// Check result
+const result = R.ok(42);
+if (result.error) {
+  console.log("Error:", result.error.message);
+} else {
+  console.log("Value:", result.value);
+}
+```
+
+## Examples
+
+### Basic Function
+
+```typescript
+function divide(a: number, b: number): Result<number, Error> {
+  if (b === 0) {
+    return R.error(new Error("Division by zero"));
+  }
+  return R.ok(a / b);
+}
+
+const result = divide(10, 2);
+if (!result.error) {
+  console.log(result.value); // 5
+}
+```
+
+### Async Operations
+
+```typescript
+async function fetchUser(id: number): AsyncResult<User, Error> {
+  try {
+    const response = await fetch(`/api/users/${id}`);
+    if (!response.ok) {
+      return R.error(new Error(`HTTP ${response.status}`));
+    }
+    const user = await response.json();
+    return R.ok(user);
+  } catch (error) {
+    return R.error(error instanceof Error ? error : new Error("Unknown error"));
+  }
+}
+```
+
+### Custom Error Types
+
+```typescript
+class ValidationError extends Error {
+  readonly customField: number;
+
+  constructor(customField: number, message: string) {
+    super(message);
+    this.name = "ValidationError";
+    this.customField = customField;
+  }
+}
+
+function validateEmail(email: string): Result<string, ValidationError> {
+  if (!email.includes("@")) {
+    return Result.error(new ValidationError(400, "custom"));
+  }
+  return Result.ok(email);
+}
+
+const result = validateEmail("invalid-email");
+if (result.error) {
+  console.log(`${result.error.customField}: ${result.error.message}`);
+}
+```
+
+## License
+
+MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mkvlrn/result",
   "description": "Simple Result type/pattern for TypeScript",
-  "version": "4.0.3",
+  "version": "4.0.4",
   "license": "MIT",
   "type": "module",
   "author": "Mike Valeriano <mkvlrn@proton.me>",
@@ -17,6 +17,9 @@
   "engines": {
     "node": "24.x"
   },
+  "files": [
+    "build"
+  ],
   "scripts": {
     "build": "vite build",
     "dev": "tsx --watch src/main.ts",

package/.turbo/turbo-build.log

@@ -1,10 +0,0 @@
-
-
-> @mkvlrn/result@4.0.3 build
-> vite build
-
-vite v7.0.6 building for production...
-transforming (1) src/index.ts✓ 1 modules transformed.
-rendering chunks (1)...computing gzip size (0)...computing gzip size (1)...build/index.js  0.15 kB │ gzip: 0.13 kB │ map: 1.52 kB
-✓ built in 409ms
-⠙

package/CHANGELOG.md

@@ -1,13 +0,0 @@
-# @repo/result
-
-## 4.0.3
-
-### Patch Changes
-
-- cfba44e: fix monorepo deploy
-
-## 4.0.2
-
-### Patch Changes
-
-- 8ebb722: move to monorepo

package/biome.jsonc

@@ -1,9 +0,0 @@
-{
-  "$schema": "../../node_modules/@biomejs/biome/configuration_schema.json",
-  "root": false,
-  "extends": "//",
-  "files": {
-    "ignoreUnknown": true,
-    "includes": ["**/*", "!build/**", "!node_modules/**", "!dist/**", "!coverage/**"]
-  }
-}

package/src/index.test.ts

@@ -1,66 +0,0 @@
-import { setTimeout } from "node:timers/promises";
-import { assert, describe, it } from "vitest";
-import { type AsyncResult, R, type Result } from "./index.js";
-
-class CustomError extends Error {
-  readonly customField: number;
-
-  constructor(customField: number, message: string) {
-    super(message);
-    this.name = "CustomField";
-    this.customField = customField;
-  }
-}
-
-function division(a: number, b: number): Result<number, Error> {
-  if (b === 0) {
-    return R.error(new Error("cannot divide by zero"));
-  }
-
-  return R.ok(a / b);
-}
-
-async function longRunning(shouldFail: boolean): AsyncResult<number, CustomError> {
-  await setTimeout(1);
-
-  return shouldFail ? R.error(new CustomError(42, "wrong")) : R.ok(3);
-}
-
-describe("creates a valid result", () => {
-  describe("default Error type", () => {
-    it("ok result", () => {
-      const result = division(4, 2);
-
-      assert.isUndefined(result.error);
-      assert.isDefined(result.value);
-      assert.strictEqual(result.value, 2);
-    });
-
-    it("error result", () => {
-      const result = division(4, 0);
-
-      assert.isDefined(result.error);
-      assert.instanceOf(result.error, Error);
-      assert.strictEqual(result.error.message, "cannot divide by zero");
-    });
-  });
-
-  describe("custom error", () => {
-    it("ok result", async () => {
-      const result = await longRunning(false);
-
-      assert.isUndefined(result.error);
-      assert.isDefined(result.value);
-      assert.strictEqual(result.value, 3);
-    });
-
-    it("error result", async () => {
-      const result = await longRunning(true);
-
-      assert.isDefined(result.error);
-      assert.instanceOf(result.error, CustomError);
-      assert.strictEqual(result.error.message, "wrong");
-      assert.strictEqual(result.error.customField, 42);
-    });
-  });
-});

package/src/index.ts

@@ -1,37 +0,0 @@
-/**
- * Result type to represent the outcome of an operation.
- * It can either be a success with a value or an error.
- * This is a generic type that can be used with any type of value and error (should extend Error).
- *
- * It is also an alias object containing the ok and error functions to
- * make it easier to create Result objects.
- */
-export type Result<T, E extends Error> =
-  | { readonly error: undefined; readonly value: T }
-  | { readonly error: E };
-
-/**
- * Async version of Result type that wraps a Result in a Promise.
- */
-export type AsyncResult<T, E extends Error> = Promise<Result<T, E>>;
-
-/**
- * Result utility functions for creating Result objects.
- */
-export const R: {
-  /**
-   * Creates a successful Result with the given value.
-   * @param value The success value
-   * @returns A Result object representing success
-   */
-  ok<T>(value: T): Result<T, never>;
-  /**
-   * Creates an error Result with the given error.
-   * @param error The error value
-   * @returns A Result object representing error
-   */
-  error<E extends Error>(error: E): Result<never, E>;
-} = {
-  ok: <T>(value: T): Result<T, never> => ({ error: undefined, value }),
-  error: <E extends Error>(error: E): Result<never, E> => ({ error }),
-};

package/tsconfig.json

@@ -1,43 +0,0 @@
-{
-  "compilerOptions": {
-    // no transpiling
-    "noEmit": true,
-
-    // no funny business
-    "erasableSyntaxOnly": true,
-    "verbatimModuleSyntax": true,
-
-    // very strict
-    // https://whatislove.dev/articles/the-strictest-typescript-config/
-    "allowJs": false,
-    "exactOptionalPropertyTypes": true,
-    // "noPropertyAccessFromIndexSignature": true,
-    "noUncheckedIndexedAccess": true,
-    "strict": true,
-    "strictNullChecks": true,
-    "noUncheckedSideEffectImports": true,
-
-    // esm
-    "esModuleInterop": true,
-    "isolatedModules": true,
-    "lib": ["ESNext"],
-    "module": "esnext",
-    "moduleResolution": "bundler",
-    "target": "esnext",
-
-    // pnpm compatibility
-    "preserveSymlinks": true,
-
-    // self explanatory
-    "resolveJsonModule": true,
-
-    // don't try to check for errors on imported libs
-    "skipLibCheck": true,
-
-    // paths
-    "baseUrl": ".",
-    "paths": {
-      "#/*": ["./src/*"]
-    }
-  }
-}

package/vite.config.ts

@@ -1,55 +0,0 @@
-import { existsSync, globSync } from "node:fs";
-import nodeExternals from "rollup-plugin-node-externals";
-import dts from "vite-plugin-dts";
-import tsconfigPaths from "vite-tsconfig-paths";
-import { defineConfig } from "vitest/config";
-
-// application entry point
-const entry = globSync("./src/**/*.ts").filter((f) => !f.endsWith("test.ts"));
-const entryRoot = "src";
-
-// emits declarations only if there is no src/main.ts file
-const dtsPlugin = existsSync("./src/main.ts")
-  ? null
-  : dts({ include: entry, logLevel: "error", entryRoot: entryRoot });
-
-export default defineConfig({
-  plugins: [
-    // externalize node built-ins only
-    nodeExternals(),
-    // resolve tsconfig path aliases
-    tsconfigPaths(),
-    // declarations (if lib)
-    dtsPlugin,
-  ].filter(Boolean),
-
-  build: {
-    target: "esnext",
-    lib: {
-      entry,
-      formats: ["es"],
-    },
-    sourcemap: true,
-    outDir: "./build",
-    emptyOutDir: true,
-    rollupOptions: { output: { preserveModules: true, preserveModulesRoot: entryRoot } },
-  },
-
-  test: {
-    include: ["./src/**/*.test.{ts,tsx}"],
-    reporters: ["verbose"],
-    watch: false,
-    coverage: {
-      all: true,
-      clean: true,
-      cleanOnRerun: true,
-      include: ["src"],
-      exclude: ["**/*.test.{ts,tsx}", "**/*main.ts"],
-    },
-    // biome-ignore lint/style/useNamingConvention: needed for vitest
-    env: { NODE_ENV: "test" },
-    environment: "node",
-    passWithNoTests: true,
-    setupFiles: [],
-  },
-});