Skip to content

Create, edit and read HSSP files in pure JavaScript

License

Notifications You must be signed in to change notification settings

acridotheres/hssp-js

Repository files navigation

GitHub npm GitHub commit activity (branch) npm jsDelivr hits (npm scoped) GitHub issues npm bundle size GitHub Repo stars

HSSP for JavaScript

Handle HSSP files easily with the official HSSP JavaScript API for Node.js and web.


Usage

Node.js

  • Install HSSP for JavaScript with npm i hssp
  • Create an editor:
const hssp = require('hssp');

const editor = new hssp.Editor();

Continue with learning about the API.

Web

  • Load HSSP for JavaScript with:
<script src="https://cdn.jsdelivr.net/npm/hssp@5/dist/hssp-web.min.js"></script>
  • Create an editor:
const editor = new hssp.Editor();

Continue with learning about the API.

API

Handling files & folders

// Node
const fs = require('fs');

editor.createFile('test.txt', fs.readFileSync('test.txt')); // Uses Buffer API

// Web
editor.createFile('test.txt', hssp.Buffer.from('Hello, world!', 'utf8')); // Uses the ported Buffer API
editor.createFolder('my-folder');
  • Add a file to my-folder:
editor.addFile('my-folder/test.txt', fs.readFileSync('test2.txt'));
  • Delete a file:

Note: This method will return the file Buffer.

editor.removeFile('test.txt');
  • Delete a folder:
editor.removeFolder('my-folder'); // This will also remove all files in the folder (recrusive removal)

Modifiying the output

  • Set output file version:
editor.pack({ version: 5 }); // 5 is set by default, 1-5 are valid version numbers
  • Enable output encryption:
editor.pack({ password: 'mysupersecretpassword' });
  • Enable output compression (you have to provide a compression method yourself):

Note: Requires pack version is 4 or higher.

const { compress, decompress } = require('lzma');

const compression = new hssp.Compression();
compression.add(
  'lzma',
  {
    idxd: 'LZMA',
    sprd: 0x4950,
  },
  (data, level) => Buffer.from(compress(data, { level })),
  (data) => Buffer.from(decompress(data)),
);

editor.pack({
  compression,
  compressionAlgorithm: 'lzma',
  compressionLevel: 5, // 5 is set by default, 0-9 are valid compression levels
});
  • Add a comment:

Note: Requires editor.version is 4 or higher. The comment can be up to 16 characters (UTF-8) long.

editor.comment = 'Hello :)';

// or do it directly within the pack method
editor.pack({ comment: 'Hello :)' }); // This will overwrite the previous comment

Importing HSSP files

Currently supports HSSP 1-5.

  • Importing HSSP files without encryption:
editor.import(fs.readFileSync('pictures.hssp')); // You can provide a version number in a second parameter if it's not the default 5

// with version detection:
const file = fs.readFileSync('pictures.hssp');
editor.import(file, { version: hssp.detectVersion(file) }); // this will definetly get the right version but is a bit slower
  • Importing HSSP files with encryption:
editor.import(fs.readFileSync('pictures.hssp'), { password: 'mysupersecretpassword' });

Creating HSSP files

Currently supports HSSP 1-5.

  • Creating one file:
fs.writeFileSync('test.hssp', editor.pack());
  • Creating multiple files:

Note: This method can only be used if the pack version is 4 or higher. You also cannot create more files than bytes included.

const bufs = editor.packMultiple(4);
fs.writeFileSync('test-part1.hssp', bufs[0]);
fs.writeFileSync('test-part2.hssp', bufs[1]);
fs.writeFileSync('test-part3.hssp', bufs[2]);
fs.writeFileSync('test-part4.hssp', bufs[3]);

Fetching metadata from HSSP file

Currently supports HSSP 1-5.

Fetching metadata is as simple as that:

Note: You have to know the version codename of the file.

const metadata = hssp.parsers.idxd(fs.readFileSync('pictures.hssp'), { flgd: true });

Contributing

Feel free to contribute by opening an issue and requesting new features, reporting bugs or just asking questions.

You can also fork the repository and open a pull request after making some changes like fixing bugs.

Please note that you have to follow the ESLint rules and the code style of the project.

HSSP for JavaScript is licensed under MIT license.