keyv-registry

Protocol-based Keyv adapter registry with dynamic module installation.

Create Keyv stores from URI strings with automatic adapter resolution and on-demand installation.

Features

- URI-based configuration: Use familiar connection strings like redis://localhost:6379
- Dynamic installation: Adapters are installed on-demand, no hard dependencies
- Extensible registry: Register custom protocols or override defaults
- Dual-boot API: Supports both Promise and callback patterns
- URI parameter mapping: Query params automatically converted to adapter options
- Store passthrough: Use pre-instantiated adapters when needed

Installation

``bash
npm install keyv-registry
`

Usage

$3

`typescript
import createStore from 'keyv-registry';

// Redis
const redis = await createStore('redis://localhost:6379');

// PostgreSQL
const postgres = await createStore('postgresql://user:pass@localhost/db');

// File-based storage
const file = await createStore('file://~/.cache/myapp/data.json');

// In-memory (built-in, no package needed)
const memory = await createStore('memory://');

// SQLite
const sqlite = await createStore('sqlite:///path/to/db.sqlite');

// With options
const store = await createStore('redis://localhost:6379', {
namespace: 'myapp',
ttl: 60000
});
`

$3

`typescript
import createStore from 'keyv-registry';

createStore('redis://localhost:6379', (err, store) => {
if (err) throw err;
// use store
});

// With options
createStore('redis://localhost:6379', { namespace: 'myapp' }, (err, store) => {
if (err) throw err;
// use store
});
`

$3

Query parameters are automatically converted to adapter options:

`typescript
// Equivalent to { keyPrefix: 'myapp', ttl: 3600 }
const store = await createStore('redis://localhost:6379?keyPrefix=myapp&ttl=3600');

// Boolean and number conversion is automatic
const file = await createStore('file://~/data.json?writeDelay=100&pretty=true');
`

$3

Connection strings are passed to adapters via protocol-specific mappings. Different adapters expect connection information in different formats:

Direct URL passing (adapter instantiated with URI string):
- redis://, rediss:// - Redis
- memcache:// - Memcached

URI option mapping (wrapped in { uri } object):
- postgresql://, postgres:// - PostgreSQL
- mysql:// - MySQL/MariaDB
- sqlite:// - SQLite

URL option mapping (wrapped in { url } object):
- mongodb://, mongodb+srv:// - MongoDB
- etcd:// - etcd

Query parameters are always passed through and can be used for adapter-specific configuration. User options override both query parameters and protocol mappings.

$3

Register custom protocols or override defaults:

`typescript
import createStore, { registerAdapter } from 'keyv-registry';

// Register a new protocol
registerAdapter('cloudflare:', { package: 'keyv-cloudflare' });
const cf = await createStore('cloudflare://my-namespace');

// Override default with custom package
registerAdapter('file:', {
package: '@my-org/keyv-file-encrypted',
optionsMapper: (url) => ({
filename: url.pathname,
encryption: true
})
});
`

$3

For advanced configuration, pass a pre-instantiated adapter:

`typescript
import createStore from 'keyv-registry';
import KeyvRedis from '@keyv/redis';

const customRedis = new KeyvRedis('redis://localhost:6379', {
useUnlink: true,
cluster: true
});

// URI is ignored when store option is provided
const store = await createStore('redis://ignored', { store: customRedis });
`

Supported Protocols

$3

| Protocol | Package | Connection String Handling | Notes |
|----------|---------|---------------------------|-------|
| redis://, rediss:// | @keyv/redis | Direct URL | Redis, supports TLS |
| postgresql://, postgres:// | @keyv/postgres | URI option | PostgreSQL |
| mysql:// | @keyv/mysql | URI option | MySQL/MariaDB |
| sqlite:// | @keyv/sqlite | URI option | SQLite |
| mongodb://, mongodb+srv:// | @keyv/mongo | URL option | MongoDB |
| memcache:// | @keyv/memcache | Direct URI | Memcached |
| etcd:// | @keyv/etcd | URL option | etcd |

$3

| Protocol | Package | Notes |
|----------|---------|-------|
| file:// | keyv-file | File-based JSON storage |
| duckdb:// | keyv-duckdb | DuckDB (planned) |

$3

| Protocol | Notes |
|----------|-------|
| memory:// | In-memory Map, no package needed |

API

$3

Create a Keyv store from a URI string.

Parameters:
- uri (string): Connection URI with protocol
- options (object, optional): Keyv options
- store: Pre-instantiated adapter (bypasses URI loading)
- namespace: Keyv namespace
- ttl: Default TTL in milliseconds
- Additional options passed to Keyv
- callback (function, optional): Node-style callback (err, store) => void

Returns: Promise if no callback, undefined if callback provided

$3

Register or override a protocol adapter.

Parameters:
- protocol (string): Protocol with or without trailing colon (e.g., 'redis:' or 'redis')
- config (object): Adapter configuration
- package: npm package name, or null for built-in
- exportName: Named export (default: 'default')
- optionsMapper: Function (url: URL) => object to map URL to options

$3

Get a read-only copy of the current protocol registry.

Returns: Record

$3

Clear the loaded adapter cache. Useful for testing.

File Path Shortcuts

The file:// protocol supports path shortcuts:

`typescript
// Home directory
await createStore('file://~/.cache/myapp/data.json');

// Current working directory
await createStore('file://./data/cache.json');

// Absolute path
await createStore('file:///var/cache/myapp/data.json');
``

Directories are created automatically if they don't exist.

License

MIT