---
sidebar_position: 0
---

# fileSystem

The `sos.fileSystem` API groups together methods for low-level access to the file system. The File System API supports both internal and
external storage.

:::warning Differences between File System API and Offline Cache API
File System directory structure is **PERSISTENT** and is **NOT** automatically deleted through `Applet Reload` power action!
Applet Reload only deletes `/data` directory which is reserved for simplified [Offline Cache API](./offline). Use
`deleteFile()` to clear the device storage file system.
:::

:::info GitHub Example
- [Example usage of File System API in Applet](https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/file-system)
:::

<details>
    <summary>Device File System Capabilities</summary>
		| Capability | Description |
		|:------------|:-------------|
		| `FILE_SYSTEM_INTERNAL_STORAGE` | If device supports internal storage units |
	 	| `FILE_SYSTEM_EXTERNAL_STORAGE` | If device supports connecting external storage units |
		| `FILE_SYSTEM_FILE_CHECKSUM` | If device supports checksum for MD5 or CRC32 hash algorithms |
		| `FILE_SYSTEM_LINK` | If device supports creating hard links to files |
		| `FILE_SYSTEM_CREATE_ARCHIVE` | If device supports creating archives - zip |
		| `FILE_SYSTEM_ARCHIVE_EXTRACT_INFO` | If device supports extracting information about archive files |

		If you want to check if the device supports this capability, use [`sos.display.supports()`](https://developers.signageos.io/sdk/sos/display#supports).
</details>


## Storing files permanently
To allow more low-level file operations, the applet SDK exposes the File System API. Files created using this API are permanent and are only removed on a factory reset or file system wipeout.
The file system is also shared between all applets, which means you cannot rely on any file system structure on startup because a different applet on the device could have saved files you didn't expect.
To mitigate this issue, create a directory for your applet and save all files inside it.

```ts
import sos from '@signageos/front-applet';

sos.onReady(async () => {
	const storageUnits = await sos.fileSystem.listStorageUnits();
	const rootPath = {
		filePath: '', // Empty string is used as an absolute path instead of "/"
		storageUnit: storageUnits.find((s) => !s.removable), // Find internal storage
	};

	// This will return files previous applets saved to the device
	const files = await sos.fileSystem.listFiles(rootPath);
});
```

## Methods

### appendFile()

The `appendFile()` method appends string content to the file specified by `filePath`.
If the file does exist, it is created.

:::note
Only string can be appended to the file. If you want to append binary data, you have to convert it to a string first.
:::

```ts expandable
appendFile(filePath: IFilePath, contents: string): Promise<void>;
// show-more
/**
 * Base File System interface for methods.
 */
interface IFilePath {
    /**
     * Storage unit which is selected for performing file operations.
     */
    storageUnit: IStorageUnit;
    /**
     * File path within the storage unit.
     */
    filePath: string;
}

/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

```

#### Params

| Name       | Type        | Required         | Description                             |
|------------|-------------|------------------|-----------------------------------------|
| `filePath` | `IFilePath` |  <div>Yes</div>  | The path to the file to be appended.    |
| `contents` | `string`    |  <div>Yes</div>  | The content to be appended to the file. |

#### Return value

A promise that resolves when the content is appended successfully.

#### Possible errors


- Error If the parent directory does not exist.
- Error If the `filePath` is a directory.
- Error If the `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
- Error If any error occurs during the append operation on the device.

#### Example

```ts
const filePath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/file.txt',
};

const contents = 'This is the content to append to the file.';
await sos.fileSystem.appendFile(filePath, contents);
```

<Separator />

### copyFile()

The `copyFile()` method creates a copy of file from `sourceFilePath` to `destinationFilePath`.

```ts expandable
copyFile(sourceFilePath: IFilePath, destinationFilePath: IFilePath, options?: ICopyFileOptions): Promise<void>;
// show-more
/**
 * Base File System interface for methods.
 */
interface IFilePath {
    /**
     * Storage unit which is selected for performing file operations.
     */
    storageUnit: IStorageUnit;
    /**
     * File path within the storage unit.
     */
    filePath: string;
}

/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

interface ICopyFileOptions {
    overwrite?: boolean;
}

