Class HonuaClient

The main Honua HTTP/gRPC-Web client.

HonuaClient is the protocol-aware entry point into the Honua server. It speaks GeoServices (FeatureServer, MapServer, ImageServer, GeometryServer, GPServer), OGC API Features / Tiles / Maps / Processes, STAC, WMS, WMTS, WFS 2.0, and OData v4, with one consistent request/response shape, capability negotiation, optional retries, pluggable auth, and a small in-process metadata cache.

For cross-protocol code that does not need to know the underlying service shape, prefer the protocol-neutral createDataset contract from @honua/sdk-js/contract — it wraps this client and exposes a single Source.query(...) surface that throws HonuaCapabilityNotSupportedError when a protocol cannot satisfy the request.

Example: Basic usage

import { HonuaClient } from "@honua/sdk-js/honua";

const client = new HonuaClient({
  baseUrl: "https://your-honua-server.example",
  apiKey: process.env.HONUA_API_KEY,
});

const { supported, reasons } = await client.checkCompatibility();
if (!supported) {
  throw new Error(`Unsupported Honua server: ${reasons.join("; ")}`);
}

const result = await client.queryFeatures({
  serviceId: "natural-earth",
  layerId: 0,
  where: "1=1",
  outFields: ["*"],
  returnGeometry: true,
  resultRecordCount: 25,
});

console.log(`Loaded ${result.features?.length ?? 0} features`);

Example: Per-service fluent wrappers

const parcels = client.featureLayer<{ NAME: string }>("parcels", 0);
const items = await client.ogcFeatures();
const wms = client.wms("usgs-imagery");

Constructors

constructor

Properties

minimumSupportedServerReleaseChannel minimumSupportedServerVersion

Accessors

isGrpcWeb serverBaseUrl

Methods

applyEdits cancelOgcProcessJob checkCompatibility clearAuthCredentials clearMetadataCache createOgcItem deleteOgcItem executeOgcProcess exportMap featureLayer fetchOgcRecordRaw fetchOgcRecordsRaw fetchOgcTile fetchWmtsTile findMap geometryService geoprocessing geoprocessingRunner geospatialGrpcProcessRunner getAuthHeaders getAuthToken getCompatibility getFeatureServiceMetadata getLayerMetadata getMapLayerMetadata getMapLegend getMapServiceMetadata getOgcCollection getOgcCollectionTileset getOgcFeaturesConformance getOgcFeaturesLanding getOgcItem getOgcMapImage getOgcMapsConformance getOgcMapsLanding getOgcProcess getOgcProcessesConformance getOgcProcessesLanding getOgcProcessJob getOgcProcessJobResults getOgcQueryables getOgcRecord getOgcRecordCollection getOgcRecordsConformance getOgcRecordsLanding getOgcTileMatrixSet getOgcTilesConformance getOgcTilesLanding getStacCollection getStacItem getStacLanding getWmsCapabilities getWmsFeatureInfo getWmsLegend getWmsMap getWmtsCapabilities getWmtsFeatureInfo identifyMap imageService listOgcCollections listOgcCollectionTilesets listOgcItems listOgcProcesses listOgcRecordCollections listOgcTileMatrixSets listServices listStacCollections mapLayer mapService odata ogcFeatures ogcMaps ogcProcesses ogcProcessRunner ogcRecords ogcTiles patchOgcItem pipelineFetch pipelineRequestJson processRunner queryFeatures queryFeaturesStream queryMapLayer queryMapRelatedRecords queryRelatedRecords refreshAuthCredentials replaceOgcItem request requestText resolveOgcFeaturesLayout revokeAuthCredentials scanMigrationSource searchOgcRecords searchStac service stac supportsFeature wfs wms wmts

Constructors

constructor

  • new HonuaClient(options): HonuaClient

  • Create a new HonuaClient.

    Parameters

    Returns HonuaClient

    Example: Minimal

    const client = new HonuaClient({ baseUrl: "https://your-honua-server.example" });

    Example: With API key + retries + timeout

    const client = new HonuaClient({
      baseUrl: "https://your-honua-server.example",
      apiKey: process.env.HONUA_API_KEY,
      retry: { maxRetries: 3 },
      timeoutMs: 30_000,
    });

Properties

Static ReadonlyminimumSupportedServerReleaseChannel

minimumSupportedServerReleaseChannel: "preview" = MINIMUM_SUPPORTED_SERVER_RELEASE_CHANNEL

Static ReadonlyminimumSupportedServerVersion

minimumSupportedServerVersion: "1.0.0" = HONUA_MINIMUM_SUPPORTED_SERVER_VERSION

