numpy-ts 0.2.0 → 0.4.0

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

@@ -1,9 +1,9 @@
 /**
  * Broadcasting utilities for NumPy-compatible array operations
  *
- * Wraps @stdlib broadcasting functions with NumPy-compatible API
+ * Implements NumPy broadcasting rules without external dependencies
  */
-type StdlibNDArray = any;
+import { ArrayStorage } from './storage';
 /**
  * Check if two or more shapes are broadcast-compatible
  * and compute the resulting output shape
@@ -35,21 +35,25 @@ export declare function computeBroadcastShape(shapes: readonly number[][]): numb
  */
 export declare function areBroadcastable(shape1: readonly number[], shape2: readonly number[]): boolean;
 /**
- * Broadcast multiple stdlib ndarrays to a common shape
+ * Broadcast an ArrayStorage to a target shape
+ * Returns a view with modified strides for broadcasting
  *
- * Returns read-only views of the input arrays broadcast to the same shape.
+ * @param storage - The storage to broadcast
+ * @param targetShape - The target shape to broadcast to
+ * @returns A new ArrayStorage view with broadcasting strides
+ */
+export declare function broadcastTo(storage: ArrayStorage, targetShape: readonly number[]): ArrayStorage;
+/**
+ * Broadcast multiple ArrayStorage objects to a common shape
+ *
+ * Returns views of the input arrays broadcast to the same shape.
  * Views share memory with the original arrays.
  *
- * @param arrays - Stdlib ndarrays to broadcast
- * @returns Array of broadcast stdlib ndarrays
+ * @param storages - ArrayStorage objects to broadcast
+ * @returns Array of broadcast ArrayStorage views
  * @throws Error if arrays have incompatible shapes
- *
- * @example
- * ```typescript
- * const [a, b] = broadcastStdlibArrays([arr1._data, arr2._data]);
- * ```
  */
-export declare function broadcastStdlibArrays(arrays: StdlibNDArray[]): StdlibNDArray[];
+export declare function broadcastArrays(storages: ArrayStorage[]): ArrayStorage[];
 /**
  * Generate a descriptive error message for broadcasting failures
  *
@@ -58,5 +62,4 @@ export declare function broadcastStdlibArrays(arrays: StdlibNDArray[]): StdlibND
  * @returns Error message string
  */
 export declare function broadcastErrorMessage(shapes: readonly number[][], operation?: string): string;
-export {};
 //# sourceMappingURL=broadcasting.d.ts.map

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

@@ -1,21 +1,19 @@
 /**
  * NDArray - NumPy-compatible multidimensional array
  *
- * Thin wrapper around @stdlib/ndarray providing NumPy-like API
+ * Core array class providing NumPy-like API
  */
 import { type DType, type TypedArray } from './dtype';
 import { ArrayStorage } from './storage';