```

#### Params

| Name                  | Type               | Required         | Description                                                                            |
|-----------------------|--------------------|------------------|----------------------------------------------------------------------------------------|
| `sourceFilePath`      | `IFilePath`        |  <div>Yes</div>  | The path to the file to be copied.                                                     |
| `destinationFilePath` | `IFilePath`        |  <div>Yes</div>  | The path where the file will be copied to.                                             |
| `options`             | `ICopyFileOptions` |  <div>No</div>   | Options for copying the file.                                                          |
| `options.overwrite`   | `boolean`          |  <div>No</div>   | If set to `true`, the method will overwrite the destination file if it already exists. |

#### Return value

A promise that resolves when the file is copied successfully.

#### Possible errors


- Error If the source file does not exist.
- Error If parent of the destination file path does not exist.
- Error If `options` object is not valid.
- Error If any error occurs during the copy operation on the device.

#### Example

```ts
// Copy file from one directory to another and overwrite it if it already exists
const sourceFilePath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/source/file.txt',
};

const destinationFilePath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/destination/file.txt',
};

await sos.fileSystem.copyFile(sourceFilePath, destinationFilePath, { overwrite: true });
```

<Separator />

### createArchive()

The `createArchive()` method creates an archive file from selected files and directories.

:::warning
- Never start OR end the `filePath` with a slash - `/`.
- It is a good practice to check if file exists - `exists()` prior creating it
:::

:::info
- This function is available only on Tizen devices.
- All files are added to the archive based on absolute path from root directory.
:::

```ts expandable
createArchive(archiveFilePath: IFilePath, archiveEntries: IFilePath[]): Promise<void>;
// show-more
/**
 * Base File System interface for methods.
 */
interface IFilePath {
    /**
     * Storage unit which is selected for performing file operations.
     */
    storageUnit: IStorageUnit;
    /**
     * File path within the storage unit.
     */
    filePath: string;
}

/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

```

#### Params

| Name              | Type          | Required         | Description                                           |
|-------------------|---------------|------------------|-------------------------------------------------------|
| `archiveFilePath` | `IFilePath`   |  <div>Yes</div>  | The path where the archive file will be created.      |
| `archiveEntries`  | `IFilePath[]` |  <div>Yes</div>  | An array of file paths to be included in the archive. |

#### Return value

A promise that resolves when the archive file is created successfully.

#### Possible errors


- Error If `archiveFilePath` is not a valid object or does not contain `storageUnit` and `filePath`.
- Error If `archiveEntries` is not a valid array of objects.
- Error If the parent directory of `archiveFilePath` does not exist.
- Error If any of the `archiveEntries` do not exist or are directories.
- Error If creating the archive file fails.
- Error If the platform does not support creating archive files.

#### Example

```ts
const archiveFilePath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/archive.zip',
};

const archiveEntries = [
	{
		storageUnit: internalStorageUnit,
		filePath: 'path/to/file1.txt',
	},
	{
		storageUnit: internalStorageUnit,
		filePath: 'path/to/file2.txt',
	},
	{
		storageUnit: internalStorageUnit,
		filePath: 'path/to/directory1',
	},
];

await sos.fileSystem.createArchive(archiveFilePath, archiveEntries);
```

<Separator />

### createDirectory()

The `createDirectory()` method create a new directory at specified path.

:::warning
- Never start OR end the filePath with a slash - `/`.
- It is a good practice to check if directory exists - `isDirectory()` prior creating it.
:::

```ts expandable
createDirectory(directoryPath: IFilePath): Promise<void>;
// show-more
/**
 * Base File System interface for methods.
 */
interface IFilePath {
    /**
     * Storage unit which is selected for performing file operations.
     */
    storageUnit: IStorageUnit;
    /**
     * File path within the storage unit.
     */
    filePath: string;
}

/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

```

#### Params

| Name            | Type        | Required         | Description                                       |
|-----------------|-------------|------------------|---------------------------------------------------|
| `directoryPath` | `IFilePath` |  <div>Yes</div>  | The path where the new directory will be created. |

#### Return value

A promise that resolves when the directory is created successfully.

#### Possible errors


- Error If `directoryPath` is not a valid object or does not contain `storageUnit` and `filePath`.
- Error If the directory already exists.
- Error If parent directory does not exist.

#### Example

```ts
const internalStorageUnit = (await sos.fileSystem.listInternalStorageUnits())[0];
const directoryPath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/new/directory',
};

