Class BunSqliteKeyValue

A super fast key-value store with SQLite that uses bun:sqlite and v8 as a fast JSON replacement.

Index

Hash (Map Object)

hDecr

hDecr(key: string, field: string, decrBy?: number, ttlMs?: TtlMs): number
Parameters
- key: string
  More informations about key.
- field: string
- decrBy: number = 1
- OptionalttlMs: TtlMs
Returns number
Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#hincrby
- Defined in index.ts:948

hDelete

hDelete(key: string, field: string): undefined | boolean
Hash function: Deletes a field of the map object.
Parameters
- key: string
  The key of the item. More informations about key.
- field: string
  The name of the field.
Returns undefined | boolean
- undefined if the key does not exist.
- true if the field existed and was deleted.
- false if the field did not exist.
Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#hdel
- Defined in index.ts:893

hGet

hGet<T>(key: string, field: string): undefined | T
Hash (Map Object) - Read Value

Do not use it with several very large amounts of data or blobs. This is because the entire data record with all fields is always read and written.
Type Parameters
- T = any
Parameters
- key: string
  More informations about key.
- field: string
Returns undefined | T
Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#hget
- Defined in index.ts:701

hGetCount

hGetCount(key: string): undefined | number
Hash (Map Object) - Count Fields
Parameters
- key: string
  More informations about key.
Returns undefined | number
Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#hlen
- Defined in index.ts:803

hGetFields

hGetFields(key: string): undefined | string[]
Hash (Map Object) - Get All Field Names
Parameters
- key: string
  More informations about key.
Returns undefined | string[]
Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#hkeys
- Defined in index.ts:825

hGetValues

hGetValues<T>(key: string): undefined | T[]
Returns the values contained in the hash stored at key.

Use hmGet() to read field names and values.

Do not use the hash functions with several very large amounts of data or blobs. This is because the entire data record with all fields is always read and written. It is better to use setValues() and getValues() for large amounts of data.
Type Parameters
- T = any
Parameters
- key: string
  More informations about key.
Returns undefined | T[]
If the data record (marked with key) does not exist, undefined is returned.
Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#hvals
Example
```
import { BunSqliteKeyValue } from "bun-sqlite-key-value"

const store = new BunSqliteKeyValue()

store.hmSet("key-1", {
    "field-1": "value-1",
    "field-2": "value-2"
})
store.hGetValues("key-1") // --> ["value-1", "value-2"]
```
- Defined in index.ts:867

hHasField

hHasField(key: string, field: string): undefined | boolean
Hash (Map Object) - Has Field

Returns if field is an existing field in the hash stored at key.

Do not use it with several very large amounts of data or blobs. This is because the entire data record with all fields is always read.
Parameters
- key: string
  More informations about key.
- field: string
Returns undefined | boolean
Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#hexists
- Defined in index.ts:781

hIncr

hIncr(key: string, field: string, incrBy?: number, ttlMs?: TtlMs): number
Parameters
- key: string
  More informations about key.
- field: string
- incrBy: number = 1
- OptionalttlMs: TtlMs
Returns number
Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#hincrby
- Defined in index.ts:917

hmGet

hmGet<T>(key: string, fields?: string[]): undefined | {
[field: Field]: T | undefined;
}
Hash (Map Object) - Read Multiple Values

Do not use it with several very large amounts of data or blobs. This is because the entire data record with all fields is always read and written.
Type Parameters
- T = any
Parameters
- key: string
  More informations about key.
- Optionalfields: string[]
Returns undefined | {
[field: Field]: T | undefined;
}
Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#hmget
- Defined in index.ts:749

hmSet

hmSet<T>(key: string, fields: {
[field: Field]: T;
}, ttlMs?: TtlMs): void
Hash (Map Object) - Write Multiple Values

Do not use it with several very large amounts of data or blobs. This is because the entire data record with all fields is always read and written.
Type Parameters
- T = any
Parameters
- key: string
  More informations about key.
- fields: {
  [field: Field]: T;
  }
  - [field: Field]: T
- OptionalttlMs: TtlMs
Returns void
Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#hmset
- Defined in index.ts:723

hSet

hSet<T>(key: string, field: string, value: T, ttlMs?: TtlMs): boolean
Hash (Map Object) - Write Value

Do not use it with several very large amounts of data or blobs. This is because the entire data record with all fields is always read and written.
Type Parameters
- T = any
Parameters
- key: string
  More informations about key.
- field: string
- value: T
  More informations about value.
- OptionalttlMs: TtlMs
Returns boolean
Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#hset
- Defined in index.ts:674

List (Array Object)

