chiitiler 1.14.2 → 1.16.0

package/README.md

@@ -1,281 +1,314 @@
-# chiitiler - The Tiny MapLibre Server
+# chiitiler – Tiny MapLibre Server
 
 ![GitHub Release](https://img.shields.io/github/v/release/Kanahiro/chiitiler?label=ghcr.io/kanahiro/chiitiler)
-![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Kanahiro/chiitiler/test:unit.yml?label=unittest)
-![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Kanahiro/chiitiler/test:integration.yml?label=integrationtest)
+![Unit Tests](https://img.shields.io/github/actions/workflow/status/Kanahiro/chiitiler/test:unit.yml?label=unit%20tests)
+![Integration Tests](https://img.shields.io/github/actions/workflow/status/Kanahiro/chiitiler/test:integration.yml?label=integration)
 [![codecov](https://codecov.io/gh/Kanahiro/chiitiler/graph/badge.svg?token=9RVLAJG126)](https://codecov.io/gh/Kanahiro/chiitiler)
 
-![](./logo.webp)*generated by DALL-E*
+![chiitiler logo](./logo.webp)
 
-chii-tiler: "tiny" in Japanese is "chiisai", shorten into "chii"
+> Chiitiler is a tiny MapLibre server that renders raster tiles and map cut-outs from any MapLibre Style JSON, with built-in caching backends for source assets and a lightweight debug UI.
 
-## motivation
+## Overview
 
-- In this type of server, there is a de-facto - [maptiler/tileserver-gl](https://github.com/maptiler/tileserver-gl), but this is too big for me.
-- I want a server accept style.json-url and respond raster tile, inspired by [developmentseed/titiler](https://github.com/developmentseed/titiler)
+Chiitiler accepts remote or local `style.json` definitions and serves raster tiles or bounding-box images on demand. It was inspired by [`maptiler/tileserver-gl`](https://github.com/maptiler/tileserver-gl) and [`developmentseed/titiler`](https://github.com/developmentseed/titiler) but is intentionally minimal, scriptable, and easy to self-host.
 
-## usecases
+### Highlights
 
-- [MIERUNE/tiles](https://github.com/MIERUNE/tiles) - You can find example [here](https://mierune.github.io/tiles/color.html#11.62/43.064/141.3375)
-- [dayjournal/qgis-amazonlocationservice-plugin](https://github.com/dayjournal/qgis-amazonlocationservice-plugin) - used in Maps feature
-- [Allmaps Latest - Bluesky](https://bsky.app/profile/latest.allmaps.org)
+- Zero-config startup: point Chiitiler at a style URL or POST a style object to receive tiles.
+- Optimized for ephemeral serverless runtimes such as AWS Lambda.
+- Multiple cache adapters (`memory`, `file`, `s3`, `gcs`) to cache shared source assets (MVT tiles, glyphs, sprites) and reduce redundant fetches.
+- Built-in `/debug` and `/editor` pages to preview styles during development.
 
-## features
+### In Production
 
-### /tiles
+- [MIERUNE/tiles](https://github.com/MIERUNE/tiles) – see the live example [map](https://mierune.github.io/tiles/color.html#11.62/43.064/141.3375).
+- [dayjournal/qgis-amazonlocationservice-plugin](https://github.com/dayjournal/qgis-amazonlocationservice-plugin) – powering QGIS integrations.
+- [PLATEAU VIEW](https://plateauview.mlit.go.jp/) – serving Cesium.js imagery through the `/tiles` endpoint.
+- [Allmaps Latest (Bluesky)](https://bsky.app/profile/latest.allmaps.org).
 
-chiitiler provides you with an endpoint `/tiles`. Once server launched, you can use the endpoint like this:
+## Supported Data Protocols
 
-```planetext
-http://localhost:3000/tiles/0/0/0.png?url=https://tile.openstreetmap.jp/styles/osm-bright/style.json
-http://localhost:3000/tiles/0/0/0.webp?margin=100&url=https://tile.openstreetmap.jp/styles/maptiler-toner-en/style.json
-http://localhost:3000/tiles/1/1/1.jpg?tileSize=256&quality=80&url=https://tile.openstreetmap.jp/styles/osm-bright/style.json
-```
+Chiitiler can load tiles, sprites, glyphs, and assets via:
 
-### /clip.png|webp|jpg|jpeg
+- `http://` and `https://`
+- `s3://` (AWS S3 or compatible endpoints)
+- `gs://` (Google Cloud Storage)
+- `file://`
+- `mbtiles://`
+- `pmtiles://`
+- `cog://` (Cloud Optimized GeoTIFF, CRS must be `EPSG:3857`)
 
-chiitiler provides you with `/clip.png|webp|jpg|jpeg` endpoint. Once server launched, you can use like this:
+## Project Layout
 
-```planetext
-# default size is 1024, this is longer axis and shorter axis is calculated by aspect ratio
-http://localhost:3000/clip.png?bbox=100,30,150,60&url=https://path/to/style.json
-# specify size
-http://localhost:3000/clip.png?bbox=100,30,150,6&size=512&url=https://path/to/style.json
-# specify quality
-http://localhost:3000/clip.png?bbox=100,30,150,6&size=512&quality=80&url=https://path/to/style.json
+```
+src/
+  main.ts           # CLI entry point and cluster bootstrap
+  cli.ts            # Commander-based CLI definition
+  server/           # Hono HTTP server & debug UI
+  render/           # Rasterization and Sharp pipelines
+  cache/            # Cache adapters (none/memory/file/s3/gcs)
+  source/           # Helpers for reading external sources
+tests/              # Vitest integration & benchmark suites
+localdata/          # Sample styles and tiles for demos
+cdk/                # AWS CDK deployment project
 ```
 
-#### POST endpoint
+## Quick Start
 
-Each endpoint also supports POST method. You can pass style.json as a body. (then, url parameter is not needed)
+### Requirements
 
-## architecture
+- Node.js 20.10.0 or newer (`.node-version` is provided).
+- System dependencies to support `sharp` (see [Dockerfile](./Dockerfile) for reference).
 
-```mermaid
-graph LR
-    subgraph sources
-        direction LR
-        A[style.json]
-        z/x/y.pbf
-        z/x/y.png/webp/jpg
-        sprite
-        glyphs
-    end
+### Run From Source
 
-    subgraph chiitiler
-        cache
-        render
-        server
-    end
+```bash
+git clone https://github.com/Kanahiro/chiitiler.git
+cd chiitiler
+npm install
+npx tsx src/main.ts tile-server --port 3000 --debug
+```
 
-sources --> cache --> render --> server --/tiles/z/x/y--> png/webp/jpg
+When the server starts you can request a tile:
 
-cache <--get/set--> memory/file/S3
+```
+http://localhost:3000/tiles/0/0/0.png?url=https://tile.openstreetmap.jp/styles/osm-bright/style.json
 ```
 
-## usage
+### Docker Image
 
-### Container Image
+```bash
+docker pull ghcr.io/kanahiro/chiitiler:latest
+docker run --rm -p 3000:3000 \
+  -e CHIITILER_CACHE_METHOD=memory \
+  -e CHIITILER_CACHE_TTL_SEC=600 \
+  ghcr.io/kanahiro/chiitiler:latest
+```
 
-```sh
-docker pull ghcr.io/kanahiro/chiitiler
-docker run -p 3000:3000 ghcr.io/kanahiro/chiitiler # -> tile-server
+The container entrypoint wraps `node /app/build/main.cjs tile-server`, so command-line options can be provided via env vars or by overriding the container CMD explicitly.
 
-# recommended: you can use environment variables
-docker run -p 3000:3000 -d \
--e CHIITILER_CACHE_METHOD=s3 \
--e CHIITILER_S3CACHE_BUCKET=bucketname \
--e CHIITILER_S3_REGION=ap-northeast-1 \
-ghcr.io/kanahiro/chiitiler
-```
+#### docker-compose (local S3 + GCS emulation)
+
+The included [`docker-compose.yml`](./docker-compose.yml) spins up MinIO and `fake-gcs-server`:
 
-#### Environment Variables
-
-you can pass server options via environment variables
-
-| env var                            | default  | description                                    |
-| ---------------------------------- | -------- | ---------------------------------------------- |
-| CHIITILER_PORT                     | 3000     | port number                                    |
-| CHIITILER_PROCESSES                | 1        | num of chiitiler processes. 0 means all-CPUs   |
-| CHIITILER_DEBUG                    | false    | debug mode                                     |
-| CHIITILER_STREAM_MODE              | false    | stream mode                                    |
-| CHIITILER_CACHE_METHOD             | none     | cache method, `none`, `memory`, `file` or `s3` |
-| CHIITILER_CACHE_TTL_SEC            | 3600     | cache ttl, effect to `memory` and `file`       |
-| CHIITILER_MEMORYCACHE_MAXITEMCOUNT | 1000     | max items for memorycache                      |
-| CHIITILER_FILECACHE_DIR            | .cache   | filecache directory                            |
-| CHIITILER_S3CACHE_BUCKET           |          | s3cache bucket name                            |
-| CHIITILER_S3_REGION                | us-east1 | s3 bucket region for caching/fetching          |
-| CHIITILER_S3_ENDPOINT              |          | s3 endpoint for caching/fetching               |
-| CHIITILER_S3_FORCE_PATH_STYLE      | false    | force path style for s3, needed for minio      |
-
-### debug page
-
-- in debug mode, you can access:
-  - debug page: <http://localhost:3000/debug>
-    - You can pass style.json url: <http://localhost:3000/debug?url=https://tile.openstreetmap.jp/styles/osm-bright/style.json>
-  - editor page: <http://localhost:3000/editor>
-
-## supported protocols in style.json
-
-- `http://` or `https://` protocol are used in Style Specification
-- In addition, chiitiler supports following protocols:
-  - `s3://` for S3 bucket
-  - `file://` for file system
-  - `mbtiles://` for MBTIles files
-  - `pmtiles://` for PMTiles, remote or local or s3
-  - `cog://` experimental, for Cloud Optimized GeoTIFF. CRS must be EPSG:3857.
-- Only when `http://` and `https://` chiitiler cache them with a method you specified.
-
-### example
-
-[./localdata/style.json](./localdata/style.json)
-
-```json
-{
-  "version": "8",
-  "sources": {
-    "dir": {
-      "type": "vector",
-      "tiles": [
-        "file://localdata/tiles/{z}/{x}/{y}.pbf"
-      ],
-      "maxzoom": 6
-    },
-    "mbtiles": {
-      "type": "vector",
-      "tiles": [
-        "mbtiles://localdata/school.mbtiles/{z}/{x}/{y}"
-      ],
-      "maxzoom": 10
-    },
-    "pmtiles": {
-      "type": "vector",
-      "tiles": [
-        "pmtiles://localdata/school.pmtiles/{z}/{x}/{y}"
-      ],
-      "maxzoom": 10
-    },
-    "s3": {
-      "type": "vector",
-      "tiles": [
-        "s3://tiles/{z}/{x}/{y}.pbf"
-      ],
-      "maxzoom": 6
-    },
-    "cog": {
-      "type": "raster",
-      "tiles": [
-        "cog://https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/54/T/WN/2024/9/S2A_54TWN_20240908_0_L2A/TCI.tif/{z}/{x}/{y}"
-      ],
-      "tileSize": 256
-    }
-  },
-  "layers": [
-    {
-      "id": "dir",
-      "source": "dir",
-      "source-layer": "P2921",
-      "type": "circle",
-      "paint": {
-        "circle-radius": 10,
-        "circle-color": "red"
-      }
-    },
-    {
-      "id": "mbtiles",
-      "source": "mbtiles",
-      "source-layer": "P2921",
-      "type": "circle",
-      "paint": {
-        "circle-radius": 7,
-        "circle-color": "blue"
-      }
-    },
-    {
-      "id": "pmtiles",
-      "source": "pmtiles",
-      "source-layer": "P2921",
-      "type": "circle",
-      "paint": {
-        "circle-radius": 5,
-        "circle-color": "yellow"
-      }
-    },
-    {
-      "id": "s3",
-      "source": "s3",
-      "source-layer": "P2921",
-      "type": "circle",
-      "paint": {
-        "circle-radius": 3,
-        "circle-color": "green"
-      }
-    },
-    {
-      "id": "cog",
-      "source": "cog",
-      "type": "raster",
-      "paint": {
-        "raster-opacity": 0.5
-      }
-    }
-  ]
-}
+```bash
+docker compose up
 ```
 
-## Library Mode
+Volumes mount `localdata/` and `.cache/` so test assets and cached source data persist between runs.
+
+## HTTP API
+
+| Method | Path Pattern | Description |
+| ------ | ------------ | ----------- |
+| GET/POST | `/tiles/{z}/{x}/{y}.{ext}` | Render a raster tile (`png`, `jpeg`, `jpg`, `webp`). |
+| GET/POST | `/clip.{ext}` | Render a bounding box image (`png`, `jpeg`, `jpg`, `webp`). |
+| GET/POST | `/static/{lon},{lat},{zoom}[@{bearing}][,{pitch}]/{width}x{height}.{ext}` | Render a static image (`png`, `jpeg`, `jpg`, `webp`). |
+| GET | `/debug` | Style explorer UI (requires debug mode). |
+| GET | `/editor` | Lightweight style editor (requires debug mode). |
 
-- chiitiler can be used as a library to render MapLibre Style.
-- methods to render MapLibre Style are exposed from `chiitiler` package.
+### Query Parameters
 
-### installation
+- `url` – Required when using GET. Points to a MapLibre Style JSON.
+- `tileSize` – Tile size in pixels (default `512`).
+- `quality` – JPEG/WebP quality (default `100`).
+- `margin` – Tile edge margin (default `0`).
+- `bbox` – Bounding box for `/clip` as `minLon,minLat,maxLon,maxLat`.
+- `size` – Longest edge of `/clip` output (default `1024`).
 
-```sh
-npm install chiitiler
+POST requests accept the style object directly in the JSON body (`{ "style": { ... } }`).
+
+### Streaming Responses
+
+Enable streaming (Sharp pipeline without buffering) by setting `CHIITILER_STREAM_MODE=true` or passing `--stream`.
+
+## CLI Reference
+
+Chiitiler exposes a single command: `tile-server`.
+
+```bash
+npx tsx src/main.ts tile-server --help
 ```
 
-- chiitiler requires some dependencies in runtime, you can find them in [Dockerfile](./Dockerfile)
+| Option | Description | Environment Fallback | Default |
+| ------ | ----------- | -------------------- | ------- |
+| `--cache <none/memory/file/s3/gcs>` | Select cache backend. | `CHIITILER_CACHE_METHOD` | `none` |
+| `--cache-ttl <seconds>` | TTL for memory/file caches. | `CHIITILER_CACHE_TTL_SEC` | `3600` |
+| `--memory-cache-max-item-count <n>` | Max items in memory cache. | `CHIITILER_MEMORYCACHE_MAXITEMCOUNT` | `1000` |
+| `--file-cache-dir <dir>` | Disk cache directory. | `CHIITILER_FILECACHE_DIR` | `./.cache` |
+| `--s3-cache-bucket <name>` | S3 bucket for caching. | `CHIITILER_S3CACHE_BUCKET` | `""` |
+| `--s3-region <region>` | S3 region used for requests. | `CHIITILER_S3_REGION` | `us-east1` |
+| `--s3-endpoint <url>` | S3-compatible endpoint. | `CHIITILER_S3_ENDPOINT` | `""` |
+| `--s3-force-path-style` | Force path-style requests. | `CHIITILER_S3_FORCE_PATH_STYLE` (`true/false`) | `false` |
+| `--gcs-cache-bucket <name>` | GCS bucket for caching. | `CHIITILER_GCS_CACHE_BUCKET` | `""` |
+| `--gcs-project-id <id>` | GCP project ID. | `CHIITILER_GCS_PROJECT_ID` | `""` |
+| `--gcs-key-filename <path>` | Service account JSON. | `CHIITILER_GCS_KEY_FILENAME` | `""` |
+| `--gcs-cache-prefix <prefix>` | GCS object prefix. | `CHIITILER_GCS_CACHE_PREFIX` | `""` |
+| `--gcs-api-endpoint <url>` | Custom GCS endpoint. | `CHIITILER_GCS_API_ENDPOINT` | `""` |
+| `--port <number>` | HTTP listen port. | `CHIITILER_PORT` | `3000` |
+| `--stream` | Enable streaming mode. | `CHIITILER_STREAM_MODE` | `false` |
+| `--debug` | Enable debug UI routes. | `CHIITILER_DEBUG` | `false` |
+
+Set `CHIITILER_PROCESSES` to control clustering (`0` uses all CPUs). When `>1`, the primary process forks workers that all share the same cache adapter.
+
+## Environment Variables
+
+In addition to the CLI options above, the server respects:
+
+| Variable | Default | Notes |
+| -------- | ------- | ----- |
+| `CHIITILER_PROCESSES` | `1` | Number of worker processes; `0` = `availableParallelism()`. |
+| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | – | Used by the S3 cache adapter. |
+| `AWS_REGION` | – | Overrides SDK default region if set. |
+| `GOOGLE_APPLICATION_CREDENTIALS` | – | Path to a service account JSON used by the GCS adapter. |
+
+## Cache Backends
+
+Chiitiler caches the source material required for rendering (vector tiles, glyphs, sprites, spritesheets), not the final raster outputs. These cached assets are reused across requests to avoid refetching upstream sources.
+
+- **none** – No caching; every request renders from scratch.
+- **memory** – In-memory LRU cache with configurable TTL and max entries.
+- **file** – Stores fetched source assets under `CHIITILER_FILECACHE_DIR`.
+- **s3** – Uploads cached source assets to S3/MinIO; honors custom endpoint and path-style.
+- **gcs** – Uploads cached source assets to Google Cloud Storage or `fake-gcs-server`.
+
+Each adapter exposes the same `get`/`set` interface and can be reused when embedding Chiitiler as a library.
+
+## Debug Tools
+
+Run with `--debug` or `CHIITILER_DEBUG=true` to unlock:
+
+- `/debug` – Inspect styles, test queries, and view response metadata.
+- `/editor` – Lightweight MapLibre style editor with live preview.
+
+## Development & Testing
+
+```bash
+npm run dev               # Watch mode via tsx
+npm run build             # Bundle to build/main.cjs with esbuild
+npm run test:unit         # Vitest unit suite (src/**/*.test.ts)
+npm run test:integration  # End-to-end scenarios in tests/
+npm run test:coverage     # Unit coverage with V8 provider
+npm run test:benchmark    # Performance tests (see BENCHMARK.md)
+```
+
+Benchmark scenarios and recent measurements live in [BENCHMARK.md](./BENCHMARK.md).
 
-### Usage
+## Library Usage
 
-```typescript
+Chiitiler is also published as an npm library. Core helpers return Sharp instances or encoded buffers so you can integrate the renderer into other pipelines.
+
+```ts
+import { createWriteStream } from 'node:fs';
 import {
-    getRenderedBboxBuffer,
     getRenderedTileBuffer,
-    ChiitilerCache
+    getRenderedBboxBuffer,
+    getRenderedImageBuffer,
+    getRenderedTileStream,
+    getRenderedBboxStream,
+    getRenderedImageStream,
+    ChiitilerCache,
 } from 'chiitiler';
 
-const s3Cache = ChiitilerCache.s3Cache({
-    bucket: 'chiitiler',
-    region: 'ap-northeast-1',
-    endpoint: null,
+const cache = ChiitilerCache.fileCache({ dir: './.cache', ttl: 3600 });
+
+const tile = await getRenderedTileBuffer({
+    stylejson: 'https://tile.openstreetmap.jp/styles/osm-bright/style.json',
+    z: 5,
+    x: 27,
+    y: 12,
+    tileSize: 512,
+    margin: 0,
+    ext: 'webp',
+    quality: 100,
+    cache,
+});
+
+const clip = await getRenderedBboxBuffer({
+    stylejson: 'file://localdata/style.json',
+    bbox: [123.4, 34.5, 124.5, 35.6],
+    size: 1024,
+    ext: 'png',
+    quality: 95,
+    cache: ChiitilerCache.noneCache(),
 });
-// credentials are loaded from environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
 
-const tileBuf = await getRenderedTileBuffer({
-    stylejson: 'https://example.com/style.json', // or StyleSpecification object
-    z: 0,
-    x: 0,
-    y: 0,
+const image = await getRenderedImageBuffer({
+    stylejson: 'file://localdata/style.json',
+    lat: 123.45,
+    lon: 67.89,
+    zoom: 10,
+    bearing: 180,
+    pitch: 60,
+    size: 1024,
+    ext: 'png',
+    quality: 95,
+    cache,
+});
+
+// you can get Sharp streams directly
+const tileStream = await getRenderedTileStream({
+    stylejson: 'https://tile.openstreetmap.jp/styles/osm-bright/style.json',
+    z: 5,
+    x: 27,
+    y: 12,
     tileSize: 512,
-    ext: 'webp', // png, webp, jpg
-    cache: s3Cache,
-    quality: 80,
     margin: 0,
+    ext: 'png',
+    quality: 90,
+    cache,
 });
 
-const bboxBuf = await getRenderedBboxBuffer({
-    stylejson: 'file://path/to/style.json', // or StyleSpecification object
+const bboxStream = await getRenderedBboxStream({
+    stylejson: 'file://localdata/style.json',
     bbox: [123.4, 34.5, 124.5, 35.6],
     size: 1024,
-    cache: s3Cache,
-    ext: 'webp',
-    quality: 80,
+    ext: 'jpeg',
+    quality: 85,
+    cache,
 });
 
-// return value is Buffer - binary of each image
+const imageStream = await getRenderedImageStream({
+    stylejson: 'file://localdata/style.json',
+    lat: 123.4,
+    lon: 34.5,
+    zoom: 10,
+    bearing: 180,
+    pitch: 60,
+    size: 1024,
+    ext: 'png',
+    quality: 95,
+    cache,
+})
 ```
 
-## development
+## Deployment
+
+- **AWS CDK** – The [`cdk/`](./cdk) directory contains an AWS CDK app for provisioning Chiitiler on ECS/Fargate. See `cdk/README.md` for stack details.
+- **Docker** – The provided `Dockerfile` installs runtime dependencies for `sharp` and exposes `tile-server` as the default entrypoint.
+- **Bench setups** – `docker-compose.yml` provisions MinIO, Fake GCS, and sample data for local smoke tests.
 
-- run `docker compose up`
+## Architecture
+
+```mermaid
+graph LR
+    subgraph sources
+        direction LR
+        A[style.json]
+        z/x/y.pbf
+        z/x/y.png/webp/jpg
+        sprite
+        glyphs
+    end
+
+    subgraph chiitiler
+        cache
+        render
+        server
+    end
+
+sources --> cache --> render --> server --/tiles/z/x/y--> png/webp/jpg
+
+cache <--get/set--> memory/file/S3
+```

package/dist/cache/gcs.d.ts

@@ -0,0 +1,10 @@
+import { type Cache } from './index.js';
+type GCSCacheOptions = {
+    bucket: string;
+    prefix?: string;
+    projectId?: string;
+    keyFilename?: string;
+    apiEndpoint?: string;
+};
+declare function gcsCache(options: GCSCacheOptions): Cache;
+export { gcsCache };

package/dist/cache/gcs.js

@@ -0,0 +1,66 @@
+import { getStorageClient } from '../gcs.js';
+function gcsCache(options) {
+    if (options.prefix?.endsWith('/')) {
+        options.prefix = options.prefix.slice(0, -1);
+    }
+    const storageClient = getStorageClient({
+        projectId: options.projectId,
+        keyFilename: options.keyFilename,
+        apiEndpoint: options.apiEndpoint,
+    });
+    const bucket = storageClient.bucket(options.bucket);
+    function bucketFile(key) {
+        const name = escapeFileName(key);
+        const nameWithPrefix = options.prefix ? `${options.prefix}/${name}` : name;
+        return bucket.file(nameWithPrefix);
+    }
+    return {
+        name: 'gcs',
+        set: async function (key, value) {
+            const file = bucketFile(key);
+            try {
+                await file.save(value, {
+                    resumable: false,
+                });
+            }
+            catch (e) {
+                console.log(`[error]: ${e}`);
+            }
+        },
+        get: async function (key) {
+            const file = bucketFile(key);
+            try {
+                const [content] = await file.download();
+                return Buffer.from(content);
+            }
+            catch {
+                // miss or any error
+                return undefined;
+            }
+        },
+    };
+}
+function escapeFileName(url) {
+    return url
+        .replace(/\//g, '_') // replace slashes with underscores
+        .replace(/\?/g, '-') // replace question marks with dashes
+        .replace(/&/g, '-') // replace ampersands with dashes
+        .replace(/=/g, '-') // replace equals signs with dashes
+        .replace(/%/g, '-') // replace percent signs with dashes
+        .replace(/#/g, '-') // replace hash signs with dashes
+        .replace(/:/g, '-') // replace colons with dashes
+        .replace(/\+/g, '-') // replace plus signs with dashes
+        .replace(/ /g, '-') // replace spaces with dashes
+        .replace(/</g, '-') // replace less than signs with dashes
+        .replace(/>/g, '-') // replace greater than signs with dashes
+        .replace(/\*/g, '-') // replace asterisks with dashes
+        .replace(/\|/g, '-') // replace vertical bars with dashes
+        .replace(/"/g, '-') // replace double quotes with dashes
+        .replace(/'/g, '-') // replace single quotes with dashes
+        .replace(/\?/g, '-') // replace question marks with dashes
+        .replace(/\./g, '-') // replace dots with dashes
+        .replace(/,/g, '-') // replace commas with dashes
+        .replace(/;/g, '-') // replace semicolons with dashes
+        .replace(/\\/g, '-'); // replace backslashes with dashes
+}
+export { gcsCache };

package/dist/cache/index.d.ts

@@ -1,5 +1,6 @@
 import { memoryCache } from './memory.js';
 import { s3Cache } from './s3.js';
+import { gcsCache } from './gcs.js';
 import { fileCache } from './file.js';
 type Value = Buffer;
 type Cache = {
@@ -8,4 +9,4 @@ type Cache = {
     set: (key: string, value: Value) => Promise<void>;
 };
 declare const noneCache: () => Cache;
-export { noneCache, memoryCache, s3Cache, fileCache, type Value, type Cache };
+export { noneCache, memoryCache, s3Cache, gcsCache, fileCache, type Value, type Cache };

package/dist/cache/index.js

@@ -1,9 +1,10 @@
 import { memoryCache } from './memory.js';
 import { s3Cache } from './s3.js';
+import { gcsCache } from './gcs.js';
 import { fileCache } from './file.js';
 const noneCache = () => ({
     name: 'none',
     get: async () => undefined,
     set: async () => undefined,
 });
-export { noneCache, memoryCache, s3Cache, fileCache };
+export { noneCache, memoryCache, s3Cache, gcsCache, fileCache };