dbrowser.dDrive

The dDrive API provides read and write access to ddrives.

You can use the API by instantiating dDrive instances using [.dDrive()] by using the global methods. The global methods can accept paths or URLs. If you pass a path into a global method, the current dDrive will be used as the target. For example, if you were on a dDrive dweb://foobar/, the following three would be equivalent:

await dbrowser.dDrive.readdir('/')

await dbrowser.dDrive.readdir('dweb://foobar/')

await dbrowser.dDrive.dDrive('dweb://foobar/').readdir('/')

A dDrive is always allowed to read and write its own files. Applications must ask permission before writing to other ddrives.

API

dbrowser.dDrive.dDrive(url)

Create a dDrive instance. The instance provides most methods in dbrowser.dDrive but scoped to the given dDrive's URL. Unlike the unscoped dbrowser.dDrive calls, only paths can be provided to the operations.

• url String. The URL of the dDrive to access.
• Returns dDrive.
  • url String. The URL of the dDrive.
  • version String. The checked-out version of the instance. Will be undefined if using latest.
  • checkout(version): dDrive. Returns a dDrive instance at the given version.
  • watch(path, onChanged): EventTarget. Emits a 'changed' event when writes occur. Does not emit any change events for mounted drives within the parent dDrive.
  • ...most methods on dbrowser.dDrive.

var dDrive = dbrowser.dDrive.dDrive('dweb://1234..ef')

await dDrive.readdir('/')

dbrowser.dDrive.createDrive([settings])

Create a new dDrive.

• settings Object.
  • title String. The title of the dDrive.
  • description String. The description of the dDrive.
  • prompt Boolean. Should the creation prompt show? If false, permission will still be requested.
• Returns Promise<dDrive>.

var dDrive = await dbrowser.dDrive.createDrive({

title: 'My cool website',

description: 'Demonstrating how to create dDrives'

})

dbrowser.dDrive.forkDrive(url[, opts])

Creates a "fork or copy dDrive" prompt. The user will use this to copy the files and settings of a dDrive into a new dDrive, optionally overriding some settings.

• url String. The URL of the dDrive to fork.
• opts Object.
  • detached Boolean. If false, will create an "attached" fork. If true, will create a detached copy. Default false.
  • title String. Overrides the title. Only applies if detached is true.
  • description String. Overrides the description. Only applies if detached is true.
  • prompt Boolean. If true, shows the "fork" modal. If false, only asks the user for permission. Default true.
• Returns Promise<dDrive>.

var myFork = await dbrowser.dDrive.forkDrive(existingDriveUrl)

var myCopy = await dbrowser.dDrive.forkDrive(existingDriveUrl, {detached: true})

dbrowser.dDrive.getInfo(url[, opts])

Fetch metadata and system information about the dDrive.

