for...of - JavaScript

for...of
========

O loop **`for...of`** percorre objetos iterativos (en-US) (incluindo `Array`, `Map`, `Set`, o objeto arguments (en-US) e assim por diante), chamando uma função personalizada com instruções a serem executadas para o valor de cada objeto distinto.

Sintaxe
-------
```

for (variavel of iteravel) {
  declaração
}
```

`variável`

A cada iteração, um valor de uma propriedade diferente é atribuido à *variável*.

`iteravel`

Objeto cujos atributos serão iterados.

Exemplos
--------

### Iterando sobre um `Array`

```js
let iterable = [10, 20, 30];

for (let value of iterable) {
  console.log(value);
}
// 10
// 20
// 30
```

Ao invés de `let`, você pode usar `const` se você não for modificar a variável dentro do bloco.
```

let iterable = [10, 20, 30];

for (const value of iterable) {
  console.log(value);
}
// 10
// 20
// 30
```

### Iterando sobre uma `String`
```

let iterable = "boo";

for (let value of iterable) {
  console.log(value);
}
// "b"
// "o"
// "o"
```

### Iterando sobre uma `TypedArray` (en-US)
```

let iterable = new Uint8Array([0x00, 0xff]);

for (let value of iterable) {
  console.log(value);
}
// 0
// 255
```

### Iterando sobre um `Map`
```

let iterable = new Map([["a", 1], ["b", 2], ["c", 3]]);

for (let entry of iterable) {
  console.log(entry);
}
// [a, 1]
// [b, 2]
// [c, 3]

for (let [key, value] of iterable) {
  console.log(value);
}
// 1
// 2
// 3
```

### Iterando sobre um `Set`
```

let iterable = new Set([1, 1, 2, 2, 3, 3]);

for (let value of iterable) {
  console.log(value);
}
// 1
// 2
// 3
```

### Iterando sobre um objeto arguments (en-US)
```

(function() {
  for (let argument of arguments) {
    console.log(argument);
  }
})(1,2,3);

// 1
// 2
// 3
```

### Iterando sobre uma coleção do DOM

Iterar sobre uma coleção do DOM como `NodeList`: o seguinte exemplo adiciona uma classe `read` aos parágrafos que são descendentes diretos de uma tag `article`:
```

// Nota: Isso irá funcionar somente em plataformas que tem
// suporte ao NodeList.prototype[Symbol.iterator]
let articleParagraphs = document.querySelectorAll("article > p");

for (let paragraph of articleParagraphs) {
  paragraph.classList.add("read");
}
```

### Iterando sobre generators

Você pode também iterar sobre generators:
```

function* fibonacci() { // uma função geradora (generator)
  let [prev, curr] = [1, 1];
  while (true) {
    [prev, curr] = [curr, prev + curr];
    yield curr;
  }
}

for (let n of fibonacci()) {
  console.log(n);
  // Trunca a sequência em 1000
  if (n >= 1000) {
    break;
  }
}
```

#### Não reuse generators

