@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/smol/https.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @file Lazy-loader for socket-btm's `node:smol-https`. `node:smol-https` is
+ *   the HTTPS-flavored server entry shipped by socket-btm's smol Node binary.
+ *   It wraps `node:smol-http`'s `serve` with performance-oriented TLS defaults
+ *   (X25519+P-256 curves, pre-vetted cipher list, 24-hour session timeout) and
+ *   validates that TLS options are present. Returns `undefined` on stock Node +
+ *   non-Node runtimes. Result is cached across calls.
+ *
+ * @internal — `src/http-request/` is the natural consumer. Most
+ *   callers should use the standard server-side helpers, which
+ *   route through this when smol is present.
+ */
+/**
+ * TLS options accepted by `smol-https`'s `serve()`. Mirrors Node's
+ * `tls.TlsOptions` for the fields socket-lib reads; callers needing more can
+ * widen the type at the callsite.
+ */
+export interface SmolHttpsTlsOptions {
+    readonly key?: Buffer | string | undefined;
+    readonly cert?: Buffer | string | undefined;
+    readonly ca?: Buffer | string | ReadonlyArray<Buffer | string> | undefined;
+    readonly passphrase?: string | undefined;
+    readonly sessionTimeout?: number | undefined;
+    readonly honorCipherOrder?: boolean | undefined;
+    readonly ecdhCurve?: string | undefined;
+    readonly ciphers?: string | undefined;
+}
+/**
+ * Options accepted by `smol-https`'s `serve()`. Mirrors `smol-http`'s `serve`
+ * options + TLS extensions.
+ */
+export interface SmolHttpsServeOptions {
+    readonly port?: number | undefined;
+    readonly hostname?: string | undefined;
+    readonly key?: Buffer | string | undefined;
+    readonly cert?: Buffer | string | undefined;
+    readonly ca?: Buffer | string | ReadonlyArray<Buffer | string> | undefined;
+    readonly passphrase?: string | undefined;
+    readonly tls?: SmolHttpsTlsOptions | undefined;
+    fetch(request: unknown): unknown | Promise<unknown>;
+}
+/**
+ * Surface of `node:smol-https`. See socket-btm's
+ * additions/source-patched/lib/smol-https.js for the canonical shape — a single
+ * `serve()` factory backed by `smol-http.serve()` plus injected fast-TLS
+ * defaults.
+ */
+export interface SmolHttpsBinding {
+    /**
+     * Create an HTTPS server. Throws `TypeError` when no TLS options are provided
+     * (use `node:smol-http`'s `serve()` for plain HTTP).
+     */
+    serve(options: SmolHttpsServeOptions): unknown;
+}
+/**
+ * Returns `node:smol-https` when running on the smol Node binary, otherwise
+ * `undefined`. Result is cached across calls.
+ */
+export declare function getSmolHttps(): SmolHttpsBinding | undefined;

package/dist/smol/https.js

@@ -0,0 +1,42 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var https_exports = {};
+__export(https_exports, {
+  getSmolHttps: () => getSmolHttps
+});
+module.exports = __toCommonJS(https_exports);
+var import_module = require("../node/module");
+let _smolHttps;
+let _smolHttpsProbed = false;
+// @__NO_SIDE_EFFECTS__
+function getSmolHttps() {
+  if (!_smolHttpsProbed) {
+    _smolHttpsProbed = true;
+    if ((0, import_module.isNodeBuiltin)("node:smol-https")) {
+      _smolHttps = require("node:smol-https");
+    }
+  }
+  return _smolHttps;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getSmolHttps
+});

