@procedures/geo 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -3,5 +3,6 @@ export * from "./procedures.js";
 export * from "./geo.js";
 export * from "./distance.js";
 export * from "./geohash.js";
+export * from "./mercator.js";
 export * from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -4,5 +4,6 @@ export * from "./procedures.js";
 export * from "./geo.js";
 export * from "./distance.js";
 export * from "./geohash.js";
+export * from "./mercator.js";
 export * from "./types.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC"}

package/dist/mercator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Web Mercator, the projection of the slippy maps (OpenStreetMap and the others): the pixel of a
+ * point at a zoom level, the zoom that fits points into a box, and the 256-pixel tiles that cover a
+ * view. The functions are pure and need no network, so a browser bundle can use them.
+ */
+/** The size of a map tile, in pixels. */
+export declare const TILE_SIZE = 256;
+/** A position on the world map at one zoom level, in pixels from the top left corner. */
+export interface Pixel {
+    readonly x: number;
+    readonly y: number;
+}
+/** This function gives the pixel of a point (degrees) at a zoom level. */
+export declare const project: (lat: number, lon: number, zoom: number) => Pixel;
+/** The options of `fitZoom`. */
+export interface FitZoomOptions {
+    /** The deepest zoom to try (default 17). */
+    readonly deepest?: number;
+    /** The part of the box that the points can use (default 0.85: a margin of 15 %). */
+    readonly margin?: number;
+    /** The zoom for one point or none, which have no extent (default 14). */
+    readonly single?: number;
+}
+/**
+ * This function gives the deepest zoom at which all the points fit in a box of `width` by
+ * `height` pixels, with a margin. It tries each zoom from `deepest` down, and gives 1 when none fits.
+ */
+export declare const fitZoom: (points: ReadonlyArray<{
+    readonly lat: number;
+    readonly lon: number;
+}>, width: number, height: number, options?: FitZoomOptions) => number;
+/** A tile of a view: its tile numbers (`x` wraps around the world) and its place in the view. */
+export interface ViewTile {
+    readonly x: number;
+    readonly y: number;
+    readonly left: number;
+    readonly top: number;
+}
+/**
+ * This function gives the tiles that a view of `width` by `height` pixels needs, when the top left
+ * corner of the view is at `topLeft`. Each tile has its tile numbers and its position in the view.
+ * The tiles above and below the world are left out.
+ */
+export declare const tilesFor: (topLeft: Pixel, width: number, height: number, zoom: number) => ViewTile[];
+//# sourceMappingURL=mercator.d.ts.map

package/dist/mercator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mercator.d.ts","sourceRoot":"","sources":["../src/mercator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,yCAAyC;AACzC,eAAO,MAAM,SAAS,MAAM,CAAC;AAE7B,yFAAyF;AACzF,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,0EAA0E;AAC1E,eAAO,MAAM,OAAO,QAAS,MAAM,OAAO,MAAM,QAAQ,MAAM,KAAG,KAOhE,CAAC;AAEF,gCAAgC;AAChC,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,OAAO,WACV,aAAa,CAAC;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,SAC9D,MAAM,UACL,MAAM,YACL,cAAc,KACtB,MAYF,CAAC;AAEF,iGAAiG;AACjG,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,YAAa,KAAK,SAAS,MAAM,UAAU,MAAM,QAAQ,MAAM,KAAG,QAAQ,EAe9F,CAAC"}

package/dist/mercator.js

