@prisma-next/extension-postgis 0.0.1

package/src/core/geojson.ts

@@ -0,0 +1,131 @@
+/**
+ * GeoJSON-shaped value types used by the PostGIS codec.
+ *
+ * The codec speaks GeoJSON-style objects to JavaScript callers and
+ * EWKT/EWKB on the wire. This file is the single source of truth for the
+ * value shapes; the public type re-export lives in `exports/geojson.ts`.
+ */
+
+export type Position = readonly [number, number];
+
+export type GeometryPoint = {
+  readonly type: 'Point';
+  readonly coordinates: Position;
+  readonly srid?: number;
+};
+
+export type GeometryLineString = {
+  readonly type: 'LineString';
+  readonly coordinates: ReadonlyArray<Position>;
+  readonly srid?: number;
+};
+
+export type GeometryPolygon = {
+  readonly type: 'Polygon';
+  readonly coordinates: ReadonlyArray<ReadonlyArray<Position>>;
+  readonly srid?: number;
+};
+
+export type GeometryMultiPoint = {
+  readonly type: 'MultiPoint';
+  readonly coordinates: ReadonlyArray<Position>;
+  readonly srid?: number;
+};
+
+export type GeometryMultiLineString = {
+  readonly type: 'MultiLineString';
+  readonly coordinates: ReadonlyArray<ReadonlyArray<Position>>;
+  readonly srid?: number;
+};
+
+export type GeometryMultiPolygon = {
+  readonly type: 'MultiPolygon';
+  readonly coordinates: ReadonlyArray<ReadonlyArray<ReadonlyArray<Position>>>;
+  readonly srid?: number;
+};
+
+export type Geometry =
+  | GeometryPoint
+  | GeometryLineString
+  | GeometryPolygon
+  | GeometryMultiPoint
+  | GeometryMultiLineString
+  | GeometryMultiPolygon;
+
+/**
+ * Construct a Point. Convenience for the common "lng/lat" case.
+ *
+ * @example
+ *   point(-122.4194, 37.7749, 4326)
+ */
+export function point(longitude: number, latitude: number, srid?: number): GeometryPoint {
+  if (!Number.isFinite(longitude) || !Number.isFinite(latitude)) {
+    throw new RangeError('point: coordinates must be finite numbers');
+  }
+  return srid !== undefined
+    ? { type: 'Point', coordinates: [longitude, latitude], srid }
+    : { type: 'Point', coordinates: [longitude, latitude] };
+}
+
+/**
+ * Construct a Polygon from a single outer ring of `[lng, lat]` pairs.
+ * If the first and last positions differ, the ring is closed automatically.
+ */
+export function polygon(ring: ReadonlyArray<Position>, srid?: number): GeometryPolygon {
+  if (ring.length < 3) {
+    throw new Error('polygon: ring must contain at least 3 positions');
+  }
+  const first = ring[0];
+  const last = ring[ring.length - 1];
+  if (!first || !last) {
+    throw new Error('polygon: ring positions cannot be undefined');
+  }
+  for (const position of ring) {
+    if (!Number.isFinite(position[0]) || !Number.isFinite(position[1])) {
+      throw new RangeError('polygon: coordinates must be finite numbers');
+    }
+  }
+  const closed = first[0] === last[0] && first[1] === last[1] ? ring : [...ring, first];
+  const distinct = new Set(closed.slice(0, -1).map(([x, y]) => `${x},${y}`));
+  if (distinct.size < 3) {
+    throw new Error('polygon: ring must contain at least 3 distinct positions');
+  }
+  return srid !== undefined
+    ? { type: 'Polygon', coordinates: [closed], srid }
+    : { type: 'Polygon', coordinates: [closed] };
+}
+
+/**
+ * Construct a rectangular Polygon from a bounding box.
+ *
+ * @param bbox - `[minLng, minLat, maxLng, maxLat]`
+ */
+export function bboxPolygon(
+  bbox: readonly [number, number, number, number],
+  srid?: number,
+): GeometryPolygon {
+  const [minX, minY, maxX, maxY] = bbox;
+  if (
+    !Number.isFinite(minX) ||
+    !Number.isFinite(minY) ||
+    !Number.isFinite(maxX) ||
+    !Number.isFinite(maxY)
+  ) {
+    throw new RangeError('bboxPolygon: coordinates must be finite numbers');
+  }
+  if (minX > maxX || minY > maxY) {
+    throw new Error(
+      `bboxPolygon: inverted bbox [${minX}, ${minY}, ${maxX}, ${maxY}] (expected minX <= maxX and minY <= maxY)`,
+    );
+  }
+  return polygon(
+    [
+      [minX, minY],
+      [maxX, minY],
+      [maxX, maxY],
+      [minX, maxY],
+      [minX, minY],
+    ],
+    srid,
+  );
+}

