Sanitiser

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.

Table of Contents
Notice Benchmarks Installing Usage Syntax Importing Sanitising Examples Testing Support

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/sanitiser@0.0.1

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:

• [e-mail] (@msfninja)