@@ -0,0 +1,57 @@
+/**
+ * Web Mercator, the projection of the slippy maps (OpenStreetMap and the others): the pixel of a
+ * point at a zoom level, the zoom that fits points into a box, and the 256-pixel tiles that cover a
+ * view. The functions are pure and need no network, so a browser bundle can use them.
+ */
+/** The size of a map tile, in pixels. */
+export const TILE_SIZE = 256;
+/** This function gives the pixel of a point (degrees) at a zoom level. */
+export const project = (lat, lon, zoom) => {
+    const scale = TILE_SIZE * 2 ** zoom;
+    const sin = Math.sin((lat * Math.PI) / 180);
+    return {
+        x: ((lon + 180) / 360) * scale,
+        y: (0.5 - Math.log((1 + sin) / (1 - sin)) / (4 * Math.PI)) * scale,
+    };
+};
+/**
+ * This function gives the deepest zoom at which all the points fit in a box of `width` by
+ * `height` pixels, with a margin. It tries each zoom from `deepest` down, and gives 1 when none fits.
+ */
+export const fitZoom = (points, width, height, options = {}) => {
+    if (points.length <= 1)
+        return options.single ?? 14;
+    const margin = options.margin ?? 0.85;
+    for (let zoom = options.deepest ?? 17; zoom > 1; zoom -= 1) {
+        const pixels = points.map((point) => project(point.lat, point.lon, zoom));
+        const xs = pixels.map((pixel) => pixel.x);
+        const ys = pixels.map((pixel) => pixel.y);
+        if (Math.max(...xs) - Math.min(...xs) <= width * margin && Math.max(...ys) - Math.min(...ys) <= height * margin) {
+            return zoom;
+        }
+    }
+    return 1;
+};
+/**
+ * This function gives the tiles that a view of `width` by `height` pixels needs, when the top left
+ * corner of the view is at `topLeft`. Each tile has its tile numbers and its position in the view.
+ * The tiles above and below the world are left out.
+ */
+export const tilesFor = (topLeft, width, height, zoom) => {
+    const count = 2 ** zoom;
+    const out = [];
+    for (let tx = Math.floor(topLeft.x / TILE_SIZE); tx * TILE_SIZE < topLeft.x + width; tx += 1) {
+        for (let ty = Math.floor(topLeft.y / TILE_SIZE); ty * TILE_SIZE < topLeft.y + height; ty += 1) {
+            if (ty < 0 || ty >= count)
+                continue;
+            out.push({
+                x: ((tx % count) + count) % count,
+                y: ty,
+                left: tx * TILE_SIZE - topLeft.x,
+                top: ty * TILE_SIZE - topLeft.y,
+            });
+        }
+    }
+    return out;
+};
+//# sourceMappingURL=mercator.js.map

package/dist/mercator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mercator.js","sourceRoot":"","sources":["../src/mercator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,yCAAyC;AACzC,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,CAAC;AAQ7B,0EAA0E;AAC1E,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,GAAW,EAAE,GAAW,EAAE,IAAY,EAAS,EAAE;IACvE,MAAM,KAAK,GAAG,SAAS,GAAG,CAAC,IAAI,IAAI,CAAC;IACpC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC;IAC5C,OAAO;QACL,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,KAAK;QAC9B,CAAC,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK;KACnE,CAAC;AACJ,CAAC,CAAC;AAYF;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CACrB,MAAqE,EACrE,KAAa,EACb,MAAc,EACd,OAAO,GAAmB,EAAE,EACpB,EAAE;IACV,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;IACpD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC;IACtC,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;QAC3D,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;QAC1E,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC1C,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC1C,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,KAAK,GAAG,MAAM,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,MAAM,GAAG,MAAM,EAAE,CAAC;YAChH,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC,CAAC;AAUF;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAAc,EAAE,KAAa,EAAE,MAAc,EAAE,IAAY,EAAc,EAAE;IAClG,MAAM,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC;IACxB,MAAM,GAAG,GAAe,EAAE,CAAC;IAC3B,KAAK,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,GAAG,KAAK,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC;QAC7F,KAAK,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,GAAG,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC;YAC9F,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK;gBAAE,SAAS;YACpC,GAAG,CAAC,IAAI,CAAC;gBACP,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK;gBACjC,CAAC,EAAE,EAAE;gBACL,IAAI,EAAE,EAAE,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC;gBAChC,GAAG,EAAE,EAAE,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC;aAChC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC"}

