@ts-runtypes/bin 0.10.0 → 0.11.0

package/README.md

@@ -1,33 +1,29 @@
-# ts-runtypes-bin
+# @ts-runtypes/bin
 
-Platform launcher for the [`ts-runtypes`](https://github.com/mionkit/ts-runtypes) resolver binary.
+Platform launcher for the **RunTypes** compiler binary.
 
-This package ships **zero runtime dependencies**. The actual native binary is
-delivered as a per-platform **optional dependency** named
-`ts-runtypes-binary-<os>-<arch>` (e.g. `ts-runtypes-binary-linux-x64`). Each of
-those declares `os` + `cpu`, so your package manager installs only the one
-matching your machine and silently skips the rest.
+You normally never install this directly:
+[`@ts-runtypes/devtools`](https://www.npmjs.com/package/@ts-runtypes/devtools)
+depends on it and uses it to locate the binary for the host it is running on. The
+binary itself rides as a per-platform optional dependency named
+`@ts-runtypes/binary-<os>-<arch>`, so your package manager downloads only the one
+your machine needs. This package ships **zero runtime dependencies**.
 
-You normally never install this directly — `ts-runtypes-devtools` depends on it
-and calls `getExePath()` to locate the binary.
+## Documentation
 
-## API
+Install, guides, and the factory reference live at
+**[runtypes.pages.dev](https://runtypes.pages.dev/)**.
 
-```js
-import {getExePath} from 'ts-runtypes-bin';
+- [Quick start](https://runtypes.pages.dev/introduction/quick-start)
+- [Built on typescript-go](https://runtypes.pages.dev/introduction/built-on-typescript-go)
+- [Source and issues](https://github.com/MionKit/ts-run-types)
 
-const exe = getExePath(); // absolute path to the resolver binary for this host
-```
+## Status
 
-`getExePath()` throws a descriptive error if no compatible
-`ts-runtypes-binary-*` package is installed (unsupported platform, or the
-optional dependency was skipped).
+Experimental.
 
-## CLI
+## License
 
-```sh
-npx ts-runtypes-bin --version
-```
-
-Execs the resolved binary with the given arguments (forwarding stdio and exit
-code).
+Proprietary — all rights reserved. No use, copying, or distribution without prior
+written authorization. See
+[LICENSE](https://github.com/MionKit/ts-run-types/blob/main/LICENSE).

package/lib/index.d.ts

@@ -1,5 +1,7 @@
 // Returns the absolute path to the ts-runtypes resolver binary for the host
-// platform, resolving the matching `@ts-runtypes/binary-<os>-<arch>` optional
-// dependency (or the locally built `bin/ts-runtypes` inside this repo).
+// platform. The `RT_BIN` environment variable overrides the lookup (it must
+// name an executable file, or the call throws); otherwise this resolves the
+// matching `@ts-runtypes/binary-<os>-<arch>` optional dependency (or the
+// locally built `bin/ts-runtypes` inside this repo).
 // Throws when no compatible binary is installed.
 export declare function getExePath(): string;

package/lib/index.js

@@ -7,10 +7,45 @@ import {fileURLToPath} from 'node:url';
 // directory (and of the locally built dev binary at <repo>/bin/).
 const EXE_BASENAME = 'ts-runtypes';
 
+// Env var that points the launcher at a specific resolver build, overriding
+// both lookups below. It is the ONLY escape hatch the lint lane has (the
+// bundler plugins additionally take an explicit `binary` option, which wins
+// over this), so a consumer can validate an unpublished build, bisect a
+// resolver regression, or run a vendored binary in an air-gapped install.
+const OVERRIDE_ENV = 'RT_BIN';
+
 function exeName() {
   return process.platform === 'win32' ? `${EXE_BASENAME}.exe` : EXE_BASENAME;
 }
 
+// Reads the RT_BIN override, returning null when it is unset or empty (an
+// empty value is a no-op rather than an error, so `RT_BIN=` in a .env file
+// behaves like not setting it at all). A value that does not name an
+// executable file throws instead of falling through to the normal lookups —
+// a typo must fail loudly, never silently run a DIFFERENT binary than asked.
+function overrideExe() {
+  const raw = process.env[OVERRIDE_ENV];
+  if (!raw || raw.trim() === '') return null;
+  const exe = path.resolve(raw.trim());
+  let stats;
+  try {
+    stats = fs.statSync(exe);
+  } catch {
+    throw new Error(`[ts-runtypes-bin] ${OVERRIDE_ENV}=${raw} does not exist (resolved to ${exe}).`);
+  }
+  if (!stats.isFile()) {
+    throw new Error(`[ts-runtypes-bin] ${OVERRIDE_ENV}=${raw} is not a file (resolved to ${exe}).`);
+  }
+  if (process.platform !== 'win32') {
+    try {
+      fs.accessSync(exe, fs.constants.X_OK);
+    } catch {
+      throw new Error(`[ts-runtypes-bin] ${OVERRIDE_ENV}=${raw} is not executable (resolved to ${exe}); chmod +x it.`);
+    }
+  }
+  return exe;
+}
+
 // Resolves the absolute path of a package's package.json without importing it.
 // import.meta.resolve is sync on Node >= 20.6 / 18.19; older runtimes fall back
 // to createRequire. We resolve package.json (always present) rather than the
@@ -24,11 +59,17 @@ function resolvePackageJson(specifier) {
 }
 
 // Returns the absolute path to the ts-runtypes resolver binary for the host
-// platform. In an installed tree it locates the matching optional dependency
-// `@ts-runtypes/binary-<platform>-<arch>`; inside this repo's source tree it
-// falls back to the locally built `bin/ts-runtypes`. Throws a clear error when
-// neither is available (unsupported platform, or the optional dep was skipped).
+// platform. `RT_BIN` wins when set; otherwise, in an installed tree it locates
+// the matching optional dependency `@ts-runtypes/binary-<platform>-<arch>`, and
+// inside this repo's source tree it falls back to the locally built
+// `bin/ts-runtypes`. Throws a clear error when neither is available
+// (unsupported platform, or the optional dep was skipped).
 export function getExePath() {
+  const overridden = overrideExe();
+  if (overridden) {
+    return process.platform === 'win32' && overridden.length >= 248 ? `\\\\?\\${overridden}` : overridden;
+  }
+
   const here = path.dirname(fileURLToPath(import.meta.url));
   const normalized = here.replace(/\\/g, '/');
   const platformKey = `${process.platform}-${process.arch}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-runtypes/bin",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Platform launcher for the ts-runtypes resolver binary. Resolves and execs the prebuilt native binary for the host platform; the binary itself rides as a per-platform optional dependency. Ships zero runtime dependencies.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -32,12 +32,12 @@
   },
   "tsgo": "5a37e89",
   "optionalDependencies": {
-    "@ts-runtypes/binary-linux-x64": "0.10.0",
-    "@ts-runtypes/binary-linux-arm64": "0.10.0",
-    "@ts-runtypes/binary-linux-arm": "0.10.0",
-    "@ts-runtypes/binary-darwin-x64": "0.10.0",
-    "@ts-runtypes/binary-darwin-arm64": "0.10.0",
-    "@ts-runtypes/binary-win32-x64": "0.10.0",
-    "@ts-runtypes/binary-win32-arm64": "0.10.0"
+    "@ts-runtypes/binary-linux-x64": "0.11.0",
+    "@ts-runtypes/binary-linux-arm64": "0.11.0",
+    "@ts-runtypes/binary-linux-arm": "0.11.0",
+    "@ts-runtypes/binary-darwin-x64": "0.11.0",
+    "@ts-runtypes/binary-darwin-arm64": "0.11.0",
+    "@ts-runtypes/binary-win32-x64": "0.11.0",
+    "@ts-runtypes/binary-win32-arm64": "0.11.0"
   }
 }