Map resource requests and cancellation

This page describes the development-source browser SDK. Use JavaScript and WASM from the same core commit; the existing npm 0.2.0 release does not imply support for these additions. Download declarations from the browser API reference.

Configure requests

The hook follows MapLibre's transformRequest(url, resourceType) naming. ResourceType includes Style, Source, Tile, Glyphs, SpriteJSON, SpriteImage, Image, and Unknown, selected from the actual core request. SqsMap implements its own transport and renderer and embeds no MapLibre code.

import { MapView, ResourceType } from '@sqsmap/core';

const map = await MapView.create(document.querySelector('#map')!, {
  resourceTimeoutMs: 15000,
  transformRequest(url, resourceType) {
    if (resourceType === ResourceType.Style) {
      return {
        url,
        headers: new Headers({ 'X-Map-Client': 'my-app' }),
        credentials: 'omit',
        cache: 'default',
        type: 'json',
      };
    }
    return { url, credentials: 'omit' };
  },
});
map.setStyleBasemap('https://tiles.openfreemap.org/styles/bright');
await map.flush(); // Commands applied; downloading and rendering remain asynchronous.

// When the page or component stops using the map:
// map.destroy();

The host must provide a sized #map container and display the source attribution, such as OpenFreeMap / OpenMapTiles / OpenStreetMap. The source must permit cross-origin access.

Return a synchronous request object or undefined. url may rewrite the request to a proxy; omitting it preserves the original URL for compatibility with older RequestInit hooks. headers accepts objects, tuples, and Headers. Standard Fetch options including method, body, credentials, cache, and referrerPolicy are passed to the browser, which still enforces its access and security rules.

type declares the existing core decoder: styles, GeoJSON/source configuration, and sprite JSON use json; sprite images and raster tiles use image; MP4/H.264 videos and other binary resources use arrayBuffer. Changing decoder type, enabling collectResourceTiming, or using mode: 'no-cors' produces CAPABILITY_UNAVAILABLE. Unknown options, asynchronous hooks, invalid URLs, and invalid deadlines produce INVALID_ARGUMENT before downloading.

Authorization and execution thread

Automatic apiToken injection applies only to the final exact origin https://api.suanjinshan.com. Rewriting to another origin does not forward that automatic token. Users must scope any manually supplied authorization headers to the appropriate origin.

Function hooks and function token providers use the main-thread path because functions cannot be cloned into a Worker. Combining an explicit custom Worker with function-valued request options is rejected. The default Worker without function hooks uses the same transport manager and deadline settings.

Lifecycle and limits

The default request deadline is 30 seconds; the allowed range is 1–120000 milliseconds. The runtime downloads at most 8 basemap resources and 8 raster tiles concurrently; the transport manager has a total limit of 32. Basemap resources use the core byte budget; raster tiles use 16 MiB. Streaming reads enforce these limits. Exceeding a budget produces RESOURCE_LIMIT; HTTP and deadline failures produce IO_ERROR.

A successful basemap replacement or clear cancels old basemap downloads. A rejected replacement retains existing downloads. Removing a raster layer cancels its downloads; destroying the map cancels all downloads. Matching new WASM bindings use independent resource generations to reject obsolete basemap responses and images for removed layers. Decoded images are released after processing; cancelled downloads cannot populate obsolete resources.

This stage delivers the browser adapter and shared core resource descriptions. Public native request/response entry points are documented in native resources. The mobile script resource host, custom protocols, native policy alignment and common persistent caching remain pending. Unsupported entries must not be treated as a common three-platform API. Evidence covers controlled transport and the actual runtime, and does not replace browser GPU or mobile-device acceptance.

References: MapLibre RequestParameters and ResourceType.

Native styles and resource hosts: native libraries now provide set_style_json, request polling, and response submission. Optional native scripts support chainable map.setStyle(url, {diff:false}) and sqs.resourceschange. Styles enable Mercator display; clearing restores geographic display. The shared style facade is documented in style scripts; explicit setProjection remains under development.

Resource retries and fallback URLs documents a serializable policy for both main-thread and Worker hosts. A shared total deadline bounds retries and fallback attempts, including subsequent satellite tile failures. Native, application and mobile integration is still pending.