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

package/dist/astro/nebulae-planetary.d.ts

@@ -0,0 +1,37 @@
+import { Nebula } from './nebulae.js';
+import '../galactic-position-shLkm4Qg.js';
+
+/**
+ * The catalogue of **planetary** nebulae — 5489 of them, the largest class in the
+ * catalogue, each catalogued at the procedurally-named system it surrounds.
+ *
+ * @remarks
+ * **This is the heaviest data module in the library (~399 KiB bundled).** Import it
+ * only when you genuinely need every planetary nebula; for the 180 recognisable
+ * real-world nebulae use `./nebulae-real` instead (~16 KiB). Because each catalogue
+ * is its own module, importing that one never pulls this one in.
+ *
+ * Data from EDAstro; see [ATTRIBUTIONS.md](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/ATTRIBUTIONS.md) for credit and licence terms.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * All 5489 planetary nebulae, sorted by name.
+ *
+ * @remarks
+ * Every record has `type: 'planetary'`. `name` is normally identical to `system`;
+ * where explorers have given one a community name it is appended in parentheses
+ * (`"Aemonz WZ-Y e6771 (Lazurite Nebula)"`).
+ *
+ * @example
+ * ```ts
+ * import { PLANETARY_NEBULAE } from '@elite-dangerous-almanac/core/astro/nebulae-planetary';
+ *
+ * PLANETARY_NEBULAE.length;  // -> 5489
+ * PLANETARY_NEBULAE[0]?.name; // -> 'Aemonz EQ-Y e1899'
+ * ```
+ */
+declare const PLANETARY_NEBULAE: readonly Nebula[];
+
+export { PLANETARY_NEBULAE };

package/dist/astro/nebulae-planetary.js

@@ -0,0 +1 @@
+export{PLANETARY_NEBULAE}from"../chunk-Z4OUB4SJ.js";                                                          //# sourceMappingURL=nebulae-planetary.js.map

package/dist/astro/nebulae-planetary.js.map

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

package/dist/astro/nebulae-procgen.d.ts

@@ -0,0 +1,36 @@
+import { Nebula } from './nebulae.js';
+import '../galactic-position-shLkm4Qg.js';
+
+/**
+ * The catalogue of **procedurally generated** nebulae — 166 nebulae the galaxy
+ * generator places out in the black, catalogued at a nearby system.
+ *
+ * Their names follow the procedural scheme of the sector they sit in
+ * (`Agnairt AA-A h36`), so unlike {@link REAL_NEBULAE} they carry no real-world
+ * catalogue identity. About 16 KiB bundled; the far larger planetary class lives in
+ * `./nebulae-planetary`.
+ *
+ * Data from EDAstro; see [ATTRIBUTIONS.md](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/ATTRIBUTIONS.md) for credit and licence terms.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * All 166 procedurally generated nebulae, sorted by name.
+ *
+ * @remarks
+ * Every record has `type: 'procgen'`. Note that `name` and `system` differ here:
+ * the nebula is named for its own boxel (`Agnairt AA-A h36`) while `system` is the
+ * catalogued system nearby (`Agnairt TA-U d4-360`).
+ *
+ * @example
+ * ```ts
+ * import { PROCGEN_NEBULAE } from '@elite-dangerous-almanac/core/astro/nebulae-procgen';
+ *
+ * PROCGEN_NEBULAE.length;    // -> 166
+ * PROCGEN_NEBULAE[0]?.name;   // -> 'Agnairt AA-A h36'
+ * ```
+ */
+declare const PROCGEN_NEBULAE: readonly Nebula[];
+
+export { PROCGEN_NEBULAE };

package/dist/astro/nebulae-procgen.js

@@ -0,0 +1 @@
+export{PROCGEN_NEBULAE}from"../chunk-K7F6WC4T.js";                                                          //# sourceMappingURL=nebulae-procgen.js.map

package/dist/astro/nebulae-procgen.js.map

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

package/dist/astro/nebulae-real.d.ts