package/dist/smol/manifest.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @file Lazy-loader for socket-btm's `node:smol-manifest`. `node:smol-manifest`
+ *   is the manifest + lockfile parser exposed by socket-btm's smol Node binary.
+ *   It parses package.json, package-lock (npm v1/v2/v3), yarn.lock (classic +
+ *   berry), and pnpm-lock.yaml (v5/v6/v9) with internal primordial-hardened
+ *   parsing. Returns `undefined` on stock Node + non-Node runtimes. Result is
+ *   cached across calls. Callers fall back to the JS parsers under
+ *   `src/eco/<pm>/parse-*` on the undefined path.
+ *
+ * @internal — used by `src/eco/manifest/*` leaves to resolve the
+ *   smol-aware parsers. Most callers should import the specific leaf
+ *   (`@socketsecurity/lib/eco/manifest/parse`), which already routes
+ *   through this when smol is present.
+ */
+import type { EcosystemString } from '../eco/purl';
+/**
+ * Dependency-relationship tag on a parsed package reference.
+ *
+ * - `prod` — runtime dependency
+ * - `dev` — devDependency
+ * - `optional` — optionalDependency
+ * - `peer` — peerDependency
+ */
+export type DepType = 'prod' | 'dev' | 'optional' | 'peer';
+/**
+ * A single package entry inside a parsed lockfile. Frozen plain object with
+ * `__proto__: null` on smol; JS-fallback parsers return the same shape so
+ * consumers can't tell which impl ran.
+ */
+export interface PackageRef {
+    readonly name: string;
+    readonly version: string;
+    readonly resolved: string | undefined;
+    readonly integrity: string | undefined;
+    readonly ecosystem: EcosystemString;
+    readonly depType: DepType;
+    readonly isDev: boolean;
+    readonly isOptional: boolean;
+    readonly isPeer: boolean;
+    readonly isBundled: boolean;
+    readonly license?: string | undefined;
+    readonly vcsUrl: string | undefined;
+    readonly vcsCommit: string | undefined;
+    readonly dependencies: readonly string[];
+}
+/**
+ * A single dependency entry inside a parsed manifest (package.json).
+ */
+export interface ManifestDep {
+    readonly name: string;
+    readonly versionRange: string;
+    readonly type: DepType;
+    readonly optional: boolean;
+}
+/**
+ * Result of parsing a manifest (e.g. `package.json`).
+ */
+export interface ParsedManifest {
+    readonly type: 'manifest';
+    readonly name: string | undefined;
+    readonly version: string | undefined;
+    readonly description: string | undefined;
+    readonly license: string | undefined;
+    readonly repository: string | undefined;
+    readonly dependencies: readonly ManifestDep[];
+    readonly ecosystem: EcosystemString;
+}
+/**
+ * Result of parsing a lockfile (npm/yarn/pnpm). `_index` is a private
+ * name→index map (or `name→number[]` for multi-version) used by `getPackage` /
+ * `getPackageVersions` for O(1) lookup.
+ */
+export interface ParsedLockfile {
+    readonly type: 'lockfile';
+    readonly lockVersion: string;
+    readonly ecosystem: EcosystemString;
+    readonly packages: readonly PackageRef[];
+    readonly _index: Readonly<Record<string, number | readonly number[]>>;
+}
+/**
+ * Format descriptor returned by `detectFormat`.
+ */
+export interface FormatDescriptor {
+    readonly ecosystem: EcosystemString;
+    readonly type: 'manifest' | 'lockfile';
+    readonly format?: 'npm' | 'yarn' | 'pnpm' | 'composer' | 'cargo';
+}
+/**
+ * Supported-files index returned by `supportedFiles`.
+ */
+export interface SupportedFiles {
+    readonly manifests: readonly string[];
+    readonly lockfiles: readonly string[];
+}
+/**
+ * Statistics returned by `analyzeLockfile`.
+ */
+export interface LockfileStats {
+    readonly totalPackages: number;
+    readonly prodDeps: number;
+    readonly devDeps: number;
+    readonly optionalDeps: number;
+    readonly byEcosystem: Readonly<Record<string, number>>;
+    readonly maxDepth: number;
+    readonly avgDepth: number;
+}
+/**
+ * Error class thrown by every parser on invalid / unsupported input. The `code`
+ * field is one of:
+ *
+ * - `ERR_INVALID_JSON` — JSON.parse failure
+ * - `ERR_UNKNOWN_FORMAT` — filename or content didn't match a parser
+ * - `ERR_UNSUPPORTED` — ecosystem not yet implemented
+ */
+export interface ManifestErrorLike extends Error {
+    readonly name: 'ManifestError';
+    readonly code: string;
+}
+/**
+ * Surface of `node:smol-manifest`. See socket-btm's
+ * additions/source-patched/lib/smol-manifest.js for the canonical shape.
+ */
+export interface SmolManifestBinding {
+    parse(filename: string, content: string): ParsedManifest | ParsedLockfile;
+    parseManifest(content: string, ecosystem: EcosystemString): ParsedManifest;
+    parseLockfile(content: string, ecosystem: EcosystemString, format?: 'npm' | 'yarn' | 'pnpm' | 'composer' | 'cargo'): ParsedLockfile;
+    createStreamingParser(content: string, ecosystem: EcosystemString): AsyncIterableIterator<PackageRef>;
+    analyzeLockfile(lockfile: ParsedLockfile): LockfileStats;
+    getPackage(lockfile: ParsedLockfile, name: string): PackageRef | undefined;
+    getPackageVersions(lockfile: ParsedLockfile, name: string): readonly PackageRef[];
+    findPackages(lockfile: ParsedLockfile, pattern: string | RegExp): readonly PackageRef[];
+    detectFormat(filename: string): FormatDescriptor | undefined;
+    readonly supportedFiles: SupportedFiles;
+    readonly ManifestError: new (message: string, code: string) => ManifestErrorLike;
+}
+/**
+ * Returns `node:smol-manifest` when running on the smol Node binary, otherwise
+ * `undefined`. Result is cached across calls.
+ */
+export declare function getSmolManifest(): SmolManifestBinding | undefined;

