tessl/npm-redis

A modern, high performance Redis client for Node.js with full TypeScript support and all Redis Stack modules

—

Pending

Overview

Eval results

Files

JSON Operations

Name: tessl/npm-redis
Author: tessl

JSON path-based operations for storing, retrieving, and manipulating JSON documents in Redis using RedisJSON. Provides type-safe operations for working with complex JSON data structures with path-based access.

Capabilities

Core JSON Operations

Basic JSON document operations for storing and retrieving JSON data.

/**
 * Get JSON data from a key
 * @param key - The JSON key
 * @param options - Optional get parameters (path, indent, newline, space)
 * @returns The JSON value at the specified path, or null if not found
 */
function get(key: RedisArgument, options?: JsonGetOptions): Promise<RedisJSON | null>;

/**
 * Set JSON data at a key
 * @param key - The JSON key
 * @param path - JSON path (default: root '$')
 * @param value - JSON value to set
 * @param options - Optional set conditions (NX, XX)
 * @returns 'OK' if successful, null if condition not met
 */
function set(key: RedisArgument, path: string, value: RedisJSON, options?: JsonSetOptions): Promise<SimpleStringReply<'OK'> | null>;

/**
 * Get JSON data from multiple keys
 * @param keys - Array of JSON keys
 * @param path - JSON path to retrieve
 * @returns Array of JSON values (null for non-existent keys/paths)
 */
function mGet(keys: RedisArgument[], path: string): Promise<ArrayReply<RedisJSON | null>>;

/**
 * Set JSON data at multiple keys
 * @param keyPathValues - Array of key-path-value tuples
 * @returns 'OK'
 */
function mSet(keyPathValues: Array<[key: RedisArgument, path: string, value: RedisJSON]>): Promise<SimpleStringReply<'OK'>>;

/**
 * Delete JSON path from key
 * @param key - The JSON key
 * @param path - JSON path to delete (default: root '$')
 * @returns Number of paths deleted
 */
function del(key: RedisArgument, path?: string): Promise<NumberReply>;

/**
 * Get the type of JSON value at path
 * @param key - The JSON key
 * @param path - JSON path (default: root '$')
 * @returns The JSON type ('null', 'boolean', 'number', 'string', 'object', 'array')  
 */
function type(key: RedisArgument, path?: string): Promise<BlobStringReply | null>;

interface JsonGetOptions {
  /** JSON path to retrieve */
  path?: string | string[];
  /** Indentation string for pretty printing */
  indent?: string;
  /** Newline string for pretty printing */
  newline?: string;
  /** Space string for pretty printing */
  space?: string;
}

interface JsonSetOptions {
  /** Set condition: 'NX' (only if doesn't exist) or 'XX' (only if exists) */
  condition?: 'NX' | 'XX';
  /** 
   * @deprecated Use `{ condition: 'NX' }` instead
   * Only set if path does not exist 
   */
  NX?: boolean;
  /** 
   * @deprecated Use `{ condition: 'XX' }` instead
   * Only set if path exists 
   */
  XX?: boolean;
}

type RedisJSON = string | number | boolean | null | RedisJSON[] | { [key: string]: RedisJSON };

Usage Examples:

import { createClient } from "redis";

const client = createClient();
await client.connect();

// Basic JSON operations
await client.json.set("user:1", "$", {
  name: "Alice",
  age: 30,
  email: "alice@example.com",
  preferences: {
    theme: "dark",
    notifications: true
  },
  tags: ["developer", "nodejs"]
});

// Get entire document
const user = await client.json.get("user:1");
// { name: "Alice", age: 30, email: "alice@example.com", ... }

// Get specific path
const name = await client.json.get("user:1", { path: "$.name" }); // "Alice"
const age = await client.json.get("user:1", { path: "$.age" }); // 30

// Set nested property
await client.json.set("user:1", "$.preferences.theme", "light");

// Multi-get from multiple keys
const users = await client.json.mGet(["user:1", "user:2"], "$.name");
// ["Alice", null] (if user:2 doesn't exist)

// Delete path
await client.json.del("user:1", "$.tags[1]"); // Remove second tag

// Get type information
const type = await client.json.type("user:1", "$.age"); // "number"

String Operations

JSON string manipulation operations.

/**
 * Get length of JSON string at path
 * @param key - The JSON key
 * @param path - JSON path (default: root '$')
 * @returns String length, or array of lengths for multiple paths
 */
function strlen(key: RedisArgument, path?: string): Promise<NumberReply | ArrayReply<NumberReply | null>>;

/**
 * Append string to JSON string at path
 * @param key - The JSON key  
 * @param path - JSON path
 * @param value - String value to append
 * @returns New string length, or array of lengths for multiple paths
 */
function strAppend(key: RedisArgument, path: string, value: RedisArgument): Promise<NumberReply | ArrayReply<NumberReply>>;

Usage Examples:

// String operations
await client.json.set("doc", "$", { message: "Hello" });

// Get string length
const length = await client.json.strlen("doc", "$.message"); // 5

