untildify

untildify is a zero-dependency Node.js utility that expands a leading tilde in a file path into an absolute path rooted at the current user’s home directory. It handles the common ~/dev shorthand as well as the less common ~username/dev form, only expanding the latter when the username matches the user actually running the process — any other ~someone pattern is returned unchanged rather than guessing at a path that doesn’t exist.

The module targets ESM-only, modern Node.js (20+) and lazily caches the resolved home directory and current username on first use via node:os, so repeated calls avoid redundant system calls. It’s a small piece of plumbing commonly pulled into CLIs, config loaders, and file-path resolvers that accept user-supplied paths and need to normalize shell-style tilde shortcuts before touching the filesystem.

What You Get

• A single default-export function that takes a string path and returns the tilde-expanded absolute path
• Full TypeScript type definitions (index.d.ts) validated by tsd in CI
• Zero runtime dependencies — only Node’s built-in node:os module is used
• An ESM-only package targeting Node.js 20+, matching modern module conventions

Common Use Cases

• Expanding a ~/config path a user typed on the CLI before reading the file
• Normalizing a path from a config file or environment variable that may contain a leading ~
• Resolving ~username/... paths in tools that operate across multiple local user accounts
• Sanitizing user-supplied file paths in build tools and CLIs prior to fs operations

Under The Hood

Architecture untildify is a single-file ESM module (index.js) exporting one default function with no internal layering — the implementation resolves a path in two steps: a regex test for the bare ~ prefix, then a fallback regex match for ~username, each guarded by module-scoped, lazily-initialized homeDirectory and currentUser variables populated on first call via node:os. There’s no state beyond that memoization, no dependency injection, and nothing external to break — the only failure mode is a misreported home directory or username, both of which are delegated entirely to Node’s os module.

Tech Stack The package targets Node.js 20+ as an ESM-only module with zero runtime dependencies, relying solely on the node:os built-in for os.homedir() and os.userInfo(). Its dev toolchain is comparatively heavier than its runtime footprint: ava as the test runner, esmock for mocking the os module in tests without depending on the real filesystem, tsd for compiling and asserting the shipped .d.ts against real TypeScript call sites, and xo (an ESLint preset) for linting — all wired into a GitHub Actions matrix that runs the full suite against Node 20 and 24.

Code Quality Test coverage is thorough for the package’s size — test.js exercises tilde expansion with and without a resolvable home directory, path-separator variants (forward slash vs. backslash), regex-special characters in paths (guarding against String.prototype.replace’s $-pattern footguns), and multiple ~username branches (current user, other users, non-existent users), all using esmock to substitute a fake os.homedir() rather than depending on the test machine’s real environment. Type safety is enforced by a hand-written index.d.ts checked against real call sites via index.test-d.ts and tsd. Style is enforced by xo, and every push and pull request is checked by CI across two Node versions — solid quality assurance for a utility this small.

API Design The public API is a single default-export function with one required string argument and no options object — about as low-friction to adopt as a library can be, requiring zero configuration. It doesn’t introduce a new technique so much as codify a common shell convention (tilde expansion) safely for Node: it deliberately declines to expand ~otheruser paths unless they match the actual process’s username, a small but deliberate safety choice that avoids silently returning a path for a user who isn’t actually running the code. Beyond that scoping decision, the underlying technique — regex-based tilde matching backed by os.homedir() — is standard and well-established, matching what comparable tilde-expansion utilities across other ecosystems already do.