-type StdlibNDArray = any;
 export declare class NDArray {
-    private _data;
-    private _dtype?;
+    private _storage;
     private _base?;
-    constructor(stdlibArray: StdlibNDArray, dtype?: DType, base?: NDArray);
+    constructor(storage: ArrayStorage, base?: NDArray);
     /**
      * Get internal storage (for ops modules)
      * @internal
      */
-    get _storage(): ArrayStorage;
+    get storage(): ArrayStorage;
     /**
      * Create NDArray from storage (for ops modules)
      * @internal
@@ -45,41 +43,16 @@ export declare class NDArray {
      * Get a single element from the array
      * @param indices - Array of indices, one per dimension (e.g., [0, 1] for 2D array)
      * @returns The element value (BigInt for int64/uint64, number otherwise)
-     *
-     * @example
-     * ```typescript
-     * const arr = array([[1, 2], [3, 4]]);
-     * arr.get([0, 1]);  // Returns 2
-     * arr.get([-1, -1]); // Returns 4 (negative indexing supported)
-     * ```
      */
     get(indices: number[]): number | bigint;
     /**
      * Set a single element in the array
      * @param indices - Array of indices, one per dimension (e.g., [0, 1] for 2D array)
      * @param value - Value to set (will be converted to array's dtype)
-     *
-     * @example
-     * ```typescript
-     * const arr = zeros([2, 3]);
-     * arr.set([0, 1], 42);  // Set element at position [0, 1] to 42
-     * arr.set([-1, -1], 99); // Set last element to 99 (negative indexing supported)
-     * ```
      */
     set(indices: number[], value: number | bigint): void;
     /**
      * Return a deep copy of the array
-     * Creates a new array with copied data (not a view)
-     *
-     * @returns Deep copy of the array
-     *
-     * @example
-     * ```typescript
-     * const arr = array([[1, 2], [3, 4]]);
-     * const copied = arr.copy();
-     * copied.set([0, 0], 99);  // Doesn't affect original
-     * console.log(arr.get([0, 0]));  // Still 1
-     * ```
      */
     copy(): NDArray;
     /**
@@ -90,16 +63,50 @@ export declare class NDArray {
      */
     astype(dtype: DType, copy?: boolean): NDArray;
     /**
-     * Helper method for element-wise operations with broadcasting
-     * @private
+     * Element-wise addition
+     * @param other - Array or scalar to add
+     * @returns Result of addition with broadcasting
      */
     add(other: NDArray | number): NDArray;
+    /**
+     * Element-wise subtraction
+     * @param other - Array or scalar to subtract
+     * @returns Result of subtraction with broadcasting
+     */
     subtract(other: NDArray | number): NDArray;
+    /**
+     * Element-wise multiplication
+     * @param other - Array or scalar to multiply
+     * @returns Result of multiplication with broadcasting
+     */
     multiply(other: NDArray | number): NDArray;
+    /**
+     * Element-wise division
+     * @param other - Array or scalar to divide by
+     * @returns Result of division with broadcasting
+     */
     divide(other: NDArray | number): NDArray;
+    /**
+     * Element-wise modulo operation
+     * @param other - Array or scalar divisor
+     * @returns Remainder after division
+     */
     mod(other: NDArray | number): NDArray;
+    /**
+     * Element-wise floor division
+     * @param other - Array or scalar to divide by
+     * @returns Floor of the quotient
+     */
     floor_divide(other: NDArray | number): NDArray;
+    /**
+     * Numerical positive (element-wise +x)
+     * @returns Copy of the array
+     */
     positive(): NDArray;
+    /**
+     * Element-wise reciprocal (1/x)
+     * @returns New array with reciprocals
+     */
     reciprocal(): NDArray;
     /**
      * Square root of each element
@@ -173,15 +180,15 @@ export declare class NDArray {
      * @returns Boolean array (represented as uint8: 1=true, 0=false)
      */
     isclose(other: NDArray | number, rtol?: number, atol?: number): NDArray;
-    allclose(other: NDArray | number, rtol?: number, atol?: number): boolean;
     /**
-     * Helper method for isclose operation with broadcasting
-     * @private
-     */
-    /**
-     * Helper method for comparison operations with broadcasting
-     * @private
+     * Element-wise comparison with tolerance
+     * Returns True where |a - b| <= (atol + rtol * |b|)
+     * @param other - Value or array to compare with
+     * @param rtol - Relative tolerance (default: 1e-5)
+     * @param atol - Absolute tolerance (default: 1e-8)
+     * @returns Boolean array (represented as uint8: 1=true, 0=false)
      */
+    allclose(other: NDArray | number, rtol?: number, atol?: number): boolean;
     /**
      * Sum array elements over a given axis
      * @param axis - Axis along which to sum. If undefined, sum all elements
@@ -296,20 +303,47 @@ export declare class NDArray {
      * @returns Array with additional dimension (always a view)
      */
     expand_dims(axis: number): NDArray;
+    /**
+     * Matrix multiplication
+     * @param other - Array to multiply with
+     * @returns Result of matrix multiplication
+     */
     matmul(other: NDArray): NDArray;
+    /**
+     * Dot product (matching NumPy behavior)
+     * @param other - Array to dot with
+     * @returns Result of dot product (scalar or array depending on dimensions)
+     */
+    dot(other: NDArray): NDArray | number | bigint;
+    /**
+     * Sum of diagonal elements (trace)
+     * @returns Sum of diagonal elements
+     */
+    trace(): number | bigint;
+    /**
+     * Inner product (contracts over last axes of both arrays)
+     * @param other - Array to compute inner product with
+     * @returns Inner product result
+     */
+    inner(other: NDArray): NDArray | number | bigint;
+    /**
+     * Outer product (flattens inputs then computes a[i]*b[j])
+     * @param other - Array to compute outer product with
+     * @returns 2D outer product matrix
+     */
+    outer(other: NDArray): NDArray;
+    /**
+     * Tensor dot product along specified axes
+     * @param other - Array to contract with
+     * @param axes - Axes to contract (integer or [a_axes, b_axes])
+     * @returns Tensor dot product result
+     */
+    tensordot(other: NDArray, axes?: number | [number[], number[]]): NDArray | number | bigint;
     /**
      * Slice the array using NumPy-style string syntax
      *
      * @param sliceStrs - Slice specifications, one per dimension
      * @returns Sliced view of the array
-     *
-     * @example
-     * ```typescript
-     * const arr = array([[1, 2, 3], [4, 5, 6], [7, 8, 9]]);
-     * const row = arr.slice('0', ':');     // First row: [1, 2, 3]
-     * const col = arr.slice(':', '1');     // Second column: [2, 5, 8]
-     * const sub = arr.slice('0:2', '1:3'); // Top-right 2x2: [[2, 3], [5, 6]]
-     * ```
      */
     slice(...sliceStrs: string[]): NDArray;
     /**
@@ -338,87 +372,271 @@ export declare class NDArray {
      * @returns Columns as array
      */
     cols(start: number, stop: number): NDArray;
+    /**
+     * String representation of the array
+     * @returns String describing the array shape and dtype
+     */
     toString(): string;
+    /**
+     * Convert to nested JavaScript array
+     * @returns Nested JavaScript array representation
+     */
     toArray(): any;
 }
 /**
  * Create array of zeros
+ * @param shape - Shape of the array
+ * @param dtype - Data type (default: float64)
+ * @returns Array filled with zeros
  */
 export declare function zeros(shape: number[], dtype?: DType): NDArray;
 /**
  * Create array of ones
+ * @param shape - Shape of the array
+ * @param dtype - Data type (default: float64)
+ * @returns Array filled with ones
  */
 export declare function ones(shape: number[], dtype?: DType): NDArray;
