Worker

createWorkerClient

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

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

// 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.

CreateWorkerClientOptions

Import from @infrared-city/infrared-sdk-ts/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.
`worker`	`readonly`	`WorkerLike`	A module worker whose file calls `serveSdkWorker()`.

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`	A custom `fetch` for the SDK client, and the scope to listen on.

Returns

void

Example

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

ServeSdkWorkerOptions

Import from @infrared-city/infrared-sdk-ts/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`	The worker global to listen on. Defaults to `self`.

WorkerBuildingsOptions

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

WorkerBuildingsOptions = BuildingsConfig

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

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
`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()

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.

WorkerClientConfig

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

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-ts/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-ts/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-ts/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-ts/worker.

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

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