@interstellar-tools/equations 0.1.2 → 0.2.0

package/dist/__tests__/specific-mechanical-energy.spec.js

@@ -0,0 +1,81 @@
+import assert from 'node:assert/strict';
+import test, { describe } from 'node:test';
+import { specificMechanicalEnergy } from '../specific-mechanical-energy';
+import { absClose, relClose } from './helpers';
+describe('specificMechanicalEnergy', () => {
+    test('circular orbit: ε = -μ/(2r) when v = sqrt(μ/r)', () => {
+        const mu = 3.986004418e14; // m^3/s^2 (Earth GM)
+        const r = 6378e3 + 400e3; // m (LEO-ish)
+        const v = Math.sqrt(mu / r); // m/s
+        const eps = specificMechanicalEnergy(v, r, mu);
+        const expected = -mu / (2 * r);
+        relClose(eps, expected, 1e-12);
+    });
+    test('parabolic case: v = sqrt(2μ/r) → ε ≈ 0', () => {
+        const mu = 3.986004418e14; // m^3/s^2
+        const r = 7000e3; // m
+        const v = Math.sqrt((2 * mu) / r);
+        const eps = specificMechanicalEnergy(v, r, mu);
+        // Use absolute tolerance because the expected value is 0
+        absClose(eps, 0, 1e-9);
+    });
+    test('hyperbolic case: v slightly above escape → ε > 0', () => {
+        const mu = 3.986004418e14;
+        const r = 7000e3;
+        const v_escape = Math.sqrt((2 * mu) / r);
+        const v = 1.01 * v_escape;
+        const eps = specificMechanicalEnergy(v, r, mu);
+        assert.ok(eps > 0, 'ε should be positive for hyperbolic cases');
+    });
+    test('elliptic case: v below circular → ε < 0', () => {
+        const mu = 3.986004418e14;
+        const r = 7000e3;
+        const v_circ = Math.sqrt(mu / r);
+        const v = 0.95 * v_circ;
+        const eps = specificMechanicalEnergy(v, r, mu);
+        assert.ok(eps < 0, 'ε should be negative for bound (elliptic) cases');
+    });
+    test('semi-major axis identity: ε = -μ/(2a) (using vis-viva for v)', () => {
+        const mu = 3.986004418e14;
+        const a = 10000e3; // m (semi-major axis)
+        const r = 8000e3; // m (some point on the ellipse)
+        const v = Math.sqrt(mu * (2 / r - 1 / a)); // vis-viva
+        const eps = specificMechanicalEnergy(v, r, mu);
+        const expected = -mu / (2 * a);
+        relClose(eps, expected, 1e-12);
+    });
+    test('monotonic in speed: increasing v increases ε (same r, μ)', () => {
+        const mu = 3.986004418e14;
+        const r = 8000e3;
+        const v1 = 7000;
+        const v2 = 7500;
+        const eps1 = specificMechanicalEnergy(v1, r, mu);
+        const eps2 = specificMechanicalEnergy(v2, r, mu);
+        assert.ok(eps2 > eps1);
+    });
+    test('increases with radius for fixed v: larger r → larger ε (less negative)', () => {
+        const mu = 3.986004418e14;
+        const v = 7500;
+        const r1 = 7000e3;
+        const r2 = 8000e3;
+        const eps1 = specificMechanicalEnergy(v, r1, mu);
+        const eps2 = specificMechanicalEnergy(v, r2, mu);
+        assert.ok(eps2 > eps1);
+    });
+    test('throws on invalid inputs', () => {
+        const mu = 3.986004418e14;
+        const r = 7000e3;
+        const v = 7500;
+        // v invalid
+        assert.throws(() => specificMechanicalEnergy(Number.NaN, r, mu), /non-negative/);
+        assert.throws(() => specificMechanicalEnergy(-1, r, mu), /non-negative/);
+        // r invalid
+        assert.throws(() => specificMechanicalEnergy(v, Number.NaN, mu), /positive/);
+        assert.throws(() => specificMechanicalEnergy(v, 0, mu), /positive/);
+        assert.throws(() => specificMechanicalEnergy(v, -1, mu), /positive/);
+        // mu invalid
+        assert.throws(() => specificMechanicalEnergy(v, r, Number.NaN), /non-negative/);
+        assert.throws(() => specificMechanicalEnergy(v, r, -1), /non-negative/);
+    });
+});
+//# sourceMappingURL=specific-mechanical-energy.spec.js.map

