0
# GridFS File Storage
1

2
GridFS operations for storing and retrieving large files in MongoDB with streaming support.
3

4
## Capabilities
5

6
### GridStore Instance Creation
7

8
Create GridStore instances through the database interface.
9

10
```javascript { .api }
11
/**
12
 * Create GridStore instance for file operations
13
 * @param {string} filename - Name of the file
14
 * @param {string} mode - File mode ('r', 'w', 'w+')
15
 * @param {object} [options] - GridStore options
16
 * @returns {SkinGridStore} GridStore instance
17
 */
18
db.gridStore(filename, mode, options);
19
```
20

21
### Static File Operations
22

23
Static methods for common file operations without creating GridStore instances.
24

25
```javascript { .api }
26
/**
27
 * Check if file exists in GridFS
28
 * @param {SkinDb} db - Database instance
29
 * @param {string} filename - Name of the file
30
 * @param {function} callback - Callback function (err, exists)
31
 * @returns {void}
32
 */
33
GridStore.exist(db, filename, callback);
34

35
/**
36
 * List all files in GridFS
37
 * @param {SkinDb} db - Database instance
38
 * @param {function} callback - Callback function (err, files)
39
 * @returns {void}
40
 */
41
GridStore.list(db, callback);
42

43
/**
44
 * Read entire file from GridFS
45
 * @param {SkinDb} db - Database instance
46
 * @param {string} filename - Name of the file
47
 * @param {function} callback - Callback function (err, data)
48
 * @returns {void}
49
 */
50
GridStore.read(db, filename, callback);
51

52
/**
53
 * Read file lines from GridFS
54
 * @param {SkinDb} db - Database instance
55
 * @param {string} filename - Name of the file
56
 * @param {function} callback - Callback function (err, lines)
57
 * @returns {void}
58
 */
59
GridStore.readlines(db, filename, callback);
60

61
/**
62
 * Delete file from GridFS
63
 * @param {SkinDb} db - Database instance
64
 * @param {string} filename - Name of the file
65
 * @param {function} callback - Callback function (err, result)
66
 * @returns {void}
67
 */
68
GridStore.unlink(db, filename, callback);
69
```
70

71
**Usage Examples:**
72

73
```javascript
74
const mongoskin = require('mongoskin');
75
const db = mongoskin.db('mongodb://localhost:27017/myapp');
76

77
// Check if file exists
78
mongoskin.GridStore.exist(db, 'myfile.txt', (err, exists) => {
79
  if (err) throw err;
80
  console.log('File exists:', exists);
81
});
82

83
// List all files
84
mongoskin.GridStore.list(db, (err, files) => {
85
  if (err) throw err;
86
  console.log('Files in GridFS:');
87
  files.forEach(file => console.log(`- ${file.filename} (${file.length} bytes)`));
88
});
89

90
// Read entire file
91
mongoskin.GridStore.read(db, 'document.pdf', (err, data) => {
92
  if (err) throw err;
93
  console.log('Read', data.length, 'bytes from document.pdf');
94
  // data is a Buffer containing the file contents
95
});
96

97
// Read file as lines
98
mongoskin.GridStore.readlines(db, 'textfile.txt', (err, lines) => {
99
  if (err) throw err;
100
  console.log('File lines:');
101
  lines.forEach((line, index) => console.log(`${index + 1}: ${line}`));
102
});
103

104
// Delete file
105
mongoskin.GridStore.unlink(db, 'oldfile.txt', (err, result) => {
106
  if (err) throw err;
107
  console.log('File deleted:', result);
108
});
109
```
110

111
### File Writing Operations
112

113
Instance methods for writing files to GridFS.
114

115
```javascript { .api }
116
/**
117
 * Open GridStore for file operations
118
 * @param {function} callback - Callback function (err, gridStore)
119
 * @returns {void}
120
 */
121
open(callback);
122

123
/**
124
 * Write data to GridStore
125
 * @param {string|Buffer} data - Data to write
126
 * @param {function} callback - Callback function (err, gridStore)
127
 * @returns {void}
128
 */
129
write(data, callback);
130

131
/**
132
 * Write file from file system to GridFS
133
 * @param {string} file - Path to source file
134
 * @param {function} callback - Callback function (err, result)
135
 * @returns {void}
136
 */
137
writeFile(file, callback);
138

139
/**
140
 * Close GridStore and finalize file
141
 * @param {function} callback - Callback function (err, result)  
142
 * @returns {void}
143
 */
144
close(callback);
145
```
146

147
**Usage Examples:**
148

