@prisma-next/extension-postgis 0.0.1

package/src/core/codecs.ts

@@ -0,0 +1,193 @@
+/**
+ * Geometry codec for the PostGIS extension.
+ *
+ * Mirrors the descriptor + class pattern used by other codec-shipping
+ * packages (e.g. pgvector). Three artefacts:
+ *
+ * 1. `PostgisGeometryCodec` extends {@link CodecImpl} with the runtime
+ *    encode/decode conversions. Wire formats:
+ *    - encode: EWKT (`'SRID=4326;POINT(...)'`) — PostgreSQL parses
+ *      this when cast to `::geometry`.
+ *    - decode: hex EWKB — the default representation `node-postgres`
+ *      hands back for `geometry` columns. We parse it into a
+ *      GeoJSON-shaped object so callers see structured data, not
+ *      opaque hex.
+ * 2. `PostgisGeometryDescriptor` extends {@link CodecDescriptorImpl}
+ *    with the codec id, traits, target types, params schema
+ *    (`{ srid: number }`, validated as a non-negative integer), and
+ *    the emit-path `renderOutputType` producing `Geometry<${srid}>` /
+ *    `Geometry` when no SRID is supplied.
+ * 3. `pgGeometryColumn({ srid })` per-codec column helper invoking
+ *    `descriptor.factory({ srid })` and passing the bare
+ *    `nativeType: 'geometry'`. The family-layer `expandNativeType`
+ *    hook renders the parameterised form
+ *    (`geometry(Geometry,${srid})`) at emit/verify time from
+ *    `nativeType` + `typeParams`.
+ *
+ * The geometry codec's encode/decode is parameter-independent — the
+ * wire format already carries SRID inside the EWKT/EWKB payload, so the
+ * resolved codec for every `(srid)` instance is the same shared codec
+ * today. The factory threads the closure for future per-instance state
+ * (e.g. SRID cross-checks) without rewriting the constructor.
+ */
+
+import type { JsonValue } from '@prisma-next/contract/types';
+import {
+  type AnyCodecDescriptor,
+  type CodecCallContext,
+  CodecDescriptorImpl,
+  CodecImpl,
+  type CodecInstanceContext,
+  type ColumnHelperFor,
+  type ColumnHelperForStrict,
+  column,
+} from '@prisma-next/framework-components/codec';
+import type { ExtractCodecTypes } from '@prisma-next/sql-relational-core/ast';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { type as arktype } from 'arktype';
+import { POSTGIS_GEOMETRY_CODEC_ID } from './constants';
+import { decodeEWKBHex, encodeEWKT } from './ewkb';
+import type { Geometry } from './geojson';
+
+type GeometryParams = { readonly srid: number };
+
+const geometryParamsSchema = arktype({
+  srid: 'number',
+}).narrow((params, ctx) => {
+  const { srid } = params;
+  if (!Number.isInteger(srid)) {
+    return ctx.mustBe('an integer');
+  }
+  if (srid < 0) {
+    return ctx.mustBe('a non-negative integer');
+  }
+  return true;
+}) satisfies StandardSchemaV1<GeometryParams>;
+
+const POSTGIS_GEOMETRY_META = {
+  db: { sql: { postgres: { nativeType: 'geometry' } } },
+} as const;
+
+const allowedGeometryTypes = new Set([
+  'Point',
+  'LineString',
+  'Polygon',
+  'MultiPoint',
+  'MultiLineString',
+  'MultiPolygon',
+]);
+
+function assertGeometry(value: unknown): asserts value is Geometry {
+  if (!value || typeof value !== 'object') {
+    throw new Error('Geometry value must be a GeoJSON-shaped object');
+  }
+  const type = (value as { type?: unknown }).type;
+  if (typeof type !== 'string' || !allowedGeometryTypes.has(type)) {
+    throw new Error(
+      `Geometry value: unsupported type "${String(type)}" (expected Point, LineString, Polygon, MultiPoint, MultiLineString, or MultiPolygon)`,
+    );
+  }
+  if (!Array.isArray((value as { coordinates?: unknown }).coordinates)) {
+    throw new Error('Geometry value: "coordinates" must be an array');
+  }
+}
+
+export class PostgisGeometryCodec extends CodecImpl<
+  typeof POSTGIS_GEOMETRY_CODEC_ID,
+  readonly ['equality'],
+  string,
+  Geometry
+> {
+  constructor(descriptor: AnyCodecDescriptor) {
+    super(descriptor);
+  }
+
+  async encode(value: Geometry, _ctx: CodecCallContext): Promise<string> {
+    assertGeometry(value);
+    return encodeEWKT(value);
+  }
+
+  async decode(wire: string, _ctx: CodecCallContext): Promise<Geometry> {
+    if (typeof wire !== 'string') {
+      throw new Error('Geometry wire value must be a string');
+    }
+    return decodeEWKBHex(wire);
+  }
+
+  encodeJson(value: Geometry): JsonValue {
+    assertGeometry(value);
+    return value as unknown as JsonValue;
+  }
+
+  decodeJson(json: JsonValue): Geometry {
+    assertGeometry(json);
+    return json;
+  }
+}
+
+export class PostgisGeometryDescriptor extends CodecDescriptorImpl<GeometryParams> {
+  override readonly codecId = POSTGIS_GEOMETRY_CODEC_ID;
+  override readonly traits = ['equality'] as const;
+  override readonly targetTypes = ['geometry'] as const;
+  override readonly meta = POSTGIS_GEOMETRY_META;
+  override readonly paramsSchema: StandardSchemaV1<GeometryParams> = geometryParamsSchema;
+  override renderOutputType(params: GeometryParams): string {
+    const srid = (params as GeometryParams | undefined)?.srid;
+    if (srid === undefined) return 'Geometry';
+    return `Geometry<${srid}>`;
+  }
+  /**
+   * The runtime calls `factory(undefined)(ctx)` to materialize a
+   * representative codec for parameterised descriptors that ship a
+   * no-params column variant (here, `geometryColumn` vs `geometry({ srid })`).
+   * The runtime cast widens `params` to `unknown`, so guarding with an
+   * optional read keeps the typed call site (`factory({ srid })`)
+   * strict while still producing an SRID-agnostic codec for
+   * representative use. Encode/decode for an unparameterised column
+   * runs through this representative; the wire format already carries
+   * SRID inside the EWKT/EWKB payload, so it's dimension-independent.
+   */
+  override factory(_params: GeometryParams): (ctx: CodecInstanceContext) => PostgisGeometryCodec {
+    return () => new PostgisGeometryCodec(this);
+  }
+}
+
+export const postgisGeometryDescriptor = new PostgisGeometryDescriptor();
+
+/**
+ * Per-codec column helper for `pg/geometry@1` with an SRID constraint.
+ *
+ * Generic over `S extends number` so the column site preserves the
+ * SRID literal in `typeParams` (e.g. `pgGeometryColumn({ srid: 4326 })`
+ * packs `typeParams: { srid: 4326 }`).
+ *
+ * Passes the bare `nativeType: 'geometry'`; the family-layer
+ * `expandNativeType` hook renders the parameterised form
+ * (`geometry(Geometry,${srid})`) at emit/verify time from `nativeType`
+ * + `typeParams`.
+ *
+ * @throws {RangeError} If `srid` is not a non-negative integer.
+ */
+export const pgGeometryColumn = <S extends number>(options: { readonly srid: S }) => {
+  const { srid } = options;
+  if (!Number.isInteger(srid) || srid < 0) {
+    throw new RangeError(`postgis: srid must be a non-negative integer, got ${srid}`);
+  }
+  return column(
+    postgisGeometryDescriptor.factory({ srid }),
+    postgisGeometryDescriptor.codecId,
+    { srid },
+    'geometry',
+  );
+};
+
+pgGeometryColumn satisfies ColumnHelperFor<PostgisGeometryDescriptor>;
+pgGeometryColumn satisfies ColumnHelperForStrict<PostgisGeometryDescriptor>;
+
+const codecDescriptorMap = {
+  geometry: postgisGeometryDescriptor,
+} as const;
+
+export type CodecTypes = ExtractCodecTypes<typeof codecDescriptorMap>;
+
+export const codecDescriptors: readonly AnyCodecDescriptor[] = Object.values(codecDescriptorMap);