@@ -0,0 +1,37 @@
+import { Nebula } from './nebulae.js';
+import '../galactic-position-shLkm4Qg.js';
+
+/**
+ * The catalogue of **real** nebulae — the 180 real-world nebulae and dark regions
+ * Elite Dangerous models under their catalogue name (Horsehead, Witch Head,
+ * Barnard's Loop, the Coalsack and Aquila dark regions, …).
+ *
+ * This is the small, human-recognisable slice of the nebula catalogue (~16 KiB
+ * bundled) and the one most apps want. The much larger planetary and procedurally
+ * generated classes live in `./nebulae-planetary` and `./nebulae-procgen`, so
+ * importing this module never bundles them.
+ *
+ * Data from EDAstro; see [ATTRIBUTIONS.md](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/ATTRIBUTIONS.md) for credit and licence terms.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * All 180 real-world nebulae and dark regions, sorted by name.
+ *
+ * @remarks
+ * Every record has `type: 'real'`. Search it with `nearestNebulae` or
+ * `nebulaeWithin` from `./nebulae`.
+ *
+ * @example
+ * ```ts
+ * import { REAL_NEBULAE } from '@elite-dangerous-almanac/core/astro/nebulae-real';
+ *
+ * REAL_NEBULAE.length; // -> 180
+ * REAL_NEBULAE.find((n) => n.name === 'Horsehead Nebula')?.system;
+ * // -> 'Horsehead Dark Region IR-V c2-9'
+ * ```
+ */
+declare const REAL_NEBULAE: readonly Nebula[];
+
+export { REAL_NEBULAE };

package/dist/astro/nebulae-real.js

@@ -0,0 +1 @@
+export{REAL_NEBULAE}from"../chunk-HI7FCS3G.js";                                                          //# sourceMappingURL=nebulae-real.js.map

package/dist/astro/nebulae-real.js.map

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

package/dist/astro/nebulae.d.ts

