fgb-vt - v1.0.6
    Preparing search index...

    Class TileServer

    Stateful tile server with lazy header caching and multi-connector support.

    All connectors and sources are bound at construction. Tile requests take only coordinates. FGB headers and spatial indices are cached per source path on first access, amortizing I/O overhead across the lifetime of the instance.

    Use case: long-running tile server process with a fixed set of FGB sources. Maximum throughput -- all per-source overhead is amortized after the first request.

    const server = new TileServer({
      connector: new LocalConnector(),
      sources: [
        { name: 'buildings', path: './data/buildings.fgb' },
        { name: 'roads', path: './data/roads.fgb', options: { maxZoom: 16 } },
      ],
    });

    const pbf = await server.tile(14, 8192, 5461);
    await server.close();

    const server = new TileServer([
      {
        connector: new LocalConnector(),
        sources: { name: 'boundaries', path: './data/boundaries.fgb' },
      },
      {
        connector: new HttpConnector(),
        sources: { name: 'imagery-grid', path: 'https://tiles.example.com/grid.fgb' },
      },
    ]);

    const metadata = await server.tileJSON();
    const pbf = await server.tile(10, 512, 341);
    await server.close();
    Index
    constructor
    close invalidate open tile tileETag tileJSON

    • Create a new tile server with the given layer configuration.

      Accepts a single layer or an array of layers. Each layer binds a connector to one or more sources. Sources across layers may use different connectors (e.g. local files + HTTP endpoints).

      Parameters

      • layers: TileServerLayer | TileServerLayer[]

        One or more layer configurations binding connectors to sources. A single TileServerLayer is accepted for convenience.

      • Optionaloptions: TileOptions & IoOptions & Pick<RequestOptions, "onTile">

        Tile-level tiling option defaults applied to all sources unless overridden by per-source options, plus I/O options (cache, prefetch, range merging, scan budget) and a default onTile hook.

      Returns TileServer

      If a source has no name or path.

      If an option is invalid.

    • Release all connector resources and cached state.

      Clears the instance's own cache (a caller-supplied cache is left untouched) and closes every unique connector. After calling close(), this server instance must not be used again.

      Returns Promise<void>

      Resolves when all connectors have been closed.

    • Forget what is cached about a file, so the next request re-reads its header and index, e.g. after the file was replaced at the same path. Without a path, every configured source is forgotten.

      Files with version tags (ETags, file metadata) are detected as changed automatically; this is for connectors and servers that report none.

      Parameters

      • Optionalpath: string

        Source path, or omitted for all sources.

      Returns Promise<void>

      Resolves when the entries are removed from the cache.

    • Open every configured source ahead of the first tile request: read headers and the top of each spatial index and, within the OpenOptions.warmIndex budget, all upper index levels.

      Opening is otherwise lazy. Call this at start-up (or in the init phase of a serverless function) to move that I/O out of the first requests.

      Parameters

      Returns Promise<void>

      Resolves when every source is open.

      If a source cannot be opened (annotated with its path).

    • Render a vector tile as a PBF-encoded MVT.

      Layers appear in the output in the order defined at construction time. Sources are opened on first use and their headers and index pages cached for subsequent calls.

      Parameters

      • z: number

        Tile zoom level.

      • x: number

        Tile column.

      • y: number

        Tile row.

      • Optionalrequest: RequestOptions

        Optional abort signal and onTile hook (overrides the constructor's).

      Returns Promise<Uint8Array<ArrayBufferLike>>

      PBF-encoded Mapbox Vector Tile. Returns an empty tile if no features intersect the requested tile bounds.

      If z/x/y is not a valid tile.

      If a source cannot be read or a budget is exceeded (annotated with the source path); I/O failures are a ConnectorError whose status maps to an HTTP status.

    • Compute the ETag of a tile without rendering it, e.g. to answer If-None-Match with 304 Not Modified (or to let a CDN revalidate). It changes whenever a source file, a setting or the library's tile encoding changes; sources outside their zoom range are not opened.

      Parameters

      • z: number

        Tile zoom level.

      • x: number

        Tile column.

      • y: number

        Tile row.

      • Optionalrequest: Pick<RequestOptions, "signal">

        Optional abort signal.

      Returns Promise<string | null>

      A strong, quoted ETag, or null when a source's connector reports no version tag.

      If a source cannot be opened (annotated with its path).

      const etag = await server.tileETag(z, x, y);
      if (etag && req.headers['if-none-match'] === etag) return res.writeHead(304).end();
      const pbf = await server.tile(z, x, y);
      res.writeHead(200, { 'Content-Type': 'application/vnd.mapbox-vector-tile', ...(etag ? { ETag: etag } : {}) });

    • Generate TileJSON 3.0.0 metadata derived from all configured sources.

      Returns aggregated bounds, zoom range, and a vector_layers array listing each source's layer name, field schema, and zoom range. Sources are opened (headers read) if not already open.

      • tiles: the URL templates from options (required by the TileJSON spec; empty when not given).
      • name / description: from options, or, for a single source, the file's header title (or name) and description.
      • bounds: each file's header envelope or, when that is absent or invalid, the root of its spatial index, converted to WGS 84. Without either (an unindexed file without envelope) the world is assumed.
      • minzoom / maxzoom: the lowest minZoom and highest maxZoom of the sources, as the zoom levels served (integers from 0 to 30).
      • fields: the columns actually written as properties, after the source's properties selection and without the id column (unless kept) and binary columns.
      • Sources sharing a name are listed as one layer (fields combined, zoom range covering all of them), as they are merged in tiles.

      Parameters

      Returns Promise<TileJSON>

      TileJSON metadata object conforming to the 3.0.0 specification.

      If a source cannot be opened (annotated with its path).

    Settings
    Member Visibility

    On This Page
    Constructors
    Methods