numpy-ts 0.2.0 → 0.3.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,17 @@ 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;
     /**
      * 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 +342,207 @@ 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 {};
 //# 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/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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "numpy-ts",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Complete NumPy implementation for TypeScript and JavaScript (under construction)",
   "main": "dist/numpy-ts.node.cjs",
   "browser": "dist/numpy-ts.browser.js",
@@ -54,8 +54,10 @@
     "bench:build": "esbuild benchmarks/src/index.ts --bundle --platform=node --format=cjs --outfile=benchmarks/dist/bench.cjs",
     "bench": "npm run bench:build && node benchmarks/dist/bench.cjs",
     "bench:quick": "npm run bench:build && node benchmarks/dist/bench.cjs --quick",
+    "bench:large": "npm run bench:build && node benchmarks/dist/bench.cjs --large",
     "bench:category": "npm run bench:build && node benchmarks/dist/bench.cjs --category",
-    "bench:view": "open benchmarks/results/plots/latest.html || xdg-open benchmarks/results/plots/latest.html"
+    "bench:view": "open benchmarks/results/plots/latest.html || xdg-open benchmarks/results/plots/latest.html",
+    "bench:large:view": "open benchmarks/results/plots/latest-large.html || xdg-open benchmarks/results/plots/latest-large.html"
   },
   "keywords": [
     "numpy",
@@ -104,12 +106,14 @@
     "vitest": "^4.0.3"
   },
   "dependencies": {
-    "@stdlib/blas": "^0.3.3",
-    "@stdlib/ndarray": "^0.3.3"
+    "@stdlib/blas": "^0.3.3"
   },
   "engines": {
     "node": ">=18.0.0"
   },
+  "overrides": {
+    "js-yaml": ">=4.1.1"
+  },
   "lint-staged": {
     "*.ts": [
       "eslint --fix",