Class RuntimeHandle

[asyncDispose]

[dispose]

Readonlyid

discarding

• get discarding(): RuntimeHandleDiscarding

  The commands of this owner that discard their outcomes.

  Returns RuntimeHandleDiscarding

clearEventHandler

• clearEventHandler(): Promise<CommandCompletion>

  Stops sending the events of the runtime and its maps to a callback.

  See mln_runtime_clear_event_handler in the C API reference.

  Returns Promise<CommandCompletion>

clearHttpHeaderTransform

• clearHttpHeaderTransform(): Promise<CommandCompletion>

  Stops adding headers to the runtime's HTTP requests.

  See mln_runtime_clear_http_header_transform in the C API reference.

  Returns Promise<CommandCompletion>

clearResourceProvider

• clearResourceProvider(): Promise<CommandCompletion>

  Removes the runtime's resource provider, so the library loads every request itself.

  See mln_runtime_clear_resource_provider in the C API reference.

  Returns Promise<CommandCompletion>

clearResourceTransform

• clearResourceTransform(): Promise<CommandCompletion>

  Stops rewriting the URLs of the runtime's network requests.

  See mln_runtime_clear_resource_transform in the C API reference.

  Returns Promise<CommandCompletion>

createMap

• createMap(options: MapOptions): MapHandle

  Creates a map on runtime.

  Asynchronous calls on the map before the completion runs wait for it, and complete with Status.invalidState when creation fails.

  See mln_runtime_create_map in the C API reference.

  Parameters

  • options: MapOptions

  Returns MapHandle

createOfflineRegion

• createOfflineRegion(
      definition: OfflineRegionDefinition,
      metadata: Uint8Array,
  ): Promise<OfflineRegionInfo>

  Creates an offline region in the runtime's cache file.

  metadata holds any bytes to store with the region, such as its name. The region doesn't download until RuntimeHandle.setOfflineRegionDownloadState() makes its download active.

  See mln_runtime_create_offline_region in the C API reference.

  Parameters

  • definition: OfflineRegionDefinition
  • metadata: Uint8Array

  Returns Promise<OfflineRegionInfo>

deleteOfflineRegion

• deleteOfflineRegion(regionId: bigint): Promise<void>

  Deletes the offline region regionId from the runtime's cache file.

  See mln_runtime_delete_offline_region in the C API reference.

  Errors:

  • Status.notFound when the cache file has no region regionId.

  Parameters

  • regionId: bigint

  Returns Promise<void>

dispose

• dispose(): void

  Releases a runtime in any state, without waiting.

  The runtime finishes its teardown after its maps are released.

  See mln_runtime_dispose in the C API reference.

  Returns void

getOfflineRegion

• getOfflineRegion(regionId: bigint): Promise<OfflineRegionInfo | undefined>

  Reads the offline region regionId.

  The result is null when the cache file has no region with that ID.

  See mln_runtime_get_offline_region in the C API reference.

  Parameters

  • regionId: bigint

  Returns Promise<OfflineRegionInfo | undefined>

getOfflineRegionStatus

• getOfflineRegionStatus(regionId: bigint): Promise<OfflineRegionStatus>

  Reads the download progress of the offline region regionId.

  While the download is active, the counts cover what it has visited. Once it's inactive, they cover every resource the region holds, including those that only earlier versions of its style listed, so the completed counts can exceed the required counts.

  See mln_runtime_get_offline_region_status in the C API reference.

  Errors:

  • Status.notFound when the cache file has no region regionId.

  Parameters

  • regionId: bigint

  Returns Promise<OfflineRegionStatus>

invalidateOfflineRegion

• invalidateOfflineRegion(regionId: bigint): Promise<void>

  Makes maps check each resource of the offline region regionId with the server before they use it.

  The region keeps its resources. Starting its download again fetches the invalidated resources for offline use. If the style or a TileJSON document is then missing or invalid, the download reports an offline region response error and goes on from the stored copy. Resources that the current style no longer lists stay in the region until it's deleted.

  See mln_runtime_invalidate_offline_region in the C API reference.

  Errors:

  • Status.notFound when the cache file has no region regionId.

  Parameters

  • regionId: bigint

  Returns Promise<void>

listOfflineRegions

• listOfflineRegions(): Promise<readonly OfflineRegionInfo[]>

  Lists the offline regions in the runtime's cache file.

  See mln_runtime_list_offline_regions in the C API reference.

  Returns Promise<readonly OfflineRegionInfo[]>

mergeOfflineRegions

• mergeOfflineRegions(
      sideDatabasePath: string,
  ): Promise<readonly OfflineRegionInfo[]>

  Copies the offline regions of another cache file into the runtime's cache file.

  A region whose definition and metadata match one that the runtime's file already has isn't copied again. The result lists the runtime's copy of each region in the other file.

  See mln_runtime_merge_offline_regions in the C API reference.

  Errors:

  • Status.invalidArgument when sideDatabasePath isn't a readable database file.
  • Status.nativeError when the merge would exceed the tile limit that RuntimeEventType.offlineRegionTileCountLimitExceeded describes.

  Parameters

  • sideDatabasePath: string

  Returns Promise<readonly OfflineRegionInfo[]>

