npm package: @gistbase/gistbase
Description: Key value data storage backed by GitHub Gists.
Author: Peter Evans
Latest version: 1.3.2

# Gistbase
[![CI](https://github.com/gistbase/gistbase/workflows/CI/badge.svg)](https://github.com/gistbase/gistbase/actions?query=workflow%3ACI)

A key-value datastore backed by GitHub Gists.

## Usage

```
npm install @gistbase/gistbase
```

### GistbaseLite

`GistbaseLite` uses the [GitHub Gists API](https://developer.github.com/v3/gists/#truncation) _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.

```typescript
import {GistbaseLite} from '@gistbase/gistbase'
```

`token` is a `gist` scoped GitHub [PAT](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line).
```typescript
// 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](https://developer.github.com/v3/gists/#truncation) and a git client to perform operations.
It requires a filesystem path to cache the underlying Gist.

```typescript
import {Gistbase} from '@gistbase/gistbase'
```

`token` is a `gist` scoped GitHub [PAT](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line).
```typescript
// 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](LICENSE)