MutableData

MutableData

new MutableData()

Source:

Methods

applyEntriesMutation(mutations) → {Promise}

Commit the transaction to the network

Parameters:
Name Type Description
mutations EntryMutationTransaction

the Mutations you want to apply
Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        await mData.quickSetup({ key1: 'value1', key2: 'value2' });
        const mutation = await app.mutableData.newMutation();
        await mutation.insert('key2', 'value2')
        await mData.applyEntriesMutation(mutation);
    } catch (err) {
        throw err;
    }
};

decrypt(value) → {Promise.<Buffer>}

Decrypt the entry key/value provided as parameter with the encryption key contained in a private MutableData.

Parameters:
Name Type Description
value String | Buffer
Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        const encryptedValue = await mData.encryptValue('value1')
        const decryptedValue = await mData.decrypt(encryptedKey)
    } catch (err) {
        throw err;
    }
};

delUserPermissions(signKeyopt, version) → {Promise}

Delete the permissions of a specifc key. Directly commits to the network. Requires 'ManagePermissions' permission for the app.

Parameters:
Name Type Attributes Default Description
signKey PubSignKey | CONSTANTS.USER_ANYONE <optional>
 CONSTANTS.USER_ANYONE

the key to lookup for
version Number

The version successor, to confirm you are actually asking for the right one
Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        await mData.quickSetup({ key1: 'value1', key2: 'value2' });
        const version = await mData.getVersion();
        const signKey = await app.crypto.getAppPubSignKey();
        const permissionSet = mData.delUserPermissions(signKey, version + 1);
    } catch (err) {
        throw err;
    }
};

emulateAs(eml) → {Emulation}

Wrap this MutableData into a known abstraction. Currently only known: NFS

Parameters:
Name Type Description
eml String

name of the emulation
Source:
Example
// Assumes SAFEApp interface has been obtained
const emulationOptions = {
    nfs   : 'NFS',
    rdf   : 'RDF',
    webid : 'WebId'
};
const asyncFn = async () => {
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        await mData.quickSetup({ });
        const nfs = await mData.emulateAs(emulationOptions.nfs)
    } catch (err) {
        throw err;
    }
};

encryptKey(key) → {Promise.<Buffer>}

Encrypt an entry key value for a private MutableData. If the MutableData is public, the same, unencrypted, value is returned.

Parameters:
Name Type Description
key String | Buffer
Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
             const mData = await app.mutableData.newRandomPrivate(15001);
        const encryptedKey = await mData.encryptKey('key1')
    } catch (err) {
        throw err;
    }
};

encryptValue(value) → {Promise.<Buffer>}

Encrypt an entry value for a private MutableData. If the MutableData is public, the same, unencrypted, value is returned.

Parameters:
Name Type Description
value String | Buffer
Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
             const mData = await app.mutableData.newRandomPrivate(15001);
        const encryptedValue = await mData.encryptValue('value1')
    } catch (err) {
        throw err;
    }
};

get() → {Promise.<ValueVersion>}

Look up the value of a specific key

Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        const entryValue = await mData.get('key1');
    } catch (err) {
        throw err;
    }
};

getEntries() → {Promise.<Entries>}

Get a Handle to the entries associated with this MutableData

Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        await mData.quickSetup({});
        const entries = mData.getEntries();
    } catch (err) {
        throw err;
    }
};

getKeys() → {Promise.<Array>}

Get a list with the keys contained in this MutableData

Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        await mData.quickSetup({ key1: 'value1', key2: 'value2' });
        const entryKeysArray = mData.getKeys();
    } catch (err) {
        throw err;
    }
};

getNameAndTag() → {Promise.<NameAndTag>}

Look up the name, tag, and XOR-URL of the MutableData as required to look it up on the network.

Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        const  nameAndTag = await mData.getNameAndTag();
    } catch (err) {
        throw err;
    }
};

getPermissions() → {Permissions}

Get an interface to the permissions associated with this MutableData

Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        await mData.quickSetup({ key1: 'value1', key2: 'value2' });
        const permissionsInterface = mData.getPermissions();
    } catch (err) {
        throw err;
    }
};

getSerialisedSize() → {Promise.<Number>}

Get serialised size of current MutableData

Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        await mData.quickSetup({ key1: 'value1', key2: 'value2' });
        const serialisedSize = await mData.getSerialisedSize();
    } catch (err) {
        throw err;
    }
};

