Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mmkal/handy-redis
A wrapper around node_redis with Promise and TypeScript support.
https://github.com/mmkal/handy-redis
Last synced: about 4 hours ago
JSON representation
A wrapper around node_redis with Promise and TypeScript support.
- Host: GitHub
- URL: https://github.com/mmkal/handy-redis
- Owner: mmkal
- License: apache-2.0
- Created: 2017-04-29T18:04:55.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2024-09-17T00:44:38.000Z (17 days ago)
- Last Synced: 2024-09-17T20:02:32.046Z (16 days ago)
- Language: TypeScript
- Size: 2.81 MB
- Stars: 172
- Watchers: 7
- Forks: 10
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
>Note: since I wrote this, [node_redis](https://npmjs.com/package/redis) has now added built-in promise and typescript support, as well as many other high-level features - so you shouldn't need this anymore! Just install `redis`.
# handy-redis
A wrapper around [node_redis](https://npmjs.com/package/redis) with Promise and TypeScript support.
[](https://github.com/mmkal/handy-redis/actions?query=workflow%3ACI)
[](https://codecov.io/gh/mmkal/handy-redis)
[](https://npmjs.com/package/handy-redis)
[](https://npmjs.com/package/handy-redis)
## Motivation
[node_redis](https://npmjs.com/package/redis) doesn't support Promises out-of-the-box - you have to use `util.promisify` on each command, or bluebird's `promisifyAll`, which has the side effect of removing all TypeScript/intellisense support from the package.
This package is a wrapper around node_redis and exclusively uses Promises. It publishes TypeScript types generated from the official redis documentation and examples, so it's much easier to know what parameters a command expects, and how to use the return values.
## Usage
```cli
npm install handy-redis redis
```
ES6/TypeScript:
```JavaScript
import { createNodeRedisClient } from 'handy-redis';
(async function() {
const client = createNodeRedisClient();
// or, call createNodeRedisClient(opts) using opts for https://www.npmjs.com/package/redis#rediscreateclient
// or, call createNodeRedisClient(oldClient) where oldClient is an existing node_redis client.
await client.set('foo', 'bar');
const foo = await client.get('foo');
console.log(foo);
})();
```
Vanilla JS, no async/await:
```JavaScript
const { createNodeRedisClient } = require('handy-redis');
const client = createNodeRedisClient();
client
.set('foo', 'bar')
.then(() => client.get('foo'))
.then(foo => console.log(foo));
```
The package is published with TypeScript types, with the redis documentation and response type attached to each command:
### Adding new commands
Note that the [`redis`](https://npmjs.com/package/redis) package should be installed separately. If you need to use recent redis commands (e.g. `lpos` (recent at time of writing, at least)), which is not included in the [`redis`](https://npmjs.com/package/redis) package by default, you can use `addNodeRedisCommand`:
```js
import { addNodeRedisCommand, createNodeRedisClient } from 'handy-redis'
addNodeRedisCommand('lpos')
const client = createNodeRedisClient(...)
```
If there's a command without a type, a new version of this library will need to be released - [raise an issue](https://github.com/mmkal/handy-redis/issues) if you come across one.
### Accessing the underlying client
Some features of node_redis are not duplicated in this library, such as `watch`, pubsub and events generally. To use them, get the underlying client via `.nodeRedis`:
```js
import { createNodeRedisClient } from 'handy-redis'
const client = createNodeRedisClient(...)
client.nodeRedis.on('error', err => console.error(err))
client.nodeRedis.publish('a_channel', 'a message')
```
### v1.x compatibility
Some aliases exist for backwards-compatibility with v1.x:
- `createNodeRedisClient` (preferred) is aliased to `createHandyClient`
- `WrappedNodeRedisClient` (preferred) is aliased to `IHandyRedis`
- `client.nodeRedis` (preferred) is aliased to `client.redis`
### Examples
See the [snapshot tests](./test/generated/commands) for tons of usage examples.
### Multi
Most members of node_redis's `multi` type don't need to be promisified, because they execute synchronously. Only `exec` is async. Usage example:
```JavaScript
import { createNodeRedisClient } from 'handy-redis';
(async function() {
const client = createNodeRedisClient();
const result = await client.multi().set("z:foo", "987").keys("z:*").get("z:foo").exec();
console.log(result); // ["OK", ["z:foo"], "987"]
})();
```
The resolved value returned by `exec` is a tuple type, which keeps track of the commands that have been queued. In the above example, the type will be `[string, string[], string]`.
Note: `multi` results are strongly-typed only when using typescript 4.0 and above - for lower typescript versions they will gracefully fall back to a union type (for the example above, it'll be `Array`).
`client.batch()` also works, with the same API. See [node_redis docs](https://www.npmjs.com/package/redis#clientbatchcommands) for details.
#### Migrating from v1.x
The client no longer has an `execMulti` function. Use the `.exec()` method on the multi instance.
## Wrong types? Raise an issue!
Since the types are autogenerated from [redis-doc](https://github.com/redis/redis-doc), which doesn't adhere to a formal schema, they might be incomplete, or in some cases, wrong. The errors are easy enough to fix, but not easy to find, so if you think you've come across a case like this, please [raise an issue](https://github.com/mmkal/handy-redis/issues).
___
## Development
Most of the package is generated by running sample commands from the redis documentation repo.
How it works
The client is generated from the [redis-doc](https://github.com/redis/redis-doc) repo.
- `pnpm codegen` generates code:
- `generate-schema`:
- [commands.json](./docs/redis-doc/commands.json) is used to output a commands file with json-schema arguments and return types.
- Argument lists are modeled as arrays, which are flattened when sent to the underlying client. e.g. `SET` might have args `['foo', 'bar', ['EX', 60]]` corresponding to the CLI command `SET foo bar EX 60`
- the markdown documentation for each command is parsed for the return type
- `generate-client`:
- the json-schema from the previous step is parsed and used to generate a [typescript interface of commands](./src/generated/interface.ts).
- Commands use a basic higher-kinded types implementation. The `Multi` interface requires a key pointing to a property on a `ResultTypes` interface, with properties defined via module augmentation. By default, each command returns a promisified result type. See the [node_redis multi implementation](./src/node_redis/multi.ts) for an example which configures each command to return a chainable multi instance, using previous commands as the `Context`.
- `generate-tests`:
- the markdown docs for each command are parsed and transformed into typescript calls. e.g. `SET FOO BAR EX 60` is decoded into `client.set('foo', 'bar', ['EX', 60])`
- these typescript calls are put into jest tests and their outputs are snapshotted
- these tests are internal only and are not included in the published package
At each stage, there are some [patches](./codegen/patches) to plug gaps and inconsistencies in redis-doc and node_redis.
From all the code-generation only the [interface file](./src/generated/interface.ts) is exported. When a client is created, each command on the node_redis client prototype is added as a method on handy-redis's client, a wrapped and promisified version of the equivalent node_redis method.
```cli
git clone https://github.com/mmkal/handy-redis
cd handy-redis
pnpm install
```
Make sure you have docker installed and `docker-compose` is on your path, and start up a redis server in the background with `pnpm redis:up -d`.
To fully test the package as it is on your machine, the same way CI does:
```cli
pnpm test
```
`pnpm test` runs the build, test and lint scripts. It removes all generated code before, and after checks that your git status is clean. This is to allow tracking changes to the generated client over time, to make what the published package contains more visible, and to make sure that generated code hasn't been modified without auditing first. You should not manually edit any files under a `*/generated/*` path. If `pnpm test` fails for you because you deliberately changed the way the codegen works, take a look at the git changes, check them in and run `pnpm test` again.
The `build` script generates the client before using TypeScript to compile it. If you want to run the tests without rebuilding, linting etc., use `pnpm jest`.
There are some more scripts in `package.json` which can be useful for local development.
Redis doc was added via `git subtree add --prefix docs/redis-doc https://github.com/redis/redis-doc master --squash` following [this guide](https://www.atlassian.com/git/tutorials/git-subtree). Here's how they say it can be updated:
```
git subtree pull --prefix docs/redis-doc https://github.com/redis/redis-doc master --squash
```
### Testing
If a snapshot test fails, it's possible it just needs to be updated. Make sure your git status is clean and run `pnpm jest -u`.
Types are tested using [expect-type](https://npmjs.com/package/expect-type).