@math.gl/geospatial 5.0.0-alpha.9 → 5.0.0-beta.2

package/src/crs/resolver.ts

@@ -0,0 +1,194 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {createSpatialReference, inferCRSRepresentation} from './spatial-reference';
+import type {
+  CRSInput,
+  CRSReference,
+  ReadonlyCRSDefinition,
+  SpatialReference
+} from './spatial-reference';
+
+/** An application-owned catalogue. Null means a miss; errors stop resolution. */
+export type CRSDefinitionProvider = Readonly<{
+  id: string;
+  /** Catalogue/database revision, for diagnostics. Create a new resolver when it changes. */
+  version?: string;
+  resolve(identifier: string): ReadonlyCRSDefinition | null | Promise<ReadonlyCRSDefinition | null>;
+}>;
+
+export type CRSLookup = Readonly<{identifier: string; provider: string; version?: string}>;
+export type CRSResolution = Readonly<{
+  /** Resolved input, retaining source storage conventions and original references. */
+  input: CRSInput;
+  lookups: readonly CRSLookup[];
+}>;
+export type CRSResolverOptions = Readonly<{
+  providers: readonly CRSDefinitionProvider[];
+  /** Maximum cached top-level identifier requests, including pending requests. Default 128. */
+  maxCacheSize?: number;
+  /** Maximum provider alias hops. Default 16. */
+  maxDepth?: number;
+}>;
+export interface CRSResolver {
+  resolve(input: CRSInput): Promise<CRSResolution>;
+  /** Evict cached successes and pending requests; already returned promises still complete. */
+  clear(): void;
+}
+
+export class CRSResolutionError extends Error {
+  constructor(
+    readonly reason: 'not-found' | 'cycle' | 'limit' | 'invalid-result',
+    readonly identifier: string
+  ) {
+    super(`CRS resolution ${reason}: ${identifier}`);
+    this.name = 'CRSResolutionError';
+  }
+}
+
+/** Snapshot a local catalogue without registering it globally. Exact keys are significant. */
+export function createCRSDictionaryProvider(
+  definitions: Readonly<Record<string, ReadonlyCRSDefinition>>,
+  options: {id?: string; version?: string} = {}
+): CRSDefinitionProvider {
+  const entries = new Map(
+    Object.entries(definitions).map(([key, value]) => [key, snapshot(value)])
+  );
+  return Object.freeze({
+    id: options.id ?? 'dictionary',
+    version: options.version,
+    resolve: (identifier: string) => entries.get(identifier) ?? null
+  });
+}
+
+/** Resolve definitions only. No bundled authority database, network access or coordinate execution. */
+export function createCRSResolver(options: CRSResolverOptions): CRSResolver {
+  const {maxCacheSize = 128, maxDepth = 16} = options;
+  if (
+    !Number.isSafeInteger(maxCacheSize) ||
+    maxCacheSize < 0 ||
+    !Number.isSafeInteger(maxDepth) ||
+    maxDepth < 0
+  ) {
+    throw new RangeError('Invalid CRS resolver cache size or alias depth');
+  }
+  const providers = options.providers.map(provider => {
+    if (!provider.id.trim() || typeof provider.resolve !== 'function') {
+      throw new TypeError('A CRS provider needs an id and resolve method');
+    }
+    return {id: provider.id, version: provider.version, resolve: provider.resolve.bind(provider)};
+  });
+  if (new Set(providers.map(provider => provider.id)).size !== providers.length) {
+    throw new Error('CRS provider ids must be unique');
+  }
+  type DefinitionResult = {definition: ReadonlyCRSDefinition; lookups: readonly CRSLookup[]};
+  const cache = new Map<string, Promise<DefinitionResult>>();
+
+  async function lookup(
+    identifier: string,
+    visited = new Set<string>()
+  ): Promise<DefinitionResult> {
+    if (visited.has(identifier)) throw new CRSResolutionError('cycle', identifier);
+    if (visited.size > maxDepth) throw new CRSResolutionError('limit', identifier);
+    visited.add(identifier);
+    for (const provider of providers) {
+      const supplied = await provider.resolve(identifier);
+      if (supplied === null) continue;
+      if (
+        !(typeof supplied === 'string' && supplied.trim()) &&
+        !(
+          supplied &&
+          typeof supplied === 'object' &&
+          !Array.isArray(supplied) &&
+          typeof supplied.type === 'string'
+        )
+      ) {
+        throw new CRSResolutionError('invalid-result', identifier);
+      }
+      const definition = snapshot(supplied);
+      const entry = Object.freeze({identifier, provider: provider.id, version: provider.version});
+      if (typeof definition === 'string' && inferCRSRepresentation(definition) === 'identifier') {
+        const next = await lookup(definition, visited);
+        return {definition: next.definition, lookups: Object.freeze([entry, ...next.lookups])};
+      }
+      return {definition, lookups: Object.freeze([entry])};
+    }
+    throw new CRSResolutionError('not-found', identifier);
+  }
+
+  function resolveDefinition(
+    definition: ReadonlyCRSDefinition,
+    representation = inferCRSRepresentation(definition)
+  ): Promise<DefinitionResult> {
+    if (typeof definition !== 'string' || representation !== 'identifier') {
+      return Promise.resolve({definition, lookups: Object.freeze([])});
+    }
+    const existing = cache.get(definition);
+    if (existing) {
+      cache.delete(definition);
+      cache.set(definition, existing);
+      return existing;
+    }
+    const pending = lookup(definition).catch(error => {
+      if (cache.get(definition) === pending) cache.delete(definition);
+      throw error;
+    });
+    if (maxCacheSize) {
+      cache.set(definition, pending);
+      if (cache.size > maxCacheSize) cache.delete(cache.keys().next().value!);
+    }
+    return pending;
+  }
+
+  return Object.freeze({
+    clear: () => cache.clear(),
+    async resolve(input: CRSInput): Promise<CRSResolution> {
+      // Snapshot before awaiting a provider; metadata must not change during preparation.
+      const captured = snapshot(input);
+      const lookups: CRSLookup[] = [];
+      async function reference(ref: CRSReference): Promise<CRSReference> {
+        if (ref.state !== 'explicit' && ref.state !== 'default') return ref;
+        const result = await resolveDefinition(ref.definition, ref.representation);
+        lookups.push(...result.lookups);
+        if (!result.lookups.length) return ref;
+        return {
+          ...ref,
+          definition: result.definition,
+          representation: inferCRSRepresentation(result.definition),
+          alternatives: [
+            {definition: ref.definition, representation: ref.representation},
+            ...(ref.alternatives ?? [])
+          ]
+        };
+      }
+      let resolved: CRSInput;
+      if (typeof captured === 'string' || 'type' in captured) {
+        const result = await resolveDefinition(captured);
+        lookups.push(...result.lookups);
+        resolved = result.definition;
+      } else {
+        const metadata = captured as CRSReference | SpatialReference;
+        resolved =
+          'crs' in metadata
+            ? createSpatialReference({
+                ...metadata,
+                crs: await reference(metadata.crs),
+                vertical: metadata.vertical ? await reference(metadata.vertical) : undefined
+              })
+            : snapshot(await reference(metadata));
+      }
+      return Object.freeze({input: resolved, lookups: Object.freeze(lookups)});
+    }
+  });
+}
+
+function snapshot<T>(value: T): T {
+  if (Array.isArray(value)) return Object.freeze(value.map(item => snapshot(item))) as T;
+  if (value && typeof value === 'object') {
+    return Object.freeze(
+      Object.fromEntries(Object.entries(value).map(([key, item]) => [key, snapshot(item)]))
+    ) as T;
+  }
+  return value;
+}