lIndex

lIndex<T>(key: string, index: number): undefined | T
Returns the element at index in the list stored at key.

The index is zero-based, so 0 means the first element, 1 the second element and so on. Negative indices can be used to designate elements starting at the tail of the list. Here, -1 means the last element, -2 means the penultimate and so forth.
Type Parameters
- T = any
Parameters
- key: string
  More informations about key.
- index: number
Returns undefined | T
When the value at key is not a list, an error is returned.

Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#lindex
- Defined in index.ts:1125

lLen

lLen(key: string): number
Returns the length of the list stored at key.

If key does not exist, it is interpreted as an empty list and 0 is returned. An error is returned when the value stored at key is not an array.
Parameters
- key: string
  More informations about key.
Returns number
The length of the list at key.

Remarks
Inspired by: https://www.dragonflydb.io/docs/command-reference/lists/llen
- Defined in index.ts:1154

lPop

lPop<T>(key: string, count?: number): undefined | T | T[]
Removes and returns the first element of the list stored at key. If count is specified, returns count number of elements.
Type Parameters
- T = any
Parameters
- key: string
  More informations about key.
- Optionalcount: number
Returns undefined | T | T[]
If count is undefined, it returns the first element of the list stored at key. If count is a positive number, it returns the first count elements of the list stored at key. Returns undefined if key was not found or the array is empty.

Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#lpop
- Defined in index.ts:1037

lPush

lPush<T>(key: string, ...values: T[]): number
Array - Left Push - Adds elements at the begin of the array.
Type Parameters
- T = any
Parameters
- key: string
  More informations about key.
- Rest...values: T[]
  More informations about value.
Returns number
New length of the list.

Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#lpush
- Defined in index.ts:967

lSet

lSet<T>(key: string, index: number, value: T): true
Updates the list element at index to value.

For more information on the index argument, see lIndex().

An error is returned if the key does not exist. An error is returned when the value stored at key is not an array. An error is returned for out of range indexes.
Type Parameters
- T = any
Parameters
- key: string
  More informations about key.
- index: number
- value: T
  More informations about value.
Returns true
true if the key exists and the value has been set.

Remarks
Inspired by: https://www.dragonflydb.io/docs/command-reference/lists/lset
- Defined in index.ts:1184

rPop

rPop<T>(key: string, count?: number): undefined | T | T[]
Removes and returns the last element of the list stored at key. If count is specified, returns count number of elements.
Type Parameters
- T = any
Parameters
- key: string
  More informations about key.
- Optionalcount: number
Returns undefined | T | T[]
If count is undefined, it returns the last element of the list stored at key. If count is a positive number, it returns the last count elements of the list stored at key. Returns undefined if key was not found or the array is empty.

Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#rpop
- Defined in index.ts:1080

rPush

rPush<T>(key: string, ...values: T[]): number
Array - Right Push - Adds elements at the end of the array.
Type Parameters
- T = any
Parameters
- key: string
  More informations about key.
- Rest...values: T[]
  More informations about value.
Returns number
New length of the list.

Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#rpush
- Defined in index.ts:1002

Other

constructor

new BunSqliteKeyValue(filename?: string, options?: Options): BunSqliteKeyValue
Opens and creates the SQLite database either in memory or on the file system.
Parameters
- Optionalfilename: string
  The full path to the SQLite database to open. Or pass an empty string (""), ":memory:" or undefined for an in-memory database.
- Optionaloptions: Options
  Database options
Returns BunSqliteKeyValue
- Defined in index.ts:47

clear

clear(): void
Deletes all items

Returns void
- Defined in index.ts:121

close

close(): void
Close database

Removes .sqlite-shm and .sqlite-wal files

Returns void
- Defined in index.ts:131

delete

delete(keyOrKeys?: string | string[]): void
Deletes one or multiple items.
Parameters
- OptionalkeyOrKeys: string | string[]
  More informations about key.
Returns void
Remarks
Inspired by: https://docs.keydb.dev/docs/commands/#del
- Defined in index.ts:96

deleteExpired

deleteExpired(): void
Deletes all expired records.

Returns void
- Defined in index.ts:82

get

get<T>(key: string): undefined | T

Reads a value from the database.

Type Parameters

T = any

Parameters

key: string
More informations about key.

Returns undefined | T

Example

import { BunSqliteKeyValue } from "bun-sqlite-key-value"
const store = new BunSqliteKeyValue()
store.set("myKey", "my-value")
store.get("myKey") // --> "my-value"
store.data.myKey // --> "my-value"
store.data["myKey"] // --> "my-value"

getCount