await sos.fileSystem.createDirectory(directoryPath);
```

<Separator />

### deleteFile()

The `deleteFile()` method deletes the file specified by `filePath`.

```ts expandable
deleteFile(filePath: IFilePath, recursive: boolean): Promise<void>;
// show-more
/**
 * Base File System interface for methods.
 */
interface IFilePath {
    /**
     * Storage unit which is selected for performing file operations.
     */
    storageUnit: IStorageUnit;
    /**
     * File path within the storage unit.
     */
    filePath: string;
}

/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

```

#### Params

| Name        | Type        | Required         | Description                                                                              |
|-------------|-------------|------------------|------------------------------------------------------------------------------------------|
| `filePath`  | `IFilePath` |  <div>Yes</div>  | The path to the file or directory to be deleted.                                         |
| `recursive` | `boolean`   |  <div>Yes</div>  | If set to `true`, the method will delete the directory and all its contents recursively. |

#### Return value

A promise that resolves when the file is deleted successfully.

#### Possible errors


- Error If `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
- Error If the file does not exist or if `recursive` is set to false and the file path is a directory.
- Error If deleting path does not exist.
- Error When is deleting directory and is not empty (not recursive).

#### Example

```ts
// Delete directory and all files inside
//// First check, if there is such a directory
if (await sos.fileSystem.exists({ storageUnit: internalStorageUnit, filePath: 'test-dir' })) {
    // Delete the directory and all it's content recursively
    await sos.fileSystem.deleteFile({ storageUnit: internalStorageUnit, filePath: 'test-dir' }, true);
}

// Delete file
//// First check, if there is such a file
if (await sos.fileSystem.exists({ storageUnit: internalStorageUnit, filePath: 'test-dir/downloaded-file.png' })) {
    // Delete the file
    await sos.fileSystem.deleteFile({ storageUnit: internalStorageUnit, filePath: 'test-dir/downloaded-file.png' }, false);
}
```

<Separator />

### downloadFile()

The `downloadFile()` method download a file from `sourceUri` and saves it to the specified path. If the file already exists, the file will be
overwritten. Optionally, headers for the download request may be specified.

:::danger
For every download request, our Core Apps makes HEAD request for `content-length` header on that downloaded file. It's due to determining if device has enough space to download the file.
:::

#### Encoding
All downloads respect a standard of `Encoding` with optional compression of files. See [Mozilla standard Accept Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) and [Content Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding).

Download file method is always sending optional following headers:
```
Accept-Encoding: gzip
Accept-Encoding: compress
Accept-Encoding: deflate
Accept-Encoding: br
Accept-Encoding: identity
Accept-Encoding: *
```

If the server understands the `Encoding` standard, it compresses files using `gzip` algorithm before the files are sent to the client. If so, the response will contain the following headers:
```
Content-Encoding: gzip
Content-Encoding: compress
Content-Encoding: deflate
Content-Encoding: br
```
So the data communication is compressed under the hood. The client will automatically decompress data before it's saved to a specified location path. So from JS API point of view, there is no requirement to decompress data by itself.

The standard is supported on all following platforms:

- WebOS 3+
- Tizen 2.4+
- Brightsign
- Raspberry Pi
- Windows

```ts expandable
downloadFile(filePath: IFilePath, sourceUri: string, headers?: IHeaders): Promise<void>;
// show-more
/**
 * Base File System interface for methods.
 */
interface IFilePath {
    /**
     * Storage unit which is selected for performing file operations.
     */
    storageUnit: IStorageUnit;
    /**
     * File path within the storage unit.
     */
    filePath: string;
}

/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

interface IHeaders {
    [key: string]: string;
}

```

#### Params