package/src/crs/spatial-reference.ts

@@ -0,0 +1,224 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {CRSStringDefinition, PROJJSONCRS} from './crs';
+
+/** Recursively readonly view of a JSON-compatible type. */
+type DeepReadonly<T> = T extends readonly (infer Item)[]
+  ? readonly DeepReadonly<Item>[]
+  : T extends object
+    ? {readonly [Key in keyof T]: DeepReadonly<T[Key]>}
+    : T;
+
+/** A deeply readonly PROJJSON CRS object. */
+export type ReadonlyPROJJSONCRS<T extends PROJJSONCRS = PROJJSONCRS> = DeepReadonly<T>;
+
+/** A serialized CRS definition or deeply readonly PROJJSON CRS object. */
+export type ReadonlyCRSDefinition<T extends PROJJSONCRS = PROJJSONCRS> =
+  | CRSStringDefinition
+  | ReadonlyPROJJSONCRS<T>;
+
+/** Serialization or naming form in which a CRS definition was supplied. */
+export type SpatialReferenceRepresentation =
+  | 'identifier'
+  | 'wkt'
+  | 'proj-string'
+  | 'projjson'
+  | 'opaque';
+
+/** Whether a CRS was declared, supplied by a specification default, unknown, or absent. */
+export type SpatialReferenceState = 'explicit' | 'default' | 'unknown' | 'absent';
+
+/** Origin of a normalized CRS reference. */
+export type SpatialReferenceProvenance =
+  | 'metadata'
+  | 'format-default'
+  | 'caller-override'
+  | 'legacy-assumption'
+  | 'unknown';
+
+/** Broad coordinate frame used by a spatial dataset. */
+export type SpatialReferenceCoordinateFrame =
+  | 'geographic'
+  | 'geocentric'
+  | 'projected'
+  | 'local'
+  | 'unknown';
+
+/** One alternate serialization of the same CRS retained by the source. */
+export type SpatialReferenceAlternative = Readonly<{
+  /** Original alternate CRS definition. */
+  definition: ReadonlyCRSDefinition;
+  /** Representation used by the alternate definition. */
+  representation: SpatialReferenceRepresentation;
+}>;
+
+/** A known CRS and its source representation. */
+export type KnownCRSReference = Readonly<{
+  /** A known definition is either explicitly declared or established by a specification default. */
+  state: 'explicit' | 'default';
+  /** Preferred definition selected without discarding alternate source representations. */
+  definition: ReadonlyCRSDefinition;
+  /** Representation used by the preferred definition. */
+  representation: SpatialReferenceRepresentation;
+  /** How the preferred definition was established. */
+  provenance: SpatialReferenceProvenance;
+  /** Additional equivalent serializations carried by the source metadata. */
+  alternatives?: readonly SpatialReferenceAlternative[];
+}>;
+
+/** An unknown or absent CRS that must not be replaced by an implicit WGS84 assumption. */
+export type UnresolvedCRSReference = Readonly<{
+  /** `unknown` preserves an explicit unknown value; `absent` means no value was supplied. */
+  state: 'unknown' | 'absent';
+  /** How the unresolved state was established. */
+  provenance: SpatialReferenceProvenance;
+}>;
+
+/** Normalized CRS state, discriminated without comparing definition strings. */
+export type CRSReference = KnownCRSReference | UnresolvedCRSReference;
+
+/** Shared definition or source metadata accepted by CRS consumers. */
+export type CRSInput = ReadonlyCRSDefinition | CRSReference | SpatialReference;
+
+/**
+ * Format-neutral spatial-reference metadata.
+ *
+ * The descriptor reports how source coordinates are defined. It does not claim that coordinates,
+ * bounds, or heights have been transformed. Format-specific metadata remains responsible for
+ * lossless preservation of fields that cannot be represented here.
+ */
+export type SpatialReference = Readonly<{
+  /** Primary horizontal or compound CRS state. */
+  crs: CRSReference;
+  /** Independently declared vertical CRS state. */
+  vertical?: CRSReference;
+  /** Coordinate epoch associated with source coordinates, expressed as a decimal year. */
+  coordinateEpoch?: number;
+  /** Broad frame in which source coordinates are stored. */
+  coordinateFrame: SpatialReferenceCoordinateFrame;
+  /** Component order used by stored arrays, independent of authoritative CRS axis order. */
+  coordinateOrder: readonly string[];
+  /** Per-component units when declared by the source. */
+  units?: readonly string[];
+}>;
+
+/** Values accepted by {@link createSpatialReference}. */
+export type CreateSpatialReferenceOptions = Readonly<{
+  /** Primary horizontal or compound CRS state. Defaults to absent. */
+  crs?: CRSReference;
+  /** Independently declared vertical CRS state. */
+  vertical?: CRSReference;
+  /** Coordinate epoch associated with source coordinates. */
+  coordinateEpoch?: number;
+  /** Broad stored coordinate frame. Defaults to unknown. */
+  coordinateFrame?: SpatialReferenceCoordinateFrame;
+  /** Stored component order. Defaults to an empty, unknown order. */
+  coordinateOrder?: readonly string[];
+  /** Per-component units. */
+  units?: readonly string[];
+}>;
+
+/**
+ * Creates an immutable format-neutral spatial-reference descriptor.
+ *
+ * PROJJSON definitions and descriptor-owned arrays are cloned and recursively frozen. The
+ * function does not parse definitions, resolve identifiers, or determine semantic equivalence.
+ *
+ * @param options - Spatial-reference discovery results to normalize.
+ * @returns A readonly descriptor with cloned definitions and arrays.
+ */
+export function createSpatialReference(
+  options: CreateSpatialReferenceOptions = {}
+): SpatialReference {
+  if (options.coordinateEpoch !== undefined && !Number.isFinite(options.coordinateEpoch)) {
+    throw new Error('Spatial reference coordinate epoch must be a finite decimal year');
+  }
+
+  return Object.freeze({
+    crs: freezeCRSReference(options.crs || {state: 'absent', provenance: 'unknown'}),
+    vertical: options.vertical ? freezeCRSReference(options.vertical) : undefined,
+    coordinateEpoch: options.coordinateEpoch,
+    coordinateFrame: options.coordinateFrame || 'unknown',
+    coordinateOrder: Object.freeze([...(options.coordinateOrder || [])]),
+    units: options.units ? Object.freeze([...options.units]) : undefined
+  });
+}
+
+/**
+ * Infers a CRS representation from runtime syntax without resolving its meaning.
+ *
+ * Format adapters should pass an explicit representation when their metadata identifies one.
+ * Unrecognized free-form strings are classified as `opaque`, not assumed to be identifiers.
+ *
+ * @param definition - CRS definition to classify syntactically.
+ * @returns The apparent serialized representation.
+ */
+export function inferCRSRepresentation(
+  definition: ReadonlyCRSDefinition
+): SpatialReferenceRepresentation {
+  if (typeof definition === 'object') {
+    return 'projjson';
+  }
+
+  const text = definition.trim();
+  if (/^[A-Z][A-Z0-9_]*\s*[\[(]/i.test(text)) {
+    return 'wkt';
+  }
+  if (/(?:^|\s)\+?proj=/i.test(text)) {
+    return 'proj-string';
+  }
+  if (
+    /^[A-Z][A-Z0-9._-]*(?::[A-Z0-9._-]+)+$/i.test(text) ||
+    /^urn:ogc:def:crs:/i.test(text) ||
+    /^https?:\/\//i.test(text) ||
+    /^[A-Z][A-Z0-9._-]*$/i.test(text)
+  ) {
+    return 'identifier';
+  }
+  return 'opaque';
+}
+
+/** Clone and freeze one CRS reference without mutating caller-owned objects. */
+function freezeCRSReference(reference: CRSReference): CRSReference {
+  if (reference.state === 'explicit' || reference.state === 'default') {
+    return Object.freeze({
+      ...reference,
+      definition: cloneAndFreezeDefinition(reference.definition),
+      alternatives: reference.alternatives
+        ? Object.freeze(
+            reference.alternatives.map(alternative =>
+              Object.freeze({
+                ...alternative,
+                definition: cloneAndFreezeDefinition(alternative.definition)
+              })
+            )
+          )
+        : undefined
+    });
+  }
+  return Object.freeze({...reference});
+}
+
+/** Clone and recursively freeze a JSON CRS object while leaving string definitions unchanged. */
+function cloneAndFreezeDefinition(definition: ReadonlyCRSDefinition): ReadonlyCRSDefinition {
+  return typeof definition === 'string'
+    ? definition
+    : (cloneAndFreezeJsonValue(definition) as ReadonlyCRSDefinition);
+}
+
+/** Clone and freeze the JSON-compatible values used by PROJJSON definitions. */
+function cloneAndFreezeJsonValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return Object.freeze(value.map(item => cloneAndFreezeJsonValue(item)));
+  }
+  if (value && typeof value === 'object') {
+    return Object.freeze(
+      Object.fromEntries(
+        Object.entries(value).map(([key, item]) => [key, cloneAndFreezeJsonValue(item)])
+      )
+    );
+  }
+  return value;
+}

