Cheerp x idb device (#211)

Author: AtibQur

sites/cheerpx/src/content/docs/11-guides/File-System-support.md

@@ -133,11 +133,11 @@ For a full server setup and additional details, check our [basic server guide](/
 
 ## IDBDevice
 
-IDBDevice provides a persistent, read-write filesystem using the browser's IndexedDB. It's ideal for storing data that should persist between sessions.
+[`IDBDevice`](/docs/reference/CheerpX.IDBDevice) provides a persistent, read-write filesystem using the browser's IndexedDB. It's ideal for storing data that should persist between sessions.
 
 ### Usage
 
-Create an IDBDevice using the `CheerpX.IDBDevice.create()` method:
+[`Create`](/docs/reference/CheerpX.IDBDevice/create) an [`IDBDevice`](/docs/reference/CheerpX.IDBDevice) using the `CheerpX.IDBDevice.create()` method:
 
 ```javascript
 const idbDevice = await CheerpX.IDBDevice.create("dbName");
@@ -151,38 +151,13 @@ This setup creates a virtual filesystem at `/files` that is backed by IndexedDB.
 
 ### Reading files from JavaScript
 
-You can read files from an `IDBDevice` in JavaScript using the `readFileAsBlob` method:
+You can read files from an [`IDBDevice`](/docs/reference/CheerpX.IDBDevice) in JavaScript using the [`readFileAsBlob`](/docs/reference/CheerpX.IDBDevice/readFileAsBlob) method:
 
 ```javascript
 await idbDevice.readFileAsBlob("/filename");
 ```
 
-### `idbDevice.readFileAsBlob`
-
-`CheerpX.IDBDevice` provides a method to read back files as JavaScript accessible data.
-
-```js
-await idbDevice.readFileAsBlob(filename: string): Promise<Blob>
-```
-
-**Parameters**:
-
-- **filename**: A string representing the path to the file within the device, starting with a `/` (e.g., "/filename"). Do not include the mount point.
-
-**Returns**:
-
-The method returns a Promise that resolves to a standard JavaScript Blob object.
-
-Example:
-
-```js
-const idbDevice = await CheerpX.IDBDevice.create("files");
-// Use CheerpX to write something to the device
-const outputBlob = await idbDevice.readFileAsBlob("/filename");
-```
-
-> [!note] Note
-> The `readFileAsBlob` API returns a standard JavaScript Blob object. You can convert it to a string if needed, but you can also convert it to an `ArrayBuffer` or to a URL via `URL.createObjectURL`.
+For more details on reading files using [`IDBDevice`](/docs/reference/CheerpX.IDBDevice) and redirecting output, see the [Input/Output](/docs/guides/input-output#reading-files-using-idbdevice-and-redirecting-output) guide.
 
 ## DataDevice
 
@@ -243,7 +218,7 @@ CheerpX supports ext2 filesystems, which can be configured as an overlay device.
 
 ### Usage
 
-Create an ext2 filesystem by combining a `HttpBytesDevice` to acess disk blocks, an `IDBDevice` to cache and persist data and a `OverlayDevice` to combine the two.
+Create an ext2 filesystem by combining a `HttpBytesDevice` to access disk blocks, an `IDBDevice` to cache and persist data and a `OverlayDevice` to combine the two.
 
 ```javascript
 // Create an HttpBytesDevice for streaming disk blocks via HTTP

sites/cheerpx/src/content/docs/11-guides/input-output.md

@@ -43,7 +43,7 @@ For more details on customizing the console, see [CheerpX Custom console](/docs/
 
 ## Reading Files Using IDBDevice and Redirecting Output
 
-`IDBDevice` provides a persistent, read-write filesystem using the browser’s IndexedDB. It’s ideal for storing data that should persist between sessions. You can use the `readFileAsBlob` method to read files from an `IDBDevice` as Blob objects.
+[`IDBDevice`](/docs/reference/CheerpX.IDBDevice) provides a persistent, read-write filesystem using the browser’s IndexedDB. It’s ideal for storing data that should persist between sessions. You can use the [`readFileAsBlob`](/docs/reference/CheerpX.IDBDevice/readFileAsBlob) method to read files from an [`IDBDevice`](/docs/reference/CheerpX.IDBDevice) as Blob objects.
 
 To make a file accessible, you can copy files using commands within the virtual machine. Here’s an example on how to do it:
 
@@ -86,8 +86,6 @@ console.log(await outputBlob.text());
 > [!note] Note
 > This method has a significant limitation: it doesn't provide streaming output. The entire program needs to finish execution before you can read the output file. This means you won't see real-time output, and for long-running programs, you'll have to wait until completion to see any results. For real-time output, consider using the _custom_ console approach, which allows for streaming output.
 
-For more on `IDBDevice` operations, see the [CheerpX IDBDevice].
-
 ## Accessing JS Data in the Filesystem via DataDevice
 
 The `DataDevice` API exposes JavaScript data via the filesystem. This device provides read-only access to a `Uint8Array` and a JavaScript `String`. It is particularly useful for transferring data from JavaScript to programs running in CheerpX.
@@ -96,6 +94,5 @@ For more information, see the [CheerpX DataDevice].
 
 [CheerpX documentations]: https://cheerpx.io/docs/overview
 [CheerpX DataDevice]: https://cheerpx.io/docs/guides/File-System-support#datadevice
-[CheerpX IDBDevice]: https://cheerpx.io/docs/guides/File-System-support#idbdevice
 [Frequently Asked Questions]: https://cheerpx.io/docs/faq
 [xterm.js]: https://xtermjs.org/

sites/cheerpx/src/content/docs/12-reference/CheerpX.IDBDevice/create.md

@@ -0,0 +1,50 @@
+---
+title: create
+description: Create a CheerpX IDBDevice instance to store data in the browser's IndexedDB with read and write access.
+---
+
+```ts
+namespace CheerpX {
+	class IDBDevice {
+		static async create(dbName: string): Promise<IDBDevice>;
+	}
+}
+```
+
+## Parameters
+
+- **dbName (`string`)** - The name of `IndexedDB` where the filesystem will be stored.
+
+## Returns
+
+`CheerpX.IDBDevice.create` returns a [Promise] that gives you an `IDBDevice` instance. You can use this instance to create a virtual filesystem stored in `IndexedDB` within your CheerpX environment.
+
+## Example
+
+Create an `IDBDevice` instance for persistent storage.
+
+```js {4}
+// Create a read-only block device for a disk image stored on the HTTP server
+const blockDevice = await CheerpX.HttpBytesDevice.create("/cheerpXImage.ext2");
+// Make the block device read-write using a persistent IndexedDB overlay
+const idbDevice = await CheerpX.IDBDevice.create("block_idbDevice");
+const overlayDevice = await CheerpX.OverlayDevice.create(
+	blockDevice,
+	idbDevice
+);
+// Initialize the CheerpX environment
+const mountPoints = [
+	// Use the disk image as the filesystem root
+	{ type: "ext2", path: "/", dev: overlayDevice },
+];
+const cx = await CheerpX.Linux.create({
+	mounts: mountPoints,
+});
+```
+
+If you’d like to learn more about related topics, check out these guides:
+
+- [Files and filesystems](/docs/guides/File-System-support) – Managing files and storage in CheerpX.
+- [Input and output](/docs/guides/input-output) – Handling data flow in your environment.
+
+[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

sites/cheerpx/src/content/docs/12-reference/CheerpX.IDBDevice/readFileAsBlob.md

@@ -0,0 +1,53 @@
+---
+title: readFileAsBlob
+description: Reads a file from an IDBDevice and returns it as a Javascript Blob object.
+---
+
+```js
+namespace CheerpX {
+  class IDBDevice {
+    async readFileAsBlob(filename: string): Promise<Blob>;
+  }
+}
+```
+
+## Parameters
+
+- **filename (`string`)** - The path to the file within the `IDBDevice`, starting with a `/` (e.g., `/filename`). Do not include the mount point.
+
+## Returns
+
+`CheerpX.IDBDevice.readFileAsBlob` returns a [Promise] that resolves to a Javascript `Blob` object. This object represents the file's data, which can be further manipulated or converted as needed.
+
+## Example
+
+```js {4, 15}
+// Create a read-only block device for a disk image stored on the HTTP server
+const blockDevice = await CheerpX.HttpBytesDevice.create("/cheerpXImage.ext2");
+// Make the block device read-write using a persistent IndexedDB overlay
+const idbDevice = await CheerpX.IDBDevice.create("block_idbDevice");
+const overlayDevice = await CheerpX.OverlayDevice.create(
+	blockDevice,
+	idbDevice
+);
+// Initialize the CheerpX environment
+const mountPoints = [
+	// Use the disk image as the filesystem root
+	{ type: "ext2", path: "/", dev: overlayDevice },
+];
+const cx = await CheerpX.Linux.create({
+	mounts: mountPoints,
+});
+
+const outputBlob = await idbDevice.readFileAsBlob("/fileName");
+console.log(outputBlob);
+```
+
+> [!tip] View stored files in DevTools
+> To see your stored files, open Developer Tools, go to the Application tab, and check Storage > IndexedDB. Here, you can browse and inspect your files easily! <br>
+> Want to learn more? Check out these related guides: <br>
+>
+> - [Files and filesystems](/docs/guides/File-System-support) <br>
+> - [Input and output](/docs/guides/input-output)
+
+[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

sites/cheerpx/src/content/docs/12-reference/CheerpX.IDBDevice/reset.md

@@ -0,0 +1,50 @@
+---
+title: reset
+description: Reset the IDBDevice instance, clearing all its stored data in the associated IndexedDB.
+---
+
+```ts
+namespace CheerpX {
+	class IDBDevice {
+		async reset(): Promise<void>;
+	}
+}
+```
+
+## Parameters
+
+None.
+
+## Returns
+
+`CheerpX.IDBDevice.reset` returns a [Promise] that resolves once the `IDBDevice` has been reset. This operation clears all stored data, effectively restoring the `IDBDevice` to an empty state.
+
+## Example
+
+Reset an `IDBDevice` instance before mounting it.
+
+```ts {8}
+// Create a read-only block device for a disk image stored on the HTTP server
+const blockDevice = await CheerpX.HttpBytesDevice.create("/cheerpXImage.ext2");
+
+// Make the block device read-write using a persistent IndexedDB overlay
+const idbDevice = await CheerpX.IDBDevice.create("block_idbDevice");
+
+// Reset the IndexedDB storage
+await idbDevice.reset();
+
+const overlayDevice = await CheerpX.OverlayDevice.create(
+	blockDevice,
+	idbDevice
+);
+// Initialize the CheerpX environment
+const mountPoints = [
+	// Use the disk image as the filesystem root
+	{ type: "ext2", path: "/", dev: overlayDevice },
+];
+const cx = await CheerpX.Linux.create({
+	mounts: mountPoints,
+});
+```
+
+[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

sites/cheerpx/src/content/docs/20-faq.md

@@ -22,7 +22,7 @@ Yes, `WebDevice` can handle third-party origins as paths, but it's important to
 
 ## Why can't I execute files directly from a `DataDevice`?
 
-`DataDevice` in CheerpX does not have full support for Linux mode bits, and in particular it lacks the _**executable**_ bit. This means you can read data from it, but you cannot execute files directly from it. To execute files that are in a DataDevice, you need to first copy the files to a filesystem with complete support for mode bits, such as `IDBDevice` (IndexedDB) or Ext2.
+`DataDevice` in CheerpX does not have full support for Linux mode bits, and in particular it lacks the _**executable**_ bit. This means you can read data from it, but you cannot execute files directly from it. To execute files that are in a `DataDevice`, you need to first copy the files to a filesystem with complete support for mode bits, such as [`IDBDevice`](/docs/reference/CheerpX.IDBDevice) (IndexedDB) or Ext2.
 
 ## Why can't CheerpX do what v86 does in terms of disk access and networking?