fix #1714 - update README(s)

examples/.gitignore

@@ -0,0 +1 @@
+package-lock.json

examples/README.md

@@ -0,0 +1,75 @@
+# Node Redis: Examples
+
+This folder contains example scripts showing how to use Node Redis in different scenarios.
+
+| File Name                   | Description                          |
+|-----------------------------|--------------------------------------|
+| `connect-as-acl-user.js`    | Connect to Redis 6 using an ACL user |
+| `blocking-list-pop.js`      | Block until an element is pushed to a list  |
+| `lua-multi-incr.js`         | Define a custom lua script that allows you to perform INCRBY on multiple keys |
+| `command-with-modifiers.js` | Define a script that allows to run a command with several modifiers |
+| `set-scan.js` | An example script that shows how to use the SSCAN iterator functionality  |
+
+## Contributing
+
+We'd love to see more examples here. If you have an idea that you'd like to see included here, submit a Pull Request and we'll be sure to review it!  Don't forget to check out our [contributing guide](../CONTRIBUTING.md).
+
+## Setup
+
+To set up the examples folder so that you can run an example / develop one of your own:
+
+```
+$ git clone https://github.com/redis/node-redis.git
+$ cd node-redis
+$ npm install -ws && npm run build
+$ cd examples
+$ npm install
+```
+
+### Coding Guidelines for Examples
+
+When adding a new example, please follow these guidelines:
+
+* Add your code in a single JavaScript or TypeScript file per example, directly in the `examples` folder
+* Do not introduce other dependencies in your example
+* Give your `.js` file a meaningful name using `-` separators e.g. `adding-to-a-stream.js` / `adding-to-a-stream.ts`
+* Indent your code using 2 spaces
+* Use the single line `//` comment style and comment your code
+* Add a comment at the top of your `.js` / `.ts` file describing what your example does
+* Add a comment at the top of your `.js` / `.ts` file describing any Redis commands that need to be run to set up data for your example (try and keep this minimal)
+* Use semicolons
+* Use `async` and `await`
+* Use single quotes, `'hello'` not `"hello"`
+* Place your example code in a single `async` function where possible, named according to the file name e.g. `add-to-stream.js` would contain `const addtoStream = async () => { ... };`, and call this function at the end of the file e.g. `addToStream();`
+* Unless your example requires a connection string, assume Redis is on the default localhost port 6379 with no password
+* Use meaningful example data, let's not use `foo`, `bar`, `baz` etc!
+* Leave an empty line at the end of your `.js` file
+* Update this `README.md` file to add your example to the table
+
+Use [connect-as-acl-user.js](connect-as-acl-user.js) as a guide to develop a well formatted example script.
+
+### Example Template
+
+Here's a starter template for adding a new example, imagine this is stored in `do-something.js`:
+
+```javascript
+// This comment should describe what the example does
+// and can extend to multiple lines.
+
+// Set up the data in redis-cli using these commands:
+//   <add your command(s) here, one per line>
+
+import { createClient } from 'redis';
+
+async function doSomething() {
+    const client = createClient();
+
+    await client.connect();
+
+    // Add your example code here...
+
+    await client.quit();
+}
+
+doSomething();
+```

examples/blocking-list-pop.js

@@ -0,0 +1,32 @@
+// This example shows how to use the blocking LPUSH command.
+
+// This code shows how to run with isolation the blPop Command to block the script while waiting for a value to be pushed to the list.
+// The script will be blocked until the LPUSH command is executed.
+// After which we log the list and quit the client.
+
+import { createClient, commandOptions } from 'redis';
+
+async function blockingListPop() {
+	const client = createClient();
+
+	await client.connect();
+
+	const keyName = 'keyName';
+
+	const blpopPromise = client.blPop(
+		commandOptions({ isolated: true }),
+		keyName,
+		0
+	);
+
+	await client.lPush(keyName, 'value');
+
+	await blpopPromise;
+
+	console.log('blpopPromise resolved');
+	console.log(keyName);
+
+	await client.quit();
+}
+
+blockingListPop();

examples/command-with-modifiers.js

@@ -0,0 +1,31 @@
+// Define a custom script that shows example of SET command
+// with several modifiers.
+
+import { createClient } from 'redis';
+
+async function commandWithModifiers() {
+  const client = createClient();
+
+  await client.connect();
+  await client.del('mykey');
+
+  let result = await client.set('mykey', 'myvalue', {
+    EX: 60,
+    GET: true
+  });
+
+  console.log(result); //nil
+
+  result = await client.set('mykey', 'newvalue', {
+    EX: 60,
+    GET: true
+  }
+  );
+
+  console.log(result); //myvalue
+
+  await client.quit();
+}
+
+commandWithModifiers();
+

