Document.The failure model

@elite-dangerous-almanac/core / The failure model

The failure model

The library distinguishes "there is no such thing" from "you passed me nonsense" from "I do not have the data", and each gets a different shape. Once you know the four, you can write a consumer that never guesses.

The four outcomes

Outcome	Means	Example
null	Nothing matched, or the input did not parse as that kind of thing	getShipBySymbol('nope')
TypeError	The input was malformed	toSystemAddress(2 ** 53)
RangeError	Well-formed, but outside a supported range	massCodeToSizeClass('z')
SyntaxError	The text was not JSON	parseSlef('{')

import { getShipBySymbol } from '@elite-dangerous-almanac/core/ships/ships';
import { toSystemAddress } from '@elite-dangerous-almanac/core/astro/system-address-input';
import { parseSlef } from '@elite-dangerous-almanac/core/ships/slef';

getShipBySymbol('no such hull'); // -> null, an ordinary answer

try {
    toSystemAddress(2 ** 53); // a number too large to be exact
} catch (error) {
    error instanceof TypeError; // -> true
}

try {
    parseSlef('{'); // JSON.parse fails before anything else runs
} catch (error) {
    error instanceof SyntaxError; // -> true
}

Two of those rows need qualifying on the SLEF entry points that accept a string — parseSlef, inspectSlef and ShipLoadout.fromSlef. All three throw SyntaxError, which comes from JSON.parse before any validation runs. Past that point a payload number outside its documented journal range — a module Priority of 5, a Health of -0.1 — counts as malformed alongside every other bad field rather than as a range violation: parseSlef and ShipLoadout.fromSlef throw TypeError naming the field, and inspectSlef records it as that entry's diagnostic.

A wrong-typed argument is malformed input, not a miss. Passing a number where a symbol belongs is the same kind of failure as passing an unusable address, and an entry point that guards it names the parameter and what arrived — ShipLoadout.empty(42) throws TypeError: ShipLoadout.empty: shipSymbol must be a string, received number 42. So does a missing one: ProceduralSystem.fromName(undefined) throws rather than answering null, because "you passed me nothing" is not "the naming scheme does not cover that system".

Human-readable errors and validation messages abbreviate an oversized argument or capture field with an ellipsis. They identify the bad value without copying a whole payload into a log or UI; structured diagnostic fields such as slot and symbol keep the original value for programmatic handling.

Which half of your call the message names depends on what you handed over, and that is worth knowing before you write a catch:

• An entry point that takes a value names the parameter and the value, and names itself — a lookup you reach through a facade reports the function you called, not the one it delegates to, so getShipSlots(42) says getShipSlots: symbol, never getShipBySymbol: symbol. toSystemAddress prints the value it rejected without a parameter to name, having only the one.
• An entry point that takes a structure names the offending field. parseSlef and ShipLoadout.fromSlef check every one of them (parseSlef: entries[0].data.Modules[0].Priority must be an integer from 0 to 4) — the more useful half when the argument is a whole export, and the same text inspectSlef reports as that entry's diagnostic. ShipLoadout.fromLoadout checks the structure a build is assembled from — an object, an array of module objects, a Slot and Item on each, no two modules claiming one slot, and an Engineering that is an object holding an array of Modifiers, each a labelled object, whenever their key is there at all — plus Ship and the block's two ids when they carry a value. It trusts every value inside, so use fromSlef for an event you did not produce yourself.

A missing argument is not a wrong-typed one, and the two get different answers:

import { getShipBySymbol } from '@elite-dangerous-almanac/core/ships/ships';

getShipBySymbol(undefined as unknown as string); // -> null, the answer an unknown symbol gets

try {
    getShipBySymbol(42 as unknown as string);
} catch (error) {
    (error as Error).message;
    // -> 'getShipBySymbol: symbol must be a string, received number 42'
}

A lookup that answers null for a symbol no record carries answers null for no symbol at all — asking for nothing found nothing. So do parseSystemName, canonicalizeSystemName and isProceduralSystemName, which answer null and false for a nullish name.

Where a missing argument is loud instead: everything that is not a search. A function that hands you back a value has no "no such thing" answer to give, so there is nothing for a missing argument to mean — ProceduralSystem.fromName(undefined) and ShipLoadout.empty(undefined) throw rather than answering null, and so do toSystemAddress, massCodeToSizeClass and resolveBlueprintForModule's fdname, which convert or resolve what you pass rather than looking it up. The rule is what the function does with the argument, not what it returns: massCodeToSizeClass hands back a number and is still strict.

