numpy-ts 0.3.0 → 0.5.0

package/dist/types/io/npz/parser.d.ts

@@ -0,0 +1,57 @@
+/**
+ * NPZ file parser
+ *
+ * NPZ is a ZIP archive containing multiple .npy files.
+ */
+import { NDArray } from '../../core/ndarray';
+/**
+ * Options for parsing NPZ files
+ */
+export interface NpzParseOptions {
+    /**
+     * If true, skip arrays with unsupported dtypes instead of throwing an error.
+     * Skipped arrays will not be included in the result.
+     * Default: false
+     */
+    force?: boolean;
+}
+/**
+ * Result of parsing an NPZ file
+ */
+export interface NpzParseResult {
+    /** Successfully parsed arrays */
+    arrays: Map<string, NDArray>;
+    /** Names of arrays that were skipped due to unsupported dtypes (only when force=true) */
+    skipped: string[];
+    /** Error messages for skipped arrays */
+    errors: Map<string, string>;
+}
+/**
+ * Parse an NPZ file from bytes
+ *
+ * @param buffer - The NPZ file contents
+ * @param options - Parse options
+ * @returns Promise resolving to parsed arrays
+ */
+export declare function parseNpz(buffer: ArrayBuffer | Uint8Array, options?: NpzParseOptions): Promise<NpzParseResult>;
+/**
+ * Synchronously parse an NPZ file (only works if not DEFLATE compressed)
+ *
+ * @param buffer - The NPZ file contents
+ * @param options - Parse options
+ * @returns Parsed arrays
+ */
+export declare function parseNpzSync(buffer: ArrayBuffer | Uint8Array, options?: NpzParseOptions): NpzParseResult;
+/**
+ * Convenience function to get arrays as a plain object
+ *
+ * @param buffer - The NPZ file contents
+ * @param options - Parse options
+ * @returns Promise resolving to object with array names as keys
+ */
+export declare function loadNpz(buffer: ArrayBuffer | Uint8Array, options?: NpzParseOptions): Promise<Record<string, NDArray>>;
+/**
+ * Synchronous version of loadNpz
+ */
+export declare function loadNpzSync(buffer: ArrayBuffer | Uint8Array, options?: NpzParseOptions): Record<string, NDArray>;
+//# sourceMappingURL=parser.d.ts.map

package/dist/types/io/npz/serializer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * NPZ file serializer
+ *
+ * Serializes multiple NDArrays to NPZ format (ZIP archive of .npy files).
+ */
+import { NDArray } from '../../core/ndarray';
+/**
+ * Input type for arrays - supports:
+ * - Array of NDArrays (positional, named arr_0, arr_1, etc.)
+ * - Map of names to NDArrays
+ * - Object with names as keys
+ */
+export type NpzArraysInput = NDArray[] | Map<string, NDArray> | Record<string, NDArray>;
+/**
+ * Options for serializing NPZ files
+ */
+export interface NpzSerializeOptions {
+    /**
+     * Whether to compress the NPZ file using DEFLATE.
+     * Default: false (matches np.savez behavior; use true for np.savez_compressed behavior)
+     */
+    compress?: boolean;
+}
+/**
+ * Serialize multiple arrays to NPZ format
+ *
+ * @param arrays - Arrays to save. Can be:
+ *   - An array of NDArrays (named arr_0, arr_1, etc. like np.savez positional args)
+ *   - A Map of names to NDArrays
+ *   - An object with names as keys (like np.savez keyword args)
+ * @param options - Serialization options
+ * @returns Promise resolving to NPZ file as Uint8Array
+ *
+ * @example
+ * // Positional arrays (named arr_0, arr_1)
+ * await serializeNpz([arr1, arr2])
+ *
+ * // Named arrays
+ * await serializeNpz({ x: arr1, y: arr2 })
+ */
+export declare function serializeNpz(arrays: NpzArraysInput, options?: NpzSerializeOptions): Promise<Uint8Array>;
+/**
+ * Synchronously serialize multiple arrays to NPZ format (no compression)
+ *
+ * @param arrays - Arrays to save (same input types as serializeNpz)
+ * @returns NPZ file as Uint8Array
+ */
+export declare function serializeNpzSync(arrays: NpzArraysInput): Uint8Array;
+//# sourceMappingURL=serializer.d.ts.map