// Append to string
await client.json.strAppend("doc", "$.message", " World");
const newLength = await client.json.strlen("doc", "$.message"); // 11

const message = await client.json.get("doc", { path: "$.message" }); // "Hello World"

Numeric Operations

JSON numeric manipulation operations.

/**
 * Increment JSON number at path
 * @param key - The JSON key
 * @param path - JSON path
 * @param number - Number to add
 * @returns New number value, or array of values for multiple paths
 */
function numIncrBy(key: RedisArgument, path: string, number: number): Promise<BlobStringReply | ArrayReply<BlobStringReply>>;

/**
 * Multiply JSON number at path
 * @deprecated since JSON version 2.0
 * @param key - The JSON key
 * @param path - JSON path
 * @param number - Number to multiply by
 * @returns New number value, or array of values for multiple paths
 */
function numMultBy(key: RedisArgument, path: string, number: number): Promise<BlobStringReply | ArrayReply<BlobStringReply>>;

/**
 * Toggle JSON boolean at path
 * @param key - The JSON key
 * @param path - JSON path
 * @returns New boolean value as array
 */
function toggle(key: RedisArgument, path: string): Promise<ArrayReply<BooleanReply>>;

Usage Examples:

// Numeric operations
await client.json.set("stats", "$", { 
  views: 100, 
  likes: 50, 
  active: true 
});

// Increment number
await client.json.numIncrBy("stats", "$.views", 10); 
const views = await client.json.get("stats", { path: "$.views" }); // 110

// Multiply number (deprecated but still available)
await client.json.numMultBy("stats", "$.likes", 2);
const likes = await client.json.get("stats", { path: "$.likes" }); // 100

// Toggle boolean
await client.json.toggle("stats", "$.active");
const active = await client.json.get("stats", { path: "$.active" }); // false

Array Operations

JSON array manipulation operations.

/**
 * Append values to JSON array at path
 * @param key - The JSON key
 * @param path - JSON path
 * @param values - Values to append
 * @returns New array length, or array of lengths for multiple paths
 */
function arrAppend(key: RedisArgument, path: string, ...values: RedisJSON[]): Promise<NumberReply | ArrayReply<NumberReply>>;

/**
 * Find index of value in JSON array
 * @param key - The JSON key
 * @param path - JSON path
 * @param value - Value to search for
 * @param start - Start index (optional)
 * @param stop - Stop index (optional)
 * @returns Index of value, or -1 if not found
 */
function arrIndex(key: RedisArgument, path: string, value: RedisJSON, start?: number, stop?: number): Promise<NumberReply | ArrayReply<NumberReply>>;

/**
 * Insert values into JSON array at index
 * @param key - The JSON key
 * @param path - JSON path
 * @param index - Index to insert at
 * @param values - Values to insert
 * @returns New array length, or array of lengths for multiple paths
 */
function arrInsert(key: RedisArgument, path: string, index: number, ...values: RedisJSON[]): Promise<NumberReply | ArrayReply<NumberReply>>;

/**
 * Get length of JSON array at path
 * @param key - The JSON key
 * @param path - JSON path (default: root '$')
 * @returns Array length, or array of lengths for multiple paths
 */
function arrLen(key: RedisArgument, path?: string): Promise<NumberReply | ArrayReply<NumberReply | null>>;

/**
 * Remove and return element from JSON array
 * @param key - The JSON key
 * @param path - JSON path (default: root '$')
 * @param index - Index to pop from (default: -1, last element)
 * @returns Popped element, or array of elements for multiple paths
 */
function arrPop(key: RedisArgument, path?: string, index?: number): Promise<BlobStringReply | ArrayReply<BlobStringReply | null>>;

/**
 * Trim JSON array to specified range
 * @param key - The JSON key
 * @param path - JSON path
 * @param start - Start index (inclusive)
 * @param stop - Stop index (inclusive)
 * @returns New array length, or array of lengths for multiple paths
 */
function arrTrim(key: RedisArgument, path: string, start: number, stop: number): Promise<NumberReply | ArrayReply<NumberReply>>;

Usage Examples:

// Array operations
await client.json.set("doc", "$", { 
  tags: ["redis", "json"],
  scores: [10, 20, 30]
});

// Append to array
await client.json.arrAppend("doc", "$.tags", "nodejs", "typescript");
let tags = await client.json.get("doc", { path: "$.tags" });
// ["redis", "json", "nodejs", "typescript"]

// Find array index
const index = await client.json.arrIndex("doc", "$.tags", "nodejs"); // 2

// Insert into array
await client.json.arrInsert("doc", "$.tags", 1, "database");
tags = await client.json.get("doc", { path: "$.tags" });
// ["redis", "database", "json", "nodejs", "typescript"]

// Get array length
const length = await client.json.arrLen("doc", "$.tags"); // 5

// Pop from array
const popped = await client.json.arrPop("doc", "$.tags"); // "typescript"
const lastScore = await client.json.arrPop("doc", "$.scores", -1); // "30"

