tryumph - npm Package Compare versions

Comparing version 1.0.7 to 1.0.8

dist/index.js

@@ -7,3 +7,3 @@ "use strict";
 exports.when = exports.tryFn$ = exports.try$ = exports.Err = exports.Ok = void 0;
-console.error("experimental library, not ready for production use. everything maybe subject to change!");
+console.warn("experimental library, not ready for production use. everything maybe subject to change!");
 const result_1 = require("./result");
@@ -10,0 +10,0 @@ Object.defineProperty(exports, "Ok", { enumerable: true, get: function () { return result_1.Ok; } });

dist/matcher.d.ts

 import type { Result } from "./result";
+/**
+ * Match condition function signature.
+ * */
 type MatchCondition<TResult, TError> = (result: Result<TResult, TError>) => boolean;
+/**
+ * Match transform function signature.
+ * */
 type MatchTransform<TResult, TError, TMatchResult> = (result: Result<TResult, TError>) => TMatchResult;
+/**
+ * Matcher object type.
+ * */
 type Matcher<TResult, TError, TMatchResult> = {
+    /**
+     * Determines if this `Matcher` is a match with the given result or not.
+     */
     condition: MatchCondition<TResult, TError>;
+    /**
+     * Transforms the given `Result` to the `TMatchResult`.
+     */
     transform: MatchTransform<TResult, TError, TMatchResult>;
@@ -7,0 +22,0 @@ };

dist/result.d.ts

 import type { Matcher } from "./matcher";
