|
1 | | - |
2 | | - |
3 | | - |
4 | | - |
5 | | - |
6 | | - |
7 | | - |
8 | | - |
| 1 | +[](LICENSE) |
| 2 | +[](https://npmjs.com/package/hssp) |
| 3 | +[](https://github.com/HSSPfile/js/commits/main) |
| 4 | +[](https://npmjs.com/package/hssp) |
| 5 | +[](https://www.jsdelivr.com/package/npm/hssp) |
| 6 | +[](https://github.com/HSSPfile/js/issues) |
| 7 | +[](.) |
| 8 | +[](https://github.com/HSSPfile/js/stargazers) |
9 | 9 |
|
10 | 10 | # HSSP for JavaScript |
11 | 11 |
|
|
16 | 16 | ## Usage |
17 | 17 | ### Node.js |
18 | 18 |
|
19 | | -Create an editor: |
| 19 | +- Install HSSP for JavaScript with `npm i hssp` |
| 20 | +- Create an editor: |
20 | 21 | ```js |
21 | 22 | const HSSP = require('hssp'); |
22 | 23 |
|
23 | 24 | const editor = new HSSP.Editor(); |
24 | | -``` |
| 25 | +``` |
| 26 | +Continue with [learning about the API](#api). |
| 27 | + |
| 28 | +### Web |
| 29 | +- Load HSSP for JavaScript with: |
| 30 | +```html |
| 31 | +<script src="https://cdn.jsdelivr.net/npm/hssp@3/web.min.js"></script> |
| 32 | +``` |
| 33 | +- Create an editor: |
| 34 | +```js |
| 35 | +const editor = new HSSP.Editor(); |
| 36 | +``` |
| 37 | +Continue with [learning about the API](#api). |
| 38 | + |
| 39 | +### API |
| 40 | +#### Handling files & folders |
| 41 | + |
| 42 | +- Add a file (see [Optional parameters](#optional-parameters-for-creating-filesfolders)): |
| 43 | +```js |
| 44 | +// Node |
| 45 | +const fs = require('fs'); |
| 46 | + |
| 47 | +editor.addFile('test.txt', fs.readFileSync('test.txt')); // Uses Buffer API |
| 48 | + |
| 49 | +// Web |
| 50 | +editor.addFile('test.txt', (new TextEncoder()).encode('Hello, world!').buffer); // Uses ArrayBuffer API |
| 51 | +``` |
| 52 | +- Add a folder (see [Optional parameters](#optional-parameters-for-creating-filesfolders)): |
| 53 | +```js |
| 54 | +editor.addFolder('my-folder'); |
| 55 | +``` |
| 56 | +- Add a file into `my-folder`: |
| 57 | +```js |
| 58 | +// Node |
| 59 | +editor.addFile('my-folder/test.txt', fs.readFileSync('test2.txt')); |
| 60 | + |
| 61 | +// Web |
| 62 | +editor.addFile('my-folder/test.txt', (new TextEncoder()).encode('Hello, world! 2').buffer); |
| 63 | +``` |
| 64 | +- Delete a file: |
| 65 | +**Note:** _This method will return the file Buffer/ArrayBuffer._ |
| 66 | +```js |
| 67 | +editor.remove('test.txt'); |
| 68 | +``` |
| 69 | +- Delete a folder: |
| 70 | +```js |
| 71 | +editor.remove('my-folder'); |
| 72 | +``` |
| 73 | +**Note:** _This will only remove the folder, not the files in it! If you want to remove the folder with the files in it, use:_ |
| 74 | +```js |
| 75 | +var folderName = 'my-folder'; |
| 76 | + |
| 77 | +var filesStored = Object.keys(editor.files); // Create a list of all the files in the editor |
| 78 | +filesStored.forEach(fileName => { // Loop over all the files stored |
| 79 | + if (fileName.startsWith(folderName + '/')) editor.remove(fileName); // Remove everything starting with folderName/ from the editor |
| 80 | +}); |
| 81 | +editor.remove(folderName); // Remove the folder itself |
| 82 | +``` |
| 83 | + |
| 84 | +#### Modifiying the output |
| 85 | + |
| 86 | +- Set output file version: |
| 87 | +```js |
| 88 | +editor.version = 4; // 4 is set by default, 1-4 are valid version numbers |
| 89 | +``` |
| 90 | +- Enable output encryption: |
| 91 | +```js |
| 92 | +editor.password = 'MySecretPassword'; // write-only |
| 93 | +``` |
| 94 | +- Disable output encryption: |
| 95 | +```js |
| 96 | +editor.password = null; // Encryption is disabled by default |
| 97 | +``` |
| 98 | +- Enable output compression ([Supported algorithms](#supported-compression-algorithms)): |
| 99 | +**Note:** _Requires editor.version is 4 or higher._ |
| 100 | +```js |
| 101 | +editor.compression = { algorithm: 'LZMA', level: 9 }; // Level default is 5 |
| 102 | +``` |
| 103 | +- Disable output compression: |
| 104 | +```js |
| 105 | +editor.compression = null; // default |
| 106 | +``` |
| 107 | +- Add a comment: |
| 108 | +**Note:** _Requires editor.version is 4 or higher. The comment can be up to 16 characters (UTF-8) long._ |
| 109 | +```js |
| 110 | +editor.comment = 'Hello :)'; |
| 111 | +``` |
| 112 | + |
| 113 | +#### Importing HSSP files |
| 114 | + |
| 115 | +Currently supports HSSP 1-4. |
| 116 | + |
| 117 | +- Importing HSSP files _without_ encryption: |
| 118 | +```js |
| 119 | +// Node |
| 120 | +editor.import(fs.readFileSync('pictures.hssp')); |
| 121 | + |
| 122 | +// Web |
| 123 | +const fileReadEventHandler = (ev) => new Promise((resolve, reject) => { |
| 124 | + const file = ev.target.files[0]; |
| 125 | + const reader = new FileReader(); |
| 126 | + reader.onload = () => resolve(reader.result); |
| 127 | + reader.readAsArrayBuffer(file); |
| 128 | +}); |
| 129 | + |
| 130 | +document.querySelector('input[type=file]').onchange = async (ev) => { |
| 131 | + editor.import(await fileReadEventHandler(ev)); |
| 132 | +}; |
| 133 | +``` |
| 134 | + |
| 135 | +- Importing HSSP files _with_ encryption: |
| 136 | +```js |
| 137 | +// Node |
| 138 | +editor.import(fs.readFileSync('pictures.hssp')); |
| 139 | + |
| 140 | +// Web |
| 141 | +document.querySelector('input[type=file]').onchange = async (ev) => { |
| 142 | + editor.import(await fileReadEventHandler(ev), 'MySecretPassword'); // use the fileReadEventHandler function from previous code block |
| 143 | +}; |
| 144 | +``` |
| 145 | + |
| 146 | +#### Creating HSSP files |
| 147 | + |
| 148 | +Currently supports HSSP 1-4. |
| 149 | + |
| 150 | +- Creating _one_ file: |
| 151 | +```js |
| 152 | +// Node |
| 153 | +fs.writeFileSync('test.hssp', editor.toBuffer()); |
| 154 | + |
| 155 | +// Web |
| 156 | +const a = document.createElement('a'); |
| 157 | +a.download = 'test.hssp'; |
| 158 | +const blob = new Blob([editor.toBuffer()], { type: 'application/octet-stream' }); |
| 159 | +const url = URL.createObjectURL(blob); |
| 160 | +a.href = url; |
| 161 | +a.click(); |
| 162 | +URL.revokeObjectURL(url); |
| 163 | +``` |
| 164 | +- Creating _multiple_ files: |
| 165 | +**Note:** _This method can only be used if `editor.version` is 4 or higher. You also cannot create more files than bytes included._ |
| 166 | +```js |
| 167 | +// Node |
| 168 | +const bufs = editor.toBuffers(4); |
| 169 | +fs.writeFileSync('test-part1.hssp', bufs[0]); |
| 170 | +fs.writeFileSync('test-part2.hssp', bufs[1]); |
| 171 | +fs.writeFileSync('test-part3.hssp', bufs[2]); |
| 172 | +fs.writeFileSync('test-part4.hssp', bufs[3]); |
| 173 | + |
| 174 | +// Web |
| 175 | +editor.toBuffers(4).forEach((buf, i) => { |
| 176 | + const a = document.createElement('a'); |
| 177 | + a.download = 'test-part' + (i + 1) + '.hssp'; |
| 178 | + const blob = new Blob([buf], { type: 'application/octet-stream' }); |
| 179 | + const url = URL.createObjectURL(blob); |
| 180 | + a.href = url; |
| 181 | + a.click(); |
| 182 | + URL.revokeObjectURL(url); |
| 183 | +}); |
| 184 | +``` |
| 185 | + |
| 186 | +#### Fetching metadata from HSSP file |
| 187 | + |
| 188 | +Currently supports HSSP 1-4. |
| 189 | + |
| 190 | +Fetching metadata is as simple as that: |
| 191 | +```js |
| 192 | +// Node |
| 193 | +var meta = HSSP.metadata(fs.readFileSync('pictures.hssp')); // You can provide a password in a second parameter |
| 194 | + |
| 195 | +// Web |
| 196 | +document.querySelector('input[type=file]').onchange = async (ev) => { |
| 197 | + var meta = HSSP.metadata(await fileReadEventHandler(ev)); // You can provide a password in a second parameter |
| 198 | +}; |
| 199 | +``` |
| 200 | + |
| 201 | +To see how the output looks like, look in the [docs](https://hssp.leox.dev/jsdoc/). |
| 202 | + |
| 203 | +#### Optional parameters for creating files/folders |
| 204 | + |
| 205 | +```js |
| 206 | +const options = { |
| 207 | + hidden: false, // Is the file hidden? |
| 208 | + system: false, // Is the file a system file? |
| 209 | + enableBackup: true, // Enable this file for backups? |
| 210 | + forceBackup: false, // Should the file be backed up (for very important files)? |
| 211 | + readOnly: false, // Should be write operations disabled? |
| 212 | + mainFile: false, // Is this the main file of the directory? |
| 213 | + |
| 214 | + permissions: 764, // rwxrw-r-- (chmod syntax) |
| 215 | + |
| 216 | + owner: 'user', |
| 217 | + group: 'users', |
| 218 | + created: new Date(1188518400000), |
| 219 | + changed: new Date(1188518400000), |
| 220 | + opened: new Date(1188518400000), |
| 221 | + webLink: 'https://leox.dev/projects/lora/logo.png' // A string containing a link to an exact same file on the web |
| 222 | +}; |
| 223 | + |
| 224 | +editor.addFile(name, buf, options); |
| 225 | +editor.addFolder(name, options); |
| 226 | +``` |
| 227 | + |
| 228 | +#### Supported compression algorithms |
| 229 | +- `DEFLATE` |
| 230 | +- `LZMA` |
| 231 | +- `NONE` |
| 232 | + |
| 233 | +## [Docs (generated by JSDoc)](https://hssp.leox.dev/jsdoc/) |
| 234 | + |
| 235 | +## Contributing |
| 236 | + |
| 237 | +Feel free to contribute by [opening an issue](https://github.com/HSSPfile/js/issues/new/choose) and requesting new features, reporting bugs or just asking questions. |
| 238 | + |
| 239 | +You can also [fork the repository](https://github.com/HSSPfile/js/fork) and opening a [pull request](https://github.com/HSSPfile/js/pulls) after making some changes like fixing bugs. |
| 240 | + |
| 241 | +## [License](LICENSE) |
| 242 | + |
| 243 | +HSSP for JavaScript is licensed under MIT license. |
0 commit comments