package/dist/__tests__/specific-mechanical-energy.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specific-mechanical-energy.spec.js","sourceRoot":"","sources":["../../src/__tests__/specific-mechanical-energy.spec.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/vis-viva-speed.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=vis-viva-speed.spec.d.ts.map

package/dist/__tests__/vis-viva-speed.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vis-viva-speed.spec.d.ts","sourceRoot":"","sources":["../../src/__tests__/vis-viva-speed.spec.ts"],"names":[],"mappings":""}

package/dist/__tests__/vis-viva-speed.spec.js

@@ -0,0 +1,80 @@
+import assert from 'node:assert/strict';
+import test, { describe } from 'node:test';
+import { absClose, relClose } from './helpers';
+import { visVivaSpeed } from '../vis-viva-speed';
+describe('visVivaSpeed', () => {
+    test('circular orbit: a = r → v = sqrt(μ/r)', () => {
+        const mu = 3.986004418e14; // m^3/s^2 (Earth GM)
+        const r = 6778e3; // m (LEO-ish)
+        const a = r;
+        const v = visVivaSpeed(r, a, mu);
+        const expected = Math.sqrt(mu / r);
+        relClose(v, expected, 1e-12);
+    });
+    test('parabolic trajectory: a = Infinity → v = sqrt(2μ/r)', () => {
+        const mu = 3.986004418e14;
+        const r = 7000e3;
+        const v = visVivaSpeed(r, Infinity, mu);
+        const expected = Math.sqrt((2 * mu) / r);
+        relClose(v, expected, 1e-12);
+    });
+    test('hyperbolic case: a < 0 uses same formula and yields valid speed', () => {
+        const mu = 3.986004418e14;
+        const r = 10000e3;
+        const a = -15000e3; // negative semi-major axis
+        const v = visVivaSpeed(r, a, mu);
+        const expected = Math.sqrt(mu * (2 / r - 1 / a));
+        relClose(v, expected, 1e-12);
+    });
+    test('radicand zero boundary: choose a such that 2/r - 1/a = 0 → v = 0', () => {
+        const mu = 3.986004418e14;
+        const r = 8000e3;
+        const a = r / 2; // 1/a = 2/r
+        const v = visVivaSpeed(r, a, mu);
+        absClose(v, 0, 1e-12);
+    });
+    test('tiny negative radicand (within tolerance) is clamped to v ≈ 0', () => {
+        const mu = 3.986004418e14;
+        const r = 8000e3;
+        // Function's tolerance: tol = |1e-14 * mu / r|
+        const tol = Math.abs((1e-14 * mu) / r);
+        const delta = tol / (2 * mu); // makes radicand = μ*(2/r - 1/a) = -tol/2
+        // Choose 1/a = 2/r + delta  → a = 1 / (2/r + delta)
+        const a = 1 / (2 / r + delta);
+        const v = visVivaSpeed(r, a, mu);
+        absClose(v, 0, 1e-12);
+    });
+    test('significantly negative radicand throws (physically impossible state)', () => {
+        const mu = 3.986004418e14;
+        const r = 8000e3;
+        const a = r / 4; // 1/a = 4/r -> 2/r - 1/a = -2/r (negative)
+        assert.throws(() => visVivaSpeed(r, a, mu), /Invalid state: μ\*\(2\/r - 1\/a\) < 0/);
+    });
+    test('monotonic with radius for fixed a, μ: larger r → smaller v (ellipse domain)', () => {
+        const mu = 3.986004418e14;
+        const a = 10000e3; // ellipse: r must be < 2a
+        const r1 = 8000e3;
+        const r2 = 15000e3; // < 2a = 20000 km
+        const v1 = visVivaSpeed(r1, a, mu);
+        const v2 = visVivaSpeed(r2, a, mu);
+        assert.ok(v1 > v2, 'speed should decrease as radius increases (for fixed a)');
+    });
+    test('input validation: r<=0, mu<0/NaN, a non-finite (except +Infinity), a=0', () => {
+        const mu = 3.986004418e14;
+        const r = 7000e3;
+        const a = r;
+        // r invalid
+        assert.throws(() => visVivaSpeed(0, a, mu), /positive/);
+        assert.throws(() => visVivaSpeed(-1, a, mu), /positive/);
+        assert.throws(() => visVivaSpeed(Number.NaN, a, mu), /finite/);
+        // mu invalid
+        assert.throws(() => visVivaSpeed(r, a, -1), /non-negative/);
+        assert.throws(() => visVivaSpeed(r, a, Number.NaN), /finite/);
+        // a invalid (non-finite other than +Infinity)
+        assert.throws(() => visVivaSpeed(r, Number.NaN, mu), /finite/);
+        assert.throws(() => visVivaSpeed(r, Number.NEGATIVE_INFINITY, mu), /finite/);
+        // a = 0 invalid
+        assert.throws(() => visVivaSpeed(r, 0, mu), /non-zero/);
+    });
+});
+//# sourceMappingURL=vis-viva-speed.spec.js.map

