@pawells/math-extended 1.1.1 → 3.0.0

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 (113) hide show
  1. package/README.md +15 -21
  2. package/build/angles.d.ts +28 -18
  3. package/build/angles.d.ts.map +1 -1
  4. package/build/angles.js +28 -18
  5. package/build/angles.js.map +1 -1
  6. package/build/clamp.d.ts +2 -0
  7. package/build/clamp.d.ts.map +1 -1
  8. package/build/clamp.js +2 -0
  9. package/build/clamp.js.map +1 -1
  10. package/build/core.d.ts +23 -0
  11. package/build/core.d.ts.map +1 -0
  12. package/build/core.js +25 -0
  13. package/build/core.js.map +1 -0
  14. package/build/index.d.ts +1 -4
  15. package/build/index.d.ts.map +1 -1
  16. package/build/index.js +1 -6
  17. package/build/index.js.map +1 -1
  18. package/build/interpolation.d.ts +62 -13
  19. package/build/interpolation.d.ts.map +1 -1
  20. package/build/interpolation.js +66 -23
  21. package/build/interpolation.js.map +1 -1
  22. package/build/matrices/arithmetic.d.ts +65 -76
  23. package/build/matrices/arithmetic.d.ts.map +1 -1
  24. package/build/matrices/arithmetic.js +65 -107
  25. package/build/matrices/arithmetic.js.map +1 -1
  26. package/build/matrices/asserts.d.ts +26 -273
  27. package/build/matrices/asserts.d.ts.map +1 -1
  28. package/build/matrices/asserts.js +106 -350
  29. package/build/matrices/asserts.js.map +1 -1
  30. package/build/matrices/core.d.ts +150 -79
  31. package/build/matrices/core.d.ts.map +1 -1
  32. package/build/matrices/core.js +128 -104
  33. package/build/matrices/core.js.map +1 -1
  34. package/build/matrices/decompositions.d.ts +41 -44
  35. package/build/matrices/decompositions.d.ts.map +1 -1
  36. package/build/matrices/decompositions.js +51 -94
  37. package/build/matrices/decompositions.js.map +1 -1
  38. package/build/matrices/index.d.ts +2 -2
  39. package/build/matrices/index.d.ts.map +1 -1
  40. package/build/matrices/index.js +2 -2
  41. package/build/matrices/index.js.map +1 -1
  42. package/build/matrices/linear-algebra.d.ts +56 -19
  43. package/build/matrices/linear-algebra.d.ts.map +1 -1
  44. package/build/matrices/linear-algebra.js +80 -36
  45. package/build/matrices/linear-algebra.js.map +1 -1
  46. package/build/matrices/normalization.d.ts +36 -15
  47. package/build/matrices/normalization.d.ts.map +1 -1
  48. package/build/matrices/normalization.js +32 -23
  49. package/build/matrices/normalization.js.map +1 -1
  50. package/build/matrices/transformations.d.ts +39 -52
  51. package/build/matrices/transformations.d.ts.map +1 -1
  52. package/build/matrices/transformations.js +8 -11
  53. package/build/matrices/transformations.js.map +1 -1
  54. package/build/matrices/types.d.ts +39 -67
  55. package/build/matrices/types.d.ts.map +1 -1
  56. package/build/matrices/types.js +63 -1
  57. package/build/matrices/types.js.map +1 -1
  58. package/build/quaternions/asserts.d.ts +114 -15
  59. package/build/quaternions/asserts.d.ts.map +1 -1
  60. package/build/quaternions/asserts.js +189 -51
  61. package/build/quaternions/asserts.js.map +1 -1
  62. package/build/quaternions/conversions.d.ts +18 -8
  63. package/build/quaternions/conversions.d.ts.map +1 -1
  64. package/build/quaternions/conversions.js +14 -4
  65. package/build/quaternions/conversions.js.map +1 -1
  66. package/build/quaternions/core.d.ts +31 -2
  67. package/build/quaternions/core.d.ts.map +1 -1
  68. package/build/quaternions/core.js +32 -4
  69. package/build/quaternions/core.js.map +1 -1
  70. package/build/quaternions/index.d.ts +2 -2
  71. package/build/quaternions/index.d.ts.map +1 -1
  72. package/build/quaternions/index.js +3 -2
  73. package/build/quaternions/index.js.map +1 -1
  74. package/build/quaternions/interpolation.d.ts +7 -1
  75. package/build/quaternions/interpolation.d.ts.map +1 -1
  76. package/build/quaternions/interpolation.js +12 -6
  77. package/build/quaternions/interpolation.js.map +1 -1
  78. package/build/quaternions/predefined.d.ts +7 -1
  79. package/build/quaternions/predefined.d.ts.map +1 -1
  80. package/build/quaternions/predefined.js +6 -0
  81. package/build/quaternions/predefined.js.map +1 -1
  82. package/build/quaternions/types.d.ts +24 -13
  83. package/build/quaternions/types.d.ts.map +1 -1
  84. package/build/quaternions/types.js +51 -1
  85. package/build/quaternions/types.js.map +1 -1
  86. package/build/random.d.ts +66 -20
  87. package/build/random.d.ts.map +1 -1
  88. package/build/random.js +73 -20
  89. package/build/random.js.map +1 -1
  90. package/build/vectors/asserts.d.ts +33 -99
  91. package/build/vectors/asserts.d.ts.map +1 -1
  92. package/build/vectors/asserts.js +145 -181
  93. package/build/vectors/asserts.js.map +1 -1
  94. package/build/vectors/core.d.ts +76 -44
  95. package/build/vectors/core.d.ts.map +1 -1
  96. package/build/vectors/core.js +128 -119
  97. package/build/vectors/core.js.map +1 -1
  98. package/build/vectors/index.d.ts.map +1 -1
  99. package/build/vectors/index.js +1 -0
  100. package/build/vectors/index.js.map +1 -1
  101. package/build/vectors/interpolation.d.ts +13 -1
  102. package/build/vectors/interpolation.d.ts.map +1 -1
  103. package/build/vectors/interpolation.js +48 -47
  104. package/build/vectors/interpolation.js.map +1 -1
  105. package/build/vectors/predefined.d.ts +73 -25
  106. package/build/vectors/predefined.d.ts.map +1 -1
  107. package/build/vectors/predefined.js +62 -18
  108. package/build/vectors/predefined.js.map +1 -1
  109. package/build/vectors/types.d.ts +26 -4
  110. package/build/vectors/types.d.ts.map +1 -1
  111. package/build/vectors/types.js +50 -1
  112. package/build/vectors/types.js.map +1 -1
  113. package/package.json +4 -3
