# Working with Files

## Structure

Files & folders in win32.run shared the same structure. I'm not good at naming, let's call them `fs_item`

To get a fs\_item from id

```javascript
import { hardDrive } from '$lib/store.js';

let id = '1Ggc8cPyxmAqp5tqKdo3s9';
let fs_item = $hardDrive[id];
```

Each fs\_item is identified with an id. Here's the general structure of a fs\_item

```javascript
{
    id: String,
    //used to identify a fs_item
    
    basename: String,
    //name of the item without extension
    
    ext: String,
    //extension. e.g. .jpg, .png
    
    name: String,
    // = basename + ext. :) now I'm ashamed at this redundancy
    
    size: Number,
    //item size, in Kilobytes
    
    date_created: Number,
    //timestamp of the Date when item was first created,
    
    date_modified: Number,
    //timestamp of the Date when item was last modified,
    
    storage_type: String,
    //possible values include 'local' and 'remote'
    //local: the content of the file is stored locally in IndexedDB as File
    //remote: the content is on a web address (https or http)
    
    url: String,
    //if the storage_type is local, url is a id point to a File object
    //in IndexedDB
    //if the storage_type is remote, url is the web address of the file
    
    parent: String,
    //id of the parent folder (the folder that contains this fs_item)
    
    children: [String],
    //list of its children fs_items' ids
    //if it's a file, then children is a empty array
}
```

## Operations

It's recommended that you use `$lib/fs.js` instead of working with files manually.

When I wrote this fs.js file, I didn't intend for its functions to be used by another human being, so it's pretty messed up there, without any code comments. Shame on me.

```javascript
import * as fs from '$lib/fs.js';
```

### Create

This function creates a new fs\_item (can create both file and folder), returns a promise that resolves with the newly created fs\_item id.

```javascript
let fs_item_id = await fs.new_fs_item(type, ext, seedname, parent_id, file);
```

* `type: String`: can be '`file`' to create a new file, or '`folder`' to create a new folder
* `ext: String:` the `fs_item` extension, start with a dot. e.g: .jpg, .png. Leave an empty string `''` if `type == 'folder'`
* `seedname: String:` suggested file name. e.g: '`nevada desert'.`
* `parent_id: String:` id of the parent folder where the newly created item will be located.
* `file: File:` the actually file content. See [Mozilla Docs](https://developer.mozilla.org/en-US/docs/Web/API/File)

### Copy

To actually copy a fs\_item, use `fs.clone_fs()`

```javascript
fs.clone_fs(item_id, new_parent_id, new_item_id)
```

* `item_id: String`: the fs\_item id that you want to copy
* `new_parent_id: String`: id of the destination directory (folder)
* `new_item_id: String`: provide the newly created item an id so you can refer to it later. Sorry for this inconvenience.

To generate an id:

```javascript
import short from 'short-uuid';
let id = short.generate();
```

Note: The `fs.copy`, `fs.cut` functions are used to put an item into the clipboard. These functions don't actually copy or cut an item.

### Delete

To permanently delete a fs\_item

```javascript
fs.del_fs(item_id)
```

### Save

To save content to a fs\_item

```javascript
await fs.save_file(fs_item_id, file)
```

In which `file` is the new content as a File object. See [Mozilla Docs](https://developer.mozilla.org/en-US/docs/Web/API/File)

Example:

```javascript
let text = '<h1>Hello World</h1>';
let file = new File([text], 'any_name.html', {type: 'text/html'});

let fs_item_id = '1Ggc8cPyxmAqp5tqKdo3s9';

await fs.save_file(fs_item_id, file); 
```

### Read

To read content of a fs\_item, use `fs.get_file(item_id)`. This function returns a promise that resolves with a File object. See [Mozilla Docs](https://developer.mozilla.org/en-US/docs/Web/API/File).

```javascript
let file = await fs.get_file(item_id);
//file is a File object

let text_content = await file.text();//read file as text
```

### fs\_item's id to human-readable path

If you have a fs\_item's id (e.g. `1Ggc8cPyxmAqp5tqKdo3s9`) and want to convert it into a human-readable path like what is being displayed in My Computer `D:\webpages\any_name.html`&#x20;

```javascript
import * as finder from '$lib/finder.js';

let fs_item_id = '1Ggc8cPyxmAqp5tqKdo3s9';
let path_str = finder.to_url(fs_item_id);
//return value is D:\webpages\any_name.html
```

### human-readable path to fs\_item id

If you have path (for example `D:\webpages\any_name.html` ) and want to get the fs\_item id out of it

```javascript
import * as finder from '$lib/finder.js';

let path_str = 'D:\\webpages\\any_name.html';
//the double backslash \\ is for escaping \
//the actual path_str is D:\webpages\any_name.html

let fs_item_id = finder.to_id(path_str);
//returns 1Ggc8cPyxmAqp5tqKdo3s9

//then you can use this id to save, copy or delete the file
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.win32.run/developers/spaghetti-code/working-with-files.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.