getCount(): number
Returns the number of all items in the database, including those that have already expired.

Use getCountValid() if you want to get the number of items that have not yet expired.

Returns number
- Defined in index.ts:143

getCountValid

getCountValid(deleteExpired?: boolean): number
Returns the number of all valid (non-expired) items in the database.

Use getCount() if you want the fastet possible method.
Parameters
- OptionaldeleteExpired: boolean
Returns number
- Defined in index.ts:166

set

set<T>(key: undefined | string, value: T, ttlMs?: TtlMs): string

Writes a value into the database and returns the key.

Type Parameters

T = any

Parameters

key: undefined | string
More informations about key.
value: T
More informations about value.
OptionalttlMs: TtlMs

Returns string

Returns the key.

Example

import { BunSqliteKeyValue } from "bun-sqlite-key-value"
const store = new BunSqliteKeyValue()
// Stays in database
store.set("myKey1", "my-value")
store.data.myKey2 = "my-value"
store.data["myKey3"] = "my-value"
// Becomes invalid after 30 seconds
store.set("myKey6", "item-with-ttl", 30000)

setItems

setItems<T>(items: {
    key: undefined | string;
    ttlMs?: TtlMs;
    value: T;
}[]): void
Adds a large number of entries to the database and takes only a small fraction of the time that set() would take individually.
Type Parameters
- T = any
Parameters
- items: {
      key: undefined | string;
      ttlMs?: TtlMs;
      value: T;
  }[]
Returns void
- Defined in index.ts:227

Tags (Labels)

addTag

addTag(key: string, tag: string): boolean
Adds a tag to an item.

Raises an error if the item key does not exist.
Parameters
- key: string
  More informations about key.
- tag: string
Returns boolean
Returns true if the tag has been added. Returns false if the tag already exists.
- Defined in index.ts:1282

deleteTag

deleteTag(key: string, tag: string): boolean
Deletes a tag of an item.
Parameters
- key: string
  More informations about key.
- tag: string
Returns boolean
Returns true if the tag has been deleted. Returns false if the tag or the item does not exist.
- Defined in index.ts:1306

deleteTaggedItems

deleteTaggedItems(tag: string): void
Deletes tagged items.
Parameters
- tag: string
Returns void
- Defined in index.ts:1338

deleteTags

deleteTags(key: string, tags?: string[]): void
Deletes multiple tags or all tags of the item.
Parameters
- key: string
  More informations about key.
- Optionaltags: string[]
  Deletes all tags within the array. If undefined, all tags of the item are deleted.
Returns void
- Defined in index.ts:1321

getTaggedItems

getTaggedItems<T>(tag: string): undefined | Item<T>[]
Returns tagged items.
Type Parameters
- T
Parameters
- tag: string
Returns undefined | Item<T>[]
- Defined in index.ts:1380

getTaggedKeys

getTaggedKeys(tag: string): undefined | string[]
Returns tagged keys.
Parameters
- tag: string
Returns undefined | string[]
- Defined in index.ts:1350

getTaggedValues

getTaggedValues<T>(tag: string): undefined | (undefined | T)[]
Returns tagged values.
Type Parameters
- T = any
Parameters
- tag: string
Returns undefined | (undefined | T)[]
- Defined in index.ts:1364

Class BunSqliteKeyValue

Index

Hash (Map Object)

List (Array Object)

Other

Tags (Labels)

Hash (Map Object)

hDecr

Parameters

Returns number

Remarks

hDelete

Parameters

Returns undefined | boolean

Remarks

hGet

Type Parameters

Parameters

Returns undefined | T

Remarks

hGetCount

Parameters

Returns undefined | number

Remarks

hGetFields

Parameters

Returns undefined | string[]

Remarks

hGetValues

Type Parameters

Parameters

Returns undefined | T[]

Remarks

Example

hHasField

Parameters

Returns undefined | boolean

Remarks

hIncr

Parameters

Returns number

Remarks

hmGet

Type Parameters

Parameters

Returns undefined | { [field: Field]: T | undefined; }

Remarks

hmSet

Type Parameters

Parameters

[field: Field]: T

Returns void

Remarks

hSet

Type Parameters

Parameters

Returns boolean

Remarks

List (Array Object)

lIndex

Type Parameters

Parameters

Returns undefined | T

Remarks

lLen

Parameters

Returns number

Remarks

lPop

Type Parameters

Parameters

Returns undefined | T | T[]

Remarks

lPush

Type Parameters

Parameters

Returns number

Remarks

lSet

Type Parameters

Returns undefined | {
[field: Field]: T | undefined;
}