Update doctests

doctests/README.md

@@ -0,0 +1,32 @@
+# Command examples for redis.io
+
+## 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 doctests
+$ npm install
+```
+
+## How to add examples
+
+Create regular node file in the current folder with meaningful name. It makes sense prefix example files with
+command category (e.g. string, set, list, hash, etc) to make navigation in the folder easier.
+
+### Special markup
+
+See https://github.com/redis-stack/redis-stack-website#readme for more details.
+
+## How to test the examples
+
+Just include necessary assertions in the example file and run
+```bash
+sh doctests/run_examples.sh
+```
+to test all examples in the current folder.
+
+See `tests.js` for more details.

doctests/cmds-cnxmgmt.js

@@ -0,0 +1,49 @@
+// EXAMPLE: cmds_cnxmgmt
+// REMOVE_START
+import assert from "node:assert";
+// REMOVE_END
+
+// HIDE_START
+import { createClient } from 'redis';
+
+const client = createClient();
+await client.connect().catch(console.error);
+// HIDE_END
+
+// STEP_START auth1
+// REMOVE_START
+await client.sendCommand(['CONFIG', 'SET', 'requirepass', 'temp_pass']);
+// REMOVE_END
+const res1 = await client.auth({ password: 'temp_pass' });
+console.log(res1); // OK
+
+const res2 = await client.auth({ username: 'default', password: 'temp_pass' });
+console.log(res2); // OK
+
+// REMOVE_START
+assert.equal(res1, "OK");
+assert.equal(res2, "OK");
+await client.sendCommand(['CONFIG', 'SET', 'requirepass', '']);
+// REMOVE_END
+// STEP_END
+
+// STEP_START auth2
+// REMOVE_START
+await client.sendCommand([
+  'ACL', 'SETUSER', 'test-user',
+  'on', '>strong_password', '+acl'
+]);
+// REMOVE_END
+const res3 = await client.auth({ username: 'test-user', password: 'strong_password' });
+console.log(res3); // OK
+
+// REMOVE_START
+assert.equal(res3, "OK");
+await client.auth({ username: 'default', password: '' })
+await client.sendCommand(['ACL', 'DELUSER', 'test-user']);
+// REMOVE_END
+// STEP_END
+
+// HIDE_START
+await client.quit();
+// HIDE_END

doctests/cmds-generic.js

@@ -0,0 +1,195 @@
+// EXAMPLE: cmds_generic
+// REMOVE_START
+import assert from "node:assert";
+// REMOVE_END
+
+// HIDE_START
+import { createClient } from 'redis';
+
+const client = createClient();
+await client.connect().catch(console.error);
+// HIDE_END
+
+// STEP_START del
+const delRes1 = await client.set('key1', 'Hello');
+console.log(delRes1); // OK
+
+const delRes2 = await client.set('key2', 'World');
+console.log(delRes2); // OK
+
+const delRes3 = await client.del(['key1', 'key2', 'key3']);
+console.log(delRes3); // 2
+// REMOVE_START
+assert.equal(delRes3, 2);
+// REMOVE_END
+// STEP_END
+
+// STEP_START expire
+const expireRes1 = await client.set('mykey', 'Hello');
+console.log(expireRes1); // OK
+
+const expireRes2 = await client.expire('mykey', 10);
+console.log(expireRes2); // 1
+
+const expireRes3 = await client.ttl('mykey');
+console.log(expireRes3); // 10
+// REMOVE_START
+assert.equal(expireRes3, 10);
+// REMOVE_END
+
+const expireRes4 = await client.set('mykey', 'Hello World');
+console.log(expireRes4); // OK
+
+const expireRes5 = await client.ttl('mykey');
+console.log(expireRes5); // -1
+// REMOVE_START
+assert.equal(expireRes5, -1);
+// REMOVE_END
+
+const expireRes6 = await client.expire('mykey', 10, "XX");
+console.log(expireRes6); // 0
+// REMOVE_START
+assert.equal(expireRes6, 0)
+// REMOVE_END
+
+const expireRes7 = await client.ttl('mykey');
+console.log(expireRes7); // -1
+// REMOVE_START
+assert.equal(expireRes7, -1);
+// REMOVE_END
+
+const expireRes8 = await client.expire('mykey', 10, "NX");
+console.log(expireRes8); // 1
+// REMOVE_START
+assert.equal(expireRes8, 1);
+// REMOVE_END
+
+const expireRes9 = await client.ttl('mykey');
+console.log(expireRes9); // 10
+// REMOVE_START
+assert.equal(expireRes9, 10);
+await client.del('mykey');
+// REMOVE_END
+// STEP_END
+
+// STEP_START ttl
+const ttlRes1 = await client.set('mykey', 'Hello');
+console.log(ttlRes1); // OK
+
+const ttlRes2 = await client.expire('mykey', 10);
+console.log(ttlRes2); // 1
+
+const ttlRes3 = await client.ttl('mykey');
+console.log(ttlRes3); // 10
+// REMOVE_START
+assert.equal(ttlRes3, 10);
+await client.del('mykey');
+// REMOVE_END
+// STEP_END
+
+// STEP_START scan1
+const scan1Res1 = await client.sAdd('myset', ['1', '2', '3', 'foo', 'foobar', 'feelsgood']);
+console.log(scan1Res1); // 6
+
+let scan1Res2 = [];
+for await (const value of client.sScanIterator('myset', { MATCH: 'f*' })) {
+    scan1Res2 = scan1Res2.concat(value);
+}
+console.log(scan1Res2); // ['foo', 'foobar', 'feelsgood']
+// REMOVE_START
+console.assert(scan1Res2.sort().toString() === ['foo', 'foobar', 'feelsgood'].sort().toString());
+await client.del('myset');
+// REMOVE_END
+// STEP_END
+
+// STEP_START scan2
+// REMOVE_START
+for (let i = 1; i <= 1000; i++) {
+    await client.set(`key:${i}`, i);
+}
+// REMOVE_END
+let cursor = '0';
+let scanResult;
+
+scanResult = await client.scan(cursor, { MATCH: '*11*' });
+console.log(scanResult.cursor, scanResult.keys);
+
+scanResult = await client.scan(scanResult.cursor, { MATCH: '*11*' });
+console.log(scanResult.cursor, scanResult.keys);
+
+scanResult = await client.scan(scanResult.cursor, { MATCH: '*11*' });
+console.log(scanResult.cursor, scanResult.keys);
+
+scanResult = await client.scan(scanResult.cursor, { MATCH: '*11*' });
+console.log(scanResult.cursor, scanResult.keys);
+
+scanResult = await client.scan(scanResult.cursor, { MATCH: '*11*', COUNT: 1000 });
+console.log(scanResult.cursor, scanResult.keys);
+// REMOVE_START
+console.assert(scanResult.keys.length === 18);
+cursor = '0';
+const prefix = 'key:*';
+while (cursor !== '0') {
+    scanResult = await client.scan(cursor, { MATCH: prefix, COUNT: 1000 });
+    console.log(scanResult.cursor, scanResult.keys);
+    cursor = scanResult.cursor;
+    const keys = scanResult.keys;
+    if (keys.length) {
+        await client.del(keys);
+    }
+}
+// REMOVE_END
+// STEP_END
+
+// STEP_START scan3
+const scan3Res1 = await client.geoAdd('geokey', { longitude: 0, latitude: 0, member: 'value' });
+console.log(scan3Res1); // 1
+
+const scan3Res2 = await client.zAdd('zkey', [{ score: 1000, value: 'value' }]);
+console.log(scan3Res2); // 1
+
+const scan3Res3 = await client.type('geokey');
+console.log(scan3Res3); // zset
+// REMOVE_START
+console.assert(scan3Res3 === 'zset');
+// REMOVE_END
+
+const scan3Res4 = await client.type('zkey');
+console.log(scan3Res4); // zset
+// REMOVE_START
+console.assert(scan3Res4 === 'zset');
+// REMOVE_END
+
+const scan3Res5 = await client.scan('0', { TYPE: 'zset' });
+console.log(scan3Res5.keys); // ['zkey', 'geokey']
+// REMOVE_START
+console.assert(scan3Res5.keys.sort().toString() === ['zkey', 'geokey'].sort().toString());
+await client.del(['geokey', 'zkey']);
+// REMOVE_END
+// STEP_END
+
+// STEP_START scan4
+const scan4Res1 = await client.hSet('myhash', { a: 1, b: 2 });
+console.log(scan4Res1); // 2
+
+const scan4Res2 = await client.hScan('myhash', 0);
+console.log(scan4Res2.tuples); // [{field: 'a', value: '1'}, {field: 'b', value: '2'}]
+// REMOVE_START
+assert.deepEqual(scan4Res2.tuples, [
+  { field: 'a', value: '1' },
+  { field: 'b', value: '2' }
+]);
+// REMOVE_END
+
+const scan4Res3 = await client.hScan('myhash', 0, { COUNT: 10 });
+const items = scan4Res3.tuples.map((item) => item.field)
+console.log(items); // ['a', 'b']
+// REMOVE_START
+assert.deepEqual(items, ['a', 'b'])
+await client.del('myhash');
+// REMOVE_END
+// STEP_END
+
+// HIDE_START
+await client.quit();
+// HIDE_END

doctests/cmds-hash.js

@@ -0,0 +1,109 @@
+// EXAMPLE: cmds_hash
+// HIDE_START
+import assert from 'node:assert';
+import { createClient } from 'redis';
+
+const client = createClient();
+await client.connect().catch(console.error);
+// HIDE_END
+
+// STEP_START hset
+const res1 = await client.hSet('myhash', 'field1', 'Hello')
+console.log(res1) // 1
+
+const res2 = await client.hGet('myhash', 'field1')
+console.log(res2) // Hello
+
+const res3 = await client.hSet(
+  'myhash',
+  {
+    'field2': 'Hi',
+    'field3': 'World'
+  }
+)
+console.log(res3) // 2
+
+const res4 = await client.hGet('myhash', 'field2')
+console.log(res4) // Hi
+
+const res5 = await client.hGet('myhash', 'field3')
+console.log(res5) // World
+
+const res6 = await client.hGetAll('myhash')
+console.log(res6)  
+
+// REMOVE_START
+assert.equal(res1, 1);
+assert.equal(res2, 'Hello');
+assert.equal(res3, 2);
+assert.equal(res4, 'Hi');
+assert.equal(res5, 'World');
+assert.deepEqual(res6, {
+  field1: 'Hello',
+  field2: 'Hi',
+  field3: 'World'
+});
+await client.del('myhash')
+// REMOVE_END
+// STEP_END
+
+// STEP_START hget
+const res7 = await client.hSet('myhash', 'field1', 'foo')
+console.log(res7) // 1
+
+const res8 = await client.hGet('myhash', 'field1')
+console.log(res8) // foo
+
+const res9 = await client.hGet('myhash', 'field2')
+console.log(res9) // null
+
+// REMOVE_START
+assert.equal(res7, 1);
+assert.equal(res8, 'foo');
+assert.equal(res9, null);
+await client.del('myhash')
+// REMOVE_END
+// STEP_END
+
+// STEP_START hgetall
+const res10 = await client.hSet(
+  'myhash',
+  {
+    'field1': 'Hello',
+    'field2': 'World'
+  }
+)
+
+const res11 = await client.hGetAll('myhash')
+console.log(res11) // [Object: null prototype] { field1: 'Hello', field2: 'World' }
+
+// REMOVE_START
+assert.deepEqual(res11, {
+  field1: 'Hello',
+  field2: 'World'
+});
+await client.del('myhash')
+// REMOVE_END
+// STEP_END
+
+// STEP_START hvals
+const res12 = await client.hSet(
+  'myhash',
+  {
+    'field1': 'Hello',
+    'field2': 'World'
+  }
+)
+
+const res13 = await client.hVals('myhash')
+console.log(res13) // [ 'Hello', 'World' ]
+
+// REMOVE_START
+assert.deepEqual(res13, [ 'Hello', 'World' ]);
+await client.del('myhash')
+// REMOVE_END
+// STEP_END
+
+// HIDE_START
+await client.close();
+// HIDE_END