astrospatial-services 0.0.0-stage → 0.1.0

package/lib-esm/astronomy/tap/TapService.js

@@ -0,0 +1,198 @@
+import { FetchHttpTransport, } from "../../core/HttpTransport.js";
+import { ServiceError } from "../../core/ServiceError.js";
+function tapBaseUrl(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new TypeError("Invalid TAP endpoint URL");
+    }
+    if (!["http:", "https:"].includes(url.protocol) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash) {
+        throw new TypeError("TAP endpoint must be an HTTP(S) URL without credentials, query or fragment");
+    }
+    url.pathname = url.pathname.replace(/\/+$/, "");
+    if (url.pathname.endsWith("/sync"))
+        url.pathname = url.pathname.slice(0, -5);
+    if (url.pathname.endsWith("/capabilities"))
+        url.pathname = url.pathname.slice(0, -13);
+    return url.toString().replace(/\/$/, "");
+}
+/** Parse RFC-style CSV with quoted commas, escaped quotes and embedded newlines. */
+export function parseTapCsvTable(csv) {
+    // Ignore an optional UTF-8 BOM at the beginning of the CSV.
+    if (csv.startsWith('\uFEFF')) {
+        csv = csv.slice(1);
+    }
+    const rows = [];
+    let row = [], field = "", quoted = false, afterQuote = false;
+    for (let i = 0; i < csv.length; i++) {
+        const c = csv[i];
+        if (quoted) {
+            if (c === '"' && csv[i + 1] === '"') {
+                field += '"';
+                i++;
+            }
+            else if (c === '"') {
+                quoted = false;
+                afterQuote = true;
+            }
+            else
+                field += c;
+        }
+        else if (afterQuote) {
+            if (c === ",") {
+                row.push(field);
+                field = "";
+                afterQuote = false;
+            }
+            else if (c === "\n" || c === "\r") {
+                row.push(field);
+                rows.push(row);
+                row = [];
+                field = "";
+                afterQuote = false;
+                if (c === "\r" && csv[i + 1] === "\n")
+                    i++;
+            }
+            else
+                throw new ServiceError("INVALID_RESPONSE", "Malformed TAP CSV quoting");
+        }
+        else if (c === '"') {
+            if (field)
+                throw new ServiceError("INVALID_RESPONSE", "Malformed TAP CSV quoting");
+            quoted = true;
+        }
+        else if (c === ",") {
+            row.push(field);
+            field = "";
+        }
+        else if (c === "\n" || c === "\r") {
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = "";
+            if (c === "\r" && csv[i + 1] === "\n")
+                i++;
+        }
+        else
+            field += c;
+    }
+    if (quoted)
+        throw new ServiceError("INVALID_RESPONSE", "Unterminated TAP CSV field");
+    if (afterQuote || field || row.length) {
+        row.push(field);
+        rows.push(row);
+    }
+    if (!rows.length || !rows[0].length || rows[0].some((h) => !h)) {
+        throw new ServiceError("INVALID_RESPONSE", "Missing TAP CSV header");
+    }
+    const [headers, ...data] = rows;
+    const columns = headers.map((h) => h.replace(/^\uFEFF/, ""));
+    return {
+        columns,
+        rows: data.map((values) => {
+            if (values.length !== headers.length) {
+                throw new ServiceError("INVALID_RESPONSE", "TAP CSV column count mismatch");
+            }
+            return Object.fromEntries(columns.map((name, i) => [name, values[i]]));
+        }),
+    };
+}
+/**
+ * Parse TAP CSV and return data rows.
+ * Preserves the existing public API.
+ */
+export function parseTapCsv(csv) {
+    return parseTapCsvTable(csv).rows;
+}
+function sqlLiteral(value) {
+    if (!value.trim())
+        throw new TypeError("TAP metadata filter must not be blank");
+    return "'" + value.replace(/'/g, "''") + "'";
+}
+/** TAP 1.x synchronous ADQL client. No rendering or backend dependency. */
+export class TapService {
+    baseUrl;
+    url;
+    transport;
+    timeoutMs;
+    constructor(options) {
+        this.baseUrl = tapBaseUrl(options.endpoint);
+        this.url = this.baseUrl + "/sync";
+        this.transport = options.transport ?? new FetchHttpTransport();
+        this.timeoutMs = options.timeoutMs ?? 30000;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0) {
+            throw new RangeError("timeoutMs must be a positive finite number");
+        }
+    }
+    /** Raw VOSI capabilities XML; parsing is intentionally left to the caller. */
+    async getCapabilities(options = {}) {
+        return this.transport.getText(this.baseUrl + "/capabilities", {
+            signal: options.signal,
+            timeoutMs: this.timeoutMs,
+        });
+    }
+    async metadataRows(adql, signal) {
+        const response = await this.querySync({ adql, format: "csv", signal });
+        if (response.contentType &&
+            !/\b(csv|text\/plain)\b/i.test(response.contentType)) {
+            throw new ServiceError("INVALID_RESPONSE", "TAP metadata query did not return CSV");
+        }
+        return parseTapCsv(response.body);
+    }
+    async listSchemas(options = {}) {
+        return this.metadataRows("SELECT schema_name, description, utype FROM TAP_SCHEMA.schemas", options.signal);
+    }
+    async listTables(options = {}) {
+        const where = options.schemaName === undefined
+            ? ""
+            : " WHERE schema_name = " + sqlLiteral(options.schemaName);
+        return this.metadataRows("SELECT schema_name, table_name, table_type, description, utype FROM TAP_SCHEMA.tables" +
+            where, options.signal);
+    }
+    async listColumns(tableName, options = {}) {
+        return this.metadataRows("SELECT table_name, column_name, description, unit, ucd, utype, datatype, arraysize, xtype, principal, indexed, std FROM TAP_SCHEMA.columns WHERE table_name = " +
+            sqlLiteral(tableName), options.signal);
+    }
+    async querySync(query) {
+        if (typeof query.adql !== "string" || !query.adql.trim()) {
+            throw new TypeError("ADQL query must not be blank");
+        }
+        if (query.maxrec !== undefined &&
+            (!Number.isSafeInteger(query.maxrec) || query.maxrec < 0)) {
+            throw new RangeError("maxrec must be a non-negative safe integer");
+        }
+        const form = new URLSearchParams({
+            REQUEST: "doQuery",
+            LANG: "ADQL",
+            QUERY: query.adql,
+            FORMAT: query.format ?? "votable",
+        });
+        if (query.maxrec !== undefined)
+            form.set("MAXREC", String(query.maxrec));
+        if (!this.transport.request) {
+            throw new ServiceError("INVALID_RESPONSE", "TAP requires an HTTP transport supporting POST requests");
+        }
+        const response = await this.transport.request(this.url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
+                Accept: "*/*",
+            },
+            body: form.toString(),
+            signal: query.signal,
+            timeoutMs: this.timeoutMs,
+        });
+        return {
+            body: response.body,
+            status: response.status,
+            headers: response.headers,
+            contentType: response.headers.get("content-type"),
+        };
+    }
+}