The minimum Honua server version this SDK is contractually tested against.

Accessors

isGrpcWeb

serverBaseUrl

  • get serverBaseUrl(): string

  • Normalized base URL the client was constructed with (trailing slashes trimmed). Helpers that build absolute URLs without going through request() (e.g. tile URL generators) read this so they produce the same origin and base path the server actually serves from.

    Returns string

Methods

applyEdits

cancelOgcProcessJob

checkCompatibility

clearAuthCredentials

clearMetadataCache

createOgcItem

deleteOgcItem

executeOgcProcess

exportMap

featureLayer

  • featureLayer<T>(serviceId, layerId): HonuaFeatureLayer<T>

  • Construct a typed wrapper for a single FeatureServer layer.

    The returned HonuaFeatureLayer carries the same serviceId / layerId on every call so you can write await layer.queryFeatures({ where: "..." }) without restating the address.

    Type Parameters

    • T = Record<string, unknown>

      The attribute shape of features in this layer.

    Parameters

    • serviceId: string
    • layerId: number

    Returns HonuaFeatureLayer<T>

    Example

    const parcels = client.featureLayer<{ NAME: string; STATUS: string }>("parcels", 0);
    const { features } = await parcels.queryFeatures({ where: "STATUS = 'ACTIVE'" });

fetchOgcRecordRaw

fetchOgcRecordsRaw

fetchOgcTile

fetchWmtsTile

findMap

geometryService

geoprocessing

geoprocessingRunner

geospatialGrpcProcessRunner

getAuthHeaders

  • getAuthHeaders(): Promise<Record<string, string>>

  • Resolve the auth headers the client would attach to an outgoing request right now, refreshing provider credentials first if they are expiring.

    Transports that build their own connection outside the REST/gRPC pipeline — notably realtime SSE streams, which must re-authenticate on every (re)connect so a refreshed token is picked up after a drop — call this per connect to obtain fresh credentials. Returns an empty object when no credentials are configured.

    Returns Promise<Record<string, string>>

getAuthToken

  • getAuthToken(): Promise<undefined | string>

  • Resolve just the current bearer/authorization token value (without the Bearer scheme prefix when a plain bearer token is configured), or undefined if none. Convenience for realtime transports that must carry the token as a query parameter (native EventSource cannot set headers).

    Returns Promise<undefined | string>

getCompatibility

  • getCompatibility(options?): Promise<HonuaServerCompatibility>

  • Fetch and parse the server's compatibility contract from GET /api/v1/admin/capabilities.

    The first call populates an in-process cache; subsequent calls return the cached value unless options.refresh is true. Use HonuaClient.checkCompatibility instead when you want a non-throwing pass/fail signal with a list of reasons.

    Parameters

    Returns Promise<HonuaServerCompatibility>

    Throws

    HonuaError when the server response cannot be parsed into a valid compatibility envelope (missing serverVersion, controlPlaneApi, etc.).

    Example

    const contract = await client.getCompatibility();
    console.log(contract.serverVersion, contract.releaseChannel);
    console.log(contract.metadataSchemas);

getFeatureServiceMetadata

getLayerMetadata

getMapLayerMetadata

getMapLegend

getMapServiceMetadata

getOgcCollection

getOgcCollectionTileset

getOgcFeaturesConformance

getOgcFeaturesLanding

getOgcItem

getOgcMapImage

getOgcMapsConformance

getOgcMapsLanding

getOgcProcess

getOgcProcessesConformance

getOgcProcessesLanding

getOgcProcessJob

getOgcProcessJobResults

getOgcQueryables

getOgcRecord

getOgcRecordCollection

getOgcRecordsConformance

getOgcRecordsLanding

getOgcTileMatrixSet

getOgcTilesConformance

getOgcTilesLanding

getStacCollection

getStacItem

  • getStacItem(request): Promise<HonuaStacItemResponse>

  • Parameters

    • request: {
          collectionId: string | number;
          extraParams?: Record<string, string | number | boolean>;
          itemId: string | number;
          responseFormat?: string;
          signal?: AbortSignal;
      }
      • collectionId: string | number
      • OptionalextraParams?: Record<string, string | number | boolean>
      • itemId: string | number
      • OptionalresponseFormat?: string
      • Optionalsignal?: AbortSignal

    Returns Promise<HonuaStacItemResponse>

getStacLanding