package/dist/__tests__/vis-viva-speed.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vis-viva-speed.spec.js","sourceRoot":"","sources":["../../src/__tests__/vis-viva-speed.spec.ts"],"names":[],"mappings":"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"}

package/dist/compute-mean-anomaly.d.ts

@@ -21,7 +21,7 @@ import type { CelestialBodyType, Radians, TemporalInterface } from '@interstella
  * @param {TemporalInterface} timeStep - The time step over which to compute the change.
  * @returns {Radians} The computed mean anomaly in radians.
  *
- * @throws {RangeError} If the body's eccentricity is outside the range $0 \leq e < 1$.
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError | RangeError} If the body's eccentricity is outside the range $0 \leq e < 1$.
  *
  * @example
  * ```ts

package/dist/compute-mean-anomaly.js

@@ -36,7 +36,7 @@ const areEqual = (a, b, epsilon = EPSILON) => {
  * @param {TemporalInterface} timeStep - The time step over which to compute the change.
  * @returns {Radians} The computed mean anomaly in radians.
  *
- * @throws {RangeError} If the body's eccentricity is outside the range $0 \leq e < 1$.
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError | RangeError} If the body's eccentricity is outside the range $0 \leq e < 1$.
  *
  * @example
  * ```ts

package/dist/eccentric-to-true-anomaly.d.ts

@@ -27,7 +27,7 @@ import { Radians } from '@interstellar-tools/types';
  * @param {number} e - Orbital eccentricity ($0 \leq e < 1$).
  * @returns {Radians} True anomaly ($V$) in radians.
  *
- * @throws {RangeError} If **eccentricity** is out of the range $0 \leq e \leq 1$.
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError | RangeError} If **eccentricity** is out of the range $0 \leq e \leq 1$.
  *
  * @example
  * ```ts

package/dist/eccentric-to-true-anomaly.js

@@ -26,7 +26,7 @@
  * @param {number} e - Orbital eccentricity ($0 \leq e < 1$).
  * @returns {Radians} True anomaly ($V$) in radians.
  *
- * @throws {RangeError} If **eccentricity** is out of the range $0 \leq e \leq 1$.
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError | RangeError} If **eccentricity** is out of the range $0 \leq e \leq 1$.
  *
  * @example
  * ```ts

