Skip to main content

Path Utils

PathUtil standardizes file path, URL, and resource path manipulation so asset loading remains predictable between environments. The PathUtil class works closely with the ResourcePath class, which is responsible for parsing, storing, and manipulating path components.

resolve​

Resolves a sequence of paths, joining them one by one. Works in a similar way to the resolve method from the Node.JS Path module.

static resolve(...paths:ResourcePathLike[]):string
const resolvedPath = PathUtil.resolve('assets', 'images', 'sprite.png');
console.log(resolvedPath);
// Output: assets/images/sprite.png

const absolutePath = PathUtil.resolve('/root', 'assets', 'images', 'sprite.png');
console.log(absolutePath);
// Output: /root/assets/images/sprite.png

const relativePath = PathUtil.resolve('assets', '../textures', 'sprite.png');
console.log(relativePath);
// Output: textures/sprite.png

const urlPath = PathUtil.resolve('http://localhost:8080', 'bundle.json');
console.log(urlPath);
// Output: http://localhost:8080/bundle.json

const resourcePath = new ResourcePath('db://assets/icons');
const resolvedResource = PathUtil.resolve(resourcePath, '../atlas/bonus.png');
console.log(resolvedResource);
// Output: db://assets/atlas/bonus.png

normalize​

Normalizes a path by removing redundant parts like ., .., and multiple slashes.

The unknown parameter is a flag indicating the source of the path is unknown, forcing path cleanup before parsing.

static normalize(path:ResourcePathLike, unknown:boolean = true):string
const normalizedPath1 = PathUtil.normalize('assets/images/../textures/./sprite.png');
console.log(normalizedPath1);
// Output: assets/textures/sprite.png

const normalizedPath2 = PathUtil.normalize('assets/../../textures/sprite.png');
console.log(normalizedPath2);
// Output: ../textures/sprite.png

const normalizedPath3 = PathUtil.normalize('assets/////textures/sprite.png');
console.log(normalizedPath3);
// Output: assets/textures/sprite.png

const normalizedUrl = PathUtil.normalize('schema://hostname/folder/../file.txt');
console.log(normalizedUrl);
// Output: schema://hostname/file.txt

const resourcePath = new ResourcePath('assets\\icons\\award.png');
const normalizedResource = PathUtil.normalize(resourcePath);
console.log(normalizedResource);
// Output: assets/icons/award.png

separate​

Separates a path into segments. Expects a relative path. If an absolute path is provided, the schema part and hostname are ignored. Can return '..' part/parts at the beginning.

static separate(path:ResourcePathLike):string[]
const urlParts = PathUtil.separate('schema://hostname/folder/file.txt');
console.log(urlParts);
// Output: [ 'folder', 'file.txt' ]

const relativeParts = PathUtil.separate('../../folder/file.txt');
console.log(relativeParts);
// Output: [ '..', '..', 'folder', 'file.txt' ]

const currentDirParts = PathUtil.separate('./folder/file.txt');
console.log(currentDirParts);
// Output: [ 'folder', 'file.txt' ]

const absoluteParts = PathUtil.separate('/folder_1/folder_2/');
console.log(absoluteParts);
// Output: [ 'folder_1', 'folder_2' ]

const filenameParts = PathUtil.separate('file.txt');
console.log(filenameParts);
// Output: [ 'file.txt' ]

relative​

Returns the relative path from one path to another. If the paths are the same, returns an empty string.

static relative(from:ResourcePathLike, path:ResourcePathLike):string
const relativePath = PathUtil.relative('assets/images', 'assets/textures/sprite.png');
console.log(relativePath);
// Output: ../textures/sprite.png

const parentPath = PathUtil.relative('assets/images/icons', 'assets');
console.log(parentPath);
// Output: ../..

const samePath = PathUtil.relative('/', '/');
console.log(samePath);
// Output: (empty string)

const resourcePath1 = new ResourcePath('db://assets/icons');
const resourcePath2 = new ResourcePath('db://assets/atlas/bonus.png');
const relativeResource = PathUtil.relative(resourcePath1, resourcePath2);
console.log(relativeResource);
// Output: ../atlas/bonus.png

split​

