---
url: https://incajs.tom96da.com/reference/built-ins.md
description: >-
  Where the globals the host provides differ from the Web standards, and which
  standard ones are missing.
---

# Built-ins

The host defines these globals before your app runs. This page lists where a
global differs from the Web standards and how to load their types.
[Console](./console) has its own page.

## Types

Add the types of these globals to your `tsconfig.json`:

```json
{
  "compilerOptions": {
    "types": ["incajs/globals"]
  }
}
```

Don't load the DOM and Node.js types. They declare names the host does not define, such as
the window object and the fetch function. With `@types/node` loaded as well, keep
`skipLibCheck` on. A file that uses Node APIs, such as an `inca.config.ts` that reads
`process.env`, belongs in a second tsconfig with `"types": ["node"]`.

## `TextEncoder` and `TextDecoder`

Both follow the
[Encoding Standard](https://encoding.spec.whatwg.org/).

* `TextEncoderStream` and `TextDecoderStream` are missing.
* The host refuses two cases of a detached buffer:
  * `encodeInto()` with a view over a detached resizable buffer throws a
    `TypeError`.
  * `decode()` returns an empty string when a `stream` getter of the options
    detaches the buffer of the view.

## `URL` and `URLSearchParams`

Both follow the
[URL Standard](https://url.spec.whatwg.org/).

* `URL.createObjectURL()` and `URL.revokeObjectURL()` are missing, because the
  host has no `Blob`.
* `new URLSearchParams(record)` reads a `Proxy` record in this order: every
  `getOwnPropertyDescriptor` trap, then every `get` trap.
* A URL of 4 GiB or more aborts the host.
* The `origin` of a `file:` URL is `file://`.

These results of parsing and setting differ from the ones of browsers:

* The characters `^` and `|` stay raw in a path.
* Setting `pathname` to `//x` on `foo:/p` gives `foo://x`.
* A space in a host and the label `xn--a` are refused.
* Setting `protocol` to `http` on `mailto:x?q#f` changes nothing.
* The `origin` of `filesystem:http://a/t/x` is `"null"`.
* On `data:a ?x`, `searchParams.delete("x")` and `search = ""` give `data:a`.
  On `data:a #x`, `hash = ""` gives `data:a`.

These results for `file:` URLs differ from the ones of browsers:

* `file:///C|/x` keeps the `|`.
* `file://C:/x` parses.
* The host `localhost` is dropped, also by the `hostname` setter.
* `file:///c:/../x` and `/x` against `file:///C:/a/b` keep the drive letter.

## `structuredClone()`

`structuredClone()` follows the
[HTML Standard](https://html.spec.whatwg.org/multipage/structured-data.html#dom-structuredclone).
It differs in two places:

* A view that tracks the length of a resizable `ArrayBuffer` becomes a view of a fixed length when
  it is cloned.
* A `SharedArrayBuffer` and a view over one throw a `DataCloneError`.

## `performance`

* `now()` counts milliseconds from the start of the app, and a reload of the
  development window starts it again.
  `timeOrigin` and the entries of `mark()` and `measure()` start again with it.
* The timeline starts empty. It holds the entries of `mark()` and `measure()`,
  and no other entry type.
* `toJSON()` returns `timeOrigin` only, and entries have no `navigationId`.
* `performance` is not an `EventTarget`, so it has no `addEventListener()`.
* `measure()` with a navigation timing name, such as `fetchStart`, as `start`
  or `end` throws `InvalidAccessError`. `navigationStart` is 0.
* These do not exist:
  * `PerformanceObserver`
  * `timing`
  * `navigation`
  * `memory`
  * `eventCounts`
  * `interactionCount`
  * `clearResourceTimings()`
  * `setResourceTimingBufferSize()`
  * `onresourcetimingbufferfull`

## `crypto`

This follows the [Web Cryptography API](https://www.w3.org/TR/WebCryptoAPI/).

* `CryptoKey` is missing, and so are all `SubtleCrypto` methods except `digest()`:
  * `generateKey()`
  * `importKey()`
  * `exportKey()`
  * `sign()`
  * `verify()`
  * `encrypt()`
  * `decrypt()`
  * `deriveKey()`
  * `deriveBits()`
  * `wrapKey()`
  * `unwrapKey()`

## `AbortController` and `AbortSignal`

* `AbortSignal.timeout()` waits at most 4294967295 milliseconds.
* A signal that one of its own listeners refers to stays in memory until it aborts.
* One start of the host can create 2^32 - 1 signals, and a reload of the development window starts
  the count again. After that, `new AbortController()`, `AbortSignal.abort()`,
  `AbortSignal.timeout()` and `AbortSignal.any()` throw a `RangeError`.

## `setTimeout()` and `setInterval()`

These follow the
[HTML Standard](https://html.spec.whatwg.org/multipage/timers-and-user-prompts.html#timers).

* A handler must be a function. A string or any other value throws a
  `TypeError`.
* An interval keeps its schedule. After a late run, the next run is the next
  point of the original schedule, and the runs it missed are skipped.

## `requestAnimationFrame()`

This follows the
[HTML Standard](https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#animation-frames).

* A callback must be a function. A string or any other value throws a
  `TypeError`.
* On macOS, callbacks wait while another window fully covers the app's window,
  and run when it is uncovered.

## Limits

* One run of the app can register 2^31 - 1 timers, frame callbacks and event
  listeners in total. A cleared or removed one still counts. After that, these
  throw a `RangeError`:
  * `setTimeout()`
  * `AbortSignal.timeout()`
  * `setInterval()`
  * `requestAnimationFrame()`
  * `addEventListener()`
* A reload of the development window starts the count again.