package/src/crs/units-table.ts

@@ -0,0 +1,51 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2014 Mike Adair, Richard Greenwood, Didier Richard, Stephen Irons, Olivier Terral and Calvin Metcalf (proj4js)
+// SPDX-FileComment: Unit conversion factors adapted from proj4js 2.22.0.
+
+/*
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * _THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE._
+ */
+
+import type {CRSUnit} from './crs-metadata';
+
+/** Linear units keyed by PROJ unit identifier, with names and metre conversion factors. */
+export const linearUnits: Readonly<Record<string, CRSUnit>> = {
+  m: {name: 'meters', metersPerUnit: 1},
+  mm: {name: 'millimeters', metersPerUnit: 0.001},
+  cm: {name: 'centimeters', metersPerUnit: 0.01},
+  ft: {name: 'feet', metersPerUnit: 0.3048},
+  'us-ft': {name: 'us-survey-feet', metersPerUnit: 1200 / 3937},
+  fath: {name: 'fathoms', metersPerUnit: 1.8288},
+  kmi: {name: 'nautical-miles', metersPerUnit: 1852},
+  'us-ch': {name: 'us-survey-chains', metersPerUnit: 20.1168402336805},
+  'us-mi': {name: 'us-survey-miles', metersPerUnit: 1609.34721869444},
+  km: {name: 'kilometers', metersPerUnit: 1000},
+  'ind-ft': {name: 'indian-feet', metersPerUnit: 0.30479841},
+  'ind-yd': {name: 'indian-yards', metersPerUnit: 0.91439523},
+  mi: {name: 'miles', metersPerUnit: 1609.344},
+  yd: {name: 'yards', metersPerUnit: 0.9144},
+  ch: {name: 'chains', metersPerUnit: 20.1168},
+  link: {name: 'links', metersPerUnit: 0.201168},
+  dm: {name: 'decimeters', metersPerUnit: 0.1},
+  in: {name: 'inches', metersPerUnit: 0.0254},
+  'ind-ch': {name: 'indian-chains', metersPerUnit: 20.11669506},
+  'us-in': {name: 'us-survey-inches', metersPerUnit: 0.025400050800101},
+  'us-yd': {name: 'us-survey-yards', metersPerUnit: 0.914401828803658}
+};