@remit/search-service 0.0.7 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/search-service",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -32,7 +32,7 @@
   },
   "scripts": {
     "test:typecheck": "tsgo --noEmit",
-    "test:run": "node --env-file=../../localhost-test-unit.env --import tsx --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=75 --test 'src/**/*.test.ts'",
+    "test:run": "node --env-file=../../localhost-test-unit.env --import tsx --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=82 --test 'src/**/*.test.ts'",
     "test:integ": "RUN_INTEG_TESTS=1 node --env-file=../../localhost-test-unit.env --import tsx --test 'src/**/*.integ.test.ts'",
     "test": "npm run test:typecheck && npm run test:run"
   },

package/src/embeddings.test.ts

@@ -1,6 +1,24 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
-import { LocalEmbeddingService } from "./embeddings.js";
+import type { pipeline as PipelineFn } from "@huggingface/transformers";
+import {
+	EmbeddingModelUnavailableError,
+	LocalEmbeddingService,
+} from "./embeddings.js";
+
+// Exercises the model-load path without the network: the pipeline factory
+// rejects the way a failed `from_pretrained` (HuggingFace fetch failed) does.
+class FailingLoadService extends LocalEmbeddingService {
+	importCount = 0;
+	protected importTransformers(): Promise<{ pipeline: typeof PipelineFn }> {
+		this.importCount++;
+		const pipeline = (() =>
+			Promise.reject(
+				new TypeError("fetch failed"),
+			)) as unknown as typeof PipelineFn;
+		return Promise.resolve({ pipeline });
+	}
+}
 
 describe("LocalEmbeddingService", () => {
 	it("keeps the historical embeddingId when dtype is unset", () => {
@@ -25,4 +43,26 @@ describe("LocalEmbeddingService", () => {
 			"local:Xenova/paraphrase-multilingual-MiniLM-L12-v2:q8@384",
 		);
 	});
+
+	it("raises a typed EmbeddingModelUnavailableError when the model cannot be loaded", async () => {
+		const service = new FailingLoadService({ dimensions: 8 });
+		await assert.rejects(
+			() => service.embed(["hello"]),
+			(error: unknown) => {
+				assert.ok(error instanceof EmbeddingModelUnavailableError);
+				assert.equal(
+					(error as { code?: string }).code,
+					"ERR_EMBEDDING_MODEL_UNAVAILABLE",
+				);
+				return true;
+			},
+		);
+	});
+
+	it("clears the memoized pipeline on a load failure so a later call retries", async () => {
+		const service = new FailingLoadService({ dimensions: 8 });
+		await assert.rejects(() => service.embed(["hello"]));
+		await assert.rejects(() => service.embed(["hello"]));
+		assert.equal(service.importCount, 2);
+	});
 });

package/src/embeddings.ts

@@ -91,6 +91,24 @@ export interface LocalEmbeddingConfig {
 const DEFAULT_LOCAL_MODEL_ID = "Xenova/all-MiniLM-L6-v2";
 const DEFAULT_LOCAL_DIMENSIONS = 384;
 
+/**
+ * The local embedder could not load its model. Raised when Transformers.js fails
+ * to resolve the model files — the common cause is `from_pretrained` lazily
+ * fetching the weights from HuggingFace and the network fetch failing
+ * (`TypeError: fetch failed`), which otherwise surfaces as an opaque 500.
+ *
+ * The `code` is the contract consumers match on (mirroring Node's own error
+ * codes) to degrade the semantic path to empty results instead of crashing,
+ * without importing this class or string-matching undici internals.
+ */
+export class EmbeddingModelUnavailableError extends Error {
+	readonly code = "ERR_EMBEDDING_MODEL_UNAVAILABLE";
+	constructor(modelId: string, options?: { cause?: unknown }) {
+		super(`Embedding model "${modelId}" could not be loaded`, options);
+		this.name = "EmbeddingModelUnavailableError";
+	}
+}
+
 type TransformersModule = { pipeline: typeof PipelineFn };
 
 /**
@@ -122,15 +140,34 @@ export class LocalEmbeddingService implements EmbeddingService {
 
 	private getPipeline = async (): Promise<FeatureExtractionPipeline> => {
 		if (this.pipelinePromise) return this.pipelinePromise;
-		this.pipelinePromise = (async () => {
-			const { pipeline } = await runtimeImport<TransformersModule>(
-				"@huggingface/transformers",
-			);
-			return pipeline("feature-extraction", this.modelId, {
+		const promise = this.loadPipeline();
+		this.pipelinePromise = promise;
+		try {
+			return await promise;
+		} catch (error) {
+			// A failed load (module absent, or the model could not be fetched) must
+			// not poison the instance: clear the memo so a later call retries rather
+			// than returning the same rejected promise for the process lifetime.
+			if (this.pipelinePromise === promise) this.pipelinePromise = null;
+			throw error;
+		}
+	};
+
+	// Import boundary kept overridable so a load failure can be exercised without
+	// the network; the default resolves Transformers.js lazily via runtimeImport.
+	protected importTransformers(): Promise<TransformersModule> {
+		return runtimeImport<TransformersModule>("@huggingface/transformers");
+	}
+
+	private loadPipeline = async (): Promise<FeatureExtractionPipeline> => {
+		const { pipeline } = await this.importTransformers();
+		try {
+			return await pipeline("feature-extraction", this.modelId, {
 				dtype: this.dtype,
 			});
-		})();
-		return this.pipelinePromise;
+		} catch (error) {
+			throw new EmbeddingModelUnavailableError(this.modelId, { cause: error });
+		}
 	};
 
 	embed = async (texts: string[]): Promise<number[][]> => {

package/src/index.ts

@@ -36,6 +36,7 @@ export {
 	createLocalEmbeddingService,
 	type DeterministicEmbeddingConfig,
 	DeterministicEmbeddingService,
+	EmbeddingModelUnavailableError,
 	type EmbeddingService,
 	type LocalEmbeddingConfig,
 	LocalEmbeddingService,