@@ -2,7 +2,7 @@
2
2
  * Core vector mathematics operations for linear algebra and geometric calculations.
3
3
  * Provides a comprehensive set of vector operations with type safety and error checking.
4
4
  */
5
- import { TAnyVector, TVectorResult, TVector, TVector2, TVector3 } from './types.js';
5
+ import type { TAnyVector, TVectorResult, TVector, TVector2, TVector3 } from './types.js';
6
6
  /**
7
7
  * Creates a deep copy of a vector.
8
8
  * Essential for avoiding mutations when performing operations that should preserve the original vector.
@@ -12,9 +12,11 @@ import { TAnyVector, TVectorResult, TVector, TVector2, TVector3 } from './types.
12
12
  * @returns A new vector with identical components
13
13
  *
14
14
  * @example
15
+ * ```typescript
15
16
  * const original = [1, 2, 3];
16
17
  * const copy = VectorClone(original);
17
18
  * copy[0] = 10; // original remains unchanged
19
+ * ```
18
20
  */
19
21
  export declare function VectorClone<T extends TAnyVector>(vector: T): TVectorResult<T>;
20
22
  /**
@@ -28,10 +30,12 @@ export declare function VectorClone<T extends TAnyVector>(vector: T): TVectorRes
28
30
  * @returns True if vectors are equal within tolerance, false otherwise
29
31
  *
30
32
  * @example
33
+ * ```typescript
31
34
  * const a = [1.0001, 2.0001];
32
35
  * const b = [1.0002, 2.0002];
33
36
  * const exactlyEqual = VectorEquals(a, b); // false
34
37
  * const approximatelyEqual = VectorEquals(a, b, 0.001); // true
38
+ * ```
35
39
  */