// Trim array
await client.json.arrTrim("doc", "$.tags", 0, 2); // Keep first 3 elements
tags = await client.json.get("doc", { path: "$.tags" });
// ["redis", "database", "json"]

Object Operations

JSON object manipulation operations.

/**
 * Get JSON object keys at path
 * @param key - The JSON key
 * @param path - JSON path (default: root '$')
 * @returns Array of object keys, or array of key arrays for multiple paths
 */
function objKeys(key: RedisArgument, path?: string): Promise<ArrayReply<BlobStringReply> | ArrayReply<ArrayReply<BlobStringReply>>>;

/**
 * Get number of keys in JSON object at path
 * @param key - The JSON key
 * @param path - JSON path (default: root '$')
 * @returns Number of keys, or array of counts for multiple paths
 */
function objLen(key: RedisArgument, path?: string): Promise<NumberReply | ArrayReply<NumberReply | null>>;

Usage Examples:

// Object operations
await client.json.set("user", "$", {
  profile: {
    name: "Alice",
    age: 30,
    email: "alice@example.com"
  },
  settings: {
    theme: "dark",
    notifications: true
  }
});

// Get object keys
const profileKeys = await client.json.objKeys("user", "$.profile");
// ["name", "age", "email"]

const allKeys = await client.json.objKeys("user"); // Root object keys
// ["profile", "settings"]

// Get object length
const profileSize = await client.json.objLen("user", "$.profile"); // 3
const rootSize = await client.json.objLen("user"); // 2

Utility Operations

Utility operations for JSON data management.

/**
 * Clear JSON value at path (set to default empty value)
 * @param key - The JSON key
 * @param path - JSON path (default: root '$')
 * @returns Number of paths cleared
 */
function clear(key: RedisArgument, path?: string): Promise<NumberReply>;

/**
 * Merge JSON value into existing JSON at path
 * @param key - The JSON key
 * @param path - JSON path
 * @param value - JSON value to merge
 * @returns 'OK'
 */
function merge(key: RedisArgument, path: string, value: RedisJSON): Promise<SimpleStringReply<'OK'>>;

/**
 * Get memory usage of JSON value at path
 * @param key - The JSON key
 * @param path - JSON path (default: root '$')
 * @returns Memory usage in bytes, or array of usage for multiple paths
 */
function debugMemory(key: RedisArgument, path?: string): Promise<NumberReply | ArrayReply<NumberReply>>;

Usage Examples:

// Utility operations
await client.json.set("data", "$", {
  counters: { a: 1, b: 2 },
  items: ["x", "y", "z"],
  config: { enabled: true }
});

// Clear array (makes it empty)
await client.json.clear("data", "$.items");
let items = await client.json.get("data", { path: "$.items" }); // []

// Clear object (makes it empty)
await client.json.clear("data", "$.counters");
let counters = await client.json.get("data", { path: "$.counters" }); // {}

// Merge objects
await client.json.merge("data", "$.config", { timeout: 5000, retries: 3 });
const config = await client.json.get("data", { path: "$.config" });
// { enabled: true, timeout: 5000, retries: 3 }

// Check memory usage
const memory = await client.json.debugMemory("data"); // Memory usage in bytes
const configMemory = await client.json.debugMemory("data", "$.config");

JSON Path Syntax

RedisJSON uses JSONPath syntax for accessing JSON data:

// JSONPath examples:
"$"           // Root
"$.name"      // Top-level 'name' field
"$.user.age"  // Nested field access
"$.items[0]"  // Array index access  
"$.items[-1]" // Last array element
"$.items[*]"  // All array elements
"$..name"     // Recursive descent for 'name'
"$.items[?(@.active)]" // Filter expression

Usage Examples:

await client.json.set("complex", "$", {
  users: [
    { name: "Alice", age: 30, active: true },
    { name: "Bob", age: 25, active: false },
    { name: "Charlie", age: 35, active: true }
  ],
  metadata: {
    total: 3,
    updated: "2023-01-01"
  }
});

// Various path expressions
const firstUser = await client.json.get("complex", { path: "$.users[0]" });
const lastUser = await client.json.get("complex", { path: "$.users[-1]" });
const allNames = await client.json.get("complex", { path: "$.users[*].name" });
const activeUsers = await client.json.get("complex", { path: "$.users[?(@.active)]" });

Type Conversion Helpers

/**
 * Transform JavaScript value to Redis argument
 * @param json - JavaScript value
 * @returns Redis argument representation
 */
function transformRedisJsonArgument(json: RedisJSON): RedisArgument;

/**
 * Transform Redis reply to JavaScript value
 * @param reply - Redis reply
 * @returns JavaScript value
 */
function transformRedisJsonReply(reply: any): RedisJSON;

/**
 * Transform Redis reply to JavaScript value with null handling
 * @param reply - Redis reply
 * @returns JavaScript value or null
 */
function transformRedisJsonNullReply(reply: any): RedisJSON | null;

Install with Tessl CLI