@kayahr/edsm 1.1.0

package/src/main/codex.ts

@@ -0,0 +1,31 @@
+/*
+ * Copyright (C) 2020 Klaus Reimer <k@ailis.de>
+ * See LICENSE.md for licensing information.
+ */
+
+import type { Id64 } from "./common.ts";
+import { parseJSONArray } from "./util.ts";
+
+/** Single EDSM codex. */
+export interface Codex {
+    systemId: number;
+    systemId64: Id64;
+    systemName: string;
+    region: string;
+    type: string | null;
+    name: string | number;
+    reportedOn: string;
+}
+
+/** List of EDSM codices. */
+export type Codices = Codex[];
+
+/**
+ * Parses codices from the given JSON stream.
+ *
+ * @param stream - The JSON input stream.
+ * @returns Stream of codices.
+ */
+export function parseCodexJSON(stream: AsyncIterable<Uint8Array>): AsyncIterable<Codex> {
+    return parseJSONArray(stream);
+}

package/src/main/common.ts

@@ -0,0 +1,29 @@
+/*
+ * Copyright (C) 2020 Klaus Reimer <k@ailis.de>
+ * See LICENSE.md for licensing information.
+ */
+
+export interface Coordinates {
+    x: number;
+    y: number;
+    z: number;
+}
+
+/** A 64 bit ID. Can be a `number` if ID does not need more then 53 bit. Must be `bigint` if ID needs more than 53 bit. */
+export type Id64 = number | bigint;
+
+/**
+ * Converts the given date to a UTC date string as expected by the EDSM REST API.
+ *
+ * @param date - The date to convert.
+ * @returns The date as an EDSM-compatible UTC date string.
+ */
+export function toUTCString(date: Date): string {
+    const year = date.getUTCFullYear().toString().padStart(4, "0");
+    const month = (date.getUTCMonth() + 1).toString().padStart(2, "0");
+    const day = date.getUTCDate().toString().padStart(2, "0");
+    const hour = date.getUTCHours().toString().padStart(2, "0");
+    const minute = date.getUTCMinutes().toString().padStart(2, "0");
+    const second = date.getUTCSeconds().toString().padStart(2, "0");
+    return `${year}-${month}-${day} ${hour}:${minute}:${second}`;
+}

package/src/main/index.ts

@@ -0,0 +1,42 @@
+/*
+ * Copyright (C) 2020 Klaus Reimer <k@ailis.de>
+ * See LICENSE.md for licensing information.
+ */
+
+export {
+    type CommanderCreditsResponse, type CommanderInventoryResponse, type CommanderRanksResponse, type CreditsPeriod, getCommanderCredits, getCommanderInventory,
+    getCommanderRanks, type InventoryType
+} from "./api/commander.ts";
+export { APIException, ServerException, type SystemIdRequestOptions } from "./api/common.ts";
+export { type EDSMEvent, type EventResponse, getDiscardEvents, sendEvents } from "./api/journal.ts";
+export {
+type CommanderPositionOptions, type CommanderPositionResponse, type FlightLog, type FlightLogFilter, type FlightLogsResponse, getCommanderPosition,
+    getFlightLogs, getSystemComment, getSystemComments, setSystemComment, type SystemCommentResponse, type SystemCommentsOptions,
+    type SystemCommentsResponse
+} from "./api/logs.ts";
+export { type EliteServerStatusResponse, type EliteServerStatusType, getEliteServerStatus } from "./api/status.ts";
+export {
+    type BodyScanValue, getStationMarket, getStationOutfitting, getStationShipyard, getSystemBodies, getSystemDeaths, getSystemEstimatedValue,
+    getSystemFactions, getSystemStations, getSystemTraffic, type ShortSystemFaction, type StationMarketResponse, type StationOutfittingResponse,
+    type StationShipyardResponse, type SystemBodiesResponse, type SystemDeathsResponse, type SystemEstimatedValueResponse, type SystemFaction,
+    type SystemFactionsOptions, type SystemFactionsResponse, type SystemStationsResponse, type SystemTrafficResponse
+} from "./api/system.ts";
+export {
+    type CubeSystemsRequestOptions, getCubeSystems, getSphereSystems, getSystem, getSystems, type SphereSystemsRequestOptions, type SystemRequestFlags,
+    type SystemRequestOptions, type SystemResponse, type SystemsRequestOptions
+} from "./api/systems.ts";
+export {
+    type Asteroids, type AtmosphereComposition, type Bodies, type Body, isPlanet, isStar, type Materials, parseBodiesJSON, type Planet, type SolidComposition,
+    type Star, type SystemBody, type SystemPlanet, type SystemStar
+} from "./bodies.ts";
+export { type Codex, type Codices, parseCodexJSON } from "./codex.ts";
+export { type Coordinates, type Id64, toUTCString } from "./common.ts";
+export { parsePowerPlayJSON, type PowerPlay, type PowerPlays } from "./powerplay.ts";
+export {
+    type Commodity, type Outfitting, parseStationsJSON, type Ship, type Station, type StationBody, type StationControllingFaction, type Stations,
+    type StationUpdateTime, type SystemStation
+} from "./stations.ts";
+export {
+    type ControllingFaction, type EstimatedCoordinates, type Faction, parseSystemsJSON, type State, type System, type Systems, type TrendState
+} from "./systems.ts";
+export { IllegalStateException, NotFoundException } from "./util.ts";