Generators não devem ser re-usados, mesmo se o loop `for...of` for terminado precocemente, por exemplo através da palavra-chave `break`. Enquanto em um loop ativo, o generator é fechado e tentar iterar novamente sobre ele não produz (yield) nenhum resultado adicional. O Firefox ainda não implementou este comportamento (o generator pode ser reutilizado, violando o padrão do ES2015 (13.7.5.13, step 5m), mas isso irá mudar uma vez que o Erro do Firefox 1147371 for resolvido.
```

var gen = (function *(){
  yield 1;
  yield 2;
  yield 3;
})();
for (let o of gen) {
  console.log(o);
  break;  // Closes iterator
}

// O generator não deve ser reutilizado, o código a seguir não
// faz sentido!
for (let o of gen) {
  console.log(o); // Nunca será chamado.
}
```

### Iterando sobre outros objetos iteráveis

Você pode também iterar sobre um objeto que implementa explicitamente um protocolo iterável protocol:
```

var iterable = {
  [Symbol.iterator]() {
    return {
      i: 0,
      next() {
        if (this.i < 3) {
          return { value: this.i++, done: false };
        }
        return { value: undefined, done: true };
      }
    };
  }
};

for (var value of iterable) {
  console.log(value);
}
// 0
// 1
// 2
```

### Diferença entre `for...of` e `for...in`

O loop `for...in` irá iterar sobre todas as propriedades enumeráveis de um objeto.

A sintaxe do `for...of` é específica para **coleções**, ao invés de todos os objetos. Ela irá iterar desta maneira sobre os elementos de qualquer coleção que tiver uma propriedade `[Symbol.iterator]`.

O exemplo a seguir mostra a diferença entre um loop `for...of` e um loop `for...in`.
```

Object.prototype.objCustom = function () {};
Array.prototype.arrCustom = function () {};

let iterable = [3, 5, 7];
iterable.foo = "hello";

for (let i in iterable) {
  console.log(i); // escreve 0, 1, 2, "foo", "arrCustom", "objCustom"
}

for (let i of iterable) {
  console.log(i); // escreve 3, 5, 7
}
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-for-in-and-for-of-statements |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Consulte também
---------------

* for each...in - uma declaração similar, mas que itera entre os valores dos atributos de um objeto, ao invés dos seus nomes (obsoleto).
* `Array.prototype.forEach()`


continue - JavaScript

continue
========

A palavra chave **continue** termina a atual iteração do laço em que ele se encontra ou de um laço rotulado, e continua a execução deste laço com a próxima iteração.

Syntax
------
```

continue [rótulo];
```

`rótulo`

Identificador associado ao laço.

Descrição
---------

Diferentemente do `break`, o `continue` não termina a execução do laço completamente, em vez disso ele:

* Volta à condição, em um laço do tipo `while`.
* Volta à expressão, atualizando-a, em um laço do tipo `for`.

O `continue` pode incluir, opcionalmente, um rótulo que premite ao programa pular para a próxima iteração de um laço rotulado em vez de pular o loop em que ele se encontra. Neste caso, o `continue` necessita estar dentro deste laço rotulado.

Exemplos
--------

### Usando `continue` com `while`

O exemplo abaixo mostra um laço `while` que tem um `continue` que será executado quando o valor de `i` for 3. Assim, `n` terá os valores 1, 3, 7, e 12.

```js
var i = 0;
var n = 0;

while (i < 5) {
  i++;

  if (i === 3) {
    continue;
  }

  n += i;
}
```

### Usando o `continue` com um rótulo

No exemplo abaixo, um laço rotulado como `checkiandj` contém o laço rotulado `checkj`. Se o `continue` for alcançado, o programa continua a execução voltando ao topo do rótulo `checkj`. Cada vez que o `continue` for alcançado, `checkj` reiterará até sua condição for falsa. Quando retornar `false`, o restante de `checkiandj` será executado.

Se o `continue` tivesse o rótulo `checkiandj`, o programa iria continuar retornando a execução ao label `checkiandj`.

Veja também `label`.

```js
var i = 0;
var j = 8;

checkiandj: while (i < 4) {
  console.log("i: " + i);
  i += 1;

  checkj: while (j > 4) {
    console.log("j: " + j);
    j -= 1;

    if (j % 2 == 0) continue checkj;
    console.log(j + " is odd.");
  }
  console.log("i = " + i);
  console.log("j = " + j);
}
```

Output:

```js
"i: 0";

// start checkj
"j: 8";
"7 is odd.";
"j: 7";
"j: 6";
"5 is odd.";
"j: 5";
// end checkj

"i = 1";
"j = 4";

"i: 1";
"i = 2";
"j = 4";

"i: 2";
"i = 3";
"j = 4";

"i: 3";
"i = 4";
"j = 4";
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-continue-statement |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* `break`
* `label`


do...while - JavaScript

do...while
==========

A declaração **`do...while`** cria um laço que executa uma declaração até que o teste da condição for falsa (false). A condição é avaliada depois que o bloco de código é executado, resultando que uma declaração seja executada pelo menos uma vez.

Sintaxe
-------
```

do
   statement
while (condition);
```

`declarações`

A declaração é executada pelo menos uma vez e re-executada cada vez que a condição (`condition`) for avaliada como verdadeira (true). Para executar múltiplas declarações dentro do laço, use um `block` declaração (`{ ... }`) ao grupo dessas declarações.

`condição`

Uma expressão é validade depois de cada passagem pelo laço. Se a condição `(condition)` é avaliada como verdadeira (true) o bloco de código é executado novamente. Quando a condição `(condition)` é avaliada como falsa (false), o controle passa para a instrução seguinte ao laço **do...while**.

Exemplos
--------

### Usando `do...while`

No exemplo seguinte, o laço **do...while** soma pelo menos uma vez e executa novamente até `i` não ser menor que 5.

### Conteúdo HTML

```html
<div id="exemplo"></div>
```

### Conteúdo JavaScript

```js
var resultado = "";
var i = 0;
do {
  i += 1;
  resultado += i + " ";
} while (i < 5);
document.getElementById("exemplo").innerHTML = resultado;
```

### Resultado

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-do-while-statement |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* `while`
* `for`


function* - JavaScript

function\*
==========

A declaração **`function*`** (palavra chave `function` seguida de um asterisco) define uma *função geradora* (*generator function*), que retorna um objeto `Generator`.

Experimente
-----------

Você também pode definir funções geradoras usando o construtor `GeneratorFunction` (en-US) ou a sintaxe da expressão de uma função.

Sintaxe
-------
```

function* name([param[, param[, ... param]]]) {
   statements
}
```

`name`

O nome da função.

`param`

O nome do argumento que será passado á função. Uma função pode ter até 255 argumentos.

`statements`

As instruções que formam o corpo da função.

Descrição
---------

Geradores são funções cuja execução pode ser interrompida e posteriormente reconduzida. Seus contextos (de associações de variáveis) ficarão salvos entre cada recondução.

Geradores em JavaScript — especialmente quando combinados com *Promises* — são uma ferramenta muito poderosa para programação assíncrona, por mitigarem — se não eliminarem — problemas com callbacks, como o Callback Hell e Inversão de Controle. Funções `async` são fundamentadas nisso.

Chamar uma função geradora não executa seu conteúdo imediatamente; ao invés disso um objeto *iterator (en-US)* é retornado. Quando o método `next()` do objeto *iterator* é chamado, o conteúdo da função do gerador é executado até a primeira expressão `yield`, que especifica o valor a ser devolvido do *iterator* ou com `yield*` que delega para outra função geradora. O método `next()` retorna um objeto com uma propriedade `value` contendo o valor retornado e a propriedade *boolean*: `done` indicando se o gerador produziu seu último valor. Chamar o método `next()` com um argumento resumirá a execução da função geradora, substituindo a expressão `yield` onde a execução foi pausada com o argumento de `next()`.

Uma expressão `return` em um gerador, quando executada, fará com que o gerador termine (isto é, a propriedade `done` do objeto retornado será atribuído com o valor `true`). Se um valor foi retornado, este será usado como propriedade `value` do objeto retornado pelo gerador. Semelhantemente a uma expressão `return`, um erro lançado dentro do gerador o terminará — a não ser que tratado no corpo do gerador. Quando um gerador estiver terminado, chamadas `next` subsequentes não executarão nenhum código do gerador, retornarão simplesmente um objeto da seguinte forma: `{value: undefined, done: true}`.

Exemplos
--------

### Exemplo simples

```js
function\* idMaker() {
  var index = 0;
  while (true) yield index++;
}

var gen = idMaker();

console.log(gen.next().value); // 0
console.log(gen.next().value); // 1
console.log(gen.next().value); // 2
console.log(gen.next().value); // 3
// ...
```

### Exemplo com yield\*

```js
function\* outroGerador(i) {
  yield i + 1;
  yield i + 2;
  yield i + 3;
}

function\* gerador(i) {
  yield i;
  yield\* outroGerador(i);
  yield i + 10;
}

var gen = gerador(10);

console.log(gen.next().value); // 10
console.log(gen.next().value); // 11
console.log(gen.next().value); // 12
console.log(gen.next().value); // 13
console.log(gen.next().value); // 20
```

### Passando argumentos em geradores
```

function* logGenerator() {
  console.log(0);
  console.log(1, yield);
  console.log(2, yield);
  console.log(3, yield);
}

var gen = logGenerator();

// a primeira chamada next é executada desde o início da função
// até a primeira declaração yield
gen.next();             // 0
gen.next('pretzel');    // 1 pretzel
gen.next('california'); // 2 california
gen.next('mayonnaise'); // 3 mayonnaise
```

### Declaração de retono em um gerador
```

function* yieldAndReturn() {
  yield "Y";
  return "R";
  yield "unreachable";
}

var gen = yieldAndReturn()
console.log(gen.next()); // { value: "Y", done: false }
console.log(gen.next()); // { value: "R", done: true }
console.log(gen.next()); // { value: undefined, done: true }
```

### Geradores não possuem construtor
```

function* f() {}
var obj = new f; // lança o TypeError: f não é construtor
```

### Gerador definido em uma expressão
```

const foo = function* () {
  yield 10;
  yield 20;
};

const bar = foo();
console.log(bar.next()); // {value: 10, done: false}
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-generator-function-definitions |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Observações específicas Firefox
-------------------------------

#### Generators e iterators no Firefox em versões anteriores a 26

Versões mais antigas do Firefox implementam uma versão antiga da proposta de *generators*. Na versão mais antiga, *generators* foram intruídos a usarem a palavra chave `function`(sem um asterísco) dentre outras diferenças.

#### O retorno do objeto `IteratorResult` ao invés de um throw

Iniciando com Gecko 29, o *generator* finalizado não lança mais um `TypeError` "generator has already finished". Ao invés disso, ele retorna um objeto `IteratorResult`, como por exemplo `{ value: undefined, done: true }` (Erro do Firefox 958951).

Veja também
-----------

* `function* expression`
* `GeneratorFunction` (en-US) object
* The Iterator protocol (en-US)
* `yield`
* `yield*`
* `Function` object
* `function declaration`
* `function expression`
* `Functions and function scope` (en-US)
* Outras fontes na web:
    + Regenerator um ES6 generator que compila para ES5
    + Forbes Lindesay: Promises and Generators: control flow utopia — JSConf EU 2013
    + Hemanth.HM: The New gen of \*gen(){}
    + Task.js


throw - JavaScript

throw
=====

A **declaração** **`throw`** lança uma exceção definida pelo usuário. A execução da função atual vai parar (as instruções após o `throw` não serão executadas), e o controle será passado para o primeiro bloco `catch` na pilha de chamadas. Se nenhum bloco `catch` existe entre as funções "chamadoras", o programa vai terminar.

Sintaxe
-------
```

throw expressão;
```

`expressão`

A expressão a ser lançada.

Descrição
---------

Use a instrução `throw` para lançar uma exceção. Quando você lança uma exceção, `expressão` especifica o valor da exceção. Cada uma das intruções a seguir lança uma exceção:

```js
throw "Erro2"; // gera uma exceção com um valor string
throw 42; // gera uma exceção com o valor 42
throw true; // gera uma exceção com o valor true
```

Note também que a instrução `throw` é afetada pela inserção automática de ponto-e-vírgula (ASI) como nenhum terminador de linha entre a palavra `throw` e a expressão é permitido.

Exemplos
--------

### Lançando um objeto

Você pode especificar um objeto quando você lança uma exceção. Você pode então referenciar as propriedades do objeto no bloco `catch`. O exemplo a seguir cria um objeto do tipo `UserException` e o usa na intrução `throw`.

```js
function UserException(message) {
  this.message = message;
  this.name = "UserException";
}
function getMonthName(mo) {
  mo = mo - 1; // Ajusta o número do mês para index de array (1=Jan, 12=Dec)
  var months = [
    "Jan",
    "Feb",
    "Mar",
    "Apr",
    "May",
    "Jun",
    "Jul",
    "Aug",
    "Sep",
    "Oct",
    "Nov",
    "Dec",
  ];
  if (months[mo] !== undefined) {
    return months[mo];
  } else {
    throw new UserException("InvalidMonthNo");
  }
}

try {
  // statements to try
  var myMonth = 15; // 15 is out of bound to raise the exception
  monthName = getMonthName(myMonth);
} catch (e) {
  monthName = "unknown";
  logMyErrors(e.message, e.name); // pass exception object to err handler
}
```

### Outro exemplo lançando um objeto

O exemplo a seguir testa uma string de entrada para um cep dos Estados Unidos. Se o CEP utiliza um formato inválido, a intrução throw lança uma exceção através da criação de um objeto do tipo `ZipCodeFormatException`.

```js
/\*
 \* Cria um objeto ZipCode.
 \*
 \* Formatos aceitos para o CEP são:
 \* 12345
 \* 12345-6789
 \* 123456789
 \* 12345 6789
 \*
 \* Se o argumento passado para o construtor do ZipCode não atende
 \* a um desses padrões uma exceção é lançada.
 \*/

function ZipCode(zip) {
  zip = new String(zip);
  pattern = /[0-9]{5}([- ]?[0-9]{4})?/;
  if (pattern.test(zip)) {
    // o valor do CEP será a primeira combinação na string
    this.value = zip.match(pattern)[0];
    this.valueOf = function () {
      return this.value;
    };
    this.toString = function () {
      return String(this.value);
    };
  } else {
    throw new ZipCodeFormatException(zip);
  }
}

function ZipCodeFormatException(value) {
  this.value = value;
  this.message = "does not conform to the expected format for a zip code";
  this.toString = function () {
    return this.value + this.message;
  };
}

/\*
 \* Isso poderia estar em um script que valida dados de endereços
 \* para os endereços dos Estados Unidos.
 \*/

const ZIPCODE\_INVALID = -1;
const ZIPCODE\_UNKNOWN\_ERROR = -2;

function verifyZipCode(z) {
  try {
    z = new ZipCode(z);
  } catch (e) {
    if (e instanceof ZipCodeFormatException) {
      return ZIPCODE\_INVALID;
    } else {
      return ZIPCODE\_UNKNOWN\_ERROR;
    }
  }
  return z;
}

a = verifyZipCode(95060); // retorna 95060
b = verifyZipCode(9560); // retorna -1
c = verifyZipCode("a"); // retorna -1
d = verifyZipCode("95060"); // retorna 95060
e = verifyZipCode("95060 1234"); // retorna 95060 1234
```

### Relançando uma exceção

Você pode usar `throw` para relançar uma exceção após você pegá-la. O exemplo a seguir pega uma exceção com um valor numérico e a relança se o valor for maior que 50. A exceção relançada propaga para a função encapsuladora ou para o nível superior para que o usuário a veja.

```js
try {
  throw n; // lança uma exceção com um valor numérico
} catch (e) {
  if (e <= 50) {
    // instruções para tratar exceções 1-50
  } else {
    // não pode tratar esta exceção então relança
    throw e;
  }
}
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-throw-statement |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* `try...catch`


static - JavaScript

static
======

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2017.

* Learn more
* See full compatibility
* Report feedback
A palavra chave **static** define um método estático para a classe. Métodos estáticos não são chamados na instâncias da classe. Em vez disso, eles são chamados na própria classe. Geralmente, são funções utilitárias, como funções para criar ou clonar objetos.

Sintaxe
-------
```

static nomeDoMetodo() { ... }
```

Descrição
---------

Chamadas a métodos estáticos são feitas diretamente na classe e não podem ser feitas em uma instância da classe. Métodos estáticos são comumente utilizados como funções utilitárias.

Chamada de métodos estáticos
----------------------------

### De outro método estático

Para chamar um método estático dentro de outro método estático da mesma classe, podemos utilizar a palavra reservada `this`.

```js
class ChamadaDoMetodoEstatico {
  static metodoEstatico() {
    return "O método estático foi chamado";
  }
  static outroMetodoEstatico() {
    return this.metodoEstatico() + " de outro método estático";
  }
}
ChamadaDoMetodoEstatico.metodoEstatico();
// 'O método estático foi chamado'

ChamadaDoMetodoEstatico.outroMetodoEstatico();
// 'O método estático foi chamado de outro método estático'
```

### De outro construtor e outros métodos

Métodos estáticos não são diretamente acessíveis utilizando-se `this` a partir de métodos não estáticos. É necessário chamá-los usando o nome da classe:

```js
nomeDaClasse.nomeDoMetodoEstatico();
```

ou chamando o método como uma propriedade do construtor:

```js
this.constructor.nomeDoMetodoEstatico().
```

```js
class ChamadaDoMetodoEstatico {
  constructor() {
    console.log(ChamadaDoMetodoEstatico.MetodoEstatico());
    // 'O método estático foi chamado.'

    console.log(this.constructor.MetodoEstatico());
    // 'O método estático foi chamado.'
  }

  static MetodoEstatico() {
    return "O método estático foi chamado.";
  }
}
```

Exemplos
--------

O exemplo a seguir demonstra várias coisas. Ele mostra como um método estático é implementado em uma classe e como uma classe com um membro estático pode virar uma subclasse. Por fim, ele mostra como um método estático pode e não pode ser chamado.

```js
class Tripple {
  static tripple(n) {
    n = n | 1;
    return n \* 3;
  }
}

class BiggerTripple extends Tripple {
  static tripple(n) {
    return super.tripple(n) \* super.tripple(n);
  }
}

console.log(Tripple.tripple());
console.log(Tripple.tripple(6));
console.log(BiggerTripple.tripple(3));
var tp = new Tripple();
console.log(tp.tripple()); //Logs 'tp.tripple is not a function'.
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-class-definitions |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* `class` expression
* `class` declaration
* Classes


extends - JavaScript

extends
=======

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2017.

* Learn more
* See full compatibility
* Report feedback
A palavra chave **`extends`** é usada em uma class declarations ou class expressions para criar uma classe filha de outra classe.

Sintaxe
-------
```

class ChildClass extends ParentClass { ... }
```

Descrição
---------

A palavra chave extends pode ser usada para tanto classes filhas quanto objetos filhos pré-construidos.

O `.prototype` da extensão deve ser um `Object` ou `null`.

Exemplos
--------

### Usando `extends`

O primeiro exemplo cria uma classe chamada `Square` a partir de uma classe chamada `Polygon`. Este exemplo foi extraido deste live demo (source).

```js
class Square extends Polygon {
  constructor(length) {
    // Here, it calls the parent class' constructor with lengths
    // provided for the Polygon's width and height
    super(length, length);
    // Nota: In derived classes, super() must be called before you
    // can use 'this'. Leaving this out will cause a reference error.
    this.name = "Square";
  }

  get area() {
    return this.height \* this.width;
  }

  set area(value) {
    this.area = value;
  }
}
```

### Usando `extends` com objetos pré-construidos

Este exemplo extende o objeto pré-construido `Date`. Este exemplo foi extraido deste live demo (source).

```js
class myDate extends Date {
  constructor() {
    super();
  }

  getFormattedDate() {
    var months = [
      "Jan",
      "Feb",
      "Mar",
      "Apr",
      "May",
      "Jun",
      "Jul",
      "Aug",
      "Sep",
      "Oct",
      "Nov",
      "Dec",
    ];
    return (
      this.getDate() + "-" + months[this.getMonth()] + "-" + this.getFullYear()
    );
  }
}
```

### Estendendo `null`

Estender de `null` funciona como em uma classe normal, exceto que o objeto prototype não herda de `Object.prototype` (en-US).

```js
class nullExtends extends null {
  constructor() {}
}

Object.getPrototypeOf(nullExtends); // Function.prototype
Object.getPrototypeOf(nullExtends.prototype); // null
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-class-definitions |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Ver também
----------

* Classes
* super


constructor - JavaScript

constructor
===========

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2017.

* Learn more
* See full compatibility
* Report feedback
O construtor é um método especial para criar e inicializar um objeto criado a partir de uma classe.

Sintaxe
-------
```

constructor([argumentos]) { ... }
```

Descrição
---------

Apenas um método especial com o nome *constructor* pode existir em uma classe. O erro `SyntaxError` (en-US) será mostrado se a classe contiver mais de um método *constructor.*

Um construtor pode usar a palavra reservada *super* para se referir ao construtor da classe pai (**superior**).

Um construtor padrão será usado se você não especificá-lo\*.\*

Exemplos
--------

### Usando o método *constructor*

O trecho de código foi fornecido por exemplo de classes (live demo).

```js
class Quadrado extends Poligono {
  constructor(comprimento) {
    // super chama o construtor da classe pai que vai atribuir comprimento para
    // os atributos comprimento e altura herdados pela nossa classe filha Quadrado
    super(comprimento, comprimento);
    // Nas classes filhas, super() deve ser chamado antes de usar o this. Sem ele
    // vai ocorrer um erro de referência. O this agora se refere a classe filha Quadrado
    this.nome = "Quadrado";
  }

  // os atributos a seguir são herdados da classe pai Poligono: altura, comprimento e area.

  get area() {
    return this.altura \* this.comprimento;
  }

  set area(valor) {
    this.area = valor;
  }
}
```

### Construtores padrão (*constructors*)

Um construtor padrão será usado pela classe caso nenhum seja especificado. Para as classes de base o construtor padrão é:

```js
constructor() {} //construtor criado por padrão
```

Para as classes filhas o construtor padrão é:

```js
constructor(...args) {
  super(...args);
}
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-static-semantics-constructormethod |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* super()
* `class` expressão
* `class` declaração
* Classes


EvalError - JavaScript

EvalError
=========

O Objeto **`EvalError`** indica um erro em relação a função global `eval()`. Esta exceção não é mais lançada pelo JavaScript, no entanto, o objeto `EvalError` ainda permanece compatível.

Sintaxe
-------
```

new EvalError([message[, fileName[, lineNumber]]])
```

### Parâmetros

`message`

Opcional. Descrição do erro legível para humanos

`fileName`
Non-standard

Opcional. O nome do arquivo que contém o código que causa a exceção

`lineNumber`
Non-standard

Opcional. O número da linha do código que causa a exceção

Propriedades
------------

`EvalError.prototype` (en-US)

Permite a adição de propriedades para um objeto `EvalError`.

Métodos
-------

O global `EvalError` não contém métodos próprios, no entando, ele irá herdar alguns métodos através da cadeia de protótipos.

`Instâncias do EvalError`
-------------------------

### Propriedades

{{page('/pt-BR/docs/Web/JavaScript/Reference/Global\_Objects/EvalError/prototype', 'Properties')}}### Métodos

{{page('/pt-BR/docs/Web/JavaScript/Reference/Global\_Objects/EvalError/prototype', 'Methods')}}Exemplos
--------

`EvalError` não é usado na especificação ECMAScript e deste modo não será lançado pelo tempo de execução. No entando, o objeto em si permanece para compatibilidade com versões anteriores da especificação.

### Criando um `EvalError`

```js
try {
  throw new EvalError("Hello", "someFile.js", 10);
} catch (e) {
  console.log(e instanceof EvalError); // true
  console.log(e.message); // "Hello"
  console.log(e.name); // "EvalError"
  console.log(e.fileName); // "someFile.js"
  console.log(e.lineNumber); // 10
  console.log(e.columnNumber); // 0
  console.log(e.stack); // "@Scratchpad/2:2:9\n"
}
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-native-error-types-used-in-this-standard-evalerror |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* `Error`
* `EvalError.prototype` (en-US)
* `eval()`


String - JavaScript

String
======

Sumário
-------

O objeto global **`String`** é um construtor para **strings,** ou uma sequência de caracteres.

Sintaxe
-------

As formas literais de declaração de *String* são:
```

'string text'
"string text"
"中文 español English हिन्दी العربية português বাংলা русский 日本語 ਪੰਜਾਬੀ 한국어"
```

Além da forma regular, de caracteres de impressão, caracteres especiais podem ser codificados usando a *escape notation* (notação com barra invertida):

| Codigo | Saida |
| --- | --- |
| \0 | o caractere NULL |
| \' | aspas simples |
| \" | aspas duplas |
| \\ | barra invertida |
| \n | nova linha |
| \r | carriage return |
| \v | tab vertical |
| \t | tab |
| \b | backspace |
| \f | form feed |
| \uXXXX | unicode codepoint |
| \xXX | the Latin-1 character |

Ou, usando o objeto global `String` diretamente:
```

String(thing)
new String(thing)
```

### Parâmetros

`thing`

Qualquer coisa a ser convertida para uma string.

Descrição
---------

Strings são úteis para guardar dados que podem ser representados em forma de texto. Uma das operações mais usadas nas **strings** é checar seu `tamanho`, para construir e concatená-las usando os operadores + e +=, checando pela existência ou posição de *substrings* com o método `indexOf` , ou extrair *substrings* com o método `substring`.

### Acesso à caractere

Há duas maneiras de acessar um caractere individual em uma string. A primeira é o método `charAt`:

```js
return "cat".charAt(1); // returns "a"
```

A outra maneira (introduzido no ECMAScript 5) consiste em tratar a string como um objeto Array-like, onde os caráteres individuais correspondem a um índice numérico:

```js
return "cat"[1]; // returns "a"
```

Para acesso de caracteres usando uma notação de colchetes, tentando deletar ou designar um valor a estas propriedades não haverá sucesso. As propriedades envolvidas não são nem escritas ou configuráveis. (Veja `Object.defineProperty` para mais informações.)

### Comparando strings

Desenvolvedores de C têm a função strcmp() para comparar strings. No JavaScript, basta usar o operador maior que e menor que (en-US):

```js
var a = "a";
var b = "b";
if (a < b)
  // verdadeiro
  print(a + " é menor que " + b);
else if (a > b) print(a + " é maior que " + b);
else print(a + " e " + b + " são iguais.");
```

Um resultado similar pode ser alcançado usando o método `localeCompare` herdado pelas instâncias de `String`.

### Distinção entre String primitiva e objetos String

Note que o JavaScript distingue entre objetos String e valores de string primitivas. (O mesmo é válido para `Boolean` e `Numbers`.)

Strings literais (definidas por aspas duplas ou aspas simples) e strings retornadas da chamada da função String fora do contexto de uma função construtora (sem o uso da palavra chave new) são strings primitivas. O JavaScript converte automaticamente strings primitivas para objetos do tipo String, por isso é possível utilizar os métodos do objeto String através de strings primitivas. Em contextos onde um método é invocado de uma string primitiva ou uma propriedade é procurada, o JavaScript irá criar um objeto com a string primitiva e executar o método ou acessar a propriedade procurada.

```js
var s_prim = "foo";
var s_obj = new String(s_prim);

console.log(typeof s_prim); // Loga "string"
console.log(typeof s_obj); // Loga "object"
```

String primitivas e objetos `String` também dão resultados diferentes quando usado `eval`. Primitivas passadas para `eval` são tratadas como código fonte; Objetos `String` são tratados como todos os outros objetos são, retornando o objeto. Por exemplo:

```js
s1 = "2 + 2"; // cria uma string primitiva
s2 = new String("2 + 2"); // cria um objeto de String
console.log(eval(s1)); // retorna o número 4
console.log(eval(s2)); // retorna a string "2 + 2"
```

Por estas razões, o código pode quebrar quando encontra objetos `String` quando espera na verdade uma string primitiva, apesar de que geralmente autores não precisam se preocupar com a distinção.

Um objeto `String` pode ser convertido sempre para sua contraparte primitiva com o método `valueOf`.

```js
console.log(eval(s2.valueOf())); // retorna o número 4
```

**Nota:** Para uma outra possível abordagem para strings em JavaScript, favor ler o artigo sobre `StringView` – a C-like representation of strings based on typed arrays.

Propriedades
------------

`String.prototype` (en-US)

Permite a adição de propriedades a um objeto String.

Métodos
-------

`String.fromCharCode()`

Retorna uma string criada usando a sequência especificada de valores Unicode.

`String.fromCodePoint()`
Experimental

Retorna uma string criada usando a sequência especificada de posições de código.

`Métodos genéricos de Strings`
------------------------------

Métodos de instância `String` também estão disponíveis no Firefox a partir de JavaScript 1.6 (embora não faça parte dos padrões ECMAScript) no objeto String para aplicar métodos String a qualquer objeto:

```js
var num = 15;
alert(String.replace(num, /5/, "2"));
```

Genéricos também estão disponíveis em métodos `Array`.

O seguinte é uma implementação para fornecer suporte a navegadores sem suporte:

```js
/\*globals define\*/
// Assume que todos os métodos de instância String fornecidos
// já presentes (podem ser usadas implementações para este se não disponível)
(function () {
  "use strict";

  var i,
    // Nós também poderíamos construir o array de métodos com os seguintes,
    // mas o método getOwnPropertyNames() não é implementável:
    // Object.getOwnPropertyNames(String).filter(function (methodName)
    // {return typeof String[methodName] === 'function'});
    methods = [
      "quote",
      "substring",
      "toLowerCase",
      "toUpperCase",
      "charAt",
      "charCodeAt",
      "indexOf",
      "lastIndexOf",
      "startsWith",
      "endsWith",
      "trim",
      "trimLeft",
      "trimRight",
      "toLocaleLowerCase",
      "toLocaleUpperCase",
      "localeCompare",
      "match",
      "search",
      "replace",
      "split",
      "substr",
      "concat",
      "slice",
    ],
    methodCount = methods.length,
    assignStringGeneric = function (methodName) {
      var method = String.prototype[methodName];
      String[methodName] = function (arg1) {
        return method.apply(arg1, Array.prototype.slice.call(arguments, 1));
      };
    };

  for (i = 0; i < methodCount; i++) {
    assignStringGeneric(methods[i]);
  }
})();
```

Instâncias de `String`
----------------------

### Propriedades

{{page('/pt-BR/docs/Web/JavaScript/Reference/Global\_Objects/String/prototype', 'Propriedades')}}### Métodos

#### Métodos não relacionados ao HTML

{{page('/pt-BR/docs/Web/JavaScript/Reference/Global\_Objects/String/prototype', 'Métodos\_não\_relacionados\_ao\_HTML')}}
#### Métodos de envoltório HTML

{{page('/pt-BR/docs/Web/JavaScript/Reference/Global\_Objects/String/prototype', 'Métodos\_de\_envoltório\_HTML')}}Exemplos
--------

### Conversão de String

É possível usar `String` como uma alternativa "mais segura" `toString`, como embora normalmente ainda chama o `toString` subjacente, também funciona para `null` e `undefined`. Por exemplo:

```js
var outputStrings = [];
for (let i = 0, n = inputValues.length; i < n; ++i) {
  outputStrings.push(String(inputValues[i]));
}
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-string-objects |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* DOMString
* `StringView` – a C-like representation of strings based on typed arrays
* Binary strings


decodeURI() - JavaScript

decodeURI()
===========

A função **`decodeURI()`** decodifica um Uniform Resource Identifier (URI) criado anteriormente por `encodeURI()` ou por uma rotina semelhante.

Experimente
-----------

Sintaxe
-------
```

decodeURI(encodedURI)
```

### Parâmetros

`encodedURI`

Um identificador de recurso uniforme codificado completo.

### Valor retornado

Uma nova string representando a versão não codificada do URI (Uniform Resource Identifier) codificado fornecido.

### Exceções

Lança uma exceção `URIError` (en-US) ("sequência de URI malformada") quando o `encodedURI` contém sequências de caracteres inválidos.

Descrição
---------

Substitui cada sequência de escape no URI codificado pelo caractere que ele representa, mas não decodifica sequências de escape que não poderiam ter sido introduzidas por `encodeURI`. O caractere "`#`" não é decodificado a partir de sequência de escape.

Exemplos
--------

### Decodificando uma URL Cyrillic

```js
decodeURI(
  "https://developer.mozilla.org/ru/docs/JavaScript\_%D1%88%D0%B5%D0%BB%D0%BB%D1%8B",
);
// "https://developer.mozilla.org/ru/docs/JavaScript\_шеллы"
```

### Captura de erros
```

try {
  var a = decodeURI('%E0%A4%A');
} catch(e) {
  console.error(e);
}

// URIError: sequência de URI malformada
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-decodeuri-encodeduri |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Ver também
----------

* `decodeURIComponent()`
* `encodeURI()`
* `encodeURIComponent()`


ReferenceError - JavaScript

ReferenceError
==============

O objeto **`ReferenceError`** representa um erro quando uma variável não existente é referenciada.

Sintaxe
-------
```

new ReferenceError([message[, fileName[, lineNumber]]])
```

### Parâmetros

`message`

Opcional. Descrição legível do erro.

`fileName`
Non-standard

Opcional. O nome do arquivo contendo o código que causou a excessão.

`lineNumber`
Non-standard

Opcional. O número da linha do código que causou a excessão.

Descrição
---------

O `ReferenceError` acontece quando é feita uma tentativa de referenciar uma variável que não foi declarada.

Propriedades
------------

`ReferenceError.prototype` (en-US)

Permite a inclusão de propriedades em um objeto `ReferenceError`.

Métodos
-------

O `ReferenceError` não contém métodos próprios, porém, ele herda alguns métodos através da cadeia de protótipos.

Instâncias do `ReferenceError`
------------------------------

### Propriedades

{{page('/pt-BR/docs/Web/JavaScript/Reference/Global\_Objects/ReferenceError/prototype', 'Properties')}}### Métodos

{{page('/pt-BR/docs/Web/JavaScript/Reference/Global\_Objects/ReferenceError/prototype', 'Methods')}}Exemplos
--------

### Capturando um `ReferenceError`

```js
try {
  var a = variavelNaoDefinida;
} catch (e) {
  console.log(e instanceof ReferenceError); // true
  console.log(e.message); // "variavelNaoDefinida não está definida"
  console.log(e.name); // "ReferenceError"
  console.log(e.fileName); // "Scratchpad/1"
  console.log(e.lineNumber); // 2
  console.log(e.columnNumber); // 6
  console.log(e.stack); // "@Scratchpad/2:2:7\n"
}
```

### Criando um `ReferenceError`

```js
try {
  throw new ReferenceError("Olá", "arquivoQualquer.js", 10);
} catch (e) {
  console.log(e instanceof ReferenceError); // true
  console.log(e.message); // "Olá"
  console.log(e.name); // "ReferenceError"
  console.log(e.fileName); // "arquivoQualquer.js"
  console.log(e.lineNumber); // 10
  console.log(e.columnNumber); // 0
  console.log(e.stack); // "@Scratchpad/2:2:9\n"
}
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-native-error-types-used-in-this-standard-referenceerror |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* `Error`
* `ReferenceError.prototype` (en-US)


ArrayBuffer - JavaScript

ArrayBuffer
===========

O objeto **`ArrayBuffer`** é um tipo de dado usado para representar um genérico, buffer de dados binários de tamanho fixo. Você não pode manipular diretamente os conteúdos de um `ArrayBuffer`; em vez disso, você cria um objeto `ArrayBufferView` que representa o buffer em um formato específico, e usa para ler e escrever os conteúdos do buffer.

Experimente
-----------

Syntax
------
```

new ArrayBuffer(length)
```

### Parameters

`length`

The size, in bytes, of the array buffer to create.

### Return value

A new `ArrayBuffer` object of the specified size. Its contents are initialized to 0.

### Exceptions

A `RangeError` (en-US) is thrown if the `length` is larger than `Number.MAX_SAFE_INTEGER` (>= 2 \*\* 53) or negative.

Description
-----------

The `ArrayBuffer` constructor creates a new `ArrayBuffer` of the given length in bytes.

### Getting an array buffer from existing data

* From a Base64 string (en-US)
* From a local file
Properties
----------

`ArrayBuffer.length`

The `ArrayBuffer` constructor's length property whose value is 1.

`get ArrayBuffer[@@species]` (en-US)

The constructor function that is used to create derived objects.

`ArrayBuffer.prototype` (en-US)

Allows the addition of properties to all `ArrayBuffer` objects.

Methods
-------

`ArrayBuffer.isView(arg)` (en-US)

Returns `true` if `arg` is one of the ArrayBuffer views, such as typed array objects (en-US) or a `DataView`. Returns `false` otherwise.

`ArrayBuffer.transfer(oldBuffer [, newByteLength])` (en-US)
Experimental

Returns a new `ArrayBuffer` whose contents are taken from the `oldBuffer`'s data and then is either truncated or zero-extended by `newByteLength`.

Instances
---------

All `ArrayBuffer` instances inherit from `ArrayBuffer.prototype` (en-US).

### Properties

{{page('en-US/Web/JavaScript/Reference/Global\_Objects/ArrayBuffer/prototype','Properties')}}### Methods

{{page('en-US/Web/JavaScript/Reference/Global\_Objects/ArrayBuffer/prototype','Methods')}}

`ArrayBuffer.slice()` (en-US)
Non-standard

Has the same functionality as `ArrayBuffer.prototype.slice()` (en-US).

Exemplo
-------

In this example, we create a 8-byte buffer with a `Int32Array` (en-US) view referring to the buffer:
```

var buffer = new ArrayBuffer(8);
var view   = new Int32Array(buffer);
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-arraybuffer-objects |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Compatibility notes
-------------------

Starting with ECMAScript 2015, `ArrayBuffer` constructors require to be constructed with a `new` operator. Calling an `ArrayBuffer` constructor as a function without `new`, will throw a `TypeError` from now on.

```js
var dv = ArrayBuffer(10);
// TypedError: calling a builtin ArrayBuffer constructor
// without new is forbidden
```

```js
var dv = new ArrayBuffer(10);
```

Veja também
-----------

* JavaScript typed arrays
* `SharedArrayBuffer` (en-US)


WeakMap - JavaScript

WeakMap
=======

Sumário
-------

 O objeto WeakMap é uma coleção de pares key/value na qual as chaves são fracamente referenciadas.
 As chaves **devem** ser objetos, e os valores podem ser de tipos arbitrários.

Você pode descobrir mais sobre `WeakMap`s na seção Objeto WeakMap.

Sintaxe
-------
```

new WeakMap([iterable])
```

### Parâmetros

`iterable`

Iterable é um Array ou outro objeto iterável cujos elementos são pares key-value (Arrays de dois elementos). Cada par key-value será adicionados ao novo `WeakMap`. `null` é tratado como `undefined`.

Descrição
---------

### Por quê WeakMap?

Um programador JavaScript experiente vai notar que esta API pode ser implementada em JavaScript com dois arrays (um para chaves, um para valores) compartilhado pelos 4 métodos da API. Tal implementação teria duas principais incoveniências. A primeira é uma busca O(n) (n sendo o número de chaves no map). A segunda é o problema de memory leak. Com maps escritos manualmente, o array de chaves guardaria referências para objetos chave, prevenindo-os de serem coletados pelo Garbage Collector. Nos WeakMaps nativos, referências aos objetos chave são segurados de modo "fraco", o que significa que eles não previnem a coleção pelo GC no caso de não haver nenhuma outra referência ao objeto.

Por conta das referências serem fracas, chaves de `WeakMap` não são enumeráveis (i.e. não existe um método que dá a você uma lista de chaves). Se existisse tal método, a lista dependeria no estado da coleção do GC, introduzindo não-determinismo. Se você quiser ter uma lista de chaves, deve usar um `Map`.

Construtor
----------

`WeakMap()` (en-US)

Cria um novo objeto `WeakMap`.

Métodos de instância
--------------------

`WeakMap.prototype.delete(key)`

Remove qualquer valor associado à chave(`key`). `WeakMap.prototype.has(key)` retornará `false` depois.

`WeakMap.prototype.get(key)`

Retorna o valor associado à chave(`key`). Ou `undefined` se não houver.

`WeakMap.prototype.has(key)`

Retorna um boolean afirmando se um valor foi associado à chave(`key`) no objeto `WeakMap` ou não.

`WeakMap.prototype.set(key, value)`

Define o valor(`value`) da chave(`key`) no objeto `WeakMap`. Retorna o objeto `WeakMap`.

Exemplos
--------

### Exemplo: Usando `WeakMap`

```js
var wm1 = new WeakMap(),
  wm2 = new WeakMap(),
  wm3 = new WeakMap();
var o1 = {},
  o2 = function () {},
  o3 = window;

wm1.set(o1, 37);
wm1.set(o2, "azerty");
wm2.set(o1, o2); // um valor pode ser qualquer coisa, incluindo um objeto or uma função
wm2.set(o3, undefined);
wm2.set(wm1, wm2); // chaves e valores pode ser quaisquer objetos. Até mesmo WeakMaps!

wm1.get(o2); // "azerty"
wm2.get(o2); // undefined, pois não existe valor para o2 em wm2
wm2.get(o3); // undefined, pois este é o valor definido

wm1.has(o2); // true
wm2.has(o2); // false
wm2.has(o3); // true (mesmo se o valor armazenado for 'undefined')

wm3.set(o1, 37);
wm3.get(o1); // 37
wm3.clear();
wm3.get(o1); // undefined, pois wm3 foi 'limpado' e não há mais valor para o1.

wm1.has(o1); // true
wm1.delete(o1);
wm1.has(o1); // false
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-weakmap-objects |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* WeakMap bug at Mozilla
* Hiding Implementation Details with ECMAScript 2015 WeakMaps
* `Map`
* `Set`
* `WeakSet`


isFinite() - JavaScript

isFinite()
==========

`A função global isFinite()` determina se o valor transmitido é um número finito. Se necessário, o parâmetro é primeiro convertido a um número.

Sintaxe
-------
```

isFinite(testValue)
```

### Parametros

`testValue`

O valor a ser testado para a finitude

Descrição
---------

`isFinite` é uma função de nível superior é não é associada com qualquer objeto.

Você pode usar esta função para determinar se um número é um número finito. `A função isFinite` examina o número em seu argumento. Se o argumento é `NaN`, positivo infinito, ou negativo infinito, este método retorna `false`; de outra forma , ele retorna `true`.

Exemplos
--------

```js
isFinite(Infinity); // false
isFinite(NaN); // false
isFinite(-Infinity); // false

isFinite(0); // true
isFinite(2e64); // true
isFinite(null); // true

isFinite("0"); // true, teria sido false com o
// mais robusto Number.isFinite("0")
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-isfinite-number |

Browser compatibilidade
-----------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* `Number.isFinite()`
* `Number.NaN()`
* `Number.POSITIVE_INFINITY`
* `Number.NEGATIVE_INFINITY`


encodeURIComponent() - JavaScript

encodeURIComponent()
====================

O método **`encodeURIComponent()`** codifica uma URI (Identificador recurso uniforme) substituindo cada ocorrência de determinados caracteres por um, dois, três, ou quatro seqüências de escape que representam a codificação UTF-8 do caractere (só será quatro seqüências de escape para caracteres compostos por dois caracteres "substituto").

Syntaxe
-------
```

encodeURIComponent(str);
```

### Parâmetros

`str`

String. Uma sequência URI.

Descrição
---------

`encodeURIComponent` escapa todos os caracteres, exceto: alfabeto, dígitos decimais, `- _ . ! ~ * ' ( )`

Note-se que um`URIError` (en-US) será gerada se uma tentativas para codificar um substituto que não faz parte de um par de alta-baixa, por exemplo,

```js
// high-low par ok
console.log(encodeURIComponent("\uD800\uDFFF"));

// lone high surrogate throws "URIError: malformed URI sequence"
console.log(encodeURIComponent("\uD800"));

// lone low surrogate throws "URIError: malformed URI sequence"
console.log(encodeURIComponent("\uDFFF"));
```

Para previnir requisões inesperadas ao servidor, deve-se chamar `encodeURIComponent` ou qualquer parâmetro fornecido pelo usuário que será passado como parte da URI. Por exemplo, um usuário poderia digitar "`Thyme &time=again`" para uma variável `commentario`. Ao não usar `encodeURIComponent` nessa variável irá ser obetido `commentario=Thyme%20&time=again`. Note que o ampersa e o sinal de igual marcam um novo par de chave e valor. Então ao invés de ter um POST com a chave `commentario` igual a "`Thyme &time=again`", tem-se chaves em POST, uma igual a "`Thyme`" e outra (`time`) igual a `again`.

Para `application/x-www-form-urlencoded`, espaços são substituídos por '+', então pode-se querer seguir um `encodeURIComponent` substituição com uma substituição adicional de "%20" com "+".

Para ser mais rigoroso à aderência da RFC 3986 (qual reserva !, ', (, ), e \*), mesmo que esses caracteres não tenham usos formalizados de delimitação de URI, o seguinte pode ser usado com segurança:

```js
function ajustadoEncodeURIComponent(str) {
  return encodeURIComponent(str).replace(/[!'()\*]/g, function (c) {
    return "%" + c.charCodeAt(0).toString(16);
  });
}
```

Exemplos
--------

O exemplo seguinte provê o encoding especial requerido pelo UTF-8 nos parâmetros `Content-Disposition` e `Link` no cabeçalho de uma Response (e.g., UTF-8 filenames):

```js
var fileName = "my file(2).txt";
var header =
  "Content-Disposition: attachment; filename\*=UTF-8''" +
  encodeRFC5987ValueChars(fileName);

console.log(header);
// logs "Content-Disposition: attachment; filename\*=UTF-8''my%20file%282%29.txt"

function encodeRFC5987ValueChars(str) {
  return (
    encodeURIComponent(str)
      // Note that although RFC3986 reserves "!", RFC5987 does not,
      // so we do not need to escape it
      .replace(/['()]/g, escape) // i.e., %27 %28 %29
      .replace(/\\*/g, "%2A")
      // The following are not required for percent-encoding per RFC5987,
      // so we can allow for a little better readability over the wire: |`^
      .replace(/%(?:7C|60|5E)/g, unescape)
  );
}
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-encodeuricomponent-uricomponent |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* `decodeURI`
* `encodeURI`
* `decodeURIComponent`