| Name        | Type        | Required         | Description                                                                                                                     |
|-------------|-------------|------------------|---------------------------------------------------------------------------------------------------------------------------------|
| `filePath`  | `IFilePath` |  <div>Yes</div>  | The path where the downloaded file will be saved.                                                                               |
| `sourceUri` | `string`    |  <div>Yes</div>  | The URI of the file to be downloaded.                                                                                           |
| `headers`   | `IHeaders`  |  <div>No</div>   | Key, value pairs of HTTP headers to send along with the request. Used when the target file is protected by a password or if any |

#### Return value

A promise that resolves when the file is downloaded successfully.

#### Possible errors


- Error If `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
- Error If `sourceUri` is not a valid URI.
- Error If `headers` is not a valid object.
- Error If the parent directory of `filePath` does not exist.
- Error If the network request fails.

#### Example

```ts
const filePath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/downloaded/file.zip',
};
const sourceUri = 'https://example.com/path/to/file.zip';
const headers = {
	'Authorization': 'Bearer your_token_here',
};
await sos.fileSystem.downloadFile(filePath, sourceUri, headers);
```

<Separator />

### exists()

The `exists()` method checks whether a file or directory exists.

```ts expandable
exists(filePath: IFilePath): Promise<boolean>;
// show-more
/**
 * Base File System interface for methods.
 */
interface IFilePath {
    /**
     * Storage unit which is selected for performing file operations.
     */
    storageUnit: IStorageUnit;
    /**
     * File path within the storage unit.
     */
    filePath: string;
}

/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

```

#### Params

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

#### Return value

A promise that resolves to `true` if the file or directory exists, `false` otherwise.

#### Possible errors


- Error If the `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
- Error If any error occurs during the existence check operation on the device.

#### Example

```ts
const filePath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/file.txt',
};

const fileExists = await sos.fileSystem.exists(filePath);
console.log(`File exists: ${fileExists}`); // Prints true if the file exists, false otherwise
```

<Separator />

### extractFile()

The `extractFile()` method extract (recursively) the archive file at `archiveFilePath` into a new file specified by `destinationDirectoryPath`.

:::note
- The directory/folder you are extracting your ZIP file into has to be created BEFORE you start extracting the ZIP.
- Only supported extract method is `zip`.
:::

```ts expandable
extractFile(archiveFilePath: IFilePath, destinationDirectoryPath: IFilePath, method: ExtractMethodType): Promise<void>;
// show-more
/**
 * Base File System interface for methods.
 */
interface IFilePath {
    /**
     * Storage unit which is selected for performing file operations.
     */
    storageUnit: IStorageUnit;
    /**
     * File path within the storage unit.
     */
    filePath: string;
}

/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

/**
 * Allowed extract method types for `extractFile()` operations.
 */
type ExtractMethodType = 'zip' | AnyString;

type AnyString = string & {};

```

#### Params

| Name                       | Type                | Required         | Description                                                           |
|----------------------------|---------------------|------------------|-----------------------------------------------------------------------|
| `archiveFilePath`          | `IFilePath`         |  <div>Yes</div>  | The path to the archive file to be decompressed.                      |
| `destinationDirectoryPath` | `IFilePath`         |  <div>Yes</div>  | The path to the directory where the decompressed files will be saved. |
| `method`                   | `ExtractMethodType` |  <div>Yes</div>  | Extract method to use for extracting, e.g. 'zip'.                     |

#### Possible errors


- Error If the archive file path does not exist.
- Error If it is not a valid archive file.
- Error If destination directory does not exist.

#### Example

```ts
const archiveFilePath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/archive.zip',
};

const destinationDirectoryPath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/destination/directory',
};

await sos.fileSystem.extractFile(archiveFilePath, destinationDirectoryPath, 'zip');
```

<Separator />

### getFile()

The `getFile()` method returns runtime information about a file path, such as local url, last modified date or size.

:::warning
Return statement is a dynamic object! It has to be always generated and retrieved by this JS API, as the values in localUri differ platform by platform. Never generate the object manually. `{"localUri":"file://internal/path/to/file.txt"}` is for demonstration only.
:::