A build's slot key is loud too, across all ten methods that take one, and it is the exception worth knowing because several of them do look like searches — fittedModuleAt('NoSuchMount') answers null the way a catalogue miss does. The difference is that the key names a mount on this build rather than a record to find: removeModule(undefined) is not "empty the slot that is not there", it is a caller who has not said which slot. So build.fittedModuleAt(undefined) throws ShipLoadout: slotKey must be a string, received undefined, where getShipBySymbol(undefined) would answer null.

null is not an error. A lookup that finds nothing has answered you. Journal symbols may be absent from the catalogues, so consumers must handle null as an ordinary miss.

For input you do not control, prefer the try… form where one exists, which converts a throw into a null:

import { toSystemAddress, tryToSystemAddress } from '@elite-dangerous-almanac/core/astro/system-address-input';

toSystemAddress('3309179996515'); // -> 3309179996515n, throws on bad input
tryToSystemAddress('not an address'); // -> null, never throws

Nullable value, or diagnostic result?

Aggregate figures that depend on catalogue data come in pairs. The property is the convenience; the …Result is what you show a user when the convenience is null.

import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';

declare const build: ShipLoadout;

build.cargoCapacity; // number | null
build.cargoCapacityResult; // the value, plus every rack it could not classify

build.unladenMass;
build.unladenMassResult;
build.fuelCapacity;
build.fuelCapacityResult;

The reason for the pair is that the alternative is worse: an unclassifiable cargo rack counted as zero would produce a plausible, wrong total that no one would question. A null with a list of what was missing cannot be mistaken for an answer.

A figure the import already stated wins, and comes back complete. These three are computed only when the source did not supply them, so a build read from a Loadout event — which states UnladenMass, CargoCapacity and FuelCapacity — reports the game's own numbers with no issues, whatever the catalogue made of the modules. The pair engages for a build you assembled yourself, or one whose source left the figure out. On an imported build, validation is what tells you a module went unrecognised.

Absent is not zero, anywhere in the library. A catalogue field the source did not carry is omitted rather than defaulted, and a capture that priced no module for a slot reports null rather than 0 — a cockpit no journal prices was not free.

valid against complete

Two different questions about a build, deliberately kept apart:

import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';

declare const build: ShipLoadout;

build.validation.valid; // is the fit structurally legal?
build.validation.complete; // every operational mount present and fully classified?
build.validation.issues; // what specifically

Each issue carries a stable code and a severity:

• error — the fit is wrong: a module in a mount that cannot take it (incompatibleModule), or a mount the hull does not have (unknownSlot). This is the user's problem, and you should say so. (duplicateSlot is an error too, but only ever reaches you from validateLoadout on a module list you assembled yourself — a ShipLoadout throws TypeError on a duplicate rather than reporting one, so do not write a UI branch for it on a build.)
• incomplete — the build does not add up to a finished answer, for one of two quite different reasons.

Branch on the code, not on the severity, because the two incomplete reasons belong in different places in your UI:

• missingRequiredSlot is the user's problem — a core or armour mount is empty. A hull straight from ShipLoadout.empty() reports eight of these, and "you have not fitted a power plant" is exactly what an outfitting screen must show as actionable.
• unknownHull and unknownModule are ours — the catalogue cannot classify the record. The build may be valid in game, so do not present this as a user mistake.

That is why the codes are stable: the severity alone does not tell you whose problem an issue is.

Strict about input, forgiving about spelling

Two rules that look like they conflict and do not:

• Identifiers are matched case-insensitively, with surrounding whitespace ignored. A symbol straight off a journal line works without normalizing it, and slot keys match whether the producer wrote FrameShiftDrive or frameshiftdrive.
• Structure is checked strictly. A malformed entry is rejected rather than half-read, and parseSlef rejects the whole payload on any bad entry. Use inspectSlef when you would rather have the good entries plus indexed diagnostics.

Data you can rely on not changing

Exported catalogues are deeply frozen, so nothing a consumer does can mutate the shared singleton a later lookup sees. Units are stated on the exported types: resistances are fractions, masses tonnes, power megawatts, distances light-years, shield strength megajoules — unless a symbol's own name says otherwise.

Next

• Getting started
• Reading a player journal
• Complete API reference