package/dist/types/io/zip/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Minimal ZIP file reading and writing
+ */
+export { readZip, readZipSync } from './reader';
+export { writeZip, writeZipSync, type ZipWriteOptions } from './writer';
+export { crc32, ZIP_STORED, ZIP_DEFLATED } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/io/zip/reader.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Minimal ZIP file reader
+ *
+ * Reads ZIP files with STORED or DEFLATE compression.
+ * Uses the Compression Streams API (built into modern browsers and Node.js 18+).
+ */
+/**
+ * Read a ZIP file and return its entries
+ *
+ * @param buffer - ZIP file contents
+ * @returns Map of file names to their uncompressed data
+ */
+export declare function readZip(buffer: ArrayBuffer | Uint8Array): Promise<Map<string, Uint8Array>>;
+/**
+ * Synchronously read a ZIP file (only works for STORED entries)
+ *
+ * @param buffer - ZIP file contents
+ * @returns Map of file names to their uncompressed data
+ * @throws Error if any entry uses compression
+ */
+export declare function readZipSync(buffer: ArrayBuffer | Uint8Array): Map<string, Uint8Array>;
+//# sourceMappingURL=reader.d.ts.map

package/dist/types/io/zip/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ZIP file format types and constants
+ */
+/**
+ * ZIP local file header signature
+ */
+export declare const ZIP_LOCAL_SIGNATURE = 67324752;
+/**
+ * ZIP central directory header signature
+ */
+export declare const ZIP_CENTRAL_SIGNATURE = 33639248;
+/**
+ * ZIP end of central directory signature
+ */
+export declare const ZIP_END_SIGNATURE = 101010256;
+/**
+ * Compression methods
+ */
+export declare const ZIP_STORED = 0;
+export declare const ZIP_DEFLATED = 8;
+/**
+ * Entry in a ZIP file
+ */
+export interface ZipEntry {
+    /** File name */
+    name: string;
+    /** Uncompressed data */
+    data: Uint8Array;
+    /** Compression method used */
+    compressionMethod: number;
+    /** CRC-32 checksum */
+    crc32: number;
+    /** Compressed size */
+    compressedSize: number;
+    /** Uncompressed size */
+    uncompressedSize: number;
+}
+/**
+ * Raw entry as read from ZIP (before decompression)
+ */
+export interface RawZipEntry {
+    /** File name */
+    name: string;
+    /** Compressed data */
+    compressedData: Uint8Array;
+    /** Compression method */
+    compressionMethod: number;
+    /** CRC-32 checksum */
+    crc32: number;
+    /** Compressed size */
+    compressedSize: number;
+    /** Uncompressed size */
+    uncompressedSize: number;
+}
+/**
+ * Calculate CRC-32 checksum
+ */
+export declare function crc32(data: Uint8Array): number;
+//# sourceMappingURL=types.d.ts.map

package/dist/types/io/zip/writer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Minimal ZIP file writer
+ *
+ * Creates ZIP files with optional DEFLATE compression.
+ * Uses the Compression Streams API (built into modern browsers and Node.js 18+).
+ */
+/**
+ * Options for writing a ZIP file
+ */
+export interface ZipWriteOptions {
+    /** Whether to compress files (default: false for NPZ compatibility) */
+    compress?: boolean;
+}
+/**
+ * Create a ZIP file from a map of file names to data
+ *
+ * @param files - Map of file names to their data
+ * @param options - Write options
+ * @returns ZIP file as Uint8Array
+ */
+export declare function writeZip(files: Map<string, Uint8Array>, options?: ZipWriteOptions): Promise<Uint8Array>;
+/**
+ * Create a ZIP file synchronously (no compression)
+ *
+ * @param files - Map of file names to their data
+ * @returns ZIP file as Uint8Array
+ */
+export declare function writeZipSync(files: Map<string, Uint8Array>): Uint8Array;
+//# sourceMappingURL=writer.d.ts.map