@@ -0,0 +1,169 @@
+import { G as GalacticPosition } from '../galactic-position-shLkm4Qg.js';
+
+/**
+ * Nebula catalogue types and proximity queries — the **data-free** core of the
+ * nebulae feature.
+ *
+ * Elite Dangerous models thousands of nebulae. This module holds the
+ * {@link Nebula} record shape and the pure functions that search a catalogue
+ * ({@link nearestNebulae}, {@link nebulaeWithin}, {@link getNebulaByName}); the
+ * catalogues themselves live in sibling modules, one per class, so you only bundle
+ * the ones you ask for:
+ *
+ * Sizes are each module's import graph once your bundler has minified it — the
+ * published package itself is not minified — before any transport compression; the
+ * gzipped figure is roughly a fifth of it.
+ *
+ * | Module | Export | Entries | Minified | Gzipped |
+ * | --- | --- | --- | --- | --- |
+ * | `./nebulae-real` | `REAL_NEBULAE` | 180 | 16.4 KiB | 5.3 KiB |
+ * | `./nebulae-procgen` | `PROCGEN_NEBULAE` | 166 | 16.4 KiB | 5.7 KiB |
+ * | `./nebulae-planetary` | `PLANETARY_NEBULAE` | 5489 | 399.3 KiB | 116.0 KiB |
+ * | `./nebulae-all` | `ALL_NEBULAE` | 5835 | 431.7 KiB | 126.5 KiB |
+ *
+ * Importing a query function from here costs nothing but the function: pass in
+ * whichever catalogue you imported. The catalogue argument is **required** — 94% of
+ * `ALL_NEBULAE` is planetary nebulae most apps never touch, so there is no default
+ * worth falling back to silently.
+ *
+ * Positions are galactic light-years with Sol at the origin — the same frame the
+ * journal, EDSM and Spansh use. Catalogue data originates from EDAstro; see
+ * [ATTRIBUTIONS.md](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/ATTRIBUTIONS.md)
+ * for credit and licence terms.
+ *
+ * @example
+ * ```ts
+ * import { nearestNebulae } from '@elite-dangerous-almanac/core/astro/nebulae';
+ * import { REAL_NEBULAE } from '@elite-dangerous-almanac/core/astro/nebulae-real';
+ *
+ * nearestNebulae({ x: 0, y: 0, z: 0 }, REAL_NEBULAE, 1)[0]?.name; // -> 'Pleiades'
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * How a nebula is classified by the source catalogue.
+ *
+ * - `real` — a catalogued real-world nebula or dark region the game models by name
+ *   (Horsehead Nebula, Barnard's Loop, Coalsack Dark Region, …).
+ * - `planetary` — a planetary nebula, catalogued at the procedurally-named system
+ *   it surrounds. By far the largest class.
+ * - `procgen` — a procedurally generated nebula, catalogued at a nearby system.
+ */
+type NebulaType = 'real' | 'planetary' | 'procgen';
+/**
+ * One catalogued nebula and where it sits in the galaxy.
+ *
+ * @remarks
+ * A nebula is a volume, but the catalogue records a single reference point — the
+ * position of {@link Nebula.system}, the system it is catalogued at. Distances
+ * computed from it are therefore "distance to the catalogued system", not distance
+ * to the nebula's edge.
+ */
+interface Nebula {
+    /**
+     * Display name, e.g. `"Witch Head Nebula"`. For procedurally-named nebulae this
+     * is usually the system name, sometimes with a community name appended in
+     * parentheses (`"Aemonz WZ-Y e6771 (Lazurite Nebula)"`).
+     */
+    readonly name: string;
+    /** The in-game system the nebula is catalogued at, e.g. `"Witch Head Sector IR-W c1-8"`. */
+    readonly system: string;
+    /** Galactic X of the catalogued system, in light-years (Sol at origin). */
+    readonly x: number;
+    /** Galactic Y of the catalogued system, in light-years (Sol at origin). */
+    readonly y: number;
+    /** Galactic Z of the catalogued system, in light-years (Sol at origin). */
+    readonly z: number;
+    /** Which class of nebula this is. */
+    readonly type: NebulaType;
+    /**
+     * Id of the galactic codex region the nebula sits in, 1–42.
+     *
+     * @remarks
+     * Resolve it to a name with `getCodexRegion` from `./codex-region` — that
+     * costs ~9 KB of region metadata rather than the ~267 KB lookup grid
+     * `findCodexRegionAt` needs.
+     */
+    readonly regionId: number;
+}
+/** A {@link Nebula} annotated with its distance from a queried point. */
+interface NebulaWithDistance extends Nebula {
+    /** Straight-line distance from the queried coordinates, in light-years. */
+    readonly distanceLy: number;
+}
+/**
+ * The nebulae closest to a point, nearest first.
+ *
+ * @param coords - The point to measure from, in light-years (Sol at origin). A
+ * `ProceduralSystem.position` value fits once you have narrowed it — it is
+ * `GalacticPosition | null`, and is `null` unless that system was built from an address
+ * *and* you supplied its coordinates, so null-check it first.
+ * @param nebulae - The catalogue to search — `REAL_NEBULAE`, `PLANETARY_NEBULAE`,
+ * `PROCGEN_NEBULAE`, `ALL_NEBULAE`, or any subset you have filtered yourself.
+ * @param count - How many to return. Defaults to `3`. Fractional values are truncated
+ * towards zero, values `<= 0` and `NaN` yield an empty array, and a count larger than
+ * the catalogue returns the whole catalogue.
+ * @returns Up to `count` nebulae sorted by ascending {@link NebulaWithDistance.distanceLy}.
+ * Ties keep catalogue order. The input array is not modified.
+ * @example
+ * ```ts
+ * import { nearestNebulae } from '@elite-dangerous-almanac/core/astro/nebulae';
+ * import { REAL_NEBULAE } from '@elite-dangerous-almanac/core/astro/nebulae-real';
+ *
+ * // The three real nebulae nearest Sol
+ * nearestNebulae({ x: 0, y: 0, z: 0 }, REAL_NEBULAE).map((n) => n.name);
+ * // -> [ 'Pleiades', 'R Cra', 'Lupus Dark Region B' ]  (nearest first)
+ *
+ * nearestNebulae({ x: 0, y: 0, z: 0 }, REAL_NEBULAE, 1)[0]?.distanceLy; // -> ≈383.31
+ * ```
+ */
+declare function nearestNebulae(coords: GalacticPosition, nebulae: readonly Nebula[], count?: number): NebulaWithDistance[];
+/**
+ * Every nebula within a radius of a point, nearest first.
+ *
+ * @param coords - The point to measure from, in light-years (Sol at origin).
+ * @param nebulae - The catalogue to search (see {@link nearestNebulae}).
+ * @param radiusLy - Search radius in light-years, inclusive of the boundary.
+ * Negative radii yield an empty array.
+ * @returns The matching nebulae sorted by ascending
+ * {@link NebulaWithDistance.distanceLy}. Ties keep catalogue order. The input array
+ * is not modified.
+ * @example
+ * ```ts
+ * import { nebulaeWithin } from '@elite-dangerous-almanac/core/astro/nebulae';
+ * import { REAL_NEBULAE } from '@elite-dangerous-almanac/core/astro/nebulae-real';
+ *
+ * // Real nebulae within 400 ly of Sol
+ * nebulaeWithin({ x: 0, y: 0, z: 0 }, REAL_NEBULAE, 400).map((n) => n.name);
+ * // -> [ 'Pleiades' ]
+ * ```
+ */
+declare function nebulaeWithin(coords: GalacticPosition, nebulae: readonly Nebula[], radiusLy: number): NebulaWithDistance[];
+/**
+ * Look up a nebula by name (case-insensitive).
+ *
+ * @param name - The nebula name as the catalogue spells it, e.g.
+ * `"Witch Head Nebula"`. Matching ignores case and surrounding whitespace on both the
+ * argument and the catalogue's own `name`, but is otherwise exact — including any
+ * parenthetical community name (`"Aemonz WZ-Y e6771 (Lazurite Nebula)"`), so pass the
+ * whole string. A record whose `name` is not a string never matches.
+ * @param nebulae - The catalogue to search (see {@link nearestNebulae}).
+ * @returns The matching {@link Nebula}, or `null` if the catalogue holds no nebula
+ * of that name. Only the catalogue you pass is searched — a real nebula will not
+ * be found in `PLANETARY_NEBULAE`.
+ * @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 { getNebulaByName } from '@elite-dangerous-almanac/core/astro/nebulae';
+ * import { REAL_NEBULAE } from '@elite-dangerous-almanac/core/astro/nebulae-real';
+ *
+ * getNebulaByName('witch head nebula', REAL_NEBULAE)?.system;
+ * // -> 'Witch Head Sector RY-R b4-0'
+ * ```
+ */
+declare function getNebulaByName(name: string, nebulae: readonly Nebula[]): Nebula | null;
+
+export { type Nebula, type NebulaType, type NebulaWithDistance, getNebulaByName, nearestNebulae, nebulaeWithin };