+/**
+ * Create array from nested JavaScript arrays
+ * @param data - Nested arrays or existing NDArray
+ * @param dtype - Data type (optional, will be inferred if not provided)
+ * @returns New NDArray
+ */
 export declare function array(data: any, dtype?: DType): NDArray;
 /**
  * Create array with evenly spaced values within a given interval
- * Similar to Python's range() but returns floats
+ * Similar to Python's range() but returns array
+ * @param start - Start value (or stop if only one argument)
+ * @param stop - Stop value (exclusive)
+ * @param step - Step between values (default: 1)
+ * @param dtype - Data type (default: float64)
+ * @returns Array of evenly spaced values
  */
 export declare function arange(start: number, stop?: number, step?: number, dtype?: DType): NDArray;
 /**
  * Create array with evenly spaced values over a specified interval
+ * @param start - Starting value
+ * @param stop - Ending value (inclusive)
+ * @param num - Number of samples (default: 50)
+ * @param dtype - Data type (default: float64)
+ * @returns Array of evenly spaced values
  */
 export declare function linspace(start: number, stop: number, num?: number, dtype?: DType): NDArray;
 /**
  * Create array with logarithmically spaced values
  * Returns num samples, equally spaced on a log scale from base^start to base^stop
+ * @param start - base^start is the starting value
+ * @param stop - base^stop is the ending value
+ * @param num - Number of samples (default: 50)
+ * @param base - Base of the log space (default: 10.0)
+ * @param dtype - Data type (default: float64)
+ * @returns Array of logarithmically spaced values
  */
 export declare function logspace(start: number, stop: number, num?: number, base?: number, dtype?: DType): NDArray;
 /**
  * Create array with geometrically spaced values
  * Returns num samples, equally spaced on a log scale (geometric progression)
+ * @param start - Starting value
+ * @param stop - Ending value
+ * @param num - Number of samples (default: 50)
+ * @param dtype - Data type (default: float64)
+ * @returns Array of geometrically spaced values
  */
 export declare function geomspace(start: number, stop: number, num?: number, dtype?: DType): NDArray;
 /**
  * Create identity matrix
+ * @param n - Number of rows
+ * @param m - Number of columns (default: n)
+ * @param k - Index of diagonal (0 for main diagonal, positive for upper, negative for lower)
+ * @param dtype - Data type (default: float64)
+ * @returns Identity matrix
  */
 export declare function eye(n: number, m?: number, k?: number, dtype?: DType): NDArray;
 /**
  * Create an uninitialized array
- * Note: Unlike NumPy, TypedArrays are zero-initialized by default in JavaScript
+ * Note: TypedArrays are zero-initialized by default in JavaScript
+ * @param shape - Shape of the array
+ * @param dtype - Data type (default: float64)
+ * @returns Uninitialized array
  */
 export declare function empty(shape: number[], dtype?: DType): NDArray;
 /**
  * Create array filled with a constant value
+ * @param shape - Shape of the array
+ * @param fill_value - Value to fill the array with
+ * @param dtype - Data type (optional, inferred from fill_value if not provided)
+ * @returns Array filled with the constant value
  */
 export declare function full(shape: number[], fill_value: number | bigint | boolean, dtype?: DType): NDArray;
 /**
  * Create a square identity matrix
+ * @param n - Size of the square matrix
+ * @param dtype - Data type (default: float64)
+ * @returns n×n identity matrix
  */
 export declare function identity(n: number, dtype?: DType): NDArray;
 /**
  * Convert input to an ndarray
- * If input is already an NDArray, optionally convert dtype
+ * @param a - Input data (array-like or NDArray)
+ * @param dtype - Data type (optional)
+ * @returns NDArray representation of the input
  */
 export declare function asarray(a: NDArray | any, dtype?: DType): NDArray;
 /**
  * Create a deep copy of an array
+ * @param a - Array to copy
+ * @returns Deep copy of the array
  */
 export declare function copy(a: NDArray): NDArray;
 /**
  * Create array of zeros with the same shape as another array
+ * @param a - Array to match shape from
+ * @param dtype - Data type (optional, uses a's dtype if not provided)
+ * @returns Array of zeros
  */
 export declare function zeros_like(a: NDArray, dtype?: DType): NDArray;
 /**
  * Create array of ones with the same shape as another array
+ * @param a - Array to match shape from
+ * @param dtype - Data type (optional, uses a's dtype if not provided)
+ * @returns Array of ones
  */
 export declare function ones_like(a: NDArray, dtype?: DType): NDArray;
 /**
  * Create uninitialized array with the same shape as another array
+ * @param a - Array to match shape from
+ * @param dtype - Data type (optional, uses a's dtype if not provided)
+ * @returns Uninitialized array
  */
 export declare function empty_like(a: NDArray, dtype?: DType): NDArray;
 /**
  * Create array filled with a constant value, same shape as another array
+ * @param a - Array to match shape from
+ * @param fill_value - Value to fill with
+ * @param dtype - Data type (optional, uses a's dtype if not provided)
+ * @returns Filled array
  */
 export declare function full_like(a: NDArray, fill_value: number | bigint | boolean, dtype?: DType): NDArray;
