await-me 1.0.3

package/README.md

@@ -0,0 +1,220 @@
+# 🛡️ await-me
+
+**Production-ready, zero-dependency async error handling for JavaScript**  
+The pre-bundled, browser & legacy-Node friendly distribution of [**await-me-ts**](https://www.npmjs.com/package/await-me-ts).
+
+Stop writing repetitive `try/catch`.  
+Write clean, linear code that handles errors declaratively — works everywhere modern JavaScript runs.
+
+### For TypeScript developers — important note
+
+This package (`await-me`) is the transpiled, bundled version optimized for broad compatibility (Node ≥7, browsers, etc.).
+
+If you're using **modern TypeScript** (especially Node.js 22+ with `--experimental-strip-types` or a proper build setup), prefer the original source package:
+
+→ [**await-me-ts** — full type safety & generics](https://www.npmjs.com/package/await-me-ts)
+
+**Why prefer await-me-ts in TypeScript?**
+
+- Proper generics: `valueOf<User>() → User | false`
+- Better inference & autocompletion
+- No `any`/`unknown` surprises
+
+In `await-me` (this package), types are looser — still fully functional, just less strict.
+
+### Quick TypeScript vs JavaScript comparison
+
+```ts
+// With await-me-ts (recommended for TS)
+const user = await valueOf<User>(
+  fetchUser(id),
+  "User not found"
+); // → User | false
+
+if (!user) return;
+// user: User (narrowed)
+
+// With await-me (this package)
+const user = await valueOf(
+  fetchUser(id),
+  "User not found"
+); // → any | false
+
+if (!user) return;
+// user: any
+```
+
+### Quick Start — The Most Popular Helpers
+
+```js
+// ESM
+import { valueOf, isSuccess, toResult, create, STYLES } from 'await-me';
+
+// CommonJS
+const { valueOf, isSuccess, toResult, create, STYLES } = require('await-me');
+
+// Browser global
+<script src="https://cdn.jsdelivr.net/npm/await-me/dist/index.global.js"></script>
+// Then: const { valueOf } = WaitForMe;
+```
+
+### The "Big Three" Helpers — with TS hints
+
+| Helper       | Success return (JS)              | Success return (TS with await-me-ts) | Failure return         | Best for                             |
+|--------------|----------------------------------|--------------------------------------|------------------------|--------------------------------------|
+| `valueOf`    | value                            | `T`                                  | `false`                | Most data fetching                   |
+| `isSuccess`  | `true`                           | `true`                               | `false`                | Mutations, status checks             |
+| `toResult`   | `{ success: true, data: value }` | `{ success: true, data: T }`         | `{ success: false, ... }` | Falsy-success cases               |
+
+### Real-world examples (JS + more TS snippets)
+
+**1. Data fetch — most common pattern**
+
+```js
+// JavaScript
+const profile = await valueOf(
+  fetch(`/api/users/${userId}`).then(r => r.json()),
+  "Could not load profile"
+);
+
+if (!profile) {
+  showError("Profile not available");
+  return;
+}
+```
+
+```ts
+// TypeScript (with await-me-ts)
+interface UserProfile { id: number; name: string; email: string }
+
+const profile = await valueOf<UserProfile>(
+  fetch(`/api/users/${userId}`).then(r => r.json()),
+  "Could not load profile"
+);
+
+if (!profile) return showError("Profile not available");
+// profile: UserProfile (type safe)
+```
+
+**2. Mutation with feedback**
+
+```js
+// JavaScript
+if (await isSuccess(
+  fetch('/api/cart', {
+    method: 'POST',
+    body: JSON.stringify(cartItems)
+  }),
+  { success: "Added to cart!", error: "Update failed" }
+)) {
+  updateCartCount();
+}
+```
+
+```ts
+// TypeScript (with await-me-ts)
+const success = await isSuccess(
+  updateCart(cartItems),
+  { success: "Added to cart!" }
+);
+
+if (success) {
+  // TypeScript knows this branch only runs on success
+  updateCartCount();
+}
+```
+
+**3. Safe handling of falsy values**
+
+```js
+// JavaScript
+const result = await toResult(fetch('/api/flags').then(r => r.json()));
+
+if (!result.success) {
+  console.warn("Flags unavailable", result.error);
+  return;
+}
+
+const darkMode = result.data?.darkMode ?? false;
+```
+
+```ts
+// TypeScript (with await-me-ts)
+interface Flags { darkMode: boolean; betaFeatures: boolean }
+
+const result = await toResult<Flags>(fetch('/api/flags').then(r => r.json()));
+
+if (!result.success) return;
+
+const darkMode: boolean = result.data.darkMode ?? false;
+// Full type safety on data
+```
+
+**4. Custom handler with conditional shielding**
+
+```ts
+// TypeScript (with await-me-ts)
+const safeApi = createAsyncHandler({
+  returnStyle: RETURN_STYLES.FALSE_STYLE,
+  conditionalHandlerChain: [
+    {
+      ifTrue: (e: { status?: number }) => e.status === 404,
+      doIt: () => console.log("Not found — silent")
+    }
+  ]
+});
+
+// JavaScript version (this package)
+const safeApi = create({
+  returnStyle: STYLES.FALSE_STYLE,
+  conditionalHandlerChain: [
+    { ifTrue: e => e?.status === 404, doIt: () => {} }
+  ]
+});
+```
+
+### Go-style example (popular among backend developers)
+
+```ts
+// TypeScript (await-me-ts)
+const [err, user] = await createAsyncHandler({ returnStyle: RETURN_STYLES.GO_STYLE })(
+  fetchUser(userId)
+); // → [Error | null, User | null]
+
+if (err) {
+  if (err.code === 404) return showNotFound();
+  // err: Error (type safe)
+}
+```
+
+```js
+// JavaScript (this package)
+const [err, user] = await create({ returnStyle: STYLES.GO_STYLE })(fetchUser(userId));
+
+if (err) {
+  // err is any
+  if (err?.code === 404) return showNotFound();
+}
+```
+
+### Installation
+
+```bash
+npm install await-me
+```
+
+CDN:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/await-me@latest/dist/index.global.js"></script>
+```
+
+### Final note for TypeScript users
+
+If you want the **best possible developer experience** with full generics, inference, and zero `any` surprises — install `await-me-ts` instead:
+
+```bash
+npm install await-me-ts
+```
+
+Happy error shielding in both JS and TS! 🛡️✨

package/example.cjs

@@ -0,0 +1,54 @@
+const { WaitForMe } = require('./dist/index.cjs');
+
+// --- Mock Utilities ---
+const mockFetch = (shouldSucceed, data, errorCode) => 
+    new Promise((resolve, reject) => {
+        setTimeout(() => {
+            if (shouldSucceed) {
+                resolve(data);
+            } else {
+                const error = new Error("Request Failed");
+                error.code = errorCode || 500;
+                reject(error);
+            }
+        }, 50);
+    });
+
+async function runAdHocTest() {
+    console.log("🚀 Starting Ad-Hoc Test for await-me Bundle\n");
+
+    // 1. Test the Barrel Class Constants
+    console.log(`Checking STYLES: ${Object.keys(WaitForMe.STYLES).join(', ')}`);
+
+    // 2. Test the "Safe" Handler (FALSE_STYLE)
+    const safeFetcher = WaitForMe.create({
+        returnStyle: WaitForMe.STYLES.FALSE_STYLE,
+        defaultHandler: (e) => console.log(`[Shield] Caught expected error: ${e.message}`)
+    });
+
+    console.log("\nScenario A: Successful Data Fetch");
+    const data = await safeFetcher(mockFetch(true, { id: 42, name: "Gemini" }));
+    console.log(`Result: ${JSON.stringify(data)} (Success expected)`);
+
+    console.log("\nScenario B: Shielded Error (500)");
+    const failedResult = await safeFetcher(mockFetch(false));
+    console.log(`Result: ${failedResult} (Boolean 'false' expected)`);
+
+    // 3. Test the Derivative 'valueOf'
+    console.log("\nScenario C: Using valueOf Derivative");
+    const value = await WaitForMe.valueOf(mockFetch(true, "Direct Value"));
+    console.log(`Value: ${value}`);
+
+    // 4. Test Go-Style handling via Barrel
+    const goHandler = WaitForMe.create({ returnStyle: WaitForMe.STYLES.GO_STYLE });
+    const [err, result] = await goHandler(mockFetch(false, null, 401));
+    
+    if (err) {
+        console.log(`\nScenario D: Go-Style Error Check`);
+        console.log(`Error Code: ${err.code} - Handled successfully without try/catch.`);
+    }
+
+    console.log("\n✅ Ad-Hoc Test Completed.");
+}
+
+runAdHocTest().catch(console.error);

package/example.js

@@ -0,0 +1,54 @@
+import { WaitForMe } from './dist/index.js';
+
+// --- Mock Utilities ---
+const mockFetch = (shouldSucceed, data, errorCode) => 
+    new Promise((resolve, reject) => {
+        setTimeout(() => {
+            if (shouldSucceed) {
+                resolve(data);
+            } else {
+                const error = new Error("Request Failed");
+                error.code = errorCode || 500;
+                reject(error);
+            }
+        }, 50);
+    });
+
+async function runAdHocTest() {
+    console.log("🚀 Starting Ad-Hoc Test for await-me Bundle\n");
+
+    // 1. Test the Barrel Class Constants
+    console.log(`Checking STYLES: ${Object.keys(WaitForMe.STYLES).join(', ')}`);
+
+    // 2. Test the "Safe" Handler (FALSE_STYLE)
+    const safeFetcher = WaitForMe.create({
+        returnStyle: WaitForMe.STYLES.FALSE_STYLE,
+        defaultHandler: (e) => console.log(`[Shield] Caught expected error: ${e.message}`)
+    });
+
+    console.log("\nScenario A: Successful Data Fetch");
+    const data = await safeFetcher(mockFetch(true, { id: 42, name: "Gemini" }));
+    console.log(`Result: ${JSON.stringify(data)} (Success expected)`);
+
+    console.log("\nScenario B: Shielded Error (500)");
+    const failedResult = await safeFetcher(mockFetch(false));
+    console.log(`Result: ${failedResult} (Boolean 'false' expected)`);
+
+    // 3. Test the Derivative 'valueOf'
+    console.log("\nScenario C: Using valueOf Derivative");
+    const value = await WaitForMe.valueOf(mockFetch(true, "Direct Value"));
+    console.log(`Value: ${value}`);
+
+    // 4. Test Go-Style handling via Barrel
+    const goHandler = WaitForMe.create({ returnStyle: WaitForMe.STYLES.GO_STYLE });
+    const [err, result] = await goHandler(mockFetch(false, null, 401));
+    
+    if (err) {
+        console.log(`\nScenario D: Go-Style Error Check`);
+        console.log(`Error Code: ${err.code} - Handled successfully without try/catch.`);
+    }
+
+    console.log("\n✅ Ad-Hoc Test Completed.");
+}
+
+runAdHocTest().catch(console.error);

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "await-me",
+  "version": "1.0.3",
+  "description": "Browser-compatible, ES2015 target distribution of await-me-ts. Supports Node.js 7+.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "browser": "./dist/index.global.js",
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=7.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "script": "./dist/index.global.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "release": "npm run build && npm version patch && npm publish"
+  },
+  "dependencies": {
+    "await-me-ts": "^1.0.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "@types/node": "^22.10.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+import { 
+  createAsyncHandler, 
+  RETURN_STYLES, 
+  valueOf, 
+  isSuccess, 
+  toResult 
+} from 'await-me-ts';
+
+/**
+ * Symmetric Reflection: 
+ * We export the exact functions from the core engine.
+ */
+export {
+  createAsyncHandler,
+  valueOf,
+  isSuccess,
+  toResult,
+  RETURN_STYLES as STYLES // Alias for convenience, while keeping core name
+};
+
+/**
+ * Optional: The Barrel Namespace
+ * Provides the same symmetry for those who prefer dot-notation.
+ */
+export const WaitForMe = {
+  create: createAsyncHandler,
+  valueOf,
+  isSuccess,
+  toResult,
+  STYLES: RETURN_STYLES
+} as const;
+
+// Re-export all types from core for full IDE support
+export * from 'await-me-ts';

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": false,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist" ,"public"]
+}

package/tsup.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: {
+    'index': 'src/index.ts'
+  },
+  // Added 'iife' for direct <script> tag support in browsers
+  format: ['cjs', 'esm', 'iife'], 
+  globalName: 'WaitForMeJS',
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  outDir: 'dist',
+  // Lowered target to ES2015 for maximum compatibility
+  target: 'es2015',
+  minify: true,
+  bundle: true,
+  noExternal: ['await-me-ts'], 
+  skipNodeModulesBundle: false, 
+});