• url String. The URL of the dDrive to query. (Not required on dDrive objects returned by [dbrowser.dDrive.dDrive()]
• opts Object.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Object>.
  • key String. The key of the dDrive.
  • url String. The URL of the dDrive.
  • writable Boolean. Can the local user modify the dDrive?
  • version Number. The latest revision number of the dDrive.
  • title String. The title of the dDrive.
  • description String. The description of the dDrive.

var info = await dbrowser.dDrive.getInfo('dweb://1234..ef')

dbrowser.dDrive.stat(url[, opts])

Get metadata about a file.

• url String. The url to the file.
• opts Object.
  • lstat Boolean. If the file is a symlink, give information about the symlink instead of the link target.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Object>.
  • isFile() Function(): Boolean. Is the entry a file?
  • isDirectory() Function(): Boolean. Is the entry a directory?
  • size Number. The size of the file in bytes.
  • blocks Number. The size of the file in blocks in the content hypercore.
  • mtime Number. The timestamp of the last modification of the file.
  • ctime Number. The timestamp of the creation of the file.
  • mount Object. Information about the target mount if the entry is a mount.
    • key String. The key of the mount target.
    • version Number. The version of the mount target, if specified.
  • metadata Object. User metadata attached to the entry.
  • linkname String. If a symlink, gives the target path.

var stat = await dbrowser.dDrive.stat('dweb://1234..ef/index.json')

dbrowser.dDrive.readFile(url[, opts])

Read the contents of a file.

• url String. The url to the file.
• opts Object | String. If a String, will act as the 'encoding' option.
  • encoding String. Desired output encoding. May be 'binary', 'utf8', 'hex', 'json', or 'base64'. Default 'utf8'.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<String | Uint8Array>

var fileStr = await dbrowser.dDrive.readFile('dweb://1234..ef/foo.txt')

var fileObj = await dbrowser.dDrive.readFile('dweb://1234..ef/foo.json', 'json')

var imgBuf = await dbrowser.dDrive.readFile('dweb://1234..ef/bar.png', 'binary')

var imgBase64 = await dbrowser.dDrive.readFile('dweb://1234..ef/bar.png', 'base64')

dbrowser.dDrive.readdir(url[, opts])

Read the contents of a directory.

• url String. The url to the directory.
• opts Object.
  • includeStats Boolean. Should the output include the 'stats' object for each entry?
  • recursive Boolean. Recurse into subfolders?
    • Note: does not recurse into child mounts.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Array<String | Object>>
  • If an object, the shape will be { name, stat }

var files = await dbrowser.dDrive.readdir('dweb://1234..ef/')

var allFiles = await dbrowser.dDrive.readdir('dweb://1234..ef/', {recursive: true})

var filesWithStats = await dbrowser.dDrive.readdir('dweb://1234..ef/', {includeStats: true})

dbrowser.dDrive.query(query)

Read the contents of a dDrive or drives across multiple specified paths. This function can be used to read a wide range of files while filtering by multiple various attributes. If dDrive were a SQL database, this would be the SELECT function.

• query Object.
  • dDrive String | Array<String>. The dDrive(s) to query against.
  • path String | Array<String>. The path(s) to query against. May use globbing patterns ('*') to specify multiple files.
  • type String. Filters results to entries of this type. May be 'file', 'directory', or 'mount'.
  • mount String (URL). Filters results to mounts which point to the dDrive specified here.
  • metadata Object. Filters results by their metadata against the key-values specified here.
  • sort String. Specifies which attribute to sort the results by. May be 'name', 'ctime', or 'mtime'.
  • reverse Boolean. If true, the result order will be reversed.
  • limit Number. Specifies a maximum number of results to return.
  • offset Number. Specifies a starting offset within the results. Used for pagination.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Array<Object>>
  • type String. The type of the entry. Must be 'file', 'directory', or 'mount'.
  • path String. The path of the entry relative to the queried dDrive.
  • url String. The URL of the entry relative to the queried dDrive.
  • stat Object. The entry's Stat object, see stat().
  • dDrive String. The URL of the queried dDrive.
  • mount String. The URL of the target dDrive if the entry is a mount.
  • origin Object.
    • path String. The path of the entry relative to its owning dDrive.
    • dDrive String. The URL of the entry's owning dDrive.
    • url String. The URL of the entry relative to its owning dDrive.

var rootFiles = await dbrowser.dDrive.query({

dDrive: 'dweb://1234..ef',

path: '/*',

type: 'file'

})

var rootImgs = await dbrowser.dDrive.query({

dDrive: 'dweb://1234..ef',

path: ['/*.png', '/*.jpg', '/*.jpeg']

})

var postFiles = await dbrowser.dDrive.query({

dDrive: 'dweb://1234..ef',

path: '/microblog/*',

sort: 'ctime'

})

var followMounts = await dbrowser.dDrive.query({

dDrive: 'dweb://1234..ef',

path: '/follows/*',

type: 'mount'

})

var bobFollow = await dbrowser.dDrive.query({

dDrive: 'dweb://1234..ef',

path: '/follows/*',

mount: bobsUrl

})

var commentsOnBeaker = await dbrowser.dDrive.query({

dDrive: 'dweb://1234..ef',

path: '/comments/*',

metadata: {href: 'https://dbrowser.com'}

})

dbrowser.dDrive.diff(url, other[, prefix, opts])

List the changes that have occurred between two versions of the dDrive.

Note: this method can only compare drives to other versions of itself. It cannot be used to compare two different drives.

• url String. The URL to diff.
• other Number|String|dDrive. The version ID or dDrive instance to compare against.
• opts Object.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Array<Object>>
  • type String. What operation occurred. One of: 'put', 'del', 'mount', 'unmount'.
  • name String. The path of the modified entry.
  • value Object. Information related to the change (e.g. the 'stat' object of a put file).

var changes = await dbrowser.dDrive.diff('dweb://1234..ef', 5) // diff latest against revision 5

dbrowser.dDrive.configure(url, settings[, opts])

Update the settings and/or manifest (index.json) of the dDrive.

• url String. The URL of the dDrive to configure.
• settings Object.
  • title String. The title of the dDrive.
  • description String. The description of the dDrive.
• opts Object.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Void>

await dbrowser.dDrive.configure('dweb://1234..ef', {

title: 'The dDrive title',

description: 'The dDrive description'

})

dbrowser.dDrive.writeFile(url, data[, opts])

Write a file to the dDrive.

• url String. The URL of the file to write.
• data String|Uint8Array. The content to write.
• opts String|Object. If a string, acts as the encoding parameter.
  • encoding String. The encoding of the data parameter. Must be 'utf8', 'base64', 'hex', 'json', or 'binary'. Defaults to 'utf8' if data is a string and 'binary' if data is an Uint8Array.
  • metadata Object. The metadata to write to the file. Even if unspecified
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Void>

await dbrowser.dDrive.writeFile('dweb://1234..ef/foo.txt', 'Foo')

await dbrowser.dDrive.writeFile('dweb://1234..ef/foo.json', {hello: 'world'}, 'json')

await dbrowser.dDrive.writeFile('dweb://1234..ef/foo.png', imgPngBase64, 'base64')

await dbrowser.dDrive.writeFile('dweb://1234..ef/foo.jpg', imgJpgUint8Array, {encoding: 'binary'})

await dbrowser.dDrive.writeFile('dweb://1234..ef/foo.md', '# Markdown Doc', {

metadata: {title: 'Markdown Doc'}

})

dbrowser.dDrive.mkdir(url[, opts])

Create a folder on the dDrive.

• url String. The URL of the folder to create.
• opts Object.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Void>

await dbrowser.dDrive.mkdir('dweb://1234..ef/sub')

dbrowser.dDrive.symlink(target, url[, opts])

Create a symlink on the dDrive. Good luck getting the argument order right the first time!

• target String. The URL which the symlink should point to.
• url String. Where to place the symlink.
• opts Object.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Void>

await dbrowser.dDrive.symlink('dweb://1234..ef/this-file-already-exists.txt', 'dweb://1234..ef/the-symlink.txt')

dbrowser.dDrive.mount(url, mount[, opts])

Create a mount on the dDrive to some other dDrive. (Mounts are like symlinks that work across ddrives.) Note: we know, we know, the argument order is the opposite of symlink.

• url String. Where to place the mount.
• mount String|Object|dDrive. The dDrive to mount. If a String or dDrive, acts as the key attribute.
  • key String. The key of the dDrive to mount.
  • version Number|String. The version to pin the mount to. If undefined, the mount will point to latest.
• opts Object.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Void>

await dbrowser.dDrive.mount('dweb://1234..ef/mount', 'dweb://fedcb..12')

await dbrowser.dDrive.mount('dweb://1234..ef/mount2', {key: 'fedcb..12', version: 10})

dbrowser.dDrive.copy(src, dst[, opts])

Copy a file or folder. Works across ddrives.

• src String. Where to copy the files from.
• dst String. Where to copy the files to.
• opts Object.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Void>

await dbrowser.dDrive.copy('dweb://1234..ef/foo.txt', 'dweb://1234..ef/bar.txt')

dbrowser.dDrive.rename(src, dst[, opts])

Move a file or folder. Works across ddrives.

• src String. Where to move the files from.
• dst String. Where to move the files to.
• opts Object.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Void>

await dbrowser.dDrive.rename('dweb://1234..af/foo.txt', 'dweb://1234..af/bar.txt')

dbrowser.dDrive.updateMetadata(url, metadata[, opts])

Modify the metadata on a file. Merges into the existing metadata of the file.

• url String. The URL of the file to modify.
• metadata Object. The metadata values to set.
• opts Object.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Void>

await dbrowser.dDrive.updateMetadata('dweb://1234..ef/foo.txt', {title: 'Foo'})

dbrowser.dDrive.unlink(url[, opts])

Deletes a file on the dDrive.

• url String. The URL of the file to delete.
• opts Object.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Void>

await dbrowser.dDrive.unlink('dweb://1234..ef/foo.txt')

dbrowser.dDrive.rmdir(url[, opts])

Deletes a folder on the dDrive.

• url String. The URL of the folder to delete.
• opts Object.
  • recursive Boolean. Delete the files within the folder if it's not empty. Default false.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Void>

await dbrowser.dDrive.rmdir('dweb://1234..ef/sub')

await dbrowser.dDrive.rmdir('dweb://1234..ef/sub2', {recursive: true})

dbrowser.dDrive.unmount(url[, opts])

Remove a mount on the dDrive.

• url String. The URL of the mount to delete.
• opts Object.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Void>

await dbrowser.dDrive.unmount('dweb://1234..ef/mount')

dbrowser.dDrive.deleteMetadata(url, keys[, opts])

Remove metadata keys from the file.

• url String. The URL of the file to modify.
• keys String|Array<String>. The key or keys to delete.
• opts Object.
  • timeout Number (ms). How long to wait for the operation to complete before throwing a timeout error. Defaults to 60000.
• Returns Promise<Void>

await dbrowser.dDrive.deleteMetadata('dweb://1234..ef/foo.txt', 'title')

await dbrowser.dDrive.deleteMetadata('dweb://1234..ef/bar.txt', ['title', 'href'])