package/dist/types/node.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Node.js-specific entry point for numpy-ts
+ *
+ * This module provides file system operations for saving and loading NPY/NPZ files,
+ * plus all core numpy-ts functionality in a single import.
+ *
+ * Usage:
+ *   import * as np from 'numpy-ts/node';
+ *   // Has everything from numpy-ts + file I/O
+ *   const arr = await np.loadNpy('data.npy');
+ *   await np.saveNpz('output.npz', { x: arr });
+ *
+ * For browser usage, use the main entry point (no file I/O).
+ */
+import { NDArray } from './core/ndarray';
+import { type NpzParseOptions, type NpzParseResult } from './io/npz/parser';
+import { type NpzSerializeOptions, type NpzArraysInput } from './io/npz/serializer';
+export * from './index';
+export * from './io';
+/**
+ * Options for loading NPY/NPZ files
+ */
+export interface LoadOptions extends NpzParseOptions {
+    /**
+     * If true, allow loading .npy files.
+     * Default: true
+     */
+    allowNpy?: boolean;
+}
+/**
+ * Options for saving NPZ files
+ */
+export interface SaveNpzOptions extends NpzSerializeOptions {
+}
+/**
+ * Load an NDArray from a .npy file
+ *
+ * @param path - Path to the .npy file
+ * @returns The loaded NDArray
+ */
+export declare function loadNpy(path: string): Promise<NDArray>;
+/**
+ * Synchronously load an NDArray from a .npy file
+ *
+ * @param path - Path to the .npy file
+ * @returns The loaded NDArray
+ */
+export declare function loadNpySync(path: string): NDArray;
+/**
+ * Save an NDArray to a .npy file
+ *
+ * @param path - Path to save the .npy file
+ * @param arr - The NDArray to save
+ */
+export declare function saveNpy(path: string, arr: NDArray): Promise<void>;
+/**
+ * Synchronously save an NDArray to a .npy file
+ *
+ * @param path - Path to save the .npy file
+ * @param arr - The NDArray to save
+ */
+export declare function saveNpySync(path: string, arr: NDArray): void;
+/**
+ * Load arrays from a .npz file
+ *
+ * @param path - Path to the .npz file
+ * @param options - Load options
+ * @returns Object with array names as keys
+ */
+export declare function loadNpzFile(path: string, options?: NpzParseOptions): Promise<NpzParseResult>;
+/**
+ * Synchronously load arrays from a .npz file
+ *
+ * Note: Only works if the NPZ file is not DEFLATE compressed.
+ *
+ * @param path - Path to the .npz file
+ * @param options - Load options
+ * @returns Object with array names as keys
+ */
+export declare function loadNpzFileSync(path: string, options?: NpzParseOptions): NpzParseResult;
+/**
+ * Save arrays to a .npz file
+ *
+ * @param path - Path to save the .npz file
+ * @param arrays - Arrays to save:
+ *   - Array of NDArrays (positional, named arr_0, arr_1, etc.)
+ *   - Map of names to NDArrays
+ *   - Object with names as keys
+ * @param options - Save options
+ */
+export declare function saveNpz(path: string, arrays: NpzArraysInput, options?: SaveNpzOptions): Promise<void>;
+/**
+ * Synchronously save arrays to a .npz file (no compression)
+ *
+ * @param path - Path to save the .npz file
+ * @param arrays - Arrays to save (same types as saveNpz)
+ */
+export declare function saveNpzSync(path: string, arrays: NpzArraysInput): void;
+/**
+ * Load an array or arrays from a .npy or .npz file
+ *
+ * This is a convenience function that auto-detects the file format based on extension.
+ *
+ * @param path - Path to the file
+ * @param options - Load options
+ * @returns NDArray for .npy files, or NpzParseResult for .npz files
+ */
+export declare function load(path: string, options?: LoadOptions): Promise<NDArray | NpzParseResult>;
+/**
+ * Synchronously load an array or arrays from a .npy or .npz file
+ *
+ * @param path - Path to the file
+ * @param options - Load options
+ * @returns NDArray for .npy files, or NpzParseResult for .npz files
+ */
+export declare function loadSync(path: string, options?: LoadOptions): NDArray | NpzParseResult;
+/**
+ * Save an array to a .npy file
+ *
+ * @param path - Path to save the file (should end with .npy)
+ * @param arr - The NDArray to save
+ */
+export declare function save(path: string, arr: NDArray): Promise<void>;
+/**
+ * Synchronously save an array to a .npy file
+ *
+ * @param path - Path to save the file (should end with .npy)
+ * @param arr - The NDArray to save
+ */
+export declare function saveSync(path: string, arr: NDArray): void;
+/**
+ * Save multiple arrays to a .npz file (like np.savez)
+ *
+ * @param path - Path to save the .npz file
+ * @param arrays - Arrays to save:
+ *   - Array of NDArrays: named arr_0, arr_1, etc. (like np.savez positional args)
+ *   - Object/Map with names as keys (like np.savez keyword args)
+ *
+ * @example
+ * // Positional arrays
+ * await savez('data.npz', [arr1, arr2])  // saved as arr_0, arr_1
+ *
+ * // Named arrays
+ * await savez('data.npz', { x: arr1, y: arr2 })
+ */
+export declare function savez(path: string, arrays: NpzArraysInput): Promise<void>;
+/**
+ * Save multiple arrays to a compressed .npz file (like np.savez_compressed)
+ *
+ * @param path - Path to save the .npz file
+ * @param arrays - Arrays to save (same input types as savez)
+ */
+export declare function savez_compressed(path: string, arrays: NpzArraysInput): Promise<void>;
+//# sourceMappingURL=node.d.ts.map