Splits a path into parts by the path separator. Does not normalize the path.

static split(path:ResourcePath | OneOrArray<string>):string[]

The method accepts strings, ResourcePath instances, or an array of segments. Arrays are returned without modification.

const segments = PathUtil.split('assets/images/sprite.png');
console.log(segments);
// Output: [ 'assets', 'images', 'sprite.png' ]

const absoluteSegments = PathUtil.split('/assets/images/sprite.png');
console.log(absoluteSegments);
// Output: [ '', 'assets', 'images', 'sprite.png' ]

const untouchedArray = PathUtil.split([ 'assets', 'images', 'sprite.png' ]);
console.log(untouchedArray);
// Output: [ 'assets', 'images', 'sprite.png' ]

const resourceSegments = PathUtil.split(new ResourcePath('db://atlas/bonus/icon.png'));
console.log(resourceSegments);
// Output: [ 'db:', '', 'atlas', 'bonus', 'icon.png' ]

merge​

Merges a sequence of paths into a single path without normalization. The paths are joined by the path separator.

static merge(...paths:ResourcePathLike[]):string
const mergedPath1 = PathUtil.merge('assets', 'images', 'sprite.png');
console.log(mergedPath1);
// Output: assets/images/sprite.png

const mergedPath2 = PathUtil.merge('assets/icons', '../atlas', 'bonus.png');
console.log(mergedPath2);
// Output: assets/icons/../atlas/bonus.png

const resourcePath = new ResourcePath('schema://hostname/folder');
const mergedWithResource = PathUtil.merge(resourcePath, 'file.txt');
console.log(mergedWithResource);
// Output: schema://hostname/folder/file.txt

basename​

Extracts the file or folder name from the provided path.

static basename(path:ResourcePathLike):string
const basename = PathUtil.basename('assets/images/sprite.png');
console.log(basename);
// Output: sprite.png

const basenameWithParams = PathUtil.basename('assets/images/sprite.png?v=1');
console.log(basenameWithParams);
// Output: sprite.png

const folderBasename = PathUtil.basename('/folder_1/folder_2/');
console.log(folderBasename);
// Output: folder_2

const resourcePath = new ResourcePath('db://atlas/bonus/icon.png');
const resourceBasename = PathUtil.basename(resourcePath);
console.log(resourceBasename);
// Output: icon.png

filename​

Extracts the file or folder name from the provided path. In case of a file, the extension is removed.

static filename(path:ResourcePathLike):string
const filename = PathUtil.filename('assets/images/sprite.png');
console.log(filename);
// Output: sprite

const filenameWithParams = PathUtil.filename('assets/images/sprite.png?v=1');
console.log(filenameWithParams);
// Output: sprite

const resourcePath = new ResourcePath('db://atlas/bonus/icon.png');
const resourceFilename = PathUtil.filename(resourcePath);
console.log(resourceFilename);
// Output: icon

params​

Extracts the query params from the provided path. If there are no query params, returns null.

static params(path:ResourcePathLike):URLSearchParams
const params = PathUtil.params('assets/images/sprite.png?v=1&size=large');
console.log(params);
// Output: URLSearchParams { 'v' => '1', 'size' => 'large' }

const withoutParams = PathUtil.params('assets/images/sprite.png');
console.log(withoutParams);
// Output: null

const resourcePath = new ResourcePath('db://atlas/icon.png?locale=en');
const resourceParams = PathUtil.params(resourcePath);
console.log(resourceParams);
// Output: URLSearchParams { 'locale' => 'en' }

extension​

Extracts the extension of the file from the provided path. If there is no extension, returns an empty string.

static extension(path:ResourcePathLike):string
const extension = PathUtil.extension('assets/images/sprite.png');
console.log(extension);
// Output: png

const extensionWithParams = PathUtil.extension('assets/images/sprite.png?v=1');
console.log(extensionWithParams);
// Output: png

const withoutExtension = PathUtil.extension('assets/images/README');
console.log(withoutExtension);
// Output: (empty string)

const resourcePath = new ResourcePath('db://atlas/icon.png?locale=en');
const resourceExtension = PathUtil.extension(resourcePath);
console.log(resourceExtension);
// Output: png