package/src/core/constants.ts

@@ -0,0 +1,3 @@
+export const POSTGIS_GEOMETRY_CODEC_ID = 'pg/geometry@1' as const;
+
+export const SRID_WGS84 = 4326 as const;

package/src/core/contract-space-constants.ts

@@ -0,0 +1,30 @@
+/**
+ * Static names and identifiers used across postgis's contract space.
+ *
+ * Centralised here so the contract IR (`./contract`), the baseline
+ * migration ops (`./migrations`), the head ref, and the descriptor
+ * (`../exports/control`) all reference the same values without typos.
+ *
+ * The space identifier `'postgis'` is what the framework writes to
+ * `migrations/` in the user's repo and what the marker table's
+ * `space` column carries for postgis-owned rows.
+ *
+ * The `postgis:*` invariantId namespace is locked here — once
+ * published, an invariantId is immutable so downstream consumers can
+ * reference it by literal string match.
+ */
+
+export const POSTGIS_SPACE_ID = 'postgis' as const;
+
+export const POSTGIS_NATIVE_TYPE = 'geometry' as const;
+
+export const POSTGIS_BASELINE_MIGRATION_NAME = '20260601T0000_install_postgis_extension' as const;
+
+/**
+ * `postgis:*` invariantIds emitted by the baseline migration. Each id,
+ * once published, is immutable: downstream consumers (other extensions,
+ * the marker table) reference them by literal string match.
+ */
+export const POSTGIS_INVARIANTS = {
+  installPostgis: 'postgis:install-postgis-v1',
+} as const;