package/dist/astro/nebulae.js

@@ -0,0 +1 @@
+export{getNebulaByName,nearestNebulae,nebulaeWithin}from"../chunk-ZFT56QFR.js";                                                          //# sourceMappingURL=nebulae.js.map

package/dist/astro/nebulae.js.map

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

package/dist/astro/permit-locked-regions.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Whole permit-locked regions, kept separate from individually locked systems.
+ *
+ * Importing this leaf module costs only the 28 region names. `ProceduralSystem` uses it
+ * to preserve the library's fine-grained tree-shaking boundary.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The 28 permit-locked regions, sorted by name.
+ *
+ * @remarks
+ * Each entry is both a hand-authored region name and the whole-token prefix used
+ * by system names inside it. The array is frozen at runtime.
+ *
+ * @example
+ * ```ts
+ * import { PERMIT_LOCKED_REGIONS } from '@elite-dangerous-almanac/core/astro/permit-locked-regions';
+ *
+ * PERMIT_LOCKED_REGIONS.slice(0, 3); // -> [ 'Bleia1', 'Bleia2', 'Bleia3' ]
+ * ```
+ */
+declare const PERMIT_LOCKED_REGIONS: readonly string[];
+/**
+ * Whether a region is permit-locked, by its exact name.
+ *
+ * @param name - A hand-authored region name in any casing, with optional
+ * surrounding whitespace.
+ * @returns `true` when the exact region is permit-locked. A system name inside the
+ * region does not count as an exact region-name match.
+ * @throws {TypeError} If `name` is present and not a string. A nullish
+ * `name` is a miss, answered the way an unrecognised one is.
+ */
+declare function isPermitLockedRegionName(name: string): boolean;
+/**
+ * Find the permit-locked region prefix applying to a system name.
+ *
+ * @param systemName - A system name in any casing, with optional surrounding
+ * whitespace.
+ * @returns The canonically-cased region name, or `null` when no locked region
+ * prefix applies.
+ * @throws {TypeError} If `systemName` is present and not a string. A nullish
+ * `systemName` is a miss, answered the way an unrecognised one is.
+ * @example
+ * ```ts
+ * import { permitLockedRegionForSystemName } from '@elite-dangerous-almanac/core/astro/permit-locked-regions';
+ *
+ * permitLockedRegionForSystemName('Col 70 Sector AA-D b17-0');
+ * // -> 'Col 70 Sector'
+ * ```
+ */
+declare function permitLockedRegionForSystemName(systemName: string): string | null;
+
+export { PERMIT_LOCKED_REGIONS, isPermitLockedRegionName, permitLockedRegionForSystemName };

