npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@zokugun/fs-path-sanitize

v0.2.2

Published

sanitize filesystem paths and path segments

Downloads

4,365

Readme

@zokugun/fs-path-sanitize

MIT licensed NPM Version Donation Donation Donation

Sanitize filesystem paths and path segments to prevent directory traversal, invalid characters, and reserved names.

Features

  • Prevent directory traversal and unsafe path resolution
  • Remove or replace invalid, restricted, or control characters
  • Configurable Sanitizer with replace/empty listeners for custom behavior
  • Small package with ESM and CJS builds

Installation

npm add @zokugun/fs-path-sanitize

Examples

1. Validate before writing

Check safety first, then read the error if it fails.

import { isSafePath, validatePath } from '@zokugun/fs-path-sanitize';

function demoValidatePosix(): void {
   const path = '/var/log/app:log';

   if(!isSafePath(path, 'universal')) {
      const result = validatePath(path, 'universal');

      console.log(result.error);

      return;
   }

   console.log('path is safe');
}

2. Sanitize a user path for Windows

Sanitize a filename and replace illegal characters with _.

import { sanitizePath } from '@zokugun/fs-path-sanitize';

function demoSanitizeWindows(): void {
   const input = 'my file:report?.txt';
   const result = sanitizePath(input, {
      target: 'windows.safe',
      replacement: '_'
   });

   if(result.fails) {
      console.log('sanitize failed');
      console.log(result.error);

      return;
   }

   console.log(result.value);
}

3. Customize sanitization with listeners

Use ReplaceHandler and EmptyHandler to control leading, trailing and empty results.

import { EmptyHandler, ReplaceHandler, Sanitizer } from '@zokugun/fs-path-sanitize';

function demoCustomSanitize(): void {
   const sanitizer = new Sanitizer({
      target: 'windows.fat32',
      replacement: '-',
      onLeading: ReplaceHandler.addLeadingUnderscore,
      onTrailing: ReplaceHandler.addTrailingUnderscore,
      onEmpty: EmptyHandler.addReplacement
   });
   const segment = '  .con';
   const output = sanitizer.sanitizeSegment(segment);

   console.log(output);
}

API reference

Validation

Use these functions to determine if a path or segment is safe for a given target.

isSafePath(path: string, target?: Target | 'auto'): boolean

Checks if the entire path is safe. Returns true if no violations are found.

  • path: The path string to check.
  • target: The filesystem target (e.g., 'windows.ntfs', 'posix'). Use 'auto' to detect the current OS automatically.

isSafeSegment(segment: string, target?: Target | 'auto'): boolean

Checks if a single path segment is safe.

validatePath(path: string, target?: Target | 'auto'): Result<string, string>

Validates the path. Returns a result indicating success or the specific reason for failure.

validateSegment(segment: string, target?: Target | 'auto'): Result<string, string>

Validates a single segment. Returns a result indicating success or failure.

Sanitization

Use these functions to remove or replace unsafe characters and keywords.

sanitizePath(path: string, options: {...}): Result<string, string>

Cleans a path based on the target rules.

  • path: The string path to sanitize.
  • options: An object containing:
    • absolute?: boolean: Whether the path is absolute.
    • parent?: string | null: Parent directory path.
    • replacement?: string | null: String to use as a replacement for invalid characters.
    • resolve?: Resolver | null: A resolver function to handle path logic.
    • target?: Target | 'auto': The filesystem target or 'auto'.

[!WARNING]

sanitizePath removes dangerous characters, but it does not guarantee the resulting string is safe for shell execution without further quoting or escaping.

By default, relative paths are allowed and . / .. segments are preserved. Set absolute: true to reject these segments. Alternatively, provide resolve to transform the path before sanitization. . / .. segments in the resolved path are then rejected.

sanitizeSegment(segment: string, options: {...}): string

Cleans a single segment.

  • path: The string segment to sanitize.
  • options: An object containing:
    • replacement?: string | null: String to use as a replacement for invalid characters.
    • target?: Target | 'auto': The filesystem target or 'auto'.

Class: Sanitizer

The underlying engine. The standalone functions use this class internally via the singleton getInstance. You can instantiate it directly if you need persistent configuration or advanced listeners.

class Sanitizer {
   static getInstance(target: Target): Sanitizer
   constructor(options: {
      additionalKeywords?: RegExp[] | null;
      maxLength?: number | null;
      minLength?: number | null;
      onEmpty?: EmptyListener | null;
      onKeyword?: ReplaceListener | null;
      onLeading?: ReplaceListener | null;
      onTrailing?: ReplaceListener | null;
      replacement?: string | null;
      target?: Target | null;
   })
   isSafePath(path: string): boolean
   isSafeSegment(segment: string): boolean
   sanitizePath(path: string, options?: { absolute?: boolean; replacement?: string | null; resolve?: Resolver | null }): Result<string, string>
   sanitizeSegment(segment: string, options?: { replacement?: string | null }): string
   validatePath(path: string): Result<string, string>
   validateSegment(segment: string): Result<string, string>
}

Types

Target

