---
sidebar_position: 99
---

# fpath

`fpath` utility mirrors node [path](https://nodejs.org/docs/latest/api/path.html)
module, but accepts IFilePath type instead of strings. It is useful when
working with [sos.fileSystem](/sdk/sos/fileSystem).

:::info Not implemented functions:
	- `format()`
	- `matchesGlob()`
	- `parse()`
	- `relative()`
:::

```ts
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

```ts expandable
path: path.Path;
```

### sep

Separator used for joining path segments

```ts expandable
sep: string;
```

## Methods

### basename()

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

```ts expandable
basename(filePath: IFilePath, suffix?: string): string;
// show-more
interface IFilePath {
    storageUnit: IStorageUnit;
    filePath: string;
}

interface IStorageUnit {
    type: string;
    capacity: number;
    freeSpace: number;
    usableSpace: number;
    removable: boolean;
}

```

#### Params

| Name       | Type        | Required         | Description                                   |
|------------|-------------|------------------|-----------------------------------------------|
| `filePath` | `IFilePath` |  <div>Yes</div>  | The file path to extract the base name from.  |
| `suffix`   | `string`    |  <div>No</div>   | 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

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

<Separator />

### concat()

Concatenate filePath with paths without adding separator.

```ts expandable
concat(filePath: IFilePath, ...paths: string[]): IFilePath;
// show-more
interface IFilePath {
    storageUnit: IStorageUnit;
    filePath: string;
}

interface IStorageUnit {
    type: string;
    capacity: number;
    freeSpace: number;
    usableSpace: number;
    removable: boolean;
}

```

#### Params

| Name       | Type        | Required         | Description                      |
|------------|-------------|------------------|----------------------------------|
| `filePath` | `IFilePath` |  <div>Yes</div>  | The file path to concatenate to. |
| `paths`    | `string[]`  |  <div>Yes</div>  | Strings to concatenate.          |

#### Return value

New file path with paths concatenated to it.

#### Example

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

<Separator />

### dirname()

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

```ts expandable
dirname(filePath: IFilePath): IFilePath;
// show-more
interface IFilePath {
    storageUnit: IStorageUnit;
    filePath: string;
}

interface IStorageUnit {
    type: string;
    capacity: number;
    freeSpace: number;
    usableSpace: number;
    removable: boolean;
}

```

#### Params

| Name       | Type        | Required         | Description                              |
|------------|-------------|------------------|------------------------------------------|
| `filePath` | `IFilePath` |  <div>Yes</div>  | The file path to get the directory from. |

#### Return value

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

#### Example

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

<Separator />

### extname()

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

```ts expandable
extname(filePath: IFilePath): string;
// show-more
interface IFilePath {
    storageUnit: IStorageUnit;
    filePath: string;
}

interface IStorageUnit {
    type: string;
    capacity: number;
    freeSpace: number;
    usableSpace: number;
    removable: boolean;
}

```

#### Params

| Name       | Type        | Required         | Description                                  |
|------------|-------------|------------------|----------------------------------------------|
| `filePath` | `IFilePath` |  <div>Yes</div>  | The file path to extract the extension from. |

#### Return value

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

#### Example

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

<Separator />

### isAbsolute()

Always returns true, because all file paths are absolute

```ts expandable
isAbsolute(_: IFilePath): boolean;
// show-more
interface IFilePath {
    storageUnit: IStorageUnit;
    filePath: string;
}

interface IStorageUnit {
    type: string;
    capacity: number;
    freeSpace: number;
    usableSpace: number;
    removable: boolean;
}

```

#### Params

| Name | Type        | Required         | Description             |
|------|-------------|------------------|-------------------------|
| `_`  | `IFilePath` |  <div>Yes</div>  | The file path to check. |

<Separator />

### join()

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

```ts expandable
join(filePath: IFilePath, ...paths: string[]): IFilePath;
// show-more
interface IFilePath {
    storageUnit: IStorageUnit;
    filePath: string;
}

interface IStorageUnit {
    type: string;
    capacity: number;
    freeSpace: number;
    usableSpace: number;
    removable: boolean;
}

```

#### Params

| Name       | Type        | Required         | Description              |
|------------|-------------|------------------|--------------------------|
| `filePath` | `IFilePath` |  <div>Yes</div>  | The base file path.      |
| `paths`    | `string[]`  |  <div>Yes</div>  | Path segments to append. |

#### Return value

New file path with paths appended to it and normalized.

#### Example

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

<Separator />

### normalize()

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

```ts expandable
normalize(filePath: IFilePath): IFilePath;
// show-more
interface IFilePath {
    storageUnit: IStorageUnit;
    filePath: string;
}

interface IStorageUnit {
    type: string;
    capacity: number;
    freeSpace: number;
    usableSpace: number;
    removable: boolean;
}

```

#### Params

| Name       | Type        | Required         | Description                 |
|------------|-------------|------------------|-----------------------------|
| `filePath` | `IFilePath` |  <div>Yes</div>  | The file path to normalize. |

#### Return value

Normalized file path.

#### Example

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

<Separator />

### 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.

```ts expandable
resolve(filePath: IFilePath, ...paths: string[]): IFilePath;
// show-more
interface IFilePath {
    storageUnit: IStorageUnit;
    filePath: string;
}

interface IStorageUnit {
    type: string;
    capacity: number;
    freeSpace: number;
    usableSpace: number;
    removable: boolean;
}

```

#### Params

| Name       | Type        | Required         | Description               |
|------------|-------------|------------------|---------------------------|
| `filePath` | `IFilePath` |  <div>Yes</div>  | The base file path.       |
| `paths`    | `string[]`  |  <div>Yes</div>  | Path segments to resolve. |

#### Return value

New file path with paths resolved to it.

<Separator />

### safeJoin()

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

```ts expandable
safeJoin(base: IFilePath, ...paths: string[]): IFilePath;
// show-more
interface IFilePath {
    storageUnit: IStorageUnit;
    filePath: string;
}

interface IStorageUnit {
    type: string;
    capacity: number;
    freeSpace: number;
    usableSpace: number;
    removable: boolean;
}

```

#### Params

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

#### Return value

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

#### Example

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

<Separator />

### stringify()

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

```ts expandable
stringify(filePath: IFilePath): string;
// show-more
interface IFilePath {
    storageUnit: IStorageUnit;
    filePath: string;
}

interface IStorageUnit {
    type: string;
    capacity: number;
    freeSpace: number;
    usableSpace: number;
    removable: boolean;
}

```

#### Params

| Name       | Type        | Required         | Description                         |
|------------|-------------|------------------|-------------------------------------|
| `filePath` | `IFilePath` |  <div>Yes</div>  | The file path to convert to string. |

#### Return value

The string representation of the file path.