package/dist/astro/permit-locked-regions.js

@@ -0,0 +1 @@
+export{PERMIT_LOCKED_REGIONS,isPermitLockedRegionName,permitLockedRegionForSystemName}from"../chunk-VZXL5KBR.js";                                                          //# sourceMappingURL=permit-locked-regions.js.map

package/dist/astro/permit-locked-regions.js.map

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

package/dist/astro/permit-locked-systems.d.ts

@@ -0,0 +1,74 @@
+import { SystemAddressInput } from './system-address-input.js';
+
+/**
+ * Individually permit-locked systems, indexed independently from region locks.
+ *
+ * Import this leaf module when only exact system locks or journal addresses are
+ * needed; it does not load the permit-locked region catalogue.
+ *
+ * @packageDocumentation
+ */
+
+/** One individually permit-locked system. */
+interface PermitLockedSystem {
+    /** Canonically-cased system name, e.g. `"Shinrarta Dezhra"`. */
+    readonly name: string;
+    /**
+     * The system's 64-bit system address, as reported by the player journal's
+     * `SystemAddress` field.
+     *
+     * @remarks
+     * Most of these systems are hand-named rather than procedural, so their address
+     * cannot be computed from the name. It is recorded from Spansh/EDSM; see
+     * [`data/astro/SOURCES.md`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/data/astro/SOURCES.md).
+     */
+    readonly id64: bigint;
+}
+/**
+ * The 54 individually permit-locked systems, sorted by name.
+ *
+ * @remarks
+ * The array and every record are frozen at runtime. Region-locked systems are not
+ * listed here; see `PERMIT_LOCKED_REGIONS` in `./permit-locked-regions`.
+ *
+ * @example
+ * ```ts
+ * import { PERMIT_LOCKED_SYSTEMS } from '@elite-dangerous-almanac/core/astro/permit-locked-systems';
+ *
+ * PERMIT_LOCKED_SYSTEMS.find((system) => system.name === 'Sol')?.id64;
+ * // -> 10477373803n
+ * ```
+ */
+declare const PERMIT_LOCKED_SYSTEMS: readonly PermitLockedSystem[];
+/**
+ * Find an individually permit-locked system by exact name.
+ *
+ * @param name - A system name in any casing, with optional surrounding whitespace.
+ * @returns The frozen catalogue record, or `null` when the name is not individually
+ * permit-locked. Region prefixes are not checked.
+ * @throws {TypeError} If `name` is present and not a string. A nullish
+ * `name` is a miss, answered the way an unrecognised one is.
+ */
+declare function permitLockedSystemForName(name: string): PermitLockedSystem | null;
+/**
+ * Find an individually permit-locked system by its system address.
+ *
+ * @param address - A `bigint` from this library, a safe integer from a normally
+ * parsed journal event, or a decimal string from persisted JSON. Unsafe numbers,
+ * non-integers and malformed strings yield `null` rather than risking a rounded
+ * address comparison.
+ * @returns The frozen catalogue record, or `null` when the address is invalid or
+ * not individually permit-locked.
+ * @example
+ * ```ts
+ * import { permitLockedSystemForAddress } from '@elite-dangerous-almanac/core/astro/permit-locked-systems';
+ *
+ * declare const event: { SystemAddress: number }; // an `FSDJump` line, parsed
+ *
+ * permitLockedSystemForAddress(event.SystemAddress)?.name; // -> 'Sol'
+ * permitLockedSystemForAddress('10477373803')?.name;       // -> 'Sol'
+ * ```
+ */
+declare function permitLockedSystemForAddress(address: SystemAddressInput): PermitLockedSystem | null;
+
+export { PERMIT_LOCKED_SYSTEMS, type PermitLockedSystem, SystemAddressInput, permitLockedSystemForAddress, permitLockedSystemForName };

