(docs) json: add jsdocs

bobymicroby · bobymicroby · commit 4b32ca731b96 · 2025-05-28T15:16:49.000+03:00
diff --git a/packages/json/lib/commands/ARRAPPEND.ts b/packages/json/lib/commands/ARRAPPEND.ts
@@ -4,6 +4,16 @@ import { RedisArgument, NumberReply, ArrayReply, NullReply, Command } from '@red
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Appends one or more values to the end of an array in a JSON document.
+   * Returns the new array length after append, or null if the path does not exist.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key to append to
+   * @param path - Path to the array in the JSON document
+   * @param json - The first value to append
+   * @param jsons - Additional values to append
+   */
   parseCommand(
     parser: CommandParser,
     key: RedisArgument,
diff --git a/packages/json/lib/commands/ARRINDEX.ts b/packages/json/lib/commands/ARRINDEX.ts
@@ -11,6 +11,18 @@ export interface JsonArrIndexOptions {
 
 export default {
   IS_READ_ONLY: true,
+  /**
+   * Returns the index of the first occurrence of a value in a JSON array.
+   * If the specified value is not found, it returns -1, or null if the path does not exist.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the array
+   * @param path - Path to the array in the JSON document
+   * @param json - The value to search for
+   * @param options - Optional range parameters for the search
+   * @param options.range.start - Starting index for the search
+   * @param options.range.stop - Optional ending index for the search
+   */
   parseCommand(
     parser: CommandParser,
     key: RedisArgument,
diff --git a/packages/json/lib/commands/ARRINSERT.ts b/packages/json/lib/commands/ARRINSERT.ts
@@ -4,6 +4,17 @@ import { RedisJSON, transformRedisJsonArgument } from './helpers';
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Inserts one or more values into an array at the specified index.
+   * Returns the new array length after insert, or null if the path does not exist.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the array
+   * @param path - Path to the array in the JSON document
+   * @param index - The position where to insert the values
+   * @param json - The first value to insert
+   * @param jsons - Additional values to insert
+   */
   parseCommand(
     parser: CommandParser,
     key: RedisArgument,
diff --git a/packages/json/lib/commands/ARRLEN.ts b/packages/json/lib/commands/ARRLEN.ts
@@ -7,6 +7,15 @@ export interface JsonArrLenOptions {
 
 export default {
   IS_READ_ONLY: true,
+  /**
+   * Returns the length of an array in a JSON document.
+   * Returns null if the path does not exist or the value is not an array.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the array
+   * @param options - Optional parameters
+   * @param options.path - Path to the array in the JSON document
+   */
   parseCommand(parser: CommandParser, key: RedisArgument, options?: JsonArrLenOptions) {
     parser.push('JSON.ARRLEN');
     parser.pushKey(key);
diff --git a/packages/json/lib/commands/ARRPOP.ts b/packages/json/lib/commands/ARRPOP.ts
@@ -10,6 +10,16 @@ export interface RedisArrPopOptions {
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Removes and returns an element from an array in a JSON document.
+   * Returns null if the path does not exist or the value is not an array.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the array
+   * @param options - Optional parameters
+   * @param options.path - Path to the array in the JSON document
+   * @param options.index - Optional index to pop from. Default is -1 (last element)
+   */
   parseCommand(parser: CommandParser, key: RedisArgument, options?: RedisArrPopOptions) {
     parser.push('JSON.ARRPOP');
     parser.pushKey(key);
diff --git a/packages/json/lib/commands/ARRTRIM.ts b/packages/json/lib/commands/ARRTRIM.ts
@@ -3,6 +3,16 @@ import { RedisArgument, ArrayReply, NumberReply, NullReply, Command } from '@red
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Trims an array in a JSON document to include only elements within the specified range.
+   * Returns the new array length after trimming, or null if the path does not exist.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the array
+   * @param path - Path to the array in the JSON document
+   * @param start - Starting index (inclusive)
+   * @param stop - Ending index (inclusive)
+   */
   parseCommand(parser: CommandParser, key: RedisArgument, path: RedisArgument, start: number, stop: number) {
     parser.push('JSON.ARRTRIM');
     parser.pushKey(key);
diff --git a/packages/json/lib/commands/CLEAR.ts b/packages/json/lib/commands/CLEAR.ts
@@ -7,6 +7,15 @@ export interface JsonClearOptions {
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Clears container values (arrays/objects) in a JSON document.
+   * Returns the number of values cleared (0 or 1), or null if the path does not exist.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the JSON document
+   * @param options - Optional parameters
+   * @param options.path - Path to the container to clear
+   */
   parseCommand(parser: CommandParser, key: RedisArgument, options?: JsonClearOptions) {
     parser.push('JSON.CLEAR');
     parser.pushKey(key);
diff --git a/packages/json/lib/commands/DEBUG_MEMORY.ts b/packages/json/lib/commands/DEBUG_MEMORY.ts
@@ -7,6 +7,15 @@ export interface JsonDebugMemoryOptions {
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Reports memory usage details for a JSON document value.
+   * Returns size in bytes of the value, or null if the key or path does not exist.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the JSON document
+   * @param options - Optional parameters
+   * @param options.path - Path to the value to examine
+   */
   parseCommand(parser: CommandParser, key: RedisArgument, options?: JsonDebugMemoryOptions) {
     parser.push('JSON.DEBUG', 'MEMORY');
     parser.pushKey(key);
diff --git a/packages/json/lib/commands/DEL.ts b/packages/json/lib/commands/DEL.ts
@@ -7,6 +7,15 @@ export interface JsonDelOptions {
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Deletes a value from a JSON document.
+   * Returns the number of paths deleted (0 or 1), or null if the key does not exist.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the JSON document
+   * @param options - Optional parameters
+   * @param options.path - Path to the value to delete
+   */
   parseCommand(parser: CommandParser, key: RedisArgument, options?: JsonDelOptions) {
     parser.push('JSON.DEL');
     parser.pushKey(key);
diff --git a/packages/json/lib/commands/FORGET.ts b/packages/json/lib/commands/FORGET.ts
@@ -7,6 +7,15 @@ export interface JsonForgetOptions {
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Alias for JSON.DEL - Deletes a value from a JSON document.
+   * Returns the number of paths deleted (0 or 1), or null if the key does not exist.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the JSON document
+   * @param options - Optional parameters 
+   * @param options.path - Path to the value to delete
+   */
   parseCommand(parser: CommandParser, key: RedisArgument, options?: JsonForgetOptions) {
     parser.push('JSON.FORGET');
     parser.pushKey(key);
diff --git a/packages/json/lib/commands/GET.ts b/packages/json/lib/commands/GET.ts
@@ -9,6 +9,15 @@ export interface JsonGetOptions {
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Gets values from a JSON document.
+   * Returns the value at the specified path, or null if the key or path does not exist.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the JSON document
+   * @param options - Optional parameters
+   * @param options.path - Path(s) to the value(s) to retrieve
+   */
   parseCommand(
     parser: CommandParser,
     key: RedisArgument,
diff --git a/packages/json/lib/commands/MERGE.ts b/packages/json/lib/commands/MERGE.ts
@@ -4,6 +4,15 @@ import { RedisJSON, transformRedisJsonArgument } from './helpers';
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Merges a given JSON value into a JSON document.
+   * Returns OK on success, or null if the key does not exist.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the JSON document
+   * @param path - Path to merge into
+   * @param value - JSON value to merge
+   */
   parseCommand(parser: CommandParser, key: RedisArgument, path: RedisArgument, value: RedisJSON) {
     parser.push('JSON.MERGE');
     parser.pushKey(key);
diff --git a/packages/json/lib/commands/MGET.ts b/packages/json/lib/commands/MGET.ts
@@ -4,6 +4,14 @@ import { transformRedisJsonNullReply } from './helpers';
 
 export default {
   IS_READ_ONLY: true,
+  /**
+   * Gets values at a specific path from multiple JSON documents.
+   * Returns an array of values at the path from each key, null for missing keys/paths.
+   * 
+   * @param parser - The Redis command parser
+   * @param keys - Array of keys containing JSON documents
+   * @param path - Path to retrieve from each document
+   */
   parseCommand(parser: CommandParser, keys: Array<RedisArgument>, path: RedisArgument) {
     parser.push('JSON.MGET');
     parser.pushKeys(keys);
diff --git a/packages/json/lib/commands/MSET.ts b/packages/json/lib/commands/MSET.ts
@@ -10,6 +10,16 @@ export interface JsonMSetItem {
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Sets multiple JSON values in multiple documents.
+   * Returns OK on success.
+   * 
+   * @param parser - The Redis command parser
+   * @param items - Array of objects containing key, path, and value to set
+   * @param items[].key - The key containing the JSON document
+   * @param items[].path - Path in the document to set
+   * @param items[].value - JSON value to set at the path
+   */
   parseCommand(parser: CommandParser, items: Array<JsonMSetItem>) {
     parser.push('JSON.MSET');
 
diff --git a/packages/json/lib/commands/NUMINCRBY.ts b/packages/json/lib/commands/NUMINCRBY.ts
@@ -3,6 +3,15 @@ import { RedisArgument, ArrayReply, NumberReply, DoubleReply, NullReply, BlobStr
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Increments a numeric value stored in a JSON document by a given number.
+   * Returns the value after increment, or null if the key/path doesn't exist or value is not numeric.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the JSON document
+   * @param path - Path to the numeric value
+   * @param by - Amount to increment by
+   */
   parseCommand(parser: CommandParser, key: RedisArgument, path: RedisArgument, by: number) {
     parser.push('JSON.NUMINCRBY');
     parser.pushKey(key);
diff --git a/packages/json/lib/commands/NUMMULTBY.ts b/packages/json/lib/commands/NUMMULTBY.ts
@@ -4,6 +4,15 @@ import NUMINCRBY from './NUMINCRBY';
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Multiplies a numeric value stored in a JSON document by a given number.
+   * Returns the value after multiplication, or null if the key/path doesn't exist or value is not numeric.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the JSON document
+   * @param path - Path to the numeric value
+   * @param by - Amount to multiply by
+   */
   parseCommand(parser: CommandParser, key: RedisArgument, path: RedisArgument, by: number) {
     parser.push('JSON.NUMMULTBY');
     parser.pushKey(key);
diff --git a/packages/json/lib/commands/OBJKEYS.ts b/packages/json/lib/commands/OBJKEYS.ts
@@ -7,6 +7,15 @@ export interface JsonObjKeysOptions {
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Returns the keys in the object stored in a JSON document.
+   * Returns array of keys, array of arrays for multiple paths, or null if path doesn't exist.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the JSON document
+   * @param options - Optional parameters
+   * @param options.path - Path to the object to examine
+   */
   parseCommand(parser: CommandParser, key: RedisArgument, options?: JsonObjKeysOptions) {
     parser.push('JSON.OBJKEYS');
     parser.pushKey(key);
diff --git a/packages/json/lib/commands/OBJLEN.ts b/packages/json/lib/commands/OBJLEN.ts
@@ -7,6 +7,15 @@ export interface JsonObjLenOptions {
 
 export default {
   IS_READ_ONLY: true,
+  /**
+   * Returns the number of keys in the object stored in a JSON document.
+   * Returns length of object, array of lengths for multiple paths, or null if path doesn't exist.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the JSON document
+   * @param options - Optional parameters
+   * @param options.path - Path to the object to examine
+   */
   parseCommand(parser: CommandParser, key: RedisArgument, options?: JsonObjLenOptions) {
     parser.push('JSON.OBJLEN');
     parser.pushKey(key);
diff --git a/packages/json/lib/commands/RESP.ts b/packages/json/lib/commands/RESP.ts
@@ -5,6 +5,14 @@ type RESPReply = Array<string | number | RESPReply>;
 
 export default {
     IS_READ_ONLY: true,
+    /**
+     * Returns the JSON value at the specified path in RESP (Redis Serialization Protocol) format.
+     * Returns the value in RESP form, useful for language-independent processing.
+     * 
+     * @param parser - The Redis command parser
+     * @param key - The key containing the JSON document
+     * @param path - Optional path to the value in the document
+     */
     parseCommand(parser: CommandParser, key: RedisArgument, path?: string) {
       parser.push('JSON.RESP');
       parser.pushKey(key);
diff --git a/packages/json/lib/commands/SET.ts b/packages/json/lib/commands/SET.ts
@@ -16,6 +16,19 @@ export interface JsonSetOptions {
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Sets a JSON value at a specific path in a JSON document.
+   * Returns OK on success, or null if condition (NX/XX) is not met.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the JSON document
+   * @param path - Path in the document to set
+   * @param json - JSON value to set at the path
+   * @param options - Optional parameters
+   * @param options.condition - Set condition: NX (only if doesn't exist) or XX (only if exists)
+   * @deprecated options.NX - Use options.condition instead
+   * @deprecated options.XX - Use options.condition instead
+   */
   parseCommand(
     parser: CommandParser,
     key: RedisArgument,
diff --git a/packages/json/lib/commands/STRAPPEND.ts b/packages/json/lib/commands/STRAPPEND.ts
@@ -8,6 +8,16 @@ export interface JsonStrAppendOptions {
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Appends a string to a string value stored in a JSON document.
+   * Returns new string length after append, or null if the path doesn't exist or value is not a string.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the JSON document
+   * @param append - String to append
+   * @param options - Optional parameters
+   * @param options.path - Path to the string value
+   */
   parseCommand(parser: CommandParser, key: RedisArgument, append: string, options?: JsonStrAppendOptions) {
     parser.push('JSON.STRAPPEND');
     parser.pushKey(key);
diff --git a/packages/json/lib/commands/STRLEN.ts b/packages/json/lib/commands/STRLEN.ts
@@ -7,6 +7,15 @@ export interface JsonStrLenOptions {
 
 export default {
   IS_READ_ONLY: true,
+  /**
+   * Returns the length of a string value stored in a JSON document.
+   * Returns string length, array of lengths for multiple paths, or null if path doesn't exist.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the JSON document
+   * @param options - Optional parameters
+   * @param options.path - Path to the string value
+   */
   parseCommand(parser: CommandParser, key: RedisArgument, options?: JsonStrLenOptions) {
     parser.push('JSON.STRLEN');
     parser.pushKey(key);
diff --git a/packages/json/lib/commands/TOGGLE.ts b/packages/json/lib/commands/TOGGLE.ts
@@ -3,6 +3,14 @@ import { RedisArgument, ArrayReply, NumberReply, NullReply, Command, } from '@re
 
 export default {
   IS_READ_ONLY: false,
+  /**
+   * Toggles a boolean value stored in a JSON document.
+   * Returns 1 if value was toggled to true, 0 if toggled to false, or null if path doesn't exist.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the JSON document
+   * @param path - Path to the boolean value
+   */
   parseCommand(parser: CommandParser, key: RedisArgument, path: RedisArgument) {
     parser.push('JSON.TOGGLE');
     parser.pushKey(key);
diff --git a/packages/json/lib/commands/TYPE.ts b/packages/json/lib/commands/TYPE.ts
@@ -7,6 +7,15 @@ export interface JsonTypeOptions {
 
 export default {
   IS_READ_ONLY: true,
+  /**
+   * Returns the type of JSON value at a specific path in a JSON document.
+   * Returns the type as a string, array of types for multiple paths, or null if path doesn't exist.
+   * 
+   * @param parser - The Redis command parser
+   * @param key - The key containing the JSON document
+   * @param options - Optional parameters
+   * @param options.path - Path to examine
+   */
   parseCommand(parser: CommandParser, key: RedisArgument, options?: JsonTypeOptions) {
     parser.push('JSON.TYPE');
     parser.pushKey(key);
