Part of the monorepo mangos

• Tokenizes filepath string into its consituants;
• Preserves correctly (node resolve does not) the root of dos device path and unc path.
• Provides utilities to work with different path types irrespective of OS used.

• Microsoft dos device path
• UNC path
• Traditional DOS path
• Unix path

Note: \ needs to be escaped when using it in js code.

// node  
> path.resolve('\\\\?\\C:\\repos','../../../text.txt');
// -> \\?\text.txt  \\?\C: is mangled

// filePath
> fp.resolve('\\\\?\\C:\\repos','../../../text.txt').toString();
// -> '\\?\C:\text.txt'  aka'\\?\C:\' root is preserved

Note: \ needs to be escaped when using it in js code.

// node resolve
path.resolve('//?/UNC/Server/share', '../../../txt');
// -> '\\\\?\\txt'  mangled unc loot

// this library
filePath.resolve('//?/UNC/Server/share', '../../../txt').toString();
// -> '\\\\?\\UNC\\Server\\share\\txt'  unc root preserved
// -> root: \\\\?\\UNC\\Server\\share

path.resolve('//system07/c$/x/y', '../../../../../txt');
// -> '\\\\system07\\c$\\txt' unc root preserved 

fp.resolve('//system07/c$/x/y', '../../../../../txt').toString()
// -> '\\\\system07\\c$\\txt' unc root is preserved

There are 4 exported functions:

import { allPath, firstPath, resolve, resolvePathObject } from '@mangos/filepath';

There are 2 exported classes:

import { ParsedPath,  ParsedPathError, PathToken } from '@mangos/filepath';

There is 1 exported type:

import type { InferPathOptions } from '@mangos/filepath'

Most of the time you will be using resolve, firstPath.

The functions allPath and firstPath will try to tokenize a path string based on options object specified as the second argument.

type InferPathOptions = {
    devicePath: boolean; // parse string as dos device path
    unc: boolean; // parse string as unc path
    dos: boolean; // parse string as traditional dos path
    posix: boolean; // parse string as unix path
}

Multiple path types can be tokenized from the same path string.

The response of allPath will be an array of ParsedPath or/and ParsedPathError class instance, representing parsing for multiple OS path types.

If InferpathOptions argument is left empty in allPath and firstPath the default will be used based on OS:

• The default for windos: { dos: true, devicePath: true, unc: true, posix: false }
• The default for unix: { posix: true }

The response of a successfull path tokenization will be an ADT: ParsedPath.

An instance of ParsedPath has the following fields/members

• members:
  • toString(): string: return the original path string
  • isRelative(): boolean: is the a path a relative one?
• fields:
  • type: string: one of the value devicePath, unc, dos, posix.
  • path: FileToken[]: the path tokenized (see source).

If a path has illigal characters or is invalid the result of a tokenization will be an ADT: ParsedPathError

• members:
  • toString(): string: algamation of all errors found during parsing.
• attributes:
  • type: string: one of the values devicePath, unc, dos, posix.
  • path: FileToken[]: the path tokenized.

When a string is parsed it will be evaluated according to path types in the following order:

1. devicePath tokanization will be tried first (if the devicePath boolean is set to true).
2. unc tokanization will be tried second, (if the devicePath boolean is set to true).
3. dos tokanization will be tried third, (if the dos boolean is set to true).
4. posix tokanization will be tried forth, (if the posix boolean is set to true)

You dont create PathTokens yourself the api will do it for you.

class PathToken {
	value: string; // actual path fragment (directory, seperator, or file)
	start: number; // start location in the original string
	end: number; // end (inclusive) in the original string
    error?: string; // this token has invalid character for the OS selected
    isRoot(): boolean; // is this token a Root Token (c:/,  /, //?/UNC/Server/share, etc)
    isPathElement(): boolean; // a normal path element
    isCurrent(): boolean; // token representing "./"
    isParent(): boolean // token representing "../"
    isSeperator(): boolean // token representing "/" (posix) or "\" (windows, dos)
    hasError(): boolean // did tokenizing the path associated an error with this token
}

function allPath(path = '', options: InferPathOptions = {}): (ParsedPath | ParsedPathError)[];

• path: string optional: (Default is current working directory). Relative or absolute path conforming to one of the supported path types.
• options: InferPathOptions optional: Parsing limited to flags set to true in options.

• An Array that is:
  • empty (path is not one of the path types)
  • contains ParsedPath and in case of errors ParsedPathError objects.

import { allPath  } from '@mangos/filepath';

// will attempt to tokenize the path according to dos and unc path types
const paths = allPath('//system07/c$/x/y', { dos: true, unc: true });

// unc is the only possible match
paths.length
// -> 1
paths[0].type
// -> unc
path[0].toString()
// -> \\system07\c$\x\y or '\\\\system07\\c$\\x\\y' with \ escaped

function firstPath(path = '', options: InferPathOptions = {}): ParsedPath | ParsedPathError | undefined;

• path: string optional: (Default is current working directory). Relative or absolute path conforming to one of the supported path types.
• options: InferPathOptions optional: Parsing limited to flags set to true in options.

• undefined: The path was not confirm to any of the types listed in path types

• ParsedPath: In case of successfull parse.

• ParsedPathError: In case of legal structure but illegal characters in the path.

function resolvePathObject(from: ParsedPath, ...toFragments: string[]): ParsedPath;

• from: ParsedPath: A previously created ParsedPath object via firstPath function.
• toFragments: string[]: A sequence of paths or path segments.

• ParsedPath: In case of successfull resolve.

• If from is a ParsedPathError an Error will be thrown.
• If any of the toFragments is an invalid path an Error will be thrown.

function resolve(fromStr: string, ...toFragments: string[]): ParsedPath;

• fromStr: string optional: A path according to a path type. Defaults to current working directory if absent/undefined.
• toFragments: string[]: A sequence of paths or path segments.

• ParsedPath: In case of successfull resolve.

If fromStr is invalid a ParsedPathError an Error will be thrown.

Copyright (c) 2019-2025 Jacob Bogers [email protected].

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.