@elite-dangerous-almanac/core 0.1.0-beta.1

package/dist/ships/slef.d.ts

@@ -0,0 +1,318 @@
+/**
+ * **SLEF** — the Ship Loadout Export Format — types, a strict parser and a tolerant
+ * inspector.
+ *
+ * SLEF is the community interchange format for a fitted ship, used by EDSY,
+ * Coriolis, Inara and others. It is nothing more than the game journal's `Loadout`
+ * event wrapped in an envelope that records which app exported it:
+ *
+ * ```json
+ * [{ "header": { "appName": "EDSY", "appVersion": "..." },
+ *    "data":   { "event": "Loadout", "Ship": "explorer_nx", "Modules": [ ... ] } }]
+ * ```
+ *
+ * The top level is an **array** so several builds can travel together. This module
+ * is **data-free** — just the record shapes, {@link parseSlef} / {@link getLoadoutModifier}
+ * to read, and {@link toSlef} / {@link stringifySlef} to write. To turn a parsed build
+ * into jump-range and fuel numbers, or to produce the `Loadout` event {@link toSlef}
+ * wraps, hand it to {@link ShipLoadout} (`./ship-loadout`).
+ *
+ * ```ts
+ * const build = ShipLoadout.fromSlef(exported);       // in
+ * const text = stringifySlef(
+ *     build.toSlef({ header: { appName: 'MyApp', appVersion: '1.0.0' } }),
+ * );                                                  // and back out
+ * ```
+ *
+ * Reference: the Inara SLEF specification, <https://inara.cz/elite/inara-impexp-slef/>.
+ *
+ * @packageDocumentation
+ */
+/** The envelope header — which app produced the export. */
+interface SlefHeader {
+    /** Exporting app's name, e.g. `"EDSY"`. */
+    readonly appName: string;
+    /**
+     * Exporting app's version. The spec calls for a string; some apps emit a
+     * number, so both are accepted.
+     */
+    readonly appVersion: string | number;
+    /** A link back to the build in the exporting app, when given. */
+    readonly appURL?: string;
+    /** App-specific extra fields, when given. */
+    readonly appCustomProperties?: Readonly<Record<string, unknown>>;
+}
+/**
+ * One engineering modifier — how a blueprint changed a single stat.
+ *
+ * @remarks
+ * `Value` is the post-engineering figure, `OriginalValue` the stock one. Some
+ * modifiers carry a string (`ValueStr`) instead of a number — generated Anti-Guardian
+ * Zone Resistance uses `"Active"`. **Do not trust `LessIsGood`** — Frontier is known to
+ * set it wrongly for some stats; decide a stat's direction yourself.
+ */
+interface EngineeringModifier {
+    /** The stat's journal name, e.g. `"FSDOptimalMass"`, `"Mass"`, `"PowerDraw"`. */
+    readonly Label: string;
+    /** The modified value, when the stat is numeric. */
+    readonly Value?: number;
+    /** The stock value before engineering, when the stat is numeric. */
+    readonly OriginalValue?: number;
+    /** A string-valued modifier's value (rare; used for non-numeric stats). */
+    readonly ValueStr?: string;
+    /** `1` if a lower value is better — unreliable; see the remark above. */
+    readonly LessIsGood?: number;
+}
+/**
+ * The durable engineering applied to one module.
+ *
+ * @remarks
+ * A journal capture may also name `Engineer`, `EngineerID` and `BlueprintID`.
+ * They are deliberately outside this type: the engineer fields record who applied a
+ * modification, while the numeric blueprint id is redundant with {@link BlueprintName};
+ * none changes the fitted module. {@link ShipLoadout.fromLoadout} therefore drops them
+ * and subsequent loadout/SLEF exports never write them.
+ */
+interface ModuleEngineering {
+    /** The blueprint's journal name, e.g. `"FSD_LongRange"`. */
+    readonly BlueprintName: string;
+    /** The blueprint grade, 1–5. */
+    readonly Level: number;
+    /** The roll quality, 0–1. */
+    readonly Quality: number;
+    /** The experimental effect's journal name, when one is applied. */
+    readonly ExperimentalEffect?: string;
+    /** The experimental effect's display name, when present. */
+    readonly ExperimentalEffect_Localised?: string;
+    /**
+     * Every stat this engineering changed.
+     *
+     * @remarks
+     * **Optional.** A journal `Loadout` event always writes it, but SLEF requires only
+     * `BlueprintName`, `Level` and `Quality` — the specification's own example omits it —
+     * so an export from another app may name the blueprint and its roll without spelling
+     * out the resulting stats. Treat a missing array as "not stated", not as "nothing was
+     * changed": the blueprint's effect can be recomputed with `computeModifiers` from
+     * `./engineering`.
+     */
+    readonly Modifiers?: readonly EngineeringModifier[];
+}
+/**
+ * One fitted module in a `Loadout` event.
+ *
+ * @remarks
+ * **Ammunition state is not carried.** A journal writes `AmmoInClip` and `AmmoInHopper`
+ * on every weapon that takes ammunition; both are dropped on import and never written
+ * back out, because they are the ship's rearm state at the instant of capture rather than
+ * part of the build — the same reason a re-export recomputes a build's credit figures by
+ * default instead of echoing the ones the capture carried. What a fitted weapon *can*
+ * hold is a property of the build, and `./ammunition` answers it: `ammunitionCapacity`,
+ * or `FittedModule.ammunition` for a fitted one, post-engineering.
+ */
+interface LoadoutModule {
+    /** The slot it occupies, e.g. `"FrameShiftDrive"`, `"Slot07_Size5"`. */
+    readonly Slot: string;
+    /** The module's internal id, e.g. `"int_hyperdrive_size5_class5"` (lower-cased). */
+    readonly Item: string;
+    /** Whether the module is powered on. Absent means on. */
+    readonly On?: boolean;
+    /** The module's power-priority group (0–4). */
+    readonly Priority?: number;
+    /** Module health, 0–1. */
+    readonly Health?: number;
+    /**
+     * What the capture says was paid for this module, in credits — net of whatever
+     * discount its owner had, and not the catalogue's list price. Absent where the
+     * capture said nothing, which is not the same as free.
+     * `ShipLoadout.sourcePurchase` keeps these figures as a stable record; the library's
+     * own exports quote list price.
+     */
+    readonly Value?: number;
+    /** Engineering, present only when the module is modified. */
+    readonly Engineering?: ModuleEngineering;
+}
+/**
+ * A journal `Loadout` event — the `data` half of a SLEF entry.
+ *
+ * @remarks
+ * Only `Ship` and `Modules` are strictly required by SLEF; every other field is
+ * optional. Masses are in tonnes, ranges in light-years, values in credits.
+ *
+ * `timestamp`, `ShipID`, `HullHealth` and `Hot` are deliberately outside the durable
+ * loadout shape. They describe the capture or the ship instance/state rather than its
+ * fit, so {@link ShipLoadout.fromLoadout} drops them and subsequent loadout/SLEF exports
+ * never write them. A tolerant parse still accepts an input object carrying those keys.
+ */
+interface LoadoutEvent {
+    /** Always `"Loadout"`. */
+    readonly event?: string;
+    /** The hull's internal id, e.g. `"explorer_nx"` (lower-cased). */
+    readonly Ship: string;
+    /** The player-given ship name. */
+    readonly ShipName?: string;
+    /** The player-given ship ID plate. */
+    readonly ShipIdent?: string;
+    /** Hull cost in credits. */
+    readonly HullValue?: number;
+    /** Fitted-modules cost in credits. */
+    readonly ModulesValue?: number;
+    /** Hull + modules mass with an empty tank and no cargo, in tonnes. */
+    readonly UnladenMass?: number;
+    /** Cargo rack capacity, in tonnes. */
+    readonly CargoCapacity?: number;
+    /** The exporter's own best single-jump range, in light-years. */
+    readonly MaxJumpRange?: number;
+    /** Fuel-tank capacities, in tonnes. */
+    readonly FuelCapacity?: {
+        readonly Main: number;
+        readonly Reserve: number;
+    };
+    /** Insurance rebuy cost in credits. */
+    readonly Rebuy?: number;
+    /** Every fitted module. */
+    readonly Modules: readonly LoadoutModule[];
+}
+/** One `{ header, data }` pair in a SLEF export. */
+interface SlefEntry {
+    /** Which app produced this entry. */
+    readonly header: SlefHeader;
+    /** The fitted-ship loadout. */
+    readonly data: LoadoutEvent;
+}
+/** A whole SLEF export — one or more {@link SlefEntry entries}. */
+type Slef = readonly SlefEntry[];
+/** Stable machine-readable reason an entry was rejected. */
+type SlefDiagnosticCode = 'invalidHeader' | 'invalidLoadout' | 'invalidModule' | 'invalidEngineering' | 'duplicateSlot';
+/** One entry rejected by {@link inspectSlef}. */
+interface SlefDiagnostic {
+    /** Zero-based entry index in the top-level array. */
+    readonly index: number;
+    /** Stable machine-readable category. */
+    readonly code: SlefDiagnosticCode;
+    /** Property path to the rejected value, including entry and module indexes. */
+    readonly path: string;
+    /** Human-readable reason the entry was rejected. */
+    readonly message: string;
+}
+/** Tolerant SLEF inspection result. */
+interface SlefInspection {
+    /** Valid entries, retaining their input order. */
+    readonly entries: readonly SlefEntry[];
+    /** Rejected entries, retaining their input order. */
+    readonly diagnostics: readonly SlefDiagnostic[];
+}
+/**
+ * Inspect a potentially mixed SLEF payload without silently losing malformed entries.
+ *
+ * @param input - A JSON string, SLEF envelope/array, or bare `Loadout` event.
+ * @returns Every valid entry and an indexed diagnostic for every rejected entry.
+ * @throws {SyntaxError} If a string is not valid JSON.
+ * @example
+ * ```ts
+ * import { inspectSlef } from '@elite-dangerous-almanac/core/ships/slef';
+ *
+ * const result = inspectSlef([{ Ship: 'sidewinder', Modules: [{ Slot: 'PowerPlant' }] }]);
+ * result.diagnostics[0]?.path; // -> 'entries[0].Modules[0].Item'
+ * ```
+ */
+declare function inspectSlef(input: unknown): SlefInspection;
+/**
+ * Parse a SLEF export into its entries.
+ *
+ * @param input - Either the SLEF JSON **string** or an already-parsed object.
+ * Accepted shapes, in order of leniency:
+ * - the standard array `[{ header, data }, ...]`;
+ * - a single `{ header, data }` object;
+ * - a bare journal `Loadout` event (`{ Ship, Modules, ... }`) — wrapped in an entry
+ *   with an empty synthetic header.
+ * Every returned header, loadout, module and engineering modifier is runtime-checked
+ * against the public record shape. Parsing is strict: one malformed entry rejects the
+ * whole payload. Use {@link inspectSlef} to recover valid entries from a mixed payload.
+ * @returns The entries, in export order — never empty (a parse that finds no valid
+ * entry throws instead).
+ * @throws {SyntaxError} If `input` is a string that is not valid JSON.
+ * @throws {TypeError} If the payload is empty or any entry, header, loadout, module or
+ * engineering field is malformed.
+ * @example
+ * ```ts
+ * import { parseSlef } from '@elite-dangerous-almanac/core/ships/slef';
+ *
+ * declare const slefJsonString: string;
+ *
+ * const [entry] = parseSlef(slefJsonString);
+ * entry?.data.Ship; // -> 'explorer_nx'
+ * ```
+ */
+declare function parseSlef(input: unknown): SlefEntry[];
+/** Options for {@link stringifySlef}. */
+interface SlefStringifyOptions {
+    /**
+     * Spaces per indent level. `0` — the default — emits compact JSON, which is what
+     * the clipboard-and-paste exchange these exports travel by wants.
+     */
+    readonly indent?: number;
+}
+/**
+ * Wrap one or more loadouts in SLEF envelopes.
+ *
+ * @param data - A single `Loadout` event or several. Several travel in one export as
+ * separate entries, which is what the format's array top level is for.
+ * @param header - Which exporting app to credit. SLEF attribution belongs to the
+ * application producing the export, so callers must provide its name and version.
+ * @returns The export, one entry per loadout, in the order given.
+ * @throws {TypeError} If `data` is empty, or the header or any loadout does not match
+ * the record shape. Every entry is checked with the same guards {@link parseSlef}
+ * applies, so anything this returns is guaranteed to parse back.
+ * @example
+ * ```ts
+ * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+ * import { stringifySlef, toSlef } from '@elite-dangerous-almanac/core/ships/slef';
+ *
+ * declare const build: ShipLoadout;
+ *
+ * const slef = toSlef(build.toLoadoutEvent(), { appName: 'MyApp', appVersion: '1.2.0' });
+ * stringifySlef(slef); // -> '[{"header":{...},"data":{...}}]'
+ * ```
+ */
+declare function toSlef(data: LoadoutEvent | readonly LoadoutEvent[], header: SlefHeader): Slef;
+/**
+ * Serialise a SLEF export to its JSON string.
+ *
+ * @param slef - The entries, as {@link toSlef} returns them.
+ * @param options - Formatting. Compact by default.
+ * @returns The JSON text.
+ * @example
+ * ```ts
+ * import { stringifySlef } from '@elite-dangerous-almanac/core/ships/slef';
+ * import type { Slef } from '@elite-dangerous-almanac/core/ships/slef';
+ *
+ * declare const slef: Slef;
+ *
+ * stringifySlef(slef, { indent: 2 }); // human-readable, for writing to a file
+ * ```
+ */
+declare function stringifySlef(slef: Slef, options?: SlefStringifyOptions): string;
+/**
+ * Read one engineering modifier off a module by its journal label.
+ *
+ * @param module - The fitted module.
+ * @param label - The stat's journal name, e.g. `"FSDOptimalMass"`. Matched
+ * case-insensitively.
+ * @returns The modifier's numeric `Value`, or `null` if the module is not
+ * engineered, states no modifiers at all, carries no such modifier, or the modifier is
+ * non-numeric.
+ * @throws {TypeError} If `label` is present and not a string. A nullish
+ * `label` is a miss, answered the way an unrecognised one is.
+ * @example
+ * ```ts
+ * import { getLoadoutModifier } from '@elite-dangerous-almanac/core/ships/slef';
+ * import type { LoadoutModule } from '@elite-dangerous-almanac/core/ships/slef';
+ *
+ * declare const fsdModule: LoadoutModule;
+ *
+ * getLoadoutModifier(fsdModule, 'FSDOptimalMass'); // -> 7528.04, or null if stock
+ * ```
+ */
+declare function getLoadoutModifier(module: LoadoutModule, label: string): number | null;
+
+export { type EngineeringModifier, type LoadoutEvent, type LoadoutModule, type ModuleEngineering, type Slef, type SlefDiagnostic, type SlefDiagnosticCode, type SlefEntry, type SlefHeader, type SlefInspection, type SlefStringifyOptions, getLoadoutModifier, inspectSlef, parseSlef, stringifySlef, toSlef };

package/dist/ships/slef.js

@@ -0,0 +1 @@
+export{getLoadoutModifier,inspectSlef,parseSlef,stringifySlef,toSlef}from"../chunk-R4OD62HV.js";                                                          //# sourceMappingURL=slef.js.map

package/dist/ships/slef.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"O"}