package/src/core/descriptor-meta.ts

@@ -0,0 +1,186 @@
+import { buildOperation, codecOf, toExpr } from '@prisma-next/sql-relational-core/expression';
+import type { CodecTypes } from '../types/codec-types';
+import type { QueryOperationTypes } from '../types/operation-types';
+import { postgisAuthoringTypes } from './authoring';
+import { postgisCodecRegistry } from './registry';
+
+const postgisTypeId = 'pg/geometry@1' as const;
+
+type CodecTypesBase = Record<string, { readonly input: unknown; readonly output: unknown }>;
+
+/**
+ * Build the PostGIS query operations exposed on `geometry` columns.
+ *
+ * Each operation lowers to a function-template that the SQL renderer
+ * stitches into the surrounding statement (`{{self}}` is the receiver,
+ * `{{argN}}` are the call arguments). All templates rely on the implicit
+ * `geometry`/`float8`/`bool` casts already wired up by the SQL family —
+ * we only add the PostGIS-specific function names.
+ */
+export function postgisQueryOperations<CT extends CodecTypesBase>(): QueryOperationTypes<CT> {
+  return {
+    distance: {
+      self: { codecId: postgisTypeId },
+      impl: (self, other) => {
+        const selfCodec = codecOf(self);
+        return buildOperation({
+          method: 'distance',
+          args: [toExpr(self, selfCodec), toExpr(other, selfCodec)],
+          returns: { codecId: 'pg/float8@1', nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: 'ST_Distance({{self}}, {{arg0}})',
+          },
+        });
+      },
+    },
+    distanceSphere: {
+      self: { codecId: postgisTypeId },
+      impl: (self, other) => {
+        const selfCodec = codecOf(self);
+        return buildOperation({
+          method: 'distanceSphere',
+          args: [toExpr(self, selfCodec), toExpr(other, selfCodec)],
+          returns: { codecId: 'pg/float8@1', nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: 'ST_DistanceSphere({{self}}, {{arg0}})',
+          },
+        });
+      },
+    },
+    dwithin: {
+      self: { codecId: postgisTypeId },
+      impl: (self, other, distance) => {
+        const selfCodec = codecOf(self);
+        return buildOperation({
+          method: 'dwithin',
+          args: [
+            toExpr(self, selfCodec),
+            toExpr(other, selfCodec),
+            toExpr(distance, { codecId: 'pg/float8@1' }),
+          ],
+          returns: { codecId: 'pg/bool@1', nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: 'ST_DWithin({{self}}, {{arg0}}, {{arg1}})',
+          },
+        });
+      },
+    },
+    contains: {
+      self: { codecId: postgisTypeId },
+      impl: (self, other) => {
+        const selfCodec = codecOf(self);
+        return buildOperation({
+          method: 'contains',
+          args: [toExpr(self, selfCodec), toExpr(other, selfCodec)],
+          returns: { codecId: 'pg/bool@1', nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: 'ST_Contains({{self}}, {{arg0}})',
+          },
+        });
+      },
+    },
+    within: {
+      self: { codecId: postgisTypeId },
+      impl: (self, other) => {
+        const selfCodec = codecOf(self);
+        return buildOperation({
+          method: 'within',
+          args: [toExpr(self, selfCodec), toExpr(other, selfCodec)],
+          returns: { codecId: 'pg/bool@1', nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: 'ST_Within({{self}}, {{arg0}})',
+          },
+        });
+      },
+    },
+    intersects: {
+      self: { codecId: postgisTypeId },
+      impl: (self, other) => {
+        const selfCodec = codecOf(self);
+        return buildOperation({
+          method: 'intersects',
+          args: [toExpr(self, selfCodec), toExpr(other, selfCodec)],
+          returns: { codecId: 'pg/bool@1', nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: 'ST_Intersects({{self}}, {{arg0}})',
+          },
+        });
+      },
+    },
+    intersectsBbox: {
+      self: { codecId: postgisTypeId },
+      impl: (self, other) => {
+        const selfCodec = codecOf(self);
+        return buildOperation({
+          method: 'intersectsBbox',
+          args: [toExpr(self, selfCodec), toExpr(other, selfCodec)],
+          returns: { codecId: 'pg/bool@1', nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: '({{self}} && {{arg0}})',
+          },
+        });
+      },
+    },
+  };
+}
+
+const postgisPackMetaBase = {
+  kind: 'extension',
+  id: 'postgis',
+  familyId: 'sql',
+  targetId: 'postgres',
+  version: '0.0.1',
+  capabilities: {
+    postgres: {
+      'postgis.geometry': true,
+    },
+  },
+  authoring: {
+    type: postgisAuthoringTypes,
+  },
+  types: {
+    codecTypes: {
+      codecDescriptors: Array.from(postgisCodecRegistry.values()),
+      import: {
+        package: '@prisma-next/extension-postgis/codec-types',
+        named: 'CodecTypes',
+        alias: 'PostgisTypes',
+      },
+      typeImports: [
+        {
+          package: '@prisma-next/extension-postgis/codec-types',
+          named: 'Geometry',
+          alias: 'Geometry',
+        },
+      ],
+    },
+    queryOperationTypes: {
+      import: {
+        package: '@prisma-next/extension-postgis/operation-types',
+        named: 'QueryOperationTypes',
+        alias: 'PostgisQueryOperationTypes',
+      },
+    },
+    storage: [
+      { typeId: postgisTypeId, familyId: 'sql', targetId: 'postgres', nativeType: 'geometry' },
+    ],
+  },
+} as const;
+
+export const postgisPackMeta: typeof postgisPackMetaBase & {
+  readonly __codecTypes?: CodecTypes;
+} = postgisPackMetaBase;