```ts expandable
getFile(filePath: IFilePath): Promise<IFile | null>;
// show-more
/**
 * Properties of returned file from File System API.
 */
interface IFile extends IFilePath {
    localUri: string;
    /**
     * Image thumbnail URI of the file, which can be used to display a preview of the file.
     * Note: Supported only on Linux.
     */
    imageThumbnailUriTemplate?: string;
    /**
     * Video thumbnail URI of the file, which can be used to display a preview of the file.
     * Note: Supported only on Linux.
     */
    videoThumbnailUriTemplate?: string;
    /**
     * Date and time when the file was created in milliseconds since the epoch.
     */
    createdAt?: number;
    lastModifiedAt?: number;
    sizeBytes?: number;
    mimeType?: string;
}

/**
 * Base File System interface for methods.
 */
interface IFilePath {
    /**
     * Storage unit which is selected for performing file operations.
     */
    storageUnit: IStorageUnit;
    /**
     * File path within the storage unit.
     */
    filePath: string;
}

/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

```

#### Params

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

#### Return value

A promise that resolves to the file information or `null` if the file does not exist.

#### Possible errors


- Error If the `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
- Error If the file is a directory.
- Error If any error occurs during the retrieval operation on the device.

#### Example

```ts
// Get file information
const filePath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/file.txt',
};

const fileInfo = await sos.fileSystem.getFile(filePath);
console.log(JSON.stringify(fileInfo)); // Prints the file information
console.log(fileInfo.localUri); // Prints the local URI of the file
```

<Separator />

### getFileChecksum()

The `getChecksumFile()` method computes a checksum of the file specified by `filePath`.

:::warning Tizen limitation
If you are about to use the MD5 file validation it will automatically return on any Samsung Tizen - 2.4, 3.0 and 4.0.
Reason: MD5 file checksum is not available on any Tizen displays due to the Samsung restriction.
:::

```ts expandable
getFileChecksum(filePath: IFilePath, hashType: HashAlgorithm): Promise<string>;
// show-more
/**
 * Base File System interface for methods.
 */
interface IFilePath {
    /**
     * Storage unit which is selected for performing file operations.
     */
    storageUnit: IStorageUnit;
    /**
     * File path within the storage unit.
     */
    filePath: string;
}

/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

/**
 * Represents the supported hash algorithms by Core Apps.
 */
type HashAlgorithm = 'md5' | 'crc32' | AnyString;

type AnyString = string & {};

```

#### Params

| Name       | Type            | Required         | Description                                                   |
|------------|-----------------|------------------|---------------------------------------------------------------|
| `filePath` | `IFilePath`     |  <div>Yes</div>  | The path to the file for which the checksum will be computed. |
| `hashType` | `HashAlgorithm` |  <div>Yes</div>  | The type of hash algorithm to use for computing the checksum. |

#### Return value

A promise that resolves to the computed checksum of the file.

#### Possible errors


- Error If `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
- Error If `hashType` is not a valid type or string.
- Error If the file does not exist.
- Error If `filepath` it is a directory

#### Example

```ts
const filePath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/file.txt',
};

const checksum = await sos.fileSystem.getFileChecksum(filePath, 'md5');
console.log(`Checksum of the file: ${checksum}`);
```

<Separator />

### isDirectory()

The `isDirectory()` method checks whether the file path points to a directory.

```ts expandable
isDirectory(filePath: IFilePath): Promise<boolean>;
// show-more
/**
 * Base File System interface for methods.
 */
interface IFilePath {
    /**
     * Storage unit which is selected for performing file operations.
     */
    storageUnit: IStorageUnit;
    /**
     * File path within the storage unit.
     */
    filePath: string;
}

/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

```

#### Params

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

#### Return value

A promise that resolves to `true` if the file path is a directory, `false` otherwise.

#### Possible errors


- Error If `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
- Error If the file path does not exist.

#### Example

```ts
const filePath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/directory',
};
const isDir = await sos.fileSystem.isDirectory(filePath);
if (isDir) {
	console.log('The file path is a directory.');
} else {
	console.log('The file path is not a directory.');
}
```

<Separator />

### link()

The `link()` method creates a symbolic link from `sourceFilePath` (existing path) to `destinationFilePath` (new path).

:::note
This method is only available on Linux devices.
:::

```ts expandable
link(sourceFilePath: IFilePath, destinationFilePath: IFilePath): Promise<void>;
// show-more
/**
 * Base File System interface for methods.
 */
