@bitbaum/geo-kit 0.0.0-stage → 0.1.1

package/dist/resources.js

@@ -0,0 +1,270 @@
+import { GeographyError } from "./errors.js";
+import { fetchGeographyBytes, publicDataUrl } from "./http.js";
+import { intersectsGeographyBounds, isWgs84Bounds } from "./spatial.js";
+import { isISODate, isPlainObject, periodContains, validateGeographyManifest, validateGeometry } from "./validation.js";
+export function selectGeographyResources(manifest, request) {
+    const manifestProblems = validateGeographyManifest(manifest);
+    if (manifestProblems.length) {
+        throw new GeographyError("invalid_manifest", manifestProblems.slice(0, 8).join("; "));
+    }
+    if (!isISODate(request.asOf))
+        throw new GeographyError("invalid_manifest", "asOf must be a real ISO date");
+    if (request.bbox !== undefined && !isWgs84Bounds(request.bbox)) {
+        throw new GeographyError("invalid_manifest", "bbox must contain WGS84 bounds in west/south/east/north order");
+    }
+    const geographyIds = new Set(request.geographyIds ?? []);
+    const resourceIds = new Set(request.resourceIds ?? []);
+    if (geographyIds.size === 0 && resourceIds.size === 0) {
+        throw new GeographyError("selection_required", "request at least one geographyId or resourceId");
+    }
+    const kindKeys = request.kindKeys ? new Set(request.kindKeys) : null;
+    const levelKeys = request.levelKeys ? new Set(request.levelKeys) : null;
+    if (request.zoom !== undefined && (!Number.isFinite(request.zoom) || request.zoom < 0 || request.zoom > 30)) {
+        throw new GeographyError("invalid_manifest", "zoom must be between 0 and 30");
+    }
+    const selected = manifest.resources.filter((resource) => {
+        if (resourceIds.size > 0 && !resourceIds.has(resource.id))
+            return false;
+        if (geographyIds.size > 0 && !geographyIds.has(resource.geographyId))
+            return false;
+        if (kindKeys && !kindKeys.has(resource.kindKey))
+            return false;
+        if (levelKeys && !levelKeys.has(resource.levelKey))
+            return false;
+        if (request.bbox && resource.bbox && !intersectsGeographyBounds(request.bbox, resource.bbox))
+            return false;
+        if (!periodContains(resource.validFrom, resource.validTo, request.asOf))
+            return false;
+        if (request.viewpointKey === undefined && resource.viewpointKey !== null)
+            return false;
+        if (request.viewpointKey !== undefined && request.viewpointKey !== "all" &&
+            resource.viewpointKey !== null && resource.viewpointKey !== request.viewpointKey)
+            return false;
+        if (request.zoom !== undefined &&
+            ((resource.minZoom !== undefined && request.zoom < resource.minZoom) ||
+                (resource.maxZoom !== undefined && request.zoom >= resource.maxZoom)))
+            return false;
+        return true;
+    });
+    const maxResources = request.maxResources ?? 128;
+    const maxBytes = request.maxBytes ?? 32 * 1024 * 1024;
+    if (!Number.isSafeInteger(maxResources) || maxResources < 1 || !Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+        throw new GeographyError("invalid_manifest", "selection limits must be positive safe integers");
+    }
+    if (selected.length > maxResources) {
+        throw new GeographyError("selection_limit", `selection has ${selected.length} resources; limit is ${maxResources}`);
+    }
+    const total = selected.reduce((sum, resource) => sum + resource.byteSize, 0);
+    if (!Number.isSafeInteger(total) || total > maxBytes) {
+        throw new GeographyError("selection_limit", `selection is ${total} bytes; limit is ${maxBytes}`);
+    }
+    return selected.sort((a, b) => lexical(a.geographyId, b.geographyId) ||
+        lexical(a.kindKey, b.kindKey) ||
+        lexical(a.levelKey, b.levelKey) ||
+        lexical(a.id, b.id));
+}
+function lexical(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Verify the declared digest, exact decoded size, JSON shape, and feature count. */
+export async function verifyGeographyResource(resource, bytes) {
+    if (bytes.byteLength !== resource.byteSize) {
+        throw new GeographyError("invalid_resource", `resource ${resource.id} has ${bytes.byteLength} bytes; expected ${resource.byteSize}`);
+    }
+    const digest = await sha256Hex(bytes);
+    if (digest !== resource.sha256.toLowerCase()) {
+        throw new GeographyError("invalid_resource", `resource ${resource.id} failed its SHA-256 check`);
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new GeographyError("invalid_resource", `resource ${resource.id} is not valid UTF-8 JSON`);
+    }
+    const problems = resource.format === "geojson"
+        ? validateFeatureCollection(decoded)
+        : validateTopology(decoded);
+    if (problems.length) {
+        throw new GeographyError("invalid_resource", `resource ${resource.id}: ${problems.slice(0, 8).join("; ")}`);
+    }
+    const actualCount = resource.format === "geojson"
+        ? decoded.features.length
+        : countTopoFeatures(decoded);
+    if (actualCount !== resource.featureCount) {
+        throw new GeographyError("invalid_resource", `resource ${resource.id} has ${actualCount} features; expected ${resource.featureCount}`);
+    }
+    return decoded;
+}
+function validateFeatureCollection(value) {
+    if (!isPlainObject(value) || value.type !== "FeatureCollection" || !Array.isArray(value.features)) {
+        return ["expected a GeoJSON FeatureCollection"];
+    }
+    const problems = [];
+    for (const [i, feature] of value.features.entries()) {
+        if (!isPlainObject(feature) || feature.type !== "Feature" || !("geometry" in feature)) {
+            problems.push(`features[${i}] is not a GeoJSON Feature`);
+        }
+        else if (feature.geometry === null) {
+            problems.push(`features[${i}] has no geometry`);
+        }
+        else {
+            problems.push(...validateGeometry(feature.geometry, 2_000_000).map((problem) => `features[${i}].${problem}`));
+        }
+        if (isPlainObject(feature) && feature.properties !== null && !isPlainObject(feature.properties)) {
+            problems.push(`features[${i}].properties must be an object or null`);
+        }
+        if (problems.length >= 40)
+            break;
+    }
+    return problems;
+}
+function validateTopology(value) {
+    if (!isPlainObject(value) || value.type !== "Topology" || !Array.isArray(value.arcs) || !isPlainObject(value.objects)) {
+        return ["expected a TopoJSON Topology with arcs and objects"];
+    }
+    const topology = value;
+    const problems = [];
+    const transform = topology.transform;
+    const hasValidTransform = transform === undefined || (!isPlainObject(transform) || !Array.isArray(transform.scale) || !Array.isArray(transform.translate) ||
+        transform.scale.length !== 2 || transform.translate.length !== 2 ||
+        ![...transform.scale, ...transform.translate].every(Number.isFinite)) === false;
+    if (!hasValidTransform) {
+        problems.push("transform must contain finite two-dimensional scale and translate values");
+    }
+    for (const [i, rawArc] of topology.arcs.entries()) {
+        if (!Array.isArray(rawArc) || rawArc.length < 2) {
+            problems.push(`arcs[${i}] needs at least two positions`);
+            continue;
+        }
+        let x = 0;
+        let y = 0;
+        for (const [j, rawPosition] of rawArc.entries()) {
+            if (!Array.isArray(rawPosition) || rawPosition.length < 2 || !rawPosition.every(Number.isFinite)) {
+                problems.push(`arcs[${i}][${j}] must contain finite coordinates`);
+                break;
+            }
+            if (transform && hasValidTransform) {
+                x += rawPosition[0];
+                y += rawPosition[1];
+                const lon = x * transform.scale[0] + transform.translate[0];
+                const lat = y * transform.scale[1] + transform.translate[1];
+                if (lon < -180 || lon > 180 || lat < -90 || lat > 90) {
+                    problems.push(`arcs[${i}][${j}] decodes outside WGS84 bounds`);
+                    break;
+                }
+            }
+            else if (rawPosition[0] < -180 || rawPosition[0] > 180 || rawPosition[1] < -90 || rawPosition[1] > 90) {
+                problems.push(`arcs[${i}][${j}] is outside WGS84 bounds`);
+                break;
+            }
+        }
+        if (problems.length >= 40)
+            break;
+    }
+    const checkReferences = (geometry, path) => {
+        if (!isPlainObject(geometry)) {
+            problems.push(`${path} must be a geometry object`);
+            return;
+        }
+        if (geometry.type === "GeometryCollection") {
+            if (!Array.isArray(geometry.geometries))
+                problems.push(`${path}.geometries must be an array`);
+            else
+                geometry.geometries.forEach((child, i) => checkReferences(child, `${path}.geometries[${i}]`));
+            return;
+        }
+        if (["LineString", "MultiLineString", "Polygon", "MultiPolygon"].includes(String(geometry.type))) {
+            const references = [];
+            const flatten = (part) => {
+                if (typeof part === "number")
+                    references.push(part);
+                else if (Array.isArray(part))
+                    part.forEach(flatten);
+            };
+            flatten(geometry.arcs);
+            if (references.length === 0)
+                problems.push(`${path}.arcs must contain arc references`);
+            for (const ref of references) {
+                const index = ref >= 0 ? ref : ~ref;
+                if (!Number.isSafeInteger(ref) || index < 0 || index >= topology.arcs.length) {
+                    problems.push(`${path} references a missing arc`);
+                    break;
+                }
+            }
+            return;
+        }
+        if (["Point", "MultiPoint"].includes(String(geometry.type))) {
+            problems.push(...validateGeometry({ type: geometry.type, coordinates: geometry.coordinates }, 2_000_000).map((problem) => `${path}.${problem}`));
+            return;
+        }
+        problems.push(`${path}.type is unsupported`);
+    };
+    for (const [key, geometry] of Object.entries(topology.objects))
+        checkReferences(geometry, `objects.${key}`);
+    return problems.slice(0, 40);
+}
+function countTopoFeatures(topology) {
+    const count = (geometry) => {
+        if (!isPlainObject(geometry))
+            return 0;
+        if (geometry.type === "GeometryCollection" && Array.isArray(geometry.geometries)) {
+            return geometry.geometries.reduce((sum, child) => sum + count(child), 0);
+        }
+        return 1;
+    };
+    return Object.values(topology.objects).reduce((sum, object) => sum + count(object), 0);
+}
+export async function sha256Hex(bytes) {
+    if (!globalThis.crypto?.subtle)
+        throw new GeographyError("invalid_resource", "Web Crypto SHA-256 is unavailable");
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", Uint8Array.from(bytes).buffer);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** Fetches selected public data without cookies; data resources may not redirect off-origin. */
+export async function loadGeographyResources(manifest, request, options) {
+    options.signal?.throwIfAborted();
+    const problems = validateGeographyManifest(manifest, { licensePolicy: options.licensePolicy });
+    if (problems.length)
+        throw new GeographyError("invalid_manifest", problems.slice(0, 8).join("; "));
+    const selected = selectGeographyResources(manifest, request);
+    const maxConcurrent = options.maxConcurrent ?? 4;
+    if (!Number.isSafeInteger(maxConcurrent) || maxConcurrent < 1 || maxConcurrent > 16) {
+        throw new GeographyError("invalid_manifest", "maxConcurrent must be between 1 and 16");
+    }
+    publicDataUrl("/", options.baseUrl);
+    const results = new Array(selected.length);
+    let cursor = 0;
+    const worker = async () => {
+        while (true) {
+            options.signal?.throwIfAborted();
+            const index = cursor++;
+            if (index >= selected.length)
+                return;
+            const resource = selected[index];
+            let bytes = await options.cache?.get(resource.sha256) ?? null;
+            options.signal?.throwIfAborted();
+            const fromCache = bytes !== null;
+            if (bytes)
+                bytes = bytes.slice();
+            if (!bytes) {
+                bytes = await fetchGeographyBytes(resource.href, resource.byteSize, options, `resource ${resource.id}`);
+            }
+            const data = await verifyGeographyResource(resource, bytes);
+            options.signal?.throwIfAborted();
+            if (!fromCache)
+                await options.cache?.put(resource.sha256, bytes.slice());
+            results[index] = { resource, data, bytes };
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(maxConcurrent, selected.length) }, () => worker()));
+    return results;
+}
+/** Build an opaque, versioned geometry reference suitable for Solon's `areas.geometry_ref`. */
+export function makeGeometryRef(input) {
+    const parts = [input.sourceId, input.datasetVersion, input.resourceId, String(input.featureId)];
+    if (parts.some((part) => !part || part.length > 256)) {
+        throw new GeographyError("invalid_resource", "geometry reference components must be non-empty and at most 256 characters");
+    }
+    return `geo:v1:${parts.map(encodeURIComponent).join(":")}`;
+}

package/dist/spatial.d.ts

@@ -0,0 +1,4 @@
+import type { GeographyBounds } from "./types.ts";
+export declare function isWgs84Bounds(value: unknown): value is GeographyBounds;
+/** Inclusive intersections: touching edges and either spelling of the date line overlap. */
+export declare function intersectsGeographyBounds(a: GeographyBounds, b: GeographyBounds): boolean;

package/dist/spatial.js

@@ -0,0 +1,21 @@
+export function isWgs84Bounds(value) {
+    if (!Array.isArray(value) || value.length !== 4 || !value.every(Number.isFinite))
+        return false;
+    const [west, south, east, north] = value;
+    return west >= -180 && west <= 180 && east >= -180 && east <= 180 &&
+        south >= -90 && north <= 90 && south <= north;
+}
+/** Inclusive intersections: touching edges and either spelling of the date line overlap. */
+export function intersectsGeographyBounds(a, b) {
+    if (a[1] > b[3] || b[1] > a[3])
+        return false;
+    const longitudeIntervals = ([west, , east]) => {
+        const intervals = west <= east ? [[west, east]] : [[west, 180], [-180, east]];
+        if (west === -180)
+            intervals.push([180, 180]);
+        if (east === 180)
+            intervals.push([-180, -180]);
+        return intervals;
+    };
+    return longitudeIntervals(a).some(([west, east]) => longitudeIntervals(b).some(([otherWest, otherEast]) => west <= otherEast && otherWest <= east));
+}

package/dist/types.d.ts

@@ -0,0 +1,216 @@
+/**
+ * @bitbaum/geo-kit
+ *
+ * Country-neutral wire contracts and client-side validation for public
+ * geography services. It does not own geography records, source policy,
+ * account data, or political conclusions. Solon owns public facts and their
+ * provenance; consumers ask for only the layers, dates, and viewpoints they
+ * need.
+ */
+export declare const GEOGRAPHY_MANIFEST_VERSION: 1;
+export type Position = readonly [longitude: number, latitude: number, ...extra: number[]];
+export type LinearRing = readonly Position[];
+export type BoundaryGeometry = {
+    type: "Polygon";
+    coordinates: readonly LinearRing[];
+} | {
+    type: "MultiPolygon";
+    coordinates: readonly (readonly LinearRing[])[];
+};
+export type GeoJSONGeometry = BoundaryGeometry | {
+    type: "Point";
+    coordinates: Position;
+} | {
+    type: "MultiPoint";
+    coordinates: readonly Position[];
+} | {
+    type: "LineString";
+    coordinates: readonly Position[];
+} | {
+    type: "MultiLineString";
+    coordinates: readonly (readonly Position[])[];
+} | {
+    type: "GeometryCollection";
+    geometries: readonly GeoJSONGeometry[];
+};
+export type ResourceFormat = "geojson" | "topojson";
+export type ISODate = string;
+/** West > east represents a box crossing the antimeridian. */
+export type GeographyBounds = readonly [west: number, south: number, east: number, north: number];
+export interface GeographySource {
+    id: string;
+    publisher: string;
+    dataset: string;
+    url: string;
+    licenseSPDX: string;
+    retrievedAt: string;
+    attribution?: string;
+}
+/** A single immutable geometry file in a manifest. */
+export interface GeographyResource {
+    id: string;
+    sourceIds: readonly string[];
+    /** An open key such as `administrative`, `economic`, `ecological`, or `custom`. */
+    kindKey: string;
+    /** Stable identifier for the geographic system or scope. */
+    geographyId: string;
+    /** Data-defined tier, such as `country`, `admin1`, or `municipality`. */
+    levelKey: string;
+    format: ResourceFormat;
+    /** Same-origin, root-relative URL. Redirects are rejected by the loader. */
+    href: string;
+    sha256: string;
+    byteSize: number;
+    featureCount: number;
+    validFrom: ISODate | null;
+    /** Exclusive upper bound. Null means no known end. */
+    validTo: ISODate | null;
+    /** Null means viewpoint-neutral source geometry. */
+    viewpointKey: string | null;
+    bbox?: GeographyBounds;
+    minZoom?: number;
+    /** Exclusive upper bound; null means no known maximum. */
+    maxZoom?: number;
+}
+export interface GeographyManifest {
+    schemaVersion: typeof GEOGRAPHY_MANIFEST_VERSION;
+    datasetVersion: string;
+    generatedAt: string;
+    sources: readonly GeographySource[];
+    viewpoints: readonly GeographyViewpoint[];
+    resources: readonly GeographyResource[];
+}
+/** A named account of the perspective represented by one or more resources. */
+export interface GeographyViewpoint {
+    key: string;
+    label: string;
+    description: string;
+    sourceIds: readonly string[];
+}
+export interface LicenseRule {
+    /** License policy is owned by the application / governing organization. */
+    spdx: string;
+    requiresAttribution: boolean;
+}
+export interface ManifestValidationOptions {
+    licensePolicy?: readonly LicenseRule[];
+    maxResources?: number;
+    maxByteSize?: number;
+}
+export interface ResourceSelection {
+    /** At least one of these selectors is required to prevent accidental full loads. */
+    geographyIds?: readonly string[];
+    resourceIds?: readonly string[];
+    kindKeys?: readonly string[];
+    levelKeys?: readonly string[];
+    /** Required: callers choose the time explicitly; the library never reads the clock. */
+    asOf: ISODate;
+    /** Default selects only neutral geometry; an explicit key adds that viewpoint. `all` is opt-in. */
+    viewpointKey?: string | "all";
+    zoom?: number;
+    /** Only intersecting resources; resources without bounds remain eligible. */
+    bbox?: GeographyBounds;
+    maxBytes?: number;
+    maxResources?: number;
+}
+export type GeometryResourceData = GeoJSONFeatureCollection | Topology;
+export interface GeoJSONFeature {
+    type: "Feature";
+    id?: string | number;
+    geometry: GeoJSONGeometry | null;
+    properties: Record<string, unknown> | null;
+    [key: string]: unknown;
+}
+export interface GeoJSONFeatureCollection {
+    type: "FeatureCollection";
+    features: GeoJSONFeature[];
+    [key: string]: unknown;
+}
+export interface Topology {
+    type: "Topology";
+    arcs: number[][][];
+    objects: Record<string, unknown>;
+    transform?: {
+        scale: [number, number];
+        translate: [number, number];
+    };
+    [key: string]: unknown;
+}
+export interface LoadedResource {
+    resource: GeographyResource;
+    data: GeometryResourceData;
+    bytes: Uint8Array;
+}
+export interface ResourceCache {
+    get(sha256: string): Promise<Uint8Array | null>;
+    put(sha256: string, bytes: Uint8Array): Promise<void>;
+}
+export interface LoadResourcesOptions {
+    baseUrl: string;
+    signal?: AbortSignal;
+    maxConcurrent?: number;
+    cache?: ResourceCache;
+    licensePolicy?: readonly LicenseRule[];
+    fetcher?: typeof fetch;
+}
+export interface LoadManifestOptions extends ManifestValidationOptions {
+    baseUrl: string;
+    signal?: AbortSignal;
+    fetcher?: typeof fetch;
+    /** Limit on decoded manifest bytes, enforced while streaming. Default: 64 KiB. */
+    maxBytes?: number;
+}
+export type AreaAssertionKind = "claims" | "administers" | "proposes";
+/** Mirrors Solon's public `area_assertions` contract; it reports claims, not truth. */
+export interface AreaAssertion {
+    areaId: string;
+    jurisdictionId: string;
+    assertion: AreaAssertionKind;
+    assertedById: string | null;
+    sourceId: string;
+    validFrom: ISODate | null;
+    validTo: ISODate | null;
+}
+export interface AreaPoliticalSummary {
+    claimants: readonly string[];
+    administrators: readonly string[];
+    proposers: readonly string[];
+    disputed: boolean;
+    unclaimed: boolean;
+}
+export interface BoundaryDraft {
+    /** Client-generated draft id; this is not a published geography id. */
+    id: string;
+    proposalId: string;
+    title: string;
+    geographyId: string;
+    kindKey: string;
+    geometry: BoundaryGeometry;
+    validFrom: ISODate | null;
+    validTo: ISODate | null;
+    source: {
+        publisher: string;
+        dataset: string;
+        licenseSPDX: string;
+        attribution?: string;
+        url?: string;
+    };
+}
+export interface BoundaryDraftValidationOptions {
+    licensePolicy: readonly LicenseRule[];
+    /** Full topology checks belong to a robust geometry engine supplied by the app. */
+    validateTopology?: (geometry: BoundaryGeometry) => {
+        valid: boolean;
+        problems?: readonly string[];
+    };
+    /** Must resolve to an approved proposal under the app's own governance workflow. */
+    proposalApproved?: (proposalId: string) => boolean;
+    maxVertices?: number;
+    maxBytes?: number;
+}
+export interface BoundaryDraftValidation {
+    problems: string[];
+    publishable: boolean;
+    vertexCount: number;
+    byteSize: number;
+}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * @bitbaum/geo-kit
+ *
+ * Country-neutral wire contracts and client-side validation for public
+ * geography services. It does not own geography records, source policy,
+ * account data, or political conclusions. Solon owns public facts and their
+ * provenance; consumers ask for only the layers, dates, and viewpoints they
+ * need.
+ */
+export const GEOGRAPHY_MANIFEST_VERSION = 1;

package/dist/validation.d.ts

@@ -0,0 +1,17 @@
+import type { ISODate, Position, ManifestValidationOptions } from "./types.ts";
+export declare function isStableKey(value: unknown): value is string;
+export declare function isISODate(value: unknown): value is ISODate;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export declare function validPeriod(from: unknown, to: unknown): boolean;
+export declare function validUrl(value: unknown, protocols: readonly string[]): value is string;
+export declare function safeResourceHref(value: unknown): value is string;
+/** Validate a manifest without fetching anything. Licenses and their legal policy are supplied by the owner. */
+export declare function validateGeographyManifest(value: unknown, options?: ManifestValidationOptions): string[];
+export declare function periodContains(from: ISODate | null, to: ISODate | null, date: ISODate): boolean;
+/** Resolve current/historical claims as recorded. No default viewpoint or legal status is inferred. */
+/** Prevent malformed API records or unsourced claims from silently changing a map's dispute styling. */
+export declare function validateAreaAssertions(value: unknown): string[];
+/** Validate a GeoJSON geometry's coordinates and structural rules. */
+export declare function validateGeometry(value: unknown, maxPositions?: number): string[];
+/** True when a coordinate tuple is a finite WGS84 position (lon, lat, optional altitude). */
+export declare function isWgs84Position(value: unknown): value is Position;