Deta Drive SDK

The Deta library is the easiest way to store and retrieve files from your Deta Drive. Currently, we support JavaScript, Typescript and Python 3. Drop us a line if you want us to support your favorite language.

Installing#


Using NPM:
npm install deta

Using Yarn:

yarn add deta

Instantiating#

To start working with your Drive, you need to import the Deta class and initialize it with a Project Key. Then instantiate a subclass called Drive with a database name of your choosing.


const { Deta } = require('deta'); // import Deta
// this also works
import { Deta } from 'deta';
// Initialize with a Project Key
const deta = Deta('project key');
// You can create as many as you want
const photos = deta.Drive('photos');
const docs = deta.Drive('docs');
note

If you are using Deta Drive within a Deta Micro, you must include deta in your package.json file to install the lastest sdk version.

A valid project key is pre-set in the Micro's environment. There is no need to pass a key in the initialization step.

const { Drive } = require('deta');
const drive = Drive('simple_drive');
note

If you are using the deta npm package of 0.0.6 or below, Deta is the sinlge default export and should be imported as such.

const Deta = require('deta');
warning

Your project key is confidential and meant to be used by you. Anyone who has your project key can access your database. Please, do not share it or commit it in your code.

Using#

Deta's Drive offres the following methods to interact with your Deta Drive:

put - Stores a file to drive. It will overwrite the file if the file already exists.

get - Retreives a file from drive by the file name.

delete - Deletes a file from drive.

list - Lists the file names in a drive.

Put#

Put uploads and stores a file in a drive with a given name. It will overwrite the file if the file name already exists.

async put(name, options)

Parameters#

  • name (required) - string

    • Description: The name of the file.
  • options (required) - {data : string | Uint8Array | Buffer, path: string, contentType: string}

    • Description: An object with three optional parameters.
      • data - string or Buffer
        • Description: Either the data string or a buffer.
      • path - string
        • Description: The path of the file to be uploaded to drive.
      • contentType - string
        • Description: The content type of the file to be uploaded to drive. If the content type is not provided, drive tries to figure out the content type from the name provided. It defaults to application/octet-stream if the content type can not be figured out from the file name.

    options must have at least and at most one of two properties data or path defined.

Returns#

Returns a promise which resolves to the name of the item on a successful put, otherwise, it throws an Error on error.

Example#

drive.put('hello.txt', {data: "Hello world"});
drive.put('hello.txt', {data: "Hello world", contentType: 'text/plain'});
drive.put('hello.txt', {data: Buffer.from('Hello World'), contentType: 'text/plain'});
drive.put('hello.txt', {path: './my/file/path/file.txt'});
drive.put('hello.txt', {path: './my/file/path/file.txt', contentType: 'text/plain'}});

Get#

Get retreives a file from a drive by its name.

async get(name)

Parameters#

  • name (required) - string
    • Description: The name of the file to get.

Returns#

Returns a promise that resolves to a blob of data if found, else null. Throws an Error on errors.

Example#

const buf = await drive.get('hello.txt');

Delete#

Delete deletes a file from drive.

async delete(name)

Parameters#

  • name (required) - string
    • Description: The name of the file to delete

Returns#

Returns a promise that resolves to the name of the deleted file on successfull deletions, otherwise raises an Error

note

If the file did not exist, the file is still returned as deleted.

Example#

const deletedFile = await drive.delete("hello.txt");

Delete Many#

Deletes multiple files (up to 1000) from a drive.

async deleteMany(names)

Parameters#

  • names (required) - Array of string
    • description: The names of the files to be deleted.

Returns#

Returns a promise which resolves to an object with deleted and failed keys indicating deleted and failed file names.

{
deleted : ["file1.txt", "file2.txt", ...],
failed: {
"file_3.txt": "reason for failure",
}
}
note

If a file did not exist, the file is still returned as deleted.

Example#

const result = await drive.DeleteMany(["file1.txt", "file2.txt"]);
console.log("deleted:", result.deleted)
console.log("failed:", result.failed)

List#

List files in your drive.

async list(options)

Parameters#

  • options (required) : {prefix: string, limit: number, last: string}
    • Description: An object with three optional parameters.
      • prefix: string
        • Description: The prefix that file names must have.
      • limit: number
        • Description: The maximum number of files names to be returned, defaults to 1000
      • last: string
        • Description: The last name seen in a previous paginated result. Provide last to fetch further pages.

Returns#

Returns a promise which resolves to an object with paging and names keys.

{
names: ["file1.txt", "file2.txt", ...],
paging: {
size: 2,
last: "file_2.txt"
}
}
  • names: The names of the files
  • paging: Contains paging information.
    • size : The number of files returned.
    • last : The last name seen in the paginated response. Provide this value in subsequent api calls to fetch further pages. For the last page, last is not present in the response.

Example#

// get all files
let result = await drive.list();
let allFiles = result.names;
let last = result.paging.last;
while (last){
// provide last from previus call
result = await drive.list({last:result.paging.last});
allFiles = allFiles.concat(result.names)
// update last
last = result.paging.last
}
console.log("all files:", allFiles)
const resultWithPrefix = await drive.list({prefix: "blog/"})
const resultWithLimit = await drive.list({limit: 100})
const resultWIthLimitAndPrefix = await drive.list({limit: 100, prefix:"blog/"})