package/dist/types/ops/advanced.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Advanced array operations
+ *
+ * Broadcasting, indexing, and comparison functions.
+ * @module ops/advanced
+ */
+import { ArrayStorage } from '../core/storage';
+/**
+ * Broadcast an array to a given shape
+ * Returns a read-only view on the original array
+ */
+export declare function broadcast_to(storage: ArrayStorage, targetShape: number[]): ArrayStorage;
+/**
+ * Broadcast multiple arrays to a common shape
+ * Returns views on the original arrays
+ */
+export declare function broadcast_arrays(storages: ArrayStorage[]): ArrayStorage[];
+/**
+ * Take elements from an array along an axis
+ */
+export declare function take(storage: ArrayStorage, indices: number[], axis?: number): ArrayStorage;
+/**
+ * Put values at specified indices (modifies array in-place)
+ */
+export declare function put(storage: ArrayStorage, indices: number[], values: ArrayStorage | number | bigint): void;
+/**
+ * Construct array from index array and choices
+ */
+export declare function choose(indexStorage: ArrayStorage, choices: ArrayStorage[]): ArrayStorage;
+/**
+ * Check if two arrays are element-wise equal
+ */
+export declare function array_equal(a: ArrayStorage, b: ArrayStorage, equal_nan?: boolean): boolean;
+//# sourceMappingURL=advanced.d.ts.map