package/src/main/powerplay.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright (C) 2020 Klaus Reimer <k@ailis.de>
+ * See LICENSE.md for licensing information.
+ */
+
+import type { Coordinates, Id64 } from "./common.ts";
+import { parseJSONArray } from "./util.ts";
+
+/** Single EDSM power play information. */
+export interface PowerPlay {
+    power: string;
+    powerState: string;
+    id: number;
+    id64: Id64;
+    name: string;
+    coords: Coordinates;
+    allegiance: string | null;
+    government: string | null;
+    state: string | null;
+    date: string;
+}
+
+/** List of EDSM power play information. */
+export type PowerPlays = PowerPlay[];
+
+/**
+ * Parses power play information from the given JSON stream.
+ *
+ * @param stream - The JSON input stream.
+ * @returns Stream of power play information.
+ */
+export function parsePowerPlayJSON(stream: AsyncIterable<Uint8Array>): AsyncIterable<PowerPlay> {
+    return parseJSONArray(stream);
+}

package/src/main/stations.ts

@@ -0,0 +1,87 @@
+/*
+ * Copyright (C) 2020 Klaus Reimer <k@ailis.de>
+ * See LICENSE.md for licensing information.
+ */
+
+import type { Id64 } from "./common.ts";
+import { parseJSONArray } from "./util.ts";
+
+export interface StationControllingFaction {
+    id: number | null;
+    name: string | null;
+}
+
+export interface StationBody {
+    id: number;
+    name: string;
+    latitude?: number;
+    longitude?: number;
+}
+
+export interface StationUpdateTime {
+    information: string;
+    market: string | null;
+    shipyard: string | null;
+    outfitting: string | null;
+}
+
+export interface Outfitting {
+    id: string | null;
+    name: string;
+}
+
+export interface Commodity {
+    id: string | null;
+    name: string;
+    buyPrice: number;
+    stock: number;
+    sellPrice: number;
+    demand: number;
+    stockBracket: number;
+}
+
+export interface Ship {
+    id: number;
+    name: string;
+}
+
+export interface Station {
+    id: number;
+    marketId: number | null;
+    type: string | null;
+    name: string;
+    body?: StationBody;
+    distanceToArrival: number | null;
+    allegiance: string | null;
+    government: string | null;
+    economy: string | null;
+    secondEconomy: string | null;
+    haveMarket: boolean;
+    haveShipyard: boolean;
+    haveOutfitting: boolean;
+    otherServices: string[];
+    controllingFaction?: StationControllingFaction;
+    updateTime: StationUpdateTime;
+    systemId?: number;
+    systemId64?: Id64 | null;
+    systemName?: string;
+    commodities: Commodity[] | null;
+    ships: Ship[] | null;
+    outfitting: Outfitting[] | null;
+}
+
+/** Station data in system objects with less details. */
+export type SystemStation = Omit<Station, "systemId" | "systemId64" | "systemName" | "outfitting" | "ships" | "commodities">;
+
+/** List of EDSM stations. */
+export type Stations = Station[];
+
+/**
+ * Parses stations from the given JSON stream.
+ *
+ * @param stream - The JSON input stream.
+ * @returns Stream of stations.
+ */
+export function parseStationsJSON(stream: AsyncIterable<Uint8Array>): AsyncIterable<Station> {
+    return parseJSONArray(stream);
+}

package/src/main/systems.ts