getWmsCapabilities

  • getWmsCapabilities(request): Promise<WmsCapabilities>

  • Fetch and parse a WMS GetCapabilities document for the addressed service. The XML body decodes through requestText; the parsed shape is the typed WmsCapabilities envelope (no XML node leaks through the public surface).

    Parameters

    • request: {
          extraParams?: Record<string, string | number | boolean>;
          serviceId: string;
          signal?: AbortSignal;
          version?: string;
      }
      • OptionalextraParams?: Record<string, string | number | boolean>
      • serviceId: string
      • Optionalsignal?: AbortSignal
      • Optionalversion?: string

    Returns Promise<WmsCapabilities>

getWmsFeatureInfo

getWmsLegend

getWmsMap

getWmtsCapabilities

getWmtsFeatureInfo

identifyMap

imageService

listOgcCollections

listOgcCollectionTilesets

listOgcItems

listOgcProcesses

listOgcRecordCollections

listOgcTileMatrixSets

listServices

listStacCollections

mapLayer

mapService

odata

ogcFeatures

  • ogcFeatures(): HonuaOgcFeatures

  • Construct the OGC API Features client wrapper.

    Use this to walk collections (landing(), conformance(), collections()), read items (items(), item()), and apply edits (create* / replace* / patch* / delete*) against an OGC API Features endpoint exposed by the Honua server.

    Returns HonuaOgcFeatures

    Example

    const features = client.ogcFeatures();
    const collections = await features.collections();
    const items = await features.items("parcels", { limit: 100 });

ogcMaps

ogcProcesses

ogcProcessRunner

ogcRecords

ogcTiles

patchOgcItem

pipelineFetch

  • pipelineFetch(method, path, init?, callerSignal?, options?): Promise<Response>

  • Pipeline-aware request that returns the raw Response after the shared auth / retry / timeout / interceptor pipeline finishes successfully. Used by adapters that need to consume non-JSON bodies (OData $metadata XML, raw passthrough) without inheriting the Accept: application/json default of pipelineRequestJson.

    The returned Response is unconsumed — the caller picks .json(), .text(), or .arrayBuffer(). Non-2xx responses still throw the normalized HonuaHttpError (and trigger retries) so error handling matches every other client method.

    Parameters

    • method: QueryMethod
    • path: string
    • Optionalinit: RequestInit
    • OptionalcallerSignal: AbortSignal
    • options: {
          okStatuses?: readonly number[];
      } = {}
      • OptionalokStatuses?: readonly number[]

    Returns Promise<Response>

pipelineRequestJson

  • pipelineRequestJson<T>(method, path, init?, signal?): Promise<T>

  • Pipeline-aware JSON request that bypasses the GeoServices f=json convention used by request. Adapters whose protocols do not model f= (OData, OGC API, …) call this directly so they keep the shared auth / retry / timeout / interceptor pipeline without sending a query parameter the server would reject as InvalidQueryOption.

    Caller-supplied query parameters belong on path itself; init carries the body, headers, and abort signal. The default Accept header is application/json; pass an explicit Accept in init.headers to override.

    Type Parameters

    • T = unknown

    Parameters

    • method: QueryMethod
    • path: string
    • Optionalinit: {
          body?: null | BodyInit;
          headers?: HeadersInit;
      }
      • Optionalbody?: null | BodyInit
      • Optionalheaders?: HeadersInit
    • Optionalsignal: AbortSignal

    Returns Promise<T>

processRunner

queryFeatures

  • queryFeatures(request): Promise<HonuaQueryResponse>

  • Run a GeoServices FeatureServer/query request against a Honua-hosted layer.

    This is the canonical low-level read path. It maps directly to the FeatureServer query endpoint and accepts the full ArcGIS query shape (where, outFields, geometry, spatialRel, orderByFields, resultRecordCount, outSr, ...).

    For cross-protocol code (OGC, WFS, OData, STAC), prefer the protocol-neutral createDataset contract — it normalizes capability differences and gives you Source.query(...) plus paginated Source.queryAll(...) with explicit exceededTransferLimit reporting.

    Parameters

    Returns Promise<HonuaQueryResponse>

    Example

    const { features, exceededTransferLimit } = await client.queryFeatures({
      serviceId: "parcels",
      layerId: 0,
      where: "STATUS = 'ACTIVE'",
      outFields: ["OBJECTID", "NAME"],
      returnGeometry: true,
      outSr: 4326,
      resultRecordCount: 500,
    });

    if (exceededTransferLimit) {
      // re-issue with `resultOffset` or use queryFeaturesStream / dataset.source().queryAll()
    }

