@vantail/runtime 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Finding the native runtime.
+ *
+ * Application developers never compile Rust. The runtime is a precompiled
+ * binary published per platform, and this module is the only thing that knows
+ * where it might be:
+ *
+ * 1. `$VANTAIL_RUNTIME_BIN` - an explicit override, for CI and for anyone
+ *    hacking on the runtime itself.
+ * 2. `@vantail/runtime-<platform>-<arch>` - the published binary, installed
+ *    as an optional dependency so only the current platform is downloaded.
+ * 3. A `cargo build` inside this repository - how Vantail's own examples run
+ *    before anything is published.
+ */
+export type RuntimeSource = "env" | "package" | "workspace";
+export interface RuntimeResolution {
+    /** Absolute path to the runtime executable. */
+    path: string;
+    source: RuntimeSource;
+    /** The npm package it came from, when it came from one. */
+    package?: string;
+    /** Which Cargo profile a workspace build came from. */
+    profile?: "release" | "debug";
+}
+export interface ResolveOptions {
+    /** Where to start looking for a project or workspace. Defaults to `cwd`. */
+    cwd?: string;
+    platform?: NodeJS.Platform;
+    arch?: string;
+    /**
+     * Which local build to prefer when both exist. Only affects the workspace
+     * fallback; a published package has no profiles.
+     *
+     * - `newest` (default) - whatever was built last, which is what you want
+     *   while iterating on the runtime.
+     * - `release` - for packaging, where picking up a debug build means
+     *   shipping something ten times the size for no reason.
+     */
+    prefer?: "newest" | "release";
+}
+export declare class RuntimeNotFoundError extends Error {
+    readonly packageName: string;
+    constructor(packageName: string, tried: string[]);
+}
+/** The npm package that carries the runtime for a platform. */
+export declare function runtimePackageName(platform?: NodeJS.Platform, arch?: string): string;
+export declare function runtimeBinaryName(platform?: NodeJS.Platform): string;
+export declare function resolveRuntimeBinary(options?: ResolveOptions): RuntimeResolution;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,SAAS,GAAG,WAAW,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,OAAO,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC/B;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,YAAY,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAS/C;CACF;AAED,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAChC,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,IAAI,GAAE,MAAqB,GAC1B,MAAM,CAER;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,MAAM,CAEtF;AAED,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,cAAmB,GAAG,iBAAiB,CAqBpF"}

package/dist/index.js