149
```javascript
150
const mongoskin = require('mongoskin');
151
const db = mongoskin.db('mongodb://localhost:27017/myapp');
152

153
// Write text data to GridFS
154
const gridStore = db.gridStore('mytext.txt', 'w');
155
gridStore.open((err, gs) => {
156
  if (err) throw err;
157
  
158
  gs.write('Hello, GridFS world!', (err, gs) => {
159
    if (err) throw err;
160
    
161
    gs.close((err, result) => {
162
      if (err) throw err;
163
      console.log('File written successfully:', result);
164
    });
165
  });
166
});
167

168
// Write binary data
169
const gridStore2 = db.gridStore('binary.dat', 'w');
170
gridStore2.open((err, gs) => {
171
  if (err) throw err;
172
  
173
  const binaryData = Buffer.from([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
174
  gs.write(binaryData, (err, gs) => {
175
    if (err) throw err;
176
    gs.close((err, result) => {
177
      if (err) throw err;
178
      console.log('Binary file written');
179
    });
180
  });
181
});
182

183
// Write file from filesystem
184
const gridStore3 = db.gridStore('uploaded.jpg', 'w');
185
gridStore3.writeFile('/path/to/source/image.jpg', (err, result) => {
186
  if (err) throw err;
187
  console.log('File uploaded to GridFS:', result);
188
});
189
```
190

191
### File Reading Operations
192

193
Instance methods for reading files from GridFS.
194

195
```javascript { .api }
196
/**
197
 * Read data from GridStore
198
 * @param {number} [length] - Number of bytes to read
199
 * @param {function} callback - Callback function (err, data)
200
 * @returns {void}
201
 */
202
read(length, callback);
203

204
/**
205
 * Read file to filesystem
206
 * @param {string} filename - Destination file path
207
 * @param {function} callback - Callback function (err, result)
208
 * @returns {void}
209
 */
210
readFile(filename, callback);
211

212
/**
213
 * Seek to position in file
214
 * @param {number} position - Byte position to seek to
215
 * @param {function} callback - Callback function (err, gridStore)
216
 * @returns {void}
217
 */
218
seek(position, callback);
219

220
/**
221
 * Get current position in file
222
 * @returns {number} Current position
223
 */
224
tell();
225

226
/**
227
 * Rewind to beginning of file
228
 * @param {function} callback - Callback function (err, gridStore)
229
 * @returns {void}
230
 */
231
rewind(callback);
232
```
233

234
**Usage Examples:**
235

236
```javascript
237
const mongoskin = require('mongoskin');
238
const db = mongoskin.db('mongodb://localhost:27017/myapp');
239

240
// Read file data
241
const gridStore = db.gridStore('mytext.txt', 'r');
242
gridStore.open((err, gs) => {
243
  if (err) throw err;
244
  
245
  gs.read((err, data) => {
246
    if (err) throw err;
247
    console.log('File contents:', data.toString());
248
    gs.close();
249
  });
250
});
251

252
// Read partial data
253
const gridStore2 = db.gridStore('largefile.dat', 'r');
254
gridStore2.open((err, gs) => {
255
  if (err) throw err;
256
  
257
  // Read first 100 bytes
258
  gs.read(100, (err, data) => {
259
    if (err) throw err;
260
    console.log('First 100 bytes:', data.length);
261
    gs.close();
262
  });
263
});
264

265
// Save GridFS file to filesystem
266
const gridStore3 = db.gridStore('document.pdf', 'r');
267
gridStore3.readFile('/tmp/downloaded.pdf', (err, result) => {
268
  if (err) throw err;
269
  console.log('File downloaded to /tmp/downloaded.pdf');
270
});
271

272
// Seek and read
273
const gridStore4 = db.gridStore('datafile.bin', 'r');
274
gridStore4.open((err, gs) => {
275
  if (err) throw err;
276
  
277
  gs.seek(1000, (err, gs) => {
278
    if (err) throw err;
279
    
280
    console.log('Current position:', gs.tell());
281
    gs.read(50, (err, data) => {
282
      if (err) throw err;
283
      console.log('Data at position 1000:', data);
284
      gs.close();
285
    });
286
  });
287
});
288
```
289

290
### Stream Operations
291

292
Stream-based operations for efficient handling of large files.
293

294
```javascript { .api }
295
/**
296
 * Create readable stream from GridStore
297
 * @param {boolean} [autoclose] - Auto-close stream when done
298
 * @returns {Stream} Readable stream
299
 */
300
stream(autoclose);
301

302
/**
303
 * Create writable stream to GridStore
304
 * @returns {Stream} Writable stream
305
 */
306
writeStream();
307
```
308

309
**Usage Examples:**
310