interface IFilePath {
    /**
     * Storage unit which is selected for performing file operations.
     */
    storageUnit: IStorageUnit;
    /**
     * File path within the storage unit.
     */
    filePath: string;
}

/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

```

#### Params

| Name                  | Type        | Required         | Description                                                          |
|-----------------------|-------------|------------------|----------------------------------------------------------------------|
| `sourceFilePath`      | `IFilePath` |  <div>Yes</div>  | The path to the existing file or directory that you want to link to. |
| `destinationFilePath` | `IFilePath` |  <div>Yes</div>  | The path where the symbolic link will be created.                    |

#### Return value

A promise that resolves when the symbolic link is created successfully.

#### Possible errors


- Error If `sourceFilePath` or `destinationPath` is not a valid object or does not contain `storageUnit` and `filePath`.
- Error If the `sourceFilePath` does not exist or if the `destinationFilePath` already exists.
- Error The platform does not support linking directories.

#### Example

```ts
const internalStorageUnit = (await sos.fileSystem.listInternalStorageUnits())[0];
const sourceFilePath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/existing/file.txt',
};

const destinationFilePath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/symlink/file_link.txt',
};

await sos.fileSystem.link(sourceFilePath, destinationFilePath);
```

<Separator />

### listFiles()

The `listFiles()` method lists all files and directories in the specified path (nested files are not included).

```ts expandable
listFiles(directoryPath: IFilePath): Promise<IFilePath[]>;
// show-more
/**
 * Base File System interface for methods.
 */
interface IFilePath {
    /**
     * Storage unit which is selected for performing file operations.
     */
    storageUnit: IStorageUnit;
    /**
     * File path within the storage unit.
     */
    filePath: string;
}

/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

```

#### Params

| Name            | Type        | Required         | Description                                           |
|-----------------|-------------|------------------|-------------------------------------------------------|
| `directoryPath` | `IFilePath` |  <div>Yes</div>  | The path to the directory where files will be listed. |

#### Return value

A promise that resolves to an array of file paths in the specified directory.

#### Possible errors


- Error If `directoryPath` is not a valid object or does not contain `storageUnit` and `filePath`.
- Error If the path does not exist, or it is a file.

#### Example

```ts
// List files in the root directory of the internal storage unit
const internalStorageUnit = (await sos.fileSystem.listInternalStorageUnits())[0];
const directoryPath = {
	storageUnit: internalStorageUnit,
	filePath: '', // Empty string is used as an absolute path instead of "/"
};

const files = await sos.fileSystem.listFiles(directoryPath);
console.log('Files in the root directory:', files.length);
files.forEach((file) => {
	console.log(`File: ${file.filePath}`);
});
```

<Separator />

### listInternalStorageUnits()

A shorthand method for listing only the internal storage units (i.e., those with the `removable: false`). The capacity values are in bytes.

```ts expandable
listInternalStorageUnits(): Promise<IStorageUnit[]>;
// show-more
/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

```

#### Return value

An array of internal storage units available on the device.

#### Example

```ts
// List internal storage units
const internalStorageUnits = await sos.fileSystem.listInternalStorageUnits();
internalStorageUnits.forEach((storageUnit) => {
  console.log(`Storage Unit Type: ${storageUnit.type}`);
  console.log(`Capacity: ${storageUnit.capacity} bytes`);
  console.log(`Free Space: ${storageUnit.freeSpace} bytes`);
  console.log(`Usable Space: ${storageUnit.usableSpace} bytes`);
});
```

<Separator />

### listStorageUnits()

The `listStorageUnits()` method lists all available storage units. All devices always have one internal storage device (with
`removable: false`) and zero or more external devices. The capacity values are in bytes.

:::note
This is a mandatory method that is required for all the other File System APIs. The other APIs require a storageUnit object that is retrieved from this method to manipulate with files on a correct storage location (internal/external).
:::

:::warning
`storageUnit` is a dynamic object! It has to be always generated and retrieved by this JS API, as the values in type differ platform by platform. Never generate the object manually. `{"type":"internal"}` is for demonstration only.
:::

```ts expandable
listStorageUnits(): Promise<IStorageUnit[]>;
// show-more
/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

