promise-tuple 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024 Eduardo DONATO
+
+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,191 @@
+# Promise Tuple
+
+A lightweight utility function for handling promises with Go-like error handling pattern. Instead of using try/catch blocks, `promiseTuple` returns a tuple containing either an error or a result.
+
+## Features
+
+- 🎯 Simple and intuitive error handling
+- 📦 TypeScript support with full type safety
+- 🔄 Go-style error handling pattern
+- ⚡ Zero dependencies
+- 🌐 Works in Node.js and browsers
+
+## Installation
+
+```bash
+npm install promise-tuple
+```
+
+or with yarn:
+
+```bash
+yarn add promise-tuple
+```
+
+or with pnpm:
+
+```bash
+pnpm add promise-tuple
+```
+
+## How to Use
+
+### Import
+
+**ES Module:**
+
+```typescript
+import promiseTuple from 'promise-tuple';
+```
+
+**CommonJS:**
+
+```javascript
+const promiseTuple = require('promise-tuple');
+```
+
+### Basic Usage
+
+```typescript
+import promiseTuple from 'promise-tuple';
+
+// Example with a fetch request
+const [error, data] = await promiseTuple(fetch('/api/data'));
+
+if (error) {
+  console.error('Error:', error);
+} else {
+  console.log('Data:', data);
+}
+```
+
+### With Custom Types
+
+You can specify the type of the resolved value and error:
+
+```typescript
+import promiseTuple from 'promise-tuple';
+
+interface User {
+  id: number;
+  name: string;
+}
+
+const [error, user] = await promiseTuple<User>(
+  fetch('/api/user').then(res => res.json())
+);
+
+if (error) {
+  console.error('Failed to fetch user:', error);
+} else {
+  console.log('User:', user?.name);
+}
+```
+
+### In async/await Functions
+
+```typescript
+async function getUser(userId: string) {
+  const [error, response] = await promiseTuple(
+    fetch(`/api/users/${userId}`)
+  );
+
+  if (error) {
+    throw new Error(`Failed to fetch user: ${error}`);
+  }
+
+  const [parseError, user] = await promiseTuple(
+    response.json()
+  );
+
+  if (parseError) {
+    throw new Error(`Failed to parse user data: ${parseError}`);
+  }
+
+  return user;
+}
+```
+
+### With Custom Error Types
+
+```typescript
+import promiseTuple from 'promise-tuple';
+
+interface CustomError {
+  code: string;
+  message: string;
+}
+
+const [error, data] = await promiseTuple<string, CustomError>(
+  someAsyncOperation()
+);
+```
+
+## API
+
+### `promiseTuple<R, E>(promise)`
+
+Handles a promise and returns a tuple with error and result.
+
+**Parameters:**
+
+- `promise: Promise<R>` - The promise to handle
+
+**Returns:**
+
+- `Promise<[E | undefined, R | undefined]>` - A promise that resolves to a tuple containing either an error or a result
+
+**Type Parameters:**
+
+- `R` (default: `unknown`) - The type of the resolved value
+- `E` (default: `unknown`) - The type of the error
+
+**Behavior:**
+
+- If the promise resolves: returns `[undefined, result]`
+- If the promise rejects: returns `[error, undefined]`
+
+## Examples
+
+### Database Query
+
+```typescript
+import promiseTuple from 'promise-tuple';
+import db from './database';
+
+async function getUserById(id: number) {
+  const [error, user] = await promiseTuple(
+    db.users.findById(id)
+  );
+
+  if (error) {
+    return { success: false, message: 'User not found' };
+  }
+
+  return { success: true, user };
+}
+```
+
+### File Operations
+
+```typescript
+import promiseTuple from 'promise-tuple';
+import fs from 'fs/promises';
+
+async function readConfigFile(path: string) {
+  const [error, content] = await promiseTuple(
+    fs.readFile(path, 'utf-8')
+  );
+
+  if (error) {
+    console.error('Failed to read config:', error);
+    return null;
+  }
+
+  return JSON.parse(content);
+}
+```
+
+## License
+
+ISC

package/dist/index.cjs