A union of strings representing specific filesystem configurations:

| Target | Purpose | | ----------------------- | ------------------------------------------------------------------------------- | | posix | Unix-style filename rules for POSIX systems and utilities. Very very strict. | | universal | Cross-platform safe preset that combines Linux, macOS and Windows restrictions. | | linux.safe | Linux safe preset. | | macos.safe | macOS safe preset; covering common HFS/APFS restrictions. | | windows.safe | Windows safe preset; combining FAT32/NTFS restrictions for compatibility. | | linux.esc.ansic | Linux preset; safe only and only if it's escaped with ANSI-C quoting | | linux.esc.single | Linux preset; safe only and only if it's escaped with single quotes | | macos.apfs.safe | APFS-safe. | | macos.apfs.esc.ansic | APFS preset; safe only and only if it's escaped with ANSI-C quoting | | macos.apfs.esc.single | APFS preset; safe only and only if it's escaped with single quotes | | macos.hfs.safe | HFS-safe. | | macos.hfs.esc.ansic | HFS preset; safe only and only if it's escaped with ANSI-C quoting | | macos.hfs.esc.single | HFS preset; safe only and only if it's escaped with single quotes | | windows.exfat | exFAT safe preset | | windows.fat32 | FAT32 safe preset | | windows.ntfs | NTFS safe preset |

Shell Targets
  • *.esc.ansic: allows the path (file\nname.txt) in touch $'file\nname.txt' to be considered safe.
  • *.esc.single: allows the path (*file.txt) in touch '*file.txt' or touch \*file.txt to be considered safe.

Resolver

type Resolver = ((path: string) => string) | ((path: string, separator: string) => string);

A function used to resolve or transform a path before it is sanitized.

Listeners

These types define how the sanitizer handles replacements.

// Returns a string when a segment becomes empty.
type EmptyListener = (replacement: string) => string

// Determines the replacement string based on the match and current replacement value.
type ReplaceListener = (args: ReplacerArray, replacement: string) => string

EmptyHandler.addReplacement, addUnderscore, addExclamation ReplaceHandler.addLeadingExclamation, addTrailingUnderscore, etc.

Use them as onEmpty, onKeyword, onLeading, onTrailing when constructing a Sanitizer directly.

Restricted Characters

Below are the actual characters and simple rules enforced per target.

  • posix: allows uppercase A-Z, lowercase a-z, digits 0-9, underscore _, dot ., hyphen -.
  • universal: combines Windows and POSIX restrictions. Disallows " * : < > ? | + , ; = [ ] : (colon), NUL (U+0000), control characters (U+0000–U+001F, U+007F), Unicode non-characters (U+FFF0–U+FFFF), various Unicode spaces (e.g. U+00A0, U+1680, U+2000–U+200A, U+202F, U+205F, U+3000), shell-special characters (space, *, ?, [, ], $, `, ", ', |, &, ;, <, >), and relative path segments like ./...
  • linux.safe: disallows shell-special characters (space, *, ?, [, ], $, `, ", ', |, &, ;, <, >), control characters, NUL, and relative path segments.
  • linux.esc.single, macos.*.esc.single: disallows control characters and NUL.
  • linux.esc.ansic, macos.*.esc.ansic: disallows NUL.
  • macos.hfs.safe, macos.safe: disallows colon (:), shell-special characters, control characters, NUL, and relative segments. HFS historically reserves : as a separator.
  • macos.apfs.safe: disallows shell-special characters, control characters, NUL, and relative segments.
  • windows.exfat: disallows " * : < > ? | and control characters (U+0000–U+001F, U+007F); rejects NUL and relative traversal sequences.
  • windows.fat32, windows.safe: disallows " * : < > ? | + , ; = [ ], control characters, leading spaces, trailing spaces or trailing dots, NUL, and relative traversal sequences.
  • windows.ntfs: disallows " * : < > ? |, NUL, control characters, certain Unicode non-characters; additionally checks reserved NTFS volume root names.

Restricted Keywords

These names are rejected (case-insensitive) when the corresponding target enforces keyword rules.

  • FAT32 reserved names (applies to windows.fat32, windows.safe, and universal):

    • CON, PRN, AUX, NUL
    • COM1..COM9 (also superscript forms COM¹, COM², COM³)
    • LPT1..LPT9 (and superscript forms LPT¹, LPT², LPT³)
    • CLOCK$, CONIN$, CONOUT$, CONERR$, CONFIG$
    • File extensions are ignored. So, CON.txt or CON.tar.gz are treated as CON.
  • NTFS volume-root reserved names (applies to windows.ntfs and universal):

    • $Mft, $MftMirr, $LogFile, $Volume, $AttrDef, $Bitmap, $Boot, $BadClus, $Secure, $Upcase, $Extend, $Quota, $ObjId, $Reparse

Contributions

Contributions are most welcome. Please:

  • Open issues and feature requests under the repository discussions.
  • Follow the CONTRIBUTING.md.

Donations

Support this project by becoming a financial contributor.

License

Copyright © 2026-present Baptiste Augrain

Licensed under the MIT license.