redis-graph-cache 1.0.0

package/dist/core/compression.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Optional value compression for entity payloads.
+ *
+ * Why this exists:
+ *   - Entity payloads (post + nested relationships) can be 5-50 KB.
+ *   - At 50k concurrent users this is meaningful network bandwidth and
+ *     Redis memory pressure.
+ *   - Compression cuts typical JSON to ~30% of original size; even with
+ *     base64 envelope overhead the net saving is 50-60%.
+ *
+ * Why ONLY entity values are compressed (not list values):
+ *   - List values are JSON arrays of ids that the atomic Lua scripts
+ *     parse server-side via `cjson.decode`. Compressed payloads would
+ *     not parse and would break list-add / list-remove atomic ops.
+ *   - Entity values are always parsed in Node, never inside Redis, so
+ *     they're safe to ship in a compressed envelope.
+ *
+ * Backward compatibility:
+ *   - Plain JSON (starts with `{` or `[`) is returned untouched on
+ *     decode, so existing keys keep working when compression is enabled.
+ *   - Compressed values carry a 4-character magic prefix `\x00z1:` that
+ *     cannot occur at the start of valid JSON.
+ *   - Writers can disable compression at any time and readers will
+ *     transparently handle a mix of compressed and uncompressed values.
+ */
+/**
+ * Wraps the (de)serialisation of an entity JSON string. A no-op codec
+ * (`enabled = false`) returns inputs unchanged on both encode and decode,
+ * with a fast-path so the engine pays virtually zero cost when the
+ * feature is off.
+ */
+export declare class CompressionCodec {
+    readonly enabled: boolean;
+    readonly threshold: number;
+    constructor(enabled: boolean, threshold: number);
+    /**
+     * Encode a value for storage. When compression is disabled or the
+     * payload is below the threshold, returns the input unchanged so we
+     * don't add overhead to small entities.
+     */
+    encode(value: string): string;
+    /**
+     * Decode a value read from Redis. Detects the magic prefix to decide
+     * whether to inflate. Untagged values pass through, which is what
+     * makes this safe to deploy on top of an existing cache: any data
+     * written before compression was enabled keeps reading correctly.
+     *
+     * Throws if a tagged value is malformed; that's a hard error worth
+     * surfacing because it indicates corruption rather than a stale
+     * format.
+     */
+    decode(value: string): string;
+}
+/**
+ * Fast-path codec used when compression is disabled. Defined separately
+ * so the hot path doesn't even branch on `enabled` per call.
+ */
+export declare const NOOP_CODEC: CompressionCodec;

