Protocol-based Keyv adapter registry with dynamic module installation
npm install keyv-registryProtocol-based Keyv adapter registry with dynamic module installation.
Create Keyv stores from URI strings with automatic adapter resolution and on-demand installation.
- 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
``bash`
npm install keyv-registry
`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
});
`
`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
});
`
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');
`
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:// - Redismemcache://
- - Memcached
URI option mapping (wrapped in { uri } object):postgresql://
- , postgres:// - PostgreSQLmysql://
- - MySQL/MariaDBsqlite://
- - SQLite
URL option mapping (wrapped in { url } object):mongodb://
- , mongodb+srv:// - MongoDBetcd://
- - etcd
Query parameters are always passed through and can be used for adapter-specific configuration. User options override both query parameters and protocol mappings.
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
})
});
`
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 });
`
| 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 |
| Protocol | Package | Notes |
|----------|---------|-------|
| file:// | keyv-file | File-based JSON storage |duckdb://
| | keyv-duckdb | DuckDB (planned) |
| Protocol | Notes |
|----------|-------|
| memory:// | In-memory Map, no package needed |
Create a Keyv store from a URI string.
Parameters:
- uri (string): Connection URI with protocoloptions
- (object, optional): Keyv optionsstore
- : Pre-instantiated adapter (bypasses URI loading)namespace
- : Keyv namespacettl
- : Default TTL in millisecondscallback
- Additional options passed to Keyv
- (function, optional): Node-style callback (err, store) => void
Returns: Promise if no callback, undefined if callback provided
Register or override a protocol adapter.
Parameters:
- protocol (string): Protocol with or without trailing colon (e.g., 'redis:' or 'redis')config
- (object): Adapter configurationpackage
- : npm package name, or null for built-inexportName
- : Named export (default: 'default')optionsMapper
- : Function (url: URL) => object to map URL to options
Get a read-only copy of the current protocol registry.
Returns: Record
Clear the loaded adapter cache. Useful for testing.
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.
MIT