@stacksjs/error-handling 0.39.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2022 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# Stacks Error Handling
+
+Similar to the way Rust handles errors and other functional programming languages.
+
+>Encode failure into your program. This package contains a Result type that represents either success (`Ok`) or failure (`Err`).
+>
+>For asynchronous tasks, this package offers a `ResultAsync` class which wraps a `Promise<Result<T, E>>` and gives you the same level of expressivity and control as a regular `Result<T, E>`.
+>
+>`ResultAsync` is "thenable" meaning it behaves exactly like a native `Promise<Result>`, except you have access to the same methods that Result provides without having to `await` or `.then` the promise. _- neverthrow_
+
+Read more about the API in the documentation [here](https://github.com/supermacro/neverthrow).
+
+## ☘️ Features
+
+Currently, a wrapper of the `neverthrow` API.
+
+- Type-Safe Errors
+- Encode failure into your program
+
+## 🤖 Usage
+
+```bash
+pnpm i -D @stacksjs/error-handling
+```
+
+You can now use it in your project:
+
+```js
+import {
+  Err,
+  Ok,
+  Result,
+  ResultAsync,
+  err,
+  errAsync,
+  fromPromise,
+  fromSafePromise,
+  fromThrowable,
+  ok,
+  okAsync,
+} from '@stacksjs/error-handling'
+
+// ...
+```
+
+### Example #1
+
+```js
+const result = ok({ myData: 'test' }) // instance of `Ok`
+
+result.isOk() // true
+result.isErr() // false
+```
+
+### Example #2
+
+```js
+const command = 'rimraf ./pnpm-lock.yaml ./node_modules/ ./.stacks/**/node_modules'
+const result = await runCommand(command, options)
+
+if (result.isOk()) {
+  log.success('Cleaned up.')
+  process.exit(ExitCode.Success)
+}
+
+log.error(result.error)
+process.exit(ExitCode.FatalError)
+```
+
+Learn more in the [docs](https://github.com/supermacro/neverthrow/wiki).
+
+## 🧪 Testing
+
+```bash
+pnpm test
+```
+
+## 🤗 Motivation
+
+As from the [HackerNews thread](https://news.ycombinator.com/item?id=26191006) relating to "Where Everything Went Wrong: Error Handling and Error Messages in Rust (2020)":
+
+```
+Error handling has been wrong since the beginning, and has continued to be wrong ever since.
+
+First, we had error codes. Except these were wrong because people forget all the time to check them.
+
+Then we had exceptions, which solved the problem of people forgetting to check by crashing the app.
+
+Then the Java team got the bright idea to have checked exceptions, which at first helped to mitigate crashes
+from uncaught exception, but caused an explosion in thrown exception signatures, culminating in "catch Throwable".
+
+Back to square one.
+
+Then we got multi-return error objects, maybes, panics, and all sorts of bright ideas that fail to understand the basic premises of errors:
+
+  Any error system that relies upon developer discipline will fail because errors will be missed.
+
+  Any error system that handles all errors the same way will fail because there are some errors we can ignore,
+  and some errors we must not ignore. And what's ignorable/retriable to one project is not ignorable/retriable to another.
+
+Attempting to get the complete set of error types that any given call may raise is a fool's errand because of the halting
+problem it eventually invokes. Forcing people to provide such a list results in the Java problem for the same reason.
+
+It's a hard problem, which is why no one has solved it yet.
+```
+
+Quote from user [kstenerud](https://news.ycombinator.com/user?id=kstenerud).
+
+## 📈 Changelog
+
+Please see our [releases](https://github.com/stacksjs/stacks/releases) page for more information on what has changed recently.
+
+## 💪🏼 Contributing
+
+Please see [CONTRIBUTING](../../.github/CONTRIBUTING.md) for details.
+
+## 🏝 Community
+
+For help, discussion about best practices, or any other conversation that would benefit from being searchable:
+
+[Discussions on GitHub](https://github.com/stacksjs/stacks/discussions)
+
+For casual chit-chat with others using this package:
+
+[Join the Open Web Discord Server](https://discord.ow3.org)
+
+## 📄 License
+
+The MIT License (MIT). Please see [LICENSE](https://github.com/stacksjs/stacks/tree/main/LICENSE.md) for more information.
+
+Made with ❤️

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { Err, Ok, Result, ResultAsync, err, errAsync, fromPromise, fromSafePromise, fromThrowable, ok, okAsync } from 'neverthrow';
+export { Err, Ok, Result, ResultAsync, err, errAsync, fromPromise, fromSafePromise, fromThrowable, ok, okAsync };

package/dist/index.mjs

@@ -0,0 +1,14 @@
+import {
+  Err,
+  Ok,
+  Result,
+  ResultAsync,
+  err,
+  errAsync,
+  fromPromise,
+  fromSafePromise,
+  fromThrowable,
+  ok,
+  okAsync
+} from "neverthrow";
+export { Err, Ok, Result, ResultAsync, err, errAsync, fromPromise, fromSafePromise, fromThrowable, ok, okAsync };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@stacksjs/error-handling",
+  "type": "module",
+  "version": "0.39.0",
+  "packageManager": "pnpm@7.15.0",
+  "description": "Type safe error handling.",
+  "author": "Chris Breuer",
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/chrisbbreuer",
+  "homepage": "https://github.com/stacksjs/stacks/tree/main/.stacks/core/error-handling#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stacks.git",
+    "directory": "./.stacks/core/error-handling"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/stacks/issues"
+  },
+  "keywords": [
+    "errors",
+    "error-handling",
+    "neverthrow",
+    "type safe",
+    "stacks"
+  ],
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "contributors": [
+    "Chris Breuer <chris@ow3.org>"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=v18.12.1",
+    "pnpm": ">=7.15.0"
+  },
+  "peerDependencies": {
+    "@ow3/eslint-config": "^0.33.10",
+    "neverthrow": "^5.1.0"
+  },
+  "devDependencies": {
+    "mkdist": "^0.4.0",
+    "typescript": "^4.8.4"
+  },
+  "scripts": {
+    "build": "mkdist -d",
+    "dev": "mkdist -d",
+    "typecheck": "tsc --noEmit"
+  }
+}