@moibitjs/core

The Core module of moibitjs to interact with MoiBit off-chain Storage platform


Keywords
off-chain, storage, moibit, js, core, sdk, javascript, immutability, decentralized-storage
License
GPL-3.0
Install
npm install @moibitjs/core@1.0.0

Documentation

MoiBit banner logo

@moibitjs/core

npm version Chat on Slack Chat on Telegram Follow us on Twitter

Core module of MoiBitJS to interact with MoiBit , a decentralized cloud storage.

This library will help authenticated MoiBit Developers to store , read , delete , pin , unpin and get details about a file/folder using MoiBit as their storage platform

Click here to get your MoiBit credentials. You will be getting API_KEY , API_SECRET and a URL after successful signup.

Install

Using npm:

npm install --save @moibitjs/core

Getting started

(async  => {
	//import moibit core sdk
	import  MoiBit  from  '@moibitjs/core'
	//create moibit instance
	const  files = new  MoiBit(
		// the url you got after signing up to moibit
		'<your-url>', {
		api_key : '<your-api-key>', // the api key you got after signing up to moibit
		api_scret : '<your-api-secret>'  // the api key you got after signing up to moibit
	});
	console.log(await files.storageUsed('GB'));
})()

Functions


new MoiBit(url,accessToken)

This constructor is to wrap the files module with a URL and an access token , so that you don't need to send an access token in every call.

  • url the URL you got after signup
  • accessToken is an object with API_KEY and API_SECRET as keys
let files = new MoiBit(<YOUR_URL>,{
	API_KEY : '<YOUR_API_KEY>' ,
	API_SECRET : '<YOUR_API_SECRET>'
});

files.addFile(file,path,options)

Adds file of any type to MoiBit

  • file The actual file you are uploading

  • fileName File name or path

  • options

    • createFolders is a boolean value. If it is false and if a path specified in fileName does not exist, the operation will fail. Default:"true"

    • pinVersion is a boolean value which ensures that the version of the file uploaded won't be unpinned (and become eligible for garbage collection) when another version of the same file is uploaded (in the future). Default:"false"

await  files.addFile(fileObject,'parent1/folder2/file3.txt');

files.addFolder(files,options)

Add a non-empty directory with file(s) and nested non-empty directories inside it. If the path where the directory should be added is not specified, the directory will be added at the root path.

  • dirData The actual non-empty folder you are uploading.

  • path The path where the directory should be uploaded. Default: "/"

  • options

    • pinVersion is a boolean value which ensures that the version of the file uploaded won't be unpinned (and become eligible for garbage collection) when another version of the same file is uploaded (in the future). Default:"false"
await  files.addFolder(filesArray,{path:'/testFolder'};

files.addFileFromFs(path,options)

This call is meant to work in the node environment. This works similar to files.addFile() but the local path of the file needs to be passed instead of passing the file directly

  • path Absolute path from the file system
await  files.addFileFromFs('local_path_of_the_file',{pinVersion:true};

files.addFolderFromFs(path,options)

This call is meant to work in the node environment. This works similar to files.addFolder() but the local path of the folder need to be passed instead of direct folder

  • path Absolute path from the file system
await  files.addFolderFromFs('local_path_of_the_folder',{path:'/testFolder'};

files.addNotes(notes,path,options)

Write string content to a file. The content of an existing file gets appended to the last byte of the existing content. String content can be added to a new file by setting the create field to true.

  • fileName File name and path

  • text Text or JSON content to add

  • options

    -create is a string value. create a new file if the file to which string content needs to be appended does not exist. Default: "false"

    • createFolders is a boolean value. If this option is set to false and if a path specified in fileName does not exist, the operation will fail. Default:"true"

    • pinVersion is a boolean value which ensures that the version of the file uploaded won't be unpinned (and become eligible for garbage collection) when another version of the same file is uploaded (in the future). Default:"false"

await  files.addNotes('Welcome to MoiBit','/invitation.txt',{create : 'true'};

files.addPin(options)

Pin to keep this version of the file accessible by hash even after a new version of the file is added.

  • options

    • hash The hash of the content requested to pin

    • fileName The name of the file, with the fully qualified path, that you're attempting to pin. Will only pin the latest version of the file.

await files.addPin({hash : 'QmAs...'})

files.fileStats(path)

View the hash, size and parent folder of a file or a folder. Also view the pin status and creation time in case of a file.

await files.fileStats('/2020/sales/employee_salary.txt');

files.getVersions(fileName)

View details of all available versions of a file. The response will show file versions in reverse chronological order. Only files can have versions, not folders.

await files.getVersions('/2020/sales/employee_salary.txt');

files.list(path)

List files and sub-folders in the specified folder.

  • path The name of the folder with the fully qualified path. Defaults to the root folder ‘/’
await files.list('/2020/sales');

files.mkdir(path)

Create an empty directory. Any folders that are a part of the path - and don't exist - will also be created.

  • path The fully qualified path at which you're attempting to create a new directory.
await files.mkdir('2020/sales');

files.read(fileName,responseType)

Read a file that has been added in given responseType

  • fileName The name of the file, with the fully qualified path, that you're attempting to read

  • responseType can be anything among

    • arraybuffer,document,json,text,stream

    • blob - browser only

await files.read('/2020/sales/employee_salary.txt','blob');

files.readFileByHash(hash,responseType)

Read a file by its hash in given responseType

  • hash The hash of the content for the file requested.

  • responseType can be anything among

    • arraybuffer,document,json,text,stream

    • blob - browser only

await files.readFileByHash('Qmbg......','json');

files.remove(path)

Remove a file or folder. In case of a file, only the most recent version of the file will be removed by default. In case of a folder, all the files and nested folders inside it will also be removed.

  • path The name of the file or folder with the fully qualified path, that you're attempting to remove
  • options -recursive Recursively remove directories. Default:"false"
    • allVersions Remove all versions of this file. Default:"false"
await files.remove('/2020/sales',{recursive : true});

files.removePin(options)

Remove pin to make sure this version of the file is removed when another version of the same file is added. Removing pin also reduces the replication factor of the file.

  • options

    • hash The hash of the content to be unpinned

    • fileName The name of the file, with the fully qualified path, that you're attempting to unpin. Will only unpin the latest version of the file.

await files.removePin({filename : '/2020/sales/employee_salary.txt'});

files.storageUsed(unit)

Returns all the storage details of the particular account (you initialize with) in a specific Unit.

  • unit is a short hand notation of storage unit. It can be B,KB,MB,GB,TB(case insensitive)
await files.storageUsed('mb');

Maintainers

  1. Vuppala Sai Prashanth
  2. Arunprakash

Review and code standards

  1. Ayush Gupta
  2. Ganesh Prasad Kumble

Support

If you need more clarifications, feel free to join our Telegram or Slack community channels. You can also write us an email at hello@moibit.io or refer to our API docs.

License

GNU General Public License v3.0