@mulingai-npm/redis 1.14.1 → 2.0.0

package/dist/managers/mulingstream-chunk-manager.d.ts

@@ -1,18 +1,13 @@
 import { RedisClient } from '../redis-client';
 export type StepStatus = 'INIT' | 'DISCARDED' | 'READY' | 'USED';
-export type MulingstreamChunkStatus = 'INIT' | 'STARTED' | 'FINISHED' | 'CANCELED' | 'USED';
-export type MulingstreamChunkStep = 'RECEIVED' | 'STT' | 'TRANSLATION' | 'TTS' | 'EMITTED';
 export type SttProvider = 'azure' | 'whisper' | 'google' | 'aws';
 export type MulingstreamChunkData = {
-    mulingstreamChunkId: string;
-    roomId: string;
     chunkNumber: number;
     language: string;
     sttProviders: SttProvider[];
     targetLanguages: string[];
     finalTranscription: string;
-    mulingstreamChunkStatus: MulingstreamChunkStatus;
-    mulingstreamChunkStep: MulingstreamChunkStep;
+    sttStatus: StepStatus;
     audioChunk: {
         start: number;
         end: number;
@@ -45,7 +40,31 @@ export type MulingstreamChunkData = {
 export declare class MulingstreamChunkManager {
     private redisClient;
     constructor(redisClient: RedisClient);
-    private parseHashData;
+    /**
+     * Initializes a room in Redis as an empty JSON array.
+     * If the key [roomId] already exists, we do NOT overwrite it.
+     * Returns true if room was created, false if room already existed.
+     */
+    initRoom(roomId: string): Promise<boolean>;
+    /**
+     * Returns all rooms. This is naive if you store many other keys in Redis,
+     * because we search keys for pattern "[*]".
+     * Adjust as needed if you have a separate naming prefix.
+     */
+    getRooms(): Promise<string[]>;
+    /**
+     * Returns the entire array of chunks for the given roomId,
+     * or null if the room doesn't exist in Redis.
+     */
+    getMulingstreamChunksByRoom(roomId: string): Promise<MulingstreamChunkData[] | null>;
+    /**
+     * Returns the room array "as is" for debugging
+     * (same as getMulingstreamChunksByRoom in this example).
+     */
+    getRoomById(roomId: string): Promise<MulingstreamChunkData[] | null>;
+    /**
+     * Adds a new Mulingstream chunk to the array stored at [${roomId}].
+     */
     addMulingstreamChunk(params: {
         roomId: string;
         chunkNumber: number;
@@ -58,28 +77,31 @@ export declare class MulingstreamChunkManager {
         theme: string;
         sttProviders: SttProvider[];
         targetLanguages: string[];
-    }): Promise<string>;
-    getMulingstreamChunks(): Promise<MulingstreamChunkData[]>;
-    getMulingstreamChunk(mulingstreamChunkId: string): Promise<MulingstreamChunkData | null>;
-    getMulingstreamChunksByRoom(roomId: string): Promise<MulingstreamChunkData[]>;
-    getByChunkNumber(chunkNumber: number, roomId: string): Promise<MulingstreamChunkData | null>;
-    updateMulingstreamChunkStatus(mulingstreamChunkId: string, mulingstreamChunkStep: MulingstreamChunkStep, mulingstreamChunkStatus: MulingstreamChunkStatus): Promise<boolean>;
-    updateFinalTranscription(mulingstreamChunkId: string, finalTranscription: string): Promise<boolean>;
-    updateSttStatus(mulingstreamChunkId: string, service: SttProvider, status: StepStatus): Promise<boolean>;
-    updateTranscription(mulingstreamChunkId: string, service: SttProvider, transcription: string, sttStatus: StepStatus): Promise<boolean>;
-    /****
-     * Discards all post-STT steps for a given chunk, i.e. sets
-     * all translation[].status and all tts[].status to "DISCARDED".
-     ****/
-    discardAllPostStt(mulingstreamChunkId: string): Promise<boolean>;
-    /****
-     * Discards all post-translation steps for a given chunk, i.e. sets
-     * all tts[].status to "DISCARDED" (leaves translation alone).
-     ****/
-    discardAllPostTranslation(mulingstreamChunkId: string): Promise<boolean>;
-    /****
-     * Discards a specific language in both the translation and tts objects,
-     * setting status to DISCARDED for just that one language.
-     ****/
-    discardLanguage(mulingstreamChunkId: string, language: string): Promise<boolean>;
+    }): Promise<void>;
+    /**
+     * Given roomId and chunkNumber, return the single chunk from the array
+     * or null if not found.
+     */
+    getMulingstreamChunkById(roomId: string, chunkNumber: number): Promise<MulingstreamChunkData | null>;
+    /**
+     * Update STT fields for a given chunk.
+     * If transcription or sttStatus is null, skip that field.
+     */
+    updateStt(roomId: string, chunkNumber: number, sttProvider: SttProvider, options: {
+        transcription?: string;
+        sttStatus?: StepStatus;
+    }): Promise<boolean>;
+    /**
+     * Update the final transcription field for a chunk.
+     */
+    updateFinalTranscription(roomId: string, chunkNumber: number, transcription: string, sttStatus: StepStatus): Promise<boolean>;
+    /**
+     * Discards all post-STT steps for a given chunk:
+     * sets all translation[].status & tts[].status to "DISCARDED".
+     */
+    discardPostStt(roomId: string, chunkNumber: number): Promise<boolean>;
+    /**
+     * Discards a specific language in both translation and tts for a chunk.
+     */
+    discardLanguage(roomId: string, chunkNumber: number, language: string): Promise<boolean>;
 }

package/dist/managers/mulingstream-chunk-manager.js

@@ -1,44 +1,64 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MulingstreamChunkManager = void 0;
-const uuid_1 = require("uuid");
 const EXPIRATION = 12 * 60 * 60; // 12 hours in seconds
 class MulingstreamChunkManager {
     constructor(redisClient) {
         this.redisClient = redisClient;
     }
-    parseHashData(data) {
-        // Parse the arrays and nested JSON fields
-        const sttProviders = JSON.parse(data.sttProviders);
-        const targetLanguages = JSON.parse(data.targetLanguages);
-        const audioChunk = JSON.parse(data.audioChunk);
-        const stt = JSON.parse(data.stt);
-        const translation = JSON.parse(data.translation);
-        const tts = JSON.parse(data.tts);
-        return {
-            mulingstreamChunkId: data.mulingstreamChunkId,
-            roomId: data.roomId,
-            chunkNumber: parseInt(data.chunkNumber, 10),
-            language: data.language,
-            sttProviders,
-            targetLanguages,
-            finalTranscription: data.finalTranscription,
-            mulingstreamChunkStatus: data.mulingstreamChunkStatus,
-            mulingstreamChunkStep: data.mulingstreamChunkStep,
-            audioChunk,
-            stt,
-            translation,
-            tts
-        };
+    /**
+     * Initializes a room in Redis as an empty JSON array.
+     * If the key [roomId] already exists, we do NOT overwrite it.
+     * Returns true if room was created, false if room already existed.
+     */
+    async initRoom(roomId) {
+        // Check if the key already exists (JSON.GET)
+        const existing = await this.redisClient.jsonGet(`[${roomId}]`, '.');
+        if (existing !== null) {
+            // Already exists
+            return false;
+        }
+        // Create an empty array at the root
+        await this.redisClient.jsonSet(`[${roomId}]`, '.', []);
+        await this.redisClient.expire(`[${roomId}]`, EXPIRATION);
+        return true;
+    }
+    /**
+     * Returns all rooms. This is naive if you store many other keys in Redis,
+     * because we search keys for pattern "[*]".
+     * Adjust as needed if you have a separate naming prefix.
+     */
+    async getRooms() {
+        // e.g., if we store everything as [foo], [bar], etc., we do:
+        const rooms = await this.redisClient.keys('\\[*\\]');
+        // This returns the raw keys, e.g. ['[myRoom]', '[anotherRoom]']
+        // We might want to strip off the brackets:
+        return rooms.map((k) => k.replace(/^\[|\]$/g, ''));
+    }
+    /**
+     * Returns the entire array of chunks for the given roomId,
+     * or null if the room doesn't exist in Redis.
+     */
+    async getMulingstreamChunksByRoom(roomId) {
+        // JSON.GET [roomId] .
+        const chunks = await this.redisClient.jsonGet(`[${roomId}]`, '.');
+        if (chunks === null)
+            return null; // room not found
+        return chunks;
+    }
+    /**
+     * Returns the room array "as is" for debugging
+     * (same as getMulingstreamChunksByRoom in this example).
+     */
+    async getRoomById(roomId) {
+        return this.getMulingstreamChunksByRoom(roomId);
     }
-    // Adds a new mulingstream chunk.
-    // - Creates a unique mulingstreamChunkId.
-    // - Stores the chunk data in a Redis hash under `mulingstreamChunk:{mulingstreamChunkId}`.
-    // - Applies an expiration (12h).
+    /**
+     * Adds a new Mulingstream chunk to the array stored at [${roomId}].
+     */
     async addMulingstreamChunk(params) {
         const { roomId, chunkNumber, language, start, end, duration, isFirst, isLast, theme, sttProviders, targetLanguages } = params;
-        const mulingstreamChunkId = `[${roomId}]-[${chunkNumber}]-[${(0, uuid_1.v4)()}]`;
-        // Prepare the nested objects
+        // Build the chunk
         const audioChunk = {
             start,
             end,
@@ -48,16 +68,15 @@ class MulingstreamChunkManager {
             theme,
             processingStart: Date.now()
         };
-        // Build the STT object
-        // For each service in `services`, create { transcription: '', status: 'INIT' }
+        // Build stt object
         const stt = {};
-        for (const service of sttProviders) {
-            stt[service] = {
+        for (const svc of sttProviders) {
+            stt[svc] = {
                 transcription: '',
                 status: 'INIT'
             };
         }
-        // Build translation & tts objects keyed by each target language
+        // Build translation and tts objects
         const translation = {};
         const tts = {};
         for (const lang of targetLanguages) {
@@ -71,217 +90,123 @@ class MulingstreamChunkManager {
                 isEmitted: false
             };
         }
-        // Root-level finalTranscription is empty initially
-        const finalTranscription = '';
-        // Store the data in a Redis hash
-        await this.redisClient.hset(`mulingstreamChunk:${mulingstreamChunkId}`, {
-            mulingstreamChunkId,
-            roomId,
-            chunkNumber: chunkNumber.toString(),
+        const newChunk = {
+            chunkNumber,
             language,
-            sttProviders: JSON.stringify(sttProviders),
-            targetLanguages: JSON.stringify(targetLanguages),
-            finalTranscription,
-            mulingstreamChunkStatus: 'INIT',
-            mulingstreamChunkStep: 'RECEIVED',
-            audioChunk: JSON.stringify(audioChunk),
-            stt: JSON.stringify(stt),
-            translation: JSON.stringify(translation),
-            tts: JSON.stringify(tts)
-        });
-        // set expiration
-        await this.redisClient.expire(`mulingstreamChunk:${mulingstreamChunkId}`, EXPIRATION);
-        return mulingstreamChunkId;
-    }
-    // Retrieves all mulingstream chunks by scanning keys `mulingstreamChunk:*`.
-    async getMulingstreamChunks() {
-        const keys = await this.redisClient.keys('mulingstreamChunk:*');
-        if (!keys || keys.length === 0) {
-            return [];
-        }
-        const results = [];
-        for (const key of keys) {
-            const data = await this.redisClient.hgetall(key);
-            if (data && data.mulingstreamChunkId) {
-                results.push(this.parseHashData(data));
-            }
-        }
-        return results;
-    }
-    // Retrieves a single mulingstream chunk by ID.
-    async getMulingstreamChunk(mulingstreamChunkId) {
-        const data = await this.redisClient.hgetall(`mulingstreamChunk:${mulingstreamChunkId}`);
-        if (!data || !data.mulingstreamChunkId) {
-            return null;
-        }
-        return this.parseHashData(data);
-    }
-    // Retrieves all mulingstream chunks for a specific room by pattern matching keys `mulingstreamChunk:[roomId]-*`.
-    async getMulingstreamChunksByRoom(roomId) {
-        const pattern = `mulingstreamChunk:[${roomId}]-*`;
-        const keys = await this.redisClient.keys(pattern);
-        if (!keys || keys.length === 0) {
-            return [];
-        }
-        const results = [];
-        for (const key of keys) {
-            const data = await this.redisClient.hgetall(key);
-            if (!data || !data.mulingstreamChunkId) {
-                continue;
-            }
-            results.push(this.parseHashData(data));
-        }
-        return results;
+            sttProviders,
+            targetLanguages,
+            finalTranscription: '',
+            sttStatus: 'INIT',
+            audioChunk,
+            stt,
+            translation,
+            tts
+        };
+        // Append it to the array
+        await this.redisClient.jsonArrAppend(`[${roomId}]`, '.', // the root of the JSON document (the array)
+        newChunk);
     }
-    // Retrieves a mulingstream chunk by (roomId, chunkNumber).
-    // Since mulingstreamChunkId = `[${roomId}]-[${chunkNumber}]-[uuid]`, we can pattern-match on keys.
-    async getByChunkNumber(chunkNumber, roomId) {
-        const pattern = `mulingstreamChunk:[${roomId}]-[${chunkNumber}]-*`;
-        const keys = await this.redisClient.keys(pattern);
-        if (!keys || keys.length === 0) {
+    /**
+     * Given roomId and chunkNumber, return the single chunk from the array
+     * or null if not found.
+     */
+    async getMulingstreamChunkById(roomId, chunkNumber) {
+        // Retrieve the entire array
+        const chunks = await this.getMulingstreamChunksByRoom(roomId);
+        if (!chunks)
             return null;
-        }
-        // If multiple match, return the first
-        const data = await this.redisClient.hgetall(keys[0]);
-        if (!data || !data.mulingstreamChunkId) {
-            return null;
-        }
-        return this.parseHashData(data);
-    }
-    async updateMulingstreamChunkStatus(mulingstreamChunkId, mulingstreamChunkStep, mulingstreamChunkStatus) {
-        // Fetch the chunk data first
-        const data = await this.redisClient.hgetall(`mulingstreamChunk:${mulingstreamChunkId}`);
-        if (!data || !data.mulingstreamChunkId) {
-            return false; // The chunk may not exist or has expired
-        }
-        // Update only the chunk status and step
-        await this.redisClient.hset(`mulingstreamChunk:${mulingstreamChunkId}`, {
-            mulingstreamChunkStatus,
-            mulingstreamChunkStep
-        });
-        return true;
+        // Find by chunkNumber
+        const chunk = chunks.find((c) => c.chunkNumber === chunkNumber);
+        return chunk || null;
     }
-    async updateFinalTranscription(mulingstreamChunkId, finalTranscription) {
-        // Fetch the chunk data first
-        const data = await this.redisClient.hgetall(`mulingstreamChunk:${mulingstreamChunkId}`);
-        if (!data || !data.mulingstreamChunkId) {
-            return false; // The chunk may not exist or has expired
-        }
-        // Update the finalTranscription field
-        await this.redisClient.hset(`mulingstreamChunk:${mulingstreamChunkId}`, {
-            finalTranscription
-        });
-        return true;
-    }
-    // Updates the STT status for a given service in the chunk's STT data.
-    async updateSttStatus(mulingstreamChunkId, service, status) {
-        const data = await this.redisClient.hgetall(`mulingstreamChunk:${mulingstreamChunkId}`);
-        if (!data || !data.mulingstreamChunkId) {
+    /**
+     * Update STT fields for a given chunk.
+     * If transcription or sttStatus is null, skip that field.
+     */
+    async updateStt(roomId, chunkNumber, sttProvider, options) {
+        const chunks = await this.getMulingstreamChunksByRoom(roomId);
+        if (!chunks)
             return false;
-        }
-        const stt = JSON.parse(data.stt);
-        if (!stt[service]) {
-            return false; // service not in stt object
-        }
-        stt[service].status = status;
-        await this.redisClient.hset(`mulingstreamChunk:${mulingstreamChunkId}`, {
-            stt: JSON.stringify(stt)
-        });
-        return true;
-    }
-    // Updates the transcription + status for a given service in the chunk's STT data.
-    async updateTranscription(mulingstreamChunkId, service, transcription, sttStatus) {
-        const data = await this.redisClient.hgetall(`mulingstreamChunk:${mulingstreamChunkId}`);
-        if (!data || !data.mulingstreamChunkId) {
+        // Find the chunk
+        const chunkIndex = chunks.findIndex((c) => c.chunkNumber === chunkNumber);
+        if (chunkIndex === -1)
             return false;
+        const chunk = chunks[chunkIndex];
+        // If this stt provider doesn't exist, ignore
+        if (!chunk.stt[sttProvider])
+            return false;
+        // Update
+        if (options.transcription != null) {
+            chunk.stt[sttProvider].transcription = options.transcription;
         }
-        const stt = JSON.parse(data.stt);
-        if (!stt[service]) {
-            return false; // service not in stt object
+        if (options.sttStatus != null) {
+            chunk.stt[sttProvider].status = options.sttStatus;
         }
-        stt[service].transcription = transcription;
-        stt[service].status = sttStatus;
-        await this.redisClient.hset(`mulingstreamChunk:${mulingstreamChunkId}`, {
-            stt: JSON.stringify(stt)
-        });
+        // Write back
+        chunks[chunkIndex] = chunk;
+        await this.redisClient.jsonSet(`[${roomId}]`, '.', chunks);
         return true;
     }
-    /****
-     * Discards all post-STT steps for a given chunk, i.e. sets
-     * all translation[].status and all tts[].status to "DISCARDED".
-     ****/
-    async discardAllPostStt(mulingstreamChunkId) {
-        // Fetch the chunk
-        const data = await this.redisClient.hgetall(`mulingstreamChunk:${mulingstreamChunkId}`);
-        if (!data || !data.mulingstreamChunkId) {
+    /**
+     * Update the final transcription field for a chunk.
+     */
+    async updateFinalTranscription(roomId, chunkNumber, transcription, sttStatus) {
+        const chunks = await this.getMulingstreamChunksByRoom(roomId);
+        if (!chunks)
             return false;
-        }
-        // Parse the translation and tts objects
-        const translation = JSON.parse(data.translation);
-        const tts = JSON.parse(data.tts);
-        // Set every language status to DISCARDED in translation
-        for (const lang of Object.keys(translation)) {
-            translation[lang].status = 'DISCARDED';
-        }
-        // Set every language status to DISCARDED in tts
-        for (const lang of Object.keys(tts)) {
-            tts[lang].status = 'DISCARDED';
-        }
+        // Find the chunk
+        const chunkIndex = chunks.findIndex((c) => c.chunkNumber === chunkNumber);
+        if (chunkIndex === -1)
+            return false;
+        chunks[chunkIndex].finalTranscription = transcription;
+        chunks[chunkIndex].sttStatus = sttStatus;
         // Write back
-        await this.redisClient.hset(`mulingstreamChunk:${mulingstreamChunkId}`, {
-            translation: JSON.stringify(translation),
-            tts: JSON.stringify(tts)
-        });
+        await this.redisClient.jsonSet(`[${roomId}]`, '.', chunks);
         return true;
     }
-    /****
-     * Discards all post-translation steps for a given chunk, i.e. sets
-     * all tts[].status to "DISCARDED" (leaves translation alone).
-     ****/
-    async discardAllPostTranslation(mulingstreamChunkId) {
-        // Fetch the chunk
-        const data = await this.redisClient.hgetall(`mulingstreamChunk:${mulingstreamChunkId}`);
-        if (!data || !data.mulingstreamChunkId) {
+    /**
+     * Discards all post-STT steps for a given chunk:
+     * sets all translation[].status & tts[].status to "DISCARDED".
+     */
+    async discardPostStt(roomId, chunkNumber) {
+        const chunks = await this.getMulingstreamChunksByRoom(roomId);
+        if (!chunks)
+            return false;
+        // Find chunk
+        const chunkIndex = chunks.findIndex((c) => c.chunkNumber === chunkNumber);
+        if (chunkIndex === -1)
             return false;
+        // Discard translation & TTS statuses
+        const chunk = chunks[chunkIndex];
+        for (const lang of Object.keys(chunk.translation)) {
+            chunk.translation[lang].status = 'DISCARDED';
         }
-        // Parse the tts object
-        const tts = JSON.parse(data.tts);
-        // Set every language status to DISCARDED in tts
-        for (const lang of Object.keys(tts)) {
-            tts[lang].status = 'DISCARDED';
+        for (const lang of Object.keys(chunk.tts)) {
+            chunk.tts[lang].status = 'DISCARDED';
         }
-        // Write back
-        await this.redisClient.hset(`mulingstreamChunk:${mulingstreamChunkId}`, {
-            tts: JSON.stringify(tts)
-        });
+        chunks[chunkIndex] = chunk;
+        await this.redisClient.jsonSet(`[${roomId}]`, '.', chunks);
         return true;
     }
-    /****
-     * Discards a specific language in both the translation and tts objects,
-     * setting status to DISCARDED for just that one language.
-     ****/
-    async discardLanguage(mulingstreamChunkId, language) {
-        // Fetch the chunk
-        const data = await this.redisClient.hgetall(`mulingstreamChunk:${mulingstreamChunkId}`);
-        if (!data || !data.mulingstreamChunkId) {
+    /**
+     * Discards a specific language in both translation and tts for a chunk.
+     */
+    async discardLanguage(roomId, chunkNumber, language) {
+        const chunks = await this.getMulingstreamChunksByRoom(roomId);
+        if (!chunks)
             return false;
+        const chunkIndex = chunks.findIndex((c) => c.chunkNumber === chunkNumber);
+        if (chunkIndex === -1)
+            return false;
+        const chunk = chunks[chunkIndex];
+        if (chunk.translation[language]) {
+            chunk.translation[language].status = 'DISCARDED';
         }
-        // Parse the translation and tts objects
-        const translation = JSON.parse(data.translation);
-        const tts = JSON.parse(data.tts);
-        // If the language exists in translation, discard
-        if (translation[language]) {
-            translation[language].status = 'DISCARDED';
-        }
-        // If the language exists in tts, discard
-        if (tts[language]) {
-            tts[language].status = 'DISCARDED';
+        if (chunk.tts[language]) {
+            chunk.tts[language].status = 'DISCARDED';
         }
-        // Write back
-        await this.redisClient.hset(`mulingstreamChunk:${mulingstreamChunkId}`, {
-            translation: JSON.stringify(translation),
-            tts: JSON.stringify(tts)
-        });
+        chunks[chunkIndex] = chunk;
+        await this.redisClient.jsonSet(`[${roomId}]`, '.', chunks);
         return true;
     }
 }

package/dist/redis-client.d.ts

@@ -19,4 +19,8 @@ export declare class RedisClient {
     flushAll(): Promise<string>;
     flushDb(): Promise<string>;
     expire(key: string, seconds: number): Promise<number>;
+    jsonSet<T>(key: string, path: string, value: T): Promise<string>;
+    jsonGet<T>(key: string, path: string): Promise<T | null>;
+    jsonDel(key: string, path: string): Promise<number>;
+    jsonArrAppend<T>(key: string, path: string, ...values: T[]): Promise<number>;
 }

package/dist/redis-client.js

@@ -61,5 +61,25 @@ class RedisClient {
     async expire(key, seconds) {
         return this.client.expire(key, seconds);
     }
+    async jsonSet(key, path, value) {
+        const result = await this.client.call('JSON.SET', key, path, JSON.stringify(value));
+        return result;
+    }
+    async jsonGet(key, path) {
+        const result = (await this.client.call('JSON.GET', key, path));
+        if (!result) {
+            return null;
+        }
+        return JSON.parse(result);
+    }
+    async jsonDel(key, path) {
+        const result = await this.client.call('JSON.DEL', key, path);
+        return Number(result);
+    }
+    async jsonArrAppend(key, path, ...values) {
+        const stringifiedValues = values.map((v) => JSON.stringify(v));
+        const result = await this.client.call('JSON.ARRAPPEND', key, path, ...stringifiedValues);
+        return Number(result);
+    }
 }
 exports.RedisClient = RedisClient;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mulingai-npm/redis",
-    "version": "1.14.1",
+    "version": "2.0.0",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "repository": {