fpath

fpath utility mirrors node path module, but accepts IFilePath type instead of strings. It is useful when working with sos.fileSystem.

Not implemented functions:

- `format()`
- `matchesGlob()`
- `parse()`
- `relative()`

import { sos, fpath } from "@signageos/front-applet";

const [internal] = await sos.fileSystem.listInternalStorageUnits();
const rootPath = {
	filePath: '', // Empty string is used as an absolute path instead of "/"
	storageUnit: internal
};

// list saved files in videos/2025-05-19/ directory
const videos = await sos.fileSystem.listFiles(
 fpath.join(rootPath, "videos", "2025-05-19"),
);

Properties

path

Underlying path polyfill

path: path.Path;

sep

Separator used for joining path segments

sep: string;

Methods

basename()

Return the last portion of path, since it is not a valid path, a string is returned.

basename(filePath: IFilePath, suffix?: string): string;

Params

Name	Type	Required	Description
filePath	IFilePath	Yes	The file path to extract the base name from.
suffix	string	No	An optional suffix to remove from the result.

Return value

The last portion of path, with suffix removed if it is provided and present in the path.

Example

const path = { filePath: "images/picture.png", storageUnit: ... };
fpath.basename(path); // "picture.png"

concat()

Concatenate filePath with paths without adding separator.

concat(filePath: IFilePath, ...paths: string[]): IFilePath;

Params

Name	Type	Required	Description
filePath	IFilePath	Yes	The file path to concatenate to.
paths	string[]	Yes	Strings to concatenate.

Return value

New file path with paths concatenated to it.

Example

const path = { filePath: "uploads/archive.tar", storageUnit: ... };
fpath.concat(path, "_extracted"); // { filePath: "uploads/archive.tar_extracted", storageUnit: ... }

dirname()

Removes the last portion of path, returning the parent directory of the path. Ignores trailing slashes

dirname(filePath: IFilePath): IFilePath;

Params

Name	Type	Required	Description
filePath	IFilePath	Yes	The file path to get the directory from.

Return value

The parent directory of the path, with the same storage unit.

Example

const path = { filePath: "images/picture.png", storageUnit: ... };
fpath.dirname(path); // { filePath: "images", storageUnit: ... }

extname()

Returns extension of the path, from the last period, including the period.

extname(filePath: IFilePath): string;

Params

Name	Type	Required	Description
filePath	IFilePath	Yes	The file path to extract the extension from.

Return value

The extension of the path, from the last period, including the period.

Example

const path = { filePath: "images/picture.png", storageUnit: ... };
fpath.dirname(path); // .png

isAbsolute()

Always returns true, because all file paths are absolute

isAbsolute(_: IFilePath): boolean;

Params

Name	Type	Required	Description
_	IFilePath	Yes	The file path to check.

join()

Returns new filePath with paths appended to it and normalized (resolved . and ..)

join(filePath: IFilePath, ...paths: string[]): IFilePath;

Params

Name	Type	Required	Description
filePath	IFilePath	Yes	The base file path.
paths	string[]	Yes	Path segments to append.

Return value

New file path with paths appended to it and normalized.

Example

const path = { filePath: "images", storageUnit: ... };
fpath.join(path, "racoons", ".", "picture.png"); // { filePath: "images/racoons/picture.png", storageUnit: ... }

normalize()

Resolves . and .. in the path and removes multiple slashes.

normalize(filePath: IFilePath): IFilePath;

Params

Name	Type	Required	Description
filePath	IFilePath	Yes	The file path to normalize.

Return value

Normalized file path.

Example

const path = { filePath: "images//test/../test2/./", storageUnit: ... };
fpath.normalize(path); // { filePath: "images/test2/", storageUnit: ... }

resolve()

Works like fpath.join(), but if any of the paths is an absolute path, it will be resolved to the root of the storage unit instead of the root of the file system.

resolve(filePath: IFilePath, ...paths: string[]): IFilePath;

Params

Name	Type	Required	Description
filePath	IFilePath	Yes	The base file path.
paths	string[]	Yes	Path segments to resolve.

Return value

New file path with paths resolved to it.

safeJoin()

Similar to fpath.join(), but resulting path will always be subdirectory of base.

safeJoin(base: IFilePath, ...paths: string[]): IFilePath;

Params

Name	Type	Required	Description
base	IFilePath	Yes	The base file path that the result will always be a subdirectory of.
paths	string[]	Yes	Path segments to append.

Return value

New file path with paths appended to it, normalized and guaranteed to be a subdirectory of base.

Example

const path = { filePath: "uploads/userA", storageUnit: ... };
fpath.safeJoin(path, "..", "userB", "picture.png"); // { filePath: "uploads/userA/userB/picture.png", storageUnit: ... }

stringify()

Convert filePath to string, this string is not guaranteed to be unique and should be only used for debugging/logging.

stringify(filePath: IFilePath): string;

Params

Name	Type	Required	Description
filePath	IFilePath	Yes	The file path to convert to string.

Return value

The string representation of the file path.