🚀 Socket Launch Week Day 5:Introducing Repository Access Permissions and Custom Roles.Learn more →
pmtiles-protocol
Advanced tools
pmtiles-protocol - npm Package Compare versions
+8
-3
| { | ||
| "name": "pmtiles-protocol", | ||
| "version": "1.1.0", | ||
| "version": "1.1.1", | ||
| "description": "pmtiles:// urls for fetch() and XMLHttpRequest", | ||
@@ -28,3 +28,6 @@ "type": "module", | ||
| "scripts": { | ||
| "test": "eslint **/*.js && prettier **/*.js --check && tsc --noEmit", | ||
| "lint": "eslint **/*.js && prettier **/*.js --check && tsc --noEmit", | ||
| "generate-fixtures": "node scripts/generate-fixtures.js", | ||
| "test": "vitest run", | ||
| "pretest": "npm run generate-fixtures && npm run lint", | ||
| "prepublishOnly": "tsc" | ||
@@ -40,5 +43,7 @@ }, | ||
| "globals": "^15.11.0", | ||
| "happy-dom": "^20.3.3", | ||
| "prettier": "^3.3.3", | ||
| "typescript": "^5.6.3" | ||
| "typescript": "^5.6.3", | ||
| "vitest": "^4.0.17" | ||
| } | ||
| } |
+4
-4
| # pmtiles-protocol | ||
| This package makes it easy to work with [Protomaps](https://protomaps.com) [PMTiles](https://docs.protomaps.com/pmtiles/) directly in the browser. It provides `fetch` and `XMLHttpRequest` versions that support urls starting with `pmtiles://`, returning the respective TileJSON or tiles. It is meant to be used in browser applications. | ||
| This package makes it easy to work with [Protomaps](https://protomaps.com) [PMTiles](https://docs.protomaps.com/pmtiles/) directly in the browser. It provides `fetch` and `XMLHttpRequest` versions as well as an `Image` or `HTMLImageElement` setter for `src` that support urls starting with `pmtiles://`, returning the respective TileJSON or tiles. It is meant to be used in browser applications. | ||
@@ -15,7 +15,7 @@ ## Supported URLs | ||
| - `pmtiles://https://example.com/path/to/mytiles.pmtiles/{z}/{x}/{y}.mvt` (absolute) | ||
| - `pmtiles://path/to/mytiles.pmtiles/{z}/{x}/{y}.mvt` (relative to `window.location.href`) | ||
| - `pmtiles://path/to/mytiles.pmtiles/{z}/{x}/{y}.png` (relative to `window.location.href`) | ||
| ## How to use | ||
| The global overrides for `fetch()` and `XMLHttpRequest` are the easiest way to use `pmtiles-protocol`: | ||
| The global overrides for `fetch()`, `XMLHttpRequest` and `Image` or `HTMLImageElment`'s `src` setter are the easiest way to use `pmtiles-protocol`: | ||
@@ -30,3 +30,3 @@ ```js | ||
| To restore the original global `fetch()` and `XMLHttpRequest` versions, and the original `src` setter on `HTMLImageElement`, call | ||
| To restore the original global `fetch()` and `XMLHttpRequest` versions, and the original `src` setter on `Image` and `HTMLImageElement`, call | ||
@@ -33,0 +33,0 @@ ```js |
| # Copilot Instructions for `pmtiles-protocol` | ||
| ## Project Overview | ||
| This is a JavaScript library that enables `pmtiles://` protocol support in browser environments by intercepting and wrapping global `fetch` and `XMLHttpRequest` APIs. It acts as a bridge between the browser's network layer and the `pmtiles` library. | ||
| ## Architecture & Core Concepts | ||
| - **Interception Strategy**: Uses JavaScript `Proxy` to wrap `globalThis.fetch` and extend `XMLHttpRequest`. | ||
| - **Protocol Handling**: | ||
| - Intercepts URLs starting with `pmtiles://`. | ||
| - Resolves them using the `pmtiles` library (parsing TileJSON or specific Z/X/Y tiles). | ||
| - Falls through to original native implementations for all other protocols (http/https). | ||
| - **State Management**: | ||
| - Maintains a module-level cache `pmtilesByUrl` to persist `PMTiles` instances across requests. | ||
| - **Key Files**: | ||
| - `index.js`: Contains the entire implementation (fetch proxy, XHR shim, registry logic). | ||
| - `index.d.ts`: Generated type definitions (do not edit manually, generated via `tsc`). | ||
| ## Tech Stack & Tooling | ||
| - **Language**: JavaScript (ESM). | ||
| - **Type System**: **JSDoc + TypeScript**. | ||
| - Source code is `.js`. | ||
| - Types are defined via JSDoc comments (`/** @type {string} */`). | ||
| - `tsconfig.json` is configured with `allowJs: true`, `checkJs: true`, and `emitDeclarationOnly: true`. | ||
| - **Rule**: Do not create `.ts` files. Use standard JavaScript with correct JSDoc annotations to satisfy the compiler. | ||
| - **Dependencies**: `pmtiles` (core logic). | ||
| ## Development Workflows | ||
| - **Validation**: | ||
| - Run `npm test` to validate code style (eslint/prettier) and type correctness (tsc). | ||
| - **Note**: This project currently relies on static analysis for CI. There are no functional unit test suites (Jest/Mocha). | ||
| - **Building**: | ||
| - `npm run prepublishOnly` runs `tsc` to generate `index.d.ts` and source maps. | ||
| ## Coding Conventions | ||
| 1. **Type Safety**: | ||
| - All functions and complex variables MUST have JSDoc annotations. | ||
| - Use `@ts-expect-error` sparingly and only when necessary for patching native APIs (e.g., inside the XHR proxy). | ||
| 2. **Browser APIs**: | ||
| - Access globals via `globalThis` (e.g., `globalThis.fetch`) to ensure safety in different JS environments. | ||
| - Handle native API signatures carefully (e.g., `fetch` accepts `Request` objects or strings). | ||
| 3. **Modern JS**: | ||
| - Use ES2022+ features (as configured in `tsconfig.json`). | ||
| - Prefer `const`/`let` over `var`. | ||
| ## release | ||
| - Manual versioning in `package.json`. |
| # This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node | ||
| # For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs | ||
| name: Node.js CI | ||
| on: | ||
| push: | ||
| branches: [ "main" ] | ||
| pull_request: | ||
| branches: [ "main" ] | ||
| jobs: | ||
| build: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - name: Test and build | ||
| uses: actions/setup-node@v4 | ||
| with: | ||
| node-version: 20 | ||
| cache: 'npm' | ||
| - run: npm ci | ||
| - run: npm run build --if-present | ||
| - run: npm test |
| { | ||
| "singleQuote": true | ||
| } |
| { | ||
| "recommendations": ["esbenp.prettier-vscode"] | ||
| } |
| { | ||
| "editor.codeActionsOnSave": { | ||
| "source.fixAll": "explicit" | ||
| }, | ||
| "editor.formatOnSave": true, | ||
| "editor.defaultFormatter": "esbenp.prettier-vscode" | ||
| } |
| import globals from 'globals'; | ||
| import pluginJs from '@eslint/js'; | ||
| export default [ | ||
| { languageOptions: { globals: globals.browser } }, | ||
| pluginJs.configs.recommended, | ||
| ]; |
| { | ||
| "compilerOptions": { | ||
| "allowJs": true, | ||
| "checkJs": true, | ||
| "esModuleInterop": true, | ||
| "declaration": true, | ||
| "emitDeclarationOnly": true, | ||
| "declarationMap": true, | ||
| "module": "ES2022", | ||
| "target": "es2022", | ||
| "lib": ["dom", "es2022"], | ||
| "moduleResolution": "node", | ||
| "strict": true | ||
| }, | ||
| "include": ["**/*.js"] | ||
| } |
No alert changes
Worsened metrics
- Total package byte prevSize
42518
-7.78%- Dev dependency count
8
33.33%- Number of package files
6
-53.85%- Lines of code
737
-4.16%No dependency changes