Sobre a Node.js®

Como uma execução de JavaScript assíncrona orientada a eventos, a Node.js foi desenhada para construir aplicações de rede escaláveis. No seguinte exemplo de "hello world", muitas conexões podem ser manipuladas simultaneamente. Em cada conexão, a função de retorno de chamada é disparada, mas se não existir trabalho a ser feito, a Node.js dormirá.

const { function createServer<Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse = typeof ServerResponse>(requestListener?: RequestListener<Request, Response>): Server<Request, Response> (+1 overload)Returns a new instance of 
{@link 
Server
}
.

The `requestListener` is a function which is automatically
added to the `'request'` event.

```js
import http from 'node:http';

// Create a local server to receive data from
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);
```

```js
import http from 'node:http';

// Create a local server to receive data from
const server = http.createServer();

// Listen to the request event
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);
```
@sincev0.1.13createServer } = var require: NodeJS.Require
(id: string) => anyUsed to import modules, `JSON`, and local files.
@sincev0.1.13require('node:http');

const const hostname: "127.0.0.1"hostname = '127.0.0.1';
const const port: 3000port = 3000;

const const server: Server<typeof IncomingMessage, typeof ServerResponse>server = createServer<typeof IncomingMessage, typeof ServerResponse>(requestListener?: RequestListener<typeof IncomingMessage, typeof ServerResponse> | undefined): Server<...> (+1 overload)Returns a new instance of 
{@link 
Server
}
.

The `requestListener` is a function which is automatically
added to the `'request'` event.

```js
import http from 'node:http';

// Create a local server to receive data from
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);
```

