@cspell/cspell-worker 9.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Dent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# CSpell Worker
+
+Package: `@cspell/cspell-worker`
+
+Designed to enable spelling checking documents on a NodeJS worker thread.
+
+> [!CAUTION]
+>
+> This package is currently experimental and its exports and APIs will change.

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import { CSpellRPCClient } from "cspell-lib/cspell-rpc";
+
+//#region src/cspellWorker.d.ts
+declare function startCSpellWorker(): CSpellWorker;
+interface CSpellWorker {
+  ready: Promise<boolean>;
+  isReadyNow: boolean;
+  numberOfPendingRequests: number;
+  ok: (timeoutMs?: number) => Promise<boolean>;
+  api: CSpellRPCClient["getApi"];
+  client: CSpellRPCClient;
+  [Symbol.asyncDispose](): Promise<void>;
+}
+//#endregion
+//#region src/cspellWorkerPool.d.ts
+interface CSpellWorkerPoolOptions {
+  /**
+  * The maximum number of workers to create in the pool.
+  */
+  maxWorkers?: number;
+  /**
+  * The minimum number of workers to create in the pool.
+  */
+  minWorkers?: number;
+  /**
+  * The maximum number of pending tasks allowed per worker before the worker is considered unavailable.
+  */
+  maxPendingTasksPerWorker?: number;
+}
+interface GetAvailableWorkerOptions {
+  /**
+  * If true, only return ready workers.
+  */
+  onlyReady?: boolean;
+  /**
+  * If true, only return workers that do not have pending requests.
+  */
+  onlyIdle?: boolean;
+  /**
+  * If true, start a new worker if no available worker is found.
+  */
+  autostart?: boolean;
+}
+declare class CSpellWorkerPool {
+  #private;
+  constructor(options?: CSpellWorkerPoolOptions);
+  get size(): number;
+  get maxWorkers(): number;
+  get minWorkers(): number;
+  get maxPendingTasksPerWorker(): number;
+  set maxPendingTasksPerWorker(value: number);
+  getAvailableWorker(options?: GetAvailableWorkerOptions): CSpellWorker | undefined;
+  stopWorker(worker: CSpellWorker): Promise<void>;
+  [Symbol.asyncDispose](): Promise<void>;
+}
+//#endregion
+export { type CSpellWorker, CSpellWorkerPool, type CSpellWorkerPoolOptions, type GetAvailableWorkerOptions, startCSpellWorker };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,128 @@
+import { MessageChannel, Worker } from "node:worker_threads";
+import { createCSpellRPCClient } from "cspell-lib/cspell-rpc";
+import { cpus } from "node:os";
+
+//#region src/cspellWorker.ts
+function startCSpellWorker() {
+	const { port1, port2 } = new MessageChannel();
+	return new CSpellWorkerImpl({
+		worker: new Worker(new URL("worker.js", import.meta.url), {
+			workerData: { port: port1 },
+			transferList: [port1],
+			stderr: true,
+			stdout: true
+		}),
+		port: port2
+	});
+}
+var CSpellWorkerImpl = class {
+	#terminated = false;
+	#worker;
+	#client;
+	constructor(instance) {
+		this.#worker = instance.worker;
+		this.#client = createCSpellRPCClient({ port: instance.port });
+	}
+	get ready() {
+		return this.#client.ready();
+	}
+	get isReadyNow() {
+		return this.#client.isReady;
+	}
+	get numberOfPendingRequests() {
+		return this.#client.length;
+	}
+	get client() {
+		return this.#client;
+	}
+	get isTerminated() {
+		return this.#terminated;
+	}
+	ok(timeoutMs) {
+		return this.#client.isOK({ timeoutMs });
+	}
+	terminate() {
+		return this[Symbol.asyncDispose]();
+	}
+	api() {
+		return this.#client.getApi();
+	}
+	async [Symbol.asyncDispose]() {
+		if (this.#terminated) return;
+		this.#terminated = true;
+		this.#client[Symbol.dispose]();
+		await this.#worker.terminate();
+	}
+};
+
+//#endregion
+//#region src/cspellWorkerPool.ts
+const MAX_WORKERS_TO_CORES_RATIO = .75;
+const DEFAULT_WORKERS_TO_CORES_RATIO = .5;
+var CSpellWorkerPool = class {
+	#workers;
+	#options;
+	#maxWorkers;
+	#minWorkers;
+	#maxPendingTasksPerWorker;
+	constructor(options) {
+		this.#workers = /* @__PURE__ */ new Set();
+		this.#options = options || {};
+		this.#maxPendingTasksPerWorker = this.#options.maxPendingTasksPerWorker ?? 1;
+		this.#maxPendingTasksPerWorker = Math.max(1, this.#maxPendingTasksPerWorker);
+		const numCores = cpus().length;
+		this.#maxWorkers = this.#options.maxWorkers ?? Math.ceil(numCores * DEFAULT_WORKERS_TO_CORES_RATIO);
+		this.#maxWorkers = Math.min(this.#maxWorkers, Math.ceil(numCores * MAX_WORKERS_TO_CORES_RATIO));
+		this.#maxWorkers = Math.max(1, this.#maxWorkers);
+		this.#minWorkers = Math.min(this.#options.minWorkers ?? 0, this.#maxWorkers);
+		for (let i = 0; i < this.#minWorkers; i++) this.#createWorker();
+	}
+	#createWorker() {
+		const w = startCSpellWorker();
+		this.#workers.add(w);
+		return w;
+	}
+	get size() {
+		return this.#workers.size;
+	}
+	get maxWorkers() {
+		return this.#maxWorkers;
+	}
+	get minWorkers() {
+		return this.#minWorkers;
+	}
+	get maxPendingTasksPerWorker() {
+		return this.#maxPendingTasksPerWorker;
+	}
+	set maxPendingTasksPerWorker(value) {
+		this.#maxPendingTasksPerWorker = Math.max(1, value);
+	}
+	getAvailableWorker(options) {
+		let workers = [...this.#workers];
+		workers = workers.filter((worker) => worker.numberOfPendingRequests < this.#maxPendingTasksPerWorker);
+		workers = options?.onlyReady ? workers.filter((worker) => worker.isReadyNow) : workers;
+		workers = options?.onlyIdle ? workers.filter((worker) => worker.numberOfPendingRequests === 0) : workers;
+		workers.sort((a, b) => {
+			let v = 0;
+			v = (a.isReadyNow ? 0 : 1) - (b.isReadyNow ? 0 : 1);
+			if (v !== 0) return v;
+			v = a.numberOfPendingRequests - b.numberOfPendingRequests;
+			return v;
+		});
+		if (workers.length > 0) return workers[0];
+		if (options?.autostart && this.#workers.size < this.#maxWorkers) return this.#createWorker();
+	}
+	stopWorker(worker) {
+		this.#workers.delete(worker);
+		return worker[Symbol.asyncDispose]();
+	}
+	[Symbol.asyncDispose]() {
+		const workers = [...this.#workers];
+		this.#workers.clear();
+		return Promise.all(workers.map((w) => this.stopWorker(w).catch(() => void 0))).then(() => void 0);
+	}
+};
+
+//#endregion
+export { CSpellWorkerPool, startCSpellWorker };
+//# sourceMappingURL=index.js.map

package/dist/worker.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/worker.js

@@ -0,0 +1,9 @@
+import { parentPort, workerData } from "node:worker_threads";
+import { createCSpellRPCServer } from "cspell-lib/cspell-rpc/server";
+
+//#region src/worker.ts
+if (parentPort) createCSpellRPCServer({ port: workerData?.port || parentPort });
+
+//#endregion
+export {  };
+//# sourceMappingURL=worker.js.map

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@cspell/cspell-worker",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "version": "9.6.1",
+  "description": "Client Server RPC worker for CSpell.",
+  "keywords": [
+    "cspell",
+    "rpc",
+    "worker"
+  ],
+  "author": "Jason Dent <jason@streetsidesoftware.nl>",
+  "homepage": "https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-worker#readme",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": true,
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "directories": {
+    "dist": "dist"
+  },
+  "typings": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "!**/*.tsbuildInfo",
+    "!**/__mocks__",
+    "!**/*.test.*",
+    "!**/*.spec.*",
+    "!**/*.map"
+  ],
+  "scripts": {
+    "build": "tsdown && tsc -p .",
+    "watch": "tsdown --watch",
+    "clean": "shx rm -rf dist temp coverage \"*.tsbuildInfo\"",
+    "clean-build": "pnpm run clean && pnpm run build",
+    "coverage": "vitest run --coverage --pool=forks",
+    "test": "vitest run --pool=forks"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/streetsidesoftware/cspell.git",
+    "directory": "packages/cspell-worker"
+  },
+  "bugs": {
+    "url": "https://github.com/streetsidesoftware/cspell"
+  },
+  "engines": {
+    "node": ">=20.18"
+  },
+  "dependencies": {
+    "cspell-lib": "9.6.1"
+  },
+  "gitHead": "666fb79096d25c53af9519cad07030e7aca597e1"
+}