AimPromises 🎯

A complete Promise/A+ compatible implementation built from scratch for educational and production use. This implementation demonstrates every aspect of how Promises work internally, including proper asynchronous execution, thenable resolution, and all standard Promise methods.

✨ Features

• 🎯 Full Promise/A+ compliance
• ⚡ Proper asynchronous execution with microtask scheduling
• 🔗 Complete thenable support - works with any Promise-like object
• 🛡️ Robust error handling and state management
• 📦 Zero dependencies
• 🔷 TypeScript support included
• 🌐 Universal compatibility - works in Node.js and browsers
• 📚 Educational - clean, readable code with detailed comments

📦 Installation

npm install aim-promises

🚀 Quick Start

CommonJS

const AimPromise = require("aim-promises");

const promise = new AimPromise((resolve, reject) => {
  setTimeout(() => resolve("Hello, World!"), 1000);
});

promise.then((value) => {
  console.log(value); // "Hello, World!" after 1 second
});

ES Modules

import AimPromise from "aim-promises";

const promise = new AimPromise((resolve, reject) => {
  setTimeout(() => resolve("Hello, World!"), 1000);
});

promise.then((value) => {
  console.log(value); // "Hello, World!" after 1 second
});

TypeScript

import AimPromise from "aim-promises";

const promise = new AimPromise<string>((resolve, reject) => {
  setTimeout(() => resolve("Hello, TypeScript!"), 1000);
});

promise.then((value: string) => {
  console.log(value); // Fully typed!
});

📖 API Reference

Constructor

new AimPromise(executor);

Creates a new AimPromise instance.

• executor (Function): A function that is passed with the arguments resolve and reject

Instance Methods

.then(onFulfilled?, onRejected?)

Attaches callbacks for the resolution and/or rejection of the Promise.

promise.then((value) => value * 2).then((value) => console.log(value));

.catch(onRejected?)

Attaches a callback for only the rejection of the Promise.

promise
  .then((value) => JSON.parse(value))
  .catch((error) => console.error("Parse error:", error));

.finally(onFinally?)

Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected).

promise
  .then((value) => processData(value))
  .catch((error) => handleError(error))
  .finally(() => cleanup());

Static Methods

AimPromise.resolve(value?)

Creates a resolved promise with the given value.

AimPromise.resolve(42).then((value) => console.log(value)); // 42

AimPromise.reject(reason?)

Creates a rejected promise with the given reason.

AimPromise.reject(new Error("Something went wrong")).catch((error) =>
  console.error(error.message)
);

AimPromise.all(iterable)

Waits for all promises to resolve, or rejects if any promise rejects.

AimPromise.all([
  AimPromise.resolve(1),
  AimPromise.resolve(2),
  AimPromise.resolve(3),
]).then((values) => {
  console.log(values); // [1, 2, 3]
});

AimPromise.allSettled(iterable)

Waits for all promises to settle (resolve or reject).

AimPromise.allSettled([
  AimPromise.resolve(1),
  AimPromise.reject("error"),
  AimPromise.resolve(3),
]).then((results) => {
  console.log(results);
  // [
  //   { status: 'fulfilled', value: 1 },
  //   { status: 'rejected', reason: 'error' },
  //   { status: 'fulfilled', value: 3 }
  // ]
});

AimPromise.race(iterable)

Returns the first promise to settle (resolve or reject).

AimPromise.race([
  new AimPromise((resolve) => setTimeout(() => resolve("slow"), 1000)),
  new AimPromise((resolve) => setTimeout(() => resolve("fast"), 100)),
]).then((value) => {
  console.log(value); // 'fast'
});

🔄 Thenable Support

AimPromise fully supports thenables - any object with a .then() method:

const thenable = {
  then(onFulfilled, onRejected) {
    onFulfilled("I am a thenable!");
  },
};

AimPromise.resolve(thenable).then((value) => console.log(value)); // 'I am a thenable!'

🎓 Educational Value

This implementation demonstrates:

• State Management: How promises transition between pending, fulfilled, and rejected states
• Asynchronous Execution: Proper use of microtasks for consistent behavior
• Promise Resolution Procedure: The complex algorithm for handling thenables
• Chaining: How .then() creates new promises for seamless chaining
• Error Handling: Propagation and catching of errors through promise chains

🧪 Examples

Basic Chaining

new AimPromise((resolve) => resolve(10))
  .then((x) => x * 2)
  .then((x) => x + 5)
  .then((result) => console.log(result)); // 25

Error Recovery

new AimPromise((resolve, reject) => reject("failed"))
  .catch((error) => "recovered")
  .then((value) => console.log(value)); // 'recovered'

Async/Await (if your environment supports it)

async function example() {
  try {
    const result = await new AimPromise((resolve) =>
      setTimeout(() => resolve("async result"), 100)
    );
    console.log(result); // 'async result'
  } catch (error) {
    console.error(error);
  }
}

📋 Promise/A+ Compliance

This implementation passes all Promise/A+ specification tests:

• ✅ Promise States and Transitions
• ✅ Promise Resolution Procedure
• ✅ Asynchronous Execution
• ✅ Thenable Assimilation
• ✅ Error Handling

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License. See LICENSE file for details.

🙏 Acknowledgments

Built to demonstrate the internals of JavaScript Promises and provide a fully-functional alternative for educational and production use.

Why AimPromise? Because understanding how Promises work internally helps you aim for better asynchronous JavaScript! 🎯