or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-unique-filename

Generate a unique filename for use in temporary directories or caches.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/unique-filename@4.0.x

To install, run

npx @tessl/cli install tessl/npm-unique-filename@4.0.0

index.mddocs/

Unique Filename

Unique Filename is a lightweight JavaScript library that generates unique filenames for use in temporary directories or caches. It combines directory paths with optional prefixes and unique identifiers to create collision-free filenames, supporting both random and deterministic filename generation.

Package Information

  • Package Name: unique-filename
  • Package Type: npm
  • Language: JavaScript (CommonJS)
  • Installation: npm install unique-filename
  • Node.js: Requires Node.js ^18.17.0 || >=20.5.0

Core Imports

const uniqueFilename = require('unique-filename');

Note: This package uses CommonJS and does not provide ES modules (ESM) support.

Basic Usage

const uniqueFilename = require('unique-filename');
const os = require('os');

// Random filename in temp directory
// Returns something like: '/tmp/7ddd44c0' (on Unix) or 'C:\\Users\\...\\7ddd44c0' (on Windows)
const randomTmpfile = uniqueFilename(os.tmpdir());

// Random filename with prefix
// Returns something like: '/tmp/my-app-51a7b48d'
const prefixedTmpfile = uniqueFilename(os.tmpdir(), 'my-app');

// Deterministic filename (same input produces same output)
// Returns something like: '/tmp/cache-7ddd44c0'
const deterministicTmpfile = uniqueFilename(os.tmpdir(), 'cache', '/path/to/unique/data');

Capabilities

Unique Filename Generation

Generates unique filenames by combining directory paths with optional prefixes and unique identifiers.

/**
 * Generate a unique filename for use in temporary directories or caches
 * @param {string} filepath - The directory path where the unique filename should be located
 * @param {string} [prefix] - Optional prefix to prepend to the unique part (with hyphen separator)
 * @param {string} [uniq] - Optional string for deterministic unique filename generation. If not provided, generates random unique part
 * @returns {string} Full path to a unique filename in the format 'filepath/[prefix-]uniquepart'
 */
function uniqueFilename(filepath, prefix, uniq);

Parameters:

  • filepath (string, required): The directory path where the unique filename should be located. Use os.tmpdir() for system temporary directory.
  • prefix (string, optional): An optional prefix to prepend to the unique part. If provided and not empty, it's added with a hyphen separator (prefix-uniquepart).
  • uniq (string, optional): Optional string for deterministic unique filename generation. If provided, the same input will always produce the same filename. If omitted, generates a random unique filename.

Return Value:

  • Returns a string containing the full path to a unique filename
  • Format: filepath/[prefix-]uniquepart where uniquepart is an 8-character hexadecimal string
  • Random generation produces different filenames on each call
  • Deterministic generation produces consistent filenames for the same uniq input

Usage Examples:

const uniqueFilename = require('unique-filename');
const os = require('os');
const path = require('path');

// Random filename generation
const tempFile1 = uniqueFilename(os.tmpdir());
// → '/tmp/a1b2c3d4' (Unix) or 'C:\\Users\\...\\a1b2c3d4' (Windows)

const tempFile2 = uniqueFilename(os.tmpdir());
// → '/tmp/e5f6g7h8' (different from tempFile1)

// Prefixed random filename
const logFile = uniqueFilename('/var/log', 'myapp');
// → '/var/log/myapp-9i0j1k2l'

// Deterministic filename generation
const cacheFile1 = uniqueFilename('/tmp/cache', 'data', '/path/to/source/file.json');
// → '/tmp/cache/data-7ddd44c0'

const cacheFile2 = uniqueFilename('/tmp/cache', 'data', '/path/to/source/file.json');
// → '/tmp/cache/data-7ddd44c0' (same as cacheFile1)

// Different source produces different filename
const cacheFile3 = uniqueFilename('/tmp/cache', 'data', '/path/to/other/file.json');
// → '/tmp/cache/data-a8b9c0d1' (different from cacheFile1)

// Using with path operations
const outputDir = '/tmp/build';
const outputFile = uniqueFilename(outputDir, 'bundle');
// → '/tmp/build/bundle-m3n4o5p6'

Dependencies

This package depends on:

  • unique-slug (^5.0.0): Provides the underlying unique identifier generation functionality