@signageos/front-applet 8.5.1 → 8.5.3

package/docs/fpath/index.md

@@ -1,19 +1,49 @@
 ---
-sidebar_position: 0
+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: import("path-browserify").Path;
+path: path.Path;
 ```
 
 ### sep
 
+Separator used for joining path segments
+
 ```ts expandable
 sep: string;
 ```
@@ -22,78 +52,658 @@ sep: string;
 
 ### basename()
 
+Return the last portion of path, since it is not a valid path, a string is returned.
+
 ```ts expandable
-basename(filePath: import("./FrontApplet/FileSystem/types").IFilePath, suffix?: string): string;
+basename(filePath: IFilePath, suffix?: string): 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 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: import("./FrontApplet/FileSystem/types").IFilePath, ...paths: string[]): import("./FrontApplet/FileSystem/types").IFilePath;
+concat(filePath: IFilePath, ...paths: string[]): 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                      |
+|------------|-------------|------------------|----------------------------------|
+| `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: import("./FrontApplet/FileSystem/types").IFilePath): import("./FrontApplet/FileSystem/types").IFilePath;
+dirname(filePath: IFilePath): 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                              |
+|------------|-------------|------------------|------------------------------------------|
+| `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: import("./FrontApplet/FileSystem/types").IFilePath): string;
+extname(filePath: IFilePath): 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 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(_: import("./FrontApplet/FileSystem/types").IFilePath): boolean;
+isAbsolute(_: IFilePath): 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             |
+|------|-------------|------------------|-------------------------|
+| `_`  | `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: import("./FrontApplet/FileSystem/types").IFilePath, ...paths: string[]): import("./FrontApplet/FileSystem/types").IFilePath;
+join(filePath: IFilePath, ...paths: string[]): 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              |
+|------------|-------------|------------------|--------------------------|
+| `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: import("./FrontApplet/FileSystem/types").IFilePath): import("./FrontApplet/FileSystem/types").IFilePath;
+normalize(filePath: IFilePath): 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                 |
+|------------|-------------|------------------|-----------------------------|
+| `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: import("./FrontApplet/FileSystem/types").IFilePath, ...paths: string[]): import("./FrontApplet/FileSystem/types").IFilePath;
+resolve(filePath: IFilePath, ...paths: string[]): 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               |
+|------------|-------------|------------------|---------------------------|
+| `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: import("./FrontApplet/FileSystem/types").IFilePath, ...paths: string[]): import("./FrontApplet/FileSystem/types").IFilePath;
+safeJoin(base: IFilePath, ...paths: string[]): 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                                                          |
+|---------|-------------|------------------|----------------------------------------------------------------------|
+| `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: import("./FrontApplet/FileSystem/types").IFilePath): string;
-```
+stringify(filePath: IFilePath): 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 file path to convert to string. |
+
+#### Return value
+
+The string representation of the file path.