@interstellar-tools/types 0.1.1 → 0.2.0

package/README.md

@@ -5,14 +5,6 @@
 - [Node.js](https://nodejs.org/) version 22.9.0 or higher
 - npm version 11.5.1 or higher
 
-::: code-group
-
 ```shell [npm]
 npm i --save @interstellar-tools/types
 ```
-
-```shell [yarn]
-yarn add @interstellar-tools/types
-```
-
-:::

package/dist/distance.d.ts

@@ -11,10 +11,10 @@ import { ValueInterface } from './numeric';
  * - Uses **meters** as the [SI](https://en.wikipedia.org/wiki/International_System_of_Units) base; larger units have conventional scientific definitions.
  *
  * ## Conventions
- * - **`au`** — Astronomical Unit (IAU 2012 B2): **149 597 870 700 m** (lowercase `au` is the IAU symbol).
- * - **`ly` family** — Light-year based on the **Julian year**:
+ * - **`au`** - Astronomical Unit (IAU 2012 B2): **149 597 870 700 m** (lowercase `au` is the IAU symbol).
+ * - **`ly` family** - Light-year based on the **Julian year**:
  *   `1 ly = c × 365.25 d = 9 460 730 472 580 800 m` (with `kly = 10³ ly`, `Mly = 10⁶ ly`, `Gly = 10⁹ ly`).
- * - **`pc` family** — Parsec defined from the arcsecond parallax:
+ * - **`pc` family** - Parsec defined from the arcsecond parallax:
  *   `1 pc = au × (648000 / π) ≈ 3.085677581×10¹⁶ m` (`kpc/Mpc/Gpc` are ×10³/×10⁶/×10⁹).
  *
  * ## Members
@@ -33,7 +33,7 @@ import { ValueInterface } from './numeric';
  * const d3: Distance = { value: 8, unit: 'kpc' };
  * ```
  *
- * @see https://www.iau.org/static/resolutions/IAU2012_English.pdf (IAU 2012 B2 — definition of the astronomical unit)
+ * @see https://www.iau.org/static/resolutions/IAU2012_English.pdf (IAU 2012 B2 - definition of the astronomical unit)
  * @see https://en.wikipedia.org/wiki/Light-year (Light-year based on Julian year)
  * @see https://en.wikipedia.org/wiki/Parsec (Parsec definition & meter equivalence)
  * @category Distance
@@ -72,7 +72,7 @@ export type DistanceUnitType = 'm' | 'km' | 'au' | 'ly' | 'kly' | 'Mly' | 'Gly'
  * ```
  *
  * @see DistanceUnitType for the canonical symbol set.
- * @see https://www.iau.org/static/resolutions/IAU2012_English.pdf (IAU 2012 B2 — astronomical unit, symbol "au")
+ * @see https://www.iau.org/static/resolutions/IAU2012_English.pdf (IAU 2012 B2 - astronomical unit, symbol "au")
  * @see https://en.wikipedia.org/wiki/Light-year (Light-year; Julian-year convention)
  * @see https://en.wikipedia.org/wiki/Parsec (Parsec definition)
  * @category Distance

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export * from './distance';
 export * from './temporal';
 export * from './numeric';
+export * from './math';
+export * from './physics';
 export * from './celestial-bodies';
 //# 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,cAAc,YAAY,CAAC;AAE3B,cAAc,YAAY,CAAC;AAE3B,cAAc,WAAW,CAAC;AAE1B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAE3B,cAAc,YAAY,CAAC;AAE3B,cAAc,WAAW,CAAC;AAE1B,cAAc,QAAQ,CAAC;AAEvB,cAAc,WAAW,CAAC;AAE1B,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,5 +1,7 @@
 export * from './distance';
 export * from './temporal';
 export * from './numeric';
+export * from './math';
+export * from './physics';
 export * from './celestial-bodies';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAE3B,cAAc,YAAY,CAAC;AAE3B,cAAc,WAAW,CAAC;AAE1B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAE3B,cAAc,YAAY,CAAC;AAE3B,cAAc,WAAW,CAAC;AAE1B,cAAc,QAAQ,CAAC;AAEvB,cAAc,WAAW,CAAC;AAE1B,cAAc,oBAAoB,CAAC"}

package/dist/math.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A read-only 3D vector tuple `[x, y, z]`.
+ *
+ * Immutable container for Cartesian coordinates or any 3-component quantity
+ * (e.g., position in meters, velocity in m/s, acceleration in m/s²).
+ * The `readonly` modifier prevents in-place mutation.
+ *
+ * @example
+ * ```ts
+ * // Declaring a point/vector
+ * const p: Vector3DTupleType = [1, 2, 3];
+ * // p[0] = 9; // Error: cannot assign to read-only element
+ *
+ * // Using with functions
+ * const dot = (a: Vector3DTupleType, b: Vector3DTupleType) => a[0]*b[0] + a[1]*b[1] + a[2]*b[2];
+ * const v = [4, 5, 6] as const; // const assertion yields a readonly tuple
+ * console.log(dot(p, v)); // 32
+ * ```
+ *
+ * @see https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types
+ * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html#const-assertions
+ */
+export type Vector3DTupleType = readonly [x: number, y: number, z: number];
+//# sourceMappingURL=math.d.ts.map

package/dist/math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../src/math.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC"}

package/dist/math.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=math.js.map

package/dist/math.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.js","sourceRoot":"","sources":["../src/math.ts"],"names":[],"mappings":""}

package/dist/physics.d.ts

@@ -0,0 +1,57 @@
+import { Vector3DTupleType } from './math';
+/**
+ * Result of a Newtonian gravitational force computation between two point masses.
+ *
+ * **Units:** SI (newtons for force). `vector` and `direction` point **from body 1 toward body 2**.
+ *
+ * **Relevant equations (invariants & definitions)**
+ *
+ * $$
+ * \mathbf F = \langle F_x, F_y, F_z \rangle,\qquad
+ * \|\mathbf F\| = \sqrt{F_x^2 + F_y^2 + F_z^2}
+ * $$
+ *
+ * $$
+ * \hat{\mathbf r}=\frac{\mathbf r_2-\mathbf r_1}{\|\mathbf r_2-\mathbf r_1\|},\qquad
+ * \|\hat{\mathbf r}\|=1
+ * $$
+ *
+ * $$
+ * \mathbf F = \|\mathbf F\|\,\hat{\mathbf r}
+ * $$
+ *
+ * And, for context (how the magnitude is obtained in Newtonian gravity):
+ *
+ * $$
+ * \|\mathbf F\| = G\,\frac{m_1 m_2}{\|\mathbf r_2-\mathbf r_1\|^2}
+ * $$
+ *
+ * **Mappings to fields**
+ * - `vector`  ↔ \( \mathbf F \)
+ * - `magnitude` ↔ \( \|\mathbf F\| \)
+ * - `direction` ↔ \( \hat{\mathbf r} \)
+ *
+ * @property vector     Force vector on body 1 due to body 2 (N).
+ * @property magnitude  Scalar magnitude of the force (N).
+ * @property direction  Unit direction from body 1 to body 2 (dimensionless).
+ *
+ * @example
+ * ```ts
+ * const res: ForceResultInterface = gravitationalForce(m1, m2, r1, r2);
+ * // Invariant checks:
+ * const [Fx, Fy, Fz] = res.vector;
+ * const magFromVec = Math.hypot(Fx, Fy, Fz);
+ * console.assert(Math.abs(magFromVec - res.magnitude) / res.magnitude < 1e-9);
+ * ```
+ *
+ * @see https://en.wikipedia.org/wiki/Newton%27s_law_of_universal_gravitation
+ */
+export interface ForceResultInterface {
+    /** Force vector on body 1 due to body 2 (newtons, N). */
+    readonly vector: Vector3DTupleType;
+    /** Magnitude (scalar) of the gravitational force (N). */
+    readonly magnitude: number;
+    /** Unit direction from body 1 to body 2 (dimensionless). */
+    readonly direction: Vector3DTupleType;
+}
+//# sourceMappingURL=physics.d.ts.map

package/dist/physics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"physics.d.ts","sourceRoot":"","sources":["../src/physics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;CACvC"}

package/dist/physics.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=physics.js.map

package/dist/physics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"physics.js","sourceRoot":"","sources":["../src/physics.ts"],"names":[],"mappings":""}

package/dist/temporal.d.ts

@@ -28,7 +28,7 @@ import { ValueInterface } from './numeric';
  *
  * :::
  *
- * @see https://www.bipm.org/en/publications/si-brochure  ([SI](https://en.wikipedia.org/wiki/International_System_of_Units) Brochure — second & day)
+ * @see https://www.bipm.org/en/publications/si-brochure  ([SI](https://en.wikipedia.org/wiki/International_System_of_Units) Brochure - second & day)
  * @see https://en.wikipedia.org/wiki/Julian_year_(astronomy) (Julian year used for `yr`)
  * @category Temporal
  */
@@ -54,7 +54,7 @@ export type TemporalUnitType = 's' | 'ms' | 'μs' | 'ns' | 'ps' | 'fs' | 'as' |
  * 2) Normalize to `TemporalUnitType`.
  * 3) Use only canonical units for arithmetic, storage, and serialization.
  *