release

• release(): Promise<void>

  Releases a runtime.

  Release the runtime's maps first.

  See mln_runtime_release in the C API reference.

  Returns Promise<void>

runCacheDatabaseOperation

• runCacheDatabaseOperation(operation: CacheDatabaseOperation): Promise<void>

  Runs a maintenance action on the runtime's cache database.

  See mln_runtime_run_cache_database_operation in the C API reference.

  Parameters

  • operation: CacheDatabaseOperation

  Returns Promise<void>

setEventHandler

• setEventHandler(handler: RuntimeEventHandler): Promise<CommandCompletion>

  Sends the events of the runtime and its maps to a callback.

  The callback replaces the one set before.

  See mln_runtime_set_event_handler in the C API reference.

  Parameters

  • handler: RuntimeEventHandler

  Returns Promise<CommandCompletion>

setHttpHeaderTransform

• setHttpHeaderTransform(
      transform: HttpHeaderTransform,
  ): Promise<CommandCompletion>

  Adds headers to the runtime's HTTP requests.

  The transform replaces the one set before. In a browser or on OpenHarmony, serve the requests with RuntimeHandle.setResourceProvider() instead.

  See mln_runtime_set_http_header_transform in the C API reference.

  Errors:

  • Status.unsupported when the library runs in a browser or on OpenHarmony.

  Parameters

  • transform: HttpHeaderTransform

  Returns Promise<CommandCompletion>

setMaximumAmbientCacheSize

• setMaximumAmbientCacheSize(size: bigint): Promise<void>

  Limits the size of the runtime's ambient cache.

  size is in bytes. Offline regions don't count toward it. It defaults to 50 MB, or to 0 in the browser when the runtime has no cache file.

  See mln_runtime_set_maximum_ambient_cache_size in the C API reference.

  Parameters

  • size: bigint

  Returns Promise<void>

setOfflineRegionDownloadState

• setOfflineRegionDownloadState(
      regionId: bigint,
      state: OfflineRegionDownloadState,
  ): Promise<void>

  Starts or pauses the download of the offline region regionId.

  Setting the state that the download already has does nothing. A download stops when the runtime closes.

  See mln_runtime_set_offline_region_download_state in the C API reference.

  Errors:

  • Status.notFound when the cache file has no region regionId.

  Parameters

  • regionId: bigint
  • state: OfflineRegionDownloadState

  Returns Promise<void>

setOfflineRegionObserved

• setOfflineRegionObserved(regionId: bigint, events: bigint): Promise<void>

  Selects the events that the runtime reports about the download of the offline region regionId.

  events holds bits of RuntimeEventFlag.allRuntimeEvents and replaces the region's previous selection. RuntimeEventFlag.none stops the region's events.

  See mln_runtime_set_offline_region_observed in the C API reference.

  Errors:

  • Status.notFound when the cache file has no region regionId.

  Parameters

  • regionId: bigint
  • events: bigint

  Returns Promise<void>

setResourceProvider

• setResourceProvider(provider: ResourceProvider): Promise<CommandCompletion>

  Serves the runtime's network requests through a callback.

  The provider receives the network requests that its routes match, and the library loads the rest as usual. A provider can serve URL schemes that the library can't load itself. The provider replaces the one set before.

  See mln_runtime_set_resource_provider in the C API reference.

  Parameters

  • provider: ResourceProvider

  Returns Promise<CommandCompletion>

setResourceTransform

• setResourceTransform(transform: ResourceTransform): Promise<CommandCompletion>

  Rewrites the URLs of the runtime's network requests.

  The transform replaces the one set before.

  See mln_runtime_set_resource_transform in the C API reference.

  Parameters

  • transform: ResourceTransform

  Returns Promise<CommandCompletion>

updateOfflineRegionMetadata

• updateOfflineRegionMetadata(
      regionId: bigint,
      metadata: Uint8Array,
  ): Promise<OfflineRegionInfo>

  Replaces the metadata of the offline region regionId.

  See mln_runtime_update_offline_region_metadata in the C API reference.

  Errors:

  • Status.notFound when the cache file has no region regionId.

  Parameters

  • regionId: bigint
  • metadata: Uint8Array

  Returns Promise<OfflineRegionInfo>

Staticcreate

• create(options?: RuntimeOptions): Promise<RuntimeHandle>

  Creates a runtime.

  A runtime holds maps and the resource loading, cache, and offline regions that they share. In a browser, create runtimes on a Web Worker, not on the main thread.

  Resolves once the call completes, so a browser page, which cannot block, can call it.

  See mln_runtime_create in the C API reference.

  Errors:

  • Status.invalidArgument when the cache database file that options names can't be opened or created.

  Parameters

  • Optionaloptions: RuntimeOptions

  Returns Promise<RuntimeHandle>