> For the complete documentation index, see [llms.txt](https://rednexie.gitbook.io/permadb/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rednexie.gitbook.io/permadb/nodejs.md).

# Node.js

Documentation for the npm package 'perma.db'

## PermaDB 

PermaDB is a versatile and easy to use database management library that aims to be fast, and save space.

## v1.0.9 API

## class PermaDB

Importing the class from the module.

```js
const { PermaDB } = require("perma.db")
```

<br>

### new PermaDB(db\_name, \[options])

**Returns** [**database**](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#database)

By creating a new instance of the PermaDB class, you create and open a new sqlite3 database.\
You can customize the options of the database with arguments.

***

**db\_name**

*String*

The database name to be created. Default is `perma.db`.

**options**

*Object*

*memory* Boolean

`options.memory` specifies if the db works both with the database file and on memory. Default is `false`.

*minimize* Boolean

`options.minimize` specifies if the db will automatically perform *vacuum* operations. Default is `false`.

*preload* Boolean

`options.preload` specifies if all database should be loaded to the memory. Only considered if the `options.memory` is `true`. Default is `false`.

## database

Creating the instance of class PermaDB imported from perma.db.

```js
const database = new PermaDB();
```

`new PermaDB(db_name, [options]): database`

### Synchronous Methods

* [database#setSync](#setsync-key-value)
* [database#getSync](#getsync-key)
* [database#fetchSync](#fetchsync-key)
* [database#updateSync](#updatesync-key-value)
* [database#hasSync](#hassync-key)
* [database#deleteSync](#deletesync-key)
* [database#removeSync](#removesync-key)
* [database#typeSync](#typesync-key)
* [database#allSync](#allsync-key)
* [database#fetchAllSync](#fetchallsync)
* [database#deleteAllSync](#deleteallsync)
* [database#clearSync](#clearsync)
* [database#removeAllSync](#removeallsync)
* [database#removeDBSync](#removedbsync)
* [database#vacuumSync](#vacuumsync)
* [database#backupSync](#backupsync-path)
* [database#querySync](#querysync-sql-...params)
* [database#sizeSync](#sizesync)
* [database#fileSizeSync](#filesizesync)
* [database#keysSync](#keyssync)
* [database#valuesSync](#valuessync)
* [database#objectSync](#objectsync)
* [database#execSync](#execsync-cmd)
* [database#closeSync](#closesync)
* [database#expireSync](#expiresync-key-time)
* [database#lengthSync](#lengthsync)

#### setSync(key, value)

Defined in [perma.db/lib/index.js#setSync](https://github.com/Rednexie/perma.db/blob/d5f76f325098baeb14827fe48f756967f649bb17/lib/src/index.js#L141)

`setSync(key, value): value`

Stores the value in the database, so you can access it with the key after.

*key* String

*value* Buffer || String || Date || Number || null

returns Buffer || String || Date || Number || null

#### getSync(key)

Defined in [perma.db/lib/index.js#getSync](https://github.com/Rednexie/perma.db/blob/d5f76f325098baeb14827fe48f756967f649bb17/lib/src/index.js#L150)

`getSync(key): value`

Gets the value with the given key in the database.

*key* String

*returns* Buffer || String || Date || Number || null

#### fetchSync(key)

Defined in [perma.db/lib/index.js#fetchSync](https://github.com/Rednexie/perma.db/blob/d5f76f325098baeb14827fe48f756967f649bb17/lib/src/index.js#L157)

`fetchSync(key): value`

Gets the value with the given key in the database.&#x20;

returns Buffer || String || Date || Number || null

*key* String\
\
*returns* Buffer || String || Date || Number || null

#### updateSync(key, value)

Defined in [perma.db/lib/index.js#updateSync](https://github.com/Rednexie/perma.db/blob/d5f76f325098baeb14827fe48f756967f649bb17/lib/src/index.js#L123)

`updateSync(key, value): changed`

If the given key exists in the database, changes its value and returns `true`. If it doesn't exist, returns `false`.

*key* String

*value* Buffer || String || Date || Number || null\
\
*returns* Boolean

#### hasSync(key)

Defined in [perma.db/lib/index.js#hasSync](https://github.com/Rednexie/perma.db/blob/d5f76f325098baeb14827fe48f756967f649bb17/lib/src/index.js#L123)

`hasSync(key) : exists`

Checks if the given key exists in the database. If it does, returns `true`. Else returns `false`.

*key* String\
\
*returns* Boolean

#### deleteSync(key)

Defined in [perma.db/lib/index.js#deleteSync](https://github.com/Rednexie/perma.db/blob/d5f76f325098baeb14827fe48f756967f649bb17/lib/src/index.js#L174)

`deleteSync(key): success`

Checks if the given key exists in the database. If it does, deletes it and returns `true`. Else returns `false`.

*key* String

*returns* Boolean

#### removeSync(key)

Defined in [perma.db/lib/index.js#removeSync](https://github.com/Rednexie/perma.db/blob/d5f76f325098baeb14827fe48f756967f649bb17/lib/src/index.js#L182)

`removeSync(key): success`

Checks if the given key exists in the database. If it does, deletes it and returns `true`. Else returns `false`.

*key* String

*returns* Boolean

#### typeSync(key)

Defined in [perma.db/lib/index.js#](https://github.com/Rednexie/perma.db/blob/d5f76f325098baeb14827fe48f756967f649bb17/lib/src/index.js#L182)[typeSync](https://github.com/Rednexie/perma.db/blob/d5f76f325098baeb14827fe48f756967f649bb17/lib/src/index.js#L190)

`typeSync(key): typeof value`

Checks if the given key exists in the database. If it does, returns the type of the value. Else returns `null`.

*key* String\
\
*returns* String

#### allSync()

Defined in [perma.db/lib/index.js#allSync](https://github.com/Rednexie/perma.db/blob/d5f76f325098baeb14827fe48f756967f649bb17/lib/src/index.js#L199)

`allSync(): [{key, value}]`

Gets all key-value pairs in the database inside an array.

*returns* Array

#### fetchAllSync()

Defined in [perma.db/lib/index.js#fetchAllSync](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L205)

`fetchAllSync(): [{key, value}]`

Returns all key-value pairs in the database inside an array.

*returns* Array

#### deleteAllSync()

Defined in [perma.db/lib/index.js#](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L205)[deleteAllSync](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L211)

`deleteAllSync(): success`

Deletes all key-value pairs in the database.

*returns* Boolean

#### removeAllSync()

Defined in [perma.db/lib/index.js#](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L205)[removeAllSync](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L219)

`removeAllSync(): success`

Deletes all key-value pairs in the database.

*returns* Boolean

#### clearSync()

Defined in [perma.db/lib/index.js#](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L205)[clearSync](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L227)

`clearSync(): success`

Deletes all key-value pairs in the database.

*returns* Boolean

#### deleteDBSync()

Defined in [perma.db/lib/index.js#](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L205)[deleteDBSync](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L235)

`deleteDBSync(): success`

Unlinks(removes) the database after closing it.

*returns* Boolean

#### removeDBSync()

Defined in [perma.db/lib/index.js#](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L205)[removeDBSync](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L241)

`removeDBSync(): success`

Unlinks(removes) the database after closing it.

*returns* Boolean

#### vacuumSync()

Defined in [perma.db/lib/index.js#](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L205)[vacuumSync](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L247)

`vacuumSync(): success`

Executes SQLite 'Vacuum' command on the database.\
\
*returns* Boolean

#### backupSync(path)

Defined in [perma.db/lib/index.js#](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L205)[backupSync](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L252)

`backupSync(path): success`

Closes the database. If the path already exists, returns false. If it doesn't, creates a backup.

*path* String

*returns* Boolean

#### querySync(sql, ...params)

Defined in [perma.db/lib/index.js#](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L205)[querySync](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L260)

`querySync(sql, ...params): results`

Execute an sql query.

*sql* String

*params* Any\
\
*returns* Any

#### sizeSync()

Defined in [perma.db/lib/index.js#](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L205)[sizeSync](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L271)

`sizeSync(): size`

Get the total size of the database contents.

*returns* Number

#### fileSizeSync()

Defined in [perma.db/lib/index.js#fileSizeSync](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L284)

`fileSizeSync(): filesize`

Get the file size of the database SQLite file.

*returns* Number

#### keysSync()

Defined in [perma.db/lib/index.js#](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L205)[keysSync](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L290)

`keysSync(): [...keys]`

Returns the array from the keys of the database.

*returns* Array

#### valuesSync()

Defined in [perma.db/lib/index.js#](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L205)[valuesSync](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L306)

`valuesSync(): [...values]`

Returns the array of the values stored in the database.\
\
*returns* Array

#### objectSync()

Defined in [perma.db/lib/index.js#](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L205)[objectSync](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L323)

`objectSync(): {key: value}`

Returns the key-value pairs as a Javascript Object.

*returns* Object

#### execSync(cmd)

Defined in [perma.db/lib/index.js#](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L205)[execSync](https://github.com/Rednexie/perma.db/edit/main/lib/src/index.js#L334)

`execSync(cmd): output`

Executes the given SQLite command, and returns the output.

*cmd* String

*returns String?*

#### closeSync()

Defined in [perma.db/lib/index.js#](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L205)[closeSync](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L266)

`closeSync(): success`

Closes the database.\
\
*returns* Boolean

#### expireSync(key, time)

Defined in [perma.db/lib/index.js#](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L205)[expireSync](https://github.com/Rednexie/perma.db/blob/main/lib/src/index.js#L339)<br>

`expireSync(key, time): success`

Waits for the given time(ms). If exists, deletes the given key along with it's value from the database, and returns `true`. Else returns `false`.\
\
*returns* Boolean

#### lengthSync()

Defined in [perma.db/lib/index.js#lengthSync](https://github.com/Rednexie/perma.db/edit/main/lib/src/index.js#L353)

`lengthSync(): length`

Gets the number of existing key-value pairs in the database.\
\
*returns* Boolean

### Asynchronous Methods

* [database#set](#set-key-value)
* [database#get](#get-key)
* [database#fetch](#fetch-key)
* [database#update](#update-key-value)
* [database#has](#hassync-key)
* [database#delete](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#deletekey)
* [database#remove](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#removekey)
* [database#type](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#typekey)
* [database#all](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#all)
* [database#fetchAll](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#fetchall)
* [database#deleteAll](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#deleteall)
* [database#clear](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#clear)
* [database#removeAll](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#removeAll)
* [database#removeDB](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#removeDB)
* [database#vacuum](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#vacuum)
* [database#backup](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#backuppath)
* [database#query](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#querysql-params)
* [database#size](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#size)
* [database#fileSize](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#fileSize)
* [database#keysSync](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#keys)
* [database#values](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#values)
* [database#object](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#object)
* [database#exec](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#exec-cmd)
* [database#close](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#close)
* [database#expire](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#expirekey-time)
* [database#length](https://github.com/Rednexie/perma.db/blob/main/DOCS.md#length)

#### set(key, value)

`async set(key, value): Promise<Buffer || String || Date || Number || null>`

Stores the value in the database, so you can access it with the key after. Returns a promise which resolves with the value.

*key* String

*value* Buffer || String || Date || Number || null

#### get(key)

`async get(key): Promise<value || null>`

Returns a promise which resolves with the value for the given key in the database

*key* String

#### fetch(key)

`async fetch(key): value || null`

Stores the value in the database, so you can access it with the key after. Returns a promise which resolves with the value.

*key* String

#### update(key, value)

`async update(key, value) : Promise<true || false>`

If the given key exists in the database, changes its value and resolves with `true`. If it doesn't exist, resolves `false`.

*key* String

*value* Buffer || String || Date || Number || null

#### has(key)

`async has(key) : Promise<true || false>`

Checks if the given key exists in the database. If it does, resolves with `true`. Else resolves `false`.

*key* String

#### delete(key)

`async delete(key): Promise<true || false>`

Checks if the given key exists in the database. If it does, deletes it and returns `true`. Else returns `false`.

*key* String

#### remove(key)

`remove(key): Promise<true || false>`

Checks if the given key exists in the database. If it does, deletes it and returns `true`. Else returns `false`.

*key* String

#### type(key)

`async type(key): Promise<typeof value || null>`

Checks if the given key exists in the database. If it does, returns the type of the value. Else returns `null`.

*key* String

#### all(key)

`async all(): Promise<[{key, value}]>`

Resolves all key-value pairs in the database inside an array.

#### fetchAll()

`async fetchAll(): Promise<Array [{key, value}]>`

Returns all key-value pairs in the database inside an array.

#### deleteAll()

`async deleteAll(): Promise<true>`

Deletes all key-value pairs in the database, and returns true

#### removeAll()

`async removeAll(): Promise<true>`

Deletes all key-value pairs in the database, and returns true

#### clear()

`async clear(): Promise<true>`

Deletes all key-value pairs in the database, and returns true

#### deleteDB()

`async deleteDB(): Promise<true>`

Unlinks(removes) the database after closing it and returns `true`.

#### removeDB()

`async removeDB(): Promise<true>`

Unlinks(removes) the database after closing it and returns `true`.

#### vacuum()

`async vacuum(): Promise<true>`

Vacuums the database and returns `true`.

#### backup(path)

`async backup(path): Promise<true || false>`

Closes the database. If the path already exists, returns false. If it doesn't, creates a backup.

*path* String

#### query(sql, ...params)

`async query(sql, ...params): Promise<results>`

Execute an sql query.

*sql* String

*params* Any

#### size()

`async size(): Promise<Number || null>`

Returns the total size of the database contents.

#### fileSize()

`async fileSize(): Promise<Number>`

Resolves with the database file size in bytes

#### keys()

`async keys(): Promise<Array [keys]>`

Resolves with the array from the keys of the database.

#### values()

`async values(): Promise<Array [values(Buffer || String || Date || Number || null)]>`

Resolves with the array of database values

#### object()

`async object(): Promise<{key, value} (Object)>`

Resolves with key-value pairs as a Javascript Object.

#### exec(cmd)

`async exec(cmd): Promise<output(String)>`

Executes the given sqlite command, and returns the output.

*cmd* String

#### close()

`async close(): Promise<true>`

Closes the database and resolves with true.

#### expire(key, time)

`async expire(key, time): Promise<success>`

If exists, deletes the given key along with it's value from the database, and returns `true`.

Else returns `false`.

*key* String

*time* Number

*resolves with* Boolean

#### length()

`length(): Promise<Number>`

Resolves with the number of existing key-value pairs in the database.