```

#### Return value

An array of storage units available on the device.

#### Possible errors

InternalFileSystemError Unexpected error occurred when listing storage units.

#### Example

```ts
// Storage units are equivalent to disk volumes (C:, D: etc on Windows; /mnt/disc1, /mnt/disc2 on Unix)
const storageUnits = await sos.fileSystem.listStorageUnits();
const externalStorageUnits = storageUnits.filter((storageUnit) => storageUnit.removable);
externalStorageUnits.forEach((storageUnit) => {
 console.log(`Storage Unit Type: ${storageUnit.type}`);
console.log(`Capacity: ${storageUnit.capacity} bytes`);
});
```

<Separator />

### moveFile()

The `moveFile()` method moves a file from `sourceFilePath` to `destinationFilePath`.

```ts expandable
moveFile(sourceFilePath: IFilePath, destinationFilePath: IFilePath, options?: IMoveFileOptions): Promise<void>;
// show-more
/**
 * Base File System interface for methods.
 */
interface IFilePath {
    /**
     * Storage unit which is selected for performing file operations.
     */
    storageUnit: IStorageUnit;
    /**
     * File path within the storage unit.
     */
    filePath: string;
}

/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

interface IMoveFileOptions {
    overwrite?: boolean;
}

```

#### Params

| Name                  | Type               | Required         | Description                                                                            |
|-----------------------|--------------------|------------------|----------------------------------------------------------------------------------------|
| `sourceFilePath`      | `IFilePath`        |  <div>Yes</div>  | The path to the file to be moved.                                                      |
| `destinationFilePath` | `IFilePath`        |  <div>Yes</div>  | The path where the file will be moved to.                                              |
| `options`             | `IMoveFileOptions` |  <div>No</div>   | Options for moving the file.                                                           |
| `options.overwrite`   | `boolean`          |  <div>No</div>   | If set to `true`, the method will overwrite the destination file if it already exists. |

#### Return value

A promise that resolves when the file is moved successfully.

#### Possible errors


- Error If the source file does not exist or parent of the destination file path does not exist.
- Error If the `options.overwrite` is not set and the destination file path already exists.
- Error If deleting path does not exist.
- Error If any error occurs during the move operation on the device.

#### Example

```ts
// Move file from one directory to another and overwrite it if it already exists
const sourceFilePath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/source/file.txt',
};

const destinationFilePath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/destination/file.txt',
};

await sos.fileSystem.moveFile(sourceFilePath, destinationFilePath, { overwrite: true });
```

<Separator />

### onStorageUnitsChanged()

The `onStorageUnitsChanged()` method sets up a listener, which is called whenever the list of storage units changes.

```ts expandable
onStorageUnitsChanged(listener: () => void): void;
```

#### Params

| Name       | Type         | Required         | Description                                                       |
|------------|--------------|------------------|-------------------------------------------------------------------|
| `listener` | `() => void` |  <div>Yes</div>  | The listener function to be called when the storage units change. |

#### Possible errors

Error If `listener` is not a valid function.

<Separator />

### readFile()

The `readFile()` method returns content of the file specified by `filePath`.
The file has to be a text file, otherwise the content will be mangled.

```ts expandable
readFile(filePath: IFilePath): Promise<string>;
// show-more
/**
 * Base File System interface for methods.
 */
interface IFilePath {
    /**
     * Storage unit which is selected for performing file operations.
     */
    storageUnit: IStorageUnit;
    /**
     * File path within the storage unit.
     */
    filePath: string;
}

/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

```

#### Params

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

#### Return value

A promise that resolves to the content of the file.

#### Possible errors


- Error If the file does not exist.
- Error If the `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
- Error If the file is a directory.
- Error If any error occurs during the read operation on the device.

#### Example

```ts
const filePath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/file.txt',
};

const fileContent = await sos.fileSystem.readFile(filePath);
console.log(`Content of the file: ${fileContent}`);
```

<Separator />

### removeAllListeners()

The `removeAllListeners()` method removes all listeners, previously added by `onStorageUnitsChanged()`

```ts expandable
removeAllListeners(): void;
```

<Separator />

### removeStorageUnitsChangedListener()

