pca-web 0.1.0

package/dist/worker/protocol.js

@@ -0,0 +1,70 @@
+/**
+ * Wire protocol shared by the worker handler (`pca-web/worker`) and the
+ * client proxies (`pca-web/client`).
+ *
+ * Import discipline: this module (and everything the client pulls in) must
+ * stay free of solver code — value imports are limited to matrix/types/
+ * model/validation; estimator and progress types appear type-only (erased
+ * at build time). This is what keeps `pca-web/client` a ~few-KB proxy while
+ * `pca-web/worker` carries the estimators.
+ */
+import { Matrix } from '../matrix.js';
+export const PCA_WORKER_PROTOCOL_VERSION = 1;
+/** A typed array that owns its entire buffer (safe to clone or transfer). */
+export function tightArray(a) {
+    return a.byteOffset === 0 && a.byteLength === a.buffer.byteLength ? a : a.slice();
+}
+/**
+ * Encodes a Matrix for the wire. The data is tight-sliced when it is a
+ * view — cloning or transferring a subarray view would otherwise serialize
+ * (or detach) its entire parent buffer.
+ */
+export function matrixToWire(m) {
+    return { kind: 'matrix', data: tightArray(m.data), rows: m.rows, cols: m.cols };
+}
+export function wireToMatrix(w) {
+    return new Matrix(w.data, w.rows, w.cols);
+}
+export function isWireMatrix(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        v.kind === 'matrix' &&
+        (v.data instanceof Float64Array ||
+            v.data instanceof Float32Array));
+}
+export function toWireError(err) {
+    if (err instanceof Error) {
+        const wire = { name: err.name || 'Error', message: err.message };
+        if (typeof err.stack === 'string') {
+            wire.stack = err.stack;
+        }
+        return wire;
+    }
+    return { name: 'Error', message: String(err) };
+}
+// ---------------------------------------------------------------------
+// Guards and transfer-list helpers
+// ---------------------------------------------------------------------
+const REQUEST_TAGS = new Set(['create', 'call', 'abort', 'dispose']);
+const RESPONSE_TAGS = new Set(['ready', 'result', 'progress', 'error']);
+export function isWorkerRequest(v) {
+    return typeof v === 'object' && v !== null && REQUEST_TAGS.has(v.t);
+}
+export function isWorkerResponse(v) {
+    return (typeof v === 'object' && v !== null && RESPONSE_TAGS.has(v.t));
+}
+/** Buffers of a model's typed arrays (all tight by `toModel` contract). */
+export function modelTransferList(model) {
+    const buffers = [
+        model.components.buffer,
+        model.mean.buffer,
+        model.explainedVariance.buffer,
+        model.explainedVarianceRatio.buffer,
+        model.singularValues.buffer,
+    ];
+    if (model.estimator === 'ipca') {
+        buffers.push(model.variance.buffer);
+    }
+    return buffers;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/worker/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/worker/protocol.ts"],"names":[],"mappings":"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"}

package/dist/worker/worker.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `pca-web/worker` — drop-in worker entry.
+ *
+ * Spawned directly (`new Worker(new URL('pca-web/worker', import.meta.url),
+ * { type: 'module' })` or via a one-line `import 'pca-web/worker'` in your
+ * own worker file), it attaches the pca-web protocol to the worker scope.
+ * Importing it from a non-worker context is harmless: auto-attach happens
+ * only inside a real DedicatedWorkerGlobalScope, so this module doubles as
+ * the programmatic entry — `attachPCAWorker(port)` works with any message
+ * port, including Node's `worker_threads` `parentPort`.
+ */
+export { type AttachPCAWorkerOptions, attachPCAWorker } from './handler.js';
+export * from './protocol.js';
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/worker/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAAE,KAAK,sBAAsB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC5E,cAAc,eAAe,CAAC"}

package/dist/worker/worker.js

@@ -0,0 +1,20 @@
+/**
+ * `pca-web/worker` — drop-in worker entry.
+ *
+ * Spawned directly (`new Worker(new URL('pca-web/worker', import.meta.url),
+ * { type: 'module' })` or via a one-line `import 'pca-web/worker'` in your
+ * own worker file), it attaches the pca-web protocol to the worker scope.
+ * Importing it from a non-worker context is harmless: auto-attach happens
+ * only inside a real DedicatedWorkerGlobalScope, so this module doubles as
+ * the programmatic entry — `attachPCAWorker(port)` works with any message
+ * port, including Node's `worker_threads` `parentPort`.
+ */
+import { attachPCAWorker } from './handler.js';
+export { attachPCAWorker } from './handler.js';
+export * from './protocol.js';
+const scope = globalThis;
+if (typeof scope.DedicatedWorkerGlobalScope === 'function' &&
+    globalThis instanceof scope.DedicatedWorkerGlobalScope) {
+    attachPCAWorker(globalThis);
+}
+//# sourceMappingURL=worker.js.map

package/dist/worker/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../../src/worker/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/C,OAAO,EAA+B,eAAe,EAAE,MAAM,cAAc,CAAC;AAC5E,cAAc,eAAe,CAAC;AAE9B,MAAM,KAAK,GAAG,UAAyE,CAAC;AACxF,IACE,OAAO,KAAK,CAAC,0BAA0B,KAAK,UAAU;IACtD,UAAU,YAAY,KAAK,CAAC,0BAA0B,EACtD,CAAC;IACD,eAAe,CAAC,UAAsC,CAAC,CAAC;AAC1D,CAAC"}

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "pca-web",
+  "version": "0.1.0",
+  "description": "Client-side PCA and IncrementalPCA for the browser and Node.js — a zero-dependency TypeScript reimplementation of scikit-learn's decomposition.PCA with optional WebGPU acceleration.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Jeya Balaji Balasubramanian",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jeyabbalas/pca-web.git"
+  },
+  "keywords": [
+    "pca",
+    "principal-component-analysis",
+    "dimensionality-reduction",
+    "scikit-learn",
+    "machine-learning",
+    "webgpu",
+    "svd",
+    "incremental-pca",
+    "browser"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": [
+    "./dist/worker/worker.js",
+    "./src/worker/worker.ts"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./webgpu": {
+      "types": "./dist/webgpu/index.d.ts",
+      "default": "./dist/webgpu/index.js"
+    },
+    "./worker": {
+      "types": "./dist/worker/worker.d.ts",
+      "default": "./dist/worker/worker.js"
+    },
+    "./client": {
+      "types": "./dist/worker/client.d.ts",
+      "default": "./dist/worker/client.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "workspaces": [
+    "examples/demo"
+  ],
+  "scripts": {
+    "prepack": "npm run build",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.tests.json",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:browser": "node tests/browser/run.mjs",
+    "test:browser:worker": "node tests/browser/run-worker.mjs",
+    "bench": "node bench/cpu.mjs",
+    "bench:browser": "node bench/browser.mjs",
+    "demo:dev": "npm run build && npm -w examples/demo run dev",
+    "demo:build": "npm run build && npm -w examples/demo run build",
+    "fixtures": ".venv/bin/python python/generate_fixtures.py",
+    "demo:data": ".venv/bin/python python/generate_demo_data.py"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.2",
+    "@types/node": "^24.13.2",
+    "@vitest/coverage-v8": "^4.1.10",
+    "@webgpu/types": "^0.1.71",
+    "esbuild": "^0.28.1",
+    "playwright": "^1.61.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "@webgpu/types": "*"
+  },
+  "peerDependenciesMeta": {
+    "@webgpu/types": {
+      "optional": true
+    }
+  }
+}