async-gate

A Promise-based async gate manager for coordinating asynchronous initialization flows in JavaScript/TypeScript applications.

Features

• 🚦 Simple API - register, open, waitFor, reset
• ⏱️ Timeout support - Avoid hanging forever
• 🔄 Resettable gates - Support for hot reload scenarios
• 📦 Zero dependencies - Lightweight and minimal
• 💪 TypeScript first - Full type support
• 🎯 Multiple wait modes - waitFor, waitForAny, waitForAll

Installation

npm install async-gate
# or
pnpm add async-gate
# or
yarn add async-gate

Usage

Basic Usage

import { AsyncGate } from "async-gate";

const gate = new AsyncGate();

// Register gates
gate.register("config").register("user");

// In your initialization code
async function loadConfig() {
  const config = await fetchConfig();
  gate.open("config", config);
}

// In your business logic
async function doSomething() {
  // Will wait until config is loaded
  const config = await gate.waitFor("config");
  console.log("Config loaded:", config);
}

Wait for Any Gate

gate.registerAll(["source1", "source2", "source3"]);

// Resolves when ANY gate opens
const { name, value } = await gate.waitForAny([
  "source1",
  "source2",
  "source3",
]);
console.log(`${name} loaded first:`, value);

Wait for All Gates

gate.registerAll(["config", "user", "resources"]);

// Resolves when ALL gates are open
const all = await gate.waitForAll(["config", "user", "resources"]);
// all = { config: {...}, user: {...}, resources: {...} }

With Timeout

try {
  const config = await gate.waitFor("config", 5000); // 5 second timeout
} catch (error) {
  console.error("Config loading timed out");
}

Reset Gate (for hot reload)

gate.open("config", initialConfig);

// Later, when config needs to reload
gate.reset("config");

// Now waitFor will wait again
reloadConfig().then((newConfig) => gate.open("config", newConfig));

API Reference

register(name: string): this

Register a new gate.

registerAll(names: string[]): this

Register multiple gates at once.

open<T>(name: string, value?: T): this

Open a gate and optionally pass a value. All waiters will be resolved.

waitFor<T>(name: string, timeout?: number): Promise<T>

Wait for a single gate to open. Returns the value passed to open().

waitForAny<T>(names: string[], timeout?: number): Promise<{name: string, value: T}>

Wait for any of the specified gates to open. Returns info about the first opened gate.

waitForAll<T>(names: string[], timeout?: number): Promise<Record<string, T>>

Wait for all specified gates to open. Returns an object with all values keyed by gate name.

reset(name: string): this

Reset a gate so it can be awaited again.

isOpen(name: string): boolean

Check if a gate is open.

has(name: string): boolean

Check if a gate is registered.

getValue<T>(name: string): T | undefined

Get the current value of a gate.

getStatus(): Record<string, GateStatus>

Get status of all gates.

getNames(): string[]

Get all registered gate names.

delete(name: string): boolean

Delete a gate.

destroy(): void

Destroy all gates.

License

MIT