redis-graph-cache 1.0.0

package/dist/core/serializer.js

@@ -0,0 +1,187 @@
+"use strict";
+/**
+ * Serializer - Pluggable (de)serialization for entity payloads.
+ *
+ * The default serializer (`TAGGED_SERIALIZER`) is a lossless wrapper
+ * around `JSON.stringify` / `JSON.parse` that preserves JS types JSON
+ * cannot represent natively. It uses a tag-based envelope only for
+ * non-JSON-native values; everything else round-trips identically to
+ * plain `JSON.stringify` so the on-wire format is unchanged for
+ * ordinary data (strings, numbers, booleans, plain objects, arrays,
+ * nulls).
+ *
+ * Why the engine needs this:
+ *   - `Date` becomes an ISO string via `Date.prototype.toJSON` and
+ *     parses back as a string, breaking `post.createdAt.getTime()`.
+ *   - `BigInt` throws `TypeError` from `JSON.stringify`.
+ *   - `Map`, `Set`, `RegExp`, `Buffer` serialize to `{}`, losing all
+ *     contents.
+ *   - `NaN`, `Infinity`, `-Infinity` become `null`, silently corrupting
+ *     numeric stats fields.
+ *
+ * Out of scope (intentionally NOT tagged):
+ *   - `undefined`. The engine's merge semantics treat
+ *     "field is undefined" identically to "field is omitted" so that
+ *     partial updates don't accidentally clobber existing values.
+ *     See `NULL_UNDEFINED_HANDLING.md`. Tagging undefined would
+ *     silently change that contract.
+ *
+ * Backward compatibility:
+ *   - Reads of plain JSON written by older versions (or by any process
+ *     without this engine) work unchanged. The reviver only transforms
+ *     objects that carry the internal tag key.
+ *   - Writes that contain only JSON-native values produce byte-for-byte
+ *     identical output to the previous `JSON.stringify` path.
+ *
+ * Pluggability:
+ *   - Consumers can opt out by passing `cache.serializer = JSON_SERIALIZER`
+ *     (raw, no tagging — original behaviour).
+ *   - Consumers can plug in a third-party codec like `superjson` or
+ *     `devalue` by passing any object that implements `Serializer`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JSON_SERIALIZER = exports.TAGGED_SERIALIZER = void 0;
+/**
+ * Internal tag key used by the default tagged serializer. It is
+ * deliberately under the engine's reserved `__rse_` prefix so it
+ * cannot collide with user fields (schema validation rejects field
+ * names starting with `__rse_`).
+ */
+const TAG = '__rse_t';
+/**
+ * Replacer used by `TAGGED_SERIALIZER.stringify`. Receives the
+ * pre-`toJSON` value via `this[key]` so we can detect `Date`,
+ * `Buffer`, etc. before their built-in `toJSON` clobbers them.
+ *
+ * Any value not matched here is returned unchanged, so plain JSON
+ * data round-trips with zero envelope overhead.
+ */
+function tagReplacer(key, value) {
+    // `this` is the holder object; `value` is the post-`toJSON` value.
+    // We need the raw value to detect Date/Buffer/etc. since their
+    // `toJSON` runs before the replacer.
+    const original = this[key];
+    if (original instanceof Date) {
+        // `getTime()` preserves invalid dates (NaN) which `toISOString`
+        // would throw on. Storing the numeric timestamp is also slightly
+        // smaller and unambiguous across timezones.
+        const t = original.getTime();
+        return { [TAG]: 'Date', v: Number.isNaN(t) ? null : t };
+    }
+    if (typeof original === 'bigint') {
+        return { [TAG]: 'BigInt', v: original.toString() };
+    }
+    if (original instanceof Map) {
+        // Entries are arrays of [key, value]; both will recurse through
+        // the replacer so nested Dates/BigInts inside a Map work too.
+        return { [TAG]: 'Map', v: Array.from(original.entries()) };
+    }
+    if (original instanceof Set) {
+        return { [TAG]: 'Set', v: Array.from(original.values()) };
+    }
+    if (original instanceof RegExp) {
+        return { [TAG]: 'RegExp', src: original.source, flags: original.flags };
+    }
+    // Buffer check is guarded so the serializer also works in non-Node
+    // environments (Edge, browsers) where `Buffer` is undefined.
+    if (typeof Buffer !== 'undefined' &&
+        typeof Buffer.isBuffer === 'function' &&
+        Buffer.isBuffer(original)) {
+        return { [TAG]: 'Buffer', v: original.toString('base64') };
+    }
+    if (typeof original === 'number' && !Number.isFinite(original)) {
+        if (Number.isNaN(original))
+            return { [TAG]: 'Number', v: 'NaN' };
+        return {
+            [TAG]: 'Number',
+            v: original > 0 ? 'Infinity' : '-Infinity',
+        };
+    }
+    return value;
+}
+/**
+ * Reviver used by `TAGGED_SERIALIZER.parse`. JSON.parse calls the
+ * reviver bottom-up (children first), so by the time we see a tagged
+ * envelope its inner `v` has already been revived. That means
+ * `Map<Date, BigInt>` round-trips correctly: the inner Dates and
+ * BigInts are reconstructed before the Map wraps them.
+ *
+ * Untagged objects (plain JSON written by any other producer) are
+ * returned unchanged, which is what makes this safe to deploy on top
+ * of an existing cache.
+ */
+function tagReviver(_key, value) {
+    if (value === null ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        !(TAG in value)) {
+        return value;
+    }
+    switch (value[TAG]) {
+        case 'Date':
+            // `null` in `v` means we serialized an Invalid Date; reconstruct
+            // it so identity round-trips even for that weird case.
+            return value.v === null ? new Date(NaN) : new Date(value.v);
+        case 'BigInt':
+            return BigInt(value.v);
+        case 'Map':
+            return new Map(value.v);
+        case 'Set':
+            return new Set(value.v);
+        case 'RegExp':
+            return new RegExp(value.src, value.flags);
+        case 'Buffer':
+            // Guarded for non-Node environments. If Buffer is unavailable
+            // we return the raw envelope so the consumer at least sees the
+            // base64 payload rather than getting `undefined`.
+            if (typeof Buffer !== 'undefined') {
+                return Buffer.from(value.v, 'base64');
+            }
+            return value;
+        case 'Number':
+            if (value.v === 'NaN')
+                return NaN;
+            if (value.v === 'Infinity')
+                return Infinity;
+            if (value.v === '-Infinity')
+                return -Infinity;
+            return Number(value.v);
+        default:
+            // Unknown tag — return the envelope as-is. This is forward
+            // compatible: a future engine version may add new tags and
+            // older readers will simply pass them through instead of
+            // crashing.
+            return value;
+    }
+}
+/**
+ * Default serializer. Lossless for `Date`, `BigInt`, `Map`, `Set`,
+ * `RegExp`, `Buffer`, `NaN`, `+Infinity`, `-Infinity`. Identical to
+ * plain JSON for all other values.
+ */
+exports.TAGGED_SERIALIZER = {
+    stringify(value) {
+        return JSON.stringify(value, tagReplacer);
+    },
+    parse(value) {
+        return JSON.parse(value, tagReviver);
+    },
+};
+/**
+ * Plain JSON serializer. No tagging, no reviver. Use this when you
+ * know your data is JSON-native and want zero serialization overhead,
+ * or when interoperating with non-engine readers that expect raw JSON.
+ *
+ * Trade-off: `Date` survives as ISO string only, `BigInt` will throw,
+ * `Map`/`Set`/`RegExp`/`Buffer` lose all data, `NaN`/`Infinity` become
+ * `null`. This is the historical engine behaviour; kept available for
+ * opt-out.
+ */
+exports.JSON_SERIALIZER = {
+    stringify(value) {
+        return JSON.stringify(value);
+    },
+    parse(value) {
+        return JSON.parse(value);
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * redis-graph-cache
+ *
+ * A TypeScript-first Redis data layer with schema-driven normalization,
+ * relationship management, and graph-based hydration for high-performance
+ * Node.js applications handling millions of entities with complex
+ * relationships.
+ */
+export { RedisGraphCache } from './redis-graph-cache';
+export * from './core';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * redis-graph-cache
+ *
+ * A TypeScript-first Redis data layer with schema-driven normalization,
+ * relationship management, and graph-based hydration for high-performance
+ * Node.js applications handling millions of entities with complex
+ * relationships.
+ */
+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 });
+exports.RedisGraphCache = void 0;
+// Main engine class (the primary export — what 95% of consumers need)
+var redis_graph_cache_1 = require("./redis-graph-cache");
+Object.defineProperty(exports, "RedisGraphCache", { enumerable: true, get: function () { return redis_graph_cache_1.RedisGraphCache; } });
+// Core components, utilities, and serializers
+__exportStar(require("./core"), exports);
+// All public types (schemas, configs, operations, errors, utilities)
+__exportStar(require("./types"), exports);

