This repository has been archived by the owner on Jan 6, 2020. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 10
/
immutable_data.js
196 lines (186 loc) · 7.31 KB
/
immutable_data.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
const { genHandle, getObj, freeObj } = require('./helpers');
module.exports.manifest = {
create: 'promise',
fetch: 'promise',
write: 'promise',
closeWriter: 'promise',
read: 'promise',
size: 'promise',
free: 'sync'
};
/**
* Create a new ImmutableData Writer
* @name window.safeImmutableData.create
*
* @param {SAFEAppHandle} appHandle the app handle
*
* @returns {Promise<WriterHandle>} the ImmutableData Writer handle
*
* @example // Creating a new ImmutableData writer:
* window.safeImmutableData.create(appHandle)
* .then((idWriterHandle) => console.log('ImmutableData writer handle: ', idWriterHandle));
*/
module.exports.create = (appHandle) => getObj(appHandle)
.then((obj) => obj.app.immutableData.create()
.then((imd) => genHandle(obj.app, imd)));
/**
* Look up an existing ImmutableData for the given address
* @name window.safeImmutableData.fetch
*
* @param {SAFEAppHandle} appHandle the app handle
* @param {Buffer} address the XorName on the network
*
* @returns {Promise<ReaderHandle>} the ImmutableData Reader handle
*
* @example // Fetch an exisiting ImmutableData from the network:
* window.safeImmutableData.create(appHandle)
* .then((idWriterHandle) => window.safeCipherOpt.newPlainText(appHandle)
* .then((cipherOptHandle) => window.safeImmutableData.closeWriter(
* idWriterHandle,
* cipherOptHandle
* )
* )
* )
* .then((addr) => window.safeImmutableData.fetch(appHandle, addr))
* .then((idReaderHandle) => console.log('ImmutableData reader handle: ', idReaderHandle));
*/
module.exports.fetch = (appHandle, address) => getObj(appHandle)
.then((obj) => obj.app.immutableData.fetch(address)
.then((imd) => genHandle(obj.app, imd)));
/**
* Append the given data to an ImmutableData.
* @name window.safeImmutableData.write
*
* @param {WriterHandle} writerHandle the ImmutableData Writer handle
* @param {String} string the data to append
*
* @returns {Promise} resolves when finished appending
*
* @example // Write data into an ImmutableData:
* window.safeImmutableData.create(appHandle)
* .then((idWriterHandle) => window.safeImmutableData.write(idWriterHandle, 'my immutable data')
* .then(_ => window.safeCipherOpt.newPlainText(appHandle)
* .then((cipherOptHandle) => window.safeImmutableData.closeWriter(
* idWriterHandle,
* cipherOptHandle
* )
* )
* )
* .then((addr) => console.log('ImmutableData written in the network at: ', addr))
* );
*/
module.exports.write = (writerHandle, string) => getObj(writerHandle)
.then((obj) => obj.netObj.write(string));
/**
* Close and write the ImmutableData to the network.
* Note this operation will free the ImmutableData Writer from the memory
* after the data is written in the network.
* Thus, a new Writer instance shall be created if more writing operations
* into the ImmutableData are required.
* @name window.safeImmutableData.closeWriter
*
* @param {WriterHandle} writerHandle the ImmutableData Writer handle
* @param {CipherOptHandle} cipherOptHandle the handle of the CipherOpt to use for encryption
*
* @returns {Promise<String>} the address to the data once written to the network
*
* @example // Creating an ImmutableData and closing its writer to commit it to the network:
* window.safeImmutableData.create(appHandle)
* .then((idWriterHandle) => window.safeCipherOpt.newPlainText(appHandle)
* .then((cipherOptHandle) => window.safeImmutableData.closeWriter(
* idWriterHandle,
* cipherOptHandle
* )
* )
* .then((addr) => console.log('ImmutableData was stored at address: ', addr))
* );
*/
module.exports.closeWriter = (writerHandle, cipherOptHandle) => getObj(writerHandle)
.then((writerObj) => getObj(cipherOptHandle)
.then((cipherOptObj) => writerObj.netObj.close(cipherOptObj.netObj))
.then((addr) => {
freeObj(writerHandle);
return addr;
})
);
/**
* Read the given amount of bytes from the network
* @name window.safeImmutableData.read
*
* @param {ReaderHandle} readerHandle the ImmutableData Reader handle
* @param {Object=} options reading options
* @param {Number} [options.offset=0] start position
* @param {Number} [options.end=size] end position or end of data
*
* @returns {Promise<String>} the data read
*
* @example // Read data from an ImmutableData:
* window.safeImmutableData.create(appHandle)
* .then((idWriterHandle) => window.safeImmutableData.write(idWriterHandle, 'my immutable data')
* .then(_ => window.safeCipherOpt.newPlainText(appHandle)
* .then((cipherOptHandle) => window.safeImmutableData.closeWriter(
* idWriterHandle,
* cipherOptHandle))
* )
* )
* .then((addr) => window.safeImmutableData.fetch(appHandle, addr))
* .then((idReaderHandle) => window.safeImmutableData.read(idReaderHandle))
* .then((data) => console.log('ImmutableData data read: ', data.toString()));
*/
module.exports.read = (readerHandle, options) => getObj(readerHandle)
.then((obj) => obj.netObj.read(options));
/**
* The size of the mutable data on the network
* @name window.safeImmutableData.size
*
* @param {ReaderHandle} readerHandle the ImmutableData Reader handle
*
* @returns {Promise<Number>} length in bytes
*
* @example // Get the size of an ImmutableData:
* window.safeImmutableData.create(appHandle)
* .then((idWriterHandle) => window.safeImmutableData.write(idWriterHandle, 'my immutable data')
* .then(_ => window.safeCipherOpt.newPlainText(appHandle)
* .then((cipherOptHandle) => window.safeImmutableData.closeWriter(
* idWriterHandle,
* cipherOptHandle))
* )
* )
* .then((addr) => window.safeImmutableData.fetch(appHandle, addr))
* .then((idReaderHandle) => window.safeImmutableData.size(idReaderHandle))
* .then((size) => console.log('Size of the ImmutableData: ', size));
*/
module.exports.size = (readerHandle) => getObj(readerHandle)
.then((obj) => obj.netObj.size());
/**
* Free the ImmutableData Reader instance from memory
* @name window.safeImmutableData.free
*
* @param {ReaderHandle} readerHandle the ImmutableData Reader handle
*
* @example // Freeing immutable data reader object from memory
* window.safeImmutableData.create(appHandle)
* .then((idWriterHandle) => window.safeImmutableData.write(idWriterHandle, 'my immutable data')
* .then(_ => window.safeCipherOpt.newPlainText(appHandle)
* .then((cipherOptHandle) => window.safeImmutableData
* .closeWriter(idWriterHandle, cipherOptHandle))
* )
* )
* .then((addr) => window.safeImmutableData.fetch(appHandle, addr))
* .then((idReaderHandle) => window.safeImmutableData.free(idReaderHandle));
*/
module.exports.free = (readerHandle) => freeObj(readerHandle);
/**
* @name ReaderHandle
* @typedef {String} ReaderHandle
* @description Holds the reference to a ImmutableData Reader instance.
* Note that it is required to free the memory used by such an instance when it's
* not needed anymore by the client aplication, please refer to the `free` function.
*/
/**
* @name WriterHandle
* @typedef {String} WriterHandle
* @description Holds the reference to a ImmutableData Writer instance.
* Note that such an instance it's free from memory when the `close` function
* is invoked.
*/