Worker, TypeScript SDK reference

createWorkerClient

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

createWorkerClient(options): 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.

In Node, pass a node:worker_threads Worker (no adapter, no module) and threads for the threaded core; the worker file calls serveSdkWorker(), which listens on parentPort.

Parameters

Parameter	Type	Description
`options`	`CreateWorkerClientOptions`	The worker, the compiled SDK core, the cloneable client config and an optional token callback.

Returns

WorkerClient

The worker client.

Example

TypeScript

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

// page
import { createWorkerClient } from "@infrared-city/infrared-sdk/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.

CreateWorkerClientOptions

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

Options for createWorkerClient.

Properties

Property	Modifier	Type	Description
`config?`	`readonly`	`WorkerClientConfig`	The cloneable part of `InfraredClientConfig` (no functions).
`getToken?`	`readonly`	() => `string` \	`Promise`<`string`>	Runs on the page; the worker asks for a token over its port.
`module?`	`readonly`	`Module`	The SDK core, compiled once on the page and shared by every worker. Required in a browser. In Node, leave it out: the worker loads the packaged core (the threaded one with `threads`).
`threads?`	`readonly`	`number`	Node only: the worker loads the packaged threaded core with this many threads in place of `module`, so one worker run uses several cores. The worker file must import `@infrared-city/infrared-sdk/worker` in Node. A browser worker has no threaded core: leave it unset there.
`worker`	`readonly`	`WorkerLike` \	`NodeWorkerLike`	A module worker whose file calls `serveSdkWorker()`: a browser `Worker`, or in Node a `node:worker_threads` `Worker`.

NodePortLike

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

The node:worker_threads parentPort, or any object with the same members.

Methods

on()

on(type, listener): unknown

Listens for messages from the page.

Parameters

Parameter	Type
`type`	`"message"`
`listener`	(`value`) => `void`

Returns

unknown

postMessage()

postMessage(message, transfer?): void

Sends a message to the page, optionally transferring objects.

Parameters

Parameter	Type
`message`	`unknown`
`transfer?`	readonly `unknown`\[\] \	readonly `never`\[\]

Returns

void

NodeWorkerLike

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

A node:worker_threads Worker, or any object with the same members.

Methods

on()

on(type, listener): unknown

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

Parameters

Parameter	Type
`type`	`"message"` \	`"messageerror"` \	`"error"` \	`"exit"`
`listener`	(`value`) => `void`

Returns

unknown

postMessage()

postMessage(message, transfer?): void

Sends a message to the worker, optionally transferring objects.

Parameters

Parameter	Type
`message`	`unknown`
`transfer?`	readonly `unknown`\[\] \	readonly `never`\[\]

Returns

void

terminate()

terminate(): unknown

Ends the worker.

Returns

unknown

serveSdkWorker