examples/connect-as-acl-user.js

@@ -0,0 +1,30 @@
+// Connect to Redis 6.x as an ACL user.  Attempt to run a command
+// that the user is allowed to execute, and a command that the 
+// user is not allowed to execute.
+
+// Create the test user in redis-cli with this command:
+//   acl setuser testuser on >testpassword +ping
+
+import { createClient } from 'redis';
+
+async function connectWithACLUser() {
+  const client = createClient({
+    url: 'redis://testuser:testpassword@127.0.0.1:6379'
+  });
+
+  await client.connect();
+
+  // Returns PONG
+  console.log(`Response from PING command: ${await client.ping()}`);
+
+  try {
+    // This will error as this user is not allowed to run this command...
+    console.log(`Response from GET command: ${await client.get('somekey')}`);
+  } catch (e) {
+    console.log(`GET command failed: ${e.message}`);
+  }
+
+  await client.quit();
+}
+
+connectWithACLUser();

examples/lua-multi-incr.js

@@ -0,0 +1,31 @@
+// Define a custome lua script that accepts two keys and an amount to
+// increment each of them by
+
+import { createClient, defineScript } from 'redis';
+
+async function luaMultiIncr() {
+  const client = createClient({
+    scripts: {
+      mincr: defineScript({
+        NUMBER_OF_KEYS: 2,
+        SCRIPT:
+          'return {' +
+          'redis.pcall("INCRBY", KEYS[1], ARGV[1]),' +
+          'redis.pcall("INCRBY", KEYS[2], ARGV[1])' +
+          '}',
+        transformArguments(key1, key2, increment) {
+          return [key1, key2, increment.toString()];
+        },
+      }),
+    },
+  });
+
+  await client.connect();
+
+  await client.set('mykey', '5');
+  console.log(await client.mincr('mykey', 'myotherkey', 10)); // [ 15, 10 ]
+
+  await client.quit();
+}
+
+luaMultiIncr();

examples/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "node-redis-examples",
+  "version": "1.0.0",
+  "description": "node-redis 4 example script",
+  "main": "index.js",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "redis": "../packages/all-in-one"
+  }
+}
+

examples/search+json.js

@@ -0,0 +1,76 @@
+// RediSearch & ReJSON example
+
+import { createClient, SchemaFieldTypes, AggregateGroupByReducers, AggregateSteps } from 'redis';
+
+async function searchPlusJson() {
+  const client = createClient();
+
+  await client.connect();
+
+  await client.flushAll();
+
+  // Create an index
+  await client.ft.create('users', {
+    '$.name': {
+      type: SchemaFieldTypes.TEXT,
+      SORTABLE: 'UNF'
+    },
+    '$.age': SchemaFieldTypes.NUMERIC,
+    '$.coins': SchemaFieldTypes.NUMERIC
+  }, {
+    ON: 'JSON'
+  });
+
+  // Add some users
+  await Promise.all([
+    client.json.set('users:1', '$', {
+      name: 'Alice',
+      age: 32,
+      coins: 100
+    }),
+    client.json.set('users:2', '$', {
+      name: 'Bob',
+      age: 23,
+      coins: 15
+    })
+  ]);
+
+  // Search all users under 30
+  // TODO: why "$.age:[-inf, 30]" does not work?
+  console.log(
+    await client.ft.search('users', '*')
+  );
+  // {
+  //   total: 1,
+  //   documents: [...]
+  // }
+
+  // Some aggrigrations
+  console.log(
+    await client.ft.aggregate('users', '*', {
+      STEPS: [{
+        type: AggregateSteps.GROUPBY,
+        REDUCE: [{
+          type: AggregateGroupByReducers.AVG,
+          property: '$.age',
+          AS: 'avarageAge'
+        }, {
+          type: AggregateGroupByReducers.SUM,
+          property: '$.coins',
+          AS: 'totalCoins'
+        }]
+      }]
+    })
+  );
+  // {
+  //   total: 2,
+  //   results: [{
+  //     avarageAvg: '27.5',
+  //     totalCoins: '115'
+  //   }]
+  // }
+
+  await client.quit();
+}
+
+searchPlusJson();

examples/set-scan.js

@@ -0,0 +1,19 @@
+// An example script that shows how to use the SSCAN iterator functionality to retrieve the contents of a Redis set.
+// Create the set in redis-cli with this command:
+//     sadd setName a b c d e f g h i j k l m n o p q
+
+import { createClient } from 'redis';
+
+async function setScan() {
+  const client = createClient();
+  await client.connect();
+
+  const setName = 'setName';
+  for await (const member of client.sScanIterator(setName)) {
+    console.log(member);
+  }
+
+  await client.quit();
+}
+
+setScan();