numpy-ts 0.9.0 → 0.11.0

package/dist/types/core/complex.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Complex number class for numpy-ts
+ *
+ * Represents complex numbers in JavaScript, similar to Python's complex type.
+ * Used when converting complex arrays to JavaScript values via toArray().
+ */
+/**
+ * Represents a complex number with real and imaginary parts.
+ *
+ * @example
+ * ```typescript
+ * const z = new Complex(1, 2);  // 1 + 2i
+ * console.log(z.re);  // 1
+ * console.log(z.im);  // 2
+ * console.log(z.toString());  // "(1+2j)"
+ * ```
+ */
+export declare class Complex {
+    /** Real part */
+    readonly re: number;
+    /** Imaginary part */
+    readonly im: number;
+    constructor(re: number, im?: number);
+    /**
+     * Returns the magnitude (absolute value) of the complex number.
+     * |z| = sqrt(re² + im²)
+     */
+    abs(): number;
+    /**
+     * Returns the phase angle (argument) of the complex number in radians.
+     * arg(z) = atan2(im, re)
+     */
+    angle(): number;
+    /**
+     * Returns the complex conjugate.
+     * conj(a + bi) = a - bi
+     */
+    conj(): Complex;
+    /**
+     * Add another complex number or real number.
+     */
+    add(other: Complex | number): Complex;
+    /**
+     * Subtract another complex number or real number.
+     */
+    sub(other: Complex | number): Complex;
+    /**
+     * Multiply by another complex number or real number.
+     * (a + bi)(c + di) = (ac - bd) + (ad + bc)i
+     */
+    mul(other: Complex | number): Complex;
+    /**
+     * Divide by another complex number or real number.
+     * (a + bi) / (c + di) = ((ac + bd) + (bc - ad)i) / (c² + d²)
+     */
+    div(other: Complex | number): Complex;
+    /**
+     * Returns the negation of this complex number.
+     */
+    neg(): Complex;
+    /**
+     * Check equality with another complex number.
+     */
+    equals(other: Complex): boolean;
+    /**
+     * String representation matching NumPy/Python format: "(a+bj)"
+     */
+    toString(): string;
+    /**
+     * Create a Complex from various input formats.
+     * Accepts:
+     * - Complex instance
+     * - {re, im} object
+     * - [re, im] array
+     * - number (creates re + 0i)
+     */
+    static from(value: ComplexInput): Complex;
+    /**
+     * Check if a value is a complex number representation.
+     */
+    static isComplex(value: unknown): value is ComplexInput;
+}
+/**
+ * Input types that can be converted to Complex.
+ */
+export type ComplexInput = Complex | {
+    re: number;
+    im?: number;
+} | [number, number] | number;
+/**
+ * Helper to check if a value looks like a complex number input.
+ */
+export declare function isComplexLike(value: unknown): value is ComplexInput;
+//# sourceMappingURL=complex.d.ts.map

package/dist/types/core/dtype.d.ts

@@ -3,6 +3,7 @@
  *
  * Supports NumPy numeric types:
  * - Floating point: float32, float64
+ * - Complex: complex64, complex128
  * - Signed integers: int8, int16, int32, int64
  * - Unsigned integers: uint8, uint16, uint32, uint64
  * - Boolean: bool
@@ -10,7 +11,7 @@
 /**
  * All supported dtypes
  */
-export type DType = 'float64' | 'float32' | 'int64' | 'int32' | 'int16' | 'int8' | 'uint64' | 'uint32' | 'uint16' | 'uint8' | 'bool';
+export type DType = 'float64' | 'float32' | 'complex128' | 'complex64' | 'int64' | 'int32' | 'int16' | 'int8' | 'uint64' | 'uint32' | 'uint16' | 'uint8' | 'bool';
 /**
  * TypedArray types for each dtype
  */
@@ -20,12 +21,16 @@ export type TypedArray = Float64Array | Float32Array | BigInt64Array | Int32Arra
  */
 export declare const DEFAULT_DTYPE: DType;
 /**
- * Get the TypedArray constructor for a given dtype
+ * Get the TypedArray constructor for a given dtype.
+ * For complex types, returns the underlying float array constructor.
+ * complex128 uses Float64Array, complex64 uses Float32Array.
+ * Note: Complex arrays have 2x the physical elements (interleaved real, imag).
  */
 export declare function getTypedArrayConstructor(dtype: DType): TypedArrayConstructor | null;
 type TypedArrayConstructor = Float64ArrayConstructor | Float32ArrayConstructor | BigInt64ArrayConstructor | Int32ArrayConstructor | Int16ArrayConstructor | Int8ArrayConstructor | BigUint64ArrayConstructor | Uint32ArrayConstructor | Uint16ArrayConstructor | Uint8ArrayConstructor;
 /**
- * Get the element size in bytes for a given dtype
+ * Get the element size in bytes for a given dtype.
+ * For complex types, returns the full element size (both real and imag parts).
  */
 export declare function getDTypeSize(dtype: DType): number;
 /**
@@ -40,6 +45,60 @@ export declare function isFloatDType(dtype: DType): boolean;
  * Check if dtype uses BigInt
  */
 export declare function isBigIntDType(dtype: DType): boolean;
+/**
+ * Check if dtype is complex
+ */
+export declare function isComplexDType(dtype: DType): boolean;
+/**
+ * Throw a TypeError if the dtype is complex.
+ * Use this at the start of functions that don't support complex numbers.
+ *
+ * @param dtype - The dtype to check
+ * @param functionName - The name of the function (for error message)
+ * @param reason - Optional reason why complex is not supported
+ * @throws TypeError if dtype is complex
+ *
+ * @example
+ * ```typescript
+ * export function floor(storage: ArrayStorage): ArrayStorage {
+ *   throwIfComplex(storage.dtype, 'floor', 'rounding is not defined for complex numbers');
+ *   // ... rest of implementation
+ * }
+ * ```
+ */
+export declare function throwIfComplex(dtype: DType, functionName: string, reason?: string): void;
+/**
+ * Throw an error if the dtype is complex and the function doesn't yet support it.
+ * Use this for functions that SHOULD support complex but haven't been implemented yet.
+ *
+ * @param dtype - The dtype to check
+ * @param functionName - The name of the function (for error message)
+ * @throws Error if dtype is complex
+ *
+ * @example
+ * ```typescript
+ * export function sin(storage: ArrayStorage): ArrayStorage {
+ *   throwIfComplexNotImplemented(storage.dtype, 'sin');
+ *   // ... existing real-only implementation
+ * }
+ * ```
+ */
+export declare function throwIfComplexNotImplemented(dtype: DType, functionName: string): void;
+/**
+ * Get the underlying float dtype for a complex dtype.
+ * complex128 -> float64, complex64 -> float32
+ */
+export declare function getComplexComponentDType(dtype: DType): 'float64' | 'float32';
+/**
+ * Get the complex dtype for a given float component dtype.
+ * float64 -> complex128, float32 -> complex64
+ */
+export declare function getComplexDType(componentDtype: 'float64' | 'float32'): 'complex128' | 'complex64';
+/**
+ * Check if a value looks like a complex number input.
+ * Accepts: Complex instance, {re, im} object
+ */
+export declare function isComplexLike(value: unknown): boolean;
 /**
  * Infer dtype from JavaScript value
  */