The `removeStorageUnitsChangedListener()` method removes a listener, previously added by `onStorageUnitsChanged()`

```ts expandable
removeStorageUnitsChangedListener(listener: () => void): void;
```

<Separator />

### wipeout()

The `wipeout()` method is used to wipe out all data from the file system.

:::danger
- Ensure that function is called only once, otherwise it will wipe out the file system again on applet or device start!
- This function is clearing internal file system storage, cache storage and cookies. Local storage will not be cleared.
:::

```ts expandable
wipeout(): Promise<void>;
```

#### Return value

A promise that resolves when the wipeout is complete.

#### Example

```ts
await sos.fileSystem.wipeout().then(() => {
	console.log('File system wiped out successfully.');
	await sos.management.power.systemReboot(); // Reboot the device after wipeout
}).catch((error) => {
	console.error('Error wiping out file system:', error);
});
```

<Separator />

### writeFile()

The `writeFile()` method writes string content to the file specified by `filePath`. If the file does exist, it is created.

```ts expandable
writeFile(filePath: IFilePath, contents: string): Promise<void>;
// show-more
/**
 * Base File System interface for methods.
 */
interface IFilePath {
    /**
     * Storage unit which is selected for performing file operations.
     */
    storageUnit: IStorageUnit;
    /**
     * File path within the storage unit.
     */
    filePath: string;
}

/**
 * File System Storage Unit returned by the File System API.
 */
interface IStorageUnit {
    /**
     * The type of the storage unit, e.g., "internal" or "external".
     */
    type: string;
    /**
     * The total capacity of the storage unit in bytes.
     */
    capacity: number;
    /**
     * The amount of free space available in the storage unit in bytes.
     */
    freeSpace: number;
    /**
     * The amount of usable space in the storage unit in bytes.
     */
    usableSpace: number;
    /**
     * Indicates whether the storage unit is removable (e.g., an SD card).
     */
    removable: boolean;
}

```

#### Params

| Name       | Type        | Required         | Description                            |
|------------|-------------|------------------|----------------------------------------|
| `filePath` | `IFilePath` |  <div>Yes</div>  | The path to the file to be written.    |
| `contents` | `string`    |  <div>Yes</div>  | The content to be written to the file. |

#### Return value

A promise that resolves when the content is written successfully.

#### Possible errors


- Error If the parent directory does not exist or the `filePath` is a directory.
- Error If the `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
- Error If any error occurs during the write operation on the device.

#### Example

```ts
const filePath = {
	storageUnit: internalStorageUnit,
	filePath: 'path/to/file.txt',
};

const contents = 'This is the content to write to the file.';
await sos.fileSystem.writeFile(filePath, contents);
```

## API Example

```ts
import { sos, fpath } from '@signageos/front-applet';
import { IFilePath } from '@signageos/front-applet/es6/FrontApplet/FileSystem/types';

void sos.onReady(async () => {
	const [internal] = await sos.fileSystem.listInternalStorageUnits();

	const root: IFilePath = {
		storageUnit: internal,
		filePath: '', // empty string points to root directory
	};

	// list files in the root directory
	const contents = await sos.fileSystem.listFiles(root);

	// print files from the root directory
	for (const entries of contents) {
		if (await sos.fileSystem.isDirectory(entries)) {
			console.log(`${entries.filePath} (directory)`);
		} else {
			console.log(`${entries.filePath} (file)`);
		}
	}

	// write data into a file
	const writePath = fpath.join(root, 'value.json');
	await sos.fileSystem.writeFile(writePath, JSON.stringify({ data: 'Lorem ipsum dolor sit amet' }));

	// download a file from the internet and play it
	const downloadPath = fpath.join(root, 'video.mp4');
	await sos.fileSystem.downloadFile(
		downloadPath,
		'https://static.signageos.io/assets/test-videos-03_AME/video-test-03_15s_1920x1080_2fe7b039750a134aeac1c0a515710007.mp4',
	);
	const file = await sos.fileSystem.getFile(downloadPath);

	if (file) {
		await sos.video.prepare(file.filePath, 0, 0, 1920, 1080);
		await sos.video.play(file.filePath, 0, 0, 1920, 1080);
	}
});

```