36
40
  export declare function VectorEquals<T extends TAnyVector>(a: T, b: T, tolerance?: number): boolean;
37
41
  /**
@@ -43,9 +47,11 @@ export declare function VectorEquals<T extends TAnyVector>(a: T, b: T, tolerance
43
47
  * @returns String representation of the vector
44
48
  *
45
49
  * @example
50
+ * ```typescript
46
51
  * const vec = [1, 2, 3];
47
52
  * const parens = VectorToString(vec, 'parens'); // "(1, 2, 3)"
48
53
  * const brackets = VectorToString(vec, 'brackets'); // "[1, 2, 3]"
54
+ * ```
49
55
  */
50
56
  export declare function VectorToString(vector: TVector, style?: 'parens' | 'brackets'): string;
51
57
  /**
@@ -58,9 +64,11 @@ export declare function VectorToString(vector: TVector, style?: 'parens' | 'brac
58
64
  * @returns New vector where each component is the sum of corresponding components
59
65
  *
60
66
  * @example
67
+ * ```typescript
61
68
  * const position = [10, 20, 30];
62
69
  * const velocity = [1, -2, 0.5];
63
70
  * const newPosition = VectorAdd(position, velocity); // [11, 18, 30.5]
71
+ * ```
64
72
  */
65
73
  export declare function VectorAdd<T extends TAnyVector>(a: T, b: T): TVectorResult<T>;
66
74
  /**
@@ -73,9 +81,11 @@ export declare function VectorAdd<T extends TAnyVector>(a: T, b: T): TVectorResu
73
81
  * @returns New vector where each component is the difference of corresponding components
74
82
  *
75
83
  * @example
84
+ * ```typescript
76
85
  * const target = [100, 50, 0];
77
86
  * const current = [80, 30, 0];
78
87
  * const direction = VectorSubtract(target, current); // [20, 20, 0]
88
+ * ```
79
89
  */
80
90
  export declare function VectorSubtract<T extends TAnyVector>(a: T, b: T): TVectorResult<T>;
81
91
  /**
@@ -88,10 +98,12 @@ export declare function VectorSubtract<T extends TAnyVector>(a: T, b: T): TVecto
88
98
  * @returns New vector with multiplied components
89
99
  *
90
100
  * @example
101
+ * ```typescript
91
102
  * const velocity = [10, 5, 0];
92
103
  * const scaled = VectorMultiply(velocity, 2); // [20, 10, 0] - scalar multiplication
93
104
  * const factors = [1, -1, 0.5];
94
105
  * const componentWise = VectorMultiply(velocity, factors); // [10, -5, 0] - component-wise
106
+ * ```
95
107
  */
96
108
  export declare function VectorMultiply<T extends TAnyVector>(a: T, b: T | number): TVectorResult<T>;
97
109
  /**
@@ -103,9 +115,11 @@ export declare function VectorMultiply<T extends TAnyVector>(a: T, b: T | number
103
115
  * @returns The straight-line distance between the two points represented by the vectors
104
116
  *
105
117
  * @example
118
+ * ```typescript
106
119
  * const pointA = [0, 0, 0];
107
120
  * const pointB = [3, 4, 0];
108
121
  * const distance = VectorDistance(pointA, pointB); // 5.0 (3-4-5 triangle)
122
+ * ```
109
123
  */
110
124
  export declare function VectorDistance(a: TVector, b: TVector): number;
