beaker-fs.js

/**
 * Beaker applications that are loaded via dat:// or ipfs:// have a sandboxed `fs` available to them.
 * But, they also need a way to get outside the sandbox, eg to work on a spreadsheet in ~/Documents
 * 
 * This is an API for both use-cases.
 * The application explicitly requests access outside of the sandbox.
 * Those requests result in file-explorer dialogs, to pick the folder or file.
 * The selection then stays in the app's perms until explicitly released, by the app or user.
 **/
 
// overview
// =

beaker.fs.getAppFolder()
beaker.fs.getUserFolders()
beaker.fs.getUserFiles()
beaker.fs.requestFolder([id], promptOptions, cb)
beaker.fs.requestFile([id], flags, promptOptions, cb)
beaker.fs.release(file|folder)

// folder methods
// =
 
// get the app's sandbox folder
// no user-prompt required
var folder = beaker.fs.getAppFolder()

// to get a folder outside of the sandbox, you use this method
// it will prompt the user to choose the directory:
beaker.fs.requestFolder({
  title: 'Documents directory',
  multi: false // allow multiple selections?
}, function (err, folder) {...})

// the folder API comes from the node `fs` library, and includes *Sync variants
// paths are relative (and scoped to) to the folder
folder.appendFile(path, data[, options], callback)
folder.exists(path, callback)
folder.mkdir(path, callback) // differs from node api (mode not included)
folder.open(path[, flags], callback) // differs from node api, see below
folder.readdir(path[, options], callback)
folder.readFile(path[, options], callback)
folder.rename(oldPath, newPath, callback)
folder.rmdir(path, callback)
folder.stat(path, callback)
folder.unlink(path, callback)
folder.writeFile(file, data[, options], callback)


// file methods
// =

// to get a file within one of your folders, use folder.open()
var file = folder.openSync('myfile.txt', 'r+')

// to get a single file outside of the sandbox, you use this method:
beaker.fs.requestFile('r+', {
  type: 'save', // can be 'open' (default) or 'save'
  title: 'Your profile picture',
  filters: [{name: 'Images', extensions: ['jpg', 'png', 'gif']}],
  multi: false, // allow multiple selections?
  defaultPath: folder // can provide a file or folder object to set the starting path
}, function (err, file) {...})

// the file API uses node's `fs` methods, scoped to the file, and includes *Sync variants
// internally, a FD is held until close() is called
file.appendFile(data[, options], callback)
file.close(cb)
file.exists(cb)
file.read(buffer, offset, length, position, callback)
file.readFile([options,] callback)
file.stat(cb)
file.sync(cb)
file.truncate(len, cb)
file.unlink(cb)
file.write(buffer, offset, length[, position], callback)
file.write(data[, position[, encoding]], callback)
file.writeFile(data[, options], callback)

// reopening files/folders after requesting them
// =

// to see which files and folders are currently available to the app:
beaker.fs.getUserFolders()
beaker.fs.getUserFiles()

// all folders and files have an internal id, stored at `folder.id` and `file.id`
// you can fetch by id directly, in the request* methods
// if the id isnt found, it'll fallback to the request prompt:
beaker.fs.requestFile(localStorage.profilePicId, 'r+', {...}, (err, profilePic) => {
  if (profilePic)
    localStorage.profilePicId = profilePic.id
})