@pawells/math-extended 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (195) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +319 -0
  3. package/build/angles.d.ts +31 -0
  4. package/build/angles.d.ts.map +1 -0
  5. package/build/angles.js +85 -0
  6. package/build/angles.js.map +1 -0
  7. package/build/angles.spec.d.ts +2 -0
  8. package/build/angles.spec.d.ts.map +1 -0
  9. package/build/angles.spec.js +147 -0
  10. package/build/angles.spec.js.map +1 -0
  11. package/build/clamp.d.ts +17 -0
  12. package/build/clamp.d.ts.map +1 -0
  13. package/build/clamp.js +19 -0
  14. package/build/clamp.js.map +1 -0
  15. package/build/clamp.spec.d.ts +2 -0
  16. package/build/clamp.spec.d.ts.map +1 -0
  17. package/build/clamp.spec.js +19 -0
  18. package/build/clamp.spec.js.map +1 -0
  19. package/build/documentation-validation.spec.d.ts +11 -0
  20. package/build/documentation-validation.spec.d.ts.map +1 -0
  21. package/build/documentation-validation.spec.js +401 -0
  22. package/build/documentation-validation.spec.js.map +1 -0
  23. package/build/index.d.ts +8 -0
  24. package/build/index.d.ts.map +1 -0
  25. package/build/index.js +8 -0
  26. package/build/index.js.map +1 -0
  27. package/build/interpolation.d.ts +175 -0
  28. package/build/interpolation.d.ts.map +1 -0
  29. package/build/interpolation.js +369 -0
  30. package/build/interpolation.js.map +1 -0
  31. package/build/interpolation.spec.d.ts +2 -0
  32. package/build/interpolation.spec.d.ts.map +1 -0
  33. package/build/interpolation.spec.js +480 -0
  34. package/build/interpolation.spec.js.map +1 -0
  35. package/build/matrices/arithmetic.d.ts +411 -0
  36. package/build/matrices/arithmetic.d.ts.map +1 -0
  37. package/build/matrices/arithmetic.js +954 -0
  38. package/build/matrices/arithmetic.js.map +1 -0
  39. package/build/matrices/arithmetic.spec.d.ts +2 -0
  40. package/build/matrices/arithmetic.spec.d.ts.map +1 -0
  41. package/build/matrices/arithmetic.spec.js +915 -0
  42. package/build/matrices/arithmetic.spec.js.map +1 -0
  43. package/build/matrices/asserts.d.ts +306 -0
  44. package/build/matrices/asserts.d.ts.map +1 -0
  45. package/build/matrices/asserts.js +396 -0
  46. package/build/matrices/asserts.js.map +1 -0
  47. package/build/matrices/asserts.spec.d.ts +2 -0
  48. package/build/matrices/asserts.spec.d.ts.map +1 -0
  49. package/build/matrices/asserts.spec.js +565 -0
  50. package/build/matrices/asserts.spec.js.map +1 -0
  51. package/build/matrices/core.d.ts +168 -0
  52. package/build/matrices/core.d.ts.map +1 -0
  53. package/build/matrices/core.js +457 -0
  54. package/build/matrices/core.js.map +1 -0
  55. package/build/matrices/core.spec.d.ts +2 -0
  56. package/build/matrices/core.spec.d.ts.map +1 -0
  57. package/build/matrices/core.spec.js +634 -0
  58. package/build/matrices/core.spec.js.map +1 -0
  59. package/build/matrices/decompositions.d.ts +326 -0
  60. package/build/matrices/decompositions.d.ts.map +1 -0
  61. package/build/matrices/decompositions.js +816 -0
  62. package/build/matrices/decompositions.js.map +1 -0
  63. package/build/matrices/decompositions.spec.d.ts +2 -0
  64. package/build/matrices/decompositions.spec.d.ts.map +1 -0
  65. package/build/matrices/decompositions.spec.js +195 -0
  66. package/build/matrices/decompositions.spec.js.map +1 -0
  67. package/build/matrices/index.d.ts +9 -0
  68. package/build/matrices/index.d.ts.map +1 -0
  69. package/build/matrices/index.js +9 -0
  70. package/build/matrices/index.js.map +1 -0
  71. package/build/matrices/linear-algebra.d.ts +64 -0
  72. package/build/matrices/linear-algebra.d.ts.map +1 -0
  73. package/build/matrices/linear-algebra.js +253 -0
  74. package/build/matrices/linear-algebra.js.map +1 -0
  75. package/build/matrices/linear-algebra.spec.d.ts +2 -0
  76. package/build/matrices/linear-algebra.spec.d.ts.map +1 -0
  77. package/build/matrices/linear-algebra.spec.js +355 -0
  78. package/build/matrices/linear-algebra.spec.js.map +1 -0
  79. package/build/matrices/normalization.d.ts +62 -0
  80. package/build/matrices/normalization.d.ts.map +1 -0
  81. package/build/matrices/normalization.js +167 -0
  82. package/build/matrices/normalization.js.map +1 -0
  83. package/build/matrices/normalization.spec.d.ts +2 -0
  84. package/build/matrices/normalization.spec.d.ts.map +1 -0
  85. package/build/matrices/normalization.spec.js +335 -0
  86. package/build/matrices/normalization.spec.js.map +1 -0
  87. package/build/matrices/transformations.d.ts +484 -0
  88. package/build/matrices/transformations.d.ts.map +1 -0
  89. package/build/matrices/transformations.js +592 -0
  90. package/build/matrices/transformations.js.map +1 -0
  91. package/build/matrices/transformations.spec.d.ts +2 -0
  92. package/build/matrices/transformations.spec.d.ts.map +1 -0
  93. package/build/matrices/transformations.spec.js +755 -0
  94. package/build/matrices/transformations.spec.js.map +1 -0
  95. package/build/matrices/types.d.ts +134 -0
  96. package/build/matrices/types.d.ts.map +1 -0
  97. package/build/matrices/types.js +6 -0
  98. package/build/matrices/types.js.map +1 -0
  99. package/build/quaternions/asserts.d.ts +77 -0
  100. package/build/quaternions/asserts.d.ts.map +1 -0
  101. package/build/quaternions/asserts.js +175 -0
  102. package/build/quaternions/asserts.js.map +1 -0
  103. package/build/quaternions/asserts.spec.d.ts +2 -0
  104. package/build/quaternions/asserts.spec.d.ts.map +1 -0
  105. package/build/quaternions/asserts.spec.js +320 -0
  106. package/build/quaternions/asserts.spec.js.map +1 -0
  107. package/build/quaternions/conversions.d.ts +73 -0
  108. package/build/quaternions/conversions.d.ts.map +1 -0
  109. package/build/quaternions/conversions.js +179 -0
  110. package/build/quaternions/conversions.js.map +1 -0
  111. package/build/quaternions/conversions.spec.d.ts +2 -0
  112. package/build/quaternions/conversions.spec.d.ts.map +1 -0
  113. package/build/quaternions/conversions.spec.js +344 -0
  114. package/build/quaternions/conversions.spec.js.map +1 -0
  115. package/build/quaternions/core.d.ts +203 -0
  116. package/build/quaternions/core.d.ts.map +1 -0
  117. package/build/quaternions/core.js +374 -0
  118. package/build/quaternions/core.js.map +1 -0
  119. package/build/quaternions/core.spec.d.ts +2 -0
  120. package/build/quaternions/core.spec.d.ts.map +1 -0
  121. package/build/quaternions/core.spec.js +294 -0
  122. package/build/quaternions/core.spec.js.map +1 -0
  123. package/build/quaternions/index.d.ts +7 -0
  124. package/build/quaternions/index.d.ts.map +1 -0
  125. package/build/quaternions/index.js +7 -0
  126. package/build/quaternions/index.js.map +1 -0
  127. package/build/quaternions/interpolation.d.ts +54 -0
  128. package/build/quaternions/interpolation.d.ts.map +1 -0
  129. package/build/quaternions/interpolation.js +201 -0
  130. package/build/quaternions/interpolation.js.map +1 -0
  131. package/build/quaternions/interpolation.spec.d.ts +2 -0
  132. package/build/quaternions/interpolation.spec.d.ts.map +1 -0
  133. package/build/quaternions/interpolation.spec.js +64 -0
  134. package/build/quaternions/interpolation.spec.js.map +1 -0
  135. package/build/quaternions/predefined.d.ts +36 -0
  136. package/build/quaternions/predefined.d.ts.map +1 -0
  137. package/build/quaternions/predefined.js +42 -0
  138. package/build/quaternions/predefined.js.map +1 -0
  139. package/build/quaternions/predefined.spec.d.ts +2 -0
  140. package/build/quaternions/predefined.spec.d.ts.map +1 -0
  141. package/build/quaternions/predefined.spec.js +35 -0
  142. package/build/quaternions/predefined.spec.js.map +1 -0
  143. package/build/quaternions/types.d.ts +55 -0
  144. package/build/quaternions/types.d.ts.map +1 -0
  145. package/build/quaternions/types.js +7 -0
  146. package/build/quaternions/types.js.map +1 -0
  147. package/build/random.d.ts +66 -0
  148. package/build/random.d.ts.map +1 -0
  149. package/build/random.js +115 -0
  150. package/build/random.js.map +1 -0
  151. package/build/random.spec.d.ts +2 -0
  152. package/build/random.spec.d.ts.map +1 -0
  153. package/build/random.spec.js +267 -0
  154. package/build/random.spec.js.map +1 -0
  155. package/build/vectors/asserts.d.ts +182 -0
  156. package/build/vectors/asserts.d.ts.map +1 -0
  157. package/build/vectors/asserts.js +285 -0
  158. package/build/vectors/asserts.js.map +1 -0
  159. package/build/vectors/asserts.spec.d.ts +2 -0
  160. package/build/vectors/asserts.spec.d.ts.map +1 -0
  161. package/build/vectors/asserts.spec.js +260 -0
  162. package/build/vectors/asserts.spec.js.map +1 -0
  163. package/build/vectors/core.d.ts +507 -0
  164. package/build/vectors/core.d.ts.map +1 -0
  165. package/build/vectors/core.js +825 -0
  166. package/build/vectors/core.js.map +1 -0
  167. package/build/vectors/core.spec.d.ts +2 -0
  168. package/build/vectors/core.spec.d.ts.map +1 -0
  169. package/build/vectors/core.spec.js +343 -0
  170. package/build/vectors/core.spec.js.map +1 -0
  171. package/build/vectors/index.d.ts +6 -0
  172. package/build/vectors/index.d.ts.map +1 -0
  173. package/build/vectors/index.js +6 -0
  174. package/build/vectors/index.js.map +1 -0
  175. package/build/vectors/interpolation.d.ts +404 -0
  176. package/build/vectors/interpolation.d.ts.map +1 -0
  177. package/build/vectors/interpolation.js +585 -0
  178. package/build/vectors/interpolation.js.map +1 -0
  179. package/build/vectors/interpolation.spec.d.ts +2 -0
  180. package/build/vectors/interpolation.spec.d.ts.map +1 -0
  181. package/build/vectors/interpolation.spec.js +378 -0
  182. package/build/vectors/interpolation.spec.js.map +1 -0
  183. package/build/vectors/predefined.d.ts +191 -0
  184. package/build/vectors/predefined.d.ts.map +1 -0
  185. package/build/vectors/predefined.js +191 -0
  186. package/build/vectors/predefined.js.map +1 -0
  187. package/build/vectors/predefined.spec.d.ts +2 -0
  188. package/build/vectors/predefined.spec.d.ts.map +1 -0
  189. package/build/vectors/predefined.spec.js +333 -0
  190. package/build/vectors/predefined.spec.js.map +1 -0
  191. package/build/vectors/types.d.ts +62 -0
  192. package/build/vectors/types.d.ts.map +1 -0
  193. package/build/vectors/types.js +6 -0
  194. package/build/vectors/types.js.map +1 -0
  195. package/package.json +75 -0