package/dist/smol/manifest.js

@@ -0,0 +1,42 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var manifest_exports = {};
+__export(manifest_exports, {
+  getSmolManifest: () => getSmolManifest
+});
+module.exports = __toCommonJS(manifest_exports);
+var import_module = require("../node/module");
+let _smolManifest;
+let _smolManifestProbed = false;
+// @__NO_SIDE_EFFECTS__
+function getSmolManifest() {
+  if (!_smolManifestProbed) {
+    _smolManifestProbed = true;
+    if ((0, import_module.isNodeBuiltin)("node:smol-manifest")) {
+      _smolManifest = require("node:smol-manifest");
+    }
+  }
+  return _smolManifest;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getSmolManifest
+});

package/dist/smol/primordial.d.ts

@@ -1,16 +1,11 @@
 /**
- * @fileoverview Lazy-loader for socket-btm's `node:smol-primordial`
- * binding.
- *
- * `node:smol-primordial` provides V8 Fast API typed implementations
- * of Math.* and Number.is* primordials, registered with
- * `CFunction::Make()` so TurboFan inlines them directly into JIT-
- * compiled JS callers. Bypasses the FunctionCallbackInfo trampoline
- * entirely — ~30-50% gain on hot loops where V8 doesn't already
- * auto-inline.
- *
- * Returns `undefined` on stock Node + non-Node runtimes. Result is
- * cached across calls.
+ * @file Lazy-loader for socket-btm's `node:smol-primordial` binding.
+ *   `node:smol-primordial` provides V8 Fast API typed implementations of Math.*
+ *   and Number.is* primordials, registered with `CFunction::Make()` so TurboFan
+ *   inlines them directly into JIT- compiled JS callers. Bypasses the
+ *   FunctionCallbackInfo trampoline entirely — ~30-50% gain on hot loops where
+ *   V8 doesn't already auto-inline. Returns `undefined` on stock Node +
+ *   non-Node runtimes. Result is cached across calls.
  *
  * @internal — used by `src/primordials.ts` to resolve smol-aware
  *   Math.* / Number.is* fast paths. Most callers should use the
@@ -21,14 +16,13 @@
  */
 /**
  * Surface of `node:smol-primordial`. See socket-btm's
- * additions/source-patched/lib/smol-primordial.js for the canonical
- * shape.
+ * additions/source-patched/lib/smol-primordial.js for the canonical shape.
  *
- * Each entry is registered as a `v8::CFunction` so V8 can inline the
- * C++ implementation directly into JIT-compiled callers — eliminating
- * the FunctionCallbackInfo allocation, the HandleScope, and the call-
- * site trampoline. See the C++ binding file for which signatures
- * get real wins (and which don't).
+ * Each entry is registered as a `v8::CFunction` so V8 can inline the C++
+ * implementation directly into JIT-compiled callers — eliminating the
+ * FunctionCallbackInfo allocation, the HandleScope, and the call- site
+ * trampoline. See the C++ binding file for which signatures get real wins (and
+ * which don't).
  */
 export interface SmolPrimordialBinding {
     arrayIsArray(v: unknown): v is unknown[];
@@ -72,9 +66,10 @@ export interface SmolPrimordialBinding {
     numberParseFloat(s: string): number;
     numberParseInt10(s: string): number;
     stringCharCodeAt(s: string, i: number): number;
+    stringIsWellFormed(s: string): boolean;
 }
 /**
- * Returns `node:smol-primordial` when running on the smol Node
- * binary, otherwise `undefined`. Result is cached across calls.
+ * Returns `node:smol-primordial` when running on the smol Node binary,
+ * otherwise `undefined`. Result is cached across calls.
  */
 export declare function getSmolPrimordial(): SmolPrimordialBinding | undefined;

package/dist/smol/primordial.js

@@ -23,22 +23,18 @@ __export(primordial_exports, {
   getSmolPrimordial: () => getSmolPrimordial
 });
 module.exports = __toCommonJS(primordial_exports);
-var import_util = require("./util");
+var import_module = require("../node/module");
 let _smolPrimordial;
+let _smolPrimordialProbed = false;
 // @__NO_SIDE_EFFECTS__
 function getSmolPrimordial() {
-  if (_smolPrimordial === void 0) {
-    if ((0, import_util.isSmol)()) {
-      try {
-        _smolPrimordial = require("node:smol-primordial");
-      } catch {
-        _smolPrimordial = null;
-      }
-    } else {
-      _smolPrimordial = null;
+  if (!_smolPrimordialProbed) {
+    _smolPrimordialProbed = true;
+    if ((0, import_module.isNodeBuiltin)("node:smol-primordial")) {
+      _smolPrimordial = require("node:smol-primordial");
     }
   }
-  return _smolPrimordial ?? void 0;
+  return _smolPrimordial;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/smol/purl.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @file Lazy-loader for socket-btm's `node:smol-purl` binding. `node:smol-purl`
+ *   is a C++-accelerated PURL (Package URL) parser exposed by socket-btm's smol
+ *   Node binary. It parses, builds, and validates PURL strings using
+ *   primordial-cached string ops, with a 10 000-entry result cache. Returns
+ *   `undefined` on stock Node + non-Node runtimes. Result is cached across
+ *   calls. Callers fall back to the JS `@socketregistry/packageurl-js` import
+ *   on the undefined path.
+ *
+ * @internal — used by `src/packages/operations.ts` to resolve the
+ *   `pkg:npm/<name>` parse on `resolveRegistryPackageName`. Most
+ *   callers should keep using `PackageURL` from
+ *   `external/@socketregistry/packageurl-js` directly; this loader
+ *   only matters where the hot path warrants the native acceleration.
+ */
+/**
+ * Surface of a parsed PURL — the shape both smol-purl's `parse()` and
+ * `packageurl-js`'s `PackageURL.fromString()` agree on. Frozen plain object on
+ * smol; `PackageURL` class instance on stock Node. Both expose the same
+ * readable fields, so consumers can destructure uniformly.
+ */
+export interface ParsedPurl {
+    readonly type: string;
+    readonly namespace: string | undefined;
+    readonly name: string;
+    readonly version: string | undefined;
+    readonly qualifiers: Readonly<Record<string, string>> | undefined;
+    readonly subpath: string | undefined;
+}
+/**
+ * Options passed to a PURL builder. Mirrors the constructor args of
+ * `PackageURL.fromObject` and the input object accepted by smol-purl's
+ * `build()`.
+ */
+export interface PurlBuildOptions {
+    type: string;
+    namespace?: string | undefined;
+    name: string;
+    version?: string | undefined;
+    qualifiers?: Readonly<Record<string, string>> | undefined;
+    subpath?: string | undefined;
+}
+/**
+ * Surface of `node:smol-purl`. See socket-btm's
+ * additions/source-patched/lib/smol-purl.js for the canonical shape.
+ *
+ * Only the ops socket-lib actually uses are typed here; smol-purl also exposes
+ * `parseBatch`, `cacheStats`, `clearCache`, `types`, etc., but those aren't
+ * part of the lib's consumer surface today.
+ */
+export interface SmolPurlBinding {
+    /**
+     * Parse a PURL string. Throws `PurlError` on invalid input.
+     */
+    parse(purl: string): ParsedPurl;
+    /**
+     * Try to parse a PURL string. Returns `undefined` on any failure (matches the
+     * Safe-suffix non-throwing convention).
+     */
+    tryParse(purl: string): ParsedPurl | undefined;
+    /**
+     * Build a PURL string from components. Throws on invalid input (missing type
+     * / name).
+     */
+    build(options: PurlBuildOptions): string;
+    /**
+     * Returns `true` if the input is a valid PURL string.
+     */
+    isValid(purl: string): boolean;
+    /**
+     * Normalize a PURL — lowercases the type, sorts qualifier keys, and
+     * round-trips through parse + build.
+     */
+    normalize(purl: string): string;
+    /**
+     * Compare two PURLs for normalized equality.
+     */
+    equals(a: string, b: string): boolean;
+}
+/**
+ * Returns `node:smol-purl` when running on the smol Node binary, otherwise
+ * `undefined`. Result is cached across calls.
+ */
+export declare function getSmolPurl(): SmolPurlBinding | undefined;

package/dist/smol/purl.js

@@ -0,0 +1,42 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var purl_exports = {};
+__export(purl_exports, {
+  getSmolPurl: () => getSmolPurl
+});
+module.exports = __toCommonJS(purl_exports);
+var import_module = require("../node/module");
+let _smolPurl;
+let _smolPurlProbed = false;
+// @__NO_SIDE_EFFECTS__
+function getSmolPurl() {
+  if (!_smolPurlProbed) {
+    _smolPurlProbed = true;
+    if ((0, import_module.isNodeBuiltin)("node:smol-purl")) {
+      _smolPurl = require("node:smol-purl");
+    }
+  }
+  return _smolPurl;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getSmolPurl
+});

package/dist/smol/versions.d.ts

@@ -1,13 +1,10 @@
 /**
- * @fileoverview Lazy-loader for socket-btm's `node:smol-versions`.
- *
- * `node:smol-versions` is the multi-ecosystem version helper exposed
- * by socket-btm's smol Node binary. It supports npm/maven/pypi/nuget/
- * gem version comparison + range satisfies with internal C++
- * acceleration on the npm hot path.
- *
- * Returns `undefined` on stock Node + non-Node runtimes. Result is
- * cached across calls.
+ * @file Lazy-loader for socket-btm's `node:smol-versions`. `node:smol-versions`
+ *   is the multi-ecosystem version helper exposed by socket-btm's smol Node
+ *   binary. It supports npm/maven/pypi/nuget/ gem version comparison + range
+ *   satisfies with internal C++ acceleration on the npm hot path. Returns
+ *   `undefined` on stock Node + non-Node runtimes. Result is cached across
+ *   calls.
  *
  * @internal — used by `src/versions.ts` to resolve smol-aware version
  *   ops. Most callers should use the standard `versions` exports,
@@ -15,9 +12,9 @@
  */
 /**
  * Surface of `node:smol-versions`. See socket-btm's
- * additions/source-patched/lib/smol-versions.js for the canonical
- * shape. Each entry takes an optional `ecosystem` (default `'npm'`)
- * — pass it for non-npm versions; npm callers can omit.
+ * additions/source-patched/lib/smol-versions.js for the canonical shape. Each
+ * entry takes an optional `ecosystem` (default `'npm'`) — pass it for non-npm
+ * versions; npm callers can omit.
  */
 export interface SmolVersionsBinding {
     compare(a: string, b: string, ecosystem?: string): -1 | 0 | 1;
@@ -40,7 +37,7 @@ export interface SmolVersionsBinding {
     coerce(version: string, ecosystem?: string): string | undefined;
 }
 /**
- * Returns `node:smol-versions` when running on the smol Node binary,
- * otherwise `undefined`. Result is cached across calls.
+ * Returns `node:smol-versions` when running on the smol Node binary, otherwise
+ * `undefined`. Result is cached across calls.
  */
 export declare function getSmolVersions(): SmolVersionsBinding | undefined;

package/dist/smol/versions.js

@@ -23,22 +23,18 @@ __export(versions_exports, {
   getSmolVersions: () => getSmolVersions
 });
 module.exports = __toCommonJS(versions_exports);
-var import_util = require("./util");
+var import_module = require("../node/module");
 let _smolVersions;
+let _smolVersionsProbed = false;
 // @__NO_SIDE_EFFECTS__
 function getSmolVersions() {
-  if (_smolVersions === void 0) {
-    if ((0, import_util.isSmol)()) {
-      try {
-        _smolVersions = require("node:smol-versions");
-      } catch {
-        _smolVersions = null;
-      }
-    } else {
-      _smolVersions = null;
+  if (!_smolVersionsProbed) {
+    _smolVersionsProbed = true;
+    if ((0, import_module.isNodeBuiltin)("node:smol-versions")) {
+      _smolVersions = require("node:smol-versions");
     }
   }
-  return _smolVersions ?? void 0;
+  return _smolVersions;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/smol/vfs.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @file Lazy-loader for socket-btm's `node:smol-vfs`. Targets the
+ *   **post-alignment** shape that mirrors upstream `node:vfs` (PR
+ *   nodejs/node#61478). socket-btm's runtime is being patched in lockstep with
+ *   this lib to match. Alignment summary vs. upstream `node:vfs`:
+ *
+ *   - `node:smol-vfs` exports a single `getSmolVfs()` accessor that returns a
+ *     `SmolVirtualFileSystem` instance pre-mounted at the SEA prefix (default
+ *     `/sea`).
+ *   - `vfs.mounted` (boolean), `vfs.mountPoint` (string | null) — instance
+ *     getters matching upstream.
+ *   - `vfs.extract(suffix)` — socket-btm-specific addition that returns a real-fs
+ *     path to an embedded asset. Upstream `node:vfs` doesn't have this — you'd
+ *     work via the patched `fs` namespace after `mount()`. We need real-fs
+ *     paths to spawn binaries (Bazel, SBT launcher, JRE's `bin/java`), so btm
+ *     carries this as a non-upstream extension.
+ *   - No `NODE_VFS_PREFIX` env-var override anywhere; prefix is set at build time
+ *     and immutable at runtime. Returns `undefined` on stock Node, non-Node
+ *     runtimes, and on socket-btm binaries that haven't yet shipped the aligned
+ *     binding. Result is cached across calls. Callers fall back to PATH lookup
+ *     (or out-of-band downloads in socket-cli's case) when this is missing.
+ */
+/**
+ * A `SmolVirtualFileSystem` instance mirroring upstream `node:vfs`'s
+ * `VirtualFileSystem`. Named with the `Smol` prefix to avoid collision if a
+ * consumer also imports `node:vfs`'s `VirtualFileSystem` in the same module —
+ * both can coexist with explicit names.
+ *
+ * Only the properties + methods socket-lib's external-tools resolvers consume
+ * are typed here. The full upstream surface (the `fs`-compatible reader API,
+ * `provider`, `readonly`, `overlay`, `[Symbol.dispose]`, etc.) is intentionally
+ * omitted — consumers that need them can widen the type at the callsite.
+ */
+export interface SmolVirtualFileSystem {
+    /**
+     * `true` once `mount(prefix)` has been called and not yet `unmount()`-ed.
+     * Mirrors upstream's `vfs.mounted` getter.
+     */
+    readonly mounted: boolean;
+    /**
+     * The path prefix this VFS is mounted at (e.g. `/sea`). `null` before
+     * `mount()` runs. Mirrors upstream's `vfs.mountPoint`.
+     */
+    readonly mountPoint: string | null;
+    /**
+     * Extract an embedded file or directory tree to the real filesystem and
+     * return its absolute path. Idempotent — the VFS cache deduplicates writes
+     * across repeated calls.
+     *
+     * `suffix` is a relative key inside the VFS payload (e.g. `'bazel'` or
+     * `'jre'`); the binding handles prefix concatenation internally. Pass bare
+     * keys, not `${mountPoint}/${suffix}`.
+     *
+     * NOT in upstream `node:vfs` — socket-btm extension for the "spawn an
+     * embedded binary" use case. Upstream callers materialize indirectly via the
+     * patched `fs.readFileSync` etc., which doesn't fit binary-execution flows.
+     */
+    extract(suffix: string): Promise<string>;
+    /**
+     * Sync equivalent of `extract()`. Prefer the async form unless you need to
+     * extract before the event loop is available (early bootstrap, native-addon
+     * load).
+     */
+    extractSync(suffix: string): string;
+    /**
+     * `true` if `suffix` is present in the embedded payload. Does NOT trigger
+     * extraction. `suffix` is the bare relative key, same as `extract()`.
+     */
+    has(suffix: string): boolean;
+}
+/**
+ * Surface of `node:smol-vfs` (post-alignment).
+ *
+ * The module exports a single accessor — `getSmolVfs()` — which returns the
+ * pre-mounted SEA VFS instance, or `undefined` when no SEA payload is
+ * embedded.
+ *
+ * Note: the method name is `getSmolVfs` on both sides (this binding type AND
+ * the lib's accessor below). socket-lib's `getSmolVfs()` is a memoizing
+ * pass-through that calls `binding.getSmolVfs()` once per process.
+ */
+export interface SmolVirtualFileSystemBinding {
+    /**
+     * Returns the `SmolVirtualFileSystem` instance auto-mounted at the SEA prefix
+     * (default `/sea`), or `undefined` when the binary has no embedded VFS
+     * payload.
+     */
+    getSmolVfs(): SmolVirtualFileSystem | undefined;
+}
+/**
+ * Returns the pre-mounted SEA `SmolVirtualFileSystem` instance when running on
+ * a smol Node binary with an embedded SEA payload; otherwise `undefined`.
+ * Result is cached across calls.
+ *
+ * This is the only accessor external-tools resolvers need — the `node:smol-vfs`
+ * binding-module loader is collapsed into this function so callers don't deal
+ * with two indirection levels.
+ */
+export declare function getSmolVfs(): SmolVirtualFileSystem | undefined;