package/dist/gravitational-parameter.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Two-body **gravitational parameter** ($ \mu $).
+ *
+ * **Definition**
+ *
+ * $$
+ * \mu = G\,(M + m)
+ * $$
+ *
+ * **Common approximation, when** ($ M \gg m $)
+ *
+ * $$
+ * \mu \approx G\,M
+ * $$
+ *
+ * **Units**
+ * - Inputs: masses in **kg**, ( $ G $ ) in **m³·kg⁻¹·s⁻²** (defaults to `G_SI`).
+ * - Output: ($ \mu $) in **m³/s²**.
+ *
+ * ::: tip
+ *
+ * - Use `m = 0` (default) for the standard published ($ \mu $) of a central body.
+ * - When modelling a binary with comparable masses, pass both `M` and `m`.
+ *
+ * :::
+ *
+ * @param {number} M Mass of the primary body (kg).
+ * @param {number} m Mass of the secondary body (kg). Defaults to `0`.
+ * @param {number} [G] Gravitational constant. Defaults to `G_SI`.
+ * @returns {number} Gravitational parameter ($ \mu $) in m³/s².
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If `M` is non-finite or negative.
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If `m` is non-finite or negative.
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If `G` is non-finite or negative.
+ *
+ * @example
+ * ```ts
+ * // Standard gravitational parameter for Earth (approximate: m ~ 0)
+ * const muEarth = gravitationalParameter(5.97219e24); // ≈ 3.986004e14 m^3/s^2
+ *
+ * // Earth + 1000 kg satellite: practically identical to GM
+ * const muExact = gravitationalParameter(5.97219e24, 1000);
+ *
+ * // Earth–Moon system (two-body μ)
+ * const muEarthMoon = gravitationalParameter(5.97219e24, 7.342e22);
+ * ```
+ * @category Dynamics
+ */
+export declare const gravitationalParameter: (M: number, m?: number, G?: number) => number;
+//# sourceMappingURL=gravitational-parameter.d.ts.map

package/dist/gravitational-parameter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gravitational-parameter.d.ts","sourceRoot":"","sources":["../src/gravitational-parameter.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,sBAAsB,GACjC,GAAG,MAAM,EACT,IAAG,MAAU,EACb,IAAG,MAAa,KACf,MAcF,CAAC"}

package/dist/gravitational-parameter.js

@@ -0,0 +1,61 @@
+import { G_SI } from '@interstellar-tools/constants';
+/**
+ * Two-body **gravitational parameter** ($ \mu $).
+ *
+ * **Definition**
+ *
+ * $$
+ * \mu = G\,(M + m)
+ * $$
+ *
+ * **Common approximation, when** ($ M \gg m $)
+ *
+ * $$
+ * \mu \approx G\,M
+ * $$
+ *
+ * **Units**
+ * - Inputs: masses in **kg**, ( $ G $ ) in **m³·kg⁻¹·s⁻²** (defaults to `G_SI`).
+ * - Output: ($ \mu $) in **m³/s²**.
+ *
+ * ::: tip
+ *
+ * - Use `m = 0` (default) for the standard published ($ \mu $) of a central body.
+ * - When modelling a binary with comparable masses, pass both `M` and `m`.
+ *
+ * :::
+ *
+ * @param {number} M Mass of the primary body (kg).
+ * @param {number} m Mass of the secondary body (kg). Defaults to `0`.
+ * @param {number} [G] Gravitational constant. Defaults to `G_SI`.
+ * @returns {number} Gravitational parameter ($ \mu $) in m³/s².
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If `M` is non-finite or negative.
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If `m` is non-finite or negative.
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If `G` is non-finite or negative.
+ *
+ * @example
+ * ```ts
+ * // Standard gravitational parameter for Earth (approximate: m ~ 0)
+ * const muEarth = gravitationalParameter(5.97219e24); // ≈ 3.986004e14 m^3/s^2
+ *
+ * // Earth + 1000 kg satellite: practically identical to GM
+ * const muExact = gravitationalParameter(5.97219e24, 1000);
+ *
+ * // Earth–Moon system (two-body μ)
+ * const muEarthMoon = gravitationalParameter(5.97219e24, 7.342e22);
+ * ```
+ * @category Dynamics
+ */
+export const gravitationalParameter = (M, m = 0, G = G_SI) => {
+    if (!Number.isFinite(M) || M < 0) {
+        throw new Error('M must be a finite, positive number (kg).');
+    }
+    if (!Number.isFinite(m) || m < 0) {
+        throw new Error('m must be a finite, positive number (kg).');
+    }
+    if (!Number.isFinite(G) || G <= 0) {
+        throw new Error('G must be a finite, positive number (m^3·kg^-1·s^-2).');
+    }
+    return G * (M + m);
+};
+//# sourceMappingURL=gravitational-parameter.js.map

package/dist/gravitational-parameter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gravitational-parameter.js","sourceRoot":"","sources":["../src/gravitational-parameter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,+BAA+B,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,CAAS,EACT,IAAY,CAAC,EACb,IAAY,IAAI,EACR,EAAE;IACV,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AACrB,CAAC,CAAC"}