package/src/core/ewkb.ts

@@ -0,0 +1,284 @@
+/**
+ * Minimal EWKB (Extended Well-Known Binary) reader for the PostGIS codec.
+ *
+ * `node-postgres` returns geometry columns as hex-encoded EWKB strings by
+ * default. This reader parses the subset we ship with the extension —
+ * Point, LineString, Polygon, and the Multi* counterparts — into GeoJSON
+ * objects. Z and M coordinates are not supported; if a wire value carries
+ * them, decoding throws so the caller can detect the mismatch instead of
+ * silently dropping data.
+ */
+
+import type {
+  Geometry,
+  GeometryLineString,
+  GeometryMultiLineString,
+  GeometryMultiPoint,
+  GeometryMultiPolygon,
+  GeometryPoint,
+  GeometryPolygon,
+  Position,
+} from './geojson';
+
+const FLAG_Z = 0x80000000;
+const FLAG_M = 0x40000000;
+const FLAG_SRID = 0x20000000;
+const TYPE_MASK = 0x1fffffff;
+
+const TYPE_POINT = 1;
+const TYPE_LINESTRING = 2;
+const TYPE_POLYGON = 3;
+const TYPE_MULTIPOINT = 4;
+const TYPE_MULTILINESTRING = 5;
+const TYPE_MULTIPOLYGON = 6;
+
+const HEX_PAIR_RE = /^[0-9a-fA-F]{2}$/;
+
+function hexToBytes(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0) {
+    throw new Error('Geometry wire value: odd-length hex string');
+  }
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    const pair = hex.slice(i * 2, i * 2 + 2);
+    if (!HEX_PAIR_RE.test(pair)) {
+      throw new Error(`Geometry wire value: invalid hex byte at offset ${i * 2}`);
+    }
+    bytes[i] = Number.parseInt(pair, 16);
+  }
+  return bytes;
+}
+
+class Reader {
+  private offset = 0;
+  private readonly view: DataView;
+
+  constructor(bytes: Uint8Array) {
+    this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  }
+
+  private requireBytes(needed: number): void {
+    if (this.offset + needed > this.view.byteLength) {
+      throw new Error(
+        `Geometry wire value: unexpected end of buffer (need ${needed} bytes at offset ${this.offset}, ${this.view.byteLength - this.offset} available)`,
+      );
+    }
+  }
+
+  readUint8(): number {
+    this.requireBytes(1);
+    const v = this.view.getUint8(this.offset);
+    this.offset += 1;
+    return v;
+  }
+
+  readUint32(littleEndian: boolean): number {
+    this.requireBytes(4);
+    const v = this.view.getUint32(this.offset, littleEndian);
+    this.offset += 4;
+    return v >>> 0;
+  }
+
+  readFloat64(littleEndian: boolean): number {
+    this.requireBytes(8);
+    const v = this.view.getFloat64(this.offset, littleEndian);
+    this.offset += 8;
+    return v;
+  }
+
+  hasRemaining(): boolean {
+    return this.offset !== this.view.byteLength;
+  }
+
+  remainingBytes(): number {
+    return this.view.byteLength - this.offset;
+  }
+}
+
+type Header = {
+  readonly geomType: number;
+  readonly littleEndian: boolean;
+  readonly srid?: number;
+};
+
+function readHeader(reader: Reader): Header {
+  const byteOrder = reader.readUint8();
+  if (byteOrder !== 0 && byteOrder !== 1) {
+    throw new Error(`Geometry wire value: invalid byte order ${byteOrder}`);
+  }
+  const littleEndian = byteOrder === 1;
+  const typeCode = reader.readUint32(littleEndian);
+  if ((typeCode & FLAG_Z) !== 0 || (typeCode & FLAG_M) !== 0) {
+    throw new Error('Geometry wire value: Z/M coordinates are not supported');
+  }
+  const geomType = typeCode & TYPE_MASK;
+  if ((typeCode & FLAG_SRID) !== 0) {
+    return { geomType, littleEndian, srid: reader.readUint32(littleEndian) };
+  }
+  return { geomType, littleEndian };
+}
+
+function readPosition(reader: Reader, littleEndian: boolean): Position {
+  const x = reader.readFloat64(littleEndian);
+  const y = reader.readFloat64(littleEndian);
+  return [x, y];
+}
+
+function readPoint(reader: Reader, header: Header): GeometryPoint {
+  const coords = readPosition(reader, header.littleEndian);
+  return header.srid !== undefined
+    ? { type: 'Point', coordinates: coords, srid: header.srid }
+    : { type: 'Point', coordinates: coords };
+}
+
+function readLineString(reader: Reader, header: Header): GeometryLineString {
+  const n = reader.readUint32(header.littleEndian);
+  const coords: Position[] = [];
+  for (let i = 0; i < n; i++) coords.push(readPosition(reader, header.littleEndian));
+  return header.srid !== undefined
+    ? { type: 'LineString', coordinates: coords, srid: header.srid }
+    : { type: 'LineString', coordinates: coords };
+}
+
+function readPolygon(reader: Reader, header: Header): GeometryPolygon {
+  const numRings = reader.readUint32(header.littleEndian);
+  const rings: Position[][] = [];
+  for (let r = 0; r < numRings; r++) {
+    const n = reader.readUint32(header.littleEndian);
+    const ring: Position[] = [];
+    for (let i = 0; i < n; i++) ring.push(readPosition(reader, header.littleEndian));
+    rings.push(ring);
+  }
+  return header.srid !== undefined
+    ? { type: 'Polygon', coordinates: rings, srid: header.srid }
+    : { type: 'Polygon', coordinates: rings };
+}
+
+function readSubGeometry(reader: Reader): Geometry {
+  // Multi* geometries embed sub-WKB records; each carries its own header.
+  const header = readHeader(reader);
+  switch (header.geomType) {
+    case TYPE_POINT:
+      return readPoint(reader, header);
+    case TYPE_LINESTRING:
+      return readLineString(reader, header);
+    case TYPE_POLYGON:
+      return readPolygon(reader, header);
+    default:
+      throw new Error(`Geometry wire value: unsupported sub-type ${header.geomType}`);
+  }
+}
+
+function readMultiPoint(reader: Reader, header: Header): GeometryMultiPoint {
+  const n = reader.readUint32(header.littleEndian);
+  const coords: Position[] = [];
+  for (let i = 0; i < n; i++) {
+    const sub = readSubGeometry(reader);
+    if (sub.type !== 'Point') {
+      throw new Error('Geometry wire value: MultiPoint contains non-Point sub-geometry');
+    }
+    coords.push(sub.coordinates);
+  }
+  return header.srid !== undefined
+    ? { type: 'MultiPoint', coordinates: coords, srid: header.srid }
+    : { type: 'MultiPoint', coordinates: coords };
+}
+
+function readMultiLineString(reader: Reader, header: Header): GeometryMultiLineString {
+  const n = reader.readUint32(header.littleEndian);
+  const lines: ReadonlyArray<Position>[] = [];
+  for (let i = 0; i < n; i++) {
+    const sub = readSubGeometry(reader);
+    if (sub.type !== 'LineString') {
+      throw new Error('Geometry wire value: MultiLineString contains non-LineString sub-geometry');
+    }
+    lines.push(sub.coordinates);
+  }
+  return header.srid !== undefined
+    ? { type: 'MultiLineString', coordinates: lines, srid: header.srid }
+    : { type: 'MultiLineString', coordinates: lines };
+}
+
+function readMultiPolygon(reader: Reader, header: Header): GeometryMultiPolygon {
+  const n = reader.readUint32(header.littleEndian);
+  const polys: ReadonlyArray<ReadonlyArray<Position>>[] = [];
+  for (let i = 0; i < n; i++) {
+    const sub = readSubGeometry(reader);
+    if (sub.type !== 'Polygon') {
+      throw new Error('Geometry wire value: MultiPolygon contains non-Polygon sub-geometry');
+    }
+    polys.push(sub.coordinates);
+  }
+  return header.srid !== undefined
+    ? { type: 'MultiPolygon', coordinates: polys, srid: header.srid }
+    : { type: 'MultiPolygon', coordinates: polys };
+}
+
+export function decodeEWKBHex(hex: string): Geometry {
+  const reader = new Reader(hexToBytes(hex));
+  const header = readHeader(reader);
+  const geometry = readGeometryBody(reader, header);
+  if (reader.hasRemaining()) {
+    throw new Error(
+      `Geometry wire value: trailing data after geometry (${reader.remainingBytes()} bytes)`,
+    );
+  }
+  return geometry;
+}
+
+function readGeometryBody(reader: Reader, header: Header): Geometry {
+  switch (header.geomType) {
+    case TYPE_POINT:
+      return readPoint(reader, header);
+    case TYPE_LINESTRING:
+      return readLineString(reader, header);
+    case TYPE_POLYGON:
+      return readPolygon(reader, header);
+    case TYPE_MULTIPOINT:
+      return readMultiPoint(reader, header);
+    case TYPE_MULTILINESTRING:
+      return readMultiLineString(reader, header);
+    case TYPE_MULTIPOLYGON:
+      return readMultiPolygon(reader, header);
+    default:
+      throw new Error(`Geometry wire value: unsupported geometry type ${header.geomType}`);
+  }
+}
+
+/**
+ * Encode a GeoJSON-shaped geometry to an EWKT string PostGIS understands
+ * via `'<ewkt>'::geometry`. We use EWKT (not EWKB) on the way in so the
+ * generated SQL stays human-readable.
+ */
+export function encodeEWKT(value: Geometry): string {
+  const sridPrefix = value.srid !== undefined ? `SRID=${value.srid};` : '';
+  switch (value.type) {
+    case 'Point':
+      return `${sridPrefix}POINT(${formatPosition(value.coordinates)})`;
+    case 'LineString':
+      return `${sridPrefix}LINESTRING(${value.coordinates.map(formatPosition).join(',')})`;
+    case 'Polygon':
+      return `${sridPrefix}POLYGON(${formatRings(value.coordinates)})`;
+    case 'MultiPoint':
+      return `${sridPrefix}MULTIPOINT(${value.coordinates.map(formatPosition).join(',')})`;
+    case 'MultiLineString':
+      return `${sridPrefix}MULTILINESTRING(${value.coordinates
+        .map((line) => `(${line.map(formatPosition).join(',')})`)
+        .join(',')})`;
+    case 'MultiPolygon':
+      return `${sridPrefix}MULTIPOLYGON(${value.coordinates
+        .map((poly) => `(${formatRings(poly)})`)
+        .join(',')})`;
+  }
+}
+
+function formatPosition(p: Position): string {
+  if (!Number.isFinite(p[0]) || !Number.isFinite(p[1])) {
+    throw new Error('Geometry encode: coordinates must be finite numbers');
+  }
+  return `${p[0]} ${p[1]}`;
+}
+
+function formatRings(rings: ReadonlyArray<ReadonlyArray<Position>>): string {
+  return rings.map((ring) => `(${ring.map(formatPosition).join(',')})`).join(',');
+}