@danielsimonjr/mathts-parallel 0.6.4 → 0.6.6

package/dist/strategies/chunk.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Chunking Strategies for Parallel Operations
+ *
+ * Provides utilities for dividing large arrays into chunks
+ * for parallel processing across multiple workers.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Result of a chunking operation
+ */
+export interface ChunkResult<T> {
+    /** The chunked data */
+    chunks: T[];
+    /** Metadata about each chunk */
+    chunkInfo: ChunkInfo[];
+    /** Total number of elements */
+    totalElements: number;
+    /** Number of workers/chunks */
+    numChunks: number;
+}
+/**
+ * Information about a single chunk
+ */
+export interface ChunkInfo {
+    /** Start index in the original array */
+    startIndex: number;
+    /** End index (exclusive) in the original array */
+    endIndex: number;
+    /** Length of this chunk */
+    length: number;
+    /** Chunk index */
+    chunkIndex: number;
+}
+/**
+ * Options for chunking operations
+ */
+export interface ChunkOptions {
+    /** Minimum elements per chunk (default: 1000) */
+    minChunkSize?: number;
+    /** Maximum number of chunks (default: number of CPUs) */
+    maxChunks?: number;
+    /** Target chunk size (default: auto-calculated) */
+    targetChunkSize?: number;
+    /** Whether to balance chunk sizes evenly (default: true) */
+    balanced?: boolean;
+}
+/**
+ * Calculate optimal number of chunks for a given array size
+ *
+ * @param totalElements - Total number of elements
+ * @param options - Chunking options
+ * @returns Optimal number of chunks
+ */
+export declare function calculateOptimalChunks(totalElements: number, options?: ChunkOptions): number;
+/**
+ * Chunk a Float64Array into multiple smaller arrays
+ *
+ * @param data - The array to chunk
+ * @param options - Chunking options
+ * @returns Chunked data with metadata
+ */
+export declare function chunkFloat64Array(data: Float64Array, options?: ChunkOptions): ChunkResult<Float64Array>;
+/**
+ * Chunk a generic array into multiple smaller arrays
+ *
+ * @param data - The array to chunk
+ * @param options - Chunking options
+ * @returns Chunked data with metadata
+ */
+export declare function chunkArray<T>(data: T[], options?: ChunkOptions): ChunkResult<T[]>;
+/**
+ * Merge chunked results back into a single array
+ *
+ * @param chunks - Array of chunk results
+ * @returns Merged array
+ */
+export declare function mergeFloat64Chunks(chunks: Float64Array[]): Float64Array;
+/**
+ * Merge generic array chunks
+ *
+ * @param chunks - Array of chunk results
+ * @returns Merged array
+ */
+export declare function mergeArrayChunks<T>(chunks: T[][]): T[];
+/**
+ * Determine if an array should be parallelized based on size
+ *
+ * @param elementCount - Number of elements
+ * @param threshold - Minimum elements for parallelization (default: 10000)
+ * @returns Whether parallelization is recommended
+ */
+export declare function shouldParallelize(elementCount: number, threshold?: number): boolean;
+/**
+ * Calculate the memory size of a Float64Array in bytes
+ *
+ * @param data - The array
+ * @returns Size in bytes
+ */
+export declare function memorySizeBytes(data: Float64Array): number;
+/**
+ * Create a range partitioner for parallel iteration
+ *
+ * @param start - Start of range (inclusive)
+ * @param end - End of range (exclusive)
+ * @param options - Chunking options
+ * @returns Array of [start, end] pairs for each chunk
+ */
+export declare function partitionRange(start: number, end: number, options?: ChunkOptions): Array<[number, number]>;
+/**
+ * Create a 2D partition for matrix operations
+ *
+ * @param rows - Number of rows
+ * @param cols - Number of columns
+ * @param options - Chunking options
+ * @returns Array of [rowStart, rowEnd, colStart, colEnd] tuples
+ */
+export declare function partition2D(rows: number, cols: number, options?: ChunkOptions): Array<[number, number, number, number]>;
+//# sourceMappingURL=chunk.d.ts.map

