@stacks/storage
Store and fetch files with Gaia, the decentralized storage system.
Installation
npm install @stacks/storage
Usage
Initiate a session
Users must authenticate to an app before the storage package will work to save or retrieve data on their behalf.
See also authentication guide using connect for web apps
The storage capabilities will work in cases userSession.isUserSignedIn()
returns true
Initiating a storage client
import { UserSession, AppConfig } from '@stacks/auth';
import { Storage } from '@stacks/storage';
const privateKey = '896adae13a1bf88db0b2ec94339b62382ec6f34cd7e2ff8abae7ec271e05f9d8';
const appConfig = new AppConfig();
const userSession = new UserSession({ appConfig });
userSession.store.getSessionData().userData = <any> {
appPrivateKey: privateKey,
};
const storage = new Storage({ userSession });
Note that you can also use an existing userSession
object created during the authentication process.
Put file
const myData = JSON.stringify({
hello: "world",
num: 1
});
const fileUrl = await storage.putFile('my_data.json', myData);
Store data at a different path
const fileUrl = await storage.putFile('path/my_data.json', myData);
Put file with options
const putFileOptions = {
contentType: 'application/json',
encrypt: false,
dangerouslyIgnoreEtag: true
}
const fileUrl = await storage.putFile('my_data.json', myData, putFileOptions);
Get file
const fileContent = await storage.getFile('my_data.json');
console.log(fileContent);
Get file with options
const getFileOptions = {
decrypt: false,
verify: false
}
const fileContent = await storage.getFile('my_data.json', getFileOptions);
console.log(fileContent);
Get file for other user
const options = {
username: 'yukan.id',
decrypt: false,
};
const fileContent = await storage.getFile('my_data.json', options);
console.log(fileContent);
Delete file
await storage.deleteFile('my_data.json');
Delete the file and the corresponding signature file if signed
await storage.deleteFile('my_data.json', { wasSigned: true });
List file
List all files in the user's Gaia hub
const files: Promise<string | undefined | ArrayBuffer | null>[] = [];
const options = { decrypt: false };
await storage.listFiles((filename: string) => {
if (filename === 'my_data.json') {
files.push(storage.getFile(filename, options));
return false;
} else {
return true;
}
});
const fileContents = await Promise.all(files);