311
```javascript
312
const mongoskin = require('mongoskin');
313
const fs = require('fs');
314
const db = mongoskin.db('mongodb://localhost:27017/myapp');
315

316
// Stream file from GridFS to filesystem
317
const gridStore = db.gridStore('largefile.mp4', 'r');
318
gridStore.open((err, gs) => {
319
  if (err) throw err;
320
  
321
  const readStream = gs.stream(true);
322
  const writeStream = fs.createWriteStream('/tmp/output.mp4');
323
  
324
  readStream.pipe(writeStream);
325
  
326
  writeStream.on('close', () => {
327
    console.log('File streamed successfully');
328
  });
329
});
330

331
// Stream file from filesystem to GridFS
332
const gridStore2 = db.gridStore('upload.zip', 'w');
333
gridStore2.open((err, gs) => {
334
  if (err) throw err;
335
  
336
  const readStream = fs.createReadStream('/path/to/large/file.zip');
337
  const writeStream = gs.writeStream();
338
  
339
  readStream.pipe(writeStream);
340
  
341
  writeStream.on('close', () => {
342
    console.log('File uploaded via stream');
343
  });
344
});
345
```
346

347
### File Metadata Operations
348

349
Operations for managing file metadata and properties.
350

351
```javascript { .api }
352
/**
353
 * Get file information and metadata
354
 * @param {function} callback - Callback function (err, fileInfo)
355
 * @returns {void}
356
 */
357
metadata(callback);
358

359
/**
360
 * Set file metadata
361
 * @param {object} metadata - Metadata object
362
 * @param {function} callback - Callback function (err, result)
363
 * @returns {void}
364
 */
365
setMetadata(metadata, callback);
366

367
/**
368
 * Get file length
369
 * @returns {number} File length in bytes
370
 */
371
length;
372

373
/**
374
 * Get file content type
375
 * @returns {string} Content type
376
 */
377
contentType;
378

379
/**
380
 * Get file upload date
381
 * @returns {Date} Upload date
382
 */
383
uploadDate;
384

385
/**
386
 * Get file MD5 checksum
387
 * @returns {string} MD5 hash
388
 */
389
md5;
390
```
391

392
**Usage Examples:**
393

394
```javascript
395
const mongoskin = require('mongoskin');
396
const db = mongoskin.db('mongodb://localhost:27017/myapp');
397

398
// Get file metadata
399
const gridStore = db.gridStore('document.pdf', 'r');
400
gridStore.open((err, gs) => {
401
  if (err) throw err;
402
  
403
  console.log('File length:', gs.length);
404
  console.log('Content type:', gs.contentType);
405
  console.log('Upload date:', gs.uploadDate);
406
  console.log('MD5 checksum:', gs.md5);
407
  
408
  gs.metadata((err, metadata) => {
409
    if (err) throw err;
410
    console.log('File metadata:', metadata);
411
    gs.close();
412
  });
413
});
414

415
// Set custom metadata
416
const gridStore2 = db.gridStore('photo.jpg', 'w');
417
gridStore2.open((err, gs) => {
418
  if (err) throw err;
419
  
420
  gs.setMetadata({
421
    author: 'John Doe',
422
    camera: 'Canon EOS',
423
    location: 'New York'
424
  }, (err, result) => {
425
    if (err) throw err;
426
    
427
    // Write image data
428
    const imageData = fs.readFileSync('/path/to/photo.jpg');
429
    gs.write(imageData, (err, gs) => {
430
      if (err) throw err;
431
      gs.close((err, result) => {
432
        if (err) throw err;
433
        console.log('Photo uploaded with metadata');
434
      });
435
    });
436
  });
437
});
438
```
439

440
### GridFS Collections
441

442
Direct access to GridFS collections for advanced operations.
443

444
```javascript { .api }
445
/**
446
 * Get GridFS files collection
447
 * @returns {Collection} Files collection (fs.files)
448
 */
449
files();
450

451
/**
452
 * Get GridFS chunks collection  
453
 * @returns {Collection} Chunks collection (fs.chunks)
454
 */
455
chunks();
456
```
457

458
**Usage Examples:**
459

460
```javascript
461
const db = mongoskin.db('mongodb://localhost:27017/myapp');
462

463
// Query files collection directly
464
const filesCollection = db.collection('fs.files');
465
filesCollection.findItems({ filename: /\.jpg$/ }, (err, imageFiles) => {
466
  if (err) throw err;
467
  console.log('Image files in GridFS:');
468
  imageFiles.forEach(file => {
469
    console.log(`- ${file.filename} (${file.length} bytes)`);
470
  });
471
});
472

473
// Query chunks for a specific file
474
const chunksCollection = db.collection('fs.chunks');
475
chunksCollection.findItems({ files_id: someFileId }, (err, chunks) => {
476
  if (err) throw err;
477
  console.log(`File has ${chunks.length} chunks`);
478
});
479
```