package/dist/core/compression.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Optional value compression for entity payloads.
+ *
+ * Why this exists:
+ *   - Entity payloads (post + nested relationships) can be 5-50 KB.
+ *   - At 50k concurrent users this is meaningful network bandwidth and
+ *     Redis memory pressure.
+ *   - Compression cuts typical JSON to ~30% of original size; even with
+ *     base64 envelope overhead the net saving is 50-60%.
+ *
+ * Why ONLY entity values are compressed (not list values):
+ *   - List values are JSON arrays of ids that the atomic Lua scripts
+ *     parse server-side via `cjson.decode`. Compressed payloads would
+ *     not parse and would break list-add / list-remove atomic ops.
+ *   - Entity values are always parsed in Node, never inside Redis, so
+ *     they're safe to ship in a compressed envelope.
+ *
+ * Backward compatibility:
+ *   - Plain JSON (starts with `{` or `[`) is returned untouched on
+ *     decode, so existing keys keep working when compression is enabled.
+ *   - Compressed values carry a 4-character magic prefix `\x00z1:` that
+ *     cannot occur at the start of valid JSON.
+ *   - Writers can disable compression at any time and readers will
+ *     transparently handle a mix of compressed and uncompressed values.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOOP_CODEC = exports.CompressionCodec = void 0;
+const zlib = __importStar(require("zlib"));
+const MAGIC = '\x00z1:';
+const MAGIC_LENGTH = MAGIC.length;
+/**
+ * Wraps the (de)serialisation of an entity JSON string. A no-op codec
+ * (`enabled = false`) returns inputs unchanged on both encode and decode,
+ * with a fast-path so the engine pays virtually zero cost when the
+ * feature is off.
+ */
+class CompressionCodec {
+    constructor(enabled, threshold) {
+        this.enabled = enabled;
+        // Threshold is in bytes; clamp to a sensible minimum to avoid
+        // compressing tiny values where the envelope overhead outweighs the
+        // saving.
+        this.threshold = Math.max(64, threshold || 1024);
+    }
+    /**
+     * Encode a value for storage. When compression is disabled or the
+     * payload is below the threshold, returns the input unchanged so we
+     * don't add overhead to small entities.
+     */
+    encode(value) {
+        if (!this.enabled)
+            return value;
+        if (Buffer.byteLength(value, 'utf8') < this.threshold)
+            return value;
+        const compressed = zlib.deflateRawSync(Buffer.from(value, 'utf8'));
+        return MAGIC + compressed.toString('base64');
+    }
+    /**
+     * Decode a value read from Redis. Detects the magic prefix to decide
+     * whether to inflate. Untagged values pass through, which is what
+     * makes this safe to deploy on top of an existing cache: any data
+     * written before compression was enabled keeps reading correctly.
+     *
+     * Throws if a tagged value is malformed; that's a hard error worth
+     * surfacing because it indicates corruption rather than a stale
+     * format.
+     */
+    decode(value) {
+        if (!value.startsWith(MAGIC))
+            return value;
+        const b64 = value.slice(MAGIC_LENGTH);
+        const buf = Buffer.from(b64, 'base64');
+        return zlib.inflateRawSync(buf).toString('utf8');
+    }
+}
+exports.CompressionCodec = CompressionCodec;
+/**
+ * Fast-path codec used when compression is disabled. Defined separately
+ * so the hot path doesn't even branch on `enabled` per call.
+ */
+exports.NOOP_CODEC = new CompressionCodec(false, 0);

package/dist/core/hydration-engine.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Hydration Engine - Reconstructs full objects from normalized storage
+ */
+import { SchemaManager } from './schema-manager';
+import { RedisConnectionManager } from './redis-connection-manager';
+import { CompressionCodec } from './compression';
+import { Serializer } from './serializer';
+import { HydrationOptions } from '../types';
+export declare class HydrationEngine {
+    private schemaManager;
+    private connectionManager;
+    private defaultMaxDepth;
+    private defaultMaxMemory;
+    private codec;
+    private serializer;
+    constructor(schemaManager: SchemaManager, connectionManager: RedisConnectionManager, defaultMaxDepth?: number, defaultMaxMemory?: number, // 100MB
+    codec?: CompressionCodec, serializer?: Serializer);
+    /**
+     * Hydrate a single entity with all its relationships
+     */
+    hydrateEntity(entityType: string, id: string | number, options?: HydrationOptions): Promise<any>;
+    /**
+     * Hydrate multiple entities in batch
+     */
+    hydrateEntities(entityType: string, ids: (string | number)[], options?: HydrationOptions): Promise<any[]>;
+    /**
+     * Create hydration context with limits and tracking
+     */
+    private createHydrationContext;
+    /**
+     * Recursively hydrate entity and its relationships
+     */
+    private hydrateRecursive;
+    /**
+     * Hydrate all relationships for an entity
+     */
+    private hydrateRelationships;
+    /**
+     * Hydrate a single relationship
+     */
+    private hydrateRelation;
+    /**
+     * Batch hydrate multiple entities efficiently
+     */
+    private batchHydrateEntities;
+    /**
+     * Get a single entity from Redis. Hits/misses are tracked by the
+     * connection-manager wrapper so we don't double-count here. The codec
+     * decodes the storage envelope (decompressing if needed) before JSON
+     * parsing; untagged values pass through, preserving compatibility
+     * with caches that pre-date compression.
+     */
+    private getEntityFromRedis;
+    /**
+     * Batch fetch multiple entities via MGET. Each value is independently
+     * decoded (codec) and JSON-parsed. Per-element parse failures surface
+     * as null so the rest of the batch is still usable.
+     */
+    private batchGetEntitiesFromRedis;
+    /**
+     * Check if relations should be skipped based on context
+     */
+    private shouldSkipRelations;
+    /**
+     * Generate unique request ID for tracking
+     */
+    private generateRequestId;
+}