queryFeaturesStream

  • queryFeaturesStream(request): AsyncGenerator<HonuaFeature[], void, undefined>

  • Drive a paginated FeatureServer query as an async generator. Each yielded chunk is a HonuaFeature[] slice; iteration stops when the server stops advertising exceededTransferLimit. Lower-level than dataset.source(...).queryAll() but suitable for streaming pipelines that want backpressure between pages.

    Parameters

    Returns AsyncGenerator<HonuaFeature[], void, undefined>

    Example

    for await (const page of client.queryFeaturesStream({ serviceId: "parcels", layerId: 0, where: "1=1" })) {
      process(page);
    }

queryMapLayer

queryMapRelatedRecords

queryRelatedRecords

refreshAuthCredentials

replaceOgcItem

request

requestText

  • requestText(method, path, options?): Promise<{
        contentType: string;
        status: number;
        text: string;
    }>

  • Fetch a text response (e.g. XML / JSON / plain) with an explicit Accept negotiation. Used by the WFS adapter for GetCapabilities, Transaction responses, and ExceptionReport bodies, and by the WMS / WMTS Capabilities pipelines. Routes through the same interceptor / retry / abort pipeline as requestJson / requestBytes, so adapter callers do not need to bypass HonuaClient to reach fetch directly.

    Parameters

    • method: QueryMethod
    • path: string
    • Optionaloptions: {
          accept?: string;
          body?: BodyInit;
          contentType?: string;
          signal?: AbortSignal;
      }
      • Optionalaccept?: string
      • Optionalbody?: BodyInit
      • OptionalcontentType?: string
      • Optionalsignal?: AbortSignal

    Returns Promise<{
        contentType: string;
        status: number;
        text: string;
    }>

resolveOgcFeaturesLayout

  • resolveOgcFeaturesLayout(mode?): Promise<OgcEndpointLayout>

  • Resolve (and memoize) the OGC API Features endpoint layout for the given discovery mode. honua-facade (default) returns the fixed /ogc/features/... fast path with no network access; ogc-api and auto discover the layout from the server's landing page per OGC API

    • Common so the same typed surface works against pygeoapi / ldproxy / GeoServer. Discovery is cached per mode for the life of the client (the layout is a function of the fixed baseUrl).

    Parameters

    • mode: OgcApiLayoutMode = "honua-facade"

    Returns Promise<OgcEndpointLayout>

revokeAuthCredentials

scanMigrationSource

searchOgcRecords

searchStac

service

stac

supportsFeature

wfs

wms

wmts

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods
applyEditscancelOgcProcessJobcheckCompatibilityclearAuthCredentialsclearMetadataCachecreateOgcItemdeleteOgcItemexecuteOgcProcessexportMapfeatureLayerfetchOgcRecordRawfetchOgcRecordsRawfetchOgcTilefetchWmtsTilefindMapgeometryServicegeoprocessinggeoprocessingRunnergeospatialGrpcProcessRunnergetAuthHeadersgetAuthTokengetCompatibilitygetFeatureServiceMetadatagetLayerMetadatagetMapLayerMetadatagetMapLegendgetMapServiceMetadatagetOgcCollectiongetOgcCollectionTilesetgetOgcFeaturesConformancegetOgcFeaturesLandinggetOgcItemgetOgcMapImagegetOgcMapsConformancegetOgcMapsLandinggetOgcProcessgetOgcProcessesConformancegetOgcProcessesLandinggetOgcProcessJobgetOgcProcessJobResultsgetOgcQueryablesgetOgcRecordgetOgcRecordCollectiongetOgcRecordsConformancegetOgcRecordsLandinggetOgcTileMatrixSetgetOgcTilesConformancegetOgcTilesLandinggetStacCollectiongetStacItemgetStacLandinggetWmsCapabilitiesgetWmsFeatureInfogetWmsLegendgetWmsMapgetWmtsCapabilitiesgetWmtsFeatureInfoidentifyMapimageServicelistOgcCollectionslistOgcCollectionTilesetslistOgcItemslistOgcProcesseslistOgcRecordCollectionslistOgcTileMatrixSetslistServiceslistStacCollectionsmapLayermapServiceodataogcFeaturesogcMapsogcProcessesogcProcessRunnerogcRecordsogcTilespatchOgcItempipelineFetchpipelineRequestJsonprocessRunnerqueryFeaturesqueryFeaturesStreamqueryMapLayerqueryMapRelatedRecordsqueryRelatedRecordsrefreshAuthCredentialsreplaceOgcItemrequestrequestTextresolveOgcFeaturesLayoutrevokeAuthCredentialsscanMigrationSourcesearchOgcRecordssearchStacservicestacsupportsFeaturewfswmswmts