InternalError - JavaScript

InternalError
=============

**Non-standard:** This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

O **objeto** **`InternalError`** indica que um erro ocorreu internamente na engine do JavaScript.

Isso ocorre quando algo é muito grande, por exemplo:

* "too many switch cases",
* "too many parentheses in regular expression",
* "array initializer too large",
* "too much recursion".
Construtor
----------

`InternalError()` (en-US)

Cria um um novo objeto `InternalError`.

Instance properties
-------------------

`InternalError.prototype.message`

Error message. Inherited from `Error`.

`InternalError.prototype.name`

Error name. Inherited from `Error`.

`InternalError.prototype.fileName` (en-US)

Path to file that raised this error. Inherited from `Error`.

`InternalError.prototype.lineNumber` (en-US)

Line number in file that raised this error. Inherited from `Error`.

`InternalError.prototype.columnNumber` (en-US)

Column number in line that raised this error. Inherited from `Error`.

`InternalError.prototype.stack` (en-US)

Stack trace. Inherited from `Error`.

Examples
--------

### Too much recursion

This recursive function runs 10 times, as per the exit condition.

```js
function loop(x) {
  if (x >= 10) {
    // "x >= 10" is the exit condition
    return;
  }
  // do stuff
  loop(x + 1); // the recursive call
}
loop(0);
```