package/dist/types/ops/hyperbolic.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Hyperbolic operations
+ *
+ * Pure functions for element-wise hyperbolic operations:
+ * sinh, cosh, tanh, arcsinh, arccosh, arctanh
+ *
+ * These functions are used by NDArray methods but are separated
+ * to keep the codebase modular and testable.
+ */
+import { ArrayStorage } from '../core/storage';
+/**
+ * Hyperbolic sine of each element (element-wise)
+ * NumPy behavior: Always promotes to float64 for integer types
+ *
+ * @param a - Input array storage
+ * @returns Result storage with sinh applied
+ */
+export declare function sinh(a: ArrayStorage): ArrayStorage;
+/**
+ * Hyperbolic cosine of each element (element-wise)
+ * NumPy behavior: Always promotes to float64 for integer types
+ *
+ * @param a - Input array storage
+ * @returns Result storage with cosh applied
+ */
+export declare function cosh(a: ArrayStorage): ArrayStorage;
+/**
+ * Hyperbolic tangent of each element (element-wise)
+ * NumPy behavior: Always promotes to float64 for integer types
+ *
+ * @param a - Input array storage
+ * @returns Result storage with tanh applied
+ */
+export declare function tanh(a: ArrayStorage): ArrayStorage;
+/**
+ * Inverse hyperbolic sine of each element (element-wise)
+ * NumPy behavior: Always promotes to float64 for integer types
+ *
+ * @param a - Input array storage
+ * @returns Result storage with arcsinh applied
+ */
+export declare function arcsinh(a: ArrayStorage): ArrayStorage;
+/**
+ * Inverse hyperbolic cosine of each element (element-wise)
+ * NumPy behavior: Always promotes to float64 for integer types
+ *
+ * @param a - Input array storage (values >= 1)
+ * @returns Result storage with arccosh applied
+ */
+export declare function arccosh(a: ArrayStorage): ArrayStorage;
+/**
+ * Inverse hyperbolic tangent of each element (element-wise)
+ * NumPy behavior: Always promotes to float64 for integer types
+ *
+ * @param a - Input array storage (values in range (-1, 1))
+ * @returns Result storage with arctanh applied
+ */
+export declare function arctanh(a: ArrayStorage): ArrayStorage;
+//# sourceMappingURL=hyperbolic.d.ts.map

package/dist/types/ops/linalg.d.ts

@@ -5,12 +5,91 @@
  * @module ops/linalg
  */
 import { ArrayStorage } from '../core/storage';
+/**
+ * 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 product over last axis of a → (N-1)D
+ * - 1D · ND (N≥2): Sum product over first axis of b → (N-1)D
+ * - ND · MD (N,M≥2): Sum product over last axis of a and second-to-last of b → (N+M-2)D
+ *
+ * For 2D·2D, prefer using matmul() instead.
+ */
+export declare function dot(a: ArrayStorage, b: ArrayStorage): ArrayStorage | number | bigint;
 /**
  * Matrix multiplication
  * Requires 2D arrays with compatible shapes
  *
+ * Automatically detects transposed/non-contiguous arrays via strides
+ * and uses appropriate DGEMM transpose parameters.
+ *
  * Note: Currently uses float64 precision for all operations.
  * Integer inputs are promoted to float64 (matching NumPy behavior).
  */
 export declare function matmul(a: ArrayStorage, b: ArrayStorage): ArrayStorage;
+/**
+ * Sum along the diagonal of a 2D array
+ *
+ * Computes the trace (sum of diagonal elements) of a matrix.
+ * For non-square matrices, sums along the diagonal up to min(rows, cols).
+ *
+ * @param a - Input 2D array
+ * @returns Sum of diagonal elements
+ */
+export declare function trace(a: ArrayStorage): number | bigint;
+/**
+ * Permute the dimensions of an array
+ *
+ * Standalone version of NDArray.transpose() method.
+ * Returns a view with axes permuted.
+ *
+ * @param a - Input array
+ * @param axes - Optional permutation of axes (defaults to reverse order)
+ * @returns Transposed view
+ */
+export declare function transpose(a: ArrayStorage, axes?: number[]): ArrayStorage;
+/**
+ * Inner product of two arrays
+ *
+ * Computes sum product over the LAST axes of both a and b.
+ * - 1D · 1D: Same as dot (ordinary inner product) → scalar
+ * - ND · MD: Contracts last dimension of each → (*a.shape[:-1], *b.shape[:-1])
+ *
+ * Different from dot: always uses last axis of BOTH arrays.
+ *
+ * @param a - First array
+ * @param b - Second array
+ * @returns Inner product result
+ */
+export declare function inner(a: ArrayStorage, b: ArrayStorage): ArrayStorage | number | bigint;
+/**
+ * Outer product of two vectors
+ *
+ * Computes out[i, j] = a[i] * b[j]
+ * Input arrays are flattened if not 1D.
+ *
+ * @param a - First input (flattened to 1D)
+ * @param b - Second input (flattened to 1D)
+ * @returns 2D array of shape (a.size, b.size)
+ */
+export declare function outer(a: ArrayStorage, b: ArrayStorage): ArrayStorage;
+/**
+ * Tensor dot product along specified axes
+ *
+ * Computes sum product over specified axes.
+ *
+ * @param a - First array
+ * @param b - Second array
+ * @param axes - Axes to contract:
+ *   - Integer N: Contract last N axes of a with first N of b
+ *   - [a_axes, b_axes]: Contract specified axes
+ * @returns Tensor dot product
+ */
+export declare function tensordot(a: ArrayStorage, b: ArrayStorage, axes: number | [number[], number[]]): ArrayStorage | number | bigint;
 //# sourceMappingURL=linalg.d.ts.map

