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

package/dist/system-address-DYsN1qOT.d.ts

@@ -0,0 +1,313 @@
+import { SystemNameParts } from './astro/system-name.js';
+import { SectorGridPosition } from './astro/sector-name.js';
+import { SystemAddressInput } from './astro/system-address-input.js';
+
+/**
+ * Origins of Elite Dangerous **naming regions** and the fallback that synthesises
+ * an origin for any procedural sector.
+ *
+ * Encoding a system name to an `id64` needs its region's origin (in internal
+ * units, 32 per light-year, measured from the galaxy corner). Hand-authored
+ * regions — nebula/cluster sectors such as `Col 285 Sector` or
+ * `Cepheus Dark Region B` — have catalogued origins that are *not* aligned to the
+ * boxel grid, so they are looked up from data. Any other region is a plain
+ * procedural sector whose origin is simply its grid position times the sector
+ * size.
+ *
+ * The catalogue derives from the EDTS reference implementation and community procedural-naming
+ * research, cross-checked against EDSM/Spansh; see [`data/astro/SOURCES.md`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/data/astro/SOURCES.md) for
+ * provenance.
+ *
+ * The catalogue is loaded once from shared JSON ([`data/astro/`](https://github.com/DarkSession/Elite-Dangerous-Almanac/tree/main/data/astro)); the lookup map is
+ * an immutable module constant.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A region's origin and extent, in internal units (32 per light-year, measured
+ * from the galaxy corner).
+ *
+ * @example
+ * ```ts
+ * import type { NamingRegionOrigin } from '@elite-dangerous-almanac/core/astro/naming-region-origins';
+ *
+ * const origin: NamingRegionOrigin = {
+ *   name: 'Example Sector',
+ *   x0: 0, y0: 0, z0: 0,
+ *   sizeX: 40960, sizeY: 40960, sizeZ: 40960,
+ * };
+ * ```
+ */
+interface NamingRegionOrigin {
+    /** The region name, as catalogued. */
+    readonly name: string;
+    /** Origin X in internal units. */
+    readonly x0: number;
+    /** Origin Y in internal units. */
+    readonly y0: number;
+    /** Origin Z in internal units. */
+    readonly z0: number;
+    /** Extent along X in internal units. */
+    readonly sizeX: number;
+    /** Extent along Y in internal units. */
+    readonly sizeY: number;
+    /** Extent along Z in internal units. */
+    readonly sizeZ: number;
+}
+/**
+ * Look up a hand-authored named region's catalogued origin.
+ *
+ * @param name - A named region in any casing, with optional surrounding whitespace.
+ * @returns Its canonical origin record, or `null` when it is not catalogued.
+ * @throws {TypeError} If `name` is present and not a string. A nullish
+ * `name` is a miss, answered the way an unrecognised one is.
+ * @example
+ * ```ts
+ * import { getHandAuthoredRegionOrigin } from '@elite-dangerous-almanac/core/astro/naming-region-origins';
+ *
+ * getHandAuthoredRegionOrigin('  PLEIADES SECTOR ')?.name; // -> 'Pleiades Sector'
+ * getHandAuthoredRegionOrigin('Synuefe');                  // -> null
+ * ```
+ */
+declare function getHandAuthoredRegionOrigin(name: string): NamingRegionOrigin | null;
+/**
+ * Resolve a region name to its origin.
+ *
+ * Hand-authored regions come from the catalogue; any other name is treated as a
+ * procedural sector and its origin synthesised from the sector grid. Returns
+ * `null` only when the name is neither catalogued nor a valid procedural sector.
+ *
+ * @param name - A region (sector) name in any casing.
+ * @returns The region origin, or `null` if the name cannot be resolved.
+ * @throws {TypeError} If `name` is present and not a string. A nullish
+ * `name` is a miss, answered the way an unrecognised one is.
+ * @example
+ * ```ts
+ * import { resolveNamingRegionOrigin } from '@elite-dangerous-almanac/core/astro/naming-region-origins';
+ *
+ * resolveNamingRegionOrigin('Pleiades Sector'); // catalogued, hand-authored origin
+ * resolveNamingRegionOrigin('Synuefe');         // origin derived from its grid position
+ * resolveNamingRegionOrigin('not a region');    // -> null
+ * ```
+ */
+declare function resolveNamingRegionOrigin(name: string): NamingRegionOrigin | null;
+
+/**
+ * The Elite Dangerous **system address** (`id64`) — the 64-bit integer that
+ * uniquely identifies a system and encodes its procedural origin.
+ *
+ * The address packs, from the low bit up: the size class (3 bits), then the
+ * boxel's absolute grid position split per axis into a sector coordinate and a
+ * within-sector offset, and finally the sequence number. Field widths shift with
+ * the size class, which is why every accessor is parameterised by it. A second,
+ * "modulated" layout ({@link encodeModSystemAddress}) is used by some tools and
+ * regroups the same information.
+ *
+ * These functions are pure bit arithmetic over {@link NamingRegionOrigin} values that
+ * the caller supplies; resolving a region name to an origin lives in
+ * `./naming-region-origins`. All packing uses `BigInt`, since fields reach bit 55 and JS
+ * number bitwise operators truncate to 32 bits.
+ *
+ * @packageDocumentation
+ */
+
+/** The edge of one procedural sector in internal units (1280 ly × 32 units/ly). */
+declare const SECTOR_INTERNAL_SIZE = 40960;
+/**
+ * Return the boxel edge for a size class in internal units (32 units per ly).
+ *
+ * @param sizeClass - An integer from 0 through 7.
+ * @returns The boxel edge in internal units (320 through 40960). Divide by 32 for
+ * light-years, or use `boxelEdgeLy` from `./mass-code`.
+ * @throws {RangeError} If `sizeClass` is outside 0–7.
+ * @example
+ * ```ts
+ * import { boxelInternalSize } from '@elite-dangerous-almanac/core/astro/system-address';
+ *
+ * boxelInternalSize(3);      // -> 2560 internal units
+ * boxelInternalSize(3) / 32; // -> 80 ly, the edge of a d-class boxel
+ * ```
+ */
+declare function boxelInternalSize(sizeClass: number): number;
+/**
+ * A boxel's position on the per-size-class boxel grid, counted from the galaxy corner.
+ *
+ * @remarks
+ * These are grid indices, not light-years: one step is one boxel edge, which depends on
+ * the size class ({@link boxelEdgeLy} from `./mass-code` converts).
+ *
+ * @example
+ * ```ts
+ * import { decodeSystemAddress } from '@elite-dangerous-almanac/core/astro/system-address';
+ * import type { AbsoluteBoxel } from '@elite-dangerous-almanac/core/astro/system-address';
+ *
+ * const boxel: AbsoluteBoxel = decodeSystemAddress(3309179996515n).absoluteBoxel;
+ * ```
+ */
+interface AbsoluteBoxel {
+    /** Boxel index along the galactic X axis. */
+    readonly x: number;
+    /** Boxel index along the galactic Y axis. */
+    readonly y: number;
+    /** Boxel index along the galactic Z axis. */
+    readonly z: number;
+}
+/** A system address decoded into its geometric components. */
+interface DecodedAddress {
+    /** Size class 0–7 (mass code `a`–`h`). */
+    readonly sizeClass: number;
+    /** The sector's position on the galaxy grid. */
+    readonly sectorGridPosition: SectorGridPosition;
+    /** The boxel's base-26 index within the sector (the "boxel code"). */
+    readonly boxelCode: number;
+    /** The system sequence number (`N2`). */
+    readonly sequence: number;
+    /** The boxel's absolute position on the per-size-class boxel grid. */
+    readonly absoluteBoxel: AbsoluteBoxel;
+}
+/**
+ * Absolute boxel indices of a name's boxel code, relative to the galaxy origin.
+ *
+ * This is the inverse of the decode split: it turns the base-26 boxel code back
+ * into a grid position by adding the region origin (snapped down to the boxel
+ * grid). It throws rather than emit a wrong address when the origin has a negative
+ * coordinate, when N1 overflows the code, when the boxel code falls outside the
+ * region, or when the resulting sector cannot be represented by the address bits.
+ *
+ * @param sizeClass - Size class 0–7 (mass code `a`–`h`).
+ * @param boxelCode - The base-26 boxel code ({@link lettersToBoxelCode}).
+ * @param origin - The resolved region origin (internal units, 32 per light-year).
+ * @returns The boxel's absolute indices on the per-size-class boxel grid, measured
+ * from the galaxy corner.
+ * @throws {RangeError} If `sizeClass` is outside 0–7, the origin has a negative
+ * coordinate, or the code or the resulting sector is out of range.
+ */
+declare function boxelCodeToAbsoluteBoxel(sizeClass: number, boxelCode: number, origin: NamingRegionOrigin): AbsoluteBoxel;
+/**
+ * Boxel code (base-26 index) of an absolute boxel relative to a region origin,
+ * or `null` when the boxel does not sit inside that region.
+ *
+ * Used by the hand-authored-sector override: the same physical boxel yields a
+ * different boxel code under a hand-authored region whose origin differs from
+ * the procedural sector's. This is the inverse of {@link boxelCodeToAbsoluteBoxel}.
+ *
+ * @param sizeClass - Size class 0–7 (mass code `a`–`h`).
+ * @param absoluteBoxel - The boxel's absolute grid indices, as
+ * {@link decodeSystemAddress} returns in `absoluteBoxel`.
+ * @param origin - The region origin to measure against (internal units, 32 per
+ * light-year), from `./naming-region-origins`.
+ * @returns The base-26 boxel code within that region, or `null` when the boxel lies
+ * outside the region or the origin has a negative coordinate.
+ * @example
+ * ```ts
+ * import { resolveNamingRegionOrigin } from '@elite-dangerous-almanac/core/astro/naming-region-origins';
+ * import { absoluteBoxelToBoxelCode, decodeSystemAddress } from '@elite-dangerous-almanac/core/astro/system-address';
+ *
+ * declare const id64: bigint;
+ *
+ * const { sizeClass, absoluteBoxel } = decodeSystemAddress(id64);
+ * absoluteBoxelToBoxelCode(sizeClass, absoluteBoxel, resolveNamingRegionOrigin('Pleiades Sector')!);
+ * ```
+ */
+declare function absoluteBoxelToBoxelCode(sizeClass: number, absoluteBoxel: AbsoluteBoxel, origin: NamingRegionOrigin): number | null;
+/**
+ * Decode a system address into its geometric components.
+ *
+ * @param id64 - The 64-bit system address, as a `bigint`, a normally parsed
+ * journal `number`, or a decimal `string` (see {@link SystemAddressInput}).
+ * @returns The decoded size class, sector, boxel code, sequence and absolute boxel.
+ * @throws {TypeError} If `id64` is not a usable address representation (a
+ * non-integer, or a `number` so large it has already been rounded).
+ * @throws {RangeError} If `id64` is negative or does not fit in 64 bits.
+ * @example
+ * ```ts
+ * import { decodeSystemAddress } from '@elite-dangerous-almanac/core/astro/system-address';
+ * declare const event: { SystemAddress: number }; // an `FSDJump` line, parsed
+ *
+ * decodeSystemAddress(3309179996515n);
+ * // -> { sizeClass: 3, sectorGridPosition: { sectorX: 39, sectorY: 31, sectorZ: 18 }, … }
+ *
+ * decodeSystemAddress(event.SystemAddress); // a journal number works too
+ * ```
+ */
+declare function decodeSystemAddress(id64: SystemAddressInput): DecodedAddress;
+/**
+ * Decode a **modulated** system address into its geometric components.
+ *
+ * @remarks
+ * The modulated form is an alternative bit-layout of the *same* system, used by
+ * some community tools and data dumps. If you have a normal `id64` (the usual
+ * case — journal, EDSM, EDDN, Spansh all use it), reach for
+ * {@link decodeSystemAddress} instead; use this only when a source specifically
+ * hands you a modulated address.
+ *
+ * @param id64 - The 64-bit modulated system address, as a `bigint`, a safe-integer
+ * `number`, or a decimal `string` (see {@link SystemAddressInput}). A modulated
+ * address packs the sector into the high bits, so it routinely exceeds `2^53`;
+ * those values must be supplied as a `bigint` or string because a JS `number` has
+ * already lost precision.
+ * @returns The decoded components (same shape as {@link decodeSystemAddress}).
+ * @throws {TypeError} If `id64` is not a usable address representation.
+ * @throws {RangeError} If `id64` is negative or does not fit in 64 bits.
+ * @example
+ * ```ts
+ * import { decodeModSystemAddress } from '@elite-dangerous-almanac/core/astro/system-address';
+ *
+ * declare const modAddressFromSomeTool: bigint;
+ *
+ * decodeModSystemAddress(modAddressFromSomeTool).sectorGridPosition;
+ * // -> { sectorX, sectorY, sectorZ }
+ * ```
+ */
+declare function decodeModSystemAddress(id64: SystemAddressInput): DecodedAddress;
+/**
+ * Encode system-name parts and a resolved region origin into a system address.
+ *
+ * @param parts - The parsed system-name parts, as {@link parseSystemName} returns
+ * (letters and mass code are zero-based numeric indices, not characters).
+ * @param origin - The region origin (internal units), from
+ * `resolveNamingRegionOrigin` in `./naming-region-origins`.
+ * @returns The 64-bit system address.
+ * @throws {RangeError} If the mass code is outside 0–7, a letter is outside 0–25, `n1`
+ * is not one the boxel packer accepts, the origin has a negative coordinate, the name's boxel code or sector falls outside the
+ * address layout, or the sequence does not fit its size-class-dependent field.
+ * @example
+ * ```ts
+ * import { resolveNamingRegionOrigin } from '@elite-dangerous-almanac/core/astro/naming-region-origins';
+ * import { encodeSystemAddress } from '@elite-dangerous-almanac/core/astro/system-address';
+ * import { parseSystemName } from '@elite-dangerous-almanac/core/astro/system-name';
+ *
+ * const parts = parseSystemName('Synuefe EN-H d11-96')!;
+ * encodeSystemAddress(parts, resolveNamingRegionOrigin(parts.regionName)!); // -> 3309179996515n
+ * ```
+ */
+declare function encodeSystemAddress(parts: SystemNameParts, origin: NamingRegionOrigin): bigint;
+/**
+ * Encode system-name parts and a resolved region origin into a **modulated**
+ * address.
+ *
+ * @remarks
+ * Prefer {@link encodeSystemAddress} for the normal `id64`; use the modulated
+ * form only when a tool you are feeding expects that specific layout.
+ *
+ * @param parts - The parsed system-name parts, as {@link parseSystemName} returns.
+ * @param origin - The region origin (internal units), from `resolveNamingRegionOrigin`.
+ * @returns The 64-bit modulated system address. These routinely exceed `2^53`, so
+ * keep them as `bigint` (or a decimal string) rather than a JS `number`.
+ * @throws {RangeError} If the mass code is outside 0–7, a letter is outside 0–25, `n1`
+ * is not one the boxel packer accepts, the origin has a negative coordinate, the name's boxel code or sector falls outside the
+ * address layout, or the sequence does not fit the 15-bit modulated field.
+ * @example
+ * ```ts
+ * import { resolveNamingRegionOrigin } from '@elite-dangerous-almanac/core/astro/naming-region-origins';
+ * import { encodeModSystemAddress } from '@elite-dangerous-almanac/core/astro/system-address';
+ * import { parseSystemName } from '@elite-dangerous-almanac/core/astro/system-name';
+ *
+ * const parts = parseSystemName('Synuefe EN-H d11-96')!;
+ * encodeModSystemAddress(parts, resolveNamingRegionOrigin(parts.regionName)!).toString();
+ * ```
+ */
+declare function encodeModSystemAddress(parts: SystemNameParts, origin: NamingRegionOrigin): bigint;
+
+export { type AbsoluteBoxel as A, type DecodedAddress as D, type NamingRegionOrigin as N, SECTOR_INTERNAL_SIZE as S, absoluteBoxelToBoxelCode as a, boxelCodeToAbsoluteBoxel as b, boxelInternalSize as c, decodeModSystemAddress as d, decodeSystemAddress as e, encodeModSystemAddress as f, encodeSystemAddress as g, getHandAuthoredRegionOrigin as h, resolveNamingRegionOrigin as r };