package/dist/tiles.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Map tiles on disk, the Node entry `@procedures/geo/tiles`. The root of the package stays
+ * browser-safe, so the functions that read and write files are here.
+ *
+ * A slippy map asks for many tiles in each view. The policy of the OpenStreetMap tile servers
+ * asks each client for a real `User-Agent` and for a cache. `cachedTile` gets a tile from the
+ * server one time, keeps it in a folder, and gives the kept file after that. An area that was
+ * shown one time works without the network.
+ */
+/** A tile of a slippy map: the zoom level, the column and the row. */
+export interface Tile {
+    readonly z: number;
+    readonly x: number;
+    readonly y: number;
+}
+/** The address of the standard tiles of OpenStreetMap. `{z}`, `{x}` and `{y}` are filled in. */
+export declare const OSM_TILES = "https://tile.openstreetmap.org/{z}/{x}/{y}.png";
+/** The fetch that `cachedTile` uses. A test or a host gives its own with the option `fetch`. */
+export type FetchBytes = (url: string, init: {
+    headers: Record<string, string>;
+    signal: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}>;
+/** The options of `cachedTile`. */
+export interface CachedTileOptions {
+    /** The folder of the kept tiles. A tile is kept as `<dir>/<z>/<x>/<y>.<extension>`. */
+    readonly dir: string;
+    /** The `User-Agent` of the requests. The policy of the tile server asks for a real one. */
+    readonly userAgent: string;
+    /** The address of a tile, with `{z}`, `{x}` and `{y}`. The default is `OSM_TILES`. */
+    readonly source?: string | undefined;
+    /** The extension of the kept files. The default is `png`. */
+    readonly extension?: string | undefined;
+    /** The time limit of a request, in milliseconds. The default is 20 000. */
+    readonly timeoutMs?: number | undefined;
+    /** The largest tile, in bytes. A larger body is not a tile. The default is 2 MiB. */
+    readonly maxBytes?: number | undefined;
+    /** This option replaces the global `fetch`. */
+    readonly fetch?: FetchBytes | undefined;
+}
+/**
+ * This function tells if a tile exists at its zoom level: the three numbers are integers, the zoom
+ * is from 0 to `maxZoom`, and the column and the row are from 0 to 2^z - 1.
+ */
+export declare function isTile(tile: Tile, maxZoom?: number): boolean;
+/** This function fills `{z}`, `{x}` and `{y}` of a tile address. */
+export declare function tileUrl(template: string, tile: Tile): string;
+/**
+ * This function gives the bytes of a tile. It reads the kept file when there is one. Otherwise it
+ * gets the tile from the server, keeps it, and gives it.
+ *
+ * - A tile that does not exist (`isTile` with zoom 30) throws a `RangeError`.
+ * - An HTTP error, no answer in the time limit, or a body larger than `maxBytes` throws an `Error`.
+ *   Then the function keeps nothing.
+ * - The file is written to a temporary name first, then renamed. A stop during the write never
+ *   leaves a part of a tile.
+ */
+export declare function cachedTile(tile: Tile, options: CachedTileOptions): Promise<Uint8Array>;
+//# sourceMappingURL=tiles.d.ts.map

package/dist/tiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiles.d.ts","sourceRoot":"","sources":["../src/tiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,sEAAsE;AACtE,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,gGAAgG;AAChG,eAAO,MAAM,SAAS,mDAAmD,CAAC;AAE1E,gGAAgG;AAChG,MAAM,MAAM,UAAU,GAAG,CACvB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,KAC3D,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;CAAE,CAAC,CAAC;AAEnF,mCAAmC;AACnC,MAAM,WAAW,iBAAiB;IAChC,uFAAuF;IACvF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,2FAA2F;IAC3F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sFAAsF;IACtF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,SAAK,GAAG,OAAO,CAMxD;AAED,oEAAoE;AACpE,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,CAE5D;AAID;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CA4B5F"}

package/dist/tiles.js

@@ -0,0 +1,76 @@
+/**
+ * Map tiles on disk, the Node entry `@procedures/geo/tiles`. The root of the package stays
+ * browser-safe, so the functions that read and write files are here.
+ *
+ * A slippy map asks for many tiles in each view. The policy of the OpenStreetMap tile servers
+ * asks each client for a real `User-Agent` and for a cache. `cachedTile` gets a tile from the
+ * server one time, keeps it in a folder, and gives the kept file after that. An area that was
+ * shown one time works without the network.
+ */
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/** The address of the standard tiles of OpenStreetMap. `{z}`, `{x}` and `{y}` are filled in. */
+export const OSM_TILES = "https://tile.openstreetmap.org/{z}/{x}/{y}.png";
+/**
+ * This function tells if a tile exists at its zoom level: the three numbers are integers, the zoom
+ * is from 0 to `maxZoom`, and the column and the row are from 0 to 2^z - 1.
+ */
+export function isTile(tile, maxZoom = 19) {
+    const { z, x, y } = tile;
+    if (!Number.isSafeInteger(z) || !Number.isSafeInteger(x) || !Number.isSafeInteger(y))
+        return false;
+    if (z < 0 || z > maxZoom)
+        return false;
+    const size = 2 ** z;
+    return x >= 0 && y >= 0 && x < size && y < size;
+}
+/** This function fills `{z}`, `{x}` and `{y}` of a tile address. */
+export function tileUrl(template, tile) {
+    return template.replace("{z}", String(tile.z)).replace("{x}", String(tile.x)).replace("{y}", String(tile.y));
+}
+let written = 0;
+/**
+ * This function gives the bytes of a tile. It reads the kept file when there is one. Otherwise it
+ * gets the tile from the server, keeps it, and gives it.
+ *
+ * - A tile that does not exist (`isTile` with zoom 30) throws a `RangeError`.
+ * - An HTTP error, no answer in the time limit, or a body larger than `maxBytes` throws an `Error`.
+ *   Then the function keeps nothing.
+ * - The file is written to a temporary name first, then renamed. A stop during the write never
+ *   leaves a part of a tile.
+ */
+export async function cachedTile(tile, options) {
+    if (!isTile(tile, 30))
+        throw new RangeError(`cachedTile: ${JSON.stringify(tile)} is not a tile`);
+    const file = join(options.dir, String(tile.z), String(tile.x), `${String(tile.y)}.${options.extension ?? "png"}`);
+    try {
+        return new Uint8Array(await readFile(file));
+    }
+    catch {
+        // Not kept yet: get it one time
+    }
+    const url = tileUrl(options.source ?? OSM_TILES, tile);
+    const timeoutMs = options.timeoutMs ?? 20_000;
+    const fetchBytes = options.fetch ?? fetch;
+    let response;
+    try {
+        response = await fetchBytes(url, { headers: { "user-agent": options.userAgent }, signal: AbortSignal.timeout(timeoutMs) });
+    }
+    catch (error) {
+        const reason = error.name === "TimeoutError" ? `no answer in ${String(timeoutMs)} ms` : "the request failed";
+        throw new Error(`The tile server did not answer for ${url}: ${reason}`);
+    }
+    if (!response.ok)
+        throw new Error(`The tile server gave HTTP ${String(response.status)} for ${url}`);
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const maxBytes = options.maxBytes ?? 2 * 1024 * 1024;
+    if (bytes.byteLength > maxBytes)
+        throw new Error(`The body for ${url} has ${String(bytes.byteLength)} bytes, more than a tile (${String(maxBytes)})`);
+    await mkdir(dirname(file), { recursive: true });
+    written += 1;
+    const temporary = `${file}.${String(process.pid)}-${String(written)}.tmp`;
+    await writeFile(temporary, bytes);
+    await rename(temporary, file);
+    return bytes;
+}
+//# sourceMappingURL=tiles.js.map

package/dist/tiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiles.js","sourceRoot":"","sources":["../src/tiles.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/geo",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Map procedures: the coordinates of an address (OpenStreetMap Nominatim), the time and distance of a drive (OSRM), the great-circle distance and the geohash.",
   "keywords": [
     "geocode",
@@ -39,6 +39,10 @@
     "./register": {
       "types": "./dist/register.d.ts",
       "import": "./dist/register.js"
+    },
+    "./tiles": {
+      "types": "./dist/tiles.d.ts",
+      "import": "./dist/tiles.js"
     }
   },
   "files": [
@@ -60,7 +64,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@procedures/client": "0.6.0",
+    "@procedures/client": "0.8.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/src/index.ts

@@ -4,4 +4,5 @@ export * from "./procedures.js";
 export * from "./geo.js";
 export * from "./distance.js";
 export * from "./geohash.js";
+export * from "./mercator.js";
 export * from "./types.js";

package/src/mercator.ts

@@ -0,0 +1,87 @@
+/**
+ * Web Mercator, the projection of the slippy maps (OpenStreetMap and the others): the pixel of a
+ * point at a zoom level, the zoom that fits points into a box, and the 256-pixel tiles that cover a
+ * view. The functions are pure and need no network, so a browser bundle can use them.
+ */
+
+/** The size of a map tile, in pixels. */
+export const TILE_SIZE = 256;
+
+/** A position on the world map at one zoom level, in pixels from the top left corner. */
+export interface Pixel {
+  readonly x: number;
+  readonly y: number;
+}
+
+/** This function gives the pixel of a point (degrees) at a zoom level. */
+export const project = (lat: number, lon: number, zoom: number): Pixel => {
+  const scale = TILE_SIZE * 2 ** zoom;
+  const sin = Math.sin((lat * Math.PI) / 180);
+  return {
+    x: ((lon + 180) / 360) * scale,
+    y: (0.5 - Math.log((1 + sin) / (1 - sin)) / (4 * Math.PI)) * scale,
+  };
+};
+
+/** The options of `fitZoom`. */
+export interface FitZoomOptions {
+  /** The deepest zoom to try (default 17). */
+  readonly deepest?: number;
+  /** The part of the box that the points can use (default 0.85: a margin of 15 %). */
+  readonly margin?: number;
+  /** The zoom for one point or none, which have no extent (default 14). */
+  readonly single?: number;
+}
+
+/**
+ * This function gives the deepest zoom at which all the points fit in a box of `width` by
+ * `height` pixels, with a margin. It tries each zoom from `deepest` down, and gives 1 when none fits.
+ */
+export const fitZoom = (
+  points: ReadonlyArray<{ readonly lat: number; readonly lon: number }>,
+  width: number,
+  height: number,
+  options: FitZoomOptions = {}
+): number => {
+  if (points.length <= 1) return options.single ?? 14;
+  const margin = options.margin ?? 0.85;
+  for (let zoom = options.deepest ?? 17; zoom > 1; zoom -= 1) {
+    const pixels = points.map((point) => project(point.lat, point.lon, zoom));
+    const xs = pixels.map((pixel) => pixel.x);
+    const ys = pixels.map((pixel) => pixel.y);
+    if (Math.max(...xs) - Math.min(...xs) <= width * margin && Math.max(...ys) - Math.min(...ys) <= height * margin) {
+      return zoom;
+    }
+  }
+  return 1;
+};
+
+/** A tile of a view: its tile numbers (`x` wraps around the world) and its place in the view. */
+export interface ViewTile {
+  readonly x: number;
+  readonly y: number;
+  readonly left: number;
+  readonly top: number;
+}
+
+/**
+ * This function gives the tiles that a view of `width` by `height` pixels needs, when the top left
+ * corner of the view is at `topLeft`. Each tile has its tile numbers and its position in the view.
+ * The tiles above and below the world are left out.
+ */
+export const tilesFor = (topLeft: Pixel, width: number, height: number, zoom: number): ViewTile[] => {
+  const count = 2 ** zoom;
+  const out: ViewTile[] = [];
+  for (let tx = Math.floor(topLeft.x / TILE_SIZE); tx * TILE_SIZE < topLeft.x + width; tx += 1) {
+    for (let ty = Math.floor(topLeft.y / TILE_SIZE); ty * TILE_SIZE < topLeft.y + height; ty += 1) {
+      if (ty < 0 || ty >= count) continue;
+      out.push({
+        x: ((tx % count) + count) % count,
+        y: ty,
+        left: tx * TILE_SIZE - topLeft.x,
+        top: ty * TILE_SIZE - topLeft.y,
+      });
+    }
+  }
+  return out;
+};

package/src/tiles.ts

@@ -0,0 +1,105 @@
+/**
+ * Map tiles on disk, the Node entry `@procedures/geo/tiles`. The root of the package stays
+ * browser-safe, so the functions that read and write files are here.
+ *
+ * A slippy map asks for many tiles in each view. The policy of the OpenStreetMap tile servers
+ * asks each client for a real `User-Agent` and for a cache. `cachedTile` gets a tile from the
+ * server one time, keeps it in a folder, and gives the kept file after that. An area that was
+ * shown one time works without the network.
+ */
+
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+/** A tile of a slippy map: the zoom level, the column and the row. */
+export interface Tile {
+  readonly z: number;
+  readonly x: number;
+  readonly y: number;
+}
+
+/** The address of the standard tiles of OpenStreetMap. `{z}`, `{x}` and `{y}` are filled in. */
+export const OSM_TILES = "https://tile.openstreetmap.org/{z}/{x}/{y}.png";
+
+/** The fetch that `cachedTile` uses. A test or a host gives its own with the option `fetch`. */
+export type FetchBytes = (
+  url: string,
+  init: { headers: Record<string, string>; signal: AbortSignal }
+) => Promise<{ ok: boolean; status: number; arrayBuffer(): Promise<ArrayBuffer> }>;
+
+/** The options of `cachedTile`. */
+export interface CachedTileOptions {
+  /** The folder of the kept tiles. A tile is kept as `<dir>/<z>/<x>/<y>.<extension>`. */
+  readonly dir: string;
+  /** The `User-Agent` of the requests. The policy of the tile server asks for a real one. */
+  readonly userAgent: string;
+  /** The address of a tile, with `{z}`, `{x}` and `{y}`. The default is `OSM_TILES`. */
+  readonly source?: string | undefined;
+  /** The extension of the kept files. The default is `png`. */
+  readonly extension?: string | undefined;
+  /** The time limit of a request, in milliseconds. The default is 20 000. */
+  readonly timeoutMs?: number | undefined;
+  /** The largest tile, in bytes. A larger body is not a tile. The default is 2 MiB. */
+  readonly maxBytes?: number | undefined;
+  /** This option replaces the global `fetch`. */
+  readonly fetch?: FetchBytes | undefined;
+}
+
+/**
+ * This function tells if a tile exists at its zoom level: the three numbers are integers, the zoom
+ * is from 0 to `maxZoom`, and the column and the row are from 0 to 2^z - 1.
+ */
+export function isTile(tile: Tile, maxZoom = 19): boolean {
+  const { z, x, y } = tile;
+  if (!Number.isSafeInteger(z) || !Number.isSafeInteger(x) || !Number.isSafeInteger(y)) return false;
+  if (z < 0 || z > maxZoom) return false;
+  const size = 2 ** z;
+  return x >= 0 && y >= 0 && x < size && y < size;
+}
+
+/** This function fills `{z}`, `{x}` and `{y}` of a tile address. */
+export function tileUrl(template: string, tile: Tile): string {
+  return template.replace("{z}", String(tile.z)).replace("{x}", String(tile.x)).replace("{y}", String(tile.y));
+}
+
+let written = 0;
+
+/**
+ * This function gives the bytes of a tile. It reads the kept file when there is one. Otherwise it
+ * gets the tile from the server, keeps it, and gives it.
+ *
+ * - A tile that does not exist (`isTile` with zoom 30) throws a `RangeError`.
+ * - An HTTP error, no answer in the time limit, or a body larger than `maxBytes` throws an `Error`.
+ *   Then the function keeps nothing.
+ * - The file is written to a temporary name first, then renamed. A stop during the write never
+ *   leaves a part of a tile.
+ */
+export async function cachedTile(tile: Tile, options: CachedTileOptions): Promise<Uint8Array> {
+  if (!isTile(tile, 30)) throw new RangeError(`cachedTile: ${JSON.stringify(tile)} is not a tile`);
+  const file = join(options.dir, String(tile.z), String(tile.x), `${String(tile.y)}.${options.extension ?? "png"}`);
+  try {
+    return new Uint8Array(await readFile(file));
+  } catch {
+    // Not kept yet: get it one time
+  }
+  const url = tileUrl(options.source ?? OSM_TILES, tile);
+  const timeoutMs = options.timeoutMs ?? 20_000;
+  const fetchBytes: FetchBytes = options.fetch ?? fetch;
+  let response: Awaited<ReturnType<FetchBytes>>;
+  try {
+    response = await fetchBytes(url, { headers: { "user-agent": options.userAgent }, signal: AbortSignal.timeout(timeoutMs) });
+  } catch (error) {
+    const reason = (error as { name?: string }).name === "TimeoutError" ? `no answer in ${String(timeoutMs)} ms` : "the request failed";
+    throw new Error(`The tile server did not answer for ${url}: ${reason}`);
+  }
+  if (!response.ok) throw new Error(`The tile server gave HTTP ${String(response.status)} for ${url}`);
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  const maxBytes = options.maxBytes ?? 2 * 1024 * 1024;
+  if (bytes.byteLength > maxBytes) throw new Error(`The body for ${url} has ${String(bytes.byteLength)} bytes, more than a tile (${String(maxBytes)})`);
+  await mkdir(dirname(file), { recursive: true });
+  written += 1;
+  const temporary = `${file}.${String(process.pid)}-${String(written)}.tmp`;
+  await writeFile(temporary, bytes);
+  await rename(temporary, file);
+  return bytes;
+}