@infra-blocks/zod-utils 0.3.0-alpha.0 → 0.4.0-alpha.0

package/README.md

@@ -8,8 +8,156 @@ This package exposes various utilities extending the [zod](https://www.npmjs.com
 
 ## API
 
+- [geojson](#geojson)
 - [json](#json)
 
+### GeoJson
+
+The `geojson` module contains utilities to validate GeoJSON objects.
+
+```typescript
+import { zu } from "@infra-blocks/zod-utils";
+
+// Supports all GeoJSON types.
+// All geometries are supported.
+zu.geojson().parse({
+  type: "Point",
+  coordinates: [1, 2]
+});
+// Features
+zu.geojson().parse({
+  type: "Feature",
+  geometry: {
+    type: "LineString",
+    // Works with 3d coordinates too.
+    coordinates: [[1, 2, 3], [4, 4, 6]]
+  },
+  // Either null or a JSON object.
+  properties: {
+    name: "BigFeature"
+  }
+});
+// Feature collections
+zu.geojson().parse({
+  type: "FeatureCollection",
+  features: [
+    {
+      type: "Feature",
+      geometry: {
+        type: "Polygon",
+        coordinates: [[[1, 2], [2, 2], [2, 1], [1, 1]]]
+      },
+      properties: {
+        name: "BroSquare"
+      }
+    }
+  ]
+});
+```
+
+#### Sub schemas & Types
+
+For convenience, the module also exports sub schemas and types. This way, a user can pick and choose which schemas
+they specifically need in their context, or which ones they'd like to extend and customize.
+
+```typescript
+import {zu} from "@infra-blocks/zod-utils";
+import {
+  GeoJson,
+  GeoJsonBoundingBox,
+  GeoJsonFeature,
+  GeoJsonFeatureCollection,
+  GeoJsonGeometryCollection,
+  GeoJsonLineString,
+  GeoJsonMultiLineString,
+  GeoJsonMultiPoint,
+  GeoJsonMultiPolygon,
+  GeoJsonPoint,
+  GeoJsonPolygon,
+  GeoJsonCoordinate
+} from "@infra-blocks/zod-utils/geojson";
+
+const boundingBoxSchema = zu.geojson.boundingBox();
+const boundingBox: GeoJsonBoundingBox = boundingBoxSchema.parse({...});
+
+const featureSchema = zu.geojson.feature();
+const feature: GeoJsonFeature = featureSchema.parse({...});
+
+const featureCollectionSchema = zu.geojson.featureCollection();
+const featureCollection: GeoJsonFeatureCollection = featureCollectionSchema.parse({...});
+
+const geometryCollectionSchema = zu.geojson.geometryCollection();
+const geometryCollection: GeoJsonGeometryCollection = geometryCollectionSchema.parse({...});
+
+const lineStringSchema = zu.geojson.lineString();
+const lineString: GeoJsonLineString = lineStringSchema.parse({...});
+
+const multiLineStringSchema = zu.geojson.multiLineString();
+const multiLineString: GeoJsonMultiLineString = multiLineStringSchema.parse({...});
+
+const multiPointSchema = zu.geojson.multiPoint();
+const multiPoint: GeoJsonMultiPoint = multiPointSchema.parse({...});
+
+const multiPolygonSchema = zu.geojson.multiPolygon();
+const multiPolygon: GeoJsonMultiPolygon = multiPolygonSchema.parse({...});
+
+const pointSchema = zu.geojson.point();
+const point: GeoJsonPoint = pointSchema.parse({...});
+
+const polygonSchema = zu.geojson.polygon();
+const polygon: GeoJsonPolygon = polygonSchema.parse({...});
+
+const coordinateSchema = zu.geojson.coordinate();
+const coordinate: GeoJsonCoordinate = coordinateSchema.parse([1, 2]);
+```
+
+#### Design considerations
+
+##### Empty coordinates arrays
+
+The module follows the [spec](https://datatracker.ietf.org/doc/html/rfc7946). Note that the spec states the
+following:
+
+> GeoJSON processors MAY interpret Geometry objects with
+empty "coordinates" arrays as null objects. 
+
+This module tolerates empty coordinates arrays where the spec doesn't explicitly state that it must not be empty.
+For example, the following won't throw:
+```typescript
+zu.geojson().parse({
+  type: "MultiLineString",
+  coordinates: []
+});
+```
+
+However, the following will throw because the spec explicitly states the coordinates must contain at least two
+positions:
+```typescript
+zu.geojson().parse({
+  type: "LineString",
+  coordinates: []
+});
+```
+
+This behaviour could become configurable in a future version with a stricter default approach.
+
+##### Properties
+
+GeoJSON features must have properties. Those properties are either null or a JSON object. This module uses
+the `json` module to validate the properties. This means that the following will throw:
+```typescript
+zu.geojson().parse({
+  type: "Feature",
+  geometry: {
+    type: "Point",
+    coordinates: [1, 2]
+  },
+  properties: {
+    notJson: new Map()
+  }
+});
+```
+
 ### JSON
 
 The `json` module contains utilities to validate JSON objects and stringified JSON objects.
@@ -44,21 +192,13 @@ zu.json().parse(new Set()); // Boom.
 zu.json.stringified().parse("5"); // Returns the number 5.
 zu.json.stringified().parse('"JSON string"'); // Returns "JSON string". Note the quotes were removed.
 zu.json.stringified().parse(JSON.strinfify({ field: "value" })); // Returns {field: "value"}.
-
-// Inferred types are exported for convenience.
-import { Json } from "@infra-blocks/zod-utils/json";
-
-// Compiles.
-const myJson: Json = { hello: "world" };
-// Doesn't compile: undefined is not valid JSON.
-const boom: Json = { nope: undefined };
 ````
 
-The package also allows using sub schemas:
+#### Sub schemas & Types
 
 ```typescript
 import { zu } from "@infra-blocks/zod-utils";
-import { JsonArray, JsonObject, JsonPrimitive } from "@infra-blocks/zod-utils/json";
+import { Json, JsonArray, JsonObject, JsonPrimitive } from "@infra-blocks/zod-utils/json";
 
 // The type hints are used just to showcase their usage. They aren't necessary when parsing.
 // Want to parse a JSON primitive?

package/lib/cjs/geojson/base.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export declare const schemaWithBoundingBox: z.ZodObject<{
+    bbox: z.ZodOptional<z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>]>>;
+}, "strict", z.ZodTypeAny, {
+    bbox?: [number, number, number, number] | [number, number, number, number, number, number] | undefined;
+}, {
+    bbox?: [number, number, number, number] | [number, number, number, number, number, number] | undefined;
+}>;

package/lib/cjs/geojson/base.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schemaWithBoundingBox = void 0;
+const zod_1 = require("zod");
+const bounding_box_js_1 = require("./bounding-box.js");
+exports.schemaWithBoundingBox = zod_1.z.strictObject({
+    bbox: (0, bounding_box_js_1.boundingBox)().optional(),
+});
+//# sourceMappingURL=base.js.map

package/lib/cjs/geojson/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/geojson/base.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,uDAAgD;AAEnC,QAAA,qBAAqB,GAAG,OAAC,CAAC,YAAY,CAAC;IAClD,IAAI,EAAE,IAAA,6BAAW,GAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAC"}

package/lib/cjs/geojson/bounding-box.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+declare const boundingBoxSchema: z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>]>;
+export type GeoJsonBoundingBox = z.infer<typeof boundingBoxSchema>;
+export declare function boundingBox(): z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>]>;
+export {};

package/lib/cjs/geojson/bounding-box.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.boundingBox = void 0;
+const zod_1 = require("zod");
+const twoDimensionalBoundingBox = zod_1.z.tuple([
+    zod_1.z.number(),
+    zod_1.z.number(),
+    zod_1.z.number(),
+    zod_1.z.number(),
+]);
+const threeDimensionalBoundingBox = zod_1.z.tuple([
+    zod_1.z.number(),
+    zod_1.z.number(),
+    zod_1.z.number(),
+    zod_1.z.number(),
+    zod_1.z.number(),
+    zod_1.z.number(),
+]);
+const boundingBoxSchema = zod_1.z.union([
+    twoDimensionalBoundingBox,
+    threeDimensionalBoundingBox,
+]);
+function boundingBox() {
+    return boundingBoxSchema;
+}
+exports.boundingBox = boundingBox;
+//# sourceMappingURL=bounding-box.js.map

package/lib/cjs/geojson/bounding-box.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounding-box.js","sourceRoot":"","sources":["../../../src/geojson/bounding-box.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB,MAAM,yBAAyB,GAAG,OAAC,CAAC,KAAK,CAAC;IACxC,OAAC,CAAC,MAAM,EAAE;IACV,OAAC,CAAC,MAAM,EAAE;IACV,OAAC,CAAC,MAAM,EAAE;IACV,OAAC,CAAC,MAAM,EAAE;CACX,CAAC,CAAC;AAEH,MAAM,2BAA2B,GAAG,OAAC,CAAC,KAAK,CAAC;IAC1C,OAAC,CAAC,MAAM,EAAE;IACV,OAAC,CAAC,MAAM,EAAE;IACV,OAAC,CAAC,MAAM,EAAE;IACV,OAAC,CAAC,MAAM,EAAE;IACV,OAAC,CAAC,MAAM,EAAE;IACV,OAAC,CAAC,MAAM,EAAE;CACX,CAAC,CAAC;AAEH,MAAM,iBAAiB,GAAG,OAAC,CAAC,KAAK,CAAC;IAChC,yBAAyB;IACzB,2BAA2B;CAC5B,CAAC,CAAC;AAIH,SAAgB,WAAW;IACzB,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAFD,kCAEC"}

package/lib/cjs/geojson/coordinate.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+declare const schema: z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>]>;
+export type GeoJsonCoordinate = z.infer<typeof schema>;
+export declare function coordinate(): z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>]>;
+export {};

package/lib/cjs/geojson/coordinate.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coordinate = void 0;
+const zod_1 = require("zod");
+const twoDimensionalCoordinate = zod_1.z.tuple([zod_1.z.number(), zod_1.z.number()]);
+const threeDimensionalCoordinate = zod_1.z.tuple([
+    zod_1.z.number(),
+    zod_1.z.number(),
+    zod_1.z.number(),
+]);
+const schema = zod_1.z.union([twoDimensionalCoordinate, threeDimensionalCoordinate]);
+function coordinate() {
+    return schema;
+}
+exports.coordinate = coordinate;
+//# sourceMappingURL=coordinate.js.map

package/lib/cjs/geojson/coordinate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinate.js","sourceRoot":"","sources":["../../../src/geojson/coordinate.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB,MAAM,wBAAwB,GAAG,OAAC,CAAC,KAAK,CAAC,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;AACnE,MAAM,0BAA0B,GAAG,OAAC,CAAC,KAAK,CAAC;IACzC,OAAC,CAAC,MAAM,EAAE;IACV,OAAC,CAAC,MAAM,EAAE;IACV,OAAC,CAAC,MAAM,EAAE;CACX,CAAC,CAAC;AAEH,MAAM,MAAM,GAAG,OAAC,CAAC,KAAK,CAAC,CAAC,wBAAwB,EAAE,0BAA0B,CAAC,CAAC,CAAC;AAI/E,SAAgB,UAAU;IACxB,OAAO,MAAM,CAAC;AAChB,CAAC;AAFD,gCAEC"}