@photostructure/heap-trim 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!--
+Added for new features.
+Changed for changes in existing functionality.
+Deprecated for soon-to-be removed features.
+Removed for now removed features.
+Fixed for any bug fixes.
+Security in case of vulnerabilities.
+-->
+
+## [Unreleased]
+
+## [1.0.0] - 2026-11-07
+
+### Added
+
+- **`heapTrim()`** returns free heap memory to the operating system on glibc Linux by calling `malloc_trim(0)`. glibc's `free()` shrinks the heap only from its top, so pages freed below a live allocation otherwise stay resident. On musl, macOS, and Windows it does nothing and returns `false`, and the package builds and loads no native code there: macOS's `malloc_zone_pressure_relief()` and Windows' `_heapmin()` released no measurable memory in the same test.
+
+[1.0.0]: https://github.com/photostructure/heap-trim/releases/tag/v1.0.0

package/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Matthew McEachen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @photostructure/heap-trim
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Returns free C heap pages to the operating system from Node.js. Built for and supported by [PhotoStructure](https://photostructure.com).
+
+[![npm version](https://img.shields.io/npm/v/@photostructure/heap-trim.svg)](https://www.npmjs.com/package/@photostructure/heap-trim)
+[![Build](https://github.com/photostructure/heap-trim/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/photostructure/heap-trim/actions/workflows/build.yml)
+[![Node-API v9 Badge](https://raw.githubusercontent.com/nodejs/abi-stable-node/refs/heads/doc/assets/Node-API%20v9%20Badge.svg)](https://nodejs.org/dist/latest/docs/api/n-api.html#node-api-version-matrix)
+[![View on GitHub](https://img.shields.io/badge/View%20on-GitHub-blue)](https://github.com/photostructure/heap-trim)
+
+## Quick start
+
+```bash
+npm install @photostructure/heap-trim
+```
+
+```typescript
+import { heapTrim } from "@photostructure/heap-trim";
+
+// After a burst of native work has freed its memory, while the process is idle:
+heapTrim();
+```
+
+## `heapTrim(): boolean`
+
+glibc's `free()` shrinks the heap only from its top, so pages freed below a
+live allocation stay in the process's RSS. Native addons such as SQLite,
+image decoders, and `Buffer` backing stores allocate from that heap.
+`heapTrim()` calls glibc's `malloc_trim(0)`, which releases those free pages in
+every malloc arena.
+
+It locks each arena while it walks it, so call it when the process is idle,
+not after every request.
+
+**Returns:** `true` if glibc found whole free pages and told the kernel to drop
+them. That doesn't mean RSS fell: glibc doesn't check whether those pages were
+still resident, so repeated calls keep returning `true`. `false` if it found
+none, or the process doesn't use glibc.
+
+The function is on both the named and the default export, from CommonJS and
+ESM.
+
+## Supported platforms
+
+| Platform      | Architecture | Node.js | What `heapTrim()` does   |
+| ------------- | ------------ | ------- | ------------------------ |
+| Linux (glibc) | x64, arm64   | 22+     | Calls `malloc_trim(0)`   |
+| Linux (musl)  | x64, arm64   | 22+     | Nothing; returns `false` |
+| macOS         | x64, arm64   | 22+     | Nothing; returns `false` |
+| Windows       | x64, arm64   | 22+     | Nothing; returns `false` |
+
+The package ships a native addon only for glibc Linux, which requires GLIBC
+2.31+ (Debian 11+, Ubuntu 20.04+). On musl, macOS, and Windows it builds and
+loads no native code.
+
+musl has no trim call. On macOS and Windows the allocators have one, but in
+the test this package uses (128 MiB of 64 KiB `Buffer`s freed below a live
+one), neither released anything:
+
+- On macOS 27.2 (arm64), `malloc_zone_pressure_relief(NULL, 0)` returned 0
+  bytes, and the physical footprint stayed at 145 MB after the call.
+- On Windows 11 (x64), the heap had already decommitted the freed pages before
+  any call, and `_heapmin()` changed private bytes by 0.1 MB.
+
+## Documentation
+
+- [Security reporting](./SECURITY.md) - How to report security issues
+- [API Reference](https://photostructure.github.io/heap-trim/modules.html)
+- [Releasing](./doc/RELEASING.md) - How a release is built, staged, and approved
+
+## Development
+
+Development of this library was assisted by AI coding tools. All changes are human-reviewed and tested.

package/binding.gyp

@@ -0,0 +1,291 @@
+{
+  "variables": {
+    # Sanitizer builds (ASan/UBSan/TSan) must NOT enable _FORTIFY_SOURCE: its
+    # libc interceptors collide with the sanitizers' own, producing both false
+    # positives and false negatives. The OpenSSF Compiler Options Hardening
+    # Guide is explicit that FORTIFY should be off for instrumented builds.
+    #
+    # Sanitizer test runners export HEAP_TRIM_SANITIZE=1 so this flips to
+    # "on" for instrumented builds only.
+    # Relying on env CFLAGS ordering to override binding.gyp is fragile; this
+    # makes the intent explicit and deterministic.
+    #
+    # The value is deliberately "on"/"off" rather than 1/0: gyp coerces
+    # numeric-looking strings to ints, so a `heap_trim_sanitize=="0"` test would
+    # silently compare int 0 against str "0" and always be false -- which
+    # inverts the condition and ships _FORTIFY_SOURCE=0 in the release build.
+    "heap_trim_sanitize%": "<!(node -p \"process.env.HEAP_TRIM_SANITIZE ? 'on' : 'off'\")",
+
+    # Absolute path to node-addon-api's headers, for -isystem.
+    #
+    # node-addon-api is also in include_dirs (-I), but -Wformat=2 makes clang
+    # emit -Wformat-nonliteral inside napi-inl.h -- a third-party header we
+    # cannot fix. Passing the same directory with -isystem marks it a SYSTEM
+    # include, which suppresses its warnings while keeping the full warning set
+    # on our own code. (GCC/Clang: when a directory is given with both -I and
+    # -isystem, the -I is ignored and the directory is treated as a system one.)
+    #
+    # `.include_dir` is RELATIVE; the build runs from build/, so it must be
+    # resolved to an absolute path here.
+    "napi_include_dir": "<!(node -p \"require('path').resolve(require('node-addon-api').include_dir)\")"
+  },
+  "targets": [
+    {
+      "target_name": "heap_trim",
+      "sources": [
+        "src/binding.cpp"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")",
+        "src"
+      ],
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').gyp\")"
+      ],
+      "defines": [
+        "NAPI_CPP_EXCEPTIONS",
+        "NAPI_VERSION=9"
+      ],
+      "conditions": [
+        [
+          "OS=='linux'",
+          {
+            # OpenSSF Compiler Options Hardening Guide baseline.
+            #
+            # Every flag below was verified against the OLDEST toolchain we ship
+            # from -- Debian 11 Bullseye / GCC 10.2 (see prebuild-linux-glibc.sh)
+            # -- on both x64 and arm64, and against Alpine/musl (GCC 14).
+            #
+            # NOTE: gyp's `cflags` are passed to BOTH C and C++ compiles
+            # (GYP_CXXFLAGS = ... $(CFLAGS_$(BUILDTYPE)) $(CFLAGS_CC_$(BUILDTYPE))),
+            # so these must NOT be duplicated into cflags_cc.
+            "cflags": [
+              "-fPIC",
+              "-Wall",
+              "-Wextra",
+              # -Wformat=2 implies -Wformat. This pairing is REQUIRED:
+              # -Werror=format-security on its own hard-errors with
+              # "-Wformat-security ignored without -Wformat".
+              "-Wformat=2",
+              "-Werror=format-security",
+              "-fstack-protector-strong",
+              "-fstack-clash-protection",
+              "-fvisibility=hidden",
+              # Silence -Wformat-nonliteral from node-addon-api's napi-inl.h
+              # without weakening -Wformat=2 on our own code. See the
+              # napi_include_dir variable above.
+              "-isystem<(napi_include_dir)"
+            ],
+            "cflags_cc": [
+              # Pin the project standard instead of inheriting a Node-major-
+              # dependent value from common.gypi.
+              "-std=gnu++20",
+              "-fexceptions",
+              "-fvisibility-inlines-hidden",
+              # libstdc++ bounds/precondition assertions. Independent of FORTIFY;
+              # safe to leave on under sanitizers.
+              "-D_GLIBCXX_ASSERTIONS"
+            ],
+            # ELF/GNU-ld only. These are deliberately absent from the macOS
+            # branch: Apple's ld64 rejects -z outright ("ld: unknown options: -z").
+            # -Wl,-z,nodlopen must NEVER be added: Node dlopen()s this .node.
+            "ldflags": [
+              "-Wl,-z,relro",
+              "-Wl,-z,now",
+              "-Wl,-z,noexecstack"
+            ],
+            "conditions": [
+              [
+                "heap_trim_sanitize=='off'",
+                {
+                  # _FORTIFY_SOURCE requires -O1+ (Release gives -O3).
+                  #
+                  # Level 3 is deliberately NOT used: it needs GCC 12 +
+                  # glibc 2.34 for __builtin_dynamic_object_size. On our
+                  # GCC 10.2 / glibc 2.31 floor it silently degrades to level 2
+                  # (verified: __USE_FORTIFY_LEVEL=2), so =2 is the honest value.
+                  # Revisit if the glibc prebuild floor moves past Bullseye.
+                  #
+                  # -U first: many distros predefine _FORTIFY_SOURCE, which would
+                  # otherwise emit a macro-redefinition warning.
+                  "cflags": [
+                    "-U_FORTIFY_SOURCE",
+                    "-D_FORTIFY_SOURCE=2"
+                  ]
+                },
+                {
+                  # Sanitizer build: FORTIFY must be OFF.
+                  "cflags": [
+                    "-U_FORTIFY_SOURCE",
+                    "-D_FORTIFY_SOURCE=0"
+                  ]
+                }
+              ],
+              [
+                "target_arch=='x64'",
+                {
+                  # Intel CET. x86-only: hard-errors on aarch64
+                  # ("'-fcf-protection=full' is not supported for this target").
+                  "cflags": ["-fcf-protection=full"]
+                }
+              ],
+              [
+                "target_arch=='arm64'",
+                {
+                  # AArch64 PAC/BTI. arm64-only: unknown option on x86.
+                  "cflags": ["-mbranch-protection=standard"]
+                }
+              ]
+            ]
+          }
+        ],
+        [
+          "OS=='win'",
+          {
+            "defines": [
+              "WIN32",
+              "_WINDOWS"
+            ],
+            "msvs_settings": {
+              "VCCLCompilerTool": {
+                "WarningLevel": 4,
+                "AdditionalOptions": [
+                  "/std:c++20",   # Pin independently of Node's common.gypi
+                  "/guard:cf",     # Control Flow Guard (forward-edge CFI), all arches
+                  "/Qspectre",     # Spectre v1. NOT x64-only: MSVC supports ARM64
+                                   # since VS 2017 15.7 (Microsoft Learn /Qspectre).
+                  "/ZH:SHA_256",   # SHA-256 source hashing in the PDB
+                  "/sdl"           # SDL checks (superset of /GS)
+                ],
+                "ExceptionHandling": 1,
+                "RuntimeTypeInfo": "true"
+              },
+              "VCLinkerTool": {
+                "AdditionalOptions": [
+                  "/guard:cf",      # Must pair with the compiler /guard:cf, or we
+                                    # pay the cost with none of the protection.
+                  "/DYNAMICBASE",   # ASLR (default on)
+                  "/HIGHENTROPYVA", # 64-bit ASLR. NOT x64-only: applies to any
+                                    # 64-bit image incl. ARM64 (default on).
+                  "/NXCOMPAT"       # DEP (default on)
+                ]
+              }
+            },
+            "conditions": [
+              [
+                "target_arch=='x64'",
+                {
+                  "defines": [
+                    "_M_X64",
+                    "_WIN64"
+                  ],
+                  "msvs_settings": {
+                    "VCLinkerTool": {
+                      # CET shadow stack (backward-edge CFI). Genuinely x64-only:
+                      # ARM64 uses signed returns below instead.
+                      "AdditionalOptions": ["/CETCOMPAT"]
+                    }
+                  }
+                }
+              ],
+              [
+                "target_arch=='arm64'",
+                {
+                  # /guard:cf, /Qspectre, /sdl, /ZH:SHA_256, /DYNAMICBASE,
+                  # /HIGHENTROPYVA and /NXCOMPAT all apply here and are set above.
+                  "defines": [
+                    "_M_ARM64",
+                    "_WIN64"
+                  ],
+                  "msvs_settings": {
+                    "VCCLCompilerTool": {
+                      # ARM64 signed returns (PAC-based backward-edge CFI).
+                      # /CETCOMPAT is x64-only and intentionally absent here.
+                      "AdditionalOptions": ["/guard:signret"]
+                    }
+                  }
+                }
+              ]
+            ]
+          }
+        ],
+        [
+          "OS=='mac'",
+          {
+            # IMPORTANT: on macOS, gyp's make generator takes compile flags ONLY
+            # from xcode_settings -- target-level `cflags`/`cflags_cc` are
+            # ignored outright (see gyp/generator/make.py: `if flavor == "mac"`).
+            # Put every macOS flag in xcode_settings or it does nothing.
+            "xcode_settings": {
+              # Match the C++20 pinned above on Linux (-std=gnu++20) and
+              # Windows (/std:c++20). Kept STRICT
+              # (c++20, not gnu++20) on purpose: Linux is the permissive one, so
+              # a GNU extension that slips into the code fails here first.
+              #
+              # Verified against MACOSX_DEPLOYMENT_TARGET 10.15: libc++ marks a
+              # few C++20 library features unavailable on older deployment
+              # targets, but none that this addon uses.
+              "CLANG_CXX_LANGUAGE_STANDARD": "c++20",
+              "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+              "CLANG_CXX_LIBRARY": "libc++",
+              "MACOSX_DEPLOYMENT_TARGET": "10.15",
+              # == -fvisibility=hidden / -fvisibility-inlines-hidden
+              "GCC_SYMBOLS_PRIVATE_EXTERN": "YES",
+              "GCC_INLINES_ARE_PRIVATE_EXTERN": "YES",
+              "OTHER_CFLAGS": [
+                "-Wall",
+                "-Wextra",
+                # Same pairing requirement as Linux: -Werror=format-security
+                # alone hard-errors without -Wformat (supplied by -Wformat=2).
+                "-Wformat=2",
+                "-Werror=format-security",
+                "-fstack-protector-strong",
+                # Silence -Wformat-nonliteral from node-addon-api's napi-inl.h
+                # without weakening -Wformat=2 on our own code.
+                "-isystem<(napi_include_dir)"
+                # No -Wl,-z,* here: ld64 rejects them.
+                # No -fstack-clash-protection here: accepted by current Apple
+                # clang but NOT verified on the older clang shipped by the
+                # macos-14/macos-15 CI images, where it would hard-error.
+              ],
+              "OTHER_CPLUSPLUSFLAGS": [
+                # "$(inherited)" is LOAD-BEARING. gyp defaults
+                # OTHER_CPLUSPLUSFLAGS to ["$(inherited)"], which is what pulls
+                # OTHER_CFLAGS into C++ compiles. Setting this key without
+                # $(inherited) would silently drop every OTHER_CFLAGS hardening
+                # flag above from the C++ TUs -- i.e. all of our code.
+                "$(inherited)",
+                # libc++ bounds/precondition assertions (libc++ 18+). Verified
+                # effective on Apple clang (traps out-of-bounds access). A no-op
+                # on older libc++ that does not know the macro, never an error.
+                "-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_FAST"
+              ]
+            },
+            "conditions": [
+              [
+                "heap_trim_sanitize=='off'",
+                {
+                  "xcode_settings": {
+                    "OTHER_CFLAGS": [
+                      "-U_FORTIFY_SOURCE",
+                      "-D_FORTIFY_SOURCE=2"
+                    ]
+                  }
+                },
+                {
+                  # Sanitizer build: FORTIFY must be OFF (see top-of-file note).
+                  "xcode_settings": {
+                    "OTHER_CFLAGS": [
+                      "-U_FORTIFY_SOURCE",
+                      "-D_FORTIFY_SOURCE=0"
+                    ]
+                  }
+                }
+              ]
+            ]
+          }
+        ]
+      ]
+    }
+  ]
+}

package/dist/index.cjs

@@ -0,0 +1,115 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default,
+  heapTrim: () => heapTrim
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_gyp_build = __toESM(require("node-gyp-build"));
+var import_node_path2 = require("path");
+
+// src/stack-path.ts
+var import_node_path = require("path");
+function getCallerDirname() {
+  const e = new Error();
+  if (e.stack == null) {
+    Error.captureStackTrace(e);
+  }
+  return (0, import_node_path.dirname)(extractCallerPath(e.stack));
+}
+var patterns = process.platform === "win32" ? [
+  // File URLs: "at functionName (file:///C:/path/file.js:1:1)"
+  /\bat\s.+?\((?<path>file:\/\/\/.+?):\d+:\d+\)$/,
+  // File URLs direct: "at file:///C:/path/file.js:1:1"
+  /\bat\s(?<path>file:\/\/\/.+?):\d+:\d+$/,
+  // Standard: "at functionName (C:\path\file.js:1:1)"
+  /\bat\s.+?\((?<path>[A-Z]:\\.+):\d+:\d+\)$/,
+  // direct: "at C:\path\file.js:1:1"
+  /\bat\s(?<path>[A-Z]:\\.+):\d+:\d+$/,
+  // UNC: "at functionName (\\server\share\path\file.js:1:1)"
+  /\bat\s.+?\((?<path>\\\\.+):\d+:\d+\)$/,
+  // direct: "at \\server\share\path\file.js:1:1"
+  /\bat\s(?<path>\\\\.+):\d+:\d+$/
+] : [
+  // Standard: "at functionName (/path/file.js:1:1)"
+  /\bat\s.+?\((?<path>\/.+?):\d+:\d+\)$/,
+  // Anonymous or direct: "at /path/file.js:1:1"
+  // eslint-disable-next-line security/detect-unsafe-regex -- Pattern is safe: no nested quantifiers
+  /\bat\s(?:[^\s()]+\s)?(?<path>\/[^:]+):\d+:\d+$/
+];
+var MaybeUrlRE = /^[a-z]{2,5}:\/\//i;
+function extractCallerPath(stack) {
+  const frames = stack.split("\n").filter(Boolean);
+  const callerFrame = frames.findIndex(
+    (frame) => frame.includes("getCallerDirname")
+  );
+  if (callerFrame === -1) {
+    throw new Error("Invalid stack trace format: missing caller frame");
+  }
+  for (let i = callerFrame + 1; i < frames.length; i++) {
+    const frame = frames[i];
+    for (const pattern of patterns) {
+      const g = frame?.trim().match(pattern)?.groups;
+      if (g != null && g["path"]) {
+        const path = g["path"];
+        if (MaybeUrlRE.test(path)) {
+          try {
+            return new URL(path).pathname;
+          } catch {
+          }
+        }
+        return path;
+      }
+    }
+  }
+  throw new Error("Invalid stack trace format: no parsable frames");
+}
+
+// src/dirname.ts
+function _dirname() {
+  try {
+    if (typeof __dirname !== "undefined") return __dirname;
+  } catch {
+  }
+  return getCallerDirname();
+}
+
+// src/index.ts
+var isGlibc = process.report.getReport().header.glibcVersionRuntime != null;
+var binding = isGlibc ? (0, import_node_gyp_build.default)((0, import_node_path2.join)(_dirname(), "..")) : { heapTrim: () => false };
+var heapTrim = binding.heapTrim;
+var index_default = binding;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  heapTrim
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/stack-path.ts","../src/dirname.ts"],"sourcesContent":["import nodeGypBuild from \"node-gyp-build\";\nimport { join } from \"node:path\";\nimport { _dirname } from \"./dirname\";\n\n/** The functions the native addon exports. */\nexport interface HeapTrimModule {\n  /** @see {@link heapTrim} */\n  heapTrim(): boolean;\n}\n\n// The addon is built and loaded only on glibc, because only glibc's trim call\n// released memory. Each of these measurements allocated 128 MiB as Buffer\n// backing stores, kept only the last one, collected the rest, then trimmed:\n//\n// - macOS: malloc_zone_pressure_relief(nullptr, 0) returned 0 bytes. On m1\n//   (macOS 27.2, arm64, Node 24.22.1) with 64 KiB buffers, the physical\n//   footprint went from 14 MB to 144 MB, stayed at 145 MB after the frees\n//   (vmmap: 124 MB of \"Malloc Small (empty)\" regions), and stayed at 145 MB\n//   after the call. With 1, 4, 16, 32, 128, 256 and 1024 KiB buffers it also\n//   returned 0 and the footprint did not change.\n// - Windows: _heapmin() returned 0 (success), which does not say whether it\n//   released anything. On swift (Windows 11, x64, Node 24.21.0) with 64 KiB\n//   buffers, the heap had already decommitted the freed pages: private bytes\n//   went from 20 MB to 151 MB and fell to 23 MB after the frees, and the call\n//   changed them by 0.1 MB. With 1 KiB buffers, 84 MB of private bytes stayed\n//   committed after the frees, and the call left 84 MB.\n// - musl has no trim call.\nconst isGlibc =\n  (process.report.getReport() as { header: { glibcVersionRuntime?: string } })\n    .header.glibcVersionRuntime != null;\n\n// Use _dirname() helper that works in both CJS/ESM and Jest\nconst binding: HeapTrimModule = isGlibc\n  ? (nodeGypBuild(join(_dirname(), \"..\")) as HeapTrimModule)\n  : { heapTrim: () => false };\n\n/**\n * Returns free C heap memory to the operating system.\n *\n * glibc's `free()` shrinks the heap only from its top, so pages freed below a\n * live allocation stay in the process's RSS. On glibc Linux this calls\n * `malloc_trim(0)`, which releases those free pages in every malloc arena. On\n * musl, macOS, and Windows it does nothing: musl has no trim call, and\n * macOS's `malloc_zone_pressure_relief()` and Windows' `_heapmin()` released\n * no measurable memory in this package's test, so it doesn't call them.\n *\n * It locks each arena while it walks it, so call it when the process is idle,\n * not after every request.\n *\n * @returns `true` if glibc found whole free pages and told the kernel to drop\n * them. That doesn't mean RSS fell: glibc doesn't check whether those pages\n * were still resident, so repeated calls keep returning `true`. `false` if it\n * found none, or the process doesn't use glibc.\n *\n * @example\n * ```typescript\n * import { heapTrim } from \"@photostructure/heap-trim\";\n *\n * heapTrim();\n * ```\n */\nexport const heapTrim: () => boolean = binding.heapTrim;\n\n// Default export for CommonJS compatibility\nexport default binding;\n","import { dirname } from \"node:path\";\n\nexport function getCallerDirname(): string {\n  const e = new Error();\n  if (e.stack == null) {\n    Error.captureStackTrace(e);\n  }\n  return dirname(extractCallerPath(e.stack as string));\n}\n\n// Comprehensive regex patterns for different stack frame formats\nconst patterns =\n  process.platform === \"win32\"\n    ? [\n        // File URLs: \"at functionName (file:///C:/path/file.js:1:1)\"\n        /\\bat\\s.+?\\((?<path>file:\\/\\/\\/.+?):\\d+:\\d+\\)$/,\n        // File URLs direct: \"at file:///C:/path/file.js:1:1\"\n        /\\bat\\s(?<path>file:\\/\\/\\/.+?):\\d+:\\d+$/,\n        // Standard: \"at functionName (C:\\path\\file.js:1:1)\"\n        /\\bat\\s.+?\\((?<path>[A-Z]:\\\\.+):\\d+:\\d+\\)$/,\n        // direct: \"at C:\\path\\file.js:1:1\"\n        /\\bat\\s(?<path>[A-Z]:\\\\.+):\\d+:\\d+$/,\n        // UNC: \"at functionName (\\\\server\\share\\path\\file.js:1:1)\"\n        /\\bat\\s.+?\\((?<path>\\\\\\\\.+):\\d+:\\d+\\)$/,\n        // direct: \"at \\\\server\\share\\path\\file.js:1:1\"\n        /\\bat\\s(?<path>\\\\\\\\.+):\\d+:\\d+$/,\n      ]\n    : [\n        // Standard: \"at functionName (/path/file.js:1:1)\"\n        /\\bat\\s.+?\\((?<path>\\/.+?):\\d+:\\d+\\)$/,\n        // Anonymous or direct: \"at /path/file.js:1:1\"\n        // eslint-disable-next-line security/detect-unsafe-regex -- Pattern is safe: no nested quantifiers\n        /\\bat\\s(?:[^\\s()]+\\s)?(?<path>\\/[^:]+):\\d+:\\d+$/,\n      ];\n\nconst MaybeUrlRE = /^[a-z]{2,5}:\\/\\//i;\n\n// only exposed for tests:\nexport function extractCallerPath(stack: string): string {\n  const frames = stack.split(\"\\n\").filter(Boolean);\n\n  // First find getCallerDirname() in the stack:\n  const callerFrame = frames.findIndex((frame) =>\n    frame.includes(\"getCallerDirname\"),\n  );\n  if (callerFrame === -1) {\n    throw new Error(\"Invalid stack trace format: missing caller frame\");\n  }\n  for (let i = callerFrame + 1; i < frames.length; i++) {\n    const frame = frames[i];\n    for (const pattern of patterns) {\n      const g = frame?.trim().match(pattern)?.groups;\n      if (g != null && g[\"path\"]) {\n        const path = g[\"path\"];\n        // Windows requires us to check if it's a reasonable URL, as URL accepts\n        // \"C:\\\\path\\\\file.txt\" as valid (!!)\n        if (MaybeUrlRE.test(path)) {\n          try {\n            return new URL(path).pathname;\n          } catch {\n            // ignore\n          }\n        }\n        return path;\n      }\n    }\n  }\n  throw new Error(\"Invalid stack trace format: no parsable frames\");\n}\n","import { getCallerDirname } from \"./stack-path\";\n\n// Thanks to tsup shims, __dirname should always be defined except when run by\n// jest (which will use the stack_path shim)\nexport function _dirname() {\n  try {\n    if (typeof __dirname !== \"undefined\") return __dirname;\n  } catch {\n    // ignore\n  }\n  // we must be in jest. Use the stack_path ~~hack~~ shim:\n  return getCallerDirname();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,4BAAyB;AACzB,IAAAA,oBAAqB;;;ACDrB,uBAAwB;AAEjB,SAAS,mBAA2B;AACzC,QAAM,IAAI,IAAI,MAAM;AACpB,MAAI,EAAE,SAAS,MAAM;AACnB,UAAM,kBAAkB,CAAC;AAAA,EAC3B;AACA,aAAO,0BAAQ,kBAAkB,EAAE,KAAe,CAAC;AACrD;AAGA,IAAM,WACJ,QAAQ,aAAa,UACjB;AAAA;AAAA,EAEE;AAAA;AAAA,EAEA;AAAA;AAAA,EAEA;AAAA;AAAA,EAEA;AAAA;AAAA,EAEA;AAAA;AAAA,EAEA;AACF,IACA;AAAA;AAAA,EAEE;AAAA;AAAA;AAAA,EAGA;AACF;AAEN,IAAM,aAAa;AAGZ,SAAS,kBAAkB,OAAuB;AACvD,QAAM,SAAS,MAAM,MAAM,IAAI,EAAE,OAAO,OAAO;AAG/C,QAAM,cAAc,OAAO;AAAA,IAAU,CAAC,UACpC,MAAM,SAAS,kBAAkB;AAAA,EACnC;AACA,MAAI,gBAAgB,IAAI;AACtB,UAAM,IAAI,MAAM,kDAAkD;AAAA,EACpE;AACA,WAAS,IAAI,cAAc,GAAG,IAAI,OAAO,QAAQ,KAAK;AACpD,UAAM,QAAQ,OAAO,CAAC;AACtB,eAAW,WAAW,UAAU;AAC9B,YAAM,IAAI,OAAO,KAAK,EAAE,MAAM,OAAO,GAAG;AACxC,UAAI,KAAK,QAAQ,EAAE,MAAM,GAAG;AAC1B,cAAM,OAAO,EAAE,MAAM;AAGrB,YAAI,WAAW,KAAK,IAAI,GAAG;AACzB,cAAI;AACF,mBAAO,IAAI,IAAI,IAAI,EAAE;AAAA,UACvB,QAAQ;AAAA,UAER;AAAA,QACF;AACA,eAAO;AAAA,MACT;AAAA,IACF;AAAA,EACF;AACA,QAAM,IAAI,MAAM,gDAAgD;AAClE;;;AChEO,SAAS,WAAW;AACzB,MAAI;AACF,QAAI,OAAO,cAAc,YAAa,QAAO;AAAA,EAC/C,QAAQ;AAAA,EAER;AAEA,SAAO,iBAAiB;AAC1B;;;AFeA,IAAM,UACH,QAAQ,OAAO,UAAU,EACvB,OAAO,uBAAuB;AAGnC,IAAM,UAA0B,cAC3B,sBAAAC,aAAa,wBAAK,SAAS,GAAG,IAAI,CAAC,IACpC,EAAE,UAAU,MAAM,MAAM;AA2BrB,IAAM,WAA0B,QAAQ;AAG/C,IAAO,gBAAQ;","names":["import_node_path","nodeGypBuild"]}

package/dist/index.d.cts

@@ -0,0 +1,35 @@
+/** The functions the native addon exports. */
+interface HeapTrimModule {
+    /** @see {@link heapTrim} */
+    heapTrim(): boolean;
+}
+declare const binding: HeapTrimModule;
+/**
+ * Returns free C heap memory to the operating system.
+ *
+ * glibc's `free()` shrinks the heap only from its top, so pages freed below a
+ * live allocation stay in the process's RSS. On glibc Linux this calls
+ * `malloc_trim(0)`, which releases those free pages in every malloc arena. On
+ * musl, macOS, and Windows it does nothing: musl has no trim call, and
+ * macOS's `malloc_zone_pressure_relief()` and Windows' `_heapmin()` released
+ * no measurable memory in this package's test, so it doesn't call them.
+ *
+ * It locks each arena while it walks it, so call it when the process is idle,
+ * not after every request.
+ *
+ * @returns `true` if glibc found whole free pages and told the kernel to drop
+ * them. That doesn't mean RSS fell: glibc doesn't check whether those pages
+ * were still resident, so repeated calls keep returning `true`. `false` if it
+ * found none, or the process doesn't use glibc.
+ *
+ * @example
+ * ```typescript
+ * import { heapTrim } from "@photostructure/heap-trim";
+ *
+ * heapTrim();
+ * ```
+ */
+declare const heapTrim: () => boolean;
+
+export { binding as default, heapTrim };
+export type { HeapTrimModule };

package/dist/index.d.mts

@@ -0,0 +1,35 @@
+/** The functions the native addon exports. */
+interface HeapTrimModule {
+    /** @see {@link heapTrim} */
+    heapTrim(): boolean;
+}
+declare const binding: HeapTrimModule;
+/**
+ * Returns free C heap memory to the operating system.
+ *
+ * glibc's `free()` shrinks the heap only from its top, so pages freed below a
+ * live allocation stay in the process's RSS. On glibc Linux this calls
+ * `malloc_trim(0)`, which releases those free pages in every malloc arena. On
+ * musl, macOS, and Windows it does nothing: musl has no trim call, and
+ * macOS's `malloc_zone_pressure_relief()` and Windows' `_heapmin()` released
+ * no measurable memory in this package's test, so it doesn't call them.
+ *
+ * It locks each arena while it walks it, so call it when the process is idle,
+ * not after every request.
+ *
+ * @returns `true` if glibc found whole free pages and told the kernel to drop
+ * them. That doesn't mean RSS fell: glibc doesn't check whether those pages
+ * were still resident, so repeated calls keep returning `true`. `false` if it
+ * found none, or the process doesn't use glibc.
+ *
+ * @example
+ * ```typescript
+ * import { heapTrim } from "@photostructure/heap-trim";
+ *
+ * heapTrim();
+ * ```
+ */
+declare const heapTrim: () => boolean;
+
+export { binding as default, heapTrim };
+export type { HeapTrimModule };

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/** The functions the native addon exports. */
+interface HeapTrimModule {
+    /** @see {@link heapTrim} */
+    heapTrim(): boolean;
+}
+declare const binding: HeapTrimModule;
+/**
+ * Returns free C heap memory to the operating system.
+ *
+ * glibc's `free()` shrinks the heap only from its top, so pages freed below a
+ * live allocation stay in the process's RSS. On glibc Linux this calls
+ * `malloc_trim(0)`, which releases those free pages in every malloc arena. On
+ * musl, macOS, and Windows it does nothing: musl has no trim call, and
+ * macOS's `malloc_zone_pressure_relief()` and Windows' `_heapmin()` released
+ * no measurable memory in this package's test, so it doesn't call them.
+ *
+ * It locks each arena while it walks it, so call it when the process is idle,
+ * not after every request.
+ *
+ * @returns `true` if glibc found whole free pages and told the kernel to drop
+ * them. That doesn't mean RSS fell: glibc doesn't check whether those pages
+ * were still resident, so repeated calls keep returning `true`. `false` if it
+ * found none, or the process doesn't use glibc.
+ *
+ * @example
+ * ```typescript
+ * import { heapTrim } from "@photostructure/heap-trim";
+ *
+ * heapTrim();
+ * ```
+ */
+declare const heapTrim: () => boolean;
+
+export { binding as default, heapTrim };
+export type { HeapTrimModule };

package/dist/index.mjs

@@ -0,0 +1,87 @@
+// node_modules/tsup/assets/esm_shims.js
+import path from "path";
+import { fileURLToPath } from "url";
+var getFilename = () => fileURLToPath(import.meta.url);
+var getDirname = () => path.dirname(getFilename());
+var __dirname = /* @__PURE__ */ getDirname();
+
+// src/index.ts
+import nodeGypBuild from "node-gyp-build";
+import { join } from "path";
+
+// src/stack-path.ts
+import { dirname } from "path";
+function getCallerDirname() {
+  const e = new Error();
+  if (e.stack == null) {
+    Error.captureStackTrace(e);
+  }
+  return dirname(extractCallerPath(e.stack));
+}
+var patterns = process.platform === "win32" ? [
+  // File URLs: "at functionName (file:///C:/path/file.js:1:1)"
+  /\bat\s.+?\((?<path>file:\/\/\/.+?):\d+:\d+\)$/,
+  // File URLs direct: "at file:///C:/path/file.js:1:1"
+  /\bat\s(?<path>file:\/\/\/.+?):\d+:\d+$/,
+  // Standard: "at functionName (C:\path\file.js:1:1)"
+  /\bat\s.+?\((?<path>[A-Z]:\\.+):\d+:\d+\)$/,
+  // direct: "at C:\path\file.js:1:1"
+  /\bat\s(?<path>[A-Z]:\\.+):\d+:\d+$/,
+  // UNC: "at functionName (\\server\share\path\file.js:1:1)"
+  /\bat\s.+?\((?<path>\\\\.+):\d+:\d+\)$/,
+  // direct: "at \\server\share\path\file.js:1:1"
+  /\bat\s(?<path>\\\\.+):\d+:\d+$/
+] : [
+  // Standard: "at functionName (/path/file.js:1:1)"
+  /\bat\s.+?\((?<path>\/.+?):\d+:\d+\)$/,
+  // Anonymous or direct: "at /path/file.js:1:1"
+  // eslint-disable-next-line security/detect-unsafe-regex -- Pattern is safe: no nested quantifiers
+  /\bat\s(?:[^\s()]+\s)?(?<path>\/[^:]+):\d+:\d+$/
+];
+var MaybeUrlRE = /^[a-z]{2,5}:\/\//i;
+function extractCallerPath(stack) {
+  const frames = stack.split("\n").filter(Boolean);
+  const callerFrame = frames.findIndex(
+    (frame) => frame.includes("getCallerDirname")
+  );
+  if (callerFrame === -1) {
+    throw new Error("Invalid stack trace format: missing caller frame");
+  }
+  for (let i = callerFrame + 1; i < frames.length; i++) {
+    const frame = frames[i];
+    for (const pattern of patterns) {
+      const g = frame?.trim().match(pattern)?.groups;
+      if (g != null && g["path"]) {
+        const path2 = g["path"];
+        if (MaybeUrlRE.test(path2)) {
+          try {
+            return new URL(path2).pathname;
+          } catch {
+          }
+        }
+        return path2;
+      }
+    }
+  }
+  throw new Error("Invalid stack trace format: no parsable frames");
+}
+
+// src/dirname.ts
+function _dirname() {
+  try {
+    if (typeof __dirname !== "undefined") return __dirname;
+  } catch {
+  }
+  return getCallerDirname();
+}
+
+// src/index.ts
+var isGlibc = process.report.getReport().header.glibcVersionRuntime != null;
+var binding = isGlibc ? nodeGypBuild(join(_dirname(), "..")) : { heapTrim: () => false };
+var heapTrim = binding.heapTrim;
+var index_default = binding;
+export {
+  index_default as default,
+  heapTrim
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../node_modules/tsup/assets/esm_shims.js","../src/index.ts","../src/stack-path.ts","../src/dirname.ts"],"sourcesContent":["// Shim globals in esm bundle\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\nconst getFilename = () => fileURLToPath(import.meta.url)\nconst getDirname = () => path.dirname(getFilename())\n\nexport const __dirname = /* @__PURE__ */ getDirname()\nexport const __filename = /* @__PURE__ */ getFilename()\n","import nodeGypBuild from \"node-gyp-build\";\nimport { join } from \"node:path\";\nimport { _dirname } from \"./dirname\";\n\n/** The functions the native addon exports. */\nexport interface HeapTrimModule {\n  /** @see {@link heapTrim} */\n  heapTrim(): boolean;\n}\n\n// The addon is built and loaded only on glibc, because only glibc's trim call\n// released memory. Each of these measurements allocated 128 MiB as Buffer\n// backing stores, kept only the last one, collected the rest, then trimmed:\n//\n// - macOS: malloc_zone_pressure_relief(nullptr, 0) returned 0 bytes. On m1\n//   (macOS 27.2, arm64, Node 24.22.1) with 64 KiB buffers, the physical\n//   footprint went from 14 MB to 144 MB, stayed at 145 MB after the frees\n//   (vmmap: 124 MB of \"Malloc Small (empty)\" regions), and stayed at 145 MB\n//   after the call. With 1, 4, 16, 32, 128, 256 and 1024 KiB buffers it also\n//   returned 0 and the footprint did not change.\n// - Windows: _heapmin() returned 0 (success), which does not say whether it\n//   released anything. On swift (Windows 11, x64, Node 24.21.0) with 64 KiB\n//   buffers, the heap had already decommitted the freed pages: private bytes\n//   went from 20 MB to 151 MB and fell to 23 MB after the frees, and the call\n//   changed them by 0.1 MB. With 1 KiB buffers, 84 MB of private bytes stayed\n//   committed after the frees, and the call left 84 MB.\n// - musl has no trim call.\nconst isGlibc =\n  (process.report.getReport() as { header: { glibcVersionRuntime?: string } })\n    .header.glibcVersionRuntime != null;\n\n// Use _dirname() helper that works in both CJS/ESM and Jest\nconst binding: HeapTrimModule = isGlibc\n  ? (nodeGypBuild(join(_dirname(), \"..\")) as HeapTrimModule)\n  : { heapTrim: () => false };\n\n/**\n * Returns free C heap memory to the operating system.\n *\n * glibc's `free()` shrinks the heap only from its top, so pages freed below a\n * live allocation stay in the process's RSS. On glibc Linux this calls\n * `malloc_trim(0)`, which releases those free pages in every malloc arena. On\n * musl, macOS, and Windows it does nothing: musl has no trim call, and\n * macOS's `malloc_zone_pressure_relief()` and Windows' `_heapmin()` released\n * no measurable memory in this package's test, so it doesn't call them.\n *\n * It locks each arena while it walks it, so call it when the process is idle,\n * not after every request.\n *\n * @returns `true` if glibc found whole free pages and told the kernel to drop\n * them. That doesn't mean RSS fell: glibc doesn't check whether those pages\n * were still resident, so repeated calls keep returning `true`. `false` if it\n * found none, or the process doesn't use glibc.\n *\n * @example\n * ```typescript\n * import { heapTrim } from \"@photostructure/heap-trim\";\n *\n * heapTrim();\n * ```\n */\nexport const heapTrim: () => boolean = binding.heapTrim;\n\n// Default export for CommonJS compatibility\nexport default binding;\n","import { dirname } from \"node:path\";\n\nexport function getCallerDirname(): string {\n  const e = new Error();\n  if (e.stack == null) {\n    Error.captureStackTrace(e);\n  }\n  return dirname(extractCallerPath(e.stack as string));\n}\n\n// Comprehensive regex patterns for different stack frame formats\nconst patterns =\n  process.platform === \"win32\"\n    ? [\n        // File URLs: \"at functionName (file:///C:/path/file.js:1:1)\"\n        /\\bat\\s.+?\\((?<path>file:\\/\\/\\/.+?):\\d+:\\d+\\)$/,\n        // File URLs direct: \"at file:///C:/path/file.js:1:1\"\n        /\\bat\\s(?<path>file:\\/\\/\\/.+?):\\d+:\\d+$/,\n        // Standard: \"at functionName (C:\\path\\file.js:1:1)\"\n        /\\bat\\s.+?\\((?<path>[A-Z]:\\\\.+):\\d+:\\d+\\)$/,\n        // direct: \"at C:\\path\\file.js:1:1\"\n        /\\bat\\s(?<path>[A-Z]:\\\\.+):\\d+:\\d+$/,\n        // UNC: \"at functionName (\\\\server\\share\\path\\file.js:1:1)\"\n        /\\bat\\s.+?\\((?<path>\\\\\\\\.+):\\d+:\\d+\\)$/,\n        // direct: \"at \\\\server\\share\\path\\file.js:1:1\"\n        /\\bat\\s(?<path>\\\\\\\\.+):\\d+:\\d+$/,\n      ]\n    : [\n        // Standard: \"at functionName (/path/file.js:1:1)\"\n        /\\bat\\s.+?\\((?<path>\\/.+?):\\d+:\\d+\\)$/,\n        // Anonymous or direct: \"at /path/file.js:1:1\"\n        // eslint-disable-next-line security/detect-unsafe-regex -- Pattern is safe: no nested quantifiers\n        /\\bat\\s(?:[^\\s()]+\\s)?(?<path>\\/[^:]+):\\d+:\\d+$/,\n      ];\n\nconst MaybeUrlRE = /^[a-z]{2,5}:\\/\\//i;\n\n// only exposed for tests:\nexport function extractCallerPath(stack: string): string {\n  const frames = stack.split(\"\\n\").filter(Boolean);\n\n  // First find getCallerDirname() in the stack:\n  const callerFrame = frames.findIndex((frame) =>\n    frame.includes(\"getCallerDirname\"),\n  );\n  if (callerFrame === -1) {\n    throw new Error(\"Invalid stack trace format: missing caller frame\");\n  }\n  for (let i = callerFrame + 1; i < frames.length; i++) {\n    const frame = frames[i];\n    for (const pattern of patterns) {\n      const g = frame?.trim().match(pattern)?.groups;\n      if (g != null && g[\"path\"]) {\n        const path = g[\"path\"];\n        // Windows requires us to check if it's a reasonable URL, as URL accepts\n        // \"C:\\\\path\\\\file.txt\" as valid (!!)\n        if (MaybeUrlRE.test(path)) {\n          try {\n            return new URL(path).pathname;\n          } catch {\n            // ignore\n          }\n        }\n        return path;\n      }\n    }\n  }\n  throw new Error(\"Invalid stack trace format: no parsable frames\");\n}\n","import { getCallerDirname } from \"./stack-path\";\n\n// Thanks to tsup shims, __dirname should always be defined except when run by\n// jest (which will use the stack_path shim)\nexport function _dirname() {\n  try {\n    if (typeof __dirname !== \"undefined\") return __dirname;\n  } catch {\n    // ignore\n  }\n  // we must be in jest. Use the stack_path ~~hack~~ shim:\n  return getCallerDirname();\n}\n"],"mappings":";AACA,OAAO,UAAU;AACjB,SAAS,qBAAqB;AAE9B,IAAM,cAAc,MAAM,cAAc,YAAY,GAAG;AACvD,IAAM,aAAa,MAAM,KAAK,QAAQ,YAAY,CAAC;AAE5C,IAAM,YAA4B,2BAAW;;;ACPpD,OAAO,kBAAkB;AACzB,SAAS,YAAY;;;ACDrB,SAAS,eAAe;AAEjB,SAAS,mBAA2B;AACzC,QAAM,IAAI,IAAI,MAAM;AACpB,MAAI,EAAE,SAAS,MAAM;AACnB,UAAM,kBAAkB,CAAC;AAAA,EAC3B;AACA,SAAO,QAAQ,kBAAkB,EAAE,KAAe,CAAC;AACrD;AAGA,IAAM,WACJ,QAAQ,aAAa,UACjB;AAAA;AAAA,EAEE;AAAA;AAAA,EAEA;AAAA;AAAA,EAEA;AAAA;AAAA,EAEA;AAAA;AAAA,EAEA;AAAA;AAAA,EAEA;AACF,IACA;AAAA;AAAA,EAEE;AAAA;AAAA;AAAA,EAGA;AACF;AAEN,IAAM,aAAa;AAGZ,SAAS,kBAAkB,OAAuB;AACvD,QAAM,SAAS,MAAM,MAAM,IAAI,EAAE,OAAO,OAAO;AAG/C,QAAM,cAAc,OAAO;AAAA,IAAU,CAAC,UACpC,MAAM,SAAS,kBAAkB;AAAA,EACnC;AACA,MAAI,gBAAgB,IAAI;AACtB,UAAM,IAAI,MAAM,kDAAkD;AAAA,EACpE;AACA,WAAS,IAAI,cAAc,GAAG,IAAI,OAAO,QAAQ,KAAK;AACpD,UAAM,QAAQ,OAAO,CAAC;AACtB,eAAW,WAAW,UAAU;AAC9B,YAAM,IAAI,OAAO,KAAK,EAAE,MAAM,OAAO,GAAG;AACxC,UAAI,KAAK,QAAQ,EAAE,MAAM,GAAG;AAC1B,cAAMA,QAAO,EAAE,MAAM;AAGrB,YAAI,WAAW,KAAKA,KAAI,GAAG;AACzB,cAAI;AACF,mBAAO,IAAI,IAAIA,KAAI,EAAE;AAAA,UACvB,QAAQ;AAAA,UAER;AAAA,QACF;AACA,eAAOA;AAAA,MACT;AAAA,IACF;AAAA,EACF;AACA,QAAM,IAAI,MAAM,gDAAgD;AAClE;;;AChEO,SAAS,WAAW;AACzB,MAAI;AACF,QAAI,OAAO,cAAc,YAAa,QAAO;AAAA,EAC/C,QAAQ;AAAA,EAER;AAEA,SAAO,iBAAiB;AAC1B;;;AFeA,IAAM,UACH,QAAQ,OAAO,UAAU,EACvB,OAAO,uBAAuB;AAGnC,IAAM,UAA0B,UAC3B,aAAa,KAAK,SAAS,GAAG,IAAI,CAAC,IACpC,EAAE,UAAU,MAAM,MAAM;AA2BrB,IAAM,WAA0B,QAAQ;AAG/C,IAAO,gBAAQ;","names":["path"]}

package/package.json

@@ -1,6 +1,141 @@
 {
   "name": "@photostructure/heap-trim",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Return free C heap pages to the operating system from Node.js",
+  "homepage": "https://photostructure.github.io/heap-trim/",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE.txt",
+    "README.md",
+    "binding.gyp",
+    "dist/",
+    "prebuilds/",
+    "scripts/install.cjs",
+    "src/**/*.cpp",
+    "src/**/*.h",
+    "!src/test-utils/**"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/photostructure/heap-trim.git"
+  },
+  "license": "MIT",
+  "scripts": {
+    "install": "node scripts/install.cjs",
+    "clean": "run-p clean:*",
+    "clean:dist": "del-cli coverage dist docs \"*.tsbuildinfo\"",
+    "clean:gyp-cache": "del-cli --force build %USERPROFILE%/.node-gyp ~/.node-gyp",
+    "clean:native": "node-gyp clean",
+    "node-gyp-rebuild": "node-gyp rebuild",
+    "build": "run-s build:native build:dist",
+    "build:native": "tsx scripts/prebuildify-wrapper.ts",
+    "build:linux-glibc": "bash scripts/prebuild-linux-glibc.sh",
+    "build:dist": "tsup && node scripts/post-build.mjs",
+    "docs": "typedoc",
+    "// test": "support `npm t name_of_file` (and don't fail due to missing coverage)",
+    "test": "npm run test:cjs -- --no-coverage",
+    "tests": "run-s test:*",
+    "test:cjs": "cross-env TEST_ESM=0 jest",
+    "test:esm": "cross-env TEST_ESM=1 node --experimental-vm-modules --no-warnings node_modules/jest/bin/jest.js",
+    "check:memory": "tsx scripts/check-memory.ts",
+    "lint": "run-s lint:*",
+    "lint:native": "tsx scripts/clang-tidy.ts",
+    "lint:tsc": "tsc --noEmit",
+    "lint:eslint": "eslint",
+    "// check:exports": "verify package.json exports + type declarations resolve correctly (arethetypeswrong). Requires `npm run build:dist` first.",
+    "check:exports": "attw --pack .",
+    "fmt": "run-p fmt:*",
+    "// fmt:cpp": "on ubuntu: `sudo apt install clang-format`. Note that windows emits `invalid format` with this || true approach, but it works and is better than introducing Yet Another Script Script (like scripts/clang-format.mjs).",
+    "fmt:cpp": "clang-format --style=LLVM -i src/*.cpp || echo \"problem with clang-format\"",
+    "fmt:js": "prettier --write \"**/*.{cjs,mjs,js}\"",
+    "fmt:ts": "prettier --write \"**/*.{cts,mts,ts}\"",
+    "fmt:md": "prettier --write \"**/*.md\"",
+    "fmt:json": "prettier --write \"**/*.json\"",
+    "fmt:yml": "prettier --write \"**/*.{yaml,yml}\"",
+    "fmt:pkg": "npm pkg fix",
+    "update": "run-p update:*",
+    "update:deps": "ncu -u",
+    "install:pinact": "go install github.com/suzuki-shunsuke/pinact/v4/cmd/pinact@v4.1.0",
+    "update:actions": "pinact run -u || echo \"problem with pinact\"",
+    "release:verify-prebuilds": "tsx scripts/release-prebuild-artifacts-cli.ts verify",
+    "release:pack-package": "tsx scripts/release-package-cli.ts pack",
+    "release:install-package": "tsx scripts/release-package-cli.ts install",
+    "release:load-package": "tsx scripts/release-package-cli.ts load",
+    "// preflight": "should be manually run by developers before they run `git commit`",
+    "preflight": "tsx scripts/preflight.ts",
+    "prepare-release": "npm run build:dist"
+  },
+  "gypfile": true,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "keywords": [
+    "malloc",
+    "malloc_trim",
+    "memory",
+    "rss",
+    "native",
+    "node-addon",
+    "linux",
+    "macos",
+    "windows"
+  ],
+  "dependencies": {
+    "node-addon-api": "8.9.2",
+    "node-gyp-build": "^4.8.4"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@eslint/js": "^10.0.1",
+    "@types/jest": "^30.0.0",
+    "@types/node": "26.6.5",
+    "cross-env": "^10.1.0",
+    "del-cli": "8.0.1",
+    "eslint": "10.13.0",
+    "eslint-plugin-regexp": "3.3.1",
+    "eslint-plugin-security": "4.2.0",
+    "globals": "17.13.0",
+    "jest": "30.4.2",
+    "jest-environment-node": "30.4.1",
+    "node-gyp": "13.1.0",
+    "npm-check-updates": "23.1.1",
+    "npm-run-all2": "9.0.4",
+    "prebuildify": "^6.0.1",
+    "prettier": "3.9.10",
+    "prettier-plugin-organize-imports": "4.3.0",
+    "ts-jest": "29.4.15",
+    "tsup": "9.0.0",
+    "tsx": "4.23.15",
+    "typedoc": "0.28.20",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.72.0"
+  }
+}

package/scripts/install.cjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+/**
+ * Install script: on glibc Linux, runs node-gyp-build, which loads a prebuild
+ * or compiles the addon from source. Everywhere else it does nothing.
+ *
+ * node-gyp-build is resolved through require.resolve and run with this
+ * process's own interpreter, rather than spawned as `npx node-gyp-build`.
+ *
+ * An outer `npm install -g` exports npm_config_global=true, and a nested npx
+ * inherits it. npx then treats its own bootstrap directory as a global
+ * install, never writes $npm_config_cache/_npx/<hash>/package.json, and fails
+ * reading the file it did not write -- exit 254 on POSIX, 127 on Windows.
+ * Resolving the binary here re-enters neither npm nor the shell, so nothing in
+ * npm's lifecycle environment can redirect it.
+ */
+
+const { spawnSync } = require("node:child_process");
+
+// src/index.ts loads the addon only on glibc, and only glibc has prebuilds, so
+// building it anywhere else would compile a file nothing loads.
+if (process.report.getReport().header.glibcVersionRuntime == null) {
+  process.exit(0);
+}
+
+// No env: option, so the child inherits process.env.
+const result = spawnSync(
+  process.execPath,
+  [require.resolve("node-gyp-build/bin.js")],
+  { stdio: "inherit" },
+);
+
+if (result.error) {
+  console.error("Failed to run node-gyp-build:", result.error);
+  process.exit(1);
+}
+
+if (result.status !== 0) {
+  console.error(`node-gyp-build exited with code ${result.status}`);
+  process.exit(result.status ?? 1);
+}

package/src/binding.cpp

@@ -0,0 +1,43 @@
+// <cstdlib> comes first so glibc's <features.h> defines __GLIBC__ before the
+// check below.
+#include <cstdlib>
+#include <napi.h>
+
+#if defined(__GLIBC__)
+#include <malloc.h>
+#endif
+
+namespace photostructure::heap_trim {
+
+// Asks the C allocator to return free pages to the operating system.
+//
+// glibc's free() shrinks the heap only from its top, so pages freed below a
+// live allocation stay resident. malloc_trim(0) releases those free pages in
+// every arena. It returns 1 if it found a whole free page to madvise() away,
+// without checking whether that page was still resident, so a second call
+// right after the first also returns 1.
+//
+// src/index.ts loads this addon only on glibc (it explains why). The #else
+// branch exists so `npm run lint` and a manual build still compile this file
+// on musl, macOS, and Windows.
+Napi::Value HeapTrim(const Napi::CallbackInfo &info) {
+#if defined(__GLIBC__)
+  return Napi::Boolean::New(info.Env(), malloc_trim(0) == 1);
+#else
+  return Napi::Boolean::New(info.Env(), false);
+#endif
+}
+
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+  exports.Set("heapTrim", Napi::Function::New(env, HeapTrim, "heapTrim"));
+  return exports;
+}
+
+} // namespace photostructure::heap_trim
+
+// NODE_API_MODULE needs an unqualified function name.
+Napi::Object InitHeapTrim(Napi::Env env, Napi::Object exports) {
+  return photostructure::heap_trim::Init(env, exports);
+}
+
+NODE_API_MODULE(heap_trim, InitHeapTrim)