+/**
+ * Element-wise square root
+ * @param x - Input array
+ * @returns Array of square roots
+ */
 export declare function sqrt(x: NDArray): NDArray;
+/**
+ * Element-wise power
+ * @param x - Base array
+ * @param exponent - Exponent (array or scalar)
+ * @returns Array of x raised to exponent
+ */
 export declare function power(x: NDArray, exponent: NDArray | number): NDArray;
+/**
+ * Element-wise absolute value
+ * @param x - Input array
+ * @returns Array of absolute values
+ */
 export declare function absolute(x: NDArray): NDArray;
+/**
+ * Element-wise negation
+ * @param x - Input array
+ * @returns Array of negated values
+ */
 export declare function negative(x: NDArray): NDArray;
+/**
+ * Element-wise sign (-1, 0, or 1)
+ * @param x - Input array
+ * @returns Array of signs
+ */
 export declare function sign(x: NDArray): NDArray;
+/**
+ * Element-wise modulo
+ * @param x - Dividend array
+ * @param divisor - Divisor (array or scalar)
+ * @returns Remainder after division
+ */
 export declare function mod(x: NDArray, divisor: NDArray | number): NDArray;
+/**
+ * Element-wise floor division
+ * @param x - Dividend array
+ * @param divisor - Divisor (array or scalar)
+ * @returns Floor of the quotient
+ */
 export declare function floor_divide(x: NDArray, divisor: NDArray | number): NDArray;
