diff --git a/README.md b/README.md
index 84228799dc..9ec70ce185 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-> :warning: version 4 is still being developed and is not yet ready for any real production use. Please do not use it for any mission critical purpose at this time.
+> :warning: Version 4 is still under development and isn't ready for production use. Use at your own risk.
---
@@ -13,9 +13,10 @@
---
- 
- 
- 
+
+ 
+ 
+
---
@@ -23,12 +24,132 @@
## Installation
```bash
-npm install redis
+npm install redis@next
+```
+
+## Usage
+
+### Basic Example
+
+```javascript
+(async () => {
+ const client = require('redis').createClient();
+
+ client.on('error', (err) => console.log('Redis Client Error', err));
+
+ await client.connect();
+
+ await client.set('key', 'value');
+ const value = await client.get('key');
+})();
+```
+
+### Redis Commands
+
+There is built-in support for all of the [out-of-the-box Redis commands](https://redis.io/commands). They are exposed using the raw Redis command names (`HGET`, `HSET`, etc.) and a friendlier camel-cased version (`hGet`, `hSet`, etc.).
+
+```javascript
+// raw Redis commands
+await client.SET('key', 'value');
+await client.GET('key');
+
+// friendly JavaScript commands
+await client.hSet('key', 'field', 'value');
+await client.hGetAll('key');
+```
+
+Modifiers to commands are specified using a JavaScript object:
+
+```javascript
+await client.set('key', 'value', {
+ EX: 10,
+ NX: true
+});
+```
+
+Replies will be transformed to useful data structures:
+
+```javascript
+await client.hGetAll('key'); // { key1: 'value1', key2: 'value2' }
+await client.hKeys('key'); // ['key1', 'key2']
+```
+
+### Unsupported Redis Commands
+
+If you want to run commands and arguments that Node Redis doesn't know about (yet!) you can use `.sendCommand`:
+
+```javascript
+await client.sendCommand(['SET', 'key', 'value', 'NX']); // 'OK'
+
+await client.sendCommand(['HGETALL', 'key']); // ['key1', 'field1', 'key2', 'field2']
+```
+
+### Blocking Commands
+
+Any command can be run on a new connection by specifying the `duplicateConnection` option. The newly created connection is closed when command's `Promise` is fulfilled.
+
+This pattern works especially well for blocking commands—such as `BLPOP` and `BRPOPLPUSH`:
+
+```javascript
+const blPopPromise = client.blPop(
+ client.commandOptions({ duplicateConnection: true }),
+ 'key'
+);
+
+await client.lPush('key', ['1', '2']);
+
+await blPopPromise; // '2'
+```
+
+### Pub/Sub
+
+Subscribing to a channel requires a dedicated Redis connection and is easily handled using events.
+
+```javascript
+await subscriber.subscribe('channel', message => {
+ console.log(message); // 'message'
+});
+
+await subscriber.pSubscribe('channe*', (message, channel) => {
+ console.log(message, channel); // 'message', 'channel'
+});
+
+await publisher.publish('channel', 'message');
+```
+
+### Lua Scripts
+
+You can define Lua scripts to create efficient custom commands:
+
+```javascript
+(async () => {
+ const client = require('redis').createClient({
+ scripts: {
+ add: require('redis/lua-script').defineScript({
+ NUMBER_OF_KEYS: 1,
+ SCRIPT:
+ 'local val = redis.pcall("GET", KEYS[1]);' +
+ 'return val + ARGV[1];',
+ transformArguments(key: string, toAdd: number): Array {
+ return [key, number.toString()];
+ },
+ transformReply(reply: number): number {
+ return reply;
+ }
+ })
+ }
+ });
+
+ await client.connect();
+
+ await client.set('key', '1');
+ await client.add('key', 2); // 3
+})();
```
## Contributing
-Please see the [contributing guide](CONTRIBUTING.md).
+If you'd like to contribute, check out the [contributing guide](CONTRIBUTING.md).
## License