feat: add setNativeModulePath for custom native module loading (#272) (#281)

* feat: add setNativeModulePath for custom native module loading (#272)

Add `setNativeModulePath()` and `PRINTERS_JS_NATIVE_MODULE_PATH` env var so
bundled apps (Electron, pkg) and sandboxed runtimes can point the loader at a
specific `.node` binary instead of relying on platform npm packages. Also
attach the per-platform binaries as GitHub release assets so they're
downloadable without npm.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* missed one

* fix bad code coverage reports

* use fileUrlToPath to fix potential issues with dirs with spaces

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: esimkowitz

.github/workflows/release.yml

@@ -247,5 +247,19 @@ jobs:
           ls -la npm/ 2>/dev/null || dir npm
       - name: Compile TypeScript for publishing
         run: task compile
+      - name: Collect native binaries for release
+        run: |
+          mkdir -p release-assets
+          for binary in npm/*/printers.*.node; do
+            if [ -f "$binary" ]; then
+              cp "$binary" release-assets/
+            fi
+          done
+          ls -la release-assets/
+      - name: Publish GitHub release with native binaries
+        uses: softprops/action-gh-release@v2
+        with:
+          files: release-assets/*.node
+          fail_on_unmatched_files: true
       - name: Publish to npm
         run: pnpm publish --no-git-checks

README.md

@@ -123,6 +123,31 @@ Check if a printer exists on the system.
 
 Get the default system printer.
 
+#### `setNativeModulePath(path: string): void`
+
+Override the path used to load the native N-API binary. Useful when shipping
+the library inside a bundler (Electron, pkg, esbuild single-file builds) or in
+sandboxed environments where the platform-specific npm package
+(`@printers/printers-<platform>`) is not present.
+
+```ts
+import { setNativeModulePath, getAllPrinters } from "@printers/printers";
+
+// MUST be called before any other @printers/printers API.
+setNativeModulePath("/absolute/path/to/printers.darwin-arm64.node");
+
+const printers = await getAllPrinters();
+```
+
+The same override is also available via the `PRINTERS_JS_NATIVE_MODULE_PATH`
+environment variable, which is convenient for CI, Docker, and deployment
+scenarios. An explicit `setNativeModulePath()` call takes precedence over the
+environment variable.
+
+Per-platform `.node` binaries are attached as assets to each GitHub release in
+addition to being published via the platform npm packages, so they can be
+downloaded and bundled directly.
+
 ### Printer Class
 
 #### Properties

Taskfile.yml

@@ -48,7 +48,7 @@ tasks:
 
   test:direct:deno:
     desc: Run Deno tests directly
-    cmd: "{{.SIMULATE}} deno test --allow-read --allow-write --allow-env --allow-ffi src/tests/shared.test.ts"
+    cmd: "{{.SIMULATE}} deno test --allow-read --allow-write --allow-env --allow-ffi --allow-run src/tests/shared.test.ts"
 
   test:direct:node:
     desc: Run Node.js tests directly

deno.lock

@@ -20,6 +20,10 @@ export default [
       "examples/**/*",
       "examples/**",
 
+      // Git worktrees (each worktree has its own checkout; let it lint itself)
+      ".worktrees/**/*",
+      ".worktrees/**",
+
       // Build artifacts and dependencies
       "dist/**/*",
       "dist/**",

eslint.config.js

@@ -196,6 +196,7 @@ async function runTests(runtimesToTest = ["rust", "deno", "node", "bun"]) {
         "--allow-env",
         "--allow-read",
         "--allow-ffi",
+        "--allow-run",
         "--no-check",
         "--coverage=test-results/coverage/deno-temp",
         "src/tests/shared.test.ts",

scripts/test-runtimes.js

@@ -738,6 +738,27 @@ export function createCustomPageSize(
 let nativeModulePromise: Promise<NativeModule> | null = null;
 let nativeModuleCache: NativeModule | null = null;
 let simulationModeLogged = false;
+let customNativeModulePath: string | null = null;
+
+/**
+ * Override the path used to load the native N-API binary.
+ *
+ * Must be called before any other `@printers/printers` API. Useful for
+ * bundlers (Electron, pkg) and sandboxed runtimes where the standard
+ * platform-package resolution cannot find the binary.
+ *
+ * @param path Absolute path to the `.node` binary file.
+ * @throws If the native module has already been loaded.
+ */
+export function setNativeModulePath(path: string): void {
+  if (nativeModuleCache !== null || nativeModulePromise !== null) {
+    throw new Error(
+      "Native module already loaded. setNativeModulePath() must be called " +
+        "before any other @printers/printers API."
+    );
+  }
+  customNativeModulePath = path;
+}
 
 /**
  * Get the platform string for the current runtime environment.
@@ -781,6 +802,31 @@ async function loadNativeModule(): Promise<NativeModule> {
     );
   }
 
+  // Custom override: explicit setNativeModulePath() call takes precedence over the env var.
+  const envOverride = isDeno
+    ? g.Deno?.env?.get("PRINTERS_JS_NATIVE_MODULE_PATH")
+    : g.process?.env?.PRINTERS_JS_NATIVE_MODULE_PATH;
+  const overridePath = customNativeModulePath ?? envOverride;
+
+  if (overridePath) {
+    try {
+      // .node binaries aren't portably loadable via dynamic import() across
+      // Node, Deno, and Bun, so use createRequire — the same shape that the
+      // generated per-platform loaders in npm/<platform>/index.js use.
+      const { createRequire } = await import("node:module");
+      const require = createRequire(import.meta.url);
+      return require(overridePath) as NativeModule;
+    } catch (overrideError) {
+      throw new Error(
+        `Failed to load native module from custom path "${overridePath}": ${
+          overrideError instanceof Error
+            ? overrideError.message
+            : String(overrideError)
+        }`
+      );
+    }
+  }
+
   const platformString = getPlatformString();
 
   // Try to load the platform-specific N-API module using dynamic imports