valid-path

Built with love, will be grateful for :heart:

Returns an object, that tells if provided string is a valid path, or describes got problem.

| | valid | invalid | | :--------- | :----- | :------- | | input | 'a/b/c' | 'a/nul/b' | | output | { valid: true, error: null, data: { input: "a/b/c", notes: [] //...flags }} | { valid: false, error: 'Input string contains file or folder name, that is forbidden in Windows (nul)', data: { input: 'a/nul/b', notes: [] //...flags }} |

Table of contents

• Install
• Migrate from version 1.0.0
• Usage
• return object
• Examples
• Options
  • simpleReturn
  • sep
  • allowSepDuplications
  • allowDriveLetter
  • allowGlobPatterns
  • allowForbiddenWindowsNames
  • allowFobiddenWindowsChars
  • allowForbiddenUnixChars
• Migrate from version 1.0.0

Install

npm i valid-path

Usage

validPath function takes three arguments:

• string
• options
• callback

validPath('string'[, options, callback]);

| argument | required | expected type | | :--------- | :---------------------- | ------------- | | string | :heavy_check_mark: | string | | options | :heavy_minus_sign: | object | | callback | :heavy_minus_sign: | function |

Example:

const validPath = require('validPath');

const myPath = validPath('string/to/check');

if (myPath.valid) {
    // ...
} else {
    console.log(`Error in ${myPath.data.input}: ${myPath.error}`);
}

return object

{
    valid: boolean,
    error: null || string,
    data: {
        input: input,
        notes: string[],
        sepDuplications: boolean,
        driveLetter: boolean,
        globPatterns: boolean,
        forbiddenWindowsNames: boolean,
        fobiddenWindowsChars: boolean,
        forbiddenUnixChars: boolean
    }
}

Examples

Outputs for calls with default options

| Input | Output | | :--------- | :----- | | a/b/c | { valid: true, error: null, data: { input: 'a/b/c', notes: [] }} | | a/b/c.js | { valid: true, error: null, data: { input: 'a/b/c.js', notes: [] }} | | C://a/b | { valid: true, error: null, data: { input: 'C://a/b', notes: [ 'Input string contains drive letter' ] }} | | (nothing) | { valid: false, error: '"string" argument must be of type "string", got "undefined" for "undefined"', data: { input: undefined, notes: [] }} | | null | { valid: false, error: '"string" argument must be of type "string", got "object" for "null"', data: { input: null, notes: [] }} | | !a/b/c | { valid: false, error: 'Input string contains Glob pattern', data: { input: '!a/b/c', notes: [] }} | | a\\b\\c | { valid: false, error: 'Input string contains characters, that are forbidden in Windows (a\\b\\c)', data: { input: 'a\\b\\c', notes: [] }} | | a/b//c | { valid: false, error: 'Input string contains duplicated separator', data: { input: 'a/b//c', notes: [] }} | | a/b/con | { valid: false, error: 'Input string contains file or folder name, that is forbidden in Windows (con)', data: { input: 'a/b/con', notes: [] }} | | a/b:c/d | { valid: false, error: 'Input string contains characters, that are forbidden in Windows (b:c)', data: { input: 'a/b:c/d', notes: [] }} | | a/\0b\c | { valid: false, error: 'Input string contains characters, that are forbidden in Unix (\x00b)', data: { input: 'a/\x00b/c', notes: [] }} |

Options

Options are optional:

• simpleReturn
• sep
• allowSepDuplications
• allowDriveLetter
• allowGlobPatterns
• allowForbiddenWindowsNames
• allowFobiddenWindowsChars
• allowForbiddenUnixChars

options.simpleReturn

If true, valid-path will return boolean (true or false), not an object.

| Default | Expects | | :------ | :------ | | false | boolean |

Example

| input | a/b/c | a/b/con | | :---------- | :---- | :------ | | options | { simpleReturn: true} | { simpleReturn: true} | | output | true | false |

options.sep

Defines path separator: / or \\.

| Default | Expects | | :------ | :------ | | / | / or \\ |

Example

| input | a/b/c | a/b/c | | :---------- | :---- | :------ | | options | { //default} | { sep: '\\'} | | output | { valid: true, error: null, data: { input: 'a/b/c', notes: [] }} | { valid: false, error: 'Input string contains characters, that are forbidden in Windows (a/b/c)', data: { input: 'a/b/c', notes: [] }} |

options.allowSepDuplications

If true, valid-path will ignore separator duplications and will add a note in notes array of returned object (Object.data.notes).

| Default | Expects | | :------ | :------ | | false | boolean |

Example

| input | a/b//c | a/b//c | | :---------- | :---- | :------ | | options | { // default} | { allowSepDuplications: true} | | output | { valid: false, error: 'Input string contains duplicated separator', data: { input: 'a/b//c', notes: [] }} | { valid: true, error: null, data: { input: 'a/b//c', notes: [ 'Input string contains duplicated separator' ] }} |

options.allowDriveLetter

If true, valid-path will accept drive letter in provided path and will add a note in notes array of returned object (Object.data.notes).

Drive letter can have single and doubled separator (C:/a/b or C://a/b). In case of doubled separator you do not need to set allowSepDuplications option to true: valid path will accept the duplication just for drive letter.

| Default | Expects | | :------ | :------ | | true | boolean |

Example

| input | C://a/b | C://a/b | | :---------- | :---- | :------ | | options | { // default} | { allowDriveLetter: false} | | output | { valid: true, error: null, data: { input: 'C://a/b', notes: [ 'Input string contains drive letter' ] }} | { valid: false, error: 'Input string contains drive letter', data: { input: 'C://a/b', notes: [] }} |

options.allowGlobPatterns

If true, valid-path will accept glob pattern in provided path and will add a note in notes array of returned object (Object.data.notes).

| Default | Expects | | :------ | :------ | | false | boolean |

Example

| input | a/*/*.js | a/*/*.js | | :---------- | :---- | :------ | | options | { // default} | { allowGlobPatterns: true} | | output | { valid: false, error: 'Input string contains Glob pattern', data: { input: 'a/*/*.js', notes: [] }} | { valid: true, error: null, data: { input: 'a/*/*.js', notes: [ 'Input string contains Glob pattern' ] }} |

options.allowForbiddenWindowsNames

By default valid-path does not accept file and folder names that are forbidden in Windows: nul, prn, con, lpt[0-9], com[0-9]. Set to true to accept these names.

| Default | Expects | | :------ | :------ | | false | boolean |

Example

| input | a/b/lpt3 | a/b/lpt3 | | :---------- | :---- | :------ | | options | { // default} | { allowForbiddenWindowsNames: true} | | output | { valid: false, error: 'Input string contains file or folder name, that is forbidden in Windows (lpt3)', data: { input: 'a/b/lpt3', notes: [] }} | { valid: true, error: null, data: { input: 'a/b/lpt3', notes: [ 'Input string contains file or folder name, that is forbidden in Windows (lpt3)' ] }} |

options.allowFobiddenWindowsChars

By default valid-path does not accept characters in path items that are forbidden in Windows: /, \, <, >, :, ", *, ?, |. Set to true to accept these characters.

| Default | Expects | | :------ | :------ | | false | boolean |

Example

| input | a/b:c/d | a/b:c/d | | :---------- | :---- | :------ | | options | { // default} | { allowFobiddenWindowsChars: true} | | output | { valid: false, error: 'Input string contains characters, that are forbidden in Windows (b:c)', data: { input: 'a/b:c/d', notes: [] }} | { valid: true, error: null, data: { input: 'a/b:c/d', notes: [ 'Input string contains characters, that are forbidden in Windows (b:c)' ] }} |

options.allowForbiddenUnixChars

By default valid-path does not accept characters in path items that are forbidden in Unix: \0 (NULL byte), /. Set to true to accept these characters.

| Default | Expects | | :------ | :------ | | false | boolean |

Example

| input | a/\0b/c | a/\0b/c | | :---------- | :---- | :------ | | options | { // default} | { allowForbiddenUnixChars: true} | | output | { valid: false, error: 'Input string contains characters, that are forbidden in Unix (\x00b)', data: { input: 'a/\x00b/c', notes: [] }} | { valid: true, error: null, data: { input: 'a/\x00b/c', notes: [ 'Input string contains characters, that are forbidden in Unix (\x00b)' ] }} |

[NB] Migrate from version 1.0.0

valid-pqath v1.0.0 had return and options different from current version, and did not have callback argument. If you switch to the latest version, it will break your code. To keep your existing code and use the latest valid-path version you have to set migrate option to true:

validPath('a/b', {migrate: true});

Plese note, that migrate will be deprecated in future versions.