Setting this condition to an extremely high value, won't work:

```js
function loop(x) {
  if (x >= 1000000000000) return;
  // do stuff
  loop(x + 1);
}
loop(0);

// InternalError: too much recursion
```

For more information, see InternalError: too much recursion.

Specifications
--------------

Not part of any standard.

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `Error`
* InternalError: too much recursion


unescape() - JavaScript

unescape()
==========

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

A função **unescape()** obsolta computa uma nova string na qual as sequencias hexadecimal são esquecidas com o caractere que representa. As sequências de escape podem ser introduzidas como funções `escape`. Porque a função 'unescape' está obsoleta, ao invez disso, use `decodeURI` ou `decodeURIComponent`.

**Nota:** Não use `unescape` para decodificar URIs, use `decodeURI` ao invez disso.

Syntax
------
```

unescape(str)
```

### Parâmetros

`str`

Uma string a ser decodificada.

### Valor retornado

Uma nova string na qual alguns caracteres tem que ser 'unescaped'.

Descrição
---------

A função `unescape` é uma propriedade do objeto global.

Exemplos
--------

```js
unescape("abc123"); // "abc123"
unescape("%E4%F6%FC"); // "äöü"
unescape("%u0107"); // "ć"
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-unescape-string |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* `decodeURI`
* `decodeURIComponent`
* `escape`


BigInt - JavaScript

BigInt
======

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2020.

* Learn more
* See full compatibility
* Report feedback
`BigInt` é um objeto nativo que fornece um modo de representar números inteiros maiores que 2^53, que é o maior número que o JavaScript consegue, com exatidão, representar com o tipo primitivo `Number`.

Sintaxe
-------

```js
BigInt(value);
```

### Parâmetros

`value`

O valor numérico do objeto que está sendo criado. Pode ser uma *string* ou um número inteiro.

**Nota:** **Observação**: `BigInt()` não é usado com o operador `new`.

Descrição
---------

Um `BigInt` é criado com a acrescentação de `n` ao final de um inteiro literal — `10n` — ou chamando a função `BigInt()`.

```js
const theBiggestInt = 9007199254740991n;