package/dist/core/hydration-engine.js

@@ -0,0 +1,288 @@
+"use strict";
+/**
+ * Hydration Engine - Reconstructs full objects from normalized storage
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HydrationEngine = void 0;
+const compression_1 = require("./compression");
+const serializer_1 = require("./serializer");
+const types_1 = require("../types");
+const types_2 = require("../types");
+class HydrationEngine {
+    constructor(schemaManager, connectionManager, defaultMaxDepth = 5, defaultMaxMemory = 100 * 1024 * 1024, // 100MB
+    codec = compression_1.NOOP_CODEC, 
+    // Pluggable (de)serializer. Defaults to the engine's lossless
+    // tagged JSON serializer so reads recover `Date`/`BigInt`/`Map`/
+    // `Set`/`RegExp`/`Buffer`/`NaN`/`±Infinity` as their original JS
+    // types instead of degrading them to strings, nulls, or `{}`.
+    serializer = serializer_1.TAGGED_SERIALIZER) {
+        this.schemaManager = schemaManager;
+        this.connectionManager = connectionManager;
+        this.defaultMaxDepth = defaultMaxDepth;
+        this.defaultMaxMemory = defaultMaxMemory;
+        this.codec = codec;
+        this.serializer = serializer;
+    }
+    /**
+     * Hydrate a single entity with all its relationships
+     */
+    async hydrateEntity(entityType, id, options = {}) {
+        const context = this.createHydrationContext(options);
+        try {
+            const result = await this.hydrateRecursive(entityType, id, context);
+            return result ? (0, types_1.stripInternalFields)(result) : null;
+        }
+        catch (error) {
+            if (error instanceof types_2.HydrationDepthExceededError ||
+                error instanceof types_2.MemoryLimitError) {
+                // Return partial result with warning for limit exceeded errors
+                console.warn(`Hydration limit exceeded for ${entityType}:${id}`, error.message);
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Hydrate multiple entities in batch
+     */
+    async hydrateEntities(entityType, ids, options = {}) {
+        if (ids.length === 0) {
+            return [];
+        }
+        // Create separate context for each entity to prevent cross-contamination
+        const results = await Promise.all(ids.map((id) => this.hydrateEntity(entityType, id, options)));
+        // Filter out null results (deleted entities)
+        return results.filter((result) => result !== null);
+    }
+    /**
+     * Create hydration context with limits and tracking
+     */
+    createHydrationContext(options) {
+        return {
+            visitedEntities: new Set(),
+            currentDepth: 0,
+            maxDepth: options.maxDepth || this.defaultMaxDepth,
+            memoryUsage: 0,
+            maxMemory: options.memoryLimit || this.defaultMaxMemory,
+            requestId: this.generateRequestId(),
+            selectiveFields: options.selectiveFields,
+            excludeRelations: options.excludeRelations,
+        };
+    }
+    /**
+     * Recursively hydrate entity and its relationships
+     */
+    async hydrateRecursive(entityType, id, context) {
+        // Check depth limit
+        if (context.currentDepth >= context.maxDepth) {
+            throw new types_2.HydrationDepthExceededError(context.currentDepth, context.maxDepth, context.requestId);
+        }
+        // Check memory limit (rough estimation)
+        if (context.memoryUsage > context.maxMemory) {
+            throw new types_2.MemoryLimitError(Math.round(context.memoryUsage / (1024 * 1024)), Math.round(context.maxMemory / (1024 * 1024)), context.requestId);
+        }
+        const schema = this.schemaManager.getEntitySchema(entityType);
+        const entityKey = this.schemaManager.generateEntityKey(entityType, id);
+        // Prevent circular references. Instead of silently dropping the related
+        // entity (which corrupts the shape consumers expect) we emit a stub
+        // that contains the id and a `$ref` marker so consumers can detect a
+        // cycle and break recursion themselves. `$ref` is intentionally
+        // un-prefixed so it survives `stripInternalFields`.
+        const visitKey = `${entityType}:${id}`;
+        if (context.visitedEntities.has(visitKey)) {
+            return { [schema.id]: id, $ref: `${entityType}:${id}` };
+        }
+        context.visitedEntities.add(visitKey);
+        try {
+            // Get entity from Redis
+            const normalizedEntity = await this.getEntityFromRedis(entityKey);
+            if (!normalizedEntity) {
+                return null; // Entity not found
+            }
+            // Update memory usage estimation. We use the configured
+            // serializer here too because plain `JSON.stringify` would throw
+            // on values that the serializer specifically handles (BigInt) or
+            // silently understate the size (Buffer, Map). Wrapped in
+            // try/catch so a serialization quirk on a single entity can
+            // never abort hydration of the whole graph — the size estimate
+            // is best-effort.
+            try {
+                context.memoryUsage +=
+                    this.serializer.stringify(normalizedEntity).length;
+            }
+            catch {
+                // Fall back to a conservative constant if even the serializer
+                // can't stringify the value. This is intentionally generous so
+                // we still apply some memory pressure rather than treating the
+                // entity as zero bytes.
+                context.memoryUsage += 4096;
+            }
+            // Build the hydrated entity. When `selectiveFields` is supplied the
+            // output is restricted to only those keys plus the ID field; we still
+            // keep the internal `__rse_*` markers in scope so relationship
+            // hydration can resolve referenced ids, then `stripInternalFields`
+            // removes them at the public boundary.
+            let hydratedEntity;
+            if (context.selectiveFields && context.selectiveFields.length > 0) {
+                const allowed = new Set(context.selectiveFields);
+                allowed.add(schema.id);
+                const filtered = {};
+                for (const [k, v] of Object.entries(normalizedEntity)) {
+                    if (allowed.has(k) || k.startsWith('__rse_')) {
+                        filtered[k] = v;
+                    }
+                }
+                hydratedEntity = filtered;
+            }
+            else {
+                hydratedEntity = { ...normalizedEntity };
+            }
+            // Hydrate relationships
+            if (schema.relations && !this.shouldSkipRelations(context)) {
+                context.currentDepth++;
+                await this.hydrateRelationships(schema, normalizedEntity, hydratedEntity, context);
+                context.currentDepth--;
+            }
+            return hydratedEntity;
+        }
+        finally {
+            // Remove from visited set to allow re-visiting in different branches
+            context.visitedEntities.delete(visitKey);
+        }
+    }
+    /**
+     * Hydrate all relationships for an entity
+     */
+    async hydrateRelationships(schema, normalizedEntity, hydratedEntity, context) {
+        if (!schema.relations)
+            return;
+        const relationPromises = [];
+        for (const [relationName, relationDef] of Object.entries(schema.relations)) {
+            // Skip excluded relations
+            if (context.excludeRelations?.includes(relationName)) {
+                continue;
+            }
+            const promise = this.hydrateRelation(relationName, relationDef, normalizedEntity, hydratedEntity, context);
+            relationPromises.push(promise);
+        }
+        // Execute all relationship hydrations in parallel
+        await Promise.all(relationPromises);
+    }
+    /**
+     * Hydrate a single relationship
+     */
+    async hydrateRelation(relationName, relationDef, normalizedEntity, hydratedEntity, context) {
+        const relationIdField = (0, types_1.generateRelationIdField)(relationName, relationDef.kind);
+        const relationIds = normalizedEntity[relationIdField];
+        if (!relationIds) {
+            // No relation data, set appropriate default
+            hydratedEntity[relationName] = relationDef.kind === 'one' ? null : [];
+            return;
+        }
+        try {
+            if (relationDef.kind === 'one') {
+                // One-to-one relationship
+                const relatedEntity = await this.hydrateRecursive(relationDef.type, relationIds, { ...context });
+                hydratedEntity[relationName] = relatedEntity;
+            }
+            else {
+                // One-to-many relationship
+                if (Array.isArray(relationIds)) {
+                    const relatedEntities = await this.batchHydrateEntities(relationDef.type, relationIds, context);
+                    hydratedEntity[relationName] = relatedEntities;
+                }
+                else {
+                    hydratedEntity[relationName] = [];
+                }
+            }
+        }
+        catch (error) {
+            // Handle relation hydration errors gracefully
+            console.warn(`Failed to hydrate relation '${relationName}':`, error);
+            hydratedEntity[relationName] = relationDef.kind === 'one' ? null : [];
+        }
+    }
+    /**
+     * Batch hydrate multiple entities efficiently
+     */
+    async batchHydrateEntities(entityType, ids, context) {
+        if (ids.length === 0) {
+            return [];
+        }
+        // First, batch fetch all entities from Redis
+        const entityKeys = ids.map((id) => this.schemaManager.generateEntityKey(entityType, id));
+        const normalizedEntities = await this.batchGetEntitiesFromRedis(entityKeys);
+        // Then hydrate each entity
+        const hydrationPromises = ids.map(async (id, index) => {
+            const normalizedEntity = normalizedEntities[index];
+            if (!normalizedEntity) {
+                return null; // Entity not found
+            }
+            // Create a copy of context for each entity
+            const entityContext = {
+                ...context,
+                visitedEntities: new Set(context.visitedEntities),
+            };
+            return this.hydrateRecursive(entityType, id, entityContext);
+        });
+        const results = await Promise.all(hydrationPromises);
+        // Filter out null results (deleted entities)
+        return results.filter((result) => result !== null);
+    }
+    /**
+     * Get a single entity from Redis. Hits/misses are tracked by the
+     * connection-manager wrapper so we don't double-count here. The codec
+     * decodes the storage envelope (decompressing if needed) before JSON
+     * parsing; untagged values pass through, preserving compatibility
+     * with caches that pre-date compression.
+     */
+    async getEntityFromRedis(key) {
+        try {
+            const value = await this.connectionManager.get(key);
+            if (!value)
+                return null;
+            return this.serializer.parse(this.codec.decode(value));
+        }
+        catch (error) {
+            throw new types_2.RedisConnectionError(`Failed to get entity from Redis: ${key}`, error);
+        }
+    }
+    /**
+     * Batch fetch multiple entities via MGET. Each value is independently
+     * decoded (codec) and JSON-parsed. Per-element parse failures surface
+     * as null so the rest of the batch is still usable.
+     */
+    async batchGetEntitiesFromRedis(keys) {
+        if (keys.length === 0)
+            return [];
+        try {
+            const values = await this.connectionManager.mget(keys);
+            return values.map((value) => {
+                if (!value)
+                    return null;
+                try {
+                    return this.serializer.parse(this.codec.decode(value));
+                }
+                catch {
+                    return null;
+                }
+            });
+        }
+        catch (error) {
+            throw new types_2.RedisConnectionError('Failed to batch get entities from Redis', error);
+        }
+    }
+    /**
+     * Check if relations should be skipped based on context
+     */
+    shouldSkipRelations(context) {
+        return context.excludeRelations?.includes('*') || false;
+    }
+    /**
+     * Generate unique request ID for tracking
+     */
+    generateRequestId() {
+        return `req_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+    }
+}
+exports.HydrationEngine = HydrationEngine;

package/dist/core/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Barrel export for public core components.
+ *
+ * NOTE: `lua-scripts` is intentionally excluded — it contains raw Lua
+ * source strings that are implementation details of the connection
+ * manager and must not become part of the public API.
+ */
+export * from './compression';
+export * from './hydration-engine';
+export * from './normalization-engine';
+export * from './redis-connection-manager';
+export * from './schema-manager';
+export * from './serializer';

package/dist/core/index.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Barrel export for public core components.
+ *
+ * NOTE: `lua-scripts` is intentionally excluded — it contains raw Lua
+ * source strings that are implementation details of the connection
+ * manager and must not become part of the public API.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./compression"), exports);
+__exportStar(require("./hydration-engine"), exports);
+__exportStar(require("./normalization-engine"), exports);
+__exportStar(require("./redis-connection-manager"), exports);
+__exportStar(require("./schema-manager"), exports);
+__exportStar(require("./serializer"), exports);