getUserPermissions(signKeyopt) → {Promise.<Object>}

Get an interface to the permissions associated with this MutableData for a specific signing key

Parameters:
Name Type Attributes Default Description
signKey PubSignKey | CONSTANTS.USER_ANYONE <optional>
 CONSTANTS.USER_ANYONE
Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        await mData.quickSetup({ key1: 'value1', key2: 'value2' });
        const signKey = await app.crypto.getAppPubSignKey();
        const permissionSet = await mData.getUserPermissions(signKey);
    } catch (err) {
        throw err;
    }
};

getValues() → {Promise.<Array>}

Get the list of values contained in this MutableData

Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        await mData.quickSetup({ key1: 'value1', key2: 'value2' });
        const entryValuesArray = mData.getValues();
    } catch (err) {
        throw err;
    }
};

getVersion() → {Promise.<Number>}

Look up the mutable data object version on the network

Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        const version = await mData.getVersion();
    } catch (err) {
        throw err;
    }
};

put(permissions, entries) → {Promise}

Commit this MutableData to the network.

Parameters:
Name Type Description
permissions Permission | CONSTANTS.MD_PERMISSION_EMPTY

the permissions to create the mutable data with
entries Entries | CONSTANTS.MD_ENTRIES_EMPTY

data entries to create the mutable data with
Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        const perms = await mData.newPermissions();
        const pmSet = ['Insert', 'Update', 'Delete', 'ManagePermissions'];
        const pubSignKey = await app.crypto.getAppPubSignKey();
        await perms.insertPermissionsSet(pubSignKey, pmSet);
        const entries = await mData.newEntries();
        await entries.insert('key1', 'value1');
        await mData.put(perms, entries)
    } catch (err) {
        throw err;
    }
};

quickSetup(data, name, description) → {Promise.<MutableData>}

Easily set up and commit a new MutableData with the app having full-access permissions (and no other). The name and description parameters are metadata for the MutableData which can be used to identify what this MutableData contains. The metadata is particularly used by the Authenticator when another application has requested mutation permissions on this MutableData, so the user can make a better decision to either allow or deny such a request based on this information.

Parameters:
Name Type Description
data Object

a key-value payload it should create the data with
name String | Buffer

A descriptive metadata name for the MutableData
description String | Buffer

A detailed metadata description for the MutableData content
Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    let mData = app.mutableData.newRandomPublic(tagtype);
    const entries = {
        key1: 'value1',
        key2: 'value2'
    };
    const name = 'My MutableData';
    const description = "To store my app\'s data";
    mData = await mData.quickSetup(entries, name, description);
};

serialise() → {Promise.<String>}

Serialise the current MutableData

Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        await mData.quickSetup({ key1: 'value1', key2: 'value2' });
        const serialisedMD = await mData.serialise();
    } catch (err) {
        throw err;
    }
};

setMetadata(name, description) → {Promise}

Set the metadata information in the MutableData. Note this can be used only if the MutableData was already committed to the network, .i.e either with put, with quickSetup, or if it is an already existing MutableData just fetched from the network. The metadata is particularly used by the Authenticator when another application has requested mutation permissions on this MutableData, displaying this information to the user, so the user can make a better decision to either allow or deny such a request based on it.

Parameters:
Name Type Description
name String | Buffer

A descriptive name for the MutableData
description String | Buffer

A detailed description for the MutableData content
Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    const name = 'Mutable data name';
    const description = 'Mutable data description';
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        await mData.quickSetup({});
        await mData.setMetadata(name, description);
    } catch (err) {
        return err;
    }
};

setUserPermissions(signKeyopt, permissionSet, version) → {Promise}

Set the permissions of a specifc key. Directly commits to the network. Requires 'ManagePermissions' permission for the app.

Parameters:
Name Type Attributes Default Description
signKey PubSignKey | CONSTANTS.USER_ANYONE <optional>
 CONSTANTS.USER_ANYONE

the key to lookup for
permissionSet PermissionSet

The permission set to set to
version Number

the version successor, to confirm you are actually asking for the right one
Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const mData = await app.mutableData.newRandomPrivate(15001);
        await mData.quickSetup({ key1: 'value1', key2: 'value2' });
        const version = await mData.getVersion();
        const pmSet = ['Insert'];
        const permissionSet = await mData.setUserPermissions(
            safe.CONSTANTS.USER_ANYONE, pmSet, version + 1
        );
    } catch (err) {
        throw err;
    }
};