const alsoHuge = BigInt(9007199254740991);
// ↪ 9007199254740991n

const hugeString = BigInt("9007199254740991");
// ↪ 9007199254740991n

const hugeHex = BigInt("0x1fffffffffffff");
// ↪ 9007199254740991n

const hugeBin = BigInt(
  "0b11111111111111111111111111111111111111111111111111111",
);
// ↪ 9007199254740991n
```

Isso é parecido com um `Number` em algumas partes, mas difere-se em alguns assuntos importantes — ele não pode ser usado com métodos no objeto `Math` e não pode ser misturado em operações ou qualquer instância de `Number`.

**Aviso:** `Number` e `BigInt` não podem ser misturados em operações — eles devem ser manipulados com o mesmo tipo.

Tenha cuidado com a conversão e desconversão de valores, visto que a precisão de `BigInt` pode ser perdida com a conversào para `Number`.

### Informações do tipo

Quando testado com `typeof` , um `BigInt` vai devolver "bigint":

```js
typeof 1n === "bigint"; // true
typeof BigInt("1") === "bigint"; // true
```

Quando envolvido em um `Object`, um `BigInt` vai ser considerado como um tipo normal de "object".

```js
typeof Object(1n) === "object"; // true
```

### Operadores

Os seguintes operadores podem ser usados com `BigInt`s (ou com `BigInt`s envolvidos em objetos): `+`, `*`, `-`, `**`, `%`.

```js
const previousMaxSafe = BigInt(Number.MAX\_SAFE\_INTEGER);
// ↪ 9007199254740991

const maxPlusOne = previousMaxSafe + 1n;
// ↪ 9007199254740992n

const theFuture = previousMaxSafe + 2n;
// ↪ 9007199254740993n, isso funciona agora!

const multi = previousMaxSafe \* 2n;
// ↪ 18014398509481982n

const subtr = multi – 10n;
// ↪ 18014398509481972n

const mod = multi % 10n;
// ↪ 2n

const bigN = 2n \*\* 54n;
// ↪ 18014398509481984n

bigN \* -1n
// ↪ –18014398509481984n
```

O operador `/` também funciona com o esperado com números inteiros. No entanto, desde que esses sejam `BigInt`s e não `BigDecimal`s, essa operação vai arredondar para 0, o que significa que não vai retornar qualquer valor fracional.

**Aviso:** Uma operação com um resultado fracional será arredondado com `BigInt.`

```js
const expected = 4n / 2n;
// ↪ 2n

const rounded = 5n / 2n;
// ↪ 2n, e não 2.5n
```

### Comparações

Um `BigInt` não é estritamente igual a um `Number`, mas é mais ou menos assim.

```js
0n === 0;
// ↪ false

0n == 0;
// ↪ true
```

Um `Number` e um `BigInt` podem ser comparado normalmente.

```js
1n < 2;
// ↪ true

2n > 1;
// ↪ true

2 > 2;
// ↪ false

2n > 2;
// ↪ false

2n >= 2;
// ↪ true
```

Eles podem ser misturados em *arrays* e ordenados.

```js
const mixed = [4n, 6, -12n, 10, 4, 0, 0n];
// ↪ [4n, 6, -12n, 10, 4, 0, 0n]

mixed.sort();
// ↪ [-12n, 0, 0n, 10, 4n, 4, 6]
```

Observe que comparações com `BigInt`s envolvidos em `Object` atuam com outros objetos, indicando somente a igualdade onde a mesma instância do objeto é comparada.

```js
0n === Object(0n); // false
Object(0n) === Object(0n); // false

const o = Object(0n);
o === o; // true
```

### Condicionais

A `BigInt` comporta-se como `Number` nos casos onde ele é convertido para um `Boolean`: através da função `Boolean`; quando usado com operadores lógicos `Logical Operators` (en-US) `||`, `&&`, e `!`; ou dentro de um teste condicional como um `if statement`.

```js
if (0n) {
  console.log("Olá de um if!");
} else {
  console.log("Olá de um else!");
}

// ↪ "Olá de um else!"

0n || 12n;
// ↪ 12n

0n && 12n;
// ↪ 0n

Boolean(0n);
// ↪ false

Boolean(12n);
// ↪ true

!12n;
// ↪ false

!0n;
// ↪ true
```

Métodos
-------

**`BigInt.asIntN()`**

Limita um BigInt entre -2expoente-1 e 2expoente-1-1

`BigInt.asUintN()`

Limita um BigInt entre 0 e 2expoente-1

Propriedades
------------

`BigInt.prototype`

Permite a adição de propriedades a um objeto `BigInt`.

Instâncias `BigInt`
-------------------

Todas as instâncias `BigInt` são herdades de BigInt.prototype. O protótipo do objeto do construtor do BigInt pode ser modificado para afetar todas as instâncias de `BigInt`.

### Métodos

{{page('/pt-BR/docs/Web/JavaScript/Reference/Global\_Objects/BigInt/prototype', 'Methods')}}Exemplos
--------

### Calculando números primos

```js
function isPrime(p) {
  for (let i = 2n; i \* i <= p; i++) {
    if (p % i === 0n) return false;
  }
  return true;
}

// Toma um BigInt como argumento e retorna um BigInt
function nthPrime(nth) {
  let maybePrime = 2n;
  let prime = 0n;

  while (nth >= 0n) {
    if (isPrime(maybePrime)) {
      nth -= 1n;
      prime = maybePrime;
    }
    maybePrime += 1n;
  }

  return prime;
}

nthPrime(20n);
// ↪ 73n
```


encodeURI() - JavaScript

encodeURI()
===========

A função **`encodeURI()`** codifica a URI substituindo cada instância de certos caracteres por um, dois, três ou quatro sequências de escape representando a codificação UTF-8 do caracter (será somente quatro sequências de escape para caracteres compostos de dois caracteres substitutos).

Experimente
-----------

Sintaxe
-------
```

