Dat API

Summary. Read and write versioned files to sites on the user's local hard-drive, and share the sites over the network.

Note


Example Usage

Dat sites can be used to save data locally for an application, or to publish on the network.

// Create a new site
var datUrl = await dat.createSite({ title: 'My Dat' })
datUrl // => 'dat://{hash}/'

// Read/write files
await dat.writeFile(datUrl + 'hello.txt', 'world')
var str = await dat.readFile(datUrl + 'hello.txt')
console.log(str) // => 'world'

Permissions

This API is only available to apps served over dat://. By default, any dat:// app can read other dat-sites via HTML embeds, Ajax, or the dat read commands.

An app can write to sites that it created. The user will be prompted to confirm permission to:

  1. Create a new dat site
  2. Modify a dat site created by another site

The user must be the owner of a dat site to modify it.


Disk Usage and Quotas

Sites are either permanent or temporary. Sites that are created via the dat api are permanent. All other sites (downloaded by browsing, HTML embeds, or Ajax) are temporary and may be automatically deleted. A permanent site can be made temporary by calling dat.deleteSite() on it.

By default, sites are limited to 100MB of storage. When the limit is reached, the user will be prompted to allow more disk-usage. Until this is granted, all writes will fail.


Versioning

Dat Sites retain a log of all changes to the archive, which is accessible via getHistory(). By default, only the latest versions of the files are retained. When a checkpoint is written, the files’ contents are captured and retained.

Checkpoint names must be unique and cannot be reused. It’s recommended that you follow semantic versioning, but this is not required.


Networking

All dat sites have URLs and can be distributed over the network.

An site which is opened from the network is downloaded and stored locally, and then updated in the background. The site’s contents may not always be findable on the network. The connection may fail, or the server could go offline. This will manifest as timeouts to the read calls. You can configure the timeout length in the call arguments.


Special Files

The dat.json file is special, and can not be read or written directly by the application. It is a manifest file that includes metadata and configuration.


Toplevel Methods

dat.createSite()

dat.createSite(opts?: Object): Promise<string>

Alias: dat.createArchive

Create a new dat archive, and return the URL. The archive is sandboxed to only access to files within it.

  • opts.title. String. The title of the new archive.
  • opts.description. String. The description of the new archive.

dat.deleteSite()

dat.deleteSite(url: string): void

Alias: dat.deleteArchive

Mark the given archive for deletion. The archive will not be deleted immediately, but put into the cache system where it can be cleaned.


dat.stat()

dat.stat(url: string, opts?: Object): Promise<Object>

Fetches information about the file or directory at ‘path’. The promise will reject if no file or directory is found.

  • url. The URL of the file/directory to stat. This must be a dat:// URL.
  • opts.version. String. Which version of the file to read? Refers to the name of a checkpoint. If unspecified, defaults to latest.
  • opts.downloadedBlocks. Boolean. Count how many blocks are downloaded? Causes the downloadedBlocks attribute to be populated. Default false.
  • opts.timeout. Number. How long, in ms, to wait for a response? Default 5000.

Return object:

{
  type: string ('file' or 'directory'),
  name: string (the full path),
  size: number (bytes),
  blocks: number (blocks),
  downloadedBlocks: number (blocks, optional),
  mtime: number (timestamp) the last modification time
}

If the archive is not found on the network, or in the local cache, this call will timeout.


dat.exists()

dat.stat(url: string): Promise<Boolean>

Returns true/false if the given file is known to exist.

  • url. The URL of the file/directory to look for. This must be a dat:// URL.

If the archive is not found on the network, or in the local cache, this call will timeout.


dat.readFile()

dat.readFile(url: string, opts?: String|Object):
  Promise<string|ArrayBuffer>

Reads the file’s contents.

  • url. The URL of the file to read. This must be a dat:// URL.
  • opts.version. String. Which version of the file to read? Refers to the name of a checkpoint. If unspecified, defaults to latest.
  • opts.encoding
    • ‘utf8’ / ‘utf-8’ (default). Return value will be a string.
    • ‘base64’. Return value will be a string.
    • ‘hex’. Return value will be a string.
    • ‘binary’. Return value will be an ArrayBuffer.
    • If opts is a string, it is specifying the encoding.
  • opts.timeout. Number. How long, in ms, to wait for a response? Default 5000.
dat.readFile('dat://.../picture.png').then(arrayBuf => {
  var blob = new Blob([arrayBuf], {type: 'image/png'})
  document.querySelector('img').src = URL.createObjectURL(blob)
})

dat.readFile('dat:/.../picture.png', 'base64').then(str => {
  document.querySelector('img').src = 'data:image/png;base64,'+str
})

If the archive is not found on the network, or in the local cache, this call will timeout.


dat.listFiles()

dat.listFiles(url: string, opts?: Object): Promise<Array<String>>

Alias: dat.readDirectory

Reads the contents of a directory. Returns an object listing the files and folders in the directory, excluding ‘.’ and ‘..’.

  • url. The URL of the directory to read. This must be a dat:// URL.
  • opts.version. String. Which version of the file to read? Refers to the name of a checkpoint. If unspecified, defaults to latest.
  • opts.timeout. Number. How long, in ms, to wait for a response? Default 5000.

dat.writeFile()

dat.writeFile(url: string, data: string|ArrayBuffer, opts?: Object|String): Promise<void>

Replaces the file’s contents with ‘data’. The promise will reject if there is already a directory at ‘url’, or if the containing directory-tree does not yet exist.

  • url. The URL of the file to write. This must be a dat:// URL.
  • data. The data to be written.
  • opts.encoding
    • ‘utf8’ / ‘utf-8’. Data must be a string. (This is the default value if data is a string.)
    • ‘base64’. Data must be a string.
    • ‘hex’. Data must be a string.
    • ‘binary’. Data must be an ArrayBuffer. (This is the default value if data is an ArrayBuffer.)
    • If opts is a string, it is specifying the encoding.

The app must be the creator of the archive to be granted permission.

dat.writeFile('dat://.../hello.txt', 'world', 'utf8').then(...)

dat.createDirectory()

dat.createDirectory(url: string): Promise<void>

Creates a new directory at ‘url’. The promise will reject if there is already a file or directory at ‘url’, or if the containing directory-tree does not yet exist.

  • url. The URL of the directory to create. This must be a dat:// URL.

The app must be the creator of the archive to be granted permission.