Synopsis

sanitiser is a path name sanitiser. It's based off of the sanitize-filename package, but accepts directory separators such as / and \, making it viable to sanitise path names, as well as filenames.

Notice

This repository is licenced under the MIT licence. For a full picture of your rights and responsibilities, refer to the licence file in the root directory of this repository (LICENCE).

Benchmarks

In the table below you can find the approximate speed of sanitiser in each version starting from 0.0.2.

|Version|Speed @ 2.20 GHz| |---|---| |0.0.2|ca. 1.5 µs per call*|

* Definition of a call—sanitiser('/path/to/file'); without any options or a callback, where the the supplied string varies.

Installing

This package is a node package. To install it using npm (Node package manager), issue the below command in your shell, given you are in the relevant working directory of your project/repository:

npm registry:

npm install sanitiser

GitHub registry:

npm install @kerig-it/[email protected]

This will add sanitiser in your dependencies in your package.json file.

Usage

Syntax

sanitiser(pathname[, options, callback]);

• pathname <string> Path
• options <Object>
  • ignoreControl <boolean> Default: false
  • ignoreIllegal <boolean> Default: false
  • ignoreRelative <boolean> Default: false
  • noTruncation <boolean> Default: false
  • replacement <string> Replacer for illegal characters
  • separator <string> Directory separator
• callback <Function>
  • error <Error>
  • result <string> Sanitised path

More information in Sanitising.

Importing

To use the sanitiser package in your project/code, you can add it using import or require.

import:

import sanitiser from 'sanitiser';

require:

const sanitiser = require('sanitiser');

Sanitising

sanitiser is a function that accepts three arguments.

|Parameter|Type|Mandatory|Description| |---|---|---|---| |pathname|String|Yes|Holds the path name that has to be sanitised.| |options|Object|No|Holds an object with proprties that can configure the behaviour of the sanitise function.| |callback|Function|No|Holds a callback function that will be executed when pathname is sanitised.|

options parameter

|Property|Type|Default|Description| |---|---|---|---| |ignoreControl|Boolean|false|Defines whether or not to apply the control characters regular expression.| |ignoreIllegal|Boolean|false|Defines whether or not to apply the illegal characters regular expression.| |ignoreRelative|Boolean|false|Defines whether or not to apply the relative paths regular expression.| |noTruncation|Boolean|false|Defines whether or not to truncate the path name to 4096 bytes.| |replacement|String|Empty string|Holds a string that illegal characters in pathname will be replaced with.| |separator|String|Auto-detection|Holds a string that defines what directory separator is used in the supplied path name. You can set this to 'system' to use the system's default directory separator.|

callback parameter

|Parameter|Type|Description| |---|---|---| |error|Error|Error instances upon errors.| |result|String|Holds the sanitised path name.|

So, the first parameter is the actual string representing the path that you would like to sanitise. The second parameter is an object where you can supply specific options to alter the behaviour of the sanitise function. The third parameter is a callback function with two parameters of its own that will be executed once the path name is sanitised.

Below are all regular expressions that are used in sanitising a path name.

Control characters:

/[\x00-\x1f\x80-\x9f]/g

Illegal characters:

/[\?<>:\*\|"]/g

Relative paths:

/^\.+$/

Before the regular expression will be applied to the supplied path name, though, pathname will be truncated to 4096 bytes with the aid of the truncate-utf8-bytes package. It is possible to not truncate the path name by supplying the noTruncation option being set to true in the options parameter.

The sanitise function returns a string representing the sanitised path name or the callback, if supplied.

Examples

Sanitised path name assigment to a variable.

const sanitiser = require('sanitiser');

let pathname = '/some/../arbitrary/./path/*';
let sanitised = sanitiser(pathname);

console.log(sanitsed);
// Expected output: /some/arbitrary/path/

Sanitised path name output via a callback.

const sanitiser = require('sanitiser');

let pathname = '/some/../arbitrary/./path/*';

sanitiser(pathname, (error, result) => {
	if (error) throw error;

	console.log(result);
	// Expected output: /some/arbitrary/path/
});

Sanitised path name with ignoreRelative enabled output via a callback.

const sanitiser = require('sanitiser');

let pathname = '/some/../arbitrary/./path/*';

sanitiser(pathname, { ignoreRelative: true }, (error, result) => {
	if (error) throw error;

	console.log(result);
	// Expected output: /some/../arbitrary/./path/
});

Testing

To test the sanitiser, you can issue the below command in your shell, given your working directory is the root directory of this repository.

npm test

This will run a test of the package, logging the original and a sanitised version of all path names from test/paths, as well as stats of the process at the end.

Support

If you have any further questions or you ran into problems, you can contact any of this repository contributors or open an issue on our GitHub repository. If you chose the former, you can choose from one of the below e-mail addresses:

• [email protected] (@msfninja)