@rsc-kit/core 0.30.25 → 0.30.26

package/dist/native.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Native packages inside a compiled binary.
+ *
+ * A package with a native binary - sharp, a database driver - is left external
+ * by the build, and Nitro traces it into .output/server/node_modules. A server
+ * run from that directory loads it from there. `bun build --compile` cannot:
+ * it bundles the package's JavaScript, and the package then looks for its
+ * `.node` file beside a module that is no longer on disk, so the binary starts
+ * and dies on the first import of it.
+ *
+ * So a binary carries those packages as files, and writes them to disk the
+ * first time it runs: to `<RSC_KIT_RUNTIME_DIR>/<hash>/node_modules`, the
+ * binary's own directory when the variable is unset. The hash is of the files,
+ * so two versions sharing one directory during a deploy never share a tree,
+ * and a second start of the same version writes nothing.
+ *
+ * Inside a binary Bun resolves no package by name, from anywhere - not from
+ * the bundle, and not from a file on disk that the bundle loaded. Neither a
+ * `Module._resolveFilename` hook nor a runtime plugin sees an ESM import there.
+ * So every name is resolved here, at build time, while the tree is on disk:
+ * each import and require of a package in the tree is rewritten to a relative
+ * path, and the app's own imports of one go through a shim that loads it from
+ * the written tree. The hook stays, for a require whose name is computed.
+ *
+ * An app with nothing traced gets none of this: its compile entry is the one
+ * it always had.
+ */
+/** Where the compile tree is written, beside .output/server. */
+export declare const COMPILE_TREE_DIR = "compile";
+/** A platform a binary runs on, in the terms a package.json's os, cpu and libc use. */
+export interface Platform {
+    os: string;
+    arch: string;
+    /** Only on linux. */
+    libc?: 'glibc' | 'musl';
+}
+/** The platform this process runs on. */
+export declare function hostPlatform(): Platform;
+/**
+ * The platform a compile script targets: `--target=bun-linux-x64-musl`, or
+ * the build machine's own when it names none. `baseline` and `modern` are CPU
+ * levels of the same arch, and change nothing a package declares.
+ */
+export declare function targetPlatform(script: string | undefined, host?: Platform): Platform;
+export declare function describePlatform(platform: Platform): string;
+interface PackageJson {
+    name?: string;
+    version?: string;
+    main?: string;
+    exports?: unknown;
+    os?: string[];
+    cpu?: string[];
+    libc?: string[];
+    optionalDependencies?: Record<string, string>;
+}
+export declare function runsOn(pkg: PackageJson, platform: Platform): boolean;
+export interface MissingPackage {
+    name: string;
+    version?: string;
+}
+export interface NativeSet {
+    /** Package directory (relative to the tree's node_modules) to the directory its files are read from. */
+    packages: Map<string, string>;
+    missing: MissingPackage[];
+}
+/**
+ * The packages a binary for `target` needs: what Nitro traced, with each
+ * package built for the build machine swapped for the one built for the
+ * target. Nitro traces what is installed and loads on this machine, so a Mac
+ * compiling for linux-x64 traced darwin binaries; the linux ones are found
+ * beside them in the project's node_modules, or reported as missing.
+ */
+export declare function nativeSet(serverNodeModules: string, projectRoot: string, target: Platform, named?: readonly string[]): NativeSet;
+export declare function missingMessage(missing: MissingPackage[], target: Platform, host: Platform): string;
+/**
+ * Every package name in a module's imports and requires, rewritten to the
+ * relative path of the file it resolves to inside the tree. A name the tree
+ * does not have - a branch for another platform, an optional peer - is left
+ * as it is. A file the parser cannot read is left whole; its requires reach
+ * the hook at runtime.
+ */
+export declare function rewriteSpecifiers(code: string, file: string, treeRoot: string, parse: (code: string) => unknown, exists?: (path: string) => boolean): string;
+/**
+ * What the binary runs before the first import of a native package: write the
+ * tree if this version has not, then answer each shim's require from it.
+ *
+ * Extraction is into a temporary directory renamed into place, so a tree that
+ * exists is a whole one: two copies starting at once each write their own,
+ * one rename wins, and the other discards its copy. A running copy touches its
+ * tree hourly, and a start removes the trees of other versions that nothing
+ * has touched for a day - never its own, and never one a running copy of
+ * another version is still using.
+ */
+export declare const RUNTIME_SOURCE = "'use strict'\nconst { hash, files } = require('./natives.mjs')\nconst fs = require('node:fs')\nconst path = require('node:path')\nconst Module = require('node:module')\n\nconst HOUR = 60 * 60 * 1000\nconst STALE = 24 * HOUR\n\nlet base\n\nfunction prepare() {\n  const root = process.env.RSC_KIT_RUNTIME_DIR ? path.resolve(process.env.RSC_KIT_RUNTIME_DIR) : path.dirname(process.execPath)\n  const dir = path.join(root, hash)\n\n  if (!fs.existsSync(dir)) {\n    try {\n      fs.mkdirSync(root, { recursive: true })\n      const tmp = fs.mkdtempSync(path.join(root, '.' + hash + '-'))\n      for (const [rel, src] of files) {\n        const to = path.join(tmp, 'node_modules', rel)\n        fs.mkdirSync(path.dirname(to), { recursive: true })\n        fs.writeFileSync(to, fs.readFileSync(src))\n      }\n      try {\n        fs.renameSync(tmp, dir)\n        console.log('[rsc-kit] native packages: wrote ' + files.length + ' files to ' + dir)\n      } catch (error) {\n        fs.rmSync(tmp, { recursive: true, force: true })\n        if (!fs.existsSync(dir)) throw error\n      }\n    } catch (error) {\n      error.message =\n        '[rsc-kit] the binary could not write its native packages to ' + root + ': ' + error.message +\n        '. Set RSC_KIT_RUNTIME_DIR to a directory it can write to.'\n      throw error\n    }\n  }\n\n  const touch = () => { try { const now = new Date(); fs.utimesSync(dir, now, now) } catch {} }\n  touch()\n  setInterval(touch, HOUR).unref()\n  sweep(root, path.basename(dir))\n\n  base = path.join(dir, 'node_modules')\n\n  // A require whose name is computed - require(name) - was not rewritten at\n  // build time, and the binary's resolver cannot find it on disk. Answered\n  // from the tree, for files inside it only.\n  const resolve = Module._resolveFilename\n  Module._resolveFilename = function (request, parent, ...rest) {\n    try {\n      return resolve.call(this, request, parent, ...rest)\n    } catch (error) {\n      const from = parent && parent.filename\n      if (!from || !from.startsWith(dir) || request.startsWith('.') || request.startsWith('/') || Module.isBuiltin(request)) throw error\n      const found = lookup(request, path.dirname(from))\n      if (!found) throw error\n      return found\n    }\n  }\n}\n\nfunction sweep(root, current) {\n  let entries\n  try { entries = fs.readdirSync(root, { withFileTypes: true }) } catch { return }\n  const now = Date.now()\n  for (const entry of entries) {\n    if (!entry.isDirectory() || entry.name === current) continue\n    const isTree = /^[0-9a-f]{16}$/.test(entry.name)\n    const isPartial = /^\\.[0-9a-f]{16}-/.test(entry.name)\n    if (!isTree && !isPartial) continue\n    try {\n      const age = now - fs.statSync(path.join(root, entry.name)).mtimeMs\n      if (age > (isTree ? STALE : HOUR)) fs.rmSync(path.join(root, entry.name), { recursive: true, force: true })\n    } catch {}\n  }\n}\n\nfunction lookup(request, fromDir) {\n  const parts = request.split('/')\n  const name = request.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0]\n  const sub = request.slice(name.length)\n  for (let dir = fromDir; dir.startsWith(base) || dir === path.dirname(base); dir = path.dirname(dir)) {\n    const pkgDir = path.join(dir, 'node_modules', name)\n    if (fs.existsSync(path.join(pkgDir, 'package.json'))) {\n      if (sub) return path.join(pkgDir, sub)\n      const pkg = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8'))\n      return path.join(pkgDir, pkg.main || 'index.js')\n    }\n    if (dir === path.dirname(base)) break\n  }\n}\n\nmodule.exports = function load(entry) {\n  if (!base) prepare()\n  const loaded = require(path.join(base, entry))\n  // A package with only an ES module: required, it is a namespace, which an\n  // import of the shim would otherwise take as a CommonJS module's exports.\n  if (Object.prototype.toString.call(loaded) === '[object Module]') return { __esModule: true, ...loaded }\n  return loaded\n}\n";
+export interface CompileTree {
+    hash: string;
+    files: number;
+    packages: string[];
+}
+/**
+ * Write the compile tree for a server whose build traced external packages,
+ * and point compile.mjs at it. Returns undefined, and touches nothing, when
+ * there is nothing traced.
+ *
+ * The tree is a copy of the server with each traced package replaced by a
+ * shim, so `bun build --compile` bundles the shim and embeds the package's
+ * files: the server's own chunks import packages by name, and Bun resolves a
+ * name from the importing file's location, so the copy is what makes those
+ * names land on the shims rather than on the real packages beside the server.
+ */
+export declare function writeCompileTree(options: {
+    serverDir: string;
+    projectRoot: string;
+    target: Platform;
+    parse: (code: string) => unknown;
+    /** serverExternalPackages, which go to disk whether or not they have a binary. */
+    named?: readonly string[];
+}): CompileTree | {
+    missing: MissingPackage[];
+} | undefined;
+/** The size of a directory, for the build's one line about it. */
+export declare function sizeOf(dir: string): number;
+export {};