once()

once<Args, Result>(fn): (...args) => Result

Creates a function that can only be called once.

remarque

Subsequent calls return the cached result and ignore new arguments.

---

Type Parameters

Args: Args extends unknown[]

The argument types of the function.

Result: Result

The return type of the function.

---

Parameters

fn: (...args) => Result

The function to restrict to one execution.

---

Returns

The restricted function that caches the first call's result.

---

Since

2.0.0

---

Performance

O(1) lookup after first call. Single boolean flag check for optimal performance.

---

Also known as

once (Lodash, es-toolkit, Remeda, Radashi, Ramda) · ❌ (Effect, Modern Dash, Antfu)

---

Example

// Basic usage
const initialize = once(() => {
  console.log('Initializing...');
  return 'initialized';
});

initialize(); // "Initializing..." -> "initialized"
initialize(); // "initialized" (cached)

// With parameters (ignores new args after first call)
const createUser = once((name: string) => ({ id: 1, name }));

createUser('John'); // { id: 1, name: 'John' }
createUser('Jane'); // { id: 1, name: 'John' } (cached)

// Async functions
const fetchData = once(async () => fetch('/api/data'));
await fetchData(); // Fetches
await fetchData(); // Cached promise

---

How it works?

Creates a function that executes only once — subsequent calls return the cached result.

Simple Flow

Key Behavior

New arguments are ignored after the first call:

---

Use Cases

Initialize resources only once 📌

Ensure initialization code runs only once to prevent duplicate setup. Essential for resource management and preventing initialization errors.

#initialize#once#singleton#setup#resources#idempotent

const initApp = once(() => {
  console.log("App initialized");
  // ... setup code
});

initApp(); // "App initialized"
initApp(); // (ignored)

Create singletons safely

Ensure singleton instances are created only once. Essential for state management and ensuring single instance patterns.

#singleton#pattern#instance#state#management#unique

const getDb = once(() => new DatabaseConnection());
const db1 = getDb();
const db2 = getDb(); 

console.log(db1 === db2); // true

Lazy-initialize an SDK or API client

Initialize a third-party SDK on first use instead of at app startup. The standard pattern for Stripe, Firebase, Analytics, or any heavy client library.

#lazy#initialize#SDK#client#Stripe#Firebase#Analytics#singleton#setup

const getStripe = once(() => {
  return loadStripe(process.env.STRIPE_PUBLIC_KEY);
});

const getAnalytics = once(() => {
  return initializeAnalytics({ trackingId: "UA-XXXXX" });
});

// Called from multiple components — SDK loads only on first call
async function handleCheckout() {
  const stripe = await getStripe();
  stripe.redirectToCheckout({ sessionId });
}