package/lib-esm/astronomy/tap/VOTableParser.d.ts

@@ -0,0 +1,13 @@
+import type { MetadataColumn } from "astrospatial-core/metadata";
+import type { TapColumn } from "./TapService.js";
+export interface VOTableResult {
+    columns: MetadataColumn[];
+    rows: string[][];
+}
+export interface VOTableOptions {
+    /** Output column name -> original TAP_SCHEMA column name. */
+    aliases?: Readonly<Record<string, string>>;
+    sourceColumns?: readonly TapColumn[];
+}
+/** Parse one XML/TABLEDATA VOTable table; no BINARY, BINARY2 or FITS support yet. */
+export declare function parseVOTable(xml: string, options?: VOTableOptions): VOTableResult;

package/lib-esm/astronomy/tap/VOTableParser.js

@@ -0,0 +1,85 @@
+import { DOMParser } from "@xmldom/xmldom";
+import { ServiceError } from "../../core/ServiceError.js";
+import { tapColumnsToMetadata } from "./TapMetadataAdapter.js";
+function children(element, name) {
+    return Array.from(element.childNodes)
+        .filter((node) => node.nodeType === 1)
+        .filter((node) => node.localName === name || node.nodeName === name);
+}
+function descendants(element, name) {
+    const found = [];
+    for (const child of Array.from(element.childNodes)) {
+        if (child.nodeType !== 1)
+            continue;
+        const el = child;
+        if (el.localName === name || el.nodeName === name)
+            found.push(el);
+        found.push(...descendants(el, name));
+    }
+    return found;
+}
+/** Parse one XML/TABLEDATA VOTable table; no BINARY, BINARY2 or FITS support yet. */
+export function parseVOTable(xml, options = {}) {
+    const errors = [];
+    let document;
+    try {
+        document = new DOMParser({
+            errorHandler: (level, message) => {
+                if (level !== "warning")
+                    errors.push(message);
+            },
+        }).parseFromString(xml, "application/xml");
+    }
+    catch (cause) {
+        throw new ServiceError("INVALID_RESPONSE", "Malformed VOTable XML", undefined, { cause });
+    }
+    if (errors.length || !document?.documentElement || document.documentElement.localName !== "VOTABLE") {
+        throw new ServiceError("INVALID_RESPONSE", "Malformed VOTable XML");
+    }
+    const tables = descendants(document.documentElement, "TABLE");
+    if (tables.length !== 1) {
+        throw new ServiceError("INVALID_RESPONSE", "Expected exactly one VOTable TABLE");
+    }
+    const table = tables[0];
+    const data = children(table, "DATA");
+    if (data.length !== 1)
+        throw new ServiceError("INVALID_RESPONSE", "Missing VOTable DATA");
+    const unsupported = ["BINARY", "BINARY2", "FITS"].find((name) => children(data[0], name).length > 0);
+    if (unsupported)
+        throw new ServiceError("NOT_IMPLEMENTED", `VOTable ${unsupported} serialization is not implemented yet`);
+    const tableData = children(data[0], "TABLEDATA");
+    if (tableData.length !== 1)
+        throw new ServiceError("INVALID_RESPONSE", "Missing VOTable TABLEDATA");
+    const fields = children(table, "FIELD");
+    if (!fields.length)
+        throw new ServiceError("INVALID_RESPONSE", "Missing VOTable FIELD");
+    const names = fields.map((field, i) => field.getAttribute("name") || field.getAttribute("ID") || `column_${i}`);
+    const source = new Map((options.sourceColumns ?? []).map((col) => [col.column_name, col]));
+    const columns = fields.map((field, i) => {
+        const name = names[i];
+        const original = source.get(options.aliases?.[name] ?? name);
+        const description = children(field, "DESCRIPTION")[0]?.textContent?.trim() || "";
+        const attr = (key) => field.getAttribute(key) || "";
+        return {
+            table_name: original?.table_name ?? "",
+            column_name: name,
+            description: description || original?.description || "",
+            unit: attr("unit") || original?.unit || "",
+            ucd: attr("ucd") || original?.ucd || "",
+            utype: attr("utype") || original?.utype || "",
+            datatype: attr("datatype") || original?.datatype || "",
+            arraysize: attr("arraysize") || original?.arraysize || "",
+            xtype: attr("xtype") || original?.xtype || "",
+            principal: original?.principal ?? "",
+            indexed: original?.indexed ?? "",
+            std: original?.std ?? "",
+        };
+    });
+    const rows = children(tableData[0], "TR").map((tr) => {
+        const values = children(tr, "TD").map((td) => td.textContent ?? "");
+        if (values.length !== fields.length)
+            throw new ServiceError("INVALID_RESPONSE", "VOTable row column count mismatch");
+        return values;
+    });
+    return { columns: tapColumnsToMetadata(columns), rows };
+}