package/src/core/registry.ts

@@ -0,0 +1,14 @@
+import { buildCodecDescriptorRegistry } from '@prisma-next/sql-relational-core/codec-descriptor-registry';
+import type { CodecDescriptorRegistry } from '@prisma-next/sql-relational-core/query-lane-context';
+import { codecDescriptors } from './codecs';
+
+/**
+ * Registry of every codec descriptor shipped by `@prisma-next/extension-postgis`.
+ *
+ * Public consumer surface for the postgis codec set. Currently a single
+ * entry (`pg/geometry@1`); the registry shape stays consistent with
+ * the other codec-shipping packages so consumers don't need to
+ * special-case extensions.
+ */
+export const postgisCodecRegistry: CodecDescriptorRegistry =
+  buildCodecDescriptorRegistry(codecDescriptors);

package/src/exports/codec-types.ts

@@ -0,0 +1,7 @@
+/**
+ * Codec type definitions for the PostGIS extension.
+ *
+ * Re-export from types module for public API.
+ */
+
+export type { CodecTypes, Geometry } from '../types/codec-types';

package/src/exports/column-types.ts

@@ -0,0 +1,38 @@
+/**
+ * Column type descriptors for the PostGIS extension.
+ *
+ * Use `geometryColumn` for an untyped `geometry` column, or
+ * `geometry({ srid })` to declare an SRID-constrained column whose DDL
+ * comes out as `geometry(Geometry, <srid>)`.
+ */
+
+import type { ColumnTypeDescriptor } from '@prisma-next/framework-components/codec';
+import { POSTGIS_GEOMETRY_CODEC_ID } from '../core/constants';
+
+export const geometryColumn = {
+  codecId: POSTGIS_GEOMETRY_CODEC_ID,
+  nativeType: 'geometry',
+} as const satisfies ColumnTypeDescriptor;
+
+/**
+ * Build an SRID-constrained geometry column descriptor.
+ *
+ * @example
+ *   .column('location', { type: geometry({ srid: 4326 }), nullable: false })
+ *   // Produces: nativeType: 'geometry', typeParams: { srid: 4326 }
+ *
+ * @throws {RangeError} If `srid` is not a non-negative integer.
+ */
+export function geometry<S extends number>(options: {
+  readonly srid: S;
+}): ColumnTypeDescriptor & { readonly typeParams: { 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 {
+    codecId: POSTGIS_GEOMETRY_CODEC_ID,
+    nativeType: 'geometry',
+    typeParams: { srid },
+  } as const;
+}

package/src/exports/control.ts

@@ -0,0 +1,101 @@
+/**
+ * Control-plane descriptor for the postgis extension.
+ *
+ * **Contract-space package layout.** The extension's contract
+ * + migrations are emitted by the same pipeline application authors use:
+ *
+ *   `prisma-next contract emit` → `<package>/src/contract.{json,d.ts}`
+ *   `prisma-next migration plan` → `<package>/migrations/<dir>/...`
+ *
+ * The descriptor wires those JSON artefacts via JSON-import declarations
+ * so they flow through the consuming application's module resolver
+ * without filesystem assumptions, and synthesises the canonical
+ * `MigrationPackage` shape for the framework's runner / verifier to
+ * consume.
+ *
+ * Wired surfaces:
+ *
+ *   - `contractSpace.{contractJson,migrations,headRef}` — sourced from
+ *     the on-disk artefacts emitted by `build:contract-space`.
+ *   - `types.codecTypes.controlPlaneHooks[POSTGIS_GEOMETRY_CODEC_ID]` —
+ *     codec control hooks (`expandNativeType`, `resolveIdentityValue`)
+ *     the SQL planner extracts via `extractCodecControlHooks` and uses
+ *     to render `geometry(Geometry,${srid})` column types.
+ *
+ * @see docs/architecture docs/adrs/ADR 212 - Contract spaces.md
+ *   (contract-space package layout convention).
+ */
+
+import type { Contract } from '@prisma-next/contract/types';
+import type {
+  CodecControlHooks,
+  SqlControlExtensionDescriptor,
+} from '@prisma-next/family-sql/control';
+import { contractSpaceFromJson } from '@prisma-next/migration-tools/spaces';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import baselineMetadata from '../../migrations/20260601T0000_install_postgis_extension/migration.json' with {
+  type: 'json',
+};
+import baselineOps from '../../migrations/20260601T0000_install_postgis_extension/ops.json' with {
+  type: 'json',
+};
+import headRef from '../../migrations/refs/head.json' with { type: 'json' };
+import contractJson from '../contract.json' with { type: 'json' };
+import { POSTGIS_GEOMETRY_CODEC_ID } from '../core/constants';
+import {
+  POSTGIS_BASELINE_MIGRATION_NAME,
+  POSTGIS_SPACE_ID,
+} from '../core/contract-space-constants';
+import { postgisPackMeta, postgisQueryOperations } from '../core/descriptor-meta';
+
+const geometryControlPlaneHooks: CodecControlHooks = {
+  expandNativeType: ({ nativeType, typeParams }) => {
+    const srid = typeParams?.['srid'];
+    if (typeof srid === 'number' && Number.isInteger(srid) && srid >= 0) {
+      // PostGIS prints the type-modifier list without a space — match
+      // it here so the verifier doesn't see `geometry(Geometry, 4326)`
+      // (DDL) mismatch `geometry(Geometry,4326)` (introspected).
+      return `${nativeType}(Geometry,${srid})`;
+    }
+    return nativeType;
+  },
+  // PostGIS has no canonical "identity" geometry; backfilling a
+  // non-null column requires the user to supply a valid value, so we
+  // don't synthesise one here.
+  resolveIdentityValue: () => null,
+};
+
+const postgisContractSpace = contractSpaceFromJson<Contract<SqlStorage>>({
+  contractJson,
+  migrations: [
+    {
+      dirName: POSTGIS_BASELINE_MIGRATION_NAME,
+      metadata: baselineMetadata,
+      ops: baselineOps,
+    },
+  ],
+  headRef,
+});
+
+const postgisExtensionDescriptor: SqlControlExtensionDescriptor<'postgres'> = {
+  ...postgisPackMeta,
+  id: POSTGIS_SPACE_ID,
+  contractSpace: postgisContractSpace,
+  types: {
+    ...postgisPackMeta.types,
+    codecTypes: {
+      ...postgisPackMeta.types.codecTypes,
+      controlPlaneHooks: {
+        [POSTGIS_GEOMETRY_CODEC_ID]: geometryControlPlaneHooks,
+      },
+    },
+  },
+  queryOperations: () => postgisQueryOperations(),
+  create: () => ({
+    familyId: 'sql' as const,
+    targetId: 'postgres' as const,
+  }),
+};
+
+export { postgisExtensionDescriptor };
+export default postgisExtensionDescriptor;

package/src/exports/geojson.ts

@@ -0,0 +1,19 @@
+/**
+ * GeoJSON-shaped value types and constructors used by the PostGIS codec.
+ *
+ * Surface these so callers can produce well-formed point/polygon values
+ * without depending on internal modules.
+ */
+
+export type {
+  Geometry,
+  GeometryLineString,
+  GeometryMultiLineString,
+  GeometryMultiPoint,
+  GeometryMultiPolygon,
+  GeometryPoint,
+  GeometryPolygon,
+  Position,
+} from '../core/geojson';
+
+export { bboxPolygon, point, polygon } from '../core/geojson';

package/src/exports/operation-types.ts

@@ -0,0 +1,7 @@
+/**
+ * Operation type definitions for the PostGIS extension.
+ *
+ * Re-export from types module for public API.
+ */
+
+export type { OperationTypes, QueryOperationTypes } from '../types/operation-types';

package/src/exports/pack.ts

@@ -0,0 +1 @@
+export { postgisPackMeta as default } from '../core/descriptor-meta';

package/src/exports/runtime.ts

@@ -0,0 +1,34 @@
+import type { SqlRuntimeExtensionDescriptor } from '@prisma-next/sql-runtime';
+import { postgisPackMeta, postgisQueryOperations } from '../core/descriptor-meta';
+import { postgisCodecRegistry } from '../core/registry';
+
+const postgisRuntimeDescriptor: SqlRuntimeExtensionDescriptor<'postgres'> = {
+  kind: 'extension' as const,
+  id: postgisPackMeta.id,
+  version: postgisPackMeta.version,
+  familyId: 'sql' as const,
+  targetId: 'postgres' as const,
+  // Expose the unified descriptor list so `extractCodecLookup` reads
+  // `targetTypes` / `meta` / `renderOutputType` directly off the
+  // descriptors and materialises the representative `Codec` for the
+  // SQL renderer's cast-policy lookup. Without it, the Postgres
+  // adapter's runtime codec lookup would miss `pg/geometry@1` and
+  // `$N::geometry` casts would disappear once the renderer switches
+  // to lookup-driven cast policy.
+  types: {
+    codecTypes: {
+      codecDescriptors: Array.from(postgisCodecRegistry.values()),
+    },
+  },
+  codecs: () => Array.from(postgisCodecRegistry.values()),
+  queryOperations: () => postgisQueryOperations(),
+  create() {
+    return {
+      familyId: 'sql' as const,
+      targetId: 'postgres' as const,
+    };
+  },
+};
+
+export { postgisCodecRegistry };
+export default postgisRuntimeDescriptor;

package/src/types/codec-types.ts

@@ -0,0 +1,16 @@
+/**
+ * Codec type definitions for the PostGIS extension.
+ *
+ * The runtime value carried for a `pg/geometry@1` cell is a GeoJSON-shaped
+ * object — see `core/geojson.ts` for the variant union. The `Geometry`
+ * type re-exported here is what `contract.d.ts` will reference; the
+ * optional generic `<S>` carries SRID metadata at the type level for
+ * dimensioned columns (e.g. `Geometry<4326>`).
+ */
+
+import type { CodecTypes as CoreCodecTypes } from '../core/codecs';
+import type { Geometry as GeometryValue } from '../core/geojson';
+
+export type Geometry<_Srid extends number = number> = GeometryValue;
+
+export type CodecTypes = CoreCodecTypes;

package/src/types/operation-types.ts

@@ -0,0 +1,81 @@
+import type { SqlQueryOperationTypes } from '@prisma-next/sql-contract/types';
+import type { CodecExpression, Expression } from '@prisma-next/sql-relational-core/expression';
+
+type CodecTypesBase = Record<string, { readonly input: unknown; readonly output: unknown }>;
+
+/**
+ * Operation type definitions for the PostGIS extension.
+ *
+ * These are type-only signatures consumed by emitted `contract.d.ts`
+ * files so the query builder surfaces `.distance()`, `.dwithin()`,
+ * `.contains()`, `.within()`, `.intersects()`, and `.intersectsBbox()`
+ * on `geometry` columns.
+ */
+
+export type OperationTypes = {
+  readonly 'pg/geometry@1': {
+    readonly distance: { readonly self: { readonly codecId: 'pg/geometry@1' } };
+    readonly distanceSphere: { readonly self: { readonly codecId: 'pg/geometry@1' } };
+    readonly dwithin: { readonly self: { readonly codecId: 'pg/geometry@1' } };
+    readonly contains: { readonly self: { readonly codecId: 'pg/geometry@1' } };
+    readonly within: { readonly self: { readonly codecId: 'pg/geometry@1' } };
+    readonly intersects: { readonly self: { readonly codecId: 'pg/geometry@1' } };
+    readonly intersectsBbox: { readonly self: { readonly codecId: 'pg/geometry@1' } };
+  };
+};
+
+export type QueryOperationTypes<CT extends CodecTypesBase> = SqlQueryOperationTypes<
+  CT,
+  {
+    readonly distance: {
+      readonly self: { readonly codecId: 'pg/geometry@1' };
+      readonly impl: (
+        self: CodecExpression<'pg/geometry@1', boolean, CT>,
+        other: CodecExpression<'pg/geometry@1', boolean, CT>,
+      ) => Expression<{ codecId: 'pg/float8@1'; nullable: false }>;
+    };
+    readonly distanceSphere: {
+      readonly self: { readonly codecId: 'pg/geometry@1' };
+      readonly impl: (
+        self: CodecExpression<'pg/geometry@1', boolean, CT>,
+        other: CodecExpression<'pg/geometry@1', boolean, CT>,
+      ) => Expression<{ codecId: 'pg/float8@1'; nullable: false }>;
+    };
+    readonly dwithin: {
+      readonly self: { readonly codecId: 'pg/geometry@1' };
+      readonly impl: (
+        self: CodecExpression<'pg/geometry@1', boolean, CT>,
+        other: CodecExpression<'pg/geometry@1', boolean, CT>,
+        distance: CodecExpression<'pg/float8@1', boolean, CT>,
+      ) => Expression<{ codecId: 'pg/bool@1'; nullable: false }>;
+    };
+    readonly contains: {
+      readonly self: { readonly codecId: 'pg/geometry@1' };
+      readonly impl: (
+        self: CodecExpression<'pg/geometry@1', boolean, CT>,
+        other: CodecExpression<'pg/geometry@1', boolean, CT>,
+      ) => Expression<{ codecId: 'pg/bool@1'; nullable: false }>;
+    };
+    readonly within: {
+      readonly self: { readonly codecId: 'pg/geometry@1' };
+      readonly impl: (
+        self: CodecExpression<'pg/geometry@1', boolean, CT>,
+        other: CodecExpression<'pg/geometry@1', boolean, CT>,
+      ) => Expression<{ codecId: 'pg/bool@1'; nullable: false }>;
+    };
+    readonly intersects: {
+      readonly self: { readonly codecId: 'pg/geometry@1' };
+      readonly impl: (
+        self: CodecExpression<'pg/geometry@1', boolean, CT>,
+        other: CodecExpression<'pg/geometry@1', boolean, CT>,
+      ) => Expression<{ codecId: 'pg/bool@1'; nullable: false }>;
+    };
+    readonly intersectsBbox: {
+      readonly self: { readonly codecId: 'pg/geometry@1' };
+      readonly impl: (
+        self: CodecExpression<'pg/geometry@1', boolean, CT>,
+        other: CodecExpression<'pg/geometry@1', boolean, CT>,
+      ) => Expression<{ codecId: 'pg/bool@1'; nullable: false }>;
+    };
+  }
+>;