@pawells/math-extended 2.0.0 → 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.
- package/README.md +15 -21
- package/build/clamp.d.ts +5 -5
- package/build/clamp.js +5 -5
- package/build/core.d.ts +23 -0
- package/build/core.d.ts.map +1 -0
- package/build/core.js +25 -0
- package/build/core.js.map +1 -0
- package/build/index.d.ts +1 -4
- package/build/index.d.ts.map +1 -1
- package/build/index.js +1 -6
- package/build/index.js.map +1 -1
- package/build/interpolation.d.ts +158 -171
- package/build/interpolation.d.ts.map +1 -1
- package/build/interpolation.js +162 -181
- package/build/interpolation.js.map +1 -1
- package/build/matrices/arithmetic.d.ts +132 -132
- package/build/matrices/arithmetic.d.ts.map +1 -1
- package/build/matrices/arithmetic.js +194 -226
- package/build/matrices/arithmetic.js.map +1 -1
- package/build/matrices/asserts.d.ts +30 -408
- package/build/matrices/asserts.d.ts.map +1 -1
- package/build/matrices/asserts.js +98 -542
- package/build/matrices/asserts.js.map +1 -1
- package/build/matrices/core.d.ts +117 -46
- package/build/matrices/core.d.ts.map +1 -1
- package/build/matrices/core.js +127 -103
- package/build/matrices/core.js.map +1 -1
- package/build/matrices/decompositions.d.ts +95 -96
- package/build/matrices/decompositions.d.ts.map +1 -1
- package/build/matrices/decompositions.js +119 -160
- package/build/matrices/decompositions.js.map +1 -1
- package/build/matrices/index.d.ts +0 -1
- package/build/matrices/index.d.ts.map +1 -1
- package/build/matrices/index.js +0 -3
- package/build/matrices/index.js.map +1 -1
- package/build/matrices/linear-algebra.d.ts +45 -8
- package/build/matrices/linear-algebra.d.ts.map +1 -1
- package/build/matrices/linear-algebra.js +76 -32
- package/build/matrices/linear-algebra.js.map +1 -1
- package/build/matrices/normalization.d.ts +29 -8
- package/build/matrices/normalization.d.ts.map +1 -1
- package/build/matrices/normalization.js +32 -23
- package/build/matrices/normalization.js.map +1 -1
- package/build/matrices/transformations.d.ts +116 -148
- package/build/matrices/transformations.d.ts.map +1 -1
- package/build/matrices/transformations.js +69 -91
- package/build/matrices/transformations.js.map +1 -1
- package/build/matrices/types.d.ts +32 -60
- package/build/matrices/types.d.ts.map +1 -1
- package/build/matrices/types.js +63 -1
- package/build/matrices/types.js.map +1 -1
- package/build/quaternions/asserts.d.ts +29 -38
- package/build/quaternions/asserts.d.ts.map +1 -1
- package/build/quaternions/asserts.js +61 -77
- package/build/quaternions/asserts.js.map +1 -1
- package/build/quaternions/conversions.d.ts +26 -26
- package/build/quaternions/conversions.d.ts.map +1 -1
- package/build/quaternions/conversions.js +24 -24
- package/build/quaternions/core.d.ts +70 -69
- package/build/quaternions/core.d.ts.map +1 -1
- package/build/quaternions/core.js +71 -71
- package/build/quaternions/core.js.map +1 -1
- package/build/quaternions/index.d.ts +0 -1
- package/build/quaternions/index.d.ts.map +1 -1
- package/build/quaternions/index.js +0 -2
- package/build/quaternions/index.js.map +1 -1
- package/build/quaternions/interpolation.d.ts +16 -16
- package/build/quaternions/interpolation.d.ts.map +1 -1
- package/build/quaternions/interpolation.js +21 -21
- package/build/quaternions/interpolation.js.map +1 -1
- package/build/quaternions/predefined.d.ts +10 -10
- package/build/quaternions/predefined.d.ts.map +1 -1
- package/build/quaternions/predefined.js +9 -9
- package/build/quaternions/types.d.ts +23 -12
- package/build/quaternions/types.d.ts.map +1 -1
- package/build/quaternions/types.js +51 -1
- package/build/quaternions/types.js.map +1 -1
- package/build/random.d.ts +66 -20
- package/build/random.d.ts.map +1 -1
- package/build/random.js +73 -20
- package/build/random.js.map +1 -1
- package/build/vectors/asserts.d.ts +50 -220
- package/build/vectors/asserts.d.ts.map +1 -1
- package/build/vectors/asserts.js +141 -327
- package/build/vectors/asserts.js.map +1 -1
- package/build/vectors/core.d.ts +182 -229
- package/build/vectors/core.d.ts.map +1 -1
- package/build/vectors/core.js +234 -288
- package/build/vectors/core.js.map +1 -1
- package/build/vectors/index.d.ts +0 -1
- package/build/vectors/index.d.ts.map +1 -1
- package/build/vectors/index.js +0 -2
- package/build/vectors/index.js.map +1 -1
- package/build/vectors/interpolation.d.ts +40 -40
- package/build/vectors/interpolation.d.ts.map +1 -1
- package/build/vectors/interpolation.js +75 -86
- package/build/vectors/interpolation.js.map +1 -1
- package/build/vectors/predefined.d.ts +31 -7
- package/build/vectors/predefined.d.ts.map +1 -1
- package/build/vectors/predefined.js +30 -6
- package/build/vectors/predefined.js.map +1 -1
- package/build/vectors/types.d.ts +26 -4
- package/build/vectors/types.d.ts.map +1 -1
- package/build/vectors/types.js +50 -1
- package/build/vectors/types.js.map +1 -1
- package/package.json +3 -2
- package/build/matrices/_exports.d.ts +0 -13
- package/build/matrices/_exports.d.ts.map +0 -1
- package/build/matrices/_exports.js +0 -13
- package/build/matrices/_exports.js.map +0 -1
- package/build/quaternions/_exports.d.ts +0 -11
- package/build/quaternions/_exports.d.ts.map +0 -1
- package/build/quaternions/_exports.js +0 -11
- package/build/quaternions/_exports.js.map +0 -1
- package/build/vectors/_exports.d.ts +0 -10
- package/build/vectors/_exports.d.ts.map +0 -1
- package/build/vectors/_exports.js +0 -10
- package/build/vectors/_exports.js.map +0 -1
package/build/vectors/asserts.js
CHANGED
|
@@ -3,35 +3,25 @@
|
|
|
3
3
|
* Provides comprehensive validation functions to ensure vector data integrity
|
|
4
4
|
* and catch errors early in mathematical operations.
|
|
5
5
|
*/
|
|
6
|
-
import {
|
|
6
|
+
import { VECTOR2_SCHEMA, VECTOR3_SCHEMA, VECTOR4_SCHEMA, VECTOR_SCHEMA } from './types.js';
|
|
7
|
+
import z from 'zod';
|
|
7
8
|
/**
|
|
8
|
-
*
|
|
9
|
-
*
|
|
9
|
+
* Vector error class for validation failures and vector operations.
|
|
10
|
+
* Extends Error to provide detailed error information with optional cause chain.
|
|
10
11
|
*
|
|
11
12
|
* @example
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
* } catch (error) {
|
|
16
|
-
* if (error instanceof VectorError) {
|
|
17
|
-
* console.log("Vector validation failed:", error.message);
|
|
18
|
-
* }
|
|
19
|
-
* }
|
|
20
|
-
* ```
|
|
13
|
+
* ```typescript
|
|
14
|
+
* throw new VectorError('Invalid vector dimensions', { cause: originalError });
|
|
15
|
+
* ```
|
|
21
16
|
*/
|
|
22
17
|
export class VectorError extends Error {
|
|
23
18
|
code = 'VECTOR_ERROR';
|
|
24
|
-
/**
|
|
25
|
-
* Creates a new VectorError instance.
|
|
26
|
-
*
|
|
27
|
-
* @param message - Error message describing the validation failure
|
|
28
|
-
* @param options - Optional error context
|
|
29
|
-
* @param options.cause - Original error that caused this error
|
|
30
|
-
*/
|
|
31
19
|
constructor(message, options) {
|
|
32
|
-
super(message
|
|
20
|
+
super(message);
|
|
33
21
|
this.name = 'VectorError';
|
|
34
|
-
|
|
22
|
+
if (options?.cause) {
|
|
23
|
+
this.cause = options.cause;
|
|
24
|
+
}
|
|
35
25
|
}
|
|
36
26
|
}
|
|
37
27
|
/**
|
|
@@ -46,56 +36,33 @@ export class VectorError extends Error {
|
|
|
46
36
|
* @throws {VectorError} If the value is not a valid vector meeting all constraints
|
|
47
37
|
*
|
|
48
38
|
* @example
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
* ```
|
|
58
|
-
* ```
|
|
39
|
+
* ```typescript
|
|
40
|
+
* // Basic validation — passes silently for a valid vector
|
|
41
|
+
* AssertVector([1, 2, 3]);
|
|
42
|
+
* // Validate with size constraint
|
|
43
|
+
* AssertVector([1, 2], { size: 2 });
|
|
44
|
+
* // Throws VectorError for non-array input
|
|
45
|
+
* AssertVector("not a vector"); // throws VectorError
|
|
46
|
+
* ```
|
|
59
47
|
*/
|
|
60
|
-
export function AssertVector(vector
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
exc.class ??= VectorError;
|
|
64
|
-
// First validate that it's an array
|
|
65
|
-
if (!Array.isArray(vector)) {
|
|
66
|
-
SetExceptionMessage(exc, 'Not a Valid Vector');
|
|
67
|
-
ThrowException(exc);
|
|
68
|
-
}
|
|
69
|
-
// Type cast is safe after array validation
|
|
70
|
-
const array = vector;
|
|
71
|
-
// Validate array size constraints (inherited from AssertArrayArgs)
|
|
72
|
-
if (args.size !== undefined && array.length !== args.size) {
|
|
73
|
-
SetExceptionMessage(exc, `Vector does not match expected size. (size: ${args.size})`);
|
|
74
|
-
ThrowException(exc);
|
|
48
|
+
export function AssertVector(vector) {
|
|
49
|
+
try {
|
|
50
|
+
VECTOR_SCHEMA.parse(vector);
|
|
75
51
|
}
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
52
|
+
catch (error) {
|
|
53
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
54
|
+
throw new VectorError(`Invalid vector: ${message}`, {
|
|
55
|
+
cause: error instanceof Error ? error : undefined,
|
|
56
|
+
});
|
|
79
57
|
}
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
58
|
+
}
|
|
59
|
+
export function ValidateVector(vector) {
|
|
60
|
+
try {
|
|
61
|
+
AssertVector(vector);
|
|
62
|
+
return true;
|
|
83
63
|
}
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
try {
|
|
87
|
-
AssertVectorValue(array[i], args, { ...exc, index: i });
|
|
88
|
-
}
|
|
89
|
-
catch (error) {
|
|
90
|
-
// Re-throw with vector context if it's our error type
|
|
91
|
-
if (error instanceof VectorError) {
|
|
92
|
-
throw error;
|
|
93
|
-
}
|
|
94
|
-
// Wrap other errors in VectorError
|
|
95
|
-
SetExceptionMessage(exc, `Invalid Vector Element${exc.index ? `[${exc.index}]` : ''}: ${error.message}`);
|
|
96
|
-
exc.index = i;
|
|
97
|
-
ThrowException(exc);
|
|
98
|
-
}
|
|
64
|
+
catch {
|
|
65
|
+
return false;
|
|
99
66
|
}
|
|
100
67
|
}
|
|
101
68
|
/**
|
|
@@ -105,234 +72,24 @@ export function AssertVector(vector, args = {}, exception = {}) {
|
|
|
105
72
|
* @param exception - Custom exception details if validation fails
|
|
106
73
|
* @throws {VectorError} If the value is not a 2-component vector
|
|
107
74
|
*
|
|
108
|
-
* @example
|
|
109
|
-
* ```typescript
|
|
110
|
-
* ```typescript
|
|
111
|
-
* AssertVector2([1, 2]); // passes
|
|
112
|
-
* AssertVector2([1, 2, 3]); // throws — too many components
|
|
113
|
-
* AssertVector2("not a vec"); // throws
|
|
114
|
-
* ```
|
|
115
|
-
* ```
|
|
116
|
-
*/
|
|
117
|
-
export function AssertVector2(vector, exception = {}) {
|
|
118
|
-
AssertVector(vector, { size: 2 }, exception);
|
|
119
|
-
}
|
|
120
|
-
/**
|
|
121
|
-
* Validates that an unknown value is a valid 3D vector (exactly 3 numeric components).
|
|
122
|
-
*
|
|
123
|
-
* @param vector - The value to validate as a 3D vector
|
|
124
|
-
* @param exception - Custom exception details if validation fails
|
|
125
|
-
* @throws {VectorError} If the value is not a 3-component vector
|
|
126
|
-
*
|
|
127
|
-
* @example
|
|
128
|
-
* ```typescript
|
|
129
|
-
* ```typescript
|
|
130
|
-
* AssertVector3([1, 2, 3]); // passes
|
|
131
|
-
* AssertVector3([1, 2]); // throws — too few components
|
|
132
|
-
* AssertVector3(null); // throws
|
|
133
|
-
* ```
|
|
134
|
-
* ```
|
|
135
|
-
*/
|
|
136
|
-
export function AssertVector3(vector, exception = {}) {
|
|
137
|
-
AssertVector(vector, { size: 3 }, exception);
|
|
138
|
-
}
|
|
139
|
-
/**
|
|
140
|
-
* Validates that an unknown value is a valid 4D vector (exactly 4 numeric components).
|
|
141
|
-
*
|
|
142
|
-
* @param vector - The value to validate as a 4D vector
|
|
143
|
-
* @param exception - Custom exception details if validation fails
|
|
144
|
-
* @throws {VectorError} If the value is not a 4-component vector
|
|
145
|
-
*
|
|
146
|
-
* @example
|
|
147
|
-
* ```typescript
|
|
148
|
-
* ```typescript
|
|
149
|
-
* AssertVector4([1, 2, 3, 4]); // passes
|
|
150
|
-
* AssertVector4([1, 2, 3]); // throws — too few components
|
|
151
|
-
* AssertVector4(undefined); // throws
|
|
152
|
-
* ```
|
|
153
|
-
* ```
|
|
154
|
-
*/
|
|
155
|
-
export function AssertVector4(vector, exception = {}) {
|
|
156
|
-
AssertVector(vector, { size: 4 }, exception);
|
|
157
|
-
}
|
|
158
|
-
/**
|
|
159
|
-
* Validates that an unknown value is a valid vector element (a finite, non-NaN number).
|
|
160
|
-
*
|
|
161
|
-
* Supports optional numeric constraints such as range bounds, integer enforcement,
|
|
162
|
-
* and finiteness checks. Throws `VectorError` with the component index when available.
|
|
163
|
-
*
|
|
164
|
-
* @param value - The value to validate as a vector element
|
|
165
|
-
* @param args - Numeric constraints (finite, integer, gt, gte, lt, lte, eq)
|
|
166
|
-
* @param exception - Custom exception details, optionally including a component `index`
|
|
167
|
-
* @throws {VectorError} If the value is not a valid number or violates any constraint
|
|
168
|
-
*
|
|
169
|
-
* @example
|
|
170
|
-
* ```typescript
|
|
171
|
-
* ```typescript
|
|
172
|
-
* AssertVectorValue(3.14); // passes
|
|
173
|
-
* AssertVectorValue(3.14, { finite: true }); // passes
|
|
174
|
-
* AssertVectorValue(Infinity, { finite: true }); // throws
|
|
175
|
-
* AssertVectorValue(NaN); // throws
|
|
176
|
-
* AssertVectorValue(5, { gte: 0, lte: 10 }); // passes
|
|
177
|
-
* ```
|
|
178
|
-
* ```
|
|
179
|
-
*/
|
|
180
|
-
export function AssertVectorValue(value, args = {}, exception = {}) {
|
|
181
|
-
// Initialize exception configuration with defaults
|
|
182
|
-
const exc = exception ?? {};
|
|
183
|
-
exc.class ??= VectorError;
|
|
184
|
-
// Validate that the value is a number (and not NaN)
|
|
185
|
-
if (typeof value !== 'number' || Number.isNaN(value)) {
|
|
186
|
-
if (exc.index !== undefined) {
|
|
187
|
-
SetExceptionMessage(exc, `Vector[${exc.index}] Not a Number`);
|
|
188
|
-
}
|
|
189
|
-
else {
|
|
190
|
-
SetExceptionMessage(exc, `Vector element must be a number, got ${typeof value}`);
|
|
191
|
-
}
|
|
192
|
-
ThrowException(exc);
|
|
193
|
-
}
|
|
194
|
-
// Type cast is safe after number validation
|
|
195
|
-
const numValue = value;
|
|
196
|
-
// Apply all number validation constraints using the same logic as AssertNumber
|
|
197
|
-
// but with VectorError as the default error class instead of NumberError
|
|
198
|
-
// Validate finite constraint (if specified, value must be finite)
|
|
199
|
-
if (args.finite === true && !Number.isFinite(numValue)) {
|
|
200
|
-
SetExceptionMessage(exc, `Vector${exc.index ? `[${exc.index}]` : ''} Must be Finite`);
|
|
201
|
-
ThrowException(exc);
|
|
202
|
-
}
|
|
203
|
-
// Validate integer constraint (if specified, value must be an integer)
|
|
204
|
-
if (args.integer === true && !Number.isInteger(numValue)) {
|
|
205
|
-
SetExceptionMessage(exc, `Vector${exc.index ? `[${exc.index}]` : ''} Must be an Integer`);
|
|
206
|
-
ThrowException(exc);
|
|
207
|
-
}
|
|
208
|
-
// Validate equality constraint (if specified, value must exactly match)
|
|
209
|
-
if (args.eq !== undefined && numValue !== args.eq) {
|
|
210
|
-
SetExceptionMessage(exc, `Vector${exc.index ? `[${exc.index}]` : ''} Must be equal to ${args.eq}`);
|
|
211
|
-
ThrowException(exc);
|
|
212
|
-
}
|
|
213
|
-
// Validate greater than constraint (exclusive - value must be strictly greater)
|
|
214
|
-
if (args.gt !== undefined && numValue <= args.gt) {
|
|
215
|
-
SetExceptionMessage(exc, `Vector${exc.index ? `[${exc.index}]` : ''} Must be greater than ${args.gt}`);
|
|
216
|
-
ThrowException(exc);
|
|
217
|
-
}
|
|
218
|
-
// Validate greater than or equal constraint (inclusive - value can equal the bound)
|
|
219
|
-
if (args.gte !== undefined && numValue < args.gte) {
|
|
220
|
-
SetExceptionMessage(exc, `Vector${exc.index ? `[${exc.index}]` : ''} Must be greater than or equal to ${args.gte}`);
|
|
221
|
-
ThrowException(exc);
|
|
222
|
-
}
|
|
223
|
-
// Validate less than constraint (exclusive - value must be strictly less)
|
|
224
|
-
if (args.lt !== undefined && numValue >= args.lt) {
|
|
225
|
-
SetExceptionMessage(exc, `Vector${exc.index ? `[${exc.index}]` : ''} Must be less than ${args.lt}`);
|
|
226
|
-
ThrowException(exc);
|
|
227
|
-
}
|
|
228
|
-
// Validate less than or equal constraint (inclusive - value can equal the bound)
|
|
229
|
-
if (args.lte !== undefined && numValue > args.lte) {
|
|
230
|
-
SetExceptionMessage(exc, `Vector${exc.index ? `[${exc.index}]` : ''} Must be less than or equal to ${args.lte}`);
|
|
231
|
-
ThrowException(exc);
|
|
232
|
-
}
|
|
233
|
-
}
|
|
234
|
-
/**
|
|
235
|
-
* Validates an array of vectors, ensuring each vector is valid and optionally
|
|
236
|
-
* enforcing that all vectors share the same size.
|
|
237
|
-
*
|
|
238
|
-
* @param vectors - The array of vectors to validate (must be non-empty)
|
|
239
|
-
* @param args - Validation constraints applied to each vector; set `sameSize: true`
|
|
240
|
-
* to require all vectors to have identical lengths
|
|
241
|
-
* @param exception - Custom exception details if validation fails
|
|
242
|
-
* @throws {VectorError} If the array is empty, any vector is invalid, or sizes
|
|
243
|
-
* differ when `sameSize` is `true`
|
|
244
|
-
*
|
|
245
|
-
* @example
|
|
246
|
-
* ```typescript
|
|
247
|
-
* // Validate an array of 3D vectors
|
|
248
|
-
* AssertVectors([[1, 2, 3], [4, 5, 6]]);
|
|
249
|
-
* // Require all vectors to share the same length
|
|
250
|
-
* AssertVectors([[1, 2], [3, 4]], { sameSize: true });
|
|
251
|
-
* // Throws because vectors have different sizes
|
|
252
|
-
* AssertVectors([[1, 2], [1, 2, 3]], { sameSize: true }); // throws
|
|
253
|
-
* ```
|
|
254
|
-
*/
|
|
255
|
-
export function AssertVectors(vectors, args, exception) {
|
|
256
|
-
const exc = exception ?? {};
|
|
257
|
-
exc.class ??= VectorError;
|
|
258
|
-
// Validate that vectors is an array of arrays
|
|
259
|
-
if (!Array.isArray(vectors)) {
|
|
260
|
-
SetExceptionMessage(exc, 'Vectors argument must be an array of vectors');
|
|
261
|
-
ThrowException(exc);
|
|
262
|
-
}
|
|
263
|
-
if (vectors.length === 0) {
|
|
264
|
-
SetExceptionMessage(exc, 'Vectors array is empty');
|
|
265
|
-
ThrowException(exc);
|
|
266
|
-
}
|
|
267
|
-
// Validate each vector and collect their sizes
|
|
268
|
-
const sizes = [];
|
|
269
|
-
for (let i = 0; i < vectors.length; i++) {
|
|
270
|
-
try {
|
|
271
|
-
AssertVector(vectors[i], args, { ...exc, index: i });
|
|
272
|
-
sizes.push(vectors[i].length);
|
|
273
|
-
}
|
|
274
|
-
catch (error) {
|
|
275
|
-
if (error instanceof VectorError) {
|
|
276
|
-
throw error;
|
|
277
|
-
}
|
|
278
|
-
SetExceptionMessage(exc, `Invalid vector at index ${i}: ${error.message}`);
|
|
279
|
-
exc.index = i;
|
|
280
|
-
ThrowException(exc);
|
|
281
|
-
}
|
|
282
|
-
}
|
|
283
|
-
// Check if all vectors have the same size if required
|
|
284
|
-
const requireSameSize = args?.sameSize ?? true;
|
|
285
|
-
if (requireSameSize) {
|
|
286
|
-
const [firstSize] = sizes;
|
|
287
|
-
for (let i = 1; i < sizes.length; i++) {
|
|
288
|
-
if (sizes[i] !== firstSize) {
|
|
289
|
-
SetExceptionMessage(exc, `Vectors at index 0 and ${i} do not have the same size (${firstSize} vs ${sizes[i]})`);
|
|
290
|
-
exc.index = i;
|
|
291
|
-
ThrowException(exc);
|
|
292
|
-
}
|
|
293
|
-
}
|
|
294
|
-
}
|
|
295
|
-
}
|
|
296
|
-
/**
|
|
297
|
-
* Validates that an unknown value is a valid vector without throwing an error.
|
|
298
|
-
*
|
|
299
|
-
* This function performs the same validation as AssertVector but returns
|
|
300
|
-
* a boolean instead of throwing an exception, making it suitable for
|
|
301
|
-
* conditional logic where exceptions are not desired.
|
|
302
|
-
*
|
|
303
|
-
* @param vector - The value to validate as a vector
|
|
304
|
-
* @param args - Validation configuration options
|
|
305
|
-
* @returns true if the vector is valid, false otherwise
|
|
306
|
-
*
|
|
307
75
|
* @example
|
|
308
76
|
* ```typescript
|
|
309
|
-
*
|
|
310
|
-
*
|
|
311
|
-
*
|
|
77
|
+
* AssertVector2([1, 2]); // passes
|
|
78
|
+
* AssertVector2([1, 2, 3]); // throws — too many components
|
|
79
|
+
* AssertVector2("not a vec"); // throws
|
|
312
80
|
* ```
|
|
313
81
|
*/
|
|
314
|
-
export function
|
|
82
|
+
export function AssertVector2(vector) {
|
|
315
83
|
try {
|
|
316
|
-
|
|
317
|
-
return true;
|
|
84
|
+
VECTOR2_SCHEMA.parse(vector);
|
|
318
85
|
}
|
|
319
|
-
catch {
|
|
320
|
-
|
|
86
|
+
catch (error) {
|
|
87
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
88
|
+
throw new VectorError(`Invalid 2D vector: ${message}`, {
|
|
89
|
+
cause: error instanceof Error ? error : undefined,
|
|
90
|
+
});
|
|
321
91
|
}
|
|
322
92
|
}
|
|
323
|
-
/**
|
|
324
|
-
* Validates that an unknown value is a valid 2D vector without throwing an error.
|
|
325
|
-
*
|
|
326
|
-
* @param vector - The value to validate as a 2D vector
|
|
327
|
-
* @returns true if the vector is valid, false otherwise
|
|
328
|
-
*
|
|
329
|
-
* @example
|
|
330
|
-
* ```typescript
|
|
331
|
-
* if (ValidateVector2([1, 2])) {
|
|
332
|
-
* // Process the valid 2D vector
|
|
333
|
-
* }
|
|
334
|
-
* ```
|
|
335
|
-
*/
|
|
336
93
|
export function ValidateVector2(vector) {
|
|
337
94
|
try {
|
|
338
95
|
AssertVector2(vector);
|
|
@@ -343,18 +100,30 @@ export function ValidateVector2(vector) {
|
|
|
343
100
|
}
|
|
344
101
|
}
|
|
345
102
|
/**
|
|
346
|
-
* Validates that an unknown value is a valid 3D vector
|
|
103
|
+
* Validates that an unknown value is a valid 3D vector (exactly 3 numeric components).
|
|
347
104
|
*
|
|
348
105
|
* @param vector - The value to validate as a 3D vector
|
|
349
|
-
* @
|
|
106
|
+
* @param exception - Custom exception details if validation fails
|
|
107
|
+
* @throws {VectorError} If the value is not a 3-component vector
|
|
350
108
|
*
|
|
351
109
|
* @example
|
|
352
110
|
* ```typescript
|
|
353
|
-
*
|
|
354
|
-
*
|
|
355
|
-
*
|
|
111
|
+
* AssertVector3([1, 2, 3]); // passes
|
|
112
|
+
* AssertVector3([1, 2]); // throws — too few components
|
|
113
|
+
* AssertVector3(null); // throws
|
|
356
114
|
* ```
|
|
357
115
|
*/
|
|
116
|
+
export function AssertVector3(vector) {
|
|
117
|
+
try {
|
|
118
|
+
VECTOR3_SCHEMA.parse(vector);
|
|
119
|
+
}
|
|
120
|
+
catch (error) {
|
|
121
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
122
|
+
throw new VectorError(`Invalid 3D vector: ${message}`, {
|
|
123
|
+
cause: error instanceof Error ? error : undefined,
|
|
124
|
+
});
|
|
125
|
+
}
|
|
126
|
+
}
|
|
358
127
|
export function ValidateVector3(vector) {
|
|
359
128
|
try {
|
|
360
129
|
AssertVector3(vector);
|
|
@@ -365,18 +134,30 @@ export function ValidateVector3(vector) {
|
|
|
365
134
|
}
|
|
366
135
|
}
|
|
367
136
|
/**
|
|
368
|
-
* Validates that an unknown value is a valid 4D vector
|
|
137
|
+
* Validates that an unknown value is a valid 4D vector (exactly 4 numeric components).
|
|
369
138
|
*
|
|
370
139
|
* @param vector - The value to validate as a 4D vector
|
|
371
|
-
* @
|
|
140
|
+
* @param exception - Custom exception details if validation fails
|
|
141
|
+
* @throws {VectorError} If the value is not a 4-component vector
|
|
372
142
|
*
|
|
373
143
|
* @example
|
|
374
144
|
* ```typescript
|
|
375
|
-
*
|
|
376
|
-
*
|
|
377
|
-
*
|
|
145
|
+
* AssertVector4([1, 2, 3, 4]); // passes
|
|
146
|
+
* AssertVector4([1, 2, 3]); // throws — too few components
|
|
147
|
+
* AssertVector4(undefined); // throws
|
|
378
148
|
* ```
|
|
379
149
|
*/
|
|
150
|
+
export function AssertVector4(vector) {
|
|
151
|
+
try {
|
|
152
|
+
VECTOR4_SCHEMA.parse(vector);
|
|
153
|
+
}
|
|
154
|
+
catch (error) {
|
|
155
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
156
|
+
throw new VectorError(`Invalid 4D vector: ${message}`, {
|
|
157
|
+
cause: error instanceof Error ? error : undefined,
|
|
158
|
+
});
|
|
159
|
+
}
|
|
160
|
+
}
|
|
380
161
|
export function ValidateVector4(vector) {
|
|
381
162
|
try {
|
|
382
163
|
AssertVector4(vector);
|
|
@@ -386,23 +167,54 @@ export function ValidateVector4(vector) {
|
|
|
386
167
|
return false;
|
|
387
168
|
}
|
|
388
169
|
}
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
170
|
+
export const VECTOR_SAME_SIZE_SCHEMA = z.array(VECTOR_SCHEMA).superRefine((vectors, ctx) => {
|
|
171
|
+
if (!Array.isArray(vectors) || vectors.length === 0) {
|
|
172
|
+
ctx.addIssue({
|
|
173
|
+
code: 'custom',
|
|
174
|
+
message: 'Input must be a non-empty array of vectors',
|
|
175
|
+
});
|
|
176
|
+
return;
|
|
177
|
+
}
|
|
178
|
+
const [firstVector] = vectors;
|
|
179
|
+
if (!Array.isArray(firstVector)) {
|
|
180
|
+
ctx.addIssue({
|
|
181
|
+
code: 'custom',
|
|
182
|
+
message: 'Each item must be an array representing a vector',
|
|
183
|
+
});
|
|
184
|
+
return;
|
|
185
|
+
}
|
|
186
|
+
const size = firstVector.length;
|
|
187
|
+
for (const vector of vectors) {
|
|
188
|
+
if (!Array.isArray(vector)) {
|
|
189
|
+
ctx.addIssue({
|
|
190
|
+
code: 'custom',
|
|
191
|
+
message: 'Each item must be an array representing a vector',
|
|
192
|
+
});
|
|
193
|
+
return;
|
|
194
|
+
}
|
|
195
|
+
if (vector.length !== size) {
|
|
196
|
+
ctx.addIssue({
|
|
197
|
+
code: 'custom',
|
|
198
|
+
message: `All vectors must have the same size. Expected size: ${size}, but got: ${vector.length}`,
|
|
199
|
+
});
|
|
200
|
+
return;
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
});
|
|
204
|
+
export function AssertVectorSameSize(vectors) {
|
|
205
|
+
try {
|
|
206
|
+
VECTOR_SAME_SIZE_SCHEMA.parse(vectors);
|
|
207
|
+
}
|
|
208
|
+
catch (error) {
|
|
209
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
210
|
+
throw new VectorError(`Vectors must have same size: ${message}`, {
|
|
211
|
+
cause: error instanceof Error ? error : undefined,
|
|
212
|
+
});
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
export function ValidateVectorSameSize(vectors) {
|
|
404
216
|
try {
|
|
405
|
-
|
|
217
|
+
AssertVectorSameSize(vectors);
|
|
406
218
|
return true;
|
|
407
219
|
}
|
|
408
220
|
catch {
|
|
@@ -410,26 +222,28 @@ export function ValidateVectorValue(value, args = {}) {
|
|
|
410
222
|
}
|
|
411
223
|
}
|
|
412
224
|
/**
|
|
413
|
-
* Validates that
|
|
225
|
+
* Validates that the given vector is not a zero vector (all components are not zero).
|
|
226
|
+
* Throws a VectorError if the vector is zero.
|
|
414
227
|
*
|
|
415
|
-
* @param
|
|
416
|
-
* @param
|
|
417
|
-
* @
|
|
228
|
+
* @param vector - The vector to validate
|
|
229
|
+
* @param label - The label for the vector used in the error message (default: 'Vector')
|
|
230
|
+
* @throws {VectorError} If the vector is a zero vector
|
|
418
231
|
*
|
|
419
232
|
* @example
|
|
420
233
|
* ```typescript
|
|
421
|
-
*
|
|
422
|
-
*
|
|
423
|
-
*
|
|
234
|
+
* const v = [1, 2, 3];
|
|
235
|
+
* AssertVectorNonZero(v); // Valid
|
|
236
|
+
*
|
|
237
|
+
* const zero = [0, 0, 0];
|
|
238
|
+
* AssertVectorNonZero(zero, 'Direction'); // Throws VectorError: Direction must not be zero
|
|
424
239
|
* ```
|
|
425
240
|
*/
|
|
426
|
-
export function
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
return false;
|
|
241
|
+
export function AssertVectorNonZero(vector, label = 'Vector') {
|
|
242
|
+
AssertVector(vector);
|
|
243
|
+
// Check if vector is zero (all components are 0)
|
|
244
|
+
const isZero = vector.every((v) => v === 0);
|
|
245
|
+
if (isZero) {
|
|
246
|
+
throw new VectorError(`${label} must not be zero`);
|
|
433
247
|
}
|
|
434
248
|
}
|
|
435
249
|
//# sourceMappingURL=asserts.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"asserts.js","sourceRoot":"","sources":["../../src/vectors/asserts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,
|
|
1
|
+
{"version":3,"file":"asserts.js","sourceRoot":"","sources":["../../src/vectors/asserts.ts"],"names":[],"mappings":"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"}
|