-declare const tupleConstructor: new <T, Y>(...p: [T | null, Y | null]) => [
-    T | null,
-    Y | null
-];
-declare class Result<TResult, TError> extends tupleConstructor<TResult, TError> {
+import TupleConstructor from "./tupleConstructor";
+/**
+ * A `Result` can either contain a result value or an error value.
+ */
+declare class Result<TResult, TError> extends TupleConstructor<TResult, TError> {
+    /**
+     * Get the result value.
+     *
+     * @returns The result value if it exists otherwise it will return `null`.
+     */
     get res(): TResult | null;
+    /**
+     * Get the error value.
+     *
+     * @returns The error value if it exists otherwise it will return `null`.
+     *
+     */
     get err(): TError | null;
+    /**
+     * Create a Result.
+     *
+     * @param options - The result initialization options.
+     * @param options.result - The result value, should be left `null` in `Err` results.
+     * @param options.error - The result error, should be left `null` in `Ok` results.
+     *
+     * @internal
+     */
     constructor({ result, error, }: {
@@ -13,15 +33,108 @@ result?: TResult | null;
     });
+    /**
+     * Check if the `Result` has a value.
+     *
+     * @returns `true` if the result is `Ok`.
+     */
     isOk: () => boolean;
+    /**
+     * Check if the `Result` has an error.
+     *
+     * @returns `true` if the result is `Err`.
+     */
     isErr: () => boolean;
+    /**
+     * Get the result value.
+     *
+     * @returns The result value if it exists otherwise it will return `null`.
+     */
     ok: () => TResult;
+    /**
+     * Get the error value.
+     *
+     * @returns The error value if it exists otherwise it will return `null`.
+     */
     error: () => TError;
+    /**
+     * Returns the contained result value.
+     *
+     * @throws If value is an error it will throw it.
+     *
+     * @returns The result value.
+     */
     unwrap: () => TResult;
+    /**
+     * Returns the contained error value.
+     *
+     * @throws If result is `Ok` it will throw the result value as an error.
+     *
+     * @returns The error value.
+     */
     unwrapErr: () => TError;
+    /**
+     * Returns the contained result value or a provided default.
+     *
+     * @param defaultResult - The default value that gets returned in case of an `Err`.
+     *
+     * @returns The result value or provided default.
+     */
     unwrapOr: (defaultResult: TResult) => TResult;
+    /**
+     * Returns the contained result value or computes it from a closure.
+     *
+     * @param defaultProvider - The closure that will provide the default value in case of an `Err`.
+     *
+     * @returns The result value or provided default via given closure.
+     */
     unwrapOrElse: (defaultProvider: (error: TError) => TResult) => TResult;
+    /**
+     * Returns the `other` result if this is `Err`, otherwise it will return itself.
+     *
+     * @param other - The other `Result`.
+     *
+     * @returns The `other` result if this is `Err`, otherwise it will return itself.
+     */
     or: (other: Result<TResult, TError>) => Result<TResult, TError>;
-    and: <TResult_1>(other: Result<TResult_1, TError>) => Result<TResult_1, TError>;
+    /**
+     * Returns the `other` result if this is `Ok`, otherwise returns the error value of itself.
+     *
+     * @param other - The other `Result`.
+     *
+     * @returns The `other` result if this is `Ok`, otherwise returns the error value of itself.
+     */
+    and: <TResultOther>(other: Result<TResultOther, TError>) => Result<TResultOther, TError>;
+    /**
+     * It will match the result with the given `Matcher`s and return the result.
+     *
+     * @param matchers - The given `Matcher`s for the pattern matching
+     *
+     * @returns Will find the first matching condition and uses that function to transform the result.
+     *
+     * @example
+     * Here's a simple example:
+     * ```
+     * const result = await try$(itMayThrow());
+     * return result.match(
+     *  when(Ok, consumeResult),
+     *  when(Err, handleError)
+     * );
+     * ```
+     */
     match: <TMatchResult>(...matchers: Matcher<TResult, TError, TMatchResult>[]) => TMatchResult;
 }
+/**
+ * Creates an `Ok` `Result`.
+ *
+ * @param result - The result value.
+ *
+ * @returns A `Result` object containing the given result value.
+ */
 declare function Ok<TResult, TError>(result: TResult): Result<TResult, TError>;
+/**
+ * Creates an `Err` `Result`.
+ *
+ * @param error - The error value.
+ *
+ * @returns A `Result` object containing the given error value.
+ */
 declare function Err<TResult, TError>(error: TError): Result<TResult, TError>;
@@ -28,0 +141,0 @@ export type { Result };

dist/result.js

 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Err = exports.Ok = void 0;
-const tupleConstructor = Array;
-class Result extends tupleConstructor {
+const tupleConstructor_1 = __importDefault(require("./tupleConstructor"));
+/**
+ * A `Result` can either contain a result value or an error value.
+ */
+class Result extends tupleConstructor_1.default {
+    /**
+     * Get the result value.
+     *
+     * @returns The result value if it exists otherwise it will return `null`.
+     */
     get res() {
         return this[0];
     }
+    /**
+     * Get the error value.
+     *
+     * @returns The error value if it exists otherwise it will return `null`.
+     *
+     */
     get err() {
         return this[1];
     }
+    /**
+     * Create a Result.
+     *
+     * @param options - The result initialization options.
+     * @param options.result - The result value, should be left `null` in `Err` results.
+     * @param options.error - The result error, should be left `null` in `Ok` results.
+     *
+     * @internal
+     */
     constructor({ result = null, error = null, }) {
@@ -17,6 +43,33 @@ if (result && error) {
         super(result, error);
+        /**
+         * Check if the `Result` has a value.
+         *
+         * @returns `true` if the result is `Ok`.
+         */
         this.isOk = () => this.err === null;
+        /**
+         * Check if the `Result` has an error.
+         *
+         * @returns `true` if the result is `Err`.
+         */
         this.isErr = () => this.err !== null;
+        /**
+         * Get the result value.
+         *
+         * @returns The result value if it exists otherwise it will return `null`.
+         */
         this.ok = () => this.res;
+        /**
+         * Get the error value.
+         *
+         * @returns The error value if it exists otherwise it will return `null`.
+         */
         this.error = () => this.err;
+        /**
+         * Returns the contained result value.
+         *
+         * @throws If value is an error it will throw it.
+         *
+         * @returns The result value.
+         */
         this.unwrap = () => {
@@ -30,2 +83,9 @@ if (this.isOk()) {
         };
+        /**
+         * Returns the contained error value.
+         *
+         * @throws If result is `Ok` it will throw the result value as an error.
+         *
+         * @returns The error value.
+         */
         this.unwrapErr = () => {
@@ -39,2 +99,9 @@ if (this.isErr()) {
         };
+        /**
+         * Returns the contained result value or a provided default.
+         *
+         * @param defaultResult - The default value that gets returned in case of an `Err`.
+         *
+         * @returns The result value or provided default.
+         */
         this.unwrapOr = (defaultResult) => {
@@ -48,2 +115,9 @@ if (this.isErr()) {
         };
+        /**
+         * Returns the contained result value or computes it from a closure.
+         *
+         * @param defaultProvider - The closure that will provide the default value in case of an `Err`.
+         *
+         * @returns The result value or provided default via given closure.
+         */
         this.unwrapOrElse = (defaultProvider) => {
@@ -57,2 +131,9 @@ if (this.isErr()) {
         };
+        /**
+         * Returns the `other` result if this is `Err`, otherwise it will return itself.
+         *
+         * @param other - The other `Result`.
+         *
+         * @returns The `other` result if this is `Err`, otherwise it will return itself.
+         */
         this.or = (other) => {
@@ -66,2 +147,9 @@ if (this.isOk()) {
         };
+        /**
+         * Returns the `other` result if this is `Ok`, otherwise returns the error value of itself.
+         *
+         * @param other - The other `Result`.
+         *
+         * @returns The `other` result if this is `Ok`, otherwise returns the error value of itself.
+         */
         this.and = (other) => {
@@ -75,2 +163,19 @@ if (this.isErr()) {
         };
+        /**
+         * It will match the result with the given `Matcher`s and return the result.
+         *
+         * @param matchers - The given `Matcher`s for the pattern matching
+         *
+         * @returns Will find the first matching condition and uses that function to transform the result.
+         *
+         * @example
+         * Here's a simple example:
+         * ```
+         * const result = await try$(itMayThrow());
+         * return result.match(
+         *  when(Ok, consumeResult),
+         *  when(Err, handleError)
+         * );
+         * ```
+         */
         this.match = (...matchers) => {
@@ -85,5 +190,13 @@ const match = matchers.find((matcher) => matcher.condition(this));
         };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.__proto__ = Result.prototype;
     }
 }
+/**
+ * Creates an `Ok` `Result`.
+ *
+ * @param result - The result value.
+ *
+ * @returns A `Result` object containing the given result value.
+ */
 function Ok(result) {
@@ -93,2 +206,9 @@ return new Result({ result });
 exports.Ok = Ok;
+/**
+ * Creates an `Err` `Result`.
+ *
+ * @param error - The error value.
+ *
+ * @returns A `Result` object containing the given error value.
+ */
 function Err(error) {
@@ -95,0 +215,0 @@ return new Result({ error });

dist/try.d.ts

 import type { Result } from "./result";
+/**
+ * It will try and catch the possible errors during execution of the given `Promise`,
+ * And then it will return the resulting value or the thrown error.
+ *
+ * @param promise - The `Promise` to be executed safely.
+ *
+ * @returns A `Promise` to a `Result` containing the result of `promise` or the error it may have thrown.
+ */
 declare function try$<TResult, TError>(promise: Promise<TResult>): Promise<Result<TResult, TError>>;
 export default try$;
 //# sourceMappingURL=try.d.ts.map

dist/try.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const result_1 = require("./result");
+/**
+ * It will try and catch the possible errors during execution of the given `Promise`,
+ * And then it will return the resulting value or the thrown error.
+ *
+ * @param promise - The `Promise` to be executed safely.
+ *
+ * @returns A `Promise` to a `Result` containing the result of `promise` or the error it may have thrown.
+ */
 async function try$(promise) {
@@ -5,0 +13,0 @@ try {

dist/tryFn.d.ts

 import type { Result } from "./result";
 type AnyFunction = (...args: any[]) => any;
+/**
+ * It will execute a function with the given arguments,
+ * And will return its result or the error it may have thrown.
+ *
+ * @param fn - The function which is going to get executed safely.
+ *
+ * @returns A `Result` containing the result of `fn` or the error it may have thrown.
+ */
 declare function tryFn$<TError, TFunc extends AnyFunction>(fn: TFunc, ...args: Parameters<TFunc>): Result<ReturnType<TFunc>, TError>;
 export default tryFn$;
 //# sourceMappingURL=tryFn.d.ts.map

dist/tryFn.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const result_1 = require("./result");
+/**
+ * It will execute a function with the given arguments,
+ * And will return its result or the error it may have thrown.
+ *
+ * @param fn - The function which is going to get executed safely.
+ *
+ * @returns A `Result` containing the result of `fn` or the error it may have thrown.
+ */
 function tryFn$(fn, ...args) {
@@ -5,0 +13,0 @@ try {

dist/when.d.ts

 import { Ok, Err } from "./result";
 import type { Matcher, MatchTransform } from "./matcher";
+/**
+ * Creates a matcher that will match to either `Ok` or `Err` `Result`s.
+ *
+ * @remarks
+ * See {@link Result.match | the Result matching} for more details.
+ *
+ * @param pattern - The pattern can be either `Ok` or `Err` functions.
+ * @param transform - The transform function will take the result value or error value and will return the result of the match function.
+ *
+ * @returns A matcher that can be used in the `Result` `match` function.
+ *
+ * @example:
+ * Here's a simple example:
+ * ```
+ * const result = await try$(primeAsync());
+ * const message = result.match(
+ *  when(Ok, (num) => `${num} is prime!`),
+ *  when(Err, (err) => `Failed to make a prime number with Error: ${err}`)
+ * );
+ * console.log(message);
+ * ```
+ */
 declare function when<TResult, TError, TMatchResult>(pattern: typeof Ok | typeof Err, transform: MatchTransform<TResult, TError, TMatchResult>): Matcher<TResult, TError, TMatchResult>;
 export default when;
 //# sourceMappingURL=when.d.ts.map

dist/when.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const result_1 = require("./result");
+/**
+ * Creates a matcher that will match to either `Ok` or `Err` `Result`s.
+ *
+ * @remarks
+ * See {@link Result.match | the Result matching} for more details.
+ *
+ * @param pattern - The pattern can be either `Ok` or `Err` functions.
+ * @param transform - The transform function will take the result value or error value and will return the result of the match function.
+ *
+ * @returns A matcher that can be used in the `Result` `match` function.
+ *
+ * @example:
+ * Here's a simple example:
+ * ```
+ * const result = await try$(primeAsync());
+ * const message = result.match(
+ *  when(Ok, (num) => `${num} is prime!`),
+ *  when(Err, (err) => `Failed to make a prime number with Error: ${err}`)
+ * );
+ * console.log(message);
+ * ```
+ */
 function when(pattern, transform) {
@@ -5,0 +27,0 @@ return {

package.json

 {
   "name": "tryumph",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Bring the \"Umph\" to the javascript's async error handling",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
+  "files": ["dist"],
   "scripts": {
-    "prepare": "ts-node ./scripts/prepare.ts & npm run build",
+    "prepare": "ts-node ./scripts/prepare.ts && npm run build",
+    "lint": "eslint .",
     "test": "jest",
+    "test-cov": "npm run test -- --coverage",
+    "test-coveralls": "npm run test-cov && node ./scripts/coveralls.mjs",
     "build": "tsc"
@@ -20,5 +21,18 @@ },
   "keywords": [
+    "try",
     "async",
     "errorHandling",
-    "dontThrow'"
+    "dontThrow",
+    "fault tolerant",
+    "production",
+    "node.js",
+    "typescript",
+    "strong",
+    "rust",
+    "rust like",
+    "rust error handling",
+    "go",
+    "go like",
+    "go error handling",
+    "tryumph"
   ],
@@ -33,7 +47,16 @@ "author": "rzvxa",
     "@types/jest": "^29.5.11",
+    "@typescript-eslint/eslint-plugin": "^6.16.0",
+    "@typescript-eslint/parser": "^6.16.0",
+    "coveralls": "^3.1.1",
+    "eslint": "^8.56.0",
     "jest": "^29.7.0",
     "ts-jest": "^29.1.1",
     "ts-node": "^10.9.2",
+    "typedoc": "^0.25.4",
     "typescript": "^5.3.3"
-  }
+  },
+  "engines": {
+    "node": "^16.20.2"
+  },
+  "engineStrict": true
 }

README.md

 # tryumph
 
-WIP: published early to reserve the name
+![GitHub License](https://img.shields.io/github/license/rzvxa/tryumph)
+[![Test](https://github.com/rzvxa/tryumph/actions/workflows/test.yml/badge.svg)](https://github.com/rzvxa/tryumph/actions/workflows/test.yml)
+![Coveralls branch](https://img.shields.io/coverallsCoverage/github/rzvxa/tryumph)
 
@@ -5,0 +7,0 @@ Bring the "Umph" back to the JavaScript error handling!

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

33422

increased by60.85%

Number of package files

31

increased by14.81%

Lines of code

546

increased by163.77%

Number of lines in readme file

147

increased by1.38%

Worsened metrics

Dev dependency count

10

increased by100%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes