Gistbase

A key-value datastore backed by GitHub Gists.

Usage

npm install @gistbase/gistbase

GistbaseLite

GistbaseLite uses the GitHub Gists API only to perform operations. This comes with the following limitations.

• Handles up to 299 keys. Adding more than 299 keys may cause getKey to fail due to truncation by the API.
• Accepts up to one megabyte of content for a key's value.

import {GistbaseLite} from '@gistbase/gistbase'

token is a gist scoped GitHub PAT.

// Create a Gistbase
const gistbase = await GistbaseLite.create(token)

// Create a Gistbase instance from an existing Gist ID
const gistbase = await GistbaseLite.fromId(id, token)

// Put a key value pair
await gistbase.putKey('foo', 'bar')

// Get the value of a key
const {value: foo} = await gistbase.getKey('foo')

// Retry getting a key until it exists or the timeout expires
const {value: baz} = await gistbase.getKey('baz', {timeoutSeconds: 360})

// Delete a key
await gistbase.deleteKey('foo')

// Re-fetch and cache the underlying Gist
await gistbase.fetch()

// Delete the Gistbase
await gistbase.delete()

Gistbase

Gistbase uses a combination of the GitHub Gists API and a git client to perform operations. It requires a filesystem path to cache the underlying Gist.

import {Gistbase} from '@gistbase/gistbase'

token is a gist scoped GitHub PAT.

// Create a Gistbase
const gistbase = await Gistbase.create('/path/to/cache/directory', token)

// Create a Gistbase instance from an existing Gist ID
const gistbase = await Gistbase.fromId(id, '/path/to/cache/directory', token)

// Put a key value pair
await gistbase.putKey('foo', 'bar')

// Get the value of a key
const {value: foo} = await gistbase.getKey('foo')

// Put a key file pair
await gistbase.putFile('foo', '/path/to/value')

// Get the filepath of a key
const {filepath: foo} = await gistbase.getFile('foo')

// Retry getting a key until it exists or the timeout expires
const {value: baz} = await gistbase.getKey('baz', {timeoutSeconds: 360})

// Delete a key
await gistbase.deleteKey('foo')

// Re-fetch and cache the underlying Gist
await gistbase.fetch()

// Start a transaction
gistbase.startTransaction()

// End a transaction applying all put and delete operations
await gistbase.endTransaction()

// Delete the Gistbase
await gistbase.delete()

Caveats

The following usage caveats apply to both GistbaseLite and Gistbase.

• Gistbase methods are not synchronised and are unsuitable for multithreaded use.
• Multiple clients may access the same Gistbase. Use getKey() with retryOptions to wait for a key to exist. Or, call fetch() to update the client's cache when changes have been made to the underlying Gist.

License

MIT