tessl/npm-tmp

Temporary file and directory creator for Node.js applications

—

Pending

Overview

Eval results

Files

File Operations

Name: tessl/npm-tmp
Author: tessl

Temporary file creation and management with full control over file descriptors, permissions, and cleanup behavior.

Capabilities

Asynchronous File Creation

Creates and opens a temporary file asynchronously.

/**
 * Creates and opens a temporary file
 * @param {Options|Function} options - Configuration options or callback function
 * @param {Function} callback - Callback function (err, path, fd, cleanupCallback) => void
 */
function file(options, callback);

Callback Parameters:

err (Error|null): Error object or null if successful
path (string): Full path to the created temporary file
fd (number): File descriptor for the opened file (-1 if discarded)
cleanupCallback (Function): Function to manually remove the file

Usage Examples:

const tmp = require("tmp");

// Basic file creation
tmp.file(function(err, path, fd, cleanupCallback) {
  if (err) throw err;
  
  console.log("File:", path);
  console.log("File descriptor:", fd);
  
  // Write to the file using the file descriptor
  const fs = require("fs");
  fs.writeSync(fd, "Hello, temporary file!");
  
  // Clean up when done
  cleanupCallback();
});

// File creation with options
tmp.file({ 
  mode: 0o644, 
  prefix: "myapp-", 
  postfix: ".txt" 
}, function(err, path, fd, cleanupCallback) {
  if (err) throw err;
  
  console.log("Custom temp file:", path);
  // File will have name like: /tmp/myapp-12345-67890.txt
  
  cleanupCallback();
});

// Discard file descriptor for stream usage
tmp.file({ discardDescriptor: true }, function(err, path, fd, cleanupCallback) {
  if (err) throw err;
  
  console.log("File path:", path);
  console.log("File descriptor:", fd); // undefined
  
  // Now safe to use with fs.createWriteStream without holding extra descriptor
  const fs = require("fs");
  const stream = fs.createWriteStream(path);
  stream.write("Stream data");
  stream.end();
  
  cleanupCallback();
});

Synchronous File Creation

Creates and opens a temporary file synchronously.

/**
 * Creates and opens a temporary file synchronously
 * @param {Options} options - Configuration options
 * @returns {FileSyncObject} Object with name, fd, and removeCallback
 * @throws {Error} If file creation fails
 */
function fileSync(options);

Return Value:

interface FileSyncObject {
  name: string;                // Full path to the temporary file
  fd: number;                  // File descriptor (-1 if discarded)
  removeCallback: Function;    // Cleanup function
}

Usage Examples:

const tmp = require("tmp");

// Basic synchronous file creation
const tmpFile = tmp.fileSync();
console.log("Temp file:", tmpFile.name);
console.log("File descriptor:", tmpFile.fd);

// Write to the file
const fs = require("fs");
fs.writeSync(tmpFile.fd, "Synchronous data");

// Clean up
tmpFile.removeCallback();

// File creation with custom options
const customFile = tmp.fileSync({
  mode: 0o600,
  prefix: "secure-",
  postfix: ".tmp",
  dir: "cache"  // Create in cache subdirectory of temp dir
});

console.log("Custom file:", customFile.name);
customFile.removeCallback();

// Discard descriptor for external management
const streamFile = tmp.fileSync({ discardDescriptor: true });
console.log("Stream file:", streamFile.name);
console.log("File descriptor:", streamFile.fd); // undefined

// Use with streams
const writeStream = fs.createWriteStream(streamFile.name);
writeStream.write("Stream content");
writeStream.end();

streamFile.removeCallback();

File Descriptor Control

The tmp library provides fine-grained control over file descriptor lifecycle:

Discard Descriptor

Use discardDescriptor: true when you want tmp to close the file descriptor immediately after creation. This is useful when using the file with streams or other APIs that open their own descriptors.

tmp.file({ discardDescriptor: true }, function(err, path, fd, cleanupCallback) {
  // fd will be undefined
  // Safe to use path with fs.createReadStream, fs.createWriteStream, etc.
});

Detach Descriptor

Use detachDescriptor: true when you want to manage the file descriptor yourself. The cleanup callback will not attempt to close the descriptor.

tmp.file({ detachDescriptor: true }, function(err, path, fd, cleanupCallback) {
  // You are responsible for closing fd
  // cleanupCallback() will only remove the file, not close the descriptor
  
  // Later, when you're done with the descriptor:
  fs.closeSync(fd);
  cleanupCallback();
});

File Options

All file operations support the following options:

interface FileOptions {
  mode?: number;               // File permissions (default: 0o600)  
  prefix?: string;             // Filename prefix (default: "tmp")
  postfix?: string;            // Filename postfix
  template?: string;           // Template with XXXXXX (e.g., "temp-XXXXXX.txt")
  name?: string;               // Fixed filename (relative to dir/tmpdir)
  dir?: string;                // Subdirectory within tmpdir
  tmpdir?: string;             // Override system temp directory
  tries?: number;              // Max naming attempts (default: 3)
  keep?: boolean;              // Skip automatic cleanup
  detachDescriptor?: boolean;  // Don't close descriptor in cleanup
  discardDescriptor?: boolean; // Close descriptor immediately after creation
}

Important Notes:

File permissions default to 0o600 (owner read/write only) for security
The template option must contain exactly one XXXXXX pattern which gets replaced with random characters
When name is specified, tries is automatically set to 1
The keep option prevents automatic cleanup but manual cleanup via callback still works
Only one of detachDescriptor or discardDescriptor should be used