Promise

The promise utility wraps any native Promise, executor function, or ReactivePromise into a ComputedPromise — an object that is both awaitable like a regular promise and reactive like a signal.

import { promise } from "elements-kit/utilities/promise";

export const data = promise<string>((resolve) => {
  setTimeout(() => resolve(`Hello at ${new Date().toLocaleTimeString()}`), 800);
});

import { promise } from "elements-kit/utilities/promise";

test("starts in pending state", () => {
  const p = promise<number>(() => {});
  expect(p.state).toBe("pending");
  expect(p.value).toBeUndefined();
});

test("resolves to fulfilled with value", async () => {
  const p = promise<number>((resolve) => resolve(42));
  await p;
  expect(p.state).toBe("fulfilled");
  expect(p.value).toBe(42);
});

test("rejects to rejected with reason", async () => {
  const p = promise<number>((_, reject) => reject(new Error("nope")));
  await p.catch(() => {});
  expect(p.state).toBe("rejected");
  expect(p.reason).toBeInstanceOf(Error);
});

test("is awaitable like a native Promise", async () => {
  const p = promise<string>((resolve) =>
    setTimeout(() => resolve("ok"), 10),
  );
  const value = await p;
  expect(value).toBe("ok");
});

Basic UsageCopy Anchor Link

import { promise } from "elements-kit/utilities/promise";

// From an executor
const cp = promise<number>((resolve) => {
  setTimeout(() => resolve(42), 1000);
});

// From an existing Promise
const cp2 = promise(fetch("/api/data").then(res => res.json()));

AwaitableCopy Anchor Link

A ComputedPromise is a real Promise — you can await it, chain .then() / .catch() / .finally(), and use it anywhere a Promise is expected:

const data = await cp;

cp.then(value => console.log(value))
  .catch(err => console.error(err));

ReactiveCopy Anchor Link

Calling the ComputedPromise as a function inside an effect or computed tracks it as a reactive dependency:

• Pending → returns undefined
• Fulfilled → returns the resolved value
• Rejected → throws the rejection reason

import { effect } from "elements-kit/signals";

effect(() => {
  try {
    const value = cp(); // undefined while pending, T when fulfilled
    console.log("value:", value);
  } catch (err) {
    console.error("error:", err);
  }
});

State PropertiesCopy Anchor Link

All three state properties are reactive — reading them inside an effect or computed subscribes to changes:

cp.state;  // "pending" | "fulfilled" | "rejected"
cp.value;  // T | undefined
cp.reason; // E | undefined

ResultCopy Anchor Link

.result is a convenience property that returns T | E | undefined — the resolved value when fulfilled, the rejection reason when rejected, or undefined while pending. Useful when you don't need to distinguish between fulfilled and rejected but just want the current value:

effect(() => {
  console.log("current result:", cp.result);
});

ReactivePromiseCopy Anchor Link

ReactivePromise is the lower-level class that powers ComputedPromise. Use it directly when you need to construct or wrap a promise and expose its reactive state without the Computed callable interface:

import { ReactivePromise } from "elements-kit/utilities/promise";

// From an executor
const rp = new ReactivePromise<number>((resolve, reject) => {
  fetch("/api/data")
    .then(res => res.json())
    .then(resolve)
    .catch(reject);
});

// Wrap an existing promise
const rp2 = ReactivePromise.from(fetch("/api/data"));

rp.state;  // "pending" | "fulfilled" | "rejected"
rp.value;  // T | undefined
rp.reason; // E | undefined
rp.result; // PromiseResult<T, E>

cp instanceof ReactivePromise returns true for any ComputedPromise.

See alsoCopy Anchor Link

• Async — higher-level controller with start / stop / run.
• Data fetching — composed async recipe.
• Signals