```js
import http from 'node:http';

// Create a local server to receive data from
const server = http.createServer();

// Listen to the request event
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);
```
@sincev0.1.13createServer((req: IncomingMessagereq, res: ServerResponse<IncomingMessage> & {
    req: IncomingMessage;
}res) => {
  res: ServerResponse<IncomingMessage> & {
    req: IncomingMessage;
}res.ServerResponse<Request extends IncomingMessage = IncomingMessage>.statusCode: numberWhen using implicit headers (not calling `response.writeHead()` explicitly),
this property controls the status code that will be sent to the client when
the headers get flushed.

```js
response.statusCode = 404;
```

After response header was sent to the client, this property indicates the
status code which was sent out.
@sincev0.4.0statusCode = 200;
  res: ServerResponse<IncomingMessage> & {
    req: IncomingMessage;
}res.OutgoingMessage<IncomingMessage>.setHeader(name: string, value: number | string | readonly string[]): ServerResponse<IncomingMessage> & {
    req: IncomingMessage;
}Sets a single header value. If the header already exists in the to-be-sent
headers, its value will be replaced. Use an array of strings to send multiple
headers with the same name.
@sincev0.4.0@paramname Header name@paramvalue Header valuesetHeader('Content-Type', 'text/plain');
  res: ServerResponse<IncomingMessage> & {
    req: IncomingMessage;
}res.Stream.Writable.end(chunk: any, cb?: () => void): ServerResponse<IncomingMessage> & {
    req: IncomingMessage;
} (+2 overloads)Calling the `writable.end()` method signals that no more data will be written
to the `Writable`. The optional `chunk` and `encoding` arguments allow one
final additional chunk of data to be written immediately before closing the
stream.

Calling the 
{@link 
write
}
 method after calling 
{@link 
end
}
 will raise an error.

```js
// Write 'hello, ' and then end with 'world!'.
import fs from 'node:fs';
const file = fs.createWriteStream('example.txt');
file.write('hello, ');
file.end('world!');
// Writing more now is not allowed!
```
@sincev0.9.4@paramchunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
{TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.@paramencoding The encoding if `chunk` is a string@paramcallback Callback for when the stream is finished.end('Hello World');
});

const server: Server<typeof IncomingMessage, typeof ServerResponse>server.Server.listen(port?: number, hostname?: string, listeningListener?: () => void): Server<typeof IncomingMessage, typeof ServerResponse> (+8 overloads)Start a server listening for connections. A `net.Server` can be a TCP or
an `IPC` server depending on what it listens to.

Possible signatures:

* `server.listen(handle[, backlog][, callback])`
* `server.listen(options[, callback])`
* `server.listen(path[, backlog][, callback])` for `IPC` servers
* `server.listen([port[, host[, backlog]]][, callback])` for TCP servers

This function is asynchronous. When the server starts listening, the `'listening'` event will be emitted. The last parameter `callback`will be added as a listener for the `'listening'`
event.

All `listen()` methods can take a `backlog` parameter to specify the maximum
length of the queue of pending connections. The actual length will be determined
by the OS through sysctl settings such as `tcp_max_syn_backlog` and `somaxconn` on Linux. The default value of this parameter is 511 (not 512).

All 
{@link 
Socket
}
 are set to `SO_REUSEADDR` (see [`socket(7)`](https://man7.org/linux/man-pages/man7/socket.7.html) for
details).

The `server.listen()` method can be called again if and only if there was an
error during the first `server.listen()` call or `server.close()` has been
called. Otherwise, an `ERR_SERVER_ALREADY_LISTEN` error will be thrown.

One of the most common errors raised when listening is `EADDRINUSE`.
This happens when another server is already listening on the requested`port`/`path`/`handle`. One way to handle this would be to retry
after a certain amount of time:

```js
server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.error('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});
```listen(const port: 3000port, const hostname: "127.0.0.1"hostname, () => {
  var console: ConsoleThe `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.

The module exports two specific components:

* A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstdout) and
[`process.stderr`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module.

_**Warning**_: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v22.x/api/process.html#a-note-on-process-io) for
more information.

Example using the global `console`:

```js
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
```

Example using the `Console` class:

```js
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
```
@see[source](https://github.com/nodejs/node/blob/v22.x/lib/console.js)console.Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)Prints to `stdout` with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html)
(the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)).

```js
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
```

See [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args) for more information.
@sincev0.1.100log(`Server running at http://${const hostname: "127.0.0.1"hostname}:${const port: 3000port}/`);
});

Isto contrasta com o modelo de concorrência mais comum atualmente, em que são utilizadas as linhas de processamento do sistema operativo. A conexão de rede baseada em linhas de processamento é relativamente ineficiente e muito difícil de usar. Além disto, os utilizadores da Node.js estão livres de preocupações com o bloqueio do processo, uma vez que não existem bloqueios. Quase nenhuma função na Node.js executa diretamente E/S, pelo que o processo nunca bloqueia, exceto quando as E/S são executadas usando métodos síncronos da biblioteca padrão da Node.js. Uma vez que nada bloqueia, os sistemas escaláveis são muito razoáveis de desenvolver na Node.js.

Se alguma desta linguagem não for familiar, existe um artigo completo sobre Bloqueio vs. Não Bloqueio.

A Node.js é semelhante em desenho a, e influenciada por, sistemas como a Máquina de Evento da Ruby e o Twisted da Python. A Node.js leva o modelo de evento um pouco mais longe. Esta apresenta um ciclo de eventos como uma construção de execução e não como uma biblioteca. Noutros sistemas, existe sempre uma chamada bloqueante para começar o ciclo de eventos. Tipicamente, o comportamento é definido através das funções de retorno de chamada no início de um programa, e no final um servidor é iniciado através duma chamada bloqueante como EventMachine::run(). Na Node.js, não existe essa chama que começa o ciclo de evento. A Node.js simplesmente entra no ciclo de eventos após executar o programa de entrada. A Node.js sai do ciclo de eventos quando não existir mais funções de retorno de chamada para executar. Este comportamento é semelhante ao interpretador de JavaScript do navegador — o ciclo de eventos é oculto ao utilizador.

O protocolo de transferência de hipertexto é um cidadão de primeira classe na Node.js, desenhado com fluxo contínuo e baixa latência em mente. Isto torna a Node.js adequada para a fundação duma biblioteca ou abstração da Web.

O fato da Node.js ter sido desenhada sem linhas de processamento não significa que não possamos tirar partido de vários núcleos no nosso ambiente. Os processos filhos podem ser gerados com o uso da nossa interface de programação de aplicação child_process.fork(), e estão desenhadas para serem fáceis de se comunicar. Construída sobre esta mesma interface está o módulo cluster, que permite-nos partilhar tomadas entre processos para permitir o balanceio de carga entre os nossos núcleos.