Disclaimer

This repository is a personal project created for practicing the process of building and publishing an open-source library.

Lazy Promise

A lazy promise that waits until you ask it to get to work.

📌 Description

LazyPromise is a lightweight utility for lazily initializing values in JavaScript and TypeScript. Specifically, it will not perform any computation until the value is accessed (e.g., awaited). Additionally, LazyPromise supports lazy chaining, allowing you to chain operations that also won’t execute until the result is needed.

✨ Features

✅ Lazy evaluation – Compute values only when first accessed.
✅ Lazy Chaining – Define transformations to values lazily.
✅ Minimal – No dependencies.
✅ TypeScript support – Fully typed.

📦 Installation

Using npm:

npm install @jovulic/lazy-promise

Using yarn:

yarn add @jovulic/lazy-promise

Using pnpm:

pnpm add @jovulic/lazy-promise

🚀 Usage

Basic Example

import { LazyPromise } from "@jovulic/lazy-promise";

const lazyValue = new LazyPromise(async () => {
  return "My Lazy Value";
});

(async () => {
  console.log(await lazyValue); // "My Lazy Value"
  console.log(await lazyValue); // "My Lazy Value" (no recomputation)
})();

Lazy Chaining

import { LazyPromise } from "@jovulic/lazy-promise";

const lazyValue = new LazyPromise(async () => {
  return "My Lazy Value";
});

const transformedValue = lazyValue.later((value) => value.toUpperCase());

console.log(await transformedValue); // "MY LAZY VALUE"

🛠️ Build

This project uses Nix for development to ensuring a consistent and reproducible environment. It is easy enough to build without it, but the following guide will be using Nix.

Follow these steps to build and work on the project locally:

1. Install Nix: If you don't have Nix installed, follow the instructions for your platform at https://nixos.org/download.html.

2. Clone the Repository: Clone the lazy-promise repository to your local machine.

   git clone https://github.com/jovulic/lazy-promise.git
   cd lazy-promise

3. Enter the Development Shell: Use the following command to enter the Nix development shell. This will automatically install all the necessary dependencies defined in the flake.nix file.

   nix develop

   This command might take a while the first time as it downloads and installs the dependencies. Subsequent entries into the shell will be much faster.

4. Install NPM Dependencies: Once inside the Nix shell, you'll need to install the project's npm dependencies. Even though Nix provides Node.js and npm, the project dependencies are managed by npm. We do this via the ctl command that is added into the development shell.

   ctl setup

5. Build the Library: You can now build the library.

   ctl build

   This will create a dist directory containing the compiled library files.