---
title: Worker
source: https://infrared.city/docs/sdk/1.0/api/typescript/worker/
---

# Worker

<a id="createworkerclient"></a>

## createWorkerClient

Import from `@infrared-city/infrared-sdk-ts/worker`.

> **createWorkerClient**(`options`): [`WorkerClient`](worker.md#workerclient)

Creates an SDK client that runs in one dedicated worker.

One worker serves one client; the helper has no pool, no retry and no persistence, and it
never sends a call again. The worker file must call `serveSdkWorker()`. Errors cross the
worker boundary as plain `Error` objects: check `error.name`, not `instanceof`.
`getToken` is called per request with no session binding, so use one worker per signed-in
session and dispose the client on sign-out.

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`CreateWorkerClientOptions`](worker.md#createworkerclientoptions) | The worker, the compiled SDK core, the cloneable client config and an optional token callback. |

### Returns

[`WorkerClient`](worker.md#workerclient)

The worker client.

### Example

```ts
// sdk.worker.ts
import { serveSdkWorker } from "@infrared-city/infrared-sdk-ts/worker";
serveSdkWorker();

// page
import { createWorkerClient } from "@infrared-city/infrared-sdk-ts/worker";
const sdk = createWorkerClient({
  worker: new Worker(new URL("./sdk.worker.ts", import.meta.url), { type: "module" }),
  module, // a WebAssembly.Module compiled once on the page
  getToken,
});
const schedule = await sdk.runArea(input, polygon, {
  onAccepted: (jobId, tileKey) => saveJobId(jobId, tileKey),
});
const result = await sdk.mergeAreaJobs(schedule);
sdk.dispose();
```

### Throws

When the worker already serves a client.

***

<a id="createworkerclientoptions"></a>

## CreateWorkerClientOptions

Import from `@infrared-city/infrared-sdk-ts/worker`.

Options for `createWorkerClient`.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="createworkerclientoptions-config"></a> `config?` | `readonly` | [`WorkerClientConfig`](worker.md#workerclientconfig) | The cloneable part of `InfraredClientConfig` (no functions). |
| <a id="createworkerclientoptions-gettoken"></a> `getToken?` | `readonly` | () => `string` \| `Promise`&lt;`string`&gt; | Runs on the page; the worker asks for a token over its port. |
| <a id="createworkerclientoptions-module"></a> `module` | `readonly` | `Module` | The SDK core, compiled once on the page and shared by every worker. |
| <a id="createworkerclientoptions-worker"></a> `worker` | `readonly` | [`WorkerLike`](worker.md#workerlike) | A module worker whose file calls `serveSdkWorker()`. |

***

<a id="servesdkworker"></a>

## serveSdkWorker

Import from `@infrared-city/infrared-sdk-ts/worker`.

> **serveSdkWorker**(`options?`): `void`

Makes this worker serve the `createWorkerClient` on the page. Call it once, in the module
worker file.

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`ServeSdkWorkerOptions`](worker.md#servesdkworkeroptions) | A custom `fetch` for the SDK client, and the scope to listen on. |

### Returns

`void`

### Example

```ts
// sdk.worker.ts
import { serveSdkWorker } from "@infrared-city/infrared-sdk-ts/worker";
serveSdkWorker();
```

***

<a id="servesdkworkeroptions"></a>

## ServeSdkWorkerOptions

Import from `@infrared-city/infrared-sdk-ts/worker`.

Options for `serveSdkWorker`.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="servesdkworkeroptions-fetch"></a> `fetch?` | `readonly` | \{(`input`, `init?`): `Promise`&lt;`Response`&gt;; (`input`, `init?`): `Promise`&lt;`Response`&gt;; \} | The `fetch` the SDK client uses in this worker, for example a proxy that rewrites storage URLs. It must pass `init.signal` on to the request it makes: the SDK aborts a request through that signal, and a fetch that drops it keeps a cancelled request running. |
| <a id="servesdkworkeroptions-geometryurlstore"></a> `geometryUrlStore?` | `readonly` | [`GeometryUrlStore`](client.md#geometryurlstore) | The `geometryUrlStore` of the SDK client in this worker (a function cannot go through `postMessage`). Use a store that the next worker can read too, for example IndexedDB. |
| <a id="servesdkworkeroptions-scope"></a> `scope?` | `readonly` | [`WorkerScope`](worker.md#workerscope) | The worker global to listen on. Defaults to `self`. |

***

<a id="workerbuildingsoptions"></a>

## WorkerBuildingsOptions

Import from `@infrared-city/infrared-sdk-ts/worker`.

> **WorkerBuildingsOptions** = [`BuildingsConfig`](buildings.md#buildingsconfig)

Options for `WorkerClient.buildings.getBuildingsInArea`: the same as `BuildingsConfig`.

***

<a id="workerclient"></a>

## WorkerClient

Import from `@infrared-city/infrared-sdk-ts/worker`.

An SDK client that runs in a dedicated worker, created by `createWorkerClient`. Its
methods mirror the main client's, and the heavy work (site preparation, encoding,
decoding, merging) happens off the page.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="workerclient-buildings"></a> `buildings` | `readonly` | `object` | Building reads that run in the worker. |
| `buildings.getBuildingsInArea` | `public` | `Promise`&lt;[`AreaBuildings`](buildings.md#areabuildings)&gt; | - |
| <a id="workerclient-groundmaterials"></a> `groundMaterials` | `readonly` | `object` | Ground material reads that run in the worker. |
| `groundMaterials.getArea` | `public` | `Promise`&lt;[`AreaGroundMaterials`](ground-materials.md#areagroundmaterials)&gt; | - |
| <a id="workerclient-vegetation"></a> `vegetation` | `readonly` | `object` | Vegetation reads that run in the worker. |
| `vegetation.getArea` | `public` | `Promise`&lt;[`AreaVegetation`](vegetation.md#areavegetation)&gt; | - |

### Methods

<a id="workerclient-dispose"></a>

#### dispose()

> **dispose**(): `void`

End the worker. Open calls reject with `WorkerLostError` (`lost`).

##### Returns

`void`

***

<a id="workerclient-mergeareajobs"></a>

#### mergeAreaJobs()

> **mergeAreaJobs**(`schedule`, `options?`): `Promise`&lt;[`AreaResult`](results-and-legend.md#arearesult)&gt;

Waits for the jobs of an area schedule and merges their results in the worker.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `schedule` | [`AreaSchedule`](run-an-analysis.md#areaschedule) | A schedule returned by `runArea`. |
| `options?` | [`WorkerMergeOptions`](worker.md#workermergeoptions) | Merge options. |

##### Returns

`Promise`&lt;[`AreaResult`](results-and-legend.md#arearesult)&gt;

The merged area result. Its grid buffer is transferred, not copied.

##### Throws

When the worker ends during the call.

***

<a id="workerclient-mergesurfaceareajobs"></a>

#### mergeSurfaceAreaJobs()

> **mergeSurfaceAreaJobs**(`schedule`, `options?`): `Promise`&lt;[`SurfaceColumns`](results-and-legend.md#surfacecolumns)&gt;

Merges the surface results (for example facade runs) of an area schedule in the worker.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `schedule` | [`AreaSchedule`](run-an-analysis.md#areaschedule) | A schedule returned by `runArea`. |
| `options?` | `Pick`&lt;[`WorkerMergeOptions`](worker.md#workermergeoptions), `"signal"` \| `"maxWorkers"`&gt; | Worker count and abort signal. |

##### Returns

`Promise`&lt;[`SurfaceColumns`](results-and-legend.md#surfacecolumns)&gt;

The merged surface result as columns.

##### Throws

When the worker ends during the call.

***

<a id="workerclient-runarea"></a>

#### runArea()

> **runArea**(`input`, `polygon`, `options?`): `Promise`&lt;[`AreaSchedule`](run-an-analysis.md#areaschedule)&gt;

Plans and submits an area analysis in the worker.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `input` | [`RunAreaInput`](run-an-analysis.md#runareainput) | The area analysis input. |
| `polygon` | [`Polygon`](tiling.md#polygon) | The area to analyse. |
| `options?` | [`RunAreaOptions`](run-an-analysis.md#runareaoptions) | Run options. Progress and acceptance callbacks run on the page. |

##### Returns

`Promise`&lt;[`AreaSchedule`](run-an-analysis.md#areaschedule)&gt;

The schedule of the submitted tiles.

##### Throws

When the worker ends during the call.

***

<a id="workerclientconfig"></a>

## WorkerClientConfig

Import from `@infrared-city/infrared-sdk-ts/worker`.

> **WorkerClientConfig** = `Omit`&lt;[`InfraredClientConfig`](client.md#infraredclientconfig), `"getToken"` \| `"auth"` \| `"fetch"` \| `"logger"` \| `"onGeometryReuseProbe"`&gt;

The part of `InfraredClientConfig` that can cross to a worker: no
functions. Give `getToken` to `createWorkerClient` and `fetch` to
`serveSdkWorker`; a logger stays the worker's default.

***

<a id="workergroundmaterialsoptions"></a>

## WorkerGroundMaterialsOptions

Import from `@infrared-city/infrared-sdk-ts/worker`.

> **WorkerGroundMaterialsOptions** = `Omit`&lt;`NonNullable`&lt;`Parameters`&lt;[`GroundMaterialsService`](ground-materials.md#groundmaterialsservice)\[`"getArea"`\]&gt;\[`1`\]&gt;, `"cleaner"`&gt;

Options for `WorkerClient.groundMaterials.getArea`: the same as the ground materials
service's area options, without a `cleaner`.

***

<a id="workerlike"></a>

## WorkerLike

Import from `@infrared-city/infrared-sdk-ts/worker`.

A `Worker`, or any object with the same three members.

### Methods

<a id="workerlike-addeventlistener"></a>

#### addEventListener()

> **addEventListener**(`type`, `listener`): `void`

Listens for the worker's `message`, `messageerror` and `error` events.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `type` | `"message"` \| `"messageerror"` \| `"error"` |
| `listener` | (`event`) => `void` |

##### Returns

`void`

***

<a id="workerlike-postmessage"></a>

#### postMessage()

> **postMessage**(`message`, `transfer?`): `void`

Sends a message to the worker, optionally transferring objects.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `message` | `unknown` |
| `transfer?` | `Transferable`\[\] |

##### Returns

`void`

***

<a id="workerlike-terminate"></a>

#### terminate()

> **terminate**(): `void`

Ends the worker.

##### Returns

`void`

***

<a id="workerlosterror"></a>

## WorkerLostError

Import from `@infrared-city/infrared-sdk-ts/worker`.

Thrown by every open call when the worker ends.

- `load`: the worker failed before it was ready. No call started work,
  so nothing was sent.
- `lost`: every other case, including `dispose()` during a call. The jobs
  in `acceptedJobIds` were accepted (the ids that `onAccepted` reported
  for this call and the page received before the loss; an id still in
  flight can be missing). Every other tile of a `runArea` call is
  uncertain: its request may have reached the server. Do not send them again
  automatically.

### Extends

- `Error`

### Constructors

<a id="workerlosterror-constructor"></a>

#### Constructor

> **new WorkerLostError**(`reason`, `acceptedJobIds`, `message?`): `WorkerLostError`

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `reason` | `"load"` \| `"lost"` | `"load"` or `"lost"`, as described above. |
| `acceptedJobIds` | readonly `string`\[\] | Ids of the jobs the server accepted before the worker ended. |
| `message` | `string` | The error message; a default is given for each reason. |

##### Returns

`WorkerLostError`

##### Overrides

`Error.constructor`

### Properties

<a id="workerlosterror-acceptedjobids"></a>

#### acceptedJobIds

> `readonly` **acceptedJobIds**: readonly `string`\[\]

Ids of the jobs accepted before the worker ended.

***

<a id="workerlosterror-name"></a>

#### name

> `readonly` **name**: `"WorkerLostError"` = `"WorkerLostError"`

##### Overrides

`Error.name`

***

<a id="workerlosterror-reason"></a>

#### reason

> `readonly` **reason**: `"load"` \| `"lost"`

Why the worker ended: `"load"` or `"lost"`.

***

<a id="workermergeoptions"></a>

## WorkerMergeOptions

Import from `@infrared-city/infrared-sdk-ts/worker`.

> **WorkerMergeOptions** = `Omit`&lt;[`AreaMergeOptions`](run-an-analysis.md#areamergeoptions), `"logger"`&gt;

Options for `WorkerClient.mergeAreaJobs`: the same as the area merge options, without a
logger.

***

<a id="workerrunareaoptions"></a>

## WorkerRunAreaOptions

Import from `@infrared-city/infrared-sdk-ts/worker`.

> **WorkerRunAreaOptions** = [`RunAreaOptions`](run-an-analysis.md#runareaoptions)

Options for `WorkerClient.runArea`: the same as `RunAreaOptions`. Callbacks run on the
page, and `retryFrom` is a schedule.

***

<a id="workerscope"></a>

## WorkerScope

Import from `@infrared-city/infrared-sdk-ts/worker`.

The worker global, or any object with the same two members.

### Methods

<a id="workerscope-addeventlistener"></a>

#### addEventListener()

> **addEventListener**(`type`, `listener`): `void`

Listens for messages from the page.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `type` | `"message"` |
| `listener` | (`event`) => `void` |

##### Returns

`void`

***

<a id="workerscope-postmessage"></a>

#### postMessage()

> **postMessage**(`message`, `transfer?`): `void`

Sends a message to the page, optionally transferring objects.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `message` | `unknown` |
| `transfer?` | `Transferable`\[\] |

##### Returns

`void`

***

<a id="workervegetationoptions"></a>

## WorkerVegetationOptions

Import from `@infrared-city/infrared-sdk-ts/worker`.

> **WorkerVegetationOptions** = `NonNullable`&lt;`Parameters`&lt;[`VegetationService`](vegetation.md#vegetationservice)\[`"getArea"`\]&gt;\[`1`\]&gt;

Options for `WorkerClient.vegetation.getArea`: the same as the vegetation service's
area options.

***