encodeURI(URI)
```

### Parâmetros

`URI`

Uma URI completa.

### Valor de retorno

Uma nova cadeia de caracteres representando a cadeia de caracteres provida, codificada como uma URI.

Descrição
---------

A função `encodeURI()` não codifica caracteres que possuem significado especial (caracteres reservados) para a URI. O exemplo seguinte mostra todas as partes que o "esquema" da URI pode possivelmente conter. Note como certos caracteres são usados para dar significado especial:
```

http://username:password@www.example.com:80/path/to/file.php?foo=316&bar=this+has+spaces#anchor
```

Consequentemente, `encodeURI()` **não** codifica caracteres que são necessários para formular uma URI completa. Também, `encodeURI()` **não** codifica alguns caracteres adicionais, conhecidos como "marcas não reservadas (unreserved marks)", que não tem propósito reservado mas são permitidos na URI "como são". (Veja RFC2396)

`encodeURI()` escapa todos os caracteres **exceto**:
```

Não escapado:

    A-Z a-z 0-9 ; , / ? : @ & = + $ - _ . ! ~ * ' ( ) #
```

Exemplos
--------

### encodeURI vs encodeURIComponent

`encodeURI()` se difere de `encodeURIComponent()` como a seguir:

```js
var set1 = ";,/?:@&=+$#"; // Caracteres reservados
var set2 = "-\_.!~\*'()"; // Marcas não reservadas
var set3 = "ABC abc 123"; // Caracteres alfanuméricos + Espaço

console.log(encodeURI(set1)); // ;,/?:@&=+$#
console.log(encodeURI(set2)); // -\_.!~\*'()
console.log(encodeURI(set3)); // ABC%20abc%20123 (o espaço é codificado como %20)

console.log(encodeURIComponent(set1)); // %3B%2C%2F%3F%3A%40%26%3D%2B%24%23
console.log(encodeURIComponent(set2)); // -\_.!~\*'()
console.log(encodeURIComponent(set3)); // ABC%20abc%20123 (o espaço é codificado como %20)
```

Note que `encodeURI()` por si só não pode formar requisições `GET` e `POST`, como para `XMLHttpRequest`, porque `"&"`, `"+"`, e `"="` não são codificados, que são tratados como caracteres especiais em requisições `GET` e `POST`. `encodeURIComponent()`, entretanto, codifica esses caracteres.

### Codificando um substituto solitário alto joga

Um `URIError` (en-US) será jogado se uma tentativa de codificar um substituto que não é parte de um par alto-baixo, e.g.,

```js
// par alto-baixo ok
console.log(encodeURI("\uD800\uDFFF"));

// substituto alto solitário joga "URIError: malformed URI sequence"
console.log(encodeURI("\uD800"));

// substituto baixo solitário joga "URIError: malformed URI sequence"
console.log(encodeURI("\uDFFF"));
```

### Codificando para IPv6

Se você deseja seguir a RFC3986 mais recente para URLs, que faz colchetes ser reservado (para IPv6) e então não será codificado quando formando algo que possa ser parte da URL (como o host), o seguinte código pode ajudar:

```js
function fixedEncodeURI(str) {
  return encodeURI(str).replace(/%5B/g, "[").replace(/%5D/g, "]");
}
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-encodeuri-uri |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* `decodeURI()`
* `encodeURIComponent()`
* `decodeURIComponent()`


isNaN() - JavaScript

isNaN()
=======

A função **`isNaN()`** determina se o valor é `NaN` ou não. Tenha cuidado, o `cast` em `isNaN` tem regras para serem observadas. Você pode ficar interessado no `Number.isNaN()` que foi definido no ECMAScript 6 ou você pode usar `typeof` para determinar se o valor é Not-A-Number, `NaN`.

Experimente
-----------

Syntaxe
-------
```

isNaN(value)
```

### Parâmetros

`value`

O valor a ser testado.

### Valor retornado

**`true`** se o valor for `NaN`; otherwise, **`false`**.

Descrição
---------

### A necessidade da função `isNaN`

Ao contrário de todas as outras possibilidades de valores no JavaScript, não é possivel confiar nos operadores de igualdade `(== e ===)` para determina se o valor é `NaN` ou não, porque ambos, `NaN == NaN` e `NaN === NaN`, terá como valor de retorno: `false`. Daí a necessidade da funçao `isNAN`.

### Origem dos valores `NaN`

Os valores `NaN` são gerados quando operações aritiméticas tem como valores: *undefined* ou *unrepresentable*. Como valores, não fazem necessariamente condições de estouro. `NaN` também resulta da tentativa de coerção para valores numéricos, de valores não numéricos, para que o valor numérico primitivo seja disponível.

Por exemplo, divida zero por zero e o resultado será `NaN` , mas se dividir outros números por zero ele não será.

### Comportamento confuso do caso especial

Desde as primeiras versões da especificação da função isNaN , o seu comportamento para argumentos não numéricos tem sido confuso. Quando o argumento para a função `isNaN` não é do tipo\* **Numbe**r\*, o valor é primeiro convertido para um número. O valor resultante é em seguida testado para determinar se se trata de `Number.isNaN()`. Assim, para os não-números que quando forçados ao tipo numérico resultado em um valor numérico não-`NaN` válido (particularmente strings vazias e primitivas booleanas, que quando submetidas ao `cast` dão valores numéricos zero ou um), o "falso" valor retornado pode ser inesperado; a cadeia vazia , por exemplo, é certamente "not-a-number" A confusão decorre do fato de que o termo, " não é um número " , tem um significado específico para os números representados como valores de ponto flutuante IEEE- 794 . A função deve ser interpretada como respondendo à pergunta: "este valor, quando convertido para um valor numérico, um valor IEEE -794 ' not-a-number"?

A ultima versão do ECMAScript (ES6) contém A função `Number.isNaN()`. `Number.isNaN(x)` será a real forma para testar se x é NaN ou não. Mesmo com `Number.isNaN`, porém, o significado de NaN continua ser a precisão numérica, e não simplesmente, "não é um número = `NaN`, *not a number*". Paralelamente , na expressão `Number.isNaN`, a expressão `(x != x)` é a forma mais confiável para testar se a variável `x` é `NaN` ou não, assim o resultado não é sujeito ao falso positivo que faz `isNaN` não ser confiável.

A polyfill for `isNaN` would be (the polyfill leverages the unique never-equal-to-itself characteristic of `NaN`):

```js
var isNaN = function (value) {
  var n = Number(value);
  return n !== n;
};
```

Exemplos
--------

```js
isNaN(NaN); // true
isNaN(undefined); // true
isNaN({}); // true

isNaN(true); // false
isNaN(null); // false
isNaN(37); // false

// strings
isNaN("37"); // false: "37" is converted to the number 37 which is not NaN
isNaN("37.37"); // false: "37.37" is converted to the number 37.37 which is not NaN
isNaN(""); // false: the empty string is converted to 0 which is not NaN
isNaN(" "); // false: a string with spaces is converted to 0 which is not NaN

// dates
isNaN(new Date()); // false
isNaN(new Date().toString()); // true

// Esse é um falso positivo e é a razão para isNaN não seja totalmente confiável.
isNaN("blabla"); // true: "blabla" é convertido para número.
// A análise desse número falha e retorna NaN como resultado.
```

### Useful special-case behavior