111
125
  /**
@@ -118,9 +132,11 @@ export declare function VectorDistance(a: TVector, b: TVector): number;
118
132
  * @returns The squared distance between vectors
119
133
  *
120
134
  * @example
135
+ * ```typescript
121
136
  * const pointA = [1, 1];
122
137
  * const pointB = [4, 5];
123
138
  * const distSq = VectorDistanceSquared(pointA, pointB); // 25 (faster than distance comparison)
139
+ * ```
124
140
  */
125
141
  export declare function VectorDistanceSquared(a: TVector, b: TVector): number;
126
142
  /**
@@ -133,12 +149,13 @@ export declare function VectorDistanceSquared(a: TVector, b: TVector): number;
133
149
  * @returns The dot product (scalar value)
134
150
  *
135
151
  * @example
152
+ * ```typescript
136
153
  * const forward = [0, 0, 1];
137
154
  * const direction = [0, 0, 2];
138
155
  * const dot = VectorDot(forward, direction); // 2 (same direction)
139
- *
140
156
  * const perpendicular = [1, 0, 0];
141
157
  * const dotPerp = VectorDot(forward, perpendicular); // 0 (perpendicular)
158
+ * ```
142
159
  */
143
160
  export declare function VectorDot(a: TVector, b: TVector): number;
144
161
  /**
@@ -152,11 +169,12 @@ export declare function VectorDot(a: TVector, b: TVector): number;
152
169
  * @throws {VectorError} If the vector is zero or has infinite magnitude
153
170
  *
154
171
  * @example
172
+ * ```typescript
155
173
  * const vector = [3, 4, 0];
156
174
  * const normalized = VectorNormalize(vector); // [0.6, 0.8, 0] (magnitude = 1)
157
- *
158
175
  * const direction = [10, 0, 0];
159
176
  * const unitDirection = VectorNormalize(direction); // [1, 0, 0]
177
+ * ```
160
178
  */
161
179
  export declare function VectorNormalize<T extends TAnyVector>(a: T): TVectorResult<T>;
162
180
  /**
@@ -167,11 +185,12 @@ export declare function VectorNormalize<T extends TAnyVector>(a: T): TVectorResu
167
185
  * @returns The magnitude (length) of the vector
168
186
  *
169
187
  * @example
188
+ * ```typescript
170
189
  * const velocity = [3, 4, 0];
171
190
  * const speed = VectorMagnitude(velocity); // 5.0
172
- *
173
191
  * const unitVector = [1, 0, 0];
174
192
  * const unitLength = VectorMagnitude(unitVector); // 1.0
193
+ * ```
175
194
  */
176
195
  export declare function VectorMagnitude(a: TVector): number;
177
196
  /**
@@ -183,11 +202,12 @@ export declare function VectorMagnitude(a: TVector): number;
183
202
  * @returns New vector with absolute values of all components
184
203
  *
185
204
  * @example
205
+ * ```typescript
186
206
  * const vector = [-3, 4, -2];
187
207
  * const absolute = VectorAbs(vector); // [3, 4, 2]
188
- *
189
208
  * const mixed = [1.5, -2.7, 0];
190
209
  * const absValues = VectorAbs(mixed); // [1.5, 2.7, 0]
210
+ * ```
191
211
  */
192
212
  export declare function VectorAbs<T extends TAnyVector>(a: T): TVectorResult<T>;
193
213
  /**
@@ -198,11 +218,12 @@ export declare function VectorAbs<T extends TAnyVector>(a: T): TVectorResult<T>;
198
218
  * @returns True if all components are zero, false otherwise
199
219
  *
200
220
  * @example
221
+ * ```typescript
201
222
  * const zero = [0, 0, 0];
202
223
  * const isZero = VectorIsZero(zero); // true
203
- *
204
224
  * const notZero = [0, 0.001, 0];
205
225
  * const isNotZero = VectorIsZero(notZero); // false
226
+ * ```
206
227
  */
207
228
  export declare function VectorIsZero(vector: TVector): boolean;
