Merge pull request #23 from reilem/relax-bbox-typing

reilem · web-flow · commit 48cb05da4776 · 2025-12-19T21:22:47.000+01:00
Relax bbox typing
diff --git a/README.md b/README.md
@@ -7,8 +7,7 @@
 
 This repository contains GeoJSON schemas for the [Zod](https://github.com/colinhacks/zod) validation library by [@colinhacks](https://x.com/colinhacks).
 
-The schemas are based on the GeoJSON specification [RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946). They validate the structure of the GeoJSON objects, types, and the validity of the dimensions, geometries and
-bounding boxes.
+The schemas are based on the GeoJSON specification RFC 7946. They validate the structure of the GeoJSON objects and types, as well as the validity of the dimensions, geometries, and bounding boxes.
 
 The schemas and inferred types are designed to be fully compatible with the
 [@types/geojson](https://www.npmjs.com/package/@types/geojson) TypeScript types.
@@ -89,47 +88,46 @@ import type {
 } from "zod-geojson";
 ```
 
-### Dimensionality
+### Strict Position Typing
+
+To maintain "out of the box" compatibility with [@types/geojson](https://www.npmjs.com/package/@types/geojson) the
+general schemas allow any position dimensionality.
+
+```typescript
+import { GeoJSONPoint } from "zod-geojson";
+
+// These are all valid
+const point3D: GeoJSONPoint = { type: "Point", coordinates: [0, 0, 0] };
+const point1D: GeoJSONPoint = { type: "Point", coordinates: [0] };
+const point0D: GeoJSONPoint = { type: "Point", coordinates: [] };
+const point4D: GeoJSONPoint = { type: "Point", coordinates: [0, 0, 0, 0] };
+```
 
-This library exports specific schemas for 2D and 3D GeoJSONs, and their accompanying types:
+If you want strict position checking at compile time then you can use the provided 2D and 3D schemas/types.
 
 ```typescript
 import type {
-    // 2D GeoJSON Schemas
+    // 2D GeoJSON
     GeoJSON2DFeatureSchema,
     GeoJSON2DFeature,
     // ...
-    // 2D GeoJSON Types
+    // 2D GeoJSON Geometries
     GeoJSON2DPointSchema,
     GeoJSON2DPoint,
     // ...
-    // 3D GeoJSON Schemas
+    // 3D GeoJSON
     GeoJSON3DFeatureSchema,
     GeoJSON3DFeature,
     // ...
-    // 3D GeoJSON Types
+    // 3D GeoJSON Geometries
     GeoJSON3DPointSchema,
     GeoJSON3DPoint,
+    // ...
 } from "zod-geojson";
 ```
 
-### Strict Position Typing
-
-To maintain "out of box" compatibility with the `@types/geojson` types the general schemas allow any position
-dimensionality.
-
-```typescript
-import { GeoJSONPoint } from "zod-geojson";
-
-// These are all valid
-const point3D: GeoJSONPoint = { type: "Point", coordinates: [0, 0, 0] };
-const point1D: GeoJSONPoint = { type: "Point", coordinates: [0] };
-const point0D: GeoJSONPoint = { type: "Point", coordinates: [] };
-const point4D: GeoJSONPoint = { type: "Point", coordinates: [0, 0, 0, 0] };
-```
-
-If you wish to have strict position typing, you can use the provided 2D and 3D schemas/types. These use strict position
-typing and will also restrict the bbox field to match the position dimension. For example:
+These use zod tuples to ensure positions are checked at compile time. However, to maintain interoperability
+with `@types/geojson`, bounding box dimensionality is not enforced at the type level, only during runtime validation.
 
 ```typescript
 import { GeoJSON2DPoint } from "zod-geojson";
@@ -143,7 +141,7 @@ const point3D: GeoJSON2DPoint = {
 const point2DWith3DBBox: GeoJSON2DPoint = {
     type: "Point",
     coordinates: [1.0, 2.0],
-    bbox: [0.0, 0.0, 3.0, 4.0, 0.0, 0.0], // This will fail. BBox has 6 values instead of 4
+    bbox: [0.0, 0.0, 3.0, 4.0, 0.0, 0.0], // This is allowed at type level, but will error during validation!
 };
 ```
 
@@ -191,7 +189,7 @@ This function takes three parameters:
 
 Even if you wish to only customize one of these aspects, you will still need to pass all three parameters to the
 schema function. For convenience, this library exposes the default schemas which you can use as a base for your
-custom schemas. There are the following "default" main schemas that you can use if you do not wish to customize
+custom schemas. These are the following "default" main schemas that you can use if you do not wish to customize
 a certain aspect of the schema:
 
 - `GeoJSONPositionSchema` - The main GeoJSON position schema which allows both 2D and 3D positions
@@ -231,7 +229,19 @@ As discussed above, if you only wish to customize the `properties` field, you wi
 by this library for this purpose.
 
 ```typescript
-import { GeoJSONFeatureGenericSchema, GeoJSONPositionSchema, GeoJSONGeometrySchema } from "zod-geojson";
+import {
+    GeoJSONFeatureGenericSchema,
+    GeoJSONPositionSchema,
+    GeoJSONPropertiesSchema,
+    GeoJSONGeometrySchema,
+} from "zod-geojson";
+
+const NonNullPropertiesGeoJSONFeatureSchema = GeoJSONFeatureGenericSchema(
+    GeoJSONPositionSchema,
+    GeoJSONPropertiesSchema.unwrap(),
+    GeoJSONGeometrySchema,
+);
+type NonNullPropertiesGeoJSONFeature = z.infer<typeof NonNullPropertiesGeoJSONFeatureSchema>;
 
 const CustomPropertiesSchema = z.object({
     name: z.string(),
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "zod-geojson",
-    "version": "1.5.0",
+    "version": "1.6.0",
     "description": "Zod schemas for GeoJSON",
     "repository": {
         "type": "git",
diff --git a/src/bbox.ts b/src/bbox.ts
@@ -8,37 +8,54 @@ import {
     GeoJSONPositionSchema,
 } from "./geometry/position";
 
-export type _GeoJSONBBoxGeneric<P extends GeoJSONAnyPosition> = P extends GeoJSON3DPosition
-    ? [number, number, number, number, number, number]
-    : P extends GeoJSON2DPosition
-      ? [number, number, number, number]
-      : [number, number, number, number] | [number, number, number, number, number, number];
-
 const _2DBBoxSchema = z.tuple([z.number(), z.number(), z.number(), z.number()]);
 const _3DBBoxSchema = z.tuple([z.number(), z.number(), z.number(), z.number(), z.number(), z.number()]);
+const _2DOr3DBBoxSchema = z.union([_2DBBoxSchema, _3DBBoxSchema]);
+type _2DOr3DBBox = z.infer<typeof _2DOr3DBBoxSchema>;
+
+/**
+ * Type representing a GeoJSON bounding box based on the provided position type.
+ * - When the position is not specifically 2D or 3D, the bounding box can be either 2D or 3D.
+ * - When the position is specifically 3D, the bounding box can be either 2D or 3D.
+ * - When the position is specifically 2D, the bounding box can be either 2D or 3D.
+ * - For other cases, it defaults to a number array.
+ *
+ * This rather strange approach is for compatibility with the @types/geojson definitions.
+ */
+export type _GeoJSONBBoxGeneric<P extends GeoJSONAnyPosition> = number extends P["length"]
+    ? _2DOr3DBBox
+    : P extends GeoJSON3DPosition
+      ? _2DOr3DBBox
+      : P extends GeoJSON2DPosition
+        ? _2DOr3DBBox
+        : number[];
 
 export type GeoJSONBBoxGenericSchemaType<P extends GeoJSONAnyPosition> = z.ZodType<_GeoJSONBBoxGeneric<P>>;
 
 /**
- * Creates a Zod schema for a GeoJSON bounding box based on the provided position schema.
- * Zod tuples with 2 or 3 items are used to represent 2D and 3D bounding boxes respectively.
- * If the position schema is not a tuple with 2 or 3 items, it returns a union of both 2D and 3D bounding box schemas.
+ * Creates a Zod schema for a GeoJSON bounding box roughly based on the provided position schema.
+ * The typing is thrown completely out of the window here, and we reply on our automated tests
+ * to ensure the runtime behavior is correct. The real bbox validation is implemented in the
+ * schema `.check` methods for each specific GeoJSON schema, so this is just here for some
+ * initial filtering of obviously invalid bbox values.
  */
 export const GeoJSONBBoxGenericSchema = <P extends GeoJSONAnyPosition>(
     positionSchema: z.ZodType<P>,
 ): GeoJSONBBoxGenericSchemaType<P> => {
-    // Because zod cannot do conditional typing we need to do some hacky type casts to make this work
+    // If the position is relaxed we assume either 2D or 3D bbox
+    if (positionSchema instanceof z.ZodArray) {
+        return _2DOr3DBBoxSchema as unknown as z.ZodType<GeoJSONBBoxGeneric<P>>;
+    }
+    // If the position is a tuple, we can infer the dimension from its length
     if (positionSchema instanceof z.ZodTuple) {
         const itemCount = positionSchema.def.items.length;
-        if (itemCount === 2) {
-            return _2DBBoxSchema as unknown as z.ZodType<GeoJSONBBoxGeneric<P>>;
-        }
-        if (itemCount === 3) {
-            return _3DBBoxSchema as unknown as z.ZodType<GeoJSONBBoxGeneric<P>>;
-        }
+        return z
+            .number()
+            .array()
+            .length(itemCount * 2) as unknown as z.ZodType<GeoJSONBBoxGeneric<P>>;
     }
-    // If the position is not a tuple, we can't infer the dimension, and we return a union of 2D and 3D bbox
-    return z.union([_2DBBoxSchema, _3DBBoxSchema]) as unknown as z.ZodType<GeoJSONBBoxGeneric<P>>;
+    // If the position is not a tuple, we can't infer the dimension, so we return a simple number array
+    return z.number().array() as unknown as z.ZodType<GeoJSONBBoxGeneric<P>>;
 };
 export type GeoJSONBBoxGeneric<P extends GeoJSONAnyPosition> = z.infer<ReturnType<typeof GeoJSONBBoxGenericSchema<P>>>;
 
diff --git a/src/geojson.ts b/src/geojson.ts
@@ -21,7 +21,11 @@ export type GeoJSONGenericSchemaType<
     R extends GeoJSONProperties,
     G extends GeoJSONGeometryGeneric<P> | null,
 > = z.ZodDiscriminatedUnion<
-    [z.ZodType<G>, GeoJSONFeatureGenericSchemaType<P, R, G>, GeoJSONFeatureCollectionGenericSchemaType<P, R, G>],
+    [
+        DiscriminableGeometrySchema<P, G>,
+        GeoJSONFeatureGenericSchemaType<P, R, G>,
+        GeoJSONFeatureCollectionGenericSchemaType<P, R, G>,
+    ],
     "type"
 >;
 
diff --git a/tests/bbox.test.ts b/tests/bbox.test.ts
@@ -1,10 +1,16 @@
 import { describe, expect, it } from "@jest/globals";
 import { point as turfPoint } from "@turf/helpers";
 import type GeoJSONTypes from "geojson";
-import { ZodError } from "zod/v4";
+import z, { ZodError } from "zod";
 import { bbox2D, bbox3D } from "../examples/bbox";
 import { GeoJSONBBox, GeoJSONBBoxSchema } from "../src";
-import { GeoJSON2DBBox, GeoJSON2DBBoxSchema, GeoJSON3DBBox, GeoJSON3DBBoxSchema } from "../src/bbox";
+import {
+    GeoJSON2DBBox,
+    GeoJSON2DBBoxSchema,
+    GeoJSON3DBBox,
+    GeoJSON3DBBoxSchema,
+    GeoJSONBBoxGenericSchema,
+} from "../src/bbox";
 
 const bbox4D = [0, 0, 0, 0, 0, 0, 0, 0];
 
@@ -69,6 +75,20 @@ describe("GeoJSONBBox", () => {
         });
     });
 
+    describe("4D", () => {
+        const GeoJSON4DBBoxSchema = GeoJSONBBoxGenericSchema(z.tuple([z.number(), z.number(), z.number(), z.number()]));
+
+        it("allows a 4D bbox", () => {
+            expect(GeoJSON4DBBoxSchema.parse(bbox4D)).toEqual(bbox4D);
+        });
+        it("does not allow a 2D bbox", () => {
+            expect(() => GeoJSON4DBBoxSchema.parse(bbox2D)).toThrow(ZodError);
+        });
+        it("does not allow a 3D bbox", () => {
+            expect(() => GeoJSON4DBBoxSchema.parse(bbox3D)).toThrow(ZodError);
+        });
+    });
+
     describe("turf.js", () => {
         it("validates bbox from turf.js", () => {
             const bbox = turfPoint([0, 0, 0], {}, { bbox: [0, 0, 0, 1, 1, 1] }).bbox;
diff --git a/tests/feature.test.ts b/tests/feature.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it } from "@jest/globals";
+import { feature as turfFeature, point as turfPoint } from "@turf/helpers";
 import type GeoJSONTypes from "geojson";
 import z, { ZodError } from "zod/v4";
-import { feature as turfFeature, point as turfPoint } from "@turf/helpers";
 
 import {
     geoJsonFeatureGeometryCollection2D,
@@ -17,11 +17,13 @@ import { geoJsonPoint3D } from "../examples/geometry/point";
 import {
     GeoJSON2DFeature,
     GeoJSON2DFeatureSchema,
+    GeoJSON2DGeometry,
     GeoJSON2DPointSchema,
     GeoJSON2DPolygonSchema,
     GeoJSON2DPositionSchema,
     GeoJSON3DFeature,
     GeoJSON3DFeatureSchema,
+    GeoJSON3DGeometry,
     GeoJSON3DPointSchema,
     GeoJSON3DPolygonSchema,
     GeoJSON3DPositionSchema,
@@ -243,17 +245,26 @@ describe("GeoJSONFeature", () => {
             GeoJSON4DGeometrySchema,
         );
 
+        const feature = {
+            ...geoJsonFeaturePoint2D,
+            geometry: {
+                type: "Point",
+                coordinates: [1.0, 2.0, 3.0, 4.0],
+            },
+        };
+
         it("allows feature with 4D positions", () => {
-            const feature = {
-                ...geoJsonFeaturePoint2D,
-                geometry: {
-                    type: "Point",
-                    coordinates: [1.0, 2.0, 3.0, 4.0],
-                },
-            };
             expect(GeoJSON4DFeatureSchema.parse(feature)).toEqual(feature);
         });
 
+        it("allows a feature with 4D position and valid bbox", () => {
+            const featureWithBBox = {
+                ...feature,
+                bbox: [1.0, 2.0, 3.0, 4.0, 1.0, 2.0, 3.0, 4.0],
+            };
+            expect(GeoJSON4DFeatureSchema.parse(featureWithBBox)).toEqual(featureWithBBox);
+        });
+
         it("does not allow feature with 3D positions", () => {
             expect(() => GeoJSON4DFeatureSchema.parse(geoJsonFeaturePoint3D)).toThrow(ZodError);
         });
@@ -268,6 +279,14 @@ describe("GeoJSONFeature", () => {
             };
             expect(() => GeoJSON4DFeatureSchema.parse(feature)).toThrow(ZodError);
         });
+
+        it("does not allow a feature with 4D positions and invalid bbox", () => {
+            const featureWithInvalidBBox = {
+                ...feature,
+                bbox: [1.0, 2.0, 3.0, 4.0], // Invalid bbox for 4D position
+            };
+            expect(() => GeoJSON4DFeatureSchema.parse(featureWithInvalidBBox)).toThrow(ZodError);
+        });
     });
 
     describe("Custom properties", () => {
@@ -586,15 +605,26 @@ export const feature5: GeoJSONTypes.Feature<GeoJSONTypes.Point> = geoJsonFeature
 
 export const feature6: GeoJSONTypes.Feature = geoJsonFeatureLineString2D as GeoJSONFeature;
 
+export const feature7: GeoJSONTypes.Feature<GeoJSON3DGeometry> = geoJsonFeaturePoint3D;
+export const feature8: GeoJSONTypes.Feature<GeoJSON2DGeometry> = geoJsonFeaturePolygon2D;
+
 /**
  * Test that @types/geojson matches our types
  */
-export const feature7: GeoJSONFeature = feature1;
+export const feature11: GeoJSONFeature = feature1;
+export const feature12: GeoJSONFeature = feature2;
+export const feature13: GeoJSONFeature = feature3;
+export const feature14: GeoJSONFeature = feature4;
+export const feature15: GeoJSONFeature = feature5;
+export const feature16: GeoJSONFeature = feature6;
+
+export const feature17: GeoJSON3DFeature = feature7;
+export const feature18: GeoJSON2DFeature = feature8;
 
 /**
  * Test that turf.js matches our types
  */
-export const feature8: GeoJSONFeature = turfFeature(geoJsonPoint3D);
-export const feature9: GeoJSONFeature = turfFeature(geoJsonPoint3D, { name: "hello" });
-export const feature10: GeoJSONFeature = turfPoint([0, 0, 0]);
-export const feature11: GeoJSONFeature = turfPoint([0, 0, 0], { extra: "field" });
+export const feature21: GeoJSONFeature = turfFeature(geoJsonPoint3D);
+export const feature22: GeoJSONFeature = turfFeature(geoJsonPoint3D, { name: "hello" });
+export const feature23: GeoJSONFeature = turfPoint([0, 0, 0]);
+export const feature24: GeoJSONFeature = turfPoint([0, 0, 0], { extra: "field" });
diff --git a/tests/feature_collection.test.ts b/tests/feature_collection.test.ts
diff --git a/tests/geojson.test.ts b/tests/geojson.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "zod-geojson",`
`3`		`- "version": "1.5.0",`
	`3`	`+ "version": "1.6.0",`
`4`	`4`	`"description": "Zod schemas for GeoJSON",`
`5`	`5`	`"repository": {`
`6`	`6`	`"type": "git",`