- * @see https://www.bipm.org/en/publications/si-brochure ([SI](https://en.wikipedia.org/wiki/International_System_of_Units) Brochure — second & day)
+ * @see https://www.bipm.org/en/publications/si-brochure ([SI](https://en.wikipedia.org/wiki/International_System_of_Units) Brochure - second & day)
  * @see https://en.wikipedia.org/wiki/Julian_year_(astronomy) (Julian year used for `yr`/`kyr`/`Myr`/`Gyr`)
  * @see https://en.wikipedia.org/wiki/Year#SI_multiples (Usage of `ka`/`Ma`/`Ga` vs `kyr`/`Myr`/`Gyr`)
  * @category Temporal

package/package.json

@@ -1,9 +1,82 @@
 {
   "name": "@interstellar-tools/types",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "types",
   "keywords": [
-    "types"
+    "types",
+    "interstellar",
+    "tools",
+    "near",
+    "earth",
+    "objects",
+    "planets",
+    "orbit",
+    "rotation",
+    "stars",
+    "star",
+    "sun",
+    "planet",
+    "earth",
+    "moon",
+    "mercury",
+    "venus",
+    "mars",
+    "tellus",
+    "gaia",
+    "jupiter",
+    "saturn",
+    "neptune",
+    "pluto",
+    "dwarf",
+    "planets",
+    "trajectory",
+    "asteroids",
+    "comets",
+    "collision",
+    "satellite",
+    "satellites",
+    "sky map",
+    "nasa",
+    "jpl",
+    "esa",
+    "astrodynamics",
+    "orbital-mechanics",
+    "celestial-mechanics",
+    "two-body",
+    "n-body",
+    "gravity",
+    "newtonian-gravity",
+    "newtons-law-of-gravitation",
+    "gravitational-constant",
+    "G_SI",
+    "standard-gravitational-parameter",
+    "gravitational-parameter",
+    "mu",
+    "gravitational-force",
+    "gravitational-acceleration",
+    "specific-mechanical-energy",
+    "vis-viva",
+    "kepler-period",
+    "keplers-third-law",
+    "orbital-speed",
+    "trajectory",
+    "orbit",
+    "satellite",
+    "simulation",
+    "numerics",
+    "si-units",
+    "vector3",
+    "vec3",
+    "vector-math",
+    "typescript",
+    "javascript",
+    "interstellar-tools",
+    "spaceflight",
+    "space-dynamics",
+    "heliocentric",
+    "leo",
+    "geo",
+    "earth-sun"
   ],
   "homepage": "https://phun-ky.net/projects/interstellar-tools",
   "bugs": {