@@ -0,0 +1,35 @@
+"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);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default,
+  promiseTuple: () => promiseTuple
+});
+module.exports = __toCommonJS(index_exports);
+async function promiseTuple(promise) {
+  return promise.then((result) => [void 0, result]).catch((error) => [error, void 0]);
+}
+var index_default = promiseTuple;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  promiseTuple
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../index.ts"],"sourcesContent":["/**\r\n * Handles a promise and returns a tuple with error and result.\r\n *\r\n * This function wraps a promise and returns a tuple containing either an error or a result,\r\n * similar to Go's error handling pattern. If the promise resolves, the tuple will contain\r\n * `[undefined, result]`. If the promise rejects, the tuple will contain `[error, undefined]`.\r\n *\r\n * @template R - The type of the resolved value. Defaults to `unknown`.\r\n * @template E - The type of the error. Defaults to `unknown`.\r\n * @param promise - The promise to handle.\r\n * @returns A promise that resolves to a tuple containing either an error or a result.\r\n *\r\n * @example\r\n * const [error, data] = await promiseTuple(fetchData());\r\n * if (error) {\r\n *   console.error('Error:', error);\r\n * } else {\r\n *   console.log('Data:', data);\r\n * }\r\n */\r\nexport async function promiseTuple<R = unknown, E = unknown>(\r\n    promise: Promise<R>\r\n): Promise<[E | undefined, R | undefined]> {\r\n    return promise\r\n        .then((result) => [undefined, result] as [undefined, R])\r\n        .catch((error) => [error, undefined] as [E, undefined])\r\n}\r\nexport default promiseTuple\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAoBA,eAAsB,aAClB,SACuC;AACvC,SAAO,QACF,KAAK,CAAC,WAAW,CAAC,QAAW,MAAM,CAAmB,EACtD,MAAM,CAAC,UAAU,CAAC,OAAO,MAAS,CAAmB;AAC9D;AACA,IAAO,gBAAQ;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,23 @@
+/**
+ * Handles a promise and returns a tuple with error and result.
+ *
+ * This function wraps a promise and returns a tuple containing either an error or a result,
+ * similar to Go's error handling pattern. If the promise resolves, the tuple will contain
+ * `[undefined, result]`. If the promise rejects, the tuple will contain `[error, undefined]`.
+ *
+ * @template R - The type of the resolved value. Defaults to `unknown`.
+ * @template E - The type of the error. Defaults to `unknown`.
+ * @param promise - The promise to handle.
+ * @returns A promise that resolves to a tuple containing either an error or a result.
+ *
+ * @example
+ * const [error, data] = await promiseTuple(fetchData());
+ * if (error) {
+ *   console.error('Error:', error);
+ * } else {
+ *   console.log('Data:', data);
+ * }
+ */
+declare function promiseTuple<R = unknown, E = unknown>(promise: Promise<R>): Promise<[E | undefined, R | undefined]>;
+
+export { promiseTuple as default, promiseTuple };

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Handles a promise and returns a tuple with error and result.
+ *
+ * This function wraps a promise and returns a tuple containing either an error or a result,
+ * similar to Go's error handling pattern. If the promise resolves, the tuple will contain
+ * `[undefined, result]`. If the promise rejects, the tuple will contain `[error, undefined]`.
+ *
+ * @template R - The type of the resolved value. Defaults to `unknown`.
+ * @template E - The type of the error. Defaults to `unknown`.
+ * @param promise - The promise to handle.
+ * @returns A promise that resolves to a tuple containing either an error or a result.
+ *
+ * @example
+ * const [error, data] = await promiseTuple(fetchData());
+ * if (error) {
+ *   console.error('Error:', error);
+ * } else {
+ *   console.log('Data:', data);
+ * }
+ */
+declare function promiseTuple<R = unknown, E = unknown>(promise: Promise<R>): Promise<[E | undefined, R | undefined]>;
+
+export { promiseTuple as default, promiseTuple };

package/dist/index.js

@@ -0,0 +1,10 @@
+// index.ts
+async function promiseTuple(promise) {
+  return promise.then((result) => [void 0, result]).catch((error) => [error, void 0]);
+}
+var index_default = promiseTuple;
+export {
+  index_default as default,
+  promiseTuple
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../index.ts"],"sourcesContent":["/**\r\n * Handles a promise and returns a tuple with error and result.\r\n *\r\n * This function wraps a promise and returns a tuple containing either an error or a result,\r\n * similar to Go's error handling pattern. If the promise resolves, the tuple will contain\r\n * `[undefined, result]`. If the promise rejects, the tuple will contain `[error, undefined]`.\r\n *\r\n * @template R - The type of the resolved value. Defaults to `unknown`.\r\n * @template E - The type of the error. Defaults to `unknown`.\r\n * @param promise - The promise to handle.\r\n * @returns A promise that resolves to a tuple containing either an error or a result.\r\n *\r\n * @example\r\n * const [error, data] = await promiseTuple(fetchData());\r\n * if (error) {\r\n *   console.error('Error:', error);\r\n * } else {\r\n *   console.log('Data:', data);\r\n * }\r\n */\r\nexport async function promiseTuple<R = unknown, E = unknown>(\r\n    promise: Promise<R>\r\n): Promise<[E | undefined, R | undefined]> {\r\n    return promise\r\n        .then((result) => [undefined, result] as [undefined, R])\r\n        .catch((error) => [error, undefined] as [E, undefined])\r\n}\r\nexport default promiseTuple\r\n"],"mappings":";AAoBA,eAAsB,aAClB,SACuC;AACvC,SAAO,QACF,KAAK,CAAC,WAAW,CAAC,QAAW,MAAM,CAAmB,EACtD,MAAM,CAAC,UAAU,CAAC,OAAO,MAAS,CAAmB;AAC9D;AACA,IAAO,gBAAQ;","names":[]}

package/package.json

@@ -0,0 +1,63 @@
+{
+    "name": "promise-tuple",
+    "version": "1.0.0",
+    "description": "A utility function for handling promises with Go-like error handling pattern",
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "require": {
+                "types": "./dist/index.d.cts",
+                "default": "./dist/index.cjs"
+            },
+            "import": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/index.js"
+            }
+        }
+    },
+    "sideEffects": false,
+    "scripts": {
+        "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+        "build": "tsup index.ts",
+        "test": "tsx index.test.ts",
+        "prepublishOnly": "npm run clean && npm run build && npm test"
+    },
+    "keywords": [
+        "promise",
+        "error-handling",
+        "async",
+        "utility",
+        "go-style",
+        "tuple",
+        "await",
+        "typescript"
+    ],
+    "author": "Eduardo DONATO <eduardo.donato@gmail.com>",
+    "license": "ISC",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ebdonato/promise-tuple.git"
+    },
+    "bugs": {
+        "url": "https://github.com/ebdonato/promise-tuple/issues"
+    },
+    "homepage": "https://github.com/ebdonato/promise-tuple#readme",
+    "engines": {
+        "node": ">=16"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "devDependencies": {
+        "@types/node": "^20.0.0",
+        "tsup": "^8.5.1",
+        "tsx": "^4.21.0",
+        "typescript": "^5.9.3"
+    }
+}