208
229
  /**
@@ -216,15 +237,33 @@ export declare function VectorIsZero(vector: TVector): boolean;
216
237
  * @throws {VectorError} If either vector is zero
217
238
  *
218
239
  * @example
240
+ * ```typescript
219
241
  * const right = [1, 0, 0];
220
242
  * const up = [0, 1, 0];
221
243
  * const angle = VectorAngle(right, up); // π/2 (90 degrees)
222
- *
223
244
  * const forward = [0, 0, 1];
224
245
  * const backward = [0, 0, -1];
225
246
  * const oppositeAngle = VectorAngle(forward, backward); // π (180 degrees)
247
+ * ```
226
248
  */
227
249
  export declare function VectorAngle(a: TVector, b: TVector): number;
250
+ /**
251
+ * Limits (clamps) the magnitude of a vector to a maximum value.
252
+ * If the vector's magnitude exceeds the maximum, scales it down proportionally while preserving direction.
253
+ * If the magnitude is below the maximum, the vector is returned unchanged.
254
+ *
255
+ * @param vector - The input vector to limit
256
+ * @param maxMagnitude - The maximum allowed magnitude (must be >= 0)
257
+ * @returns A new vector with magnitude limited to maxMagnitude
258
+ * @throws {VectorError} If vector is invalid or maxMagnitude is invalid
259
+ *
260
+ * @example
261
+ * ```typescript
262
+ * const v = [3, 4]; // magnitude 5
263
+ * VectorLimit(v, 3); // [1.8, 2.4] — magnitude now 3
264
+ * ```
265
+ */
266
+ export declare function VectorLimit<T extends TAnyVector>(vector: T, maxMagnitude: number): TVectorResult<T>;
228
267
  /**
229
268
  * Rotates a 2D vector by the specified angle in radians.
230
269
  * Essential for 2D transformations, sprite rotations, and directional calculations.
@@ -234,9 +273,11 @@ export declare function VectorAngle(a: TVector, b: TVector): number;
234
273
  * @returns New rotated 2D vector
235
274
  *
236
275
  * @example
276
+ * ```typescript
237
277
  * const right = [1, 0];
238
278
  * const rotated90 = Vector2Rotate(right, Math.PI / 2); // [0, 1] (up)
239
279
  * const rotated180 = Vector2Rotate(right, Math.PI); // [-1, 0] (left)
280
+ * ```
240
281
  */
241
282
  export declare function Vector2Rotate(vector: TVector2, radians: number): TVector2;
242
283
  /**
@@ -247,9 +288,11 @@ export declare function Vector2Rotate(vector: TVector2, radians: number): TVecto
247
288
  * @returns Unit vector pointing in the specified direction
248
289
  *
249
290
  * @example
291
+ * ```typescript
250
292
  * const right = Vector2FromAngle(0); // [1, 0]
251
293
  * const up = Vector2FromAngle(Math.PI / 2); // [0, 1]
252
294
  * const diagonal = Vector2FromAngle(Math.PI / 4); // [0.707, 0.707]
295
+ * ```
253
296
  */
254
297
  export declare function Vector2FromAngle(radians: number): TVector2;
255
298
  /**
@@ -262,10 +305,12 @@ export declare function Vector2FromAngle(radians: number): TVector2;
262
305
  * @returns Scalar cross product (positive = counterclockwise, negative = clockwise)
263
306
  *
264
307
  * @example
308
+ * ```typescript
265
309
  * const right = [1, 0];
266
310
  * const up = [0, 1];
267
311
  * const cross = Vector2Cross(right, up); // 1 (counterclockwise)
268
312
  * const crossReverse = Vector2Cross(up, right); // -1 (clockwise)
313
+ * ```
269
314
  */
270
315
  export declare function Vector2Cross(a: TVector2, b: TVector2): number;
271
316
  /**
@@ -279,9 +324,11 @@ export declare function Vector2Cross(a: TVector2, b: TVector2): number;
279
324
  * @throws {VectorError} If vector b is zero
280
325
  *
281
326
  * @example
327
+ * ```typescript
282
328
  * const force = [5, 3, 0];
283
329
  * const surface = [1, 0, 0];
284
330
  * const perpendicular = Vector3Reject(force, surface); // [0, 3, 0]
331
+ * ```
285
332
  */