Import from @infrared-city/infrared-sdk/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`	A custom `fetch` for the SDK client, and the scope to listen on.

Returns

void

Example

TypeScript

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

ServeSdkWorkerOptions

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

Options for serveSdkWorker.

Properties

Property	Modifier	Type	Description
`fetch?`	`readonly`	\{(`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; \}	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.
`geometryUrlStore?`	`readonly`	`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.
`scope?`	`readonly`	`WorkerScope` \	`NodePortLike`	The worker global to listen on. Defaults to `self`; in Node, to `parentPort` of `node:worker_threads`.

WorkerBuildingsOptions

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

WorkerBuildingsOptions = BuildingsConfig

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

WorkerClient

Import from @infrared-city/infrared-sdk/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
`buildings`	`readonly`	`object`	Building reads that run in the worker.
`buildings.getBuildingsInArea`	`public`	`Promise`<`AreaBuildings`>	-
`groundMaterials`	`readonly`	`object`	Ground material reads that run in the worker.
`groundMaterials.getArea`	`public`	`Promise`<`AreaGroundMaterials`>	-
`vegetation`	`readonly`	`object`	Vegetation reads that run in the worker.
`vegetation.getArea`	`public`	`Promise`<`AreaVegetation`>	-

Methods

dispose()

dispose(): void

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

Returns

void

mergeAreaJobs()

mergeAreaJobs(schedule, options?): Promise<AreaResult>

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

Parameters

Parameter	Type	Description
`schedule`	`AreaSchedule`	A schedule returned by `runArea`.
`options?`	`WorkerMergeOptions`	Merge options.

Returns

Promise<AreaResult>

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

Throws

When the worker ends during the call.

mergeSurfaceAreaJobs()

mergeSurfaceAreaJobs(schedule, options?): Promise<SurfaceColumns>

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

Parameters

Parameter	Type	Description
`schedule`	`AreaSchedule`	A schedule returned by `runArea`.
`options?`	`Pick`<`WorkerMergeOptions`, `"signal"` \	`"maxWorkers"`>	Worker count and abort signal.

Returns

Promise<SurfaceColumns>

The merged surface result as columns.

Throws

When the worker ends during the call.

runArea()

Call Signature

runArea(input, polygon, options?): Promise<AreaSchedule>

Plans and submits an area analysis in the worker.

Parameters

Parameter	Type	Description
`input`	`RunAreaInput`	The area analysis input.
`polygon`	`Polygon`	The area to analyse.
`options?`	`RunAreaOptions`	Run options. Progress and acceptance callbacks run on the page.

Returns

Promise<AreaSchedule>

The schedule of the submitted tiles.

Throws

When the worker ends during the call.

Call Signature

runArea(inputs, polygon, options?): Promise<AreaSchedule\[\]>

Plans and submits several analyses over one polygon in the worker; one schedule per input.

Parameters

Parameter	Type
`inputs`	readonly `RunAreaInput`\[\]
`polygon`	`Polygon`
`options?`	`RunAreaOptions`

Returns

Promise<AreaSchedule\[\]>

runAreaStream()

runAreaStream(inputs, polygon, options?): AsyncGenerator<AreaStreamItem, void, undefined>

Runs analyses in the worker and yields each one as it finishes, as InfraredClient.runAreaStream does. A result's buffers are transferred, not copied. break or options.signal cancels the run in the worker. A failed analysis is an item with error.

Parameters

Parameter	Type
`inputs`	`RunAreaInput` \	readonly `RunAreaInput`\[\]
`polygon`	`Polygon`
`options?`	`RunAreaOptions`

Returns

AsyncGenerator<AreaStreamItem, void, undefined>

Throws

When the worker ends during the run.

WorkerClientConfig

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

WorkerClientConfig = Omit<InfraredClientConfig, "getToken" \| "auth" \| "fetch" \| "logger" \| "onGeometryReuseProbe">

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.

WorkerGroundMaterialsOptions

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

WorkerGroundMaterialsOptions = Omit<NonNullable<Parameters<GroundMaterialsService\["getArea"\]>\[1\]>, "cleaner">

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

WorkerLike

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

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

Methods

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

postMessage()

postMessage(message, transfer?): void

Sends a message to the worker, optionally transferring objects.

Parameters

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

Returns

void

terminate()

terminate(): void

Ends the worker.

Returns

void

WorkerLostError

Import from @infrared-city/infrared-sdk/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

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

acceptedJobIds

readonly acceptedJobIds: readonly string\[\]

Ids of the jobs accepted before the worker ended.

name

readonly name: "WorkerLostError" = "WorkerLostError"

Overrides

Error.name

reason

readonly reason: "load" \| "lost"

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

WorkerMergeOptions

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

WorkerMergeOptions = Omit<AreaMergeOptions, "logger">

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

WorkerRunAreaOptions

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

WorkerRunAreaOptions = RunAreaOptions

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

WorkerScope

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

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

Methods

addEventListener()

addEventListener(type, listener): void

Listens for messages from the page.

Parameters

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

Returns

void

postMessage()

postMessage(message, transfer?): void

Sends a message to the page, optionally transferring objects.

Parameters

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

Returns

void

WorkerVegetationOptions

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

WorkerVegetationOptions = NonNullable<Parameters<VegetationService\["getArea"\]>\[1\]>

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