There is a more usage oriented way to think of `isNaN()`: If `isNaN(x)` returns `false`, you can use `x` in an arithmetic expression not making the expression return `NaN`. If it returns `true`, `x` will make every arithmetic expression return `NaN`. This means that in JavaScript, `isNaN(x) == true` is equivalent to `x - 0` returning `NaN` (though in JavaScript `x - 0 == NaN` always returns false, so you can't test for it). Actually, `isNaN(x)`, `isNaN(x - 0)`, `isNaN(Number(x))`, `Number.isNaN(x - 0)`, and `Number.isNaN(Number(x))` always return the same and in JavaScript `isNaN(x)` is just the shortest possible form to express each of these terms.

You can use this, for example, to test whether an argument to a function is arithmetically processable (usable "like" a number), or if it's not and you have to provide a default value or something else. This way you can have a function that makes use of the full versatility JavaScript provides by implicitly converting values depending on context.

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-isnan-number |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* `NaN`
* `Number.isNaN()`


Error - JavaScript

Error
=====

O construtor de **`Error`** cria um objeto de erro. Instâncias de objetos `Error` são lançadas quando erros de tempo de execução ocorrem. O objeto `Error` também pode ser usado como objeto base para exceções definidas pelo usuário. Veja abaixo tipos de erro padrões embutidos.

Sintaxe
-------
```

new Error([message[, fileName[, lineNumber]]])
```

### Parâmetros

`message`

Opcional. Descrição do erro legível para humanos.

`fileName`
Non-standard

Opcional. O valor da propriedade `fileName` no objeto de erro criado. O padrão é o nome do arquivo contendo o código que chamou o construtor de `Error()`.

`lineNumber`
Non-standard

Opcional. O valor da propriedade `lineNumber` no objeto de `Error` criado. O padrão é o número da linha contendo a invocação do construtor `Error()`.

Descrição
---------

Erros em tempo de execução resultam em novos objetos `Error` sendo criados e lançados.

Esta página documenta o uso do objeto `Error` em si e seu uso como uma função construtora. Para uma lista de propriedades e métodos herdados por instâncias de `Error`, veja `Error.prototype` (en-US).

### Tipos de erro

Além do construtor genérico de `Error`, existem outros seis construtores principais de erro no JavaScript. Para exceções em *client-side*, veja Exceções na captura de Instruções (en-US).

`EvalError`

Cria uma instância representando um erro que ocorre na função global. `eval()`.

`InternalError`
Non-standard

Cria uma instância representando um erro que ocorre quando um erro interno na *engine* do JavaScript é lançado. Ex: "too much recursion".

`RangeError` (en-US)

Cria uma instância representando um erro que ocorre quando um valor ou parâmetro numérico está fora de seus limites válidos.

`ReferenceError`

Cria uma instância representando um erro que ocorre ao de-referenciar uma referência inválida.

`SyntaxError` (en-US)

Cria uma instância representando um erro que ocorre ao fazer o *parse* do código em `eval()`.

`TypeError`

Cria uma instância representando um erro que ocorre quando uma variável ou parâmetro não é de um tipo válido.

`URIError` (en-US)

Cria uma instância representando um erro que ocorre quando são passados parâmetros inválidos para `encodeURI()` ou `decodeURI()`.

Propriedades
------------

`Error.prototype` (en-US)

Permite a criação de propriedades para instâncias de `Error`.

Métodos
-------

O objeto `Error` global não contém métodos próprios, entretanto, ele herda alguns métodos através da cadeia de *prototypes*.

`Instâncias de Error`
---------------------

{{page('pt-BR/docs/JavaScript/Reference/Global\_Objects/Error/prototype', 'Description')}}### Propriedades

{{page('pt-BR/docs/JavaScript/Reference/Global\_Objects/Error/prototype', 'Properties')}}### Métodos

{{page('pt-BR/docs/JavaScript/Reference/Global\_Objects/Error/prototype', 'Methods')}}Exemplos
--------

### Lançando um erro genérico

Geralmente você cria um objeto `Error` com a intenção de lançá-lo usando a palavra-chave `throw`. Você pode capturar o erro usando uma construção de `try...catch`:

```js
try {
  throw new Error("Oooops!");
} catch (e) {
  alert(e.name + ": " + e.message);
}
```

### Capturando um erro específico

Você pode escolher por capturar apenas tipos de erro específicos testando o tipo do erro com a propriedade `constructor` de erro ou, se você está escrevendo para *engines* de JavaScript modernas, a palavra-chave `instanceof`:

```js
try {
  Objeto.Metodo();
} catch (e) {
  if (e instanceof EvalError) {
    alert(e.name + ": " + e.message);
  } else if (e instanceof RangeError) {
    alert(e.name + ": " + e.message);
  }
  // ... etc
}
```

### Tipos de erro customizados

Você pode escolher definir seus próprios tipos de erro derivando de `Error` para conseguir usar `throw new MeuErro()` e usar `instanceof MeuErro` para checar o tipo de erro na captura da exceção. A forma comum para isso está demonstrada abaixo

**Aviso:** Note que as instâncias `MeuErro` lançadas vão reportar valores de `lineNumber` e `fileName` incorretos, ao menos no Firefox.

Veja também "esta discussão no Stackoverflow (em inglês): What's a good way to extend Error in JavaScript?".

```js
// Cria um novo objeto que herda o construtor de Error através do prototype.
function MeuErro(message) {
  this.name = "MeuErro";
  this.message = message || "Mensagem de erro padrão";
  this.stack = new Error().stack;
}
MeuErro.prototype = Object.create(MeuErro.prototype);
MeuErro.prototype.constructor = MeuErro;

try {
  throw new MeuErro();
} catch (e) {
  console.log(e.name); // 'MeuErro'
  console.log(e.message); // 'Mensagem de erro padrão'
}

try {
  throw new MeuErro("Mensagem customizada");
} catch (e) {
  console.log(e.name); // 'MeuErro'
  console.log(e.message); // 'Mensagem customizada'
}
```

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-error-objects |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* `Error.prototype` (en-US)
* `throw`
* `try...catch`


Promise - JavaScript

Promise
=======

O objeto **`Promise`** representa a eventual conclusão (ou falha) de uma operação assíncrona e seu valor resultante.

Para saber como as promises funcionam e como você pode usá-las, recomendamos que você leia Usando promises primeiro.

Descrição
---------

Uma **`Promise`** é um proxy para um valor não necessariamente conhecido quando a promise é criada. Ele permite que você associe manipuladores ao valor de sucesso ou motivo de falha de uma ação assíncrona. Isso permite que métodos assíncronos retornem valores como métodos síncronos: em vez de retornar imediatamente o valor final, o método assíncrono retorna uma *promise* para fornecer o valor em algum momento no futuro.

Uma `Promise` está em um destes estados:

* *pending*: estado inicial, nem cumprido nem rejeitado.
* *fulfilled*: significa que a operação foi concluída com sucesso.
* *rejected*: significa que a operação falhou.

 O *estado eventual* de uma promise pendente pode ser *fulfilled* com um valor ou *rejected* com um motivo (erro).
 Quando uma dessas opções ocorre, os manipuladores associados enfileirados pelo método `then` de uma promise são chamados. Se a promise já tiver sido cumprida ou rejeitada quando um manipulador correspondente for anexado, o manipulador será chamado, portanto, não há condição de corrida entre a conclusão de uma operação assíncrona e a anexação de seus manipuladores.

Uma promise é considerada *resolvida* se for cumprida ou rejeitada, mas não pendente.

![Fluxograma mostrando como o estado Promise transita entre pendente, cumprido e rejeitado por meio de manipuladores then/catch. Uma promise pendente pode ser cumprida ou rejeitada. Se preenchido, o manipulador "on fulfillment", ou primeiro parâmetro do método then(), é executado e realiza outras ações assíncronas. Se rejeitado, o manipulador de erro, passado como o segundo parâmetro do método then() ou como o único parâmetro do método catch(), é executado.](/pt-BR/docs/Web/JavaScript/Reference/Global_Objects/Promise/promises.png)

Você também ouvirá o termo *resolved* usado com promises — isso significa que a promise é liquidada ou "bloqueada" para corresponder ao estado eventual de outra promise e resolvê-la ou rejeitá-la não tem efeito. O documento Estados e destinos da proposta original da Promise contém mais detalhes sobre a terminologia da promise. Coloquialmente, promises "resolvidas" geralmente são equivalentes a promises "cumpridas", mas, conforme ilustrado em "Estados e destinos", as promises resolvidas também podem estar pendentes ou rejeitadas. Por exemplo:

```js
new Promise((resolveOuter) => {
  resolveOuter(
    new Promise((resolveInner) => {
      setTimeout(resolveInner, 1000);
    }),
  );
});
```

Essa promise já está *resolvida* no momento em que é criada (porque o `resolveOuter` é chamado de forma síncrona), mas é resolvido com outra promise e, portanto, não será *cumprida* até 1 segundo depois, quando a promise interna for cumprida. Na prática, a "resolução" muitas vezes é feita nos bastidores e não observável, e apenas o seu cumprimento ou rejeição o são.

**Nota:** várias outras linguagens têm mecanismos para avaliação preguiçosa e adiamento de uma computação, que eles também chamam de "promises", por exemplo, Esquema. As promises em JavaScript representam processos que já estão acontecendo, que podem ser encadeados com funções de retorno de chamada. Se você deseja avaliar lentamente uma expressão, considere usar uma função sem argumentos, por exemplo. `f = () => expressão` para criar a expressão avaliada lentamente e `f()` para avaliar a expressão imediatamente.

### Promises em cadeia

Os métodos ``Promise.prototype.then()``, ``Promise.prototype.catch()`` e ``Promise.prototype.finally()`` são usados para associar uma ação adicional com uma promise que se torna liquidada. Como ``Promise.prototype.then()`` e ``Promise.prototype.catch()`` métodos retornam promises, eles podem ser encadeados.

O método `.then()` aceita até dois argumentos; o primeiro argumento é uma função de retorno de chamada para o caso cumprido da promise e o segundo argumento é uma função de retorno de chamada para o caso rejeitado. Cada `.then()` retorna um objeto de promise recém-gerado, que pode ser usado opcionalmente para encadeamento; por exemplo:

```js
const minhaPromise = new Promise((resolve, reject) => {
  setTimeout(() => {
    resolve("foo");
  }, 300);
});

minhaPromise
  .then(handleFulfilledA, handleRejectedA)
  .then(handleFulfilledB, handleRejectedB)
  .then(handleFulfilledC, handleRejectedC);
```

O processamento continua para o próximo elo da cadeia mesmo quando um `.then()` não possui uma função de retorno de chamada que retorna um objeto Promise. Portanto, uma cadeia pode omitir com segurança cada *rejection* função de retorno de chamada até o `.catch()` final.

Manipular uma promise rejeitada em cada `.then()` tem consequências mais adiante na cadeia de promises. Às vezes não há escolha, porque um erro deve ser tratado imediatamente. Nesses casos, devemos lançar um erro de algum tipo para manter o estado de erro na cadeia. Por outro lado, na ausência de uma necessidade imediata, é mais simples deixar de fora o tratamento de erros até uma instrução `.catch()` final. Um `.catch()` é realmente apenas um `.then()` sem um slot para uma função de retorno de chamada para o caso em que a promise é cumprida.

```js
minhaPromise
  .then(handleFulfilledA)
  .then(handleFulfilledB)
  .then(handleFulfilledC)
  .catch(handleRejectedAny);
```

Usando Arrow Function Expressions para as funções de retorno de chamada, a implementação da cadeia de promises pode ser algo assim:

```js
minhaPromise
  .then((valor) => `${valor} e barra`)
  .then((valor) => `${valor} e barra novamente`)
  .then((valor) => `${valor} e novamente`)
  .then((valor) => `${valor} e novamente`)
  .then((valor) => {
    console.log(valor);
  })
  .catch((erro) => {
    console.error(err);
  });
```

**Nota:** para uma execução mais rápida, todas as ações síncronas devem ser feitas preferencialmente em um manipulador, caso contrário, seriam necessários vários tiques para executar todos os manipuladores em sequência.

A condição de término de uma promise determina o estado "estabelecido" da próxima promise na cadeia. Um estado "cumprido" indica uma conclusão bem-sucedida da promise, enquanto um estado "rejeitado" indica falta de sucesso. O valor de retorno de cada promise cumprida na cadeia é passado para o próximo `.then()`, enquanto o motivo da rejeição é passado para a próxima função de tratamento de rejeição na cadeia.

As promises de uma corrente são aninhadas como bonecas russas, mas são estouradas como o topo de uma pilha. A primeira promise na cadeia está mais profundamente aninhada e é a primeira a aparecer.
```

(promise D, (promise C, (promise B, (promise A))))
```

Quando um `nextValue` é uma promise, o efeito é uma substituição dinâmica. O `return` faz com que uma promise seja exibida, mas a promise `nextValue` é colocada em seu lugar. Para o aninhamento mostrado acima, suponha que `.then()` associado a "promise B" retorne um `nextValue` de "promise X". O aninhamento resultante ficaria assim:
```

(promise D, (promise C, (promise X)))
```

Uma promise pode participar de mais de um aninhamento. Para o código a seguir, a transição de `promiseA` para um estado "settled" fará com que ambas as instâncias de `.then()` sejam invocadas.

```js
const promiseA = new Promise(myExecutorFunc);
const promiseB = promiseA.then(handleFulfilled1, handleRejected1);
const promiseC = promiseA.then(handleFulfilled2, handleRejected2);
```

Uma ação pode ser atribuída a uma promise já "estabelecida". Nesse caso, a ação (se apropriado) será executada na primeira oportunidade assíncrona. Observe que as promises são garantidas como assíncronas. Portanto, uma ação para uma promise já "estabelecida" ocorrerá somente depois que a pilha for limpa e um tique-taque do relógio passar. O efeito é muito parecido com `setTimeout(action,10)`.

```js
const promiseA = new Promise((resoluçãoFunc, rejeiçãoFunc) => {
  resoluçãoFunc(777);
});
// Neste ponto, "promiseA" já está liquidado.
promiseA.then((val) => console.log("log assíncrono tem val:", val));
console.log("log imediato");

// produz saída nesta ordem:
// registro imediato
// registro assíncrono tem valor: 777
```

### Thenables

O ecossistema JavaScript fez várias implementações do Promise muito antes de se tornar parte da linguagem. Apesar de serem representados de forma diferente internamente, no mínimo, todos os objetos do tipo Promise implementam a interface *Thenable*. Um thenable implementa o método `.then()`, que é chamado com dois retornos de chamada: um para quando a promise é cumprida, um para quando for rejeitado. Promises também são possíveis.

Para interoperar com as implementações de Promise existentes, a linguagem permite o uso de thenables no lugar de promises. Por exemplo, `Promise.resolve` não apenas resolverá as promises, mas também rastreará os entãoables.

```js
const aThenable = {
  then(onFulfilled, onRejected) {
    onCumprido({
      // O thenable é preenchido com outro thenable
      then(onFulfilled, onRejected) {
        onCumprido(42);
      },
    });
  },
};

Promise.resolve(aThenable); // Uma promise cumprida com 42
```

### Rastreamento de objetos de configurações incumbentes

Um objeto de configurações é um ambiente que fornece informações adicionais quando o código JavaScript está em execução. Isso inclui o mapa do domínio e do módulo, bem como informações específicas do HTML, como a origem. O objeto de configurações incumbente é rastreado para garantir que o navegador saibas qual usar para um determinado pedaço de código de usuário.

Para melhor visualizar isso, podemos dar uma olhada mais de perto em como o reino pode ser um problema. Um **reino** pode ser pensado aproximadamente como o objeto global. O que é único sobre os realms é que eles contêm todas as informações necessárias para executar o código JavaScript. Isso inclui objetos como `Array` e `Error`. Cada objeto de configurações tem sua própria "cópia" e não são compartilhados. Isso pode causar algum comportamento inesperado em relação às promises. Para contornar isso, rastreamos algo chamado **objeto de configurações incumbentes**. Isso representa informações específicas do contexto do código do usuário responsável por uma determinada chamada de função.

Para ilustrar isso um pouco mais, podemos dar uma olhada em como um `<iframe>` embutido em um documento se comunica com seu host. Como todas as APIs da Web estão cientes do objeto de configurações incumbente, o seguinte funcionará em todos os navegadores:

```html
<!doctype html> <iframe></iframe>
<!-- temos um reino aqui -->
<script>
 // temos um reino aqui também
 const bound = frames[0].postMessage.bind(frames[0], "alguns dados", "\*");
 // bound é uma função embutida — não há usuário
 // código na pilha, então qual reino usamos?
 setTimeout(limite);
 // isso ainda funciona, porque usamos o mais novo
 // reino (o titular) na pilha
</script>
```

O mesmo conceito se aplica às promises. Se modificarmos um pouco o exemplo acima, obtemos isso:

```html
<!doctype html> <iframe></iframe>
<!-- temos um reino aqui -->
<script>
 // temos um reino aqui também
 const bound = frames[0].postMessage.bind(frames[0], "alguns dados", "\*");
 // bound é uma função incorporada — não há usuário
 // código na pilha — qual reino usamos?
 Promise.resolve(undefined).then(bound);
 // isso ainda funciona, porque usamos o mais novo
 // reino (o titular) na pilha
</script>
```

Se alterarmos isso para que o `<iframe>` no documento esteja ouvindo as mensagens de postagem, podemos observar o efeito do objeto de configurações incumbente:

```html
<!-- y.html -->
<!doctype html>
<iframe src="x.html"></iframe>
<script>
 const bound = frames[0].postMessage.bind(frames[0], "alguns dados", "\*");
 Promise.resolve(undefined).then(bound);
</script>
```

```html
<!-- x.html -->
<!doctype html>
<script>
 window.addEventListener(
 "mensagem",
 (evento) => {
 document.querySelector("#texto").textContent = "olá";
 // este código será executado apenas em navegadores que rastreiam o objeto de configurações incumbente
 console.log(evento);
 },
 falso,
 );
</script>
```

No exemplo acima, o texto interno do `<iframe>` será atualizado somente se o objeto de configurações incumbente for rastreado. Isso porque, sem rastrear o titular, podemos acabar usando o ambiente errado para enviar a mensagem.

**Nota:** atualmente, o rastreamento de realm incumbente é totalmente implementado no Firefox e tem implementações parciais no Chrome e no Safari.

Construtor
----------

`Promise()` (en-US)

Cria um novo objeto `Promise`. O construtor é usado principalmente para encapsular funções que ainda não suportam promises.

Métodos estáticos
-----------------

`Promise.all(iterable)`

Aguarde que todas as promises sejam cumpridas ou que alguma seja rejeitada.

Se a promise retornada for cumprida, ela será cumprida com uma matriz de agregação dos valores das promises cumpridas, na mesma ordem definida no iterável de várias promises.

Se for rejeitado, será rejeitado com o motivo da primeira promise no iterável que foi rejeitada.

`Promise.allSettled(iterable)`

Aguarde até que todas as promises sejam resolvidas (cada uma pode cumprir ou rejeitar).

Retorna uma Promise que cumpre depois que todas as promises fornecidas são cumpridas ou rejeitadas, com uma matriz de objetos que descrevem o resultado de cada promise.

`Promise.any(iterable)` (en-US)

Pega um iterável de objetos Promise e, assim que uma das promises do iterável é cumprida, retorna uma única promise que cumpre com o valor dessa promise.

`Promise.race(iterable)`

Aguarde até que alguma das promises seja cumprida ou rejeitada.

Se a promise retornada for cumprida, ela será cumprida com o valor da primeira promise no iterável que foi cumprida.

Se for rejeitado, será rejeitado com o motivo da primeira promise que foi rejeitada.

`Promise.reject(reason)`

Retorna um novo objeto `Promise` que é rejeitado com o motivo fornecido.

`Promise.resolve(value)`

Retorna um novo objeto `Promise` que é resolvido com o valor fornecido. Se o valor for um thenable (ou seja, tem um método `then`), a promise retornada "seguirá" esse thenable, adotando seu estado eventual; caso contrário, a promise devolvida será cumprida com o valor.

Geralmente, se você não sabe se um valor é uma promise ou não, `Promise.resolve(value)` e trabalhe com o valor de retorno como uma promise.

Métodos de instância
--------------------

Consulte o Guia do Microtask (en-US) para saber mais sobre como esses métodos usam a fila e os serviços do Microtask.

`Promise.prototype.catch()`

Anexa um retorno de chamada do manipulador de rejeição à promise e retorna uma nova promise resolvendo o valor de retorno do retorno de chamada se for chamado ou seu valor de cumprimento original se a promise for cumprida.

`Promise.prototype.then()`

Anexa manipuladores de cumprimento e rejeição à promise e retorna uma nova promise resolvendo o valor de retorno do manipulador chamado ou seu valor estabelecido original se a promise não foi tratada (ou seja, se o manipulador relevante `onFulfilled` ou `onRejected` não é uma função).

`Promise.prototype.finally()`

Anexa um manipulador à promise e retorna uma nova promise que é resolvida quando a promise original é resolvida. O manipulador é chamado quando a promise é liquidada, seja cumprida ou rejeitada.

Exemplos
--------

### Exemplo básico

```js
const minhaPrimeiraPromise = new Promise((resolve, reject) => {
  // Chamamos resolve(...) quando o que estávamos fazendo de forma assíncrona foi bem-sucedido e reject(...) quando falhou.
  // Neste exemplo, usamos setTimeout(...) para simular código assíncrono.
  // Na realidade, você provavelmente estará usando algo como XHR ou uma API HTML.
  setTimeout(() => {
    resolve("Sucesso!"); // Yay! Tudo ocorreu bem!
  }, 250);
});

minhaPrimeiraPromise.then((mensagem de sucesso) => {
  // successMessage é o que passamos na função resolve(...) acima.
  // Não precisa ser uma string, mas se for apenas uma mensagem de sucesso, provavelmente será.
  console.log(`Yay! ${successMessage}`);
});
```

### Exemplo com diversas situações

Este exemplo mostra diversas técnicas para usar os recursos do Promise e diversas situações que podem ocorrer. Para entender isso, comece rolando até a parte inferior do bloco de código e examine a cadeia de promises. Após o fornecimento de uma promise inicial, uma cadeia de promises pode seguir. A cadeia é composta de chamadas `.then()`, e normalmente (mas não necessariamente) tem um único `.catch()` no final, opcionalmente seguido por `.finally()`. Neste exemplo, a cadeia de promises é iniciada por uma construção `new Promise()` escrita sob medida; mas, na prática, as cadeias de promises geralmente começam com uma função de API (escrita por outra pessoa) que retorna uma promise.

A função de exemplo `tetheredGetNumber()` mostra que um gerador de promise utilizará `reject()` ao configurar uma chamada assíncrona, ou dentro do call-back, ou ambos. A função `promiseGetWord()` ilustra como uma função de API pode gerar e retornar uma promise de maneira independente.

Observe que a função `troubleWithGetNumber()` termina com um `throw`. Isso é forçado porque uma cadeia de promises passa por todas as promises `.then()`, mesmo após um erro, e sem o `throw`, o erro pareceria "corrigido". Isso é um aborrecimento, e por esta razão, é comum omitir `rejectionFunc` em toda a cadeia de promises `.then()`, e ter apenas um único `rejectionFunc` no `catch()` final.

Este código pode ser executado em NodeJS. A compreensão é aprimorada ao ver os erros realmente ocorrerem. Para forçar mais erros, altere os valores de `threshold`.

```js
// Para experimentar o tratamento de erros, os valores "threshold" causam erros aleatoriamente
const THRESHOLD\_A = 8; // pode usar zero 0 para garantir o erro

function tetheredGetNumber(resolve, reject) {
  setTimeout(() => {
    const randomInt = Date.now();
    const value = randomInt % 10;
    if (value < THRESHOLD\_A) {
      resolve(value);
    } else {
      reject(`Muito grande: ${value}`);
    }
  }, 500);
}

function determinaParidade(valor) {
  const isOdd = valor % 2 === 1;
  return { valor, isOdd };
}

function troubleWithGetNumber(reason) {
  const err = new Error("Problema para obter o número", { cause: reason });
  console.error(err);
  throw err;
}

function promiseGetWord(parityInfo) {
  return new Promise((resolve, reject) => {
    const { value, isOdd } = parityInfo;
    if (value >= THRESHOLD\_A - 1) {
      reject(`Ainda muito grande: ${valor}`);
    } else {
      parityInfo.wordEvenOdd = isOdd ? "ímpar" : "par";
      resolve(parityInfo);
    }
  });
}

new Promise(tetheredGetNumber)
  .then(determineParity, troubleWithGetNumber)
  .then(promiseGetWord)
  .then((info) => {
    console.log(`Recebido: ${info.value}, ${info.wordEvenOdd}`);
    return info;
  })
  .catch((reason) => {
    if (reason.cause) {
      console.error("Já havia tratado o erro anteriormente");
    } else {
      console.error(`Problema com promiseGetWord(): ${reason}`);
    }
  })
  .finally((info) => console.log("Tudo pronto"));
```

### Exemplo Avançado

Este pequeno exemplo mostra o mecanismo of a `Promise`. O método `testPromise()` é chamado cada vez que o `<button>` é clicado. Ele cria uma promise que será cumprida, usando `setTimeout()` (en-US), para a contagem de promises (número começando em 1) a cada 1-3 segundos, aleatoriamente. O construtor `Promise()` é usado para criar a promise.

O cumprimento da promise é registrado, por meio de um callback de cumprimento definido usando `p1.then()`. Alguns logs mostram como a parte síncrona do método é dissociada da conclusão assíncrona da promise.

Ao clicar no botão várias vezes em um curto espaço de tempo, você verá até as diferentes promises sendo cumpridas uma após a outra.

#### HTML

```html
<button id="make-promise">Faça uma promise!</button>
<div id="log"></div>
```

#### JavaScript

```js
"use strict";

let promiseCount = 0;

function testPromise() {
  const thisPromiseCount = ++promiseCount;
  const log = document.getElementById("log");
  // começar
  log.insertAdjacentHTML("beforeend", `${thisPromiseCount}) Iniciado<br>`);
  // Fazemos uma nova promise: prometemos uma contagem numérica dessa promise,
  // a partir de 1 (após esperar 3s)
  const p1 = new Promise((resolve, reject) => {
    // A função executora é chamada com a habilidade
    // para resolver ou rejeitar a promise
    log.insertAdjacentHTML(
      "beforeend",
      `${thisPromiseCount}) Construtor de promise<br>`,
    );
    // Este é apenas um exemplo para criar assincronismo
    setTimeout(
      () => {
        // Nós cumprimos a promise
        resolve(thisPromiseCount);
      },
      Math.random() \* 2000 + 1000,
    );
  });

  // Definimos o que fazer quando a promise é resolvida com a chamada then(),
  // e o que fazer quando a promise é rejeitada com a chamada catch()
  p1.then((val) => {
    // Registra o valor de atendimento
    log.insertAdjacentHTML("beforeend", `${val}) Promise cumprida<br>`);
  }).catch((reason) => {
    // Registra o motivo da rejeição
    console.log(`Manuseie a promise rejeitada (${reason}) aqui.`);
  });
  // fim
  log.insertAdjacentHTML("beforeend", `${thisPromiseCount}) Promise feita<br>`);
}

const btn = document.getElementById("make-promise");
btn.addEventListener("click", testPromise);
```

#### Resultado

### Carregando uma imagem com XHR

Outro exemplo simples usando `Promise` e `XMLHttpRequest` para carregar uma imagem está disponível no MDN GitHub js-examples. Você também pode ver em ação. Cada etapa é comentada e permite acompanhar de perto a arquitetura Promise e XHR.

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-promise-objects |

Compatibilidade do navegador
----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* Polyfill de `Promise` em `core-js`
* Usando promises
* Promises/A+ especificação
* Promises JavaScript: uma introdução
* Domenic Denicola: Callbacks, Promises, and Coroutines – Asynchronous Programming Patterns in JavaScript