package/dist/redis-graph-cache.d.ts

@@ -0,0 +1,302 @@
+/**
+ * Redis Schema Engine - Main class providing the public API
+ */
+import { Schema, PartialRedisSchemaEngineConfig, WriteResult, ListWriteResult, CacheMetrics, HealthStatus, HydrationOptions } from './types';
+export declare class RedisGraphCache<TSchema extends Schema> {
+    private schemaManager;
+    private connectionManager;
+    private normalizationEngine;
+    private hydrationEngine;
+    private config;
+    private activeOperations;
+    constructor(schema: TSchema, config?: PartialRedisSchemaEngineConfig);
+    /**
+     * Wrap a public operation with active-counter bookkeeping. Lets the
+     * health endpoint report a real (not stubbed) `activeOperations` value.
+     */
+    private tracked;
+    /**
+     * Resolve the TTL for a given normalized entity key. The key format is
+     * always `entityType:id` so the prefix tells us which schema to consult.
+     */
+    private resolveEntityKeyTTL;
+    /**
+     * Build a TTL resolver for a single write call that, when `cascadeTTL`
+     * is true, applies a floor: every entity written in this call uses at
+     * least `parentTtl` even if its own schema TTL is shorter. This is the
+     * fix for the "parent post (1h) embeds short-TTL category (1m); after
+     * 1m the post hydrates without its category" coherence bug.
+     *
+     * Special cases:
+     *   - parentTtl = 0 (no expiry on parent): children also get 0,
+     *     guaranteeing they outlive a never-expiring parent.
+     *   - cascadeTTL = false (default): returns the unmodified resolver,
+     *     so existing behaviour is bit-for-bit preserved.
+     *   - parentTtl negative or NaN: ignored, falls back to per-key TTL.
+     */
+    private buildTTLResolver;
+    /**
+     * Runtime helper for the dual positional/object-style public API.
+     * `typeof x === 'object' && x !== null` distinguishes the object
+     * form from the positional-string-first form, since `entityType`
+     * and `listType` are always strings.
+     */
+    private isArgsObject;
+    /**
+     * Write an entity with nested relationships to Redis.
+     *
+     * Two equivalent call styles are supported:
+     *
+     * ```ts
+     * // Object form (recommended for new code)
+     * await engine.writeEntity({ entityType: 'post', data, ttl, cascadeTTL });
+     *
+     * // Positional form (preserved for existing callers)
+     * await engine.writeEntity('post', data, { ttl, cascadeTTL });
+     * ```
+     *
+     * When `ttl` is provided it overrides the entity's schema TTL for
+     * THIS WRITE ONLY, pinned to the root entity's key. Embedded
+     * relations still use their own schema TTL unless `cascadeTTL: true`
+     * is set — in which case the override also becomes the cascade
+     * floor for every child written by this call.
+     */
+    writeEntity<T>(args: {
+        entityType: keyof TSchema;
+        data: T;
+        ttl?: number;
+        cascadeTTL?: boolean;
+        forceTTL?: boolean;
+    }): Promise<WriteResult>;
+    writeEntity<T>(entityType: keyof TSchema, data: T, options?: {
+        ttl?: number;
+        cascadeTTL?: boolean;
+        forceTTL?: boolean;
+    }): Promise<WriteResult>;
+    /**
+     * Read and hydrate an entity with all its relationships
+     */
+    readEntity(entityType: keyof TSchema, id: string | number, options?: HydrationOptions): Promise<any>;
+    /**
+     * Delete an entity from Redis
+     */
+    deleteEntity(entityType: keyof TSchema, id: string | number): Promise<boolean>;
+    /**
+     * Update an entity ONLY if it already exists in cache
+     * This is useful for cache invalidation scenarios where you don't want to
+     * create cache entries for data that hasn't been accessed yet
+     *
+     * @returns WriteResult if entity exists and was updated, null if entity doesn't exist
+     */
+    updateEntityIfExists(args: {
+        entityType: keyof TSchema;
+        data: any;
+        ttl?: number;
+        cascadeTTL?: boolean;
+        forceTTL?: boolean;
+    }): Promise<WriteResult | null>;
+    updateEntityIfExists(entityType: keyof TSchema, data: any, options?: {
+        ttl?: number;
+        cascadeTTL?: boolean;
+        forceTTL?: boolean;
+    }): Promise<WriteResult | null>;
+    /**
+     * Write a list of entities to Redis
+     */
+    writeList(args: {
+        listType: keyof TSchema;
+        params: any;
+        items: any[];
+        ttl?: number;
+        cascadeTTL?: boolean;
+        forceTTL?: boolean;
+    }): Promise<ListWriteResult>;
+    writeList(listType: keyof TSchema, params: any, items: any[], options?: {
+        ttl?: number;
+        cascadeTTL?: boolean;
+        forceTTL?: boolean;
+    }): Promise<ListWriteResult>;
+    /**
+     * Read and hydrate a list of entities
+     */
+    readList(listType: keyof TSchema, params: any, options?: HydrationOptions): Promise<any[]>;
+    /**
+     * Delete a list from Redis
+     */
+    deleteList(listType: keyof TSchema, params: any): Promise<boolean>;
+    /**
+     * Add an item to a list (with entity data)
+     * This method writes the entity to cache and adds it to the list
+     */
+    addListItem(args: {
+        listType: keyof TSchema;
+        params: any;
+        entityData: any;
+        ttl?: number;
+        cascadeTTL?: boolean;
+        forceTTL?: boolean;
+    }): Promise<boolean>;
+    addListItem(listType: keyof TSchema, params: any, entityData: any, options?: {
+        ttl?: number;
+        cascadeTTL?: boolean;
+        forceTTL?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Remove an item from a list (and optionally delete the entity)
+     */
+    removeListItem(listType: keyof TSchema, params: any, entityId: any, options?: {
+        deleteEntity?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Resolve the ZSET score for an entity from its schema's `scoreField`,
+     * with fallbacks: numeric strings, ISO timestamps via `Date.parse`, or
+     * insertion time when no `scoreField` is configured. Throws on values
+     * that cannot be coerced to a finite number, since silently scoring at
+     * 0 would scramble feed ordering.
+     */
+    private resolveIndexedListScore;
+    /**
+     * Bulk upsert an indexed list. Each item is normalized + written like a
+     * regular entity, then added to the ZSET with its computed score. This
+     * does NOT clear existing members; for full replace, call
+     * `deleteIndexedList` first.
+     */
+    writeIndexedList(args: {
+        listType: keyof TSchema;
+        params: any;
+        items: any[];
+        ttl?: number;
+        cascadeTTL?: boolean;
+        forceTTL?: boolean;
+    }): Promise<ListWriteResult>;
+    writeIndexedList(listType: keyof TSchema, params: any, items: any[], options?: {
+        ttl?: number;
+        cascadeTTL?: boolean;
+        forceTTL?: boolean;
+    }): Promise<ListWriteResult>;
+    /**
+     * Read a hydrated, paginated slice of an indexed list. Returns at most
+     * `limit` (default 50) hydrated entities. Combines ZSET pagination
+     * options (`offset`, `limit`, `reverse`, `minScore`, `maxScore`) with
+     * the standard hydration options (`maxDepth`, `selectiveFields`,
+     * `excludeRelations`).
+     */
+    readIndexedList(listType: keyof TSchema, params: any, opts?: HydrationOptions & {
+        offset?: number;
+        limit?: number;
+        reverse?: boolean;
+        minScore?: number;
+        maxScore?: number;
+    }): Promise<any[]>;
+    /**
+     * Atomic single-item upsert into an indexed list. Writes the entity in
+     * full normalized form first, then issues an atomic ZADD with the
+     * resolved score and any configured trim/membership tracking. Returns
+     * true if a new member was added, false if the score was updated on
+     * an already-present id (still considered success).
+     */
+    addIndexedListItem(args: {
+        listType: keyof TSchema;
+        params: any;
+        entityData: any;
+        ttl?: number;
+        cascadeTTL?: boolean;
+        forceTTL?: boolean;
+    }): Promise<boolean>;
+    addIndexedListItem(listType: keyof TSchema, params: any, entityData: any, options?: {
+        ttl?: number;
+        cascadeTTL?: boolean;
+        forceTTL?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Atomic remove of a member from a single indexed list. By default the
+     * entity itself remains intact (it may still be referenced by other
+     * lists). Pass `{ deleteEntity: true }` to also call `invalidateEntity`,
+     * which will cascade-remove the entity from every tracked list.
+     */
+    removeIndexedListItem(listType: keyof TSchema, params: any, entityId: any, options?: {
+        deleteEntity?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Number of members currently in the indexed list. O(1).
+     */
+    indexedListSize(listType: keyof TSchema, params: any): Promise<number>;
+    /**
+     * Delete the entire indexed list. Entities remain in cache. Membership
+     * back-indexes are NOT pruned here for performance reasons (they're
+     * harmless and self-clean as part of cascade invalidation or via TTL).
+     */
+    deleteIndexedList(listType: keyof TSchema, params: any): Promise<boolean>;
+    /**
+     * Invalidate an entity from cache. When the entity is referenced by any
+     * indexed list with `trackMembership: true`, this also atomically ZREMs
+     * the entity from every such list — so consumers don't have to chase
+     * down list keys themselves. For entities not tracked by any list, the
+     * behaviour is identical to a plain entity delete.
+     *
+     * Returns the number of tracked lists the entity was removed from (0
+     * when no membership back-index exists, which is the common case).
+     */
+    invalidateEntity(entityType: keyof TSchema, id: string | number): Promise<number>;
+    /**
+     * Clear every cache key owned by this engine. Destructive and
+     * irreversible.
+     *
+     * Behaviour depends on `redis.keyPrefix`:
+     *   - **Prefix set** (recommended): uses non-blocking `SCAN` +
+     *     `UNLINK` to delete only keys starting with the prefix. Safe to
+     *     run against a Redis instance shared with other applications or
+     *     environments — their keys are untouched.
+     *   - **Prefix empty** (default, backward-compatible): falls back to
+     *     `FLUSHDB`, wiping the entire selected database. Only use this
+     *     when the engine owns the whole DB.
+     *
+     * Two safeguards apply in both modes:
+     *   1. The caller MUST pass `{ confirm: 'YES_WIPE_ALL' }` explicitly.
+     *   2. When `safety.productionMode` is true the operation is blocked
+     *      unless `allowProduction: true` is also set.
+     *
+     * `safety.productionMode` defaults to `process.env.NODE_ENV ===
+     * 'production'` at construction time but is fully consumer-overridable
+     * via the engine config. The check below reads only the resolved
+     * config — no env access at call time.
+     */
+    clearAllCache(opts: {
+        confirm: 'YES_WIPE_ALL';
+        allowProduction?: boolean;
+    }): Promise<void>;
+    /**
+     * Real cache metrics. Hits/misses are counted at the connection-manager
+     * boundary on every GET/MGET; latency, totals, failures come from the
+     * same shared HealthMetrics tracker. `memoryUsage` reports the Node-side
+     * estimate and is 0 when no operation has run yet; Redis-side memory is
+     * exposed via `getHealthStatus()`.
+     */
+    getMetrics(): CacheMetrics;
+    /**
+     * Get health status of the engine and Redis connection
+     */
+    getHealthStatus(): Promise<HealthStatus>;
+    /**
+     * Enable or disable debug mode
+     */
+    enableDebugMode(enabled: boolean): void;
+    /**
+     * Gracefully disconnect and cleanup resources
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Initialize all engine components
+     */
+    private initializeComponents;
+    /**
+     * Merge user config with defaults
+     */
+    private mergeWithDefaults;
+    /**
+     * UUIDv4 collisions are practically impossible, unlike the previous
+     * Math.random()-based IDs which collided regularly under high concurrency.
+     */
+    private generateOperationId;
+    private generateRequestId;
+}