package/dist/astro/permit-locked-systems.js

@@ -0,0 +1 @@
+export{PERMIT_LOCKED_SYSTEMS,permitLockedSystemForAddress,permitLockedSystemForName}from"../chunk-WV5YM7H5.js";                                                                                       //# sourceMappingURL=permit-locked-systems.js.map

package/dist/astro/permit-locked-systems.js.map

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

package/dist/astro/permit-locks.d.ts

@@ -0,0 +1,130 @@
+export { PERMIT_LOCKED_SYSTEMS, PermitLockedSystem, permitLockedSystemForAddress, permitLockedSystemForName } from './permit-locked-systems.js';
+export { PERMIT_LOCKED_REGIONS, isPermitLockedRegionName, permitLockedRegionForSystemName } from './permit-locked-regions.js';
+export { SystemAddressInput } from './system-address-input.js';
+
+/**
+ * Permit-locked systems and regions — "can a commander jump here without a
+ * permit?", answered from a **system name** alone.
+ *
+ * A permit lock is not published in any game data file, journal event or API
+ * (even Sol, permit-locked since launch, reports no permit flag), so this is a
+ * hand-maintained community list. It has two halves:
+ *
+ * - {@link PERMIT_LOCKED_SYSTEMS} — 54 individually locked systems, each with its
+ *   name and `id64` (`Sol`, `Shinrarta Dezhra`, `Achenar`, …).
+ * - {@link PERMIT_LOCKED_REGIONS} — 28 whole regions whose permit covers every
+ *   system inside them (`Col 70 Sector`, `Bleia1`, `Cone Sector`, …), matched by
+ *   name prefix, because the game names every system in a region after it.
+ *
+ * {@link permitLockForSystemName} checks both and tells you which one hit.
+ *
+ * @remarks
+ * Permit state lives in the two tree-shakeable leaf modules
+ * `./permit-locked-systems` and `./permit-locked-regions`; this module composes and
+ * re-exports both. `HandAuthoredRegion` carries no permit flag, so
+ * {@link isPermitLockedRegionName} is how the geometric route asks the question:
+ *
+ * ```ts
+ * const region = findHandAuthoredRegionAt(position);
+ * const needsPermit = region !== null && isPermitLockedRegionName(region.name);
+ * ```
+ *
+ * **Prefer that route when you have coordinates.** Resolving a region from a
+ * *position* is exact; matching the start of a name is a best-effort fallback for
+ * when a name is all you have (a journal line, a user's search box, a route plan).
+ *
+ * **Scope.** Systems only. Permit-locked *bodies* inside otherwise-open systems
+ * (Diso 5 C, Lave 2, Sol's Moon and Triton) are deliberately excluded — a
+ * system-level flag would be wrong for them.
+ *
+ * Sourced from the community "Elite Dangerous Permit Database" spreadsheet via
+ * canonn-signals; see [ATTRIBUTIONS.md](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/ATTRIBUTIONS.md) for credit and licence terms.
+ *
+ * @example
+ * ```ts
+ * declare const event: { SystemAddress: number }; // an `FSDJump` line, parsed
+ *
+ * import {
+ *     permitLockForSystemName,
+ *     permitLockedSystemForAddress,
+ * } from '@elite-dangerous-almanac/core/astro/permit-locks';
+ *
+ * permitLockForSystemName('Shinrarta Dezhra');          // -> { kind: 'system', ... }
+ * permitLockForSystemName('Col 70 Sector AA-D b17-0');  // -> { kind: 'region', name: 'Col 70 Sector' }
+ * permitLockedSystemForAddress(event.SystemAddress);    // accepts a journal number
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Why a system needs a permit: because that exact system is locked
+ * (`kind: 'system'`), or because it lies inside a locked region
+ * (`kind: 'region'`).
+ */
+type PermitLock = {
+    /** The system itself is on the permit-locked list. */
+    readonly kind: 'system';
+    /** The canonically-cased system name, e.g. `"Shinrarta Dezhra"`. */
+    readonly name: string;
+    /** That system's 64-bit system address. */
+    readonly id64: bigint;
+} | {
+    /** The system lies inside a permit-locked region. */
+    readonly kind: 'region';
+    /**
+     * The region's name, e.g. `"Col 70 Sector"`. Also a `HAND_AUTHORED_REGIONS`
+     * entry name, so you can look its spheres up by it (see
+     * `./hand-authored-regions`). No `id64` — a region is not a system.
+     */
+    readonly name: string;
+};
+/**
+ * The permit lock that applies to a system name, or `null` if it is open space.
+ *
+ * Checks the exact-name list first, then the region names, so a system that is
+ * both individually listed and inside a locked region reports `kind: 'system'`.
+ *
+ * @param name - A system name in any casing, with or without surrounding
+ * whitespace, e.g. `"  shinrarta dezhra "`. An empty or blank string yields `null`.
+ * @returns A {@link PermitLock} naming the system or region responsible, or `null`
+ * when nothing on the list matches.
+ * @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 { permitLockForSystemName } from '@elite-dangerous-almanac/core/astro/permit-locks';
+ *
+ * permitLockForSystemName('sol');
+ * // -> { kind: 'system', name: 'Sol', id64: 10477373803n }
+ *
+ * permitLockForSystemName('Bleia1 DL-Y f26');
+ * // -> { kind: 'region', name: 'Bleia1' }
+ *
+ * permitLockForSystemName('Col 285 Sector IX-T d3-31'); // -> null (the bubble's Col 285)
+ * ```
+ */
+declare function permitLockForSystemName(name: string): PermitLock | null;
+/**
+ * Whether a system needs a permit — either its own, or its region's.
+ *
+ * A convenience wrapper over {@link permitLockForSystemName} for when you only need
+ * the yes/no. Use that function instead when you want to tell the commander *which*
+ * permit they are missing.
+ *
+ * @param name - A system name in any casing, e.g. `"vega"`.
+ * @returns `true` if the name matches a permit-locked system or region.
+ * @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 { isPermitLockedSystemName } from '@elite-dangerous-almanac/core/astro/permit-locks';
+ *
+ * isPermitLockedSystemName('Sirius');                 // -> true  (system lock)
+ * isPermitLockedSystemName('Cone Sector GW-W c1-5');  // -> true  (region lock)
+ * isPermitLockedSystemName('Colonia');                // -> false
+ * ```
+ */
+declare function isPermitLockedSystemName(name: string): boolean;
+
+export { type PermitLock, isPermitLockedSystemName, permitLockForSystemName };

package/dist/astro/permit-locks.js

@@ -0,0 +1 @@
+export{isPermitLockedSystemName,permitLockForSystemName}from"../chunk-MFV4VZFP.js";export{PERMIT_LOCKED_SYSTEMS,permitLockedSystemForAddress,permitLockedSystemForName}from"../chunk-WV5YM7H5.js";export{PERMIT_LOCKED_REGIONS,isPermitLockedRegionName,permitLockedRegionForSystemName}from"../chunk-VZXL5KBR.js";                                                                                       //# sourceMappingURL=permit-locks.js.map

package/dist/astro/permit-locks.js.map

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