socket-function 1.2.36 → 1.2.38

package/SocketFunction.d.ts

@@ -1,5 +1,6 @@
 /// <reference path="require/RequireController.d.ts" />
 /// <reference types="node" />
+/// <reference types="node" />
 import { SocketExposedInterface, SocketFunctionHook, SocketFunctionClientHook, SocketExposedShape, SocketRegistered, CallerContext, FullCallType, SocketRegisterType } from "./SocketFunctionTypes";
 import { SocketServerConfig } from "./src/webSocketServer";
 import { Args, MaybePromise } from "./src/types";

package/index.d.ts

@@ -9,6 +9,7 @@ declare module "socket-function/SetProcessVariables" {
 declare module "socket-function/SocketFunction" {
     /// <reference path="require/RequireController.d.ts" />
     /// <reference types="node" />
+    /// <reference types="node" />
     import { SocketExposedInterface, SocketFunctionHook, SocketFunctionClientHook, SocketExposedShape, SocketRegistered, CallerContext, FullCallType, SocketRegisterType } from "socket-function/SocketFunctionTypes";
     import { SocketServerConfig } from "socket-function/src/webSocketServer";
     import { Args, MaybePromise } from "socket-function/src/types";
@@ -320,6 +321,7 @@ declare module "socket-function/require/CSSShim" {
 declare module "socket-function/require/RequireController" {
     /// <reference path="../../typenode/index.d.ts" />
     /// <reference types="node" />
+    /// <reference types="node" />
     declare global {
         namespace NodeJS {
             interface Module {
@@ -449,6 +451,7 @@ declare module "socket-function/require/compileFlags" {
 }
 
 declare module "socket-function/require/extMapper" {
+    /// <reference types="node" />
     /// <reference types="node" />
     export declare function getExtContentType(ext: string): string;
     export declare function getContentTypeFromBuffer(buffer: Buffer): string | undefined;
@@ -474,6 +477,7 @@ declare module "socket-function/require/require" {
 }
 
 declare module "socket-function/src/CallFactory" {
+    /// <reference types="node" />
     /// <reference types="node" />
     /// <reference types="node" />
     import { CallType } from "socket-function/SocketFunctionTypes";
@@ -532,6 +536,7 @@ declare module "socket-function/src/CallFactory" {
 }
 
 declare module "socket-function/src/JSONLACKS/JSONLACKS" {
+    /// <reference types="node" />
     /// <reference types="node" />
     export interface JSONLACKS_ParseConfig {
         extended?: boolean;
@@ -567,6 +572,7 @@ declare module "socket-function/src/JSONLACKS/JSONLACKS.generated.js" {
 }
 
 declare module "socket-function/src/Zip" {
+    /// <reference types="node" />
     /// <reference types="node" />
     import { MaybePromise } from "socket-function/src/types";
     export declare class Zip {
@@ -654,6 +660,7 @@ declare module "socket-function/src/batching" {
 }
 
 declare module "socket-function/src/bits" {
+    /// <reference types="node" />
     /// <reference types="node" />
     /** Subtracts the smallest possible value from a number (a double). This makes it possible to convert an exclusive range end
      *      to an inclusive range end, which is sometimes required (as in, < x is the same as <= minusEpsilon(x)).
@@ -680,6 +687,7 @@ declare module "socket-function/src/bits" {
 }
 
 declare module "socket-function/src/buffers" {
+    /// <reference types="node" />
     /// <reference types="node" />
     export type ArrayBufferViewTypes = Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | BigUint64Array | BigInt64Array | Float64Array | Float32Array | Uint8ClampedArray;
     export type BufferType = ArrayBuffer | SharedArrayBuffer | ArrayBufferViewTypes;
@@ -757,6 +765,7 @@ declare module "socket-function/src/caching" {
 }
 
 declare module "socket-function/src/callHTTPHandler" {
+    /// <reference types="node" />
     /// <reference types="node" />
     /// <reference types="node" />
     import http from "http";
@@ -811,6 +820,7 @@ declare module "socket-function/src/callManager" {
 }
 
 declare module "socket-function/src/certStore" {
+    /// <reference types="node" />
     /// <reference types="node" />
     /** Must be populated before the server starts */
     export declare function trustCertificate(cert: string | Buffer): void;
@@ -1046,6 +1056,7 @@ declare module "socket-function/src/getUniqueTime" {
 }
 
 declare module "socket-function/src/https" {
+    /// <reference types="node" />
     /// <reference types="node" />
     export interface HttpsResponseInfo {
         statusCode?: number;
@@ -1065,6 +1076,7 @@ declare module "socket-function/src/https" {
 }
 
 declare module "socket-function/src/lz4/LZ4" {
+    /// <reference types="node" />
     /// <reference types="node" />
     export declare class LZ4 {
         static compress(data: Buffer): Buffer;
@@ -1132,6 +1144,7 @@ declare module "socket-function/src/lz4/lz4_wasm_nodejs_bg.wasm" {
 }
 
 declare module "socket-function/src/misc" {
+    /// <reference types="node" />
     /// <reference types="node" />
     import { MaybePromise } from "socket-function/src/types";
     export declare const timeInSecond = 1000;
@@ -1563,6 +1576,7 @@ declare module "socket-function/src/storagePath" {
 }
 
 declare module "socket-function/src/tlsParsing" {
+    /// <reference types="node" />
     /// <reference types="node" />
     export declare function parseTLSHello(buffer: Buffer): {
         extensions: {
@@ -1592,6 +1606,7 @@ declare module "socket-function/src/upreal" {
 }
 
 declare module "socket-function/src/webSocketServer" {
+    /// <reference types="node" />
     /// <reference types="node" />
     /// <reference types="node" />
     import https from "https";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "socket-function",
-	"version": "1.2.36",
+	"version": "1.2.38",
 	"main": "index.js",
 	"license": "MIT",
 	"dependencies": {

package/require/RequireController.d.ts

@@ -1,5 +1,6 @@
 /// <reference path="../../typenode/index.d.ts" />
 /// <reference types="node" />
+/// <reference types="node" />
 declare global {
     namespace NodeJS {
         interface Module {

package/require/extMapper.d.ts

@@ -1,3 +1,4 @@
 /// <reference types="node" />
+/// <reference types="node" />
 export declare function getExtContentType(ext: string): string;
 export declare function getContentTypeFromBuffer(buffer: Buffer): string | undefined;

package/src/CallFactory.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="node" />
 /// <reference types="node" />
+/// <reference types="node" />
 import { CallType } from "../SocketFunctionTypes";
 import * as ws from "ws";
 import * as tls from "tls";

package/src/JSONLACKS/JSONLACKS.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 export interface JSONLACKS_ParseConfig {
     extended?: boolean;
     discardMissingReferences?: boolean;

package/src/Zip.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 import { MaybePromise } from "./types";
 export declare class Zip {
     static gzip(buffer: Buffer, level?: number): Promise<Buffer>;

package/src/bits.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 /** Subtracts the smallest possible value from a number (a double). This makes it possible to convert an exclusive range end
  *      to an inclusive range end, which is sometimes required (as in, < x is the same as <= minusEpsilon(x)).
  */

package/src/buffers.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 export type ArrayBufferViewTypes = Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | BigUint64Array | BigInt64Array | Float64Array | Float32Array | Uint8ClampedArray;
 export type BufferType = ArrayBuffer | SharedArrayBuffer | ArrayBufferViewTypes;
 export declare function cloneBuffer(data: Buffer): Buffer;

package/src/callHTTPHandler.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="node" />
 /// <reference types="node" />
+/// <reference types="node" />
 import http from "http";
 import { CallType } from "../SocketFunctionTypes";
 export declare function setDefaultHTTPCall(call: CallType): void;

package/src/certStore.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 /** Must be populated before the server starts */
 export declare function trustCertificate(cert: string | Buffer): void;
 export declare function getTrustedCertificates(): string[];

package/src/dnsCache.ts

@@ -158,19 +158,21 @@ export async function resolveHost(hostname: string, family = 0): Promise<DNSReco
 //  the socket use our cache instead of getaddrinfo. Always resolves via our cache; happy eyeballs
 //  (autoSelectFamily) then races the returned addresses.
 export const dnsCacheLookup: net.LookupFunction = function dnsCacheLookup(hostname, options, callback) {
-    let rawFamily = typeof options === "number" ? options : options.family ?? 0;
-    let family = rawFamily === "IPv4" ? 4 : rawFamily === "IPv6" ? 6 : rawFamily;
+    // Node's own callers pass the family as a number, but the option is documented as accepting "IPv4"/"IPv6"
+    //  too, so handle both even though the typings only admit the number.
+    let rawFamily: number | string = typeof options === "number" ? options : options.family ?? 0;
+    let family = rawFamily === "IPv4" ? 4 : rawFamily === "IPv6" ? 6 : Number(rawFamily) || 0;
     let all = typeof options === "object" && options.all;
     resolveHost(hostname, family).then(
         records => {
             if (all) {
-                callback(null, records.map(r => ({ address: r.address, family: r.family })));
+                callback(null, records.map(r => ({ address: r.address, family: r.family })), family);
             } else {
                 let record = records[0];
                 callback(null, record.address, record.family);
             }
         },
-        (err: NodeJS.ErrnoException) => callback(err, "", undefined)
+        (err: NodeJS.ErrnoException) => callback(err, "", family)
     );
 };
 

package/src/forwardPort.ts

@@ -89,10 +89,11 @@ export async function listPortMappings(): Promise<PortMapping[]> {
 //  live IGD; see test.ts.)
 const PERMANENT_LEASE = 0;
 
-// A permanent mapping never expires, so we don't renew. We only watch, on this interval, for
-//  another application having superseded our forward (or a router reboot having wiped it), and log
-//  loudly if so. We do NOT re-take it — last writer wins, so fighting back would just be a war.
-const SUPERSEDE_CHECK_INTERVAL = timeInMinute * 30;
+// A permanent mapping never expires, so we don't renew. We only watch, on this interval, for our
+//  forward having disappeared (routers do drop them, e.g. on reboot) or another application having
+//  taken it. A mapping that is simply gone is free, so we re-take it; one that someone else holds we
+//  leave alone and only log — fighting over it would just be a takeover war neither side wins.
+const MAPPING_CHECK_INTERVAL = timeInMinute * 30;
 
 /** Outcome of forwardPort. `owned` is true once we hold the router mapping for the port. When
  *      false, `reason` says why: "declined" = noPortStealing and another host holds the port (the
@@ -137,7 +138,9 @@ export async function forwardPort(config: {
         return (await listPortMappings()).find(m => m.externalPort === externalPort && m.protocol.toUpperCase() === "TCP");
     }
 
-    async function takeOwnership(): Promise<ForwardPortResult> {
+    // allowSteal is false for the periodic re-take, so a mapping that changed hands between our check
+    //  and this call is still left alone.
+    async function takeOwnership(options: { allowSteal: boolean }): Promise<ForwardPortResult> {
         try {
             const { internalIP, gatewayIP, controlPort, controlURLs } = await resolveGateway();
 
@@ -145,8 +148,8 @@ export async function forwardPort(config: {
             //  whether a mapping exists at all (so we only delete when there's something to delete).
             let existing = await readMapping();
 
-            if (existing && existing.internalClient !== internalIP && config.noPortStealing) {
-                console.log(`Port ${externalPort} is already forwarded to ${existing.internalClient} (not us); not stealing it (noPortStealing).`);
+            if (existing && existing.internalClient !== internalIP && !options.allowSteal) {
+                console.log(`Port ${externalPort} is already forwarded to ${existing.internalClient} (not us); not stealing it.`);
                 return { owned: false, reason: "declined" };
             }
 
@@ -195,32 +198,39 @@ export async function forwardPort(config: {
         return { owned: false, reason: "error" };
     }
 
-    // Re-read the mapping and warn if we no longer own it. Compares against our CURRENT LAN IP, so
-    //  this also catches the case where our own IP changed out from under the old mapping.
-    async function warnIfSuperseded() {
+    // Re-read the mapping and act on having lost it. Compares against our CURRENT LAN IP, so a mapping
+    //  left over from an IP change of ours reads as someone else's — which is the safe way around, as
+    //  we can't tell it apart from a genuine takeover and would rather not steal.
+    async function checkMapping() {
         try {
             let currentIP = await getLocalInternalIP();
-            let ours = (await listPortMappings()).find(m => m.externalPort === externalPort && m.protocol.toUpperCase() === "TCP");
-            if (!ours) {
-                console.error(`Port forward ${externalPort} is gone — the mapping was removed (router reboot, or another host deleted it).`);
-            } else if (currentIP && ours.internalClient !== currentIP) {
-                console.error(`Port forward ${externalPort} was superseded — it now forwards to ${ours.internalClient} instead of us (${currentIP}). Another application has taken the port.`);
+            let mapping = await readMapping();
+            if (!mapping) {
+                console.error(`Port forward ${externalPort} is gone — the mapping was removed (router reboot, or another host deleted it). Nothing holds the port, so re-taking it.`);
+                let retaken = await takeOwnership({ allowSteal: false });
+                if (!retaken.owned) {
+                    console.error(`Failed to re-take port forward ${externalPort} (${retaken.reason}).`);
+                }
+                return;
+            }
+            if (currentIP && mapping.internalClient !== currentIP) {
+                console.error(`Port forward ${externalPort} was taken — it now forwards to ${mapping.internalClient} instead of us (${currentIP}). Leaving it alone rather than fighting for it.`);
             }
         } catch (e) {
-            console.error(`Failed to check port forward ${externalPort} for supersession`, (e as Error).stack ?? e);
+            console.error(`Failed to check port forward ${externalPort}`, (e as Error).stack ?? e);
         }
     }
 
-    let result = await takeOwnership();
+    let result = await takeOwnership({ allowSteal: !config.noPortStealing });
 
     // Only monitor permanent mappings we actually own. A finite lease is expected to expire, so its
-    //  disappearance isn't a supersession worth warning about; a declined/failed claim owns nothing.
+    //  disappearance isn't a loss worth reporting or reclaiming; a declined/failed claim owns nothing.
     if (result.owned && permanent) {
         // unref so a script that only wants a one-off forward (and then exits) isn't held open by
         //  the monitor timer; a running server stays alive on its own and the checks keep firing.
         let timer = setInterval(() => {
-            void warnIfSuperseded();
-        }, SUPERSEDE_CHECK_INTERVAL);
+            void checkMapping();
+        }, MAPPING_CHECK_INTERVAL);
         timer.unref?.();
     }
 

package/src/https.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 export interface HttpsResponseInfo {
     statusCode?: number;
     statusMessage?: string;

package/src/lz4/LZ4.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 export declare class LZ4 {
     static compress(data: Buffer): Buffer;
     static compressUntracked(data: Buffer): Buffer;

package/src/misc.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 import { MaybePromise } from "./types";
 export declare const timeInSecond = 1000;
 export declare const timeInMinute: number;

package/src/tlsParsing.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 export declare function parseTLSHello(buffer: Buffer): {
     extensions: {
         type: number;

package/src/upreal.ts

@@ -11,17 +11,17 @@ const DEP_SECTIONS = [
     "peerDependencies",
 ] as const;
 
-// yarn can re-fetch a requesting package's real manifest (instead of trusting our rewritten lockfile entry),
-//  which re-introduces the old pinned range. Re-running the rewrite converges then, so allow a few passes.
-const MAX_DEDUPE_PASSES = 3;
-
-// Depth at which yarn.lock lists a block's dependencies. Block fields ("version", "resolved") sit shallower,
-//  so this is what keeps us from mistaking a field for a dependency entry.
-const LOCK_DEPENDENCY_INDENT = 4;
-
 // Yarn itself spells this "--dry-run", so accept that plus every spelling anyone reasonably reaches for.
 const DRY_RUN_FLAGS = ["--dry", "-dry", "--dryrun", "-dryrun", "--dry-run", "-dry-run", "--dry_run", "-dry_run"];
 
+// yarn install can still decide to re-resolve and re-split; re-running the merge converges in that case.
+const MAX_MERGE_PASSES = 3;
+
+// yarn v1 rewrites npm registry urls to its own mirror, so entries we synthesize have to match or yarn
+//  churns the lockfile back on the next install.
+const NPM_REGISTRY_HOST = "registry.npmjs.org";
+const YARN_REGISTRY_HOST = "registry.yarnpkg.com";
+
 async function main() {
     let args = process.argv.slice(2);
     let packageName = args.find(arg => !arg.startsWith("-"));
@@ -36,18 +36,20 @@ async function main() {
     let packageJsonPath = path.join(projectRoot, "package.json");
     let lockPath = path.join(projectRoot, "yarn.lock");
 
-    let latest = await getLatestVersion(packageName);
-    console.log(`Latest version of ${packageName}: ${latest}`);
+    let manifest = await getLatestManifest(packageName);
+    console.log(`Latest version of ${packageName}: ${manifest.version}`);
 
-    let newRange = updatePackageJson(packageJsonPath, packageName, latest);
-    console.log(`Forcing every reference to ${packageName} onto ${newRange}`);
+    let newRange = updatePackageJson(packageJsonPath, packageName, manifest.version);
 
-    for (let pass = 1; pass <= MAX_DEDUPE_PASSES; pass++) {
+    for (let pass = 1; pass <= MAX_MERGE_PASSES; pass++) {
         if (fs.existsSync(lockPath)) {
-            let result = forceLockRange(lockPath, packageName, newRange);
-            console.log(`Lockfile pass ${pass}: dropped ${result.removedBlocks} entr${result.removedBlocks === 1 ? "y" : "ies"} for ${packageName}, repointed ${result.rewrittenRequests} request${result.rewrittenRequests === 1 ? "" : "s"} for it to ${newRange}.`);
-            for (let skipped of result.skippedRequests) {
-                console.log(`Left ${skipped.requestedBy} asking for ${packageName}@${skipped.range} (not a registry range, so it can't be moved).`);
+            let result = mergeLockEntries(lockPath, packageName, manifest, newRange);
+            console.log(`Lockfile pass ${pass}: ${result.specs.length} spec${result.specs.length === 1 ? "" : "s"} for ${packageName} now share one entry at ${manifest.version}: ${result.specs.join(", ")}`);
+            for (let moved of result.movedFrom) {
+                console.log(`  ${moved.spec} was resolving to ${moved.version}`);
+            }
+            for (let left of result.leftAlone) {
+                console.log(`  left ${left} alone (not a registry range, so it can't point at a version)`);
             }
         }
 
@@ -61,19 +63,19 @@ async function main() {
 
         let versions = getLockedVersions(lockPath, packageName);
         if (versions.length <= 1) {
-            console.log(`Done. ${packageName} resolves to a single version: ${versions[0] ?? latest}`);
+            console.log(`Done. ${packageName} resolves to a single version: ${versions[0] ?? manifest.version}`);
             return;
         }
-        console.log(`${packageName} still resolves to ${versions.length} versions (${versions.join(", ")}); rewriting again.`);
+        console.log(`${packageName} still resolves to ${versions.length} versions (${versions.join(", ")}); merging again.`);
     }
 
     let versions = getLockedVersions(lockPath, packageName);
-    console.error(`Failed to collapse ${packageName} onto one version after ${MAX_DEDUPE_PASSES} passes; still at ${versions.join(", ")}`);
+    console.error(`Failed to collapse ${packageName} onto one version after ${MAX_MERGE_PASSES} passes; still at ${versions.join(", ")}`);
     process.exit(1);
 }
 
 // Point every package.json section that mentions the package at the latest version, keeping each section's
-//  existing range operator, and return the range we are forcing everything else onto.
+//  existing range operator, and return the range the lockfile entry has to satisfy.
 function updatePackageJson(packageJsonPath: string, packageName: string, latest: string): string {
     let raw = fs.readFileSync(packageJsonPath, "utf8");
     let packageJson = JSON.parse(raw) as {
@@ -99,28 +101,35 @@ function updatePackageJson(packageJsonPath: string, packageName: string, latest:
     }
 
     if (newRange === undefined) {
-        console.log(`${packageName} is not a direct dependency; only deduplicating transitive references.`);
+        console.log(`${packageName} is not a direct dependency; only merging the transitive references.`);
         return "^" + latest;
     }
     return newRange;
 }
 
-async function getLatestVersion(packageName: string): Promise<string> {
+interface Manifest {
+    version: string;
+    dist?: { tarball?: string; shasum?: string; integrity?: string };
+    dependencies?: { [name: string]: string };
+    optionalDependencies?: { [name: string]: string };
+}
+
+async function getLatestManifest(packageName: string): Promise<Manifest> {
     // Scoped names ("@scope/name") must have their slash encoded in the registry path.
     let encodedName = packageName.startsWith("@")
         ? "@" + encodeURIComponent(packageName.slice(1))
         : encodeURIComponent(packageName);
-    let url = `https://registry.npmjs.org/${encodedName}/latest`;
+    let url = `https://${NPM_REGISTRY_HOST}/${encodedName}/latest`;
 
     // Via httpsRequest so registry lookups go through the DNS cache (and its re-resolve/retry), rather
     //  than getaddrinfo, which caches certain failures forever.
     let body = (await httpsRequest(url)).toString("utf8");
 
-    let parsed = JSON.parse(body) as { version?: string };
+    let parsed = JSON.parse(body) as Manifest;
     if (!parsed.version) {
         throw new Error(`Registry response for ${packageName} had no version field`);
     }
-    return parsed.version;
+    return parsed;
 }
 
 // Keep whatever range operator the user already chose (^, ~, exact, or *) and point it at the new version.
@@ -167,14 +176,14 @@ function readLock(lockPath: string): LockFile {
     let blocks: LockBlock[] = [];
     let current: LockBlock | undefined;
     for (let i = 0; i < lines.length; i++) {
-        let line = lines[i];
-        if (isBlockHeader(line)) {
-            if (current) {
-                current.end = i;
-            }
-            current = { start: i, end: lines.length, specs: parseHeaderSpecs(line) };
-            blocks.push(current);
+        if (!isBlockHeader(lines[i])) {
+            continue;
         }
+        if (current) {
+            current.end = i;
+        }
+        current = { start: i, end: lines.length, specs: parseHeaderSpecs(lines[i]) };
+        blocks.push(current);
     }
     return { lines, eol, blocks };
 }
@@ -202,67 +211,143 @@ function specNamePackage(spec: string): string {
     return spec.slice(0, atIndex);
 }
 
+function specRange(spec: string): string {
+    return spec.slice(specNamePackage(spec).length + 1);
+}
+
 // Ranges that don't come from the registry (git urls, file:, link:, npm: aliases) can't be pointed at a
-//  version number, so they have to stay as they are.
+//  version number, so their entry has to stay separate.
 function isRegistryRange(range: string): boolean {
     return !range.includes(":") && !range.includes("/");
 }
 
-// Force the whole tree onto one version: drop every block for the package (so yarn re-resolves it), and
-//  repoint every *other* block's request for it at the new range, so nothing is left asking for an old
-//  pinned version that yarn would then have to resolve into a second entry.
-function forceLockRange(lockPath: string, packageName: string, newRange: string): {
-    removedBlocks: number;
-    rewrittenRequests: number;
-    skippedRequests: { requestedBy: string; range: string }[];
+// yarn.lock quotes a token only when it would otherwise be ambiguous, and rewriting a token with different
+//  quoting than yarn would use makes every later install churn the file.
+function quoteToken(value: string): string {
+    let needsQuotes = /[:\s\n\\",[\]]/.test(value) || !/^[a-zA-Z]/.test(value);
+    return needsQuotes ? `"${value}"` : value;
+}
+
+function formatHeader(specs: string[]): string {
+    return specs.map(quoteToken).join(", ") + ":";
+}
+
+// Put every registry spec for the package onto ONE entry resolving to the latest version. Nothing is deleted:
+//  a spec that asked for an old version (`pkg@1.2.3`) stays in the header and now points at the new version,
+//  which is what stops yarn from re-creating a second entry the next time something re-resolves.
+function mergeLockEntries(lockPath: string, packageName: string, manifest: Manifest, newRange: string): {
+    specs: string[];
+    movedFrom: { spec: string; version: string }[];
+    leftAlone: string[];
 } {
     let lock = readLock(lockPath);
+    let specs = new Set<string>([`${packageName}@${newRange}`]);
+    let movedFrom: { spec: string; version: string }[] = [];
+    let leftAlone: string[] = [];
     let removeLines = new Set<number>();
-    let removedBlocks = 0;
-    let rewrittenRequests = 0;
-    let skippedRequests: { requestedBy: string; range: string }[] = [];
+    let insertAt: number | undefined;
+    let body: string[] | undefined;
 
     for (let block of lock.blocks) {
-        if (block.specs.some(spec => specNamePackage(spec) === packageName)) {
-            removedBlocks++;
-            for (let i = block.start; i < block.end; i++) {
-                removeLines.add(i);
-            }
+        if (!block.specs.some(spec => specNamePackage(spec) === packageName)) {
+            continue;
+        }
+        let mergeable = block.specs.filter(spec => specNamePackage(spec) === packageName && isRegistryRange(specRange(spec)));
+        let keep = block.specs.filter(spec => !mergeable.includes(spec));
+        if (mergeable.length === 0) {
+            leftAlone.push(...block.specs);
             continue;
         }
 
-        for (let i = block.start + 1; i < block.end; i++) {
-            let parsed = parseDependencyLine(lock.lines[i]);
-            if (!parsed || parsed.name !== packageName) {
-                continue;
+        let version = getBlockVersion(lock, block);
+        for (let spec of mergeable) {
+            if (!specs.has(spec) && version !== manifest.version) {
+                movedFrom.push({ spec, version: version ?? "?" });
             }
-            if (!isRegistryRange(parsed.range)) {
-                skippedRequests.push({ requestedBy: block.specs[0], range: parsed.range });
-                continue;
-            }
-            if (parsed.range === newRange) {
-                continue;
-            }
-            lock.lines[i] = parsed.prefix + `"${newRange}"`;
-            rewrittenRequests++;
+            specs.add(spec);
+        }
+        // Reuse the real entry when the lockfile already holds the latest version, so we keep yarn's own
+        //  resolved url and integrity hash rather than synthesizing them.
+        if (version === manifest.version && !body) {
+            body = lock.lines.slice(block.start + 1, blockBodyEnd(lock, block));
         }
+        if (keep.length > 0) {
+            lock.lines[block.start] = formatHeader(keep);
+            leftAlone.push(...keep);
+            continue;
+        }
+        insertAt = insertAt ?? block.start;
+        for (let i = block.start; i < block.end; i++) {
+            removeLines.add(i);
+        }
+    }
+
+    let merged = [formatHeader(Array.from(specs).sort()), ...(body ?? synthesizeBody(manifest)), ""];
+
+    let output: string[] = [];
+    for (let i = 0; i < lock.lines.length; i++) {
+        if (i === insertAt) {
+            output.push(...merged);
+        }
+        if (removeLines.has(i)) {
+            continue;
+        }
+        output.push(lock.lines[i]);
+    }
+    if (insertAt === undefined) {
+        // The package wasn't in the lockfile at all; append and let yarn sort it.
+        output.push(...merged);
+    }
+
+    fs.writeFileSync(lockPath, output.join(lock.eol));
+    return { specs: Array.from(specs).sort(), movedFrom, leftAlone };
+}
+
+// The lines a block owns, excluding the blank line(s) separating it from the next block.
+function blockBodyEnd(lock: LockFile, block: LockBlock): number {
+    let end = block.end;
+    while (end > block.start + 1 && lock.lines[end - 1].trim() === "") {
+        end--;
     }
+    return end;
+}
 
-    let kept = lock.lines.filter((_, i) => !removeLines.has(i));
-    fs.writeFileSync(lockPath, kept.join(lock.eol));
-    return { removedBlocks, rewrittenRequests, skippedRequests };
+function getBlockVersion(lock: LockFile, block: LockBlock): string | undefined {
+    for (let i = block.start + 1; i < block.end; i++) {
+        let match = /^\s+version "(.*)"$/.exec(lock.lines[i]);
+        if (match) {
+            return match[1];
+        }
+    }
+    return undefined;
 }
 
-function parseDependencyLine(line: string): { prefix: string; name: string; range: string } | undefined {
-    let match = /^(\s+)("?)([^"\s]+)\2 "([^"]*)"$/.exec(line);
-    if (!match) {
-        return undefined;
+// Build a lockfile entry for a version the lockfile has never seen, from the registry's own metadata.
+function synthesizeBody(manifest: Manifest): string[] {
+    let tarball = manifest.dist?.tarball;
+    if (!tarball) {
+        throw new Error(`Registry response for ${manifest.version} had no dist.tarball, so no lockfile entry can be written`);
+    }
+    let resolved = tarball.replace(NPM_REGISTRY_HOST, YARN_REGISTRY_HOST);
+    if (manifest.dist?.shasum) {
+        resolved += "#" + manifest.dist.shasum;
+    }
+
+    let lines = [`  version ${quoteToken(manifest.version)}`, `  resolved ${quoteToken(resolved)}`];
+    if (manifest.dist?.integrity) {
+        lines.push(`  integrity ${quoteToken(manifest.dist.integrity)}`);
     }
-    let [, indent, quote, name, range] = match;
-    if (indent.length < LOCK_DEPENDENCY_INDENT) {
-        return undefined;
+    for (let section of ["dependencies", "optionalDependencies"] as const) {
+        let deps = manifest[section];
+        if (!deps || Object.keys(deps).length === 0) {
+            continue;
+        }
+        lines.push(`  ${section}:`);
+        for (let name of Object.keys(deps).sort()) {
+            lines.push(`    ${quoteToken(name)} ${quoteToken(deps[name])}`);
+        }
     }
-    return { prefix: `${indent}${quote}${name}${quote} `, name, range };
+    return lines;
 }
 
 function getLockedVersions(lockPath: string, packageName: string): string[] {
@@ -275,11 +360,9 @@ function getLockedVersions(lockPath: string, packageName: string): string[] {
         if (!block.specs.some(spec => specNamePackage(spec) === packageName)) {
             continue;
         }
-        for (let i = block.start + 1; i < block.end; i++) {
-            let match = /^\s+version "(.*)"$/.exec(lock.lines[i]);
-            if (match) {
-                versions.add(match[1]);
-            }
+        let version = getBlockVersion(lock, block);
+        if (version) {
+            versions.add(version);
         }
     }
     return Array.from(versions);

package/src/webSocketServer.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="node" />
 /// <reference types="node" />
+/// <reference types="node" />
 import https from "https";
 import { Watchable } from "./misc";
 export type SocketServerConfig = (https.ServerOptions & {