optionally support type-safe Tags and Key

Author: k-yle

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- Optionally support type-safe `Tags`. `Tags` is currently defined as `Record<string, string>`. If you want additional type-safety, you can specify the keys are the allowed. See the docs for more info.
+
 ## 2.6.1 (2025-05-19)
 
 - Fix configuration issue which broke the type-definitions in the previous release

README.md

@@ -96,6 +96,7 @@ All methods return promises. Examples requests and responses are available for a
   - [`getApiCapabilities()`](./examples/getApiCapabilities.md)
   - [`getMapData`](./examples/getMapData.md)
   - [Using the Development Server](./examples/dev-server.md)
+  - [Additional type-safety for Keys/Tags](./examples/type-safe-tags.md)
 - Authentication (browser only, not available in NodeJS)
   - `login`
   - `logout`

examples/type-safe-tags.md

@@ -0,0 +1 @@
+See the JSDoc comment for `Key` in [src/types/general.ts](../src/types/general.ts)

src/api/changesets/uploadChangeset.ts

@@ -22,7 +22,7 @@ export interface UploadChunkInfo {
  * @returns the changeset number
  */
 export async function uploadChangeset(
-  tags: { [key: string]: string },
+  tags: Tags,
   diff: OsmChange,
   options?: FetchOptions & {
     /**

src/types/changesets.ts

@@ -1,4 +1,5 @@
 import type { OsmFeature } from "./features";
+import type { Tags } from "./general";
 
 export type ChangesetComment = {
   id: number;
@@ -35,9 +36,7 @@ export type Changeset = {
   max_lon: number;
   uid: number;
   user: string;
-  tags: {
-    [key: string]: string;
-  };
+  tags: Tags;
   /** the `discussion` attribute is only included in the `getChangeset` API */
   discussion?: ChangesetComment[];
 };

src/types/features.ts

@@ -1,3 +1,5 @@
+import type { Tags } from "./general";
+
 export type OsmFeatureType = "node" | "way" | "relation";
 
 /** these attributes exist on nodes, ways, and relations */
@@ -11,9 +13,7 @@ export type OsmBaseFeature = {
   version: number;
   uid: number;
 
-  tags?: {
-    [key: string]: string;
-  };
+  tags?: Tags;
 
   /** if false, it means the feature has been deleted */
   visible?: false;

src/types/general.ts

@@ -1,8 +1,50 @@
+declare global {
+  namespace OsmApi {
+    /**
+     * use this interface to get additional typesafety, see the documentation
+     * on {@link Key} for more info.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- intentional
+    interface Keys {}
+  }
+}
+
+/**
+ * By default, this library defines {@link Tags} to be `Record<string, string>`. This
+ * means that you don't get any typesafety for OSM keys/tags.
+ *
+ * There are two methods to make this more strict:
+ *
+ * 1. enable TypeScript's `noPropertyAccessFromIndexSignature` along with eslint's `dot-notation`.
+ *    This is not perfect, but it will force you to use `tags[KEY]` instead of `tags.key` which
+ *    makes the hardcoded keys more visible.
+ *
+ * 2. Declare a string union for every permitted osm key. For example:
+ *    ```ts
+ *    declare global {
+ *      namespace OsmApi {
+ *        interface Keys {
+ *          keys: 'amenity' | 'highway';
+ *        }
+ *      }
+ *    }
+ *    export {};
+ *    ```
+ *
+ * Regardless of what method you use, it also makes sense to enable TypeScript's
+ * `noUncheckedIndexedAccess` option.
+ */
+export type Key = OsmApi.Keys extends { keys: string }
+  ? OsmApi.Keys["keys"]
+  : string;
+
+export type Tags = OsmApi.Keys extends { keys: string }
+  ? Partial<Record<Key, string>>
+  : Record<string, string>;
+
 export type BBox = readonly [
   minLng: number,
   minLat: number,
   maxLng: number,
   maxLat: number,
 ];
-
-export type Tags = Record<string, string>;