package/dist/index.d.ts

@@ -13,4 +13,9 @@ export * from './solve-kepler-newton-raphson';
 export * from './solve-kepler';
 export * from './true-anomaly-to-mean-anomaly';
 export * from './wrap-angle';
+export * from './gravitational-parameter';
+export * from './law-of-gravitation';
+export * from './vis-viva-speed';
+export * from './kepler-period';
+export * from './specific-mechanical-energy';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,iBAAiB,CAAC;AAEhC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,6BAA6B,CAAC;AAE5C,cAAc,0BAA0B,CAAC;AAEzC,cAAc,kCAAkC,CAAC;AAEjD,cAAc,+BAA+B,CAAC;AAE9C,cAAc,gBAAgB,CAAC;AAE/B,cAAc,gCAAgC,CAAC;AAE/C,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,iBAAiB,CAAC;AAEhC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,6BAA6B,CAAC;AAE5C,cAAc,0BAA0B,CAAC;AAEzC,cAAc,kCAAkC,CAAC;AAEjD,cAAc,+BAA+B,CAAC;AAE9C,cAAc,gBAAgB,CAAC;AAE/B,cAAc,gCAAgC,CAAC;AAE/C,cAAc,cAAc,CAAC;AAE7B,cAAc,2BAA2B,CAAC;AAE1C,cAAc,sBAAsB,CAAC;AAErC,cAAc,kBAAkB,CAAC;AAEjC,cAAc,iBAAiB,CAAC;AAEhC,cAAc,8BAA8B,CAAC"}

package/dist/index.js

@@ -13,4 +13,9 @@ export * from './solve-kepler-newton-raphson';
 export * from './solve-kepler';
 export * from './true-anomaly-to-mean-anomaly';
 export * from './wrap-angle';
+export * from './gravitational-parameter';
+export * from './law-of-gravitation';
+export * from './vis-viva-speed';
+export * from './kepler-period';
+export * from './specific-mechanical-energy';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,iBAAiB,CAAC;AAEhC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,6BAA6B,CAAC;AAE5C,cAAc,0BAA0B,CAAC;AAEzC,cAAc,kCAAkC,CAAC;AAEjD,cAAc,+BAA+B,CAAC;AAE9C,cAAc,gBAAgB,CAAC;AAE/B,cAAc,gCAAgC,CAAC;AAE/C,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,iBAAiB,CAAC;AAEhC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,6BAA6B,CAAC;AAE5C,cAAc,0BAA0B,CAAC;AAEzC,cAAc,kCAAkC,CAAC;AAEjD,cAAc,+BAA+B,CAAC;AAE9C,cAAc,gBAAgB,CAAC;AAE/B,cAAc,gCAAgC,CAAC;AAE/C,cAAc,cAAc,CAAC;AAE7B,cAAc,2BAA2B,CAAC;AAE1C,cAAc,sBAAsB,CAAC;AAErC,cAAc,kBAAkB,CAAC;AAEjC,cAAc,iBAAiB,CAAC;AAEhC,cAAc,8BAA8B,CAAC"}

package/dist/kepler-period.d.ts