package/dist/strategies/chunk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../src/strategies/chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,uBAAuB;IACvB,MAAM,EAAE,CAAC,EAAE,CAAC;IACZ,gCAAgC;IAChC,SAAS,EAAE,SAAS,EAAE,CAAC;IACvB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAYD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,CAgBhG;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,YAAY,EAClB,OAAO,GAAE,YAAiB,GACzB,WAAW,CAAC,YAAY,CAAC,CAoF3B;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,OAAO,GAAE,YAAiB,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAiFrF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,YAAY,CAcvE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,CAKtD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,GAAE,MAAc,GAAG,OAAO,CAE1F;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAE1D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,YAAiB,GACzB,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAsBzB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,YAAiB,GACzB,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAKzC"}

package/dist/strategies/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Parallel Strategies
+ *
+ * Strategies for chunking, threshold-based dispatch, and workload distribution.
+ *
+ * @packageDocumentation
+ */
+export { calculateOptimalChunks, chunkFloat64Array, chunkArray, mergeFloat64Chunks, mergeArrayChunks, shouldParallelize as shouldChunkParallelize, partitionRange, partition2D, type ChunkOptions, type ChunkResult, type ChunkInfo, } from './chunk.js';
+export { ThresholdDispatcher, thresholdDispatcher, shouldParallelize, dispatch, calculateChunks, DEFAULT_THRESHOLDS, type ThresholdConfig, type OperationCategory, type ExecutionMode, type DispatchResult, } from './threshold.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/strategies/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/strategies/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,IAAI,sBAAsB,EAC3C,cAAc,EACd,WAAW,EACX,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC"}

package/dist/strategies/threshold.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Threshold-based Dispatch Strategy
+ *
+ * Automatically decides whether to use parallel or sequential execution
+ * based on data size, operation type, and system capabilities.
+ *
+ * @packageDocumentation
+ */
+import { ComputePool } from '../ComputePool.js';
+/**
+ * Operation categories for threshold selection
+ */
+export type OperationCategory = 'matmul' | 'elementwise' | 'reduce' | 'map' | 'sort' | 'decomposition' | 'general';
+/**
+ * Threshold configuration for different operation types
+ */
+export interface ThresholdConfig {
+    /** Minimum elements for parallel matmul */
+    matmul: number;
+    /** Minimum elements for parallel elementwise ops */
+    elementwise: number;
+    /** Minimum elements for parallel reductions */
+    reduce: number;
+    /** Minimum elements for parallel map */
+    map: number;
+    /** Minimum elements for parallel sort */
+    sort: number;
+    /** Minimum elements for parallel decomposition */
+    decomposition: number;
+    /** Default threshold for other operations */
+    general: number;
+}
+/**
+ * Default category-level thresholds.
+ *
+ * NOTE: `ComputePool.shouldParallelize` (op-level, {@link DEFAULT_THRESHOLD_BY_OP})
+ * is the authority the typed functions dispatch through. This category map is a
+ * coarser helper; where a category overlaps a tuned op (matmul) its value is
+ * derived from the canonical const so the two cannot diverge. The remaining
+ * categories (no single ComputePool op equivalent — many are 'never') keep
+ * heuristic defaults for compute-vs-memory-bound work.
+ */
+export declare const DEFAULT_THRESHOLDS: ThresholdConfig;
+/**
+ * Execution mode returned by threshold dispatch
+ */
+export type ExecutionMode = 'parallel' | 'sequential';
+/**
+ * Result of threshold dispatch decision
+ */
+export interface DispatchResult {
+    /** Recommended execution mode */
+    mode: ExecutionMode;
+    /** Reason for the decision */
+    reason: string;
+    /** Threshold used for comparison */
+    threshold: number;
+    /** Actual element count */
+    elementCount: number;
+}
+/**
+ * Threshold-based Dispatch Manager
+ *
+ * Provides intelligent parallel vs sequential dispatch based on
+ * operation type, data size, and system state.
+ */
+export declare class ThresholdDispatcher {
+    private thresholds;
+    private pool;
+    constructor(thresholds?: Partial<ThresholdConfig>, pool?: ComputePool);
+    /**
+     * Get threshold for a specific operation category
+     */
+    getThreshold(category: OperationCategory): number;
+    /**
+     * Update thresholds
+     */
+    setThresholds(thresholds: Partial<ThresholdConfig>): void;
+    /**
+     * Get current threshold configuration
+     */
+    getThresholds(): ThresholdConfig;
+    /**
+     * Determine execution mode based on operation and data size
+     */
+    dispatch(elementCount: number, category?: OperationCategory): DispatchResult;
+    /**
+     * Simple boolean check for parallel execution
+     */
+    shouldParallelize(elementCount: number, category?: OperationCategory): boolean;
+    /**
+     * Calculate optimal chunk count based on operation and data size
+     */
+    calculateChunks(elementCount: number, category?: OperationCategory): number;
+}
+/**
+ * Global threshold dispatcher instance
+ */
+export declare const thresholdDispatcher: ThresholdDispatcher;
+/**
+ * Convenience function to check if operation should be parallelized
+ */
+export declare function shouldParallelize(elementCount: number, category?: OperationCategory): boolean;
+/**
+ * Convenience function to get dispatch decision
+ */
+export declare function dispatch(elementCount: number, category?: OperationCategory): DispatchResult;
+/**
+ * Convenience function to calculate optimal chunk count
+ */
+export declare function calculateChunks(elementCount: number, category?: OperationCategory): number;
+//# sourceMappingURL=threshold.d.ts.map