package/lib-esm/astronomy/tap/index.d.ts

@@ -0,0 +1,9 @@
+export { TapService } from './TapService.js';
+export type { TapServiceOptions, TapSyncQuery, TapQueryResponse, TapOutputFormat } from './TapService.js';
+export { parseTapCsv } from './TapService.js';
+export type { TapSchema, TapTable, TapColumn } from './TapService.js';
+export { tapColumnsToMetadata } from './TapMetadataAdapter.js';
+export { parseTapCsvTable } from './TapService.js';
+export type { TapCsvTable } from './TapService.js';
+export { parseVOTable } from './VOTableParser.js';
+export type { VOTableResult, VOTableOptions } from './VOTableParser.js';

package/lib-esm/astronomy/tap/index.js

@@ -0,0 +1,5 @@
+export { TapService } from './TapService.js';
+export { parseTapCsv } from './TapService.js';
+export { tapColumnsToMetadata } from './TapMetadataAdapter.js';
+export { parseTapCsvTable } from './TapService.js';
+export { parseVOTable } from './VOTableParser.js';

package/lib-esm/core/HttpTransport.d.ts

@@ -0,0 +1,28 @@
+export interface HttpRequestOptions {
+    method?: "GET" | "POST";
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface HttpResponse {
+    status: number;
+    headers: Headers;
+    body: string;
+}
+export interface HttpTransport {
+    getText(url: string, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<string>;
+    request?(url: string, options?: HttpRequestOptions): Promise<HttpResponse>;
+}
+export declare class FetchHttpTransport implements HttpTransport {
+    private readonly fetchImpl;
+    constructor(fetchImpl?: typeof fetch);
+    getText(url: string, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<string>;
+    request(url: string, options?: HttpRequestOptions): Promise<HttpResponse>;
+}

package/lib-esm/core/HttpTransport.js

@@ -0,0 +1,57 @@
+import { ServiceError } from "./ServiceError.js";
+export class FetchHttpTransport {
+    fetchImpl;
+    constructor(fetchImpl = fetch) {
+        this.fetchImpl = fetchImpl;
+    }
+    async getText(url, options = {}) {
+        const response = await this.request(url, { ...options, method: "GET" });
+        return response.body;
+    }
+    async request(url, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 10000;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            throw new RangeError("timeoutMs must be a positive finite number");
+        }
+        const method = options.method ?? "GET";
+        if (method === "GET" && options.body !== undefined) {
+            throw new TypeError("GET requests cannot have a body");
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort("timeout"), timeoutMs);
+        const onAbort = () => controller.abort("caller");
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        if (options.signal?.aborted)
+            controller.abort("caller");
+        try {
+            const response = await this.fetchImpl(url, {
+                method,
+                headers: options.headers,
+                body: options.body,
+                signal: controller.signal,
+            });
+            if (!response.ok)
+                throw new ServiceError("HTTP", `HTTP ${response.status} for ${url}`, response.status);
+            return {
+                status: response.status,
+                headers: response.headers,
+                body: await response.text(),
+            };
+        }
+        catch (error) {
+            if (error instanceof ServiceError)
+                throw error;
+            if (controller.signal.aborted) {
+                const callerAborted = options.signal?.aborted || controller.signal.reason === "caller";
+                throw new ServiceError(callerAborted ? "ABORTED" : "TIMEOUT", callerAborted
+                    ? "Request aborted"
+                    : `Request timed out after ${timeoutMs}ms`, undefined, { cause: error });
+            }
+            throw new ServiceError("NETWORK", `Network error while requesting ${url}`, undefined, { cause: error });
+        }
+        finally {
+            clearTimeout(timeout);
+            options.signal?.removeEventListener("abort", onAbort);
+        }
+    }
+}

package/lib-esm/core/ServiceError.d.ts

@@ -0,0 +1,6 @@
+export type ServiceErrorCode = 'NETWORK' | 'HTTP' | 'TIMEOUT' | 'ABORTED' | 'INVALID_RESPONSE' | 'NOT_FOUND' | 'NOT_IMPLEMENTED';
+export declare class ServiceError extends Error {
+    readonly code: ServiceErrorCode;
+    readonly status?: number | undefined;
+    constructor(code: ServiceErrorCode, message: string, status?: number | undefined, options?: ErrorOptions);
+}

package/lib-esm/core/ServiceError.js

@@ -0,0 +1,10 @@
+export class ServiceError extends Error {
+    code;
+    status;
+    constructor(code, message, status, options) {
+        super(message, options);
+        this.code = code;
+        this.status = status;
+        this.name = 'ServiceError';
+    }
+}

package/lib-esm/index.d.ts

@@ -0,0 +1,7 @@
+export { FetchHttpTransport } from './core/HttpTransport.js';
+export type { HttpTransport, HttpRequestOptions, HttpResponse } from './core/HttpTransport.js';
+export { ServiceError } from './core/ServiceError.js';
+export type { ServiceErrorCode } from './core/ServiceError.js';
+export * from './astronomy/name-resolver/index.js';
+export * from './astronomy/hips/index.js';
+export * from './astronomy/tap/index.js';

package/lib-esm/index.js

@@ -0,0 +1,5 @@
+export { FetchHttpTransport } from './core/HttpTransport.js';
+export { ServiceError } from './core/ServiceError.js';
+export * from './astronomy/name-resolver/index.js';
+export * from './astronomy/hips/index.js';
+export * from './astronomy/tap/index.js';

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "astrospatial-services",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Render-independent scientific service clients for astronomy, Earth observation and planetary data.",
+  "type": "module",
+  "main": "./lib-esm/index.js",
+  "types": "./lib-esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib-esm/index.d.ts",
+      "import": "./lib-esm/index.js"
+    },
+    "./astronomy/name-resolver": {
+      "types": "./lib-esm/astronomy/name-resolver/index.d.ts",
+      "import": "./lib-esm/astronomy/name-resolver/index.js"
+    },
+    "./package.json": "./package.json",
+    "./astronomy/hips": {
+      "types": "./lib-esm/astronomy/hips/index.d.ts",
+      "import": "./lib-esm/astronomy/hips/index.js"
+    },
+    "./astronomy/tap": {
+      "types": "./lib-esm/astronomy/tap/index.d.ts",
+      "import": "./lib-esm/astronomy/tap/index.js"
+    }
+  },
+  "files": [
+    "lib-esm/",
+    "README.md",
+    "LICENSE.md",
+    "LICENSE-COMMERCIAL.md",
+    "LICENSE-AGPL.md",
+    "DEPENDENCY-LICENSING.md",
+    "package.json"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "clean": "rm -rf lib-esm",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "test:live": "npm run build && node --test test/*.live.test.mjs"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": "Fabrizio Giordano (fab77)",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fab77/astrospatial-services.git"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "astrospatial-core": "0.4.2",
+    "@xmldom/xmldom": "^0.9.8"
+  }
+}