@@ -0,0 +1,45 @@
+/**
+ * **Kepler's 3rd law** - orbital period ($ T $) from semi-major axis ($ a $) and gravitational parameter ($ \mu $).
+ *
+ * **Definition**
+ *
+ * $$
+ * T = 2\pi \sqrt{\frac{a^3}{\mu}}
+ * $$
+ *
+ * **Units**
+ * - Inputs: ($ a $) in **meters (m)**, ($ \mu $) in **m³/s²**.
+ * - Output: ($ T $) in **seconds (s)**.
+ *
+ * ::: info
+ *
+ * - Valid for **Keplerian (two-body) bound orbits** with ($ a>0 $) (ellipses). Not defined for parabolic/hyperbolic trajectories.
+ * - ($ \mu $) is the **standard gravitational parameter** of the central body (e.g., Earth ($ \approx 3.986004418\times10^{14}\ \text{m}^3/\text{s}^2 $)).
+ *
+ * :::
+ *
+ * @param {number} a  Semi-major axis (m), must be finite and **> 0**.
+ * @param {number} mu Gravitational parameter (m³/s²), must be finite and **> 0**.
+ * @returns {number} Orbital period ($ T $) (s).
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If inputs are non-finite or out of domain.
+ *
+ * @example
+ * ```ts
+ * // GEO: a ≈ 42,164 km → T ≈ 86,164 s (one sidereal day)
+ * const a = 42164e3;                 // m
+ * const muEarth = 3.986004418e14;    // m^3/s^2
+ * const T = keplerPeriod(a, muEarth); // ≈ 86164 s
+ * ```
+ *
+ * @example
+ * ```ts
+ * // LEO-ish circular: a ≈ Earth radius + 400 km
+ * const a = 6378e3 + 400e3;          // m
+ * const muEarth = 3.986004418e14;    // m^3/s^2
+ * const T = keplerPeriod(a, muEarth); // ≈ 5550 s (~92.5 min)
+ * ```
+ *
+ * @category Dynamics
+ */
+export declare const keplerPeriod: (a: number, mu: number) => number;
+//# sourceMappingURL=kepler-period.d.ts.map

package/dist/kepler-period.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kepler-period.d.ts","sourceRoot":"","sources":["../src/kepler-period.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,MAAM,EAAE,IAAI,MAAM,KAAG,MAYpD,CAAC"}

package/dist/kepler-period.js

@@ -0,0 +1,54 @@
+/**
+ * **Kepler's 3rd law** - orbital period ($ T $) from semi-major axis ($ a $) and gravitational parameter ($ \mu $).
+ *
+ * **Definition**
+ *
+ * $$
+ * T = 2\pi \sqrt{\frac{a^3}{\mu}}
+ * $$
+ *
+ * **Units**
+ * - Inputs: ($ a $) in **meters (m)**, ($ \mu $) in **m³/s²**.
+ * - Output: ($ T $) in **seconds (s)**.
+ *
+ * ::: info
+ *
+ * - Valid for **Keplerian (two-body) bound orbits** with ($ a>0 $) (ellipses). Not defined for parabolic/hyperbolic trajectories.
+ * - ($ \mu $) is the **standard gravitational parameter** of the central body (e.g., Earth ($ \approx 3.986004418\times10^{14}\ \text{m}^3/\text{s}^2 $)).
+ *
+ * :::
+ *
+ * @param {number} a  Semi-major axis (m), must be finite and **> 0**.
+ * @param {number} mu Gravitational parameter (m³/s²), must be finite and **> 0**.
+ * @returns {number} Orbital period ($ T $) (s).
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If inputs are non-finite or out of domain.
+ *
+ * @example
+ * ```ts
+ * // GEO: a ≈ 42,164 km → T ≈ 86,164 s (one sidereal day)
+ * const a = 42164e3;                 // m
+ * const muEarth = 3.986004418e14;    // m^3/s^2
+ * const T = keplerPeriod(a, muEarth); // ≈ 86164 s
+ * ```
+ *
+ * @example
+ * ```ts
+ * // LEO-ish circular: a ≈ Earth radius + 400 km
+ * const a = 6378e3 + 400e3;          // m
+ * const muEarth = 3.986004418e14;    // m^3/s^2
+ * const T = keplerPeriod(a, muEarth); // ≈ 5550 s (~92.5 min)
+ * ```
+ *
+ * @category Dynamics
+ */
+export const keplerPeriod = (a, mu) => {
+    if (!Number.isFinite(a) || a <= 0) {
+        throw new Error('a must be a finite, positive number (meters).');
+    }
+    if (!Number.isFinite(mu) || mu <= 0) {
+        throw new Error('mu must be a finite, positive number (m^3/s^2).');
+    }
+    const a3 = a * a * a; // a^3
+    return 2 * Math.PI * Math.sqrt(a3 / mu);
+};
+//# sourceMappingURL=kepler-period.js.map

package/dist/kepler-period.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kepler-period.js","sourceRoot":"","sources":["../src/kepler-period.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAS,EAAE,EAAU,EAAU,EAAE;IAC5D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM;IAE5B,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;AAC1C,CAAC,CAAC"}