286
333
  export declare function Vector3Reject(a: TVector3, b: TVector3): TVector3;
287
334
  /**
@@ -296,9 +343,11 @@ export declare function Vector3Reject(a: TVector3, b: TVector3): TVector3;
296
343
  * @throws {VectorError} If vector b is zero
297
344
  *
298
345
  * @example
346
+ * ```typescript
299
347
  * const force = [5, 3, 0];
300
348
  * const surface = [1, 0, 0];
301
349
  * const parallel = VectorProject(force, surface); // [5, 0, 0]
350
+ * ```
302
351
  */
303
352
  export declare function VectorProject<T extends TAnyVector>(a: T, b: T): TVectorResult<T>;
304
353
  /**
@@ -312,9 +361,11 @@ export declare function VectorProject<T extends TAnyVector>(a: T, b: T): TVector
312
361
  * @throws {VectorError} If the normal is a zero vector
313
362
  *
314
363
  * @example
364
+ * ```typescript
315
365
  * const incoming = [1, -1, 0];
316
366
  * const normal = [0, 1, 0]; // surface normal (upward)
317
367
  * const reflected = Vector3Reflect(incoming, normal); // [1, 1, 0]
368
+ * ```
318
369
  */
319
370
  export declare function Vector3Reflect(incident: TVector3, normal: TVector3): TVector3;
320
371
  /**
@@ -327,11 +378,12 @@ export declare function Vector3Reflect(incident: TVector3, normal: TVector3): TV
327
378
  * @returns Vector perpendicular to both a and b (following right-hand rule)
328
379
  *
329
380
  * @example
381
+ * ```typescript
330
382
  * const right = [1, 0, 0];
331
383
  * const forward = [0, 0, 1];
332
384
  * const up = Vector3Cross(right, forward); // [0, 1, 0]
333
- *
334
385
  * const normal = Vector3Cross([1, 0, 0], [0, 1, 0]); // [0, 0, 1]
386
+ * ```
335
387
  */
336
388
  export declare function Vector3Cross(a: TVector3, b: TVector3): TVector3;
337
389
  /**
@@ -344,9 +396,11 @@ export declare function Vector3Cross(a: TVector3, b: TVector3): TVector3;
344
396
  * @returns Magnitude of the cross product
345
397
  *
346
398
  * @example
399
+ * ```typescript
347
400
  * const side1 = [3, 0, 0];
348
401
  * const side2 = [0, 4, 0];
349
402
  * const area = VectorCrossMagnitude(side1, side2); // 12 (area of rectangle)
403
+ * ```
350
404
  */
351
405
  export declare function VectorCrossMagnitude(a: TVector3, b: TVector3): number;
352
406
  /**
@@ -360,10 +414,12 @@ export declare function VectorCrossMagnitude(a: TVector3, b: TVector3): number;
360
414
  * @returns Signed volume (positive = right-handed orientation)
361
415
  *
362
416
  * @example
417
+ * ```typescript
363
418
  * const x = [1, 0, 0];
364
419
  * const y = [0, 1, 0];
365
420
  * const z = [0, 0, 1];
366
421
  * const volume = Vector3ScalarTripleProduct(x, y, z); // 1 (unit cube)
422
+ * ```
367
423
  */
368
424
  export declare function Vector3ScalarTripleProduct(a: TVector3, b: TVector3, c: TVector3): number;
369
425
  /**
@@ -377,10 +433,12 @@ export declare function Vector3ScalarTripleProduct(a: TVector3, b: TVector3, c:
377
433
  * @returns Vector result of a × (b × c)
378
434
  *
379
435
  * @example
436
+ * ```typescript
380
437
  * const a = [1, 0, 0];
381
438
  * const b = [0, 1, 0];
382
439
  * const c = [0, 0, 1];
383
440
  * const result = Vector3TripleProduct(a, b, c); // [0, 0, 0]
441
+ * ```
384
442
  */