package/dist/strategies/threshold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threshold.d.ts","sourceRoot":"","sources":["../../src/strategies/threshold.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAe,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AAatF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,aAAa,GACb,QAAQ,GACR,KAAK,GACL,MAAM,GACN,eAAe,GACf,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,aAAa,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,EAAE,eAQhC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,YAAY,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,IAAI,EAAE,aAAa,CAAC;IACpB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,IAAI,CAAc;IAE1B,YAAY,UAAU,GAAE,OAAO,CAAC,eAAe,CAAM,EAAE,IAAI,CAAC,EAAE,WAAW,EAGxE;IAED;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAEhD;IAED;;OAEG;IACH,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAExD;IAED;;OAEG;IACH,aAAa,IAAI,eAAe,CAE/B;IAED;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,GAAE,iBAA6B,GAAG,cAAc,CA0CtF;IAED;;OAEG;IACH,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,GAAE,iBAA6B,GAAG,OAAO,CAExF;IAED;;OAEG;IACH,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,GAAE,iBAA6B,GAAG,MAAM,CAiCrF;CACF;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,qBAA4B,CAAC;AAE7D;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,QAAQ,GAAE,iBAA6B,GACtC,OAAO,CAET;AAED;;GAEG;AACH,wBAAgB,QAAQ,CACtB,YAAY,EAAE,MAAM,EACpB,QAAQ,GAAE,iBAA6B,GACtC,cAAc,CAEhB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,QAAQ,GAAE,iBAA6B,GACtC,MAAM,CAER"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielsimonjr/mathts-parallel",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "WebWorker parallelization for MathTS computations",
   "author": "Daniel Simon Jr.",
   "license": "MIT",
@@ -19,26 +19,26 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/matrix.worker.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts src/matrix.worker.ts --format esm --clean && tsc -p tsconfig.dts.json",
     "dev": "tsup src/index.ts src/matrix.worker.ts --format esm --dts --watch",
-    "test": "vitest run",
+    "test": "bun test --isolate --timeout 30000",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
+    "test:coverage": "bun test --isolate --timeout 30000 --coverage",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint src --ext .ts",
-    "lint:fix": "eslint src --ext .ts --fix",
+    "lint": "oxlint src",
+    "lint:fix": "oxlint src --fix",
     "clean": "rm -rf dist",
     "build:prod": "tsup src/index.ts src/matrix.worker.ts --format esm --dts --clean --minify --treeshake"
   },
   "dependencies": {
-    "@danielsimonjr/mathts-workerpool": "^0.2.1",
-    "@danielsimonjr/mathts-core": "^0.14.0"
+    "@danielsimonjr/mathts-workerpool": "^0.2.5",
+    "@danielsimonjr/mathts-core": "^0.15.4"
   },
   "devDependencies": {
-    "@types/node": "^25.5.2",
+    "@types/node": "^26.4.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^4.1.5"
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
   },
   "publishConfig": {
     "access": "public"