@@ -0,0 +1,77 @@
+/*
+ * Copyright (C) 2020 Klaus Reimer <k@ailis.de>
+ * See LICENSE.md for licensing information.
+ */
+
+import type { SystemBody } from "./bodies.ts";
+import type { Coordinates, Id64 } from "./common.ts";
+import type { SystemStation } from "./stations.ts";
+import { parseJSONArray } from "./util.ts";
+
+export interface EstimatedCoordinates extends Coordinates {
+    precision: number;
+}
+
+export interface ControllingFaction {
+    id: number;
+    name: string | null;
+    allegiance?: string;
+    government?: string;
+    isPlayer: boolean;
+}
+
+export interface State {
+    state: string;
+}
+
+export interface TrendState extends State {
+    trend: number;
+}
+
+export interface Faction {
+    id: number;
+    name: string;
+    allegiance?: string | null;
+    government?: string | null;
+    influence: number;
+    state: string | null;
+    activeStates: State[];
+    recoveringStates: TrendState[];
+    pendingStates: TrendState[];
+    happiness: string;
+    isPlayer: boolean;
+    lastUpdate: number;
+}
+
+/** A single EDSM system. */
+export interface System {
+    name: string;
+    id: number;
+    id64: Id64 | null;
+    date: string;
+    coords?: Coordinates;
+    estimatedCoordinates?: EstimatedCoordinates;
+    allegiance?: string | null;
+    government?: string | null;
+    state?: string | null;
+    economy?: string | null;
+    security?: string;
+    population?: number | null;
+    controllingFaction?: ControllingFaction;
+    factions?: Faction[];
+    stations?: SystemStation[];
+    bodies?: SystemBody[];
+}
+
+/** List of EDSM systems. */
+export type Systems = System[];
+
+/**
+ * Parses systems from the given JSON stream.
+ *
+ * @param stream - The JSON input stream.
+ * @returns Stream of systems.
+ */
+export function parseSystemsJSON(stream: AsyncIterable<Uint8Array>): AsyncIterable<System> {
+    return parseJSONArray(stream);
+}

package/src/main/util.ts

@@ -0,0 +1,103 @@
+/*
+ * Copyright (C) 2020 Klaus Reimer <k@ailis.de>
+ * See LICENSE.md for licensing information.
+ */
+
+/**
+ * Base class for all exceptions. Automatically corrects its prototype and name.
+ */
+export abstract class EDSMException extends Error {
+    /**
+     * Creates a new exception.
+     *
+     * @param message - The exception message.
+     * @param options - Optional error options.
+     */
+    public constructor(message: string, options?: ErrorOptions) {
+        super(message, options);
+        this.name = this.constructor.name;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+
+/** Thrown when state is illegal. */
+export class IllegalStateException extends EDSMException {}
+
+/** Thrown when some resource was not found. */
+export class NotFoundException extends EDSMException {}
+
+/**
+ * Helper function to iterate over the lines of a data stream.
+ *
+ * @param stream - The input stream.
+ * @yields The created iterable for iterating over the lines of the stream.
+ */
+async function *parseLines(stream: AsyncIterable<Uint8Array>): AsyncIterable<string> {
+    let line = "";
+    const decoder = new TextDecoder();
+    for await (const chunk of stream) {
+        const data = decoder.decode(chunk);
+        const parts = data.split("\n");
+        const numParts = parts.length;
+        for (let i = 0; i < numParts; i++) {
+            line += parts[i];
+            if (i <  numParts - 1) {
+                yield line;
+                line = "";
+            }
+        }
+    }
+    if (line !== "") {
+        yield line;
+    }
+}
+
+/**
+ * Helper function to iterate over the array entries of the given stream. The stream must be a JSON file with an array
+ * bracket in the first and last line and all other lines must contain a single dataset each. So it's actually a JSONL
+ * file but wrapped in an array and with comma character suffixes.
+ *
+ * @param stream    - The JSON input as an async iterable.
+ * @yields The created iterable for iterating over the array entries of the JSON stream.
+ */
+export async function *parseJSONArray<T>(stream: AsyncIterable<Uint8Array>): AsyncIterable<T> {
+    let inData = false;
+    for await (let line of parseLines(stream)) {
+        if (!inData) {
+            if (line === "[") {
+                inData = true;
+            } else {
+                throw new IllegalStateException(`Expected array start but got: ${line}`);
+            }
+        } else {
+            if (line === "]") {
+                inData = false;
+            } else {
+                if (line.endsWith(",")) {
+                    line = line.substring(0, line.length - 1);
+                }
+                yield JSON.parse(line, jsonReviver);
+            }
+        }
+    }
+}
+
+/**
+ * JSON reviver function which converts numbers of ID properties (property names ending with 'ID' or 'Address') to bigint if needed.
+ *
+ * @param key     - The JSON property key.
+ * @param value   - The parsed JSON property value.
+ * @param context - The reviver context containing the raw JSON source string.
+ * @returns The already parsed JSON property value if suitable or the raw source converted into a bigint.
+ */
+export function jsonReviver(key: string, value: unknown, context?: { source: string }): unknown {
+    if (context != null && typeof value === "number" && (value > Number.MAX_SAFE_INTEGER || value < Number.MIN_SAFE_INTEGER)) {
+        const source = context.source;
+        if (key === "id64" || key === "systemId64") {
+            return BigInt(source);
+        } else if (String(value) !== source && /^[-+]?\d+$/.test(source)) {
+            throw new IllegalStateException(`Value of property '${key}' looks like a bigint (${source}) but was parsed as an imprecise number (${value})`);
+        }
+    }
+    return value;
+}