@gferrand/am-hook

Asset manager

The asset manager (am) is here to simplify your life concerning file in your applications.

Installing

First, install the library :

npm i @gferrand/am-hook

... and that's it ! You can now import everything you need inside your project.

The basics

First, import the am.

const AssetManager = require('@gferrand/am-hook');

Once it's imported you must initialize it inside your project, to do so, the am does have a method init() who take multiple parameters.

AssetManager.init( $applicationName, $applicationVersion, $applicationPort, $applicationUrl, $masterUrl, $filePath, $consoleCbk );

They are all mandatory.

For the masterUrl, pass an empty string if you have none. The filePath is the absolute path where the am will save your files. The consoleCbk will return a message emitted by the library, it's your job to handle it, commons cases are just a console.log.

Next, let's see how it work.

The am expose differement methods :

AssetManager.save($file);

AssetManager.get($token);

AssetManager.remove($token);

... and their plural counterparts :

AssetManager.saves($arrayOfFiles);

AssetManager.gets($arrayOfTokens);

AssetManager.getsZipped($arrayOfTokens, $dictionnaryOfTokensAndFileNames);

AssetManager.removes($arrayOfTokens);

All methods within the library return a promise.

Saving

To save files, either use one of the saves methods. This method only accept a file of this format :

const file = {
    name : yourFileName,
    data : arrayBuffer
}

If your file is not an array buffer, look into the Buffer.from() method to convert it.

Once you're ready, call the am and pass the file object you created.

As it return a promise, your code must be prepare to handle asynchronous operation. You can either pick the '.then().catch()' way, or use the new sugar 'async/await'.

Either way, once the am is done saving your(s) file(s), it'll give you what we call a token, or an array of tokens.

What is a token ? A token is simply an auto generated id used by the library to find your files.

It's your responsability to save the token when you receive it, this is the only way to get your file back.

Getting

To get your files, either use one of the get methods.

They do accept a token, or an array of tokens. The tokens are the one provided straight after the save has been done.

Just like the saves methods, it'll return a promise, be sure to handle it properly.

The am will remove the file from the disk for you, you can now delete this token safely, it won't be reusable.

Getting zip

Return a zip of the files you claimed through the tokens.

The dictionnary must be an array of objects, and each object must respect the following structure :

{
    token : yourToken,
    name : fileName
}

If you plan on zipping your files, it's your responsiablity to save the tokens, and the original name of the files.

Deleting

Refer to the getting parts, it work the same way.

Migrating

If you ever need to switch to an architecture without master/slaves, the library is able to take all your file and to save them into the master/slaves.

As the am was saving your file locally without a database, it's impossible to recover the original name of the files, but the next files will keep their original names on retrieval.

Once your master and the slaves are initialized, you're ready to start the migration.

Go inside the master, and open a terminal and execute the following command :

npm run migrate $slaveIp $filesPath $appName $ appIp $appVersion $appPort

Of course, replace all the $foo by their respectives values, a full exemple would be :

npm run migrate localhost:9202 C:/DELETEME/AssetManager fileupload-be localhost:3000 0.1.1-alpha 3000