package/dist/types/ops/shape.d.ts

@@ -36,4 +36,65 @@ export declare function squeeze(storage: ArrayStorage, axis?: number): ArrayStor
  * Returns a view with additional dimension
  */
 export declare function expandDims(storage: ArrayStorage, axis: number): ArrayStorage;
+/**
+ * Swap two axes of an array
+ * Returns a view with axes swapped
+ */
+export declare function swapaxes(storage: ArrayStorage, axis1: number, axis2: number): ArrayStorage;
+/**
+ * Move axes to new positions
+ * Returns a view with axes moved
+ */
+export declare function moveaxis(storage: ArrayStorage, source: number | number[], destination: number | number[]): ArrayStorage;
+/**
+ * Concatenate arrays along an axis
+ */
+export declare function concatenate(storages: ArrayStorage[], axis?: number): ArrayStorage;
+/**
+ * Stack arrays along a new axis
+ */
+export declare function stack(storages: ArrayStorage[], axis?: number): ArrayStorage;
+/**
+ * Stack arrays vertically (row-wise)
+ * vstack is equivalent to concatenation along the first axis after
+ * 1-D arrays of shape (N,) have been reshaped to (1,N)
+ */
+export declare function vstack(storages: ArrayStorage[]): ArrayStorage;
+/**
+ * Stack arrays horizontally (column-wise)
+ * hstack is equivalent to concatenation along the second axis,
+ * except for 1-D arrays where it concatenates along the first axis
+ */
+export declare function hstack(storages: ArrayStorage[]): ArrayStorage;
+/**
+ * Stack arrays depth-wise (along third axis)
+ * dstack is equivalent to concatenation along the third axis after
+ * 2-D arrays of shape (M,N) have been reshaped to (M,N,1) and
+ * 1-D arrays of shape (N,) have been reshaped to (1,N,1)
+ */
+export declare function dstack(storages: ArrayStorage[]): ArrayStorage;
+/**
+ * Split array into sub-arrays
+ */
+export declare function split(storage: ArrayStorage, indicesOrSections: number | number[], axis?: number): ArrayStorage[];
+/**
+ * Split array into sub-arrays (allows unequal splits)
+ */
+export declare function arraySplit(storage: ArrayStorage, indicesOrSections: number | number[], axis?: number): ArrayStorage[];
+/**
+ * Split array vertically (row-wise)
+ */
+export declare function vsplit(storage: ArrayStorage, indicesOrSections: number | number[]): ArrayStorage[];
+/**
+ * Split array horizontally (column-wise)
+ */
+export declare function hsplit(storage: ArrayStorage, indicesOrSections: number | number[]): ArrayStorage[];
+/**
+ * Tile array by repeating along each axis
+ */
+export declare function tile(storage: ArrayStorage, reps: number | number[]): ArrayStorage;
+/**
+ * Repeat elements of an array
+ */
+export declare function repeat(storage: ArrayStorage, repeats: number | number[], axis?: number): ArrayStorage;
 //# sourceMappingURL=shape.d.ts.map