385
443
  export declare function Vector3TripleProduct(a: TVector3, b: TVector3, c: TVector3): TVector3;
386
444
  /**
@@ -394,9 +452,11 @@ export declare function Vector3TripleProduct(a: TVector3, b: TVector3, c: TVecto
394
452
  * @returns The reflected vector
395
453
  *
396
454
  * @example
455
+ * ```typescript
397
456
  * const incoming = [1, -1, 0];
398
457
  * const wall = [0, 1, 0]; // vertical wall normal
399
458
  * const bounced = VectorReflect(incoming, wall); // [1, 1, 0]
459
+ * ```
400
460
  */
401
461
  export declare function VectorReflect<T extends TAnyVector>(incident: T, normal: T): TVectorResult<T>;
402
462
  /**
@@ -409,11 +469,12 @@ export declare function VectorReflect<T extends TAnyVector>(incident: T, normal:
409
469
  * @returns Vector with all components negated
410
470
  *
411
471
  * @example
472
+ * ```typescript
412
473
  * const forward = [0, 0, 1];
413
474
  * const backward = VectorNegate(forward); // [0, 0, -1]
414
- *
415
475
  * const velocity = [5, -3, 2];
416
476
  * const opposite = VectorNegate(velocity); // [-5, 3, -2]
477
+ * ```
417
478
  */
418
479
  export declare function VectorNegate<T extends TAnyVector>(a: T): TVectorResult<T>;
419
480
  /**
@@ -427,10 +488,12 @@ export declare function VectorNegate<T extends TAnyVector>(a: T): TVectorResult<
427
488
  * @throws {VectorError} If any divisor component is zero
428
489
  *
429
490
  * @example
491
+ * ```typescript
430
492
  * const velocity = [20, 10, 0];
431
493
  * const halved = VectorDivide(velocity, 2); // [10, 5, 0] - scalar division
432
494
  * const factors = [2, 5, 1];
433
495
  * const componentWise = VectorDivide(velocity, factors); // [10, 2, 0] - component-wise
496
+ * ```
434
497
  */
435
498
  export declare function VectorDivide<T extends TAnyVector>(a: T, b: T | number): TVectorResult<T>;
436
499
  /**
@@ -445,48 +508,15 @@ export declare function VectorDivide<T extends TAnyVector>(a: T, b: T | number):
445
508
  * @returns New vector with each component clamped between min and max
446
509
  *
447
510
  * @example
511
+ * ```typescript
448
512
  * const v = [5, -3, 12, 0];
449
513
  * VectorClamp(v, 0, 10); // [5, 0, 10, 0] - scalar bounds
450
- *
451
514
  * const mins = [0, -5, 0, -1];
452
515
  * const maxs = [10, 5, 8, 1];
453
516
  * VectorClamp(v, mins, maxs); // [5, -3, 8, 0] - per-component bounds
517
+ * ```
454
518
  */
455
519
  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
520
  /**
491
521
  * Performs Gram-Schmidt orthogonalization on a set of vectors.
492
522
  * Converts a set of linearly independent vectors into an orthogonal (or orthonormal) set.
@@ -499,9 +529,11 @@ export declare function VectorIsValid(vector: unknown): boolean;
499
529
  * @throws {VectorError} If vectors are linearly dependent or invalid
500
530
  *
501
531
  * @example
532
+ * ```typescript
502
533
  * const vectors = [[1, 1, 0], [1, 0, 1], [0, 1, 1]];
503
534
  * const orthogonal = VectorGramSchmidt(vectors); // Orthogonal set
504
535
  * const orthonormal = VectorGramSchmidt(vectors, true); // Orthonormal set
536
+ * ```
505
537
  */
506
538
  export declare function VectorGramSchmidt<T extends TAnyVector>(vectors: T[], normalize?: boolean): TVectorResult<T>[];
507
539
  //# sourceMappingURL=core.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/vectors/core.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/vectors/core.ts"],"names":[],"mappings":"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"}