@@ -0,0 +1,507 @@
1
+ /**
2
+ * Core vector mathematics operations for linear algebra and geometric calculations.
3
+ * Provides a comprehensive set of vector operations with type safety and error checking.
4
+ */
5
+ import { TAnyVector, TVectorResult, TVector, TVector2, TVector3 } from './types.js';
6
+ /**
7
+ * Creates a deep copy of a vector.
8
+ * Essential for avoiding mutations when performing operations that should preserve the original vector.
9
+ *
10
+ * @template T - The vector type extending TVector
11
+ * @param vector - The vector to clone
12
+ * @returns A new vector with identical components
13
+ *
14
+ * @example
15
+ * const original = [1, 2, 3];
16
+ * const copy = VectorClone(original);
17
+ * copy[0] = 10; // original remains unchanged
18
+ */
19
+ export declare function VectorClone<T extends TAnyVector>(vector: T): TVectorResult<T>;
20
+ /**
21
+ * Compares two vectors for equality with optional tolerance for floating-point precision.
22
+ * Useful for comparing vectors that may have slight numerical differences due to calculations.
23
+ *
24
+ * @template T - The vector type extending TVector
25
+ * @param a - First vector to compare
26
+ * @param b - Second vector to compare
27
+ * @param tolerance - Maximum allowed difference between components (default: 0 for exact equality)
28
+ * @returns True if vectors are equal within tolerance, false otherwise
29
+ *
30
+ * @example
31
+ * const a = [1.0001, 2.0001];
32
+ * const b = [1.0002, 2.0002];
33
+ * const exactlyEqual = VectorEquals(a, b); // false
34
+ * const approximatelyEqual = VectorEquals(a, b, 0.001); // true
35
+ */
36
+ export declare function VectorEquals<T extends TAnyVector>(a: T, b: T, tolerance?: number): boolean;
37
+ /**
38
+ * Converts a vector to a human-readable string representation.
39
+ * Useful for debugging, logging, and displaying vector values.
40
+ *
41
+ * @param vector - The vector to convert to string
42
+ * @param style - Output format: 'parens' for (x, y, z) or 'brackets' for [x, y, z]
43
+ * @returns String representation of the vector
44
+ *
45
+ * @example
46
+ * const vec = [1, 2, 3];
47
+ * const parens = VectorToString(vec, 'parens'); // "(1, 2, 3)"
48
+ * const brackets = VectorToString(vec, 'brackets'); // "[1, 2, 3]"
49
+ */
50
+ export declare function VectorToString(vector: TVector, style?: 'parens' | 'brackets'): string;
51
+ /**
52
+ * Performs component-wise addition of two vectors.
53
+ * Fundamental operation for vector arithmetic, physics simulations, and geometric transformations.
54
+ *
55
+ * @template T - The vector type extending TVector
56
+ * @param a - First vector (augend)
57
+ * @param b - Second vector (addend)
58
+ * @returns New vector where each component is the sum of corresponding components
59
+ *
60
+ * @example
61
+ * const position = [10, 20, 30];
62
+ * const velocity = [1, -2, 0.5];
63
+ * const newPosition = VectorAdd(position, velocity); // [11, 18, 30.5]
64
+ */
65
+ export declare function VectorAdd<T extends TAnyVector>(a: T, b: T): TVectorResult<T>;
66
+ /**
67
+ * Performs component-wise subtraction of two vectors.
68
+ * Essential for calculating displacement, relative positions, and vector differences.
69
+ *
70
+ * @template T - The vector type extending TVector
71
+ * @param a - First vector (minuend)
72
+ * @param b - Second vector (subtrahend)
73
+ * @returns New vector where each component is the difference of corresponding components
74
+ *
75
+ * @example
76
+ * const target = [100, 50, 0];
77
+ * const current = [80, 30, 0];
78
+ * const direction = VectorSubtract(target, current); // [20, 20, 0]
79
+ */
80
+ export declare function VectorSubtract<T extends TAnyVector>(a: T, b: T): TVectorResult<T>;
81
+ /**
82
+ * Multiplies a vector by a scalar or performs component-wise multiplication with another vector.
83
+ * Scalar multiplication scales the vector magnitude; component-wise multiplication is useful for scaling factors.
84
+ *
85
+ * @template T - The vector type extending TVector
86
+ * @param a - Vector to multiply
87
+ * @param b - Scalar number or vector for component-wise multiplication
88
+ * @returns New vector with multiplied components
89
+ *
90
+ * @example
91
+ * const velocity = [10, 5, 0];
92
+ * const scaled = VectorMultiply(velocity, 2); // [20, 10, 0] - scalar multiplication
93
+ * const factors = [1, -1, 0.5];
94
+ * const componentWise = VectorMultiply(velocity, factors); // [10, -5, 0] - component-wise
95
+ */
96
+ export declare function VectorMultiply<T extends TAnyVector>(a: T, b: T | number): TVectorResult<T>;
97
+ /**
98
+ * Calculates the Euclidean distance between two vectors.
99
+ * Fundamental for spatial calculations, collision detection, and proximity measurements.
100
+ *
101
+ * @param a - First vector
102
+ * @param b - Second vector
103
+ * @returns The straight-line distance between the two points represented by the vectors
104
+ *
105
+ * @example
106
+ * const pointA = [0, 0, 0];
107
+ * const pointB = [3, 4, 0];
108
+ * const distance = VectorDistance(pointA, pointB); // 5.0 (3-4-5 triangle)
109
+ */
110
+ export declare function VectorDistance(a: TVector, b: TVector): number;
111
+ /**
112
+ * Calculates the squared distance between two vectors.
113
+ * More efficient than VectorDistance when only relative distances matter,
114
+ * as it avoids the expensive square root operation.
115
+ *
116
+ * @param a - First vector
117
+ * @param b - Second vector
118
+ * @returns The squared distance between vectors
119
+ *
120
+ * @example
121
+ * const pointA = [1, 1];
122
+ * const pointB = [4, 5];
123
+ * const distSq = VectorDistanceSquared(pointA, pointB); // 25 (faster than distance comparison)
124
+ */
125
+ export declare function VectorDistanceSquared(a: TVector, b: TVector): number;
126
+ /**
127
+ * Calculates the dot product (scalar product) of two vectors.
128
+ * Fundamental operation for projections, angles, and determining vector relationships.
129
+ * Returns positive for acute angles, zero for perpendicular vectors, negative for obtuse angles.
130
+ *
131
+ * @param a - First vector
132
+ * @param b - Second vector
133
+ * @returns The dot product (scalar value)
134
+ *
135
+ * @example
136
+ * const forward = [0, 0, 1];
137
+ * const direction = [0, 0, 2];
138
+ * const dot = VectorDot(forward, direction); // 2 (same direction)
139
+ *
140
+ * const perpendicular = [1, 0, 0];
141
+ * const dotPerp = VectorDot(forward, perpendicular); // 0 (perpendicular)
142
+ */
143
+ export declare function VectorDot(a: TVector, b: TVector): number;
144
+ /**
145
+ * Normalizes a vector to unit length (magnitude of 1).
146
+ * Essential for direction vectors, surface normals, and unit calculations.
147
+ * Preserves direction while standardizing magnitude.
148
+ *
149
+ * @template T - The vector type extending TVector
150
+ * @param a - Vector to normalize
151
+ * @returns Unit vector in the same direction
152
+ * @throws {VectorError} If the vector is zero or has infinite magnitude
153
+ *
154
+ * @example
155
+ * const vector = [3, 4, 0];
156
+ * const normalized = VectorNormalize(vector); // [0.6, 0.8, 0] (magnitude = 1)
157
+ *
158
+ * const direction = [10, 0, 0];
159
+ * const unitDirection = VectorNormalize(direction); // [1, 0, 0]
160
+ */
161
+ export declare function VectorNormalize<T extends TAnyVector>(a: T): TVectorResult<T>;
162
+ /**
163
+ * Calculates the magnitude (length) of a vector.
164
+ * Fundamental for distance calculations, normalization, and vector analysis.
165
+ *
166
+ * @param a - Vector to measure
167
+ * @returns The magnitude (length) of the vector
168
+ *
169
+ * @example
170
+ * const velocity = [3, 4, 0];
171
+ * const speed = VectorMagnitude(velocity); // 5.0
172
+ *
173
+ * const unitVector = [1, 0, 0];
174
+ * const unitLength = VectorMagnitude(unitVector); // 1.0
175
+ */
176
+ export declare function VectorMagnitude(a: TVector): number;
177
+ /**
178
+ * Returns a vector with the absolute value of each component.
179
+ * Useful for distance calculations, bounding box calculations, and ensuring positive values.
180
+ *
181
+ * @template T - The vector type extending TVector
182
+ * @param a - Vector to process
183
+ * @returns New vector with absolute values of all components
184
+ *
185
+ * @example
186
+ * const vector = [-3, 4, -2];
187
+ * const absolute = VectorAbs(vector); // [3, 4, 2]
188
+ *
189
+ * const mixed = [1.5, -2.7, 0];
190
+ * const absValues = VectorAbs(mixed); // [1.5, 2.7, 0]
191
+ */
192
+ export declare function VectorAbs<T extends TAnyVector>(a: T): TVectorResult<T>;
193
+ /**
194
+ * Checks if a vector is a zero vector (all components are zero).
195
+ * Important for validating input vectors and avoiding division by zero in calculations.
196
+ *
197
+ * @param vector - Vector to check
198
+ * @returns True if all components are zero, false otherwise
199
+ *
200
+ * @example
201
+ * const zero = [0, 0, 0];
202
+ * const isZero = VectorIsZero(zero); // true
203
+ *
204
+ * const notZero = [0, 0.001, 0];
205
+ * const isNotZero = VectorIsZero(notZero); // false
206
+ */
207
+ export declare function VectorIsZero(vector: TVector): boolean;
208
+ /**
209
+ * Calculates the angle between two vectors in radians.
210
+ * Essential for determining angular relationships, rotations, and orientations.
211
+ * Always returns a positive angle between 0 and π radians.
212
+ *
213
+ * @param a - First vector
214
+ * @param b - Second vector
215
+ * @returns Angle between vectors in radians (0 to π)
216
+ * @throws {VectorError} If either vector is zero
217
+ *
218
+ * @example
219
+ * const right = [1, 0, 0];
220
+ * const up = [0, 1, 0];
221
+ * const angle = VectorAngle(right, up); // π/2 (90 degrees)
222
+ *
223
+ * const forward = [0, 0, 1];
224
+ * const backward = [0, 0, -1];
225
+ * const oppositeAngle = VectorAngle(forward, backward); // π (180 degrees)
226
+ */
227
+ export declare function VectorAngle(a: TVector, b: TVector): number;
228
+ /**
229
+ * Rotates a 2D vector by the specified angle in radians.
230
+ * Essential for 2D transformations, sprite rotations, and directional calculations.
231
+ *
232
+ * @param vector - 2D vector to rotate
233
+ * @param radians - Rotation angle in radians (positive = counterclockwise)
234
+ * @returns New rotated 2D vector
235
+ *
236
+ * @example
237
+ * const right = [1, 0];
238
+ * const rotated90 = Vector2Rotate(right, Math.PI / 2); // [0, 1] (up)
239
+ * const rotated180 = Vector2Rotate(right, Math.PI); // [-1, 0] (left)
240
+ */
241
+ export declare function Vector2Rotate(vector: TVector2, radians: number): TVector2;
242
+ /**
243
+ * Creates a 2D unit vector from an angle in radians.
244
+ * Useful for creating directional vectors from angular measurements.
245
+ *
246
+ * @param radians - Angle in radians (0 = right, π/2 = up)
247
+ * @returns Unit vector pointing in the specified direction
248
+ *
249
+ * @example
250
+ * const right = Vector2FromAngle(0); // [1, 0]
251
+ * const up = Vector2FromAngle(Math.PI / 2); // [0, 1]
252
+ * const diagonal = Vector2FromAngle(Math.PI / 4); // [0.707, 0.707]
253
+ */
254
+ export declare function Vector2FromAngle(radians: number): TVector2;
255
+ /**
256
+ * Calculates the 2D cross product (returns a scalar).
257
+ * In 2D, the cross product represents the signed area of the parallelogram formed by the vectors.
258
+ * Useful for determining relative orientation and winding order.
259
+ *
260
+ * @param a - First 2D vector
261
+ * @param b - Second 2D vector
262
+ * @returns Scalar cross product (positive = counterclockwise, negative = clockwise)
263
+ *
264
+ * @example
265
+ * const right = [1, 0];
266
+ * const up = [0, 1];
267
+ * const cross = Vector2Cross(right, up); // 1 (counterclockwise)
268
+ * const crossReverse = Vector2Cross(up, right); // -1 (clockwise)
269
+ */
270
+ export declare function Vector2Cross(a: TVector2, b: TVector2): number;
271
+ /**
272
+ * Calculates the 3D rejection of vector a from vector b.
273
+ * Returns the component of vector a that is perpendicular to vector b.
274
+ * Useful for separating parallel and perpendicular components.
275
+ *
276
+ * @param a - Vector to reject from
277
+ * @param b - Vector to reject onto
278
+ * @returns Component of a perpendicular to b
279
+ * @throws {VectorError} If vector b is zero
280
+ *
281
+ * @example
282
+ * const force = [5, 3, 0];
283
+ * const surface = [1, 0, 0];
284
+ * const perpendicular = Vector3Reject(force, surface); // [0, 3, 0]
285
+ */
286
+ export declare function Vector3Reject(a: TVector3, b: TVector3): TVector3;
287
+ /**
288
+ * Projects vector a onto vector b.
289
+ * Returns the component of vector a that lies parallel to vector b.
290
+ * Essential for shadow calculations, force decomposition, and geometric projections.
291
+ *
292
+ * @template T - The vector type extending TVector
293
+ * @param a - Vector to project
294
+ * @param b - Vector to project onto
295
+ * @returns Component of a parallel to b
296
+ * @throws {VectorError} If vector b is zero
297
+ *
298
+ * @example
299
+ * const force = [5, 3, 0];
300
+ * const surface = [1, 0, 0];
301
+ * const parallel = VectorProject(force, surface); // [5, 0, 0]
302
+ */
303
+ export declare function VectorProject<T extends TAnyVector>(a: T, b: T): TVectorResult<T>;
304
+ /**
305
+ * Reflects an incident vector across a 3D normal (specialized version).
306
+ * This is a specialized version of VectorReflect for 3D vectors.
307
+ * Automatically normalizes the normal vector for consistent results.
308
+ *
309
+ * @param incident - The incoming vector to reflect
310
+ * @param normal - The surface normal (will be normalized automatically)
311
+ * @returns The reflected vector
312
+ * @throws {VectorError} If the normal is a zero vector
313
+ *
314
+ * @example
315
+ * const incoming = [1, -1, 0];
316
+ * const normal = [0, 1, 0]; // surface normal (upward)
317
+ * const reflected = Vector3Reflect(incoming, normal); // [1, 1, 0]
318
+ */
319
+ export declare function Vector3Reflect(incident: TVector3, normal: TVector3): TVector3;
320
+ /**
321
+ * Calculates the 3D cross product of two vectors.
322
+ * Returns a vector perpendicular to both input vectors.
323
+ * Essential for surface normals, torque calculations, and 3D rotations.
324
+ *
325
+ * @param a - First 3D vector
326
+ * @param b - Second 3D vector
327
+ * @returns Vector perpendicular to both a and b (following right-hand rule)
328
+ *
329
+ * @example
330
+ * const right = [1, 0, 0];
331
+ * const forward = [0, 0, 1];
332
+ * const up = Vector3Cross(right, forward); // [0, 1, 0]
333
+ *
334
+ * const normal = Vector3Cross([1, 0, 0], [0, 1, 0]); // [0, 0, 1]
335
+ */
336
+ export declare function Vector3Cross(a: TVector3, b: TVector3): TVector3;
337
+ /**
338
+ * Calculates the magnitude of the 3D cross product.
339
+ * Equivalent to the area of the parallelogram formed by the two vectors.
340
+ * Useful for area calculations and determining vector orthogonality.
341
+ *
342
+ * @param a - First 3D vector
343
+ * @param b - Second 3D vector
344
+ * @returns Magnitude of the cross product
345
+ *
346
+ * @example
347
+ * const side1 = [3, 0, 0];
348
+ * const side2 = [0, 4, 0];
349
+ * const area = VectorCrossMagnitude(side1, side2); // 12 (area of rectangle)
350
+ */
351
+ export declare function VectorCrossMagnitude(a: TVector3, b: TVector3): number;
352
+ /**
353
+ * Calculates the scalar triple product of three 3D vectors.
354
+ * Returns the signed volume of the parallelepiped formed by the three vectors.
355
+ * Useful for determining orientation and volume calculations.
356
+ *
357
+ * @param a - First 3D vector
358
+ * @param b - Second 3D vector
359
+ * @param c - Third 3D vector
360
+ * @returns Signed volume (positive = right-handed orientation)
361
+ *
362
+ * @example
363
+ * const x = [1, 0, 0];
364
+ * const y = [0, 1, 0];
365
+ * const z = [0, 0, 1];
366
+ * const volume = Vector3ScalarTripleProduct(x, y, z); // 1 (unit cube)
367
+ */
368
+ export declare function Vector3ScalarTripleProduct(a: TVector3, b: TVector3, c: TVector3): number;
369
+ /**
370
+ * Calculates the vector triple product of three 3D vectors.
371
+ * Implements the formula: a × (b × c)
372
+ * Useful for advanced geometric calculations and physics simulations.
373
+ *
374
+ * @param a - First 3D vector
375
+ * @param b - Second 3D vector
376
+ * @param c - Third 3D vector
377
+ * @returns Vector result of a × (b × c)
378
+ *
379
+ * @example
380
+ * const a = [1, 0, 0];
381
+ * const b = [0, 1, 0];
382
+ * const c = [0, 0, 1];
383
+ * const result = Vector3TripleProduct(a, b, c); // [0, 0, 0]
384
+ */
385
+ export declare function Vector3TripleProduct(a: TVector3, b: TVector3, c: TVector3): TVector3;
386
+ /**
387
+ * Reflects a vector across a normal surface.
388
+ * Simulates perfect reflection like light bouncing off a mirror.
389
+ * The normal vector is automatically normalized for consistent results.
390
+ *
391
+ * @template T - The vector type extending TVector
392
+ * @param incident - The incoming vector to reflect
393
+ * @param normal - The surface normal vector
394
+ * @returns The reflected vector
395
+ *
396
+ * @example
397
+ * const incoming = [1, -1, 0];
398
+ * const wall = [0, 1, 0]; // vertical wall normal
399
+ * const bounced = VectorReflect(incoming, wall); // [1, 1, 0]
400
+ */
401
+ export declare function VectorReflect<T extends TAnyVector>(incident: T, normal: T): TVectorResult<T>;
402
+ /**
403
+ * Negates all components of a vector (multiplies by -1).
404
+ * Creates a vector pointing in the exact opposite direction.
405
+ * Handles special case of zero to avoid negative zero (-0).
406
+ *
407
+ * @template T - The vector type extending TVector
408
+ * @param a - Vector to negate
409
+ * @returns Vector with all components negated
410
+ *
411
+ * @example
412
+ * const forward = [0, 0, 1];
413
+ * const backward = VectorNegate(forward); // [0, 0, -1]
414
+ *
415
+ * const velocity = [5, -3, 2];
416
+ * const opposite = VectorNegate(velocity); // [-5, 3, -2]
417
+ */
418
+ export declare function VectorNegate<T extends TAnyVector>(a: T): TVectorResult<T>;
419
+ /**
420
+ * Divides a vector by a scalar or performs component-wise division with another vector.
421
+ * Scalar division scales the vector magnitude down; component-wise division is the inverse of component-wise multiplication.
422
+ *
423
+ * @template T - The vector type extending TVector
424
+ * @param a - Vector to divide (dividend)
425
+ * @param b - Scalar number or vector for component-wise division (divisor)
426
+ * @returns New vector with divided components
427
+ * @throws {VectorError} If any divisor component is zero
428
+ *
429
+ * @example
430
+ * const velocity = [20, 10, 0];
431
+ * const halved = VectorDivide(velocity, 2); // [10, 5, 0] - scalar division
432
+ * const factors = [2, 5, 1];
433
+ * const componentWise = VectorDivide(velocity, factors); // [10, 2, 0] - component-wise
434
+ */
435
+ export declare function VectorDivide<T extends TAnyVector>(a: T, b: T | number): TVectorResult<T>;
436
+ /**
437
+ * Clamps each component of a vector between the corresponding min and max values.
438
+ * Can accept scalar min/max (same bounds for all components) or vectors for per-component bounds.
439
+ * Mirrors the scalar `Clamp` function for vector operations.
440
+ *
441
+ * @template T - The vector type extending TVector
442
+ * @param a - Vector whose components are to be clamped
443
+ * @param min - Minimum value (scalar applied to all components, or vector for per-component bounds)
444
+ * @param max - Maximum value (scalar applied to all components, or vector for per-component bounds)
445
+ * @returns New vector with each component clamped between min and max
446
+ *
447
+ * @example
448
+ * const v = [5, -3, 12, 0];
449
+ * VectorClamp(v, 0, 10); // [5, 0, 10, 0] - scalar bounds
450
+ *
451
+ * const mins = [0, -5, 0, -1];
452
+ * const maxs = [10, 5, 8, 1];
453
+ * VectorClamp(v, mins, maxs); // [5, -3, 8, 0] - per-component bounds
454
+ */
455
+ export declare function VectorClamp<T extends TAnyVector>(a: T, min: T | number, max: T | number): TVectorResult<T>;
456
+ /**
457
+ * Limits the magnitude of a vector to a maximum value.
458
+ * If the vector's magnitude exceeds the limit, scales it down proportionally.
459
+ * Preserves direction while constraining magnitude.
460
+ *
461
+ * @template T - The vector type extending TVector
462
+ * @param a - Vector to limit
463
+ * @param max - Maximum allowed magnitude
464
+ * @returns Vector with magnitude limited to max
465
+ * @throws {VectorError} If max is negative
466
+ *
467
+ * @example
468
+ * const velocity = [15, 20, 0]; // magnitude ≈ 25
469
+ * const limited = VectorLimit(velocity, 10); // magnitude = 10, same direction
470
+ *
471
+ * const small = [1, 1, 0]; // magnitude ≈ 1.414
472
+ * const unchanged = VectorLimit(small, 5); // unchanged since already under limit
473
+ */
474
+ export declare function VectorLimit<T extends TAnyVector>(a: T, max: number): TVectorResult<T>;
475
+ /**
476
+ * Validates if the input is a properly formatted vector.
477
+ * Performs comprehensive validation without throwing errors.
478
+ * Useful for input validation and defensive programming.
479
+ *
480
+ * @param vector - Input to validate
481
+ * @returns True if input is a valid vector, false otherwise
482
+ *
483
+ * @example
484
+ * const valid = VectorIsValid([1, 2, 3]); // true
485
+ * const invalid = VectorIsValid("not a vector"); // false
486
+ * const nullVector = VectorIsValid(null); // false
487
+ * const emptyArray = VectorIsValid([]); // depends on implementation
488
+ */
489
+ export declare function VectorIsValid(vector: unknown): boolean;
490
+ /**
491
+ * Performs Gram-Schmidt orthogonalization on a set of vectors.
492
+ * Converts a set of linearly independent vectors into an orthogonal (or orthonormal) set.
493
+ * Essential for creating coordinate systems and orthogonal bases.
494
+ *
495
+ * @template T - The vector type extending TVector
496
+ * @param vectors - Array of vectors to orthogonalize
497
+ * @param normalize - Whether to normalize the resulting vectors (default: false)
498
+ * @returns Array of orthogonal (or orthonormal) vectors
499
+ * @throws {VectorError} If vectors are linearly dependent or invalid
500
+ *
501
+ * @example
502
+ * const vectors = [[1, 1, 0], [1, 0, 1], [0, 1, 1]];
503
+ * const orthogonal = VectorGramSchmidt(vectors); // Orthogonal set
504
+ * const orthonormal = VectorGramSchmidt(vectors, true); // Orthonormal set
505
+ */
506
+ export declare function VectorGramSchmidt<T extends TAnyVector>(vectors: T[], normalize?: boolean): TVectorResult<T>[];
507
+ //# sourceMappingURL=core.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/vectors/core.ts"],"names":[],"mappings":"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"}