+/**
+ * Element-wise positive (unary +)
+ * @param x - Input array
+ * @returns Copy of the array
+ */
 export declare function positive(x: NDArray): NDArray;
+/**
+ * Element-wise reciprocal (1/x)
+ * @param x - Input array
+ * @returns Array of reciprocals
+ */
 export declare function reciprocal(x: NDArray): NDArray;
-export {};
+/**
+ * Dot product of two arrays
+ *
+ * Fully NumPy-compatible. Behavior depends on input dimensions:
+ * - 0D · 0D: Multiply scalars → scalar
+ * - 0D · ND or ND · 0D: Element-wise multiply → ND
+ * - 1D · 1D: Inner product → scalar
+ * - 2D · 2D: Matrix multiplication → 2D
+ * - 2D · 1D: Matrix-vector product → 1D
+ * - 1D · 2D: Vector-matrix product → 1D
+ * - ND · 1D (N>2): Sum over last axis → (N-1)D
+ * - 1D · ND (N>2): Sum over first axis → (N-1)D
+ * - ND · MD (N,M≥2): Tensor contraction → (N+M-2)D
+ *
+ * @param a - First array
+ * @param b - Second array
+ * @returns Result of dot product
+ */
+export declare function dot(a: NDArray, b: NDArray): NDArray | number | bigint;
+/**
+ * Sum of diagonal elements
+ *
+ * @param a - Input 2D array
+ * @returns Sum of diagonal elements
+ */
+export declare function trace(a: NDArray): number | bigint;
+/**
+ * Permute array dimensions
+ *
+ * @param a - Input array
+ * @param axes - Optional permutation of axes (defaults to reverse order)
+ * @returns Transposed view
+ */
+export declare function transpose(a: NDArray, axes?: number[]): NDArray;
+/**
+ * Inner product of two arrays
+ *
+ * Contracts over last axes of both arrays.
+ * Result shape: (*a.shape[:-1], *b.shape[:-1])
+ *
+ * @param a - First array
+ * @param b - Second array
+ * @returns Inner product result
+ */
+export declare function inner(a: NDArray, b: NDArray): NDArray | number | bigint;
+/**
+ * Outer product of two arrays
+ *
+ * Flattens inputs then computes result[i,j] = a[i] * b[j]
+ *
+ * @param a - First array
+ * @param b - Second array
+ * @returns 2D outer product matrix
+ */
+export declare function outer(a: NDArray, b: NDArray): NDArray;
+/**
+ * Tensor dot product along specified axes
+ *
+ * @param a - First array
+ * @param b - Second array
+ * @param axes - Axes to contract (integer or [a_axes, b_axes])
+ * @returns Tensor dot product
+ */
+export declare function tensordot(a: NDArray, b: NDArray, axes?: number | [number[], number[]]): NDArray | number | bigint;
 //# sourceMappingURL=ndarray.d.ts.map

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

@@ -1,21 +1,22 @@
 /**
  * ArrayStorage - Internal storage abstraction
  *
- * Wraps @stdlib/ndarray to provide a clean internal interface
- * while keeping stdlib as an implementation detail.
+ * Stores array data directly using TypedArrays without external dependencies.
  *
  * @internal - This is not part of the public API
  */
