tmp-promise

tmp-promise wraps the widely used tmp library in a promise-based API, so temporary file and directory workflows can be written with async/await instead of Node-style callbacks. It preserves the underlying package’s behavior — random name generation via crypto with a pseudo-random fallback, configurable prefixes/postfixes/templates, and automatic cleanup on process exit — while adding a small set of ergonomic wrappers.

Beyond the direct file()/dir()/tmpName() promise wrappers, it also exposes withFile() and withDir() disposer-style helpers that create a temporary resource, hand it to a callback, and guarantee cleanup once that callback’s returned promise settles, whether it resolves or rejects. Synchronous variants (fileSync, dirSync, tmpNameSync) are re-exported directly from tmp for callers that don’t need promises.

What You Get

• Promise-returning file() and dir() functions that resolve with a path (and file descriptor for files) plus a cleanup() function
• withFile() and withDir() disposer helpers that automatically clean up the temp resource once your async callback settles, even on error
• Promise-wrapped tmpName() for generating a unique temporary filename without creating the file
• Re-exported synchronous APIs (fileSync, dirSync, tmpNameSync, setGracefulCleanup) for callers that don’t need promises
• Full TypeScript typings (index.d.ts) for FileResult, DirectoryResult, and all exported functions

Common Use Cases

• Writing a test that needs a scratch file or directory and wants guaranteed cleanup via withFile/withDir even if an assertion throws
• Downloading or generating a file to a temp path inside an async function before uploading or processing it further
• Building a CLI or build tool that needs a disposable working directory for intermediate build artifacts
• Replacing callback-based tmp usage in a codebase that has migrated to async/await

Under The Hood

Architecture The whole library is a single file, index.js (about 50 lines), that wraps the tmp package’s callback-based API using Node’s util.promisify, exposing file, dir, and tmpName as promise-returning functions, plus two additional composed helpers, withFile and withDir, that implement the disposer pattern via try/finally. There is no internal module structure beyond that one file — it is a thin adapter layer with no state of its own, delegating all real temp-file logic (random name generation, entropy fallback, process-exit cleanup) to the tmp dependency; changing the core abstraction here effectively means changing the shape of the promisify-based wrapper functions or the version of tmp being wrapped.

Tech Stack A plain CommonJS module targeting Node.js 8+, with a single runtime dependency, tmp (^0.2.0), and dev dependencies of @types/tmp, mocha (7.1.2) for the test suite, and tsd (0.25.0) for type-testing index.d.ts against index.test-d.ts. There is no build step — package.json’s files field ships index.js and index.d.ts directly, with no bundler or transpiler involved. CI runs on CircleCI, executing the Mocha suite and the tsd type check across Node 14, 16, 18, and 19 on every commit.

Code Quality A single test.js file uses Mocha’s BDD interface (describe/context/it) with Node’s built-in assert module, covering file(), dir(), withFile(), and withDir() — including a happy path, a custom-prefix case, and an explicit error-propagation test against a nonexistent directory. No linter or formatter configuration is present in the repo, and there is no explicit error-handling logic beyond letting tmp’s callback errors propagate through promisify. Type safety comes from the hand-written index.d.ts, exercised by tsd against index.test-d.ts, rather than the implementation itself being written in TypeScript.

API Design The public API mirrors the wrapped tmp package’s naming closely (file, dir, tmpName, and their Sync variants), which keeps the migration path from callback-based tmp usage nearly frictionless and adds only two new concepts, withFile and withDir, rather than a whole new vocabulary. Getting started requires zero configuration since file() and dir() work with no options, and the README documents every option inherited from tmp (mode, prefix, postfix, template, dir, tries, keep, unsafeCleanup) directly. TypeScript users get typed results (FileResult, DirectoryResult) out of the box via the bundled index.d.ts, though users unfamiliar with the underlying tmp package may still need to cross-reference its docs for less common options.