Suggest an edit

Improve this article

Refine the answer for “What does once() do?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

## 1. What `once()` does

> The `.once(eventName, listener)` method registers an event handler
> that will run **only once**, then remove itself automatically.

After the event fires the first time, the listener **won't be called again**,
even if an event with the same name fires again.

### Example:

```javascript
const EventEmitter = require('events');
const emitter = new EventEmitter();

emitter.once('connect', () => {
  console.log('Connection established!');
});

emitter.emit('connect'); // fires
emitter.emit('connect'); // won't fire again
```

Output:

```javascript
Connection established!
```

## 2. What `on()` does

> The `.on(eventName, listener)` method registers a **permanent** event handler.
> It will be called **every time** the event fires.

### Example:

```javascript
emitter.on('data', () => {
  console.log('Data received');
});

emitter.emit('data'); // fires
emitter.emit('data'); // fires again
```

Output:

```javascript
Data received
Data received
```

## 3. The key difference between `once()` and `on()`

| Characteristic | `on()` | `once()` |
|---|---|---|
| Number of firings | Unlimited (every `emit()`) | Only once |
| Manual listener removal needed? | Yes, if needed (`off()`) | No, removed automatically |
| Typical use cases | Repeating events (e.g. `data`, `message`) | One-time events (`connect`, `ready`, `close`, `finish`) |
| Memory impact | Listener stays around | Listener is removed after the call |

## 4. Why `once()` is useful

1. **Avoids memory leaks**, the listener is removed automatically.
2. **Convenient for initialization**, e.g. a server's `ready` event or a stream's `open` event.
3. **Simplifies logic**, no need to call `.off()` manually.

## 5. A real-world example

For instance, on an HTTP server:

```javascript
const http = require('http');
const server = http.createServer();

server.once('listening', () => {
  console.log('Server started!');
});

server.listen(3000);
```

The `'listening'` event should happen **once**,
so `.once()` is a perfect fit.

## Summary

> `on()` adds a *permanent listener* that's called **every time** `emit()` fires.
> `once()` adds a *one-time listener* that's **removed after its first call**.
>
> Recommended usage:
>
> - use `on()` for repeating events (`data`, `message`, `update`);
> - use `once()` for one-time events (`connect`, `ready`, `close`, `init`).

Markdown · drag & drop images · ⌘B / ⌘I shortcuts338 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.