-import type { ndarray as StdlibNDArray } from '@stdlib/types/ndarray';
 import { type DType, type TypedArray } from './dtype';
 /**
  * Internal storage for NDArray data
  * Manages the underlying TypedArray and metadata
  */
 export declare class ArrayStorage {
-    private _stdlib;
+    private _data;
+    private _shape;
+    private _strides;
+    private _offset;
     private _dtype;
-    constructor(stdlibArray: StdlibNDArray, dt?: DType);
+    constructor(data: TypedArray, shape: readonly number[], strides: readonly number[], offset: number, dtype: DType);
     /**
      * Shape of the array
      */
@@ -41,10 +42,9 @@ export declare class ArrayStorage {
      */
     get strides(): readonly number[];
     /**
-     * Direct access to stdlib ndarray (for internal use)
-     * @internal
+     * Offset into the data buffer
      */
-    get stdlib(): StdlibNDArray;
+    get offset(): number;
     /**
      * Check if array is C-contiguous (row-major, no gaps)
      */
@@ -54,17 +54,29 @@ export declare class ArrayStorage {
      */
     get isFContiguous(): boolean;
     /**
-     * Create a deep copy of this storage
+     * Get element at linear index (respects strides and offset)
      */
-    copy(): ArrayStorage;
+    iget(linearIndex: number): number | bigint;
+    /**
+     * Set element at linear index (respects strides and offset)
+     */
+    iset(linearIndex: number, value: number | bigint): void;
+    /**
+     * Get element at multi-index position
+     */
+    get(...indices: number[]): number | bigint;
+    /**
+     * Set element at multi-index position
+     */
+    set(indices: number[], value: number | bigint): void;
     /**
-     * Create storage from stdlib ndarray
+     * Create a deep copy of this storage
      */
-    static fromStdlib(stdlibArray: StdlibNDArray, dtype?: DType): ArrayStorage;
+    copy(): ArrayStorage;
     /**
      * Create storage from TypedArray data
      */
-    static fromData(data: TypedArray, shape: number[], dtype: DType): ArrayStorage;
+    static fromData(data: TypedArray, shape: number[], dtype: DType, strides?: number[], offset?: number): ArrayStorage;
     /**
      * Create storage with zeros
      */
@@ -73,11 +85,6 @@ export declare class ArrayStorage {
      * Create storage with ones
      */
     static ones(shape: number[], dtype?: DType): ArrayStorage;
-    /**
-     * Compute strides for row-major (C-order) layout
-     * @private
-     */
-    private _computeStrides;
     /**
      * Compute strides for row-major (C-order) layout
      * @private

package/dist/types/index.d.ts

@@ -3,6 +3,6 @@
  *
  * @module numpy-ts
  */
-export { NDArray, zeros, ones, array, arange, linspace, logspace, geomspace, eye, empty, full, identity, asarray, copy, zeros_like, ones_like, empty_like, full_like, sqrt, power, absolute, negative, sign, mod, floor_divide, positive, reciprocal, } from './core/ndarray';
+export { NDArray, zeros, ones, array, arange, linspace, logspace, geomspace, eye, empty, full, identity, asarray, copy, zeros_like, ones_like, empty_like, full_like, sqrt, power, absolute, negative, sign, mod, floor_divide, positive, reciprocal, dot, trace, transpose, inner, outer, tensordot, } from './core/ndarray';
 export declare const __version__: string;
 //# sourceMappingURL=index.d.ts.map

package/dist/types/internal/compute.d.ts

@@ -7,9 +7,18 @@
  * @internal
  */
 import { ArrayStorage } from '../core/storage';
+/**
+ * Compute the broadcast shape of two arrays
+ * Returns the shape that results from broadcasting a and b together
+ * Throws if shapes are not compatible for broadcasting
+ */
+export declare function broadcastShapes(shapeA: readonly number[], shapeB: readonly number[]): number[];
 /**
  * Perform element-wise operation with broadcasting
  *
+ * NOTE: This is the slow path for broadcasting/non-contiguous arrays.
+ * Fast paths for contiguous arrays are implemented directly in ops/arithmetic.ts
+ *
  * @param a - First array storage
  * @param b - Second array storage
  * @param op - Operation to perform (a, b) => result