@@ -0,0 +1,137 @@
+/**
+ * Finding the native runtime.
+ *
+ * Application developers never compile Rust. The runtime is a precompiled
+ * binary published per platform, and this module is the only thing that knows
+ * where it might be:
+ *
+ * 1. `$VANTAIL_RUNTIME_BIN` - an explicit override, for CI and for anyone
+ *    hacking on the runtime itself.
+ * 2. `@vantail/runtime-<platform>-<arch>` - the published binary, installed
+ *    as an optional dependency so only the current platform is downloaded.
+ * 3. A `cargo build` inside this repository - how Vantail's own examples run
+ *    before anything is published.
+ */
+import { createRequire } from "node:module";
+import { existsSync, statSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+export class RuntimeNotFoundError extends Error {
+    packageName;
+    constructor(packageName, tried) {
+        super(`Could not find the Vantail runtime for this platform.\n\n` +
+            `Install it with:\n  npm install --save-optional ${packageName}\n\n` +
+            `Or point at a build of your own:\n  export VANTAIL_RUNTIME_BIN=/path/to/vantail-runtime\n\n` +
+            `Looked in:\n${tried.map((path) => `  ${path}`).join("\n")}`);
+        this.name = "RuntimeNotFoundError";
+        this.packageName = packageName;
+    }
+}
+/** The npm package that carries the runtime for a platform. */
+export function runtimePackageName(platform = process.platform, arch = process.arch) {
+    return `@vantail/runtime-${platform}-${arch}`;
+}
+export function runtimeBinaryName(platform = process.platform) {
+    return platform === "win32" ? "vantail-runtime.exe" : "vantail-runtime";
+}
+export function resolveRuntimeBinary(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const arch = options.arch ?? process.arch;
+    const cwd = options.cwd ?? process.cwd();
+    const packageName = runtimePackageName(platform, arch);
+    const tried = [];
+    const override = process.env["VANTAIL_RUNTIME_BIN"];
+    if (override) {
+        const path = resolvePath(override);
+        if (isExecutable(path))
+            return { path, source: "env" };
+        tried.push(`${path} (from $VANTAIL_RUNTIME_BIN)`);
+    }
+    const fromPackage = fromInstalledPackage(packageName, platform, cwd, tried);
+    if (fromPackage)
+        return fromPackage;
+    const fromWorkspace = fromCargoTarget(cwd, platform, tried, options.prefer ?? "newest");
+    if (fromWorkspace)
+        return fromWorkspace;
+    throw new RuntimeNotFoundError(packageName, tried);
+}
+function fromInstalledPackage(packageName, platform, cwd, tried) {
+    const binary = runtimeBinaryName(platform);
+    // Resolve from the project first, then from this package, so an app can pin
+    // a runtime version that differs from the CLI's.
+    for (const from of [join(cwd, "package.json"), fileURLToPath(import.meta.url)]) {
+        try {
+            const require = createRequire(from);
+            const manifest = require.resolve(`${packageName}/package.json`);
+            const path = join(dirname(manifest), "bin", binary);
+            if (isExecutable(path))
+                return { path, source: "package", package: packageName };
+            tried.push(path);
+        }
+        catch {
+            // Not installed here; try the next resolution root.
+        }
+    }
+    tried.push(`${packageName} (not installed)`);
+    return undefined;
+}
+/**
+ * Find a locally built runtime by walking up for the Cargo workspace that
+ * contains it. Only used when developing Vantail itself.
+ */
+function fromCargoTarget(cwd, platform, tried, prefer) {
+    const binary = runtimeBinaryName(platform);
+    const roots = [cwd, dirname(fileURLToPath(import.meta.url))];
+    for (const start of roots) {
+        for (const root of ancestors(start)) {
+            if (!existsSync(join(root, "runtime", "Cargo.toml")))
+                continue;
+            const candidates = ["release", "debug"]
+                .map((profile) => ({ profile, path: join(root, "target", profile, binary) }))
+                .map((candidate) => ({ ...candidate, built: builtAt(candidate.path) }))
+                .filter((candidate) => candidate.built !== undefined)
+                .sort((a, b) => prefer === "release"
+                ? // Release first, whenever there is one.
+                    Number(b.profile === "release") - Number(a.profile === "release")
+                : // Otherwise whatever was built last: preferring release outright
+                    // means a `cargo build` while debugging silently changes
+                    // nothing, which is a confusing hour to spend.
+                    b.built - a.built);
+            const newest = candidates[0];
+            if (newest) {
+                return { path: newest.path, source: "workspace", profile: newest.profile };
+            }
+            tried.push(join(root, "target", "{release,debug}", binary));
+        }
+    }
+    return undefined;
+}
+/** Modification time, or `undefined` when there is no such file. */
+function builtAt(path) {
+    try {
+        const info = statSync(path);
+        return info.isFile() ? info.mtimeMs : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function* ancestors(from) {
+    let current = resolvePath(from);
+    while (true) {
+        yield current;
+        const parent = dirname(current);
+        if (parent === current)
+            return;
+        current = parent;
+    }
+}
+function isExecutable(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AA+BzC,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,WAAW,CAAS;IAE7B,YAAY,WAAmB,EAAE,KAAe;QAC9C,KAAK,CACH,2DAA2D;YACzD,mDAAmD,WAAW,MAAM;YACpE,6FAA6F;YAC7F,eAAe,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC/D,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF;AAED,+DAA+D;AAC/D,MAAM,UAAU,kBAAkB,CAChC,QAAQ,GAAoB,OAAO,CAAC,QAAQ,EAC5C,IAAI,GAAW,OAAO,CAAC,IAAI;IAE3B,OAAO,oBAAoB,QAAQ,IAAI,IAAI,EAAE,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,QAAQ,GAAoB,OAAO,CAAC,QAAQ;IAC5E,OAAO,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,iBAAiB,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAO,GAAmB,EAAE;IAC/D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IACtD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACzC,MAAM,WAAW,GAAG,kBAAkB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACvD,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACpD,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QACnC,IAAI,YAAY,CAAC,IAAI,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QACvD,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,8BAA8B,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,WAAW,GAAG,oBAAoB,CAAC,WAAW,EAAE,QAAQ,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAC5E,IAAI,WAAW;QAAE,OAAO,WAAW,CAAC;IAEpC,MAAM,aAAa,GAAG,eAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,IAAI,QAAQ,CAAC,CAAC;IACxF,IAAI,aAAa;QAAE,OAAO,aAAa,CAAC;IAExC,MAAM,IAAI,oBAAoB,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,oBAAoB,CAC3B,WAAmB,EACnB,QAAyB,EACzB,GAAW,EACX,KAAe;IAEf,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAE3C,4EAA4E;IAC5E,iDAAiD;IACjD,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,EAAE,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QAC/E,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;YACpC,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,WAAW,eAAe,CAAC,CAAC;YAChE,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;YACpD,IAAI,YAAY,CAAC,IAAI,CAAC;gBAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;YACjF,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,oDAAoD;QACtD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAG,WAAW,kBAAkB,CAAC,CAAC;IAC7C,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CACtB,GAAW,EACX,QAAyB,EACzB,KAAe,EACf,MAA4B;IAE5B,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAE7D,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACpC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;gBAAE,SAAS;YAE/D,MAAM,UAAU,GAAI,CAAC,SAAS,EAAE,OAAO,CAAW;iBAC/C,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;iBAC5E,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;iBACtE,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,KAAK,SAAS,CAAC;iBACpD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACb,MAAM,KAAK,SAAS;gBAClB,CAAC,CAAC,wCAAwC;oBACxC,MAAM,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC;gBACnE,CAAC,CAAC,iEAAiE;oBACjE,yDAAyD;oBACzD,+CAA+C;oBAC/C,CAAC,CAAC,KAAM,GAAG,CAAC,CAAC,KAAM,CACxB,CAAC;YAEJ,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;YAC7B,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;YAC7E,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,CAAC,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,oEAAoE;AACpE,SAAS,OAAO,CAAC,IAAY;IAC3B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC5B,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,QAAQ,CAAC,CAAC,SAAS,CAAC,IAAY;IAC9B,IAAI,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAChC,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,OAAO,CAAC;QACd,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,MAAM,KAAK,OAAO;YAAE,OAAO;QAC/B,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAChC,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@vantail/runtime",
+  "version": "0.1.0",
+  "description": "Locates the precompiled Vantail native runtime for the current platform.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vantail/vantail.git",
+    "directory": "packages/runtime"
+  },
+  "homepage": "https://github.com/Vantail/vantail",
+  "type": "module",
+  "files": [
+    "dist",
+    "platforms.json"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "optionalDependencies": {
+    "@vantail/runtime-darwin-arm64": "0.1.0",
+    "@vantail/runtime-win32-x64": "0.1.0",
+    "@vantail/runtime-win32-arm64": "0.1.0",
+    "@vantail/runtime-linux-x64": "0.1.0",
+    "@vantail/runtime-linux-arm64": "0.1.0"
+  }
+}

package/platforms.json

@@ -0,0 +1,10 @@
+{
+  "comment": "Targets the runtime is published for. `vantail package` and the release pipeline both read this.",
+  "targets": [
+    { "package": "@vantail/runtime-darwin-arm64", "platform": "darwin", "arch": "arm64", "rust": "aarch64-apple-darwin", "tier": 1 },
+    { "package": "@vantail/runtime-win32-x64", "platform": "win32", "arch": "x64", "rust": "x86_64-pc-windows-msvc", "tier": 1 },
+    { "package": "@vantail/runtime-win32-arm64", "platform": "win32", "arch": "arm64", "rust": "aarch64-pc-windows-msvc", "tier": 2 },
+    { "package": "@vantail/runtime-linux-x64", "platform": "linux", "arch": "x64", "rust": "x86_64-unknown-linux-gnu", "tier": 2 },
+    { "package": "@vantail/runtime-linux-arm64", "platform": "linux", "arch": "arm64", "rust": "aarch64-unknown-linux-gnu", "tier": 2 }
+  ]
+}