redis-graph-cache 1.0.0

package/dist/core/schema-manager.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Schema Manager - Validates and manages entity and list schemas
+ */
+import { Schema, EntitySchema, ListSchema, IndexedListSchema, RelationDefinition } from '../types';
+export declare class SchemaManager {
+    private schemas;
+    private entitySchemas;
+    private listSchemas;
+    private indexedListSchemas;
+    private validationCache;
+    private defaultTTL;
+    constructor(schema: Schema, defaultTTL?: number);
+    /**
+     * Resolve the TTL (seconds) to apply when writing an entity. Schema-level
+     * `ttl` wins; otherwise falls back to the engine-wide defaultTTL. Returns
+     * 0 when no TTL should be applied (key persists indefinitely).
+     */
+    resolveEntityTTL(entityType: string): number;
+    /**
+     * Resolve the TTL (seconds) for list keys. Schema-level `ttl` on the list
+     * wins; otherwise falls back to engine defaultTTL.
+     */
+    resolveListTTL(listType: string): number;
+    /**
+     * Resolve TTL for an indexed-list ZSET key.
+     */
+    resolveIndexedListTTL(listType: string): number;
+    /**
+     * Internal namespace prefix used for membership back-index keys. Kept
+     * isolated so user schemas cannot accidentally collide with it.
+     */
+    static readonly MEMBERSHIP_PREFIX = "__rse_membership";
+    /**
+     * Build the back-index key tracking which list keys currently contain a
+     * given entity. Used by indexed lists with `trackMembership: true` so
+     * cascade invalidation can find and remove the entity from every list.
+     */
+    generateMembershipKey(entityType: string, id: string | number): string;
+    /**
+     * Register and validate a complete schema
+     */
+    registerSchema(schema: Schema): void;
+    /**
+     * Get entity schema by name
+     */
+    getEntitySchema(entityType: string): EntitySchema;
+    /**
+     * Get list schema by name
+     */
+    getListSchema(listType: string): ListSchema;
+    /**
+     * Get indexed-list schema by name. Throws if not registered or not the
+     * indexed kind, so callers can rely on the returned schema's structure.
+     */
+    getIndexedListSchema(listType: string): IndexedListSchema;
+    hasIndexedListSchema(listType: string): boolean;
+    getIndexedListSchemaNames(): string[];
+    /**
+     * Generate Redis key for an indexed list, using its schema-supplied key
+     * function. Same pattern as `generateListKey` for plain lists.
+     */
+    generateIndexedListKey(listType: string, ...params: any[]): string;
+    /**
+     * Check if entity schema exists
+     */
+    hasEntitySchema(entityType: string): boolean;
+    /**
+     * Check if list schema exists
+     */
+    hasListSchema(listType: string): boolean;
+    /**
+     * Get all entity schema names
+     */
+    getEntitySchemaNames(): string[];
+    /**
+     * Get all list schema names
+     */
+    getListSchemaNames(): string[];
+    /**
+     * Validate complete schema for consistency and relationships
+     */
+    private validateCompleteSchema;
+    /**
+     * Validate individual entity schema
+     */
+    private validateEntitySchema;
+    /**
+     * Validate individual list schema
+     */
+    private validateListSchema;
+    /**
+     * Validate an indexed list schema. Mirrors validateListSchema and adds
+     * the ZSET-specific checks. The score field, when given, isn't bound to
+     * any field type because we only call `Number(...)` on it at insert time.
+     */
+    private validateIndexedListSchema;
+    /**
+     * Validate relationship definition
+     */
+    private validateRelationDefinition;
+    /**
+     * Detect circular dependencies in relationships
+     */
+    private detectCircularDependencies;
+    /**
+     * Generate Redis key for entity
+     */
+    generateEntityKey(entityType: string, id: string | number): string;
+    /**
+     * Generate Redis key for list
+     */
+    generateListKey(listType: string, ...params: any[]): string;
+    /**
+     * Get entity ID field name
+     */
+    getEntityIdField(entityType: string): string;
+    /**
+     * Get list ID field name
+     */
+    getListIdField(listType: string): string;
+    /**
+     * Check if field is defined in entity schema
+     */
+    hasEntityField(entityType: string, fieldName: string): boolean;
+    /**
+     * Check if relation is defined in entity schema
+     */
+    hasEntityRelation(entityType: string, relationName: string): boolean;
+    /**
+     * Get entity relation definition
+     */
+    getEntityRelation(entityType: string, relationName: string): RelationDefinition;
+}

package/dist/core/schema-manager.js

@@ -0,0 +1,432 @@
+"use strict";
+/**
+ * Schema Manager - Validates and manages entity and list schemas
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaManager = void 0;
+const types_1 = require("../types");
+class SchemaManager {
+    constructor(schema, defaultTTL = 0) {
+        this.schemas = new Map();
+        this.entitySchemas = new Map();
+        this.listSchemas = new Map();
+        this.indexedListSchemas = new Map();
+        this.validationCache = new Map();
+        this.defaultTTL = defaultTTL;
+        this.registerSchema(schema);
+    }
+    /**
+     * Resolve the TTL (seconds) to apply when writing an entity. Schema-level
+     * `ttl` wins; otherwise falls back to the engine-wide defaultTTL. Returns
+     * 0 when no TTL should be applied (key persists indefinitely).
+     */
+    resolveEntityTTL(entityType) {
+        const schema = this.entitySchemas.get(entityType);
+        if (schema?.ttl !== undefined)
+            return schema.ttl;
+        return this.defaultTTL;
+    }
+    /**
+     * Resolve the TTL (seconds) for list keys. Schema-level `ttl` on the list
+     * wins; otherwise falls back to engine defaultTTL.
+     */
+    resolveListTTL(listType) {
+        const schema = this.listSchemas.get(listType);
+        if (schema?.ttl !== undefined)
+            return schema.ttl;
+        return this.defaultTTL;
+    }
+    /**
+     * Resolve TTL for an indexed-list ZSET key.
+     */
+    resolveIndexedListTTL(listType) {
+        const schema = this.indexedListSchemas.get(listType);
+        if (schema?.ttl !== undefined)
+            return schema.ttl;
+        return this.defaultTTL;
+    }
+    /**
+     * Build the back-index key tracking which list keys currently contain a
+     * given entity. Used by indexed lists with `trackMembership: true` so
+     * cascade invalidation can find and remove the entity from every list.
+     */
+    generateMembershipKey(entityType, id) {
+        return `${SchemaManager.MEMBERSHIP_PREFIX}:${entityType}:${id}`;
+    }
+    /**
+     * Register and validate a complete schema
+     */
+    registerSchema(schema) {
+        // Clear existing schemas
+        this.schemas.clear();
+        this.entitySchemas.clear();
+        this.listSchemas.clear();
+        this.indexedListSchemas.clear();
+        this.validationCache.clear();
+        // First pass: register all schemas keyed by name and bucket by kind so
+        // later validation passes can reference siblings by name.
+        for (const [name, definition] of Object.entries(schema)) {
+            this.schemas.set(name, definition);
+            if (definition.type === 'entity') {
+                this.entitySchemas.set(name, definition);
+            }
+            else if (definition.type === 'list') {
+                this.listSchemas.set(name, definition);
+            }
+            else if (definition.type === 'indexedList') {
+                this.indexedListSchemas.set(name, definition);
+            }
+        }
+        // Second pass: Validate all schemas
+        const validationResult = this.validateCompleteSchema();
+        if (!validationResult.isValid) {
+            throw new types_1.SchemaValidationError(`Schema validation failed: ${validationResult.errors.join(', ')}`, {
+                errors: validationResult.errors,
+                warnings: validationResult.warnings,
+            });
+        }
+    }
+    /**
+     * Get entity schema by name
+     */
+    getEntitySchema(entityType) {
+        const schema = this.entitySchemas.get(entityType);
+        if (!schema) {
+            throw new types_1.InvalidOperationError('getEntitySchema', `Entity schema '${entityType}' not found`, { entityType, availableSchemas: Array.from(this.entitySchemas.keys()) });
+        }
+        return schema;
+    }
+    /**
+     * Get list schema by name
+     */
+    getListSchema(listType) {
+        const schema = this.listSchemas.get(listType);
+        if (!schema) {
+            throw new types_1.InvalidOperationError('getListSchema', `List schema '${listType}' not found`, { listType, availableSchemas: Array.from(this.listSchemas.keys()) });
+        }
+        return schema;
+    }
+    /**
+     * Get indexed-list schema by name. Throws if not registered or not the
+     * indexed kind, so callers can rely on the returned schema's structure.
+     */
+    getIndexedListSchema(listType) {
+        const schema = this.indexedListSchemas.get(listType);
+        if (!schema) {
+            throw new types_1.InvalidOperationError('getIndexedListSchema', `Indexed list schema '${listType}' not found`, {
+                listType,
+                availableSchemas: Array.from(this.indexedListSchemas.keys()),
+            });
+        }
+        return schema;
+    }
+    hasIndexedListSchema(listType) {
+        return this.indexedListSchemas.has(listType);
+    }
+    getIndexedListSchemaNames() {
+        return Array.from(this.indexedListSchemas.keys());
+    }
+    /**
+     * Generate Redis key for an indexed list, using its schema-supplied key
+     * function. Same pattern as `generateListKey` for plain lists.
+     */
+    generateIndexedListKey(listType, ...params) {
+        const schema = this.getIndexedListSchema(listType);
+        return schema.key(...params);
+    }
+    /**
+     * Check if entity schema exists
+     */
+    hasEntitySchema(entityType) {
+        return this.entitySchemas.has(entityType);
+    }
+    /**
+     * Check if list schema exists
+     */
+    hasListSchema(listType) {
+        return this.listSchemas.has(listType);
+    }
+    /**
+     * Get all entity schema names
+     */
+    getEntitySchemaNames() {
+        return Array.from(this.entitySchemas.keys());
+    }
+    /**
+     * Get all list schema names
+     */
+    getListSchemaNames() {
+        return Array.from(this.listSchemas.keys());
+    }
+    /**
+     * Validate complete schema for consistency and relationships
+     */
+    validateCompleteSchema() {
+        const errors = [];
+        const warnings = [];
+        // Validate each entity schema
+        for (const name of Array.from(this.entitySchemas.keys())) {
+            const schema = this.entitySchemas.get(name);
+            const result = this.validateEntitySchema(name, schema);
+            errors.push(...result.errors);
+            warnings.push(...result.warnings);
+        }
+        // Validate each list schema
+        for (const name of Array.from(this.listSchemas.keys())) {
+            const schema = this.listSchemas.get(name);
+            const result = this.validateListSchema(name, schema);
+            errors.push(...result.errors);
+            warnings.push(...result.warnings);
+        }
+        // Validate each indexed-list schema. Same baseline rules as list, plus
+        // ZSET-specific checks (scoreField name, maxSize positivity).
+        for (const name of Array.from(this.indexedListSchemas.keys())) {
+            const schema = this.indexedListSchemas.get(name);
+            const result = this.validateIndexedListSchema(name, schema);
+            errors.push(...result.errors);
+            warnings.push(...result.warnings);
+        }
+        // Check for circular dependencies
+        const circularDeps = this.detectCircularDependencies();
+        if (circularDeps.length > 0) {
+            warnings.push(`Circular dependencies detected: ${circularDeps.join(', ')}`);
+        }
+        return {
+            isValid: errors.length === 0,
+            errors,
+            warnings,
+        };
+    }
+    /**
+     * Validate individual entity schema
+     */
+    validateEntitySchema(name, schema) {
+        const errors = [];
+        const warnings = [];
+        // Validate required fields
+        if (!schema.id || typeof schema.id !== 'string') {
+            errors.push(`Entity '${name}': id field must be a non-empty string`);
+        }
+        if (!schema.key || typeof schema.key !== 'function') {
+            errors.push(`Entity '${name}': key must be a function`);
+        }
+        // Validate field definitions
+        if (schema.fields) {
+            for (const [fieldName, fieldDef] of Object.entries(schema.fields)) {
+                if (!fieldDef.type ||
+                    ![
+                        'string',
+                        'number',
+                        'boolean',
+                        'object',
+                        'array',
+                        // Extended types preserved losslessly by the default
+                        // tagged serializer. Listed here purely for schema
+                        // validation; the engine still does not coerce values
+                        // based on the declared type.
+                        'date',
+                        'bigint',
+                        'map',
+                        'set',
+                        'regexp',
+                        'buffer',
+                    ].includes(fieldDef.type)) {
+                    errors.push(`Entity '${name}', field '${fieldName}': invalid field type '${fieldDef.type}'`);
+                }
+                // Check for internal field prefix conflicts
+                if (fieldName.startsWith('__rse_')) {
+                    errors.push(`Entity '${name}', field '${fieldName}': field names cannot start with '__rse_' (reserved for internal use)`);
+                }
+            }
+        }
+        // Validate relationship definitions
+        if (schema.relations) {
+            for (const [relationName, relationDef] of Object.entries(schema.relations)) {
+                const relationErrors = this.validateRelationDefinition(name, relationName, relationDef);
+                errors.push(...relationErrors);
+                // Check for internal field prefix conflicts
+                if (relationName.startsWith('__rse_')) {
+                    errors.push(`Entity '${name}', relation '${relationName}': relation names cannot start with '__rse_' (reserved for internal use)`);
+                }
+            }
+        }
+        // Validate TTL
+        if (schema.ttl !== undefined &&
+            (typeof schema.ttl !== 'number' || schema.ttl < 0)) {
+            errors.push(`Entity '${name}': ttl must be a positive number`);
+        }
+        return { isValid: errors.length === 0, errors, warnings };
+    }
+    /**
+     * Validate individual list schema
+     */
+    validateListSchema(name, schema) {
+        const errors = [];
+        const warnings = [];
+        // Validate required fields
+        if (!schema.entityType || typeof schema.entityType !== 'string') {
+            errors.push(`List '${name}': entityType must be a non-empty string`);
+        }
+        else if (!this.hasEntitySchema(schema.entityType)) {
+            errors.push(`List '${name}': referenced entity type '${schema.entityType}' does not exist`);
+        }
+        if (!schema.key || typeof schema.key !== 'function') {
+            errors.push(`List '${name}': key must be a function`);
+        }
+        if (!schema.idField || typeof schema.idField !== 'string') {
+            errors.push(`List '${name}': idField must be a non-empty string`);
+        }
+        // Validate TTL
+        if (schema.ttl !== undefined &&
+            (typeof schema.ttl !== 'number' || schema.ttl < 0)) {
+            errors.push(`List '${name}': ttl must be a positive number`);
+        }
+        return { isValid: errors.length === 0, errors, warnings };
+    }
+    /**
+     * Validate an indexed list schema. Mirrors validateListSchema and adds
+     * the ZSET-specific checks. The score field, when given, isn't bound to
+     * any field type because we only call `Number(...)` on it at insert time.
+     */
+    validateIndexedListSchema(name, schema) {
+        const errors = [];
+        const warnings = [];
+        if (!schema.entityType || typeof schema.entityType !== 'string') {
+            errors.push(`Indexed list '${name}': entityType must be a non-empty string`);
+        }
+        else if (!this.hasEntitySchema(schema.entityType)) {
+            errors.push(`Indexed list '${name}': referenced entity type '${schema.entityType}' does not exist`);
+        }
+        if (!schema.key || typeof schema.key !== 'function') {
+            errors.push(`Indexed list '${name}': key must be a function`);
+        }
+        if (!schema.idField || typeof schema.idField !== 'string') {
+            errors.push(`Indexed list '${name}': idField must be a non-empty string`);
+        }
+        if (schema.scoreField !== undefined &&
+            (typeof schema.scoreField !== 'string' || schema.scoreField.length === 0)) {
+            errors.push(`Indexed list '${name}': scoreField must be a non-empty string when provided`);
+        }
+        if (schema.maxSize !== undefined &&
+            (!Number.isFinite(schema.maxSize) || schema.maxSize <= 0)) {
+            errors.push(`Indexed list '${name}': maxSize must be a positive number`);
+        }
+        if (schema.ttl !== undefined &&
+            (typeof schema.ttl !== 'number' || schema.ttl < 0)) {
+            errors.push(`Indexed list '${name}': ttl must be a positive number`);
+        }
+        return { isValid: errors.length === 0, errors, warnings };
+    }
+    /**
+     * Validate relationship definition
+     */
+    validateRelationDefinition(entityName, relationName, relation) {
+        const errors = [];
+        // Validate relation type exists
+        if (!relation.type || typeof relation.type !== 'string') {
+            errors.push(`Entity '${entityName}', relation '${relationName}': type must be a non-empty string`);
+        }
+        else if (!this.hasEntitySchema(relation.type)) {
+            errors.push(`Entity '${entityName}', relation '${relationName}': referenced entity type '${relation.type}' does not exist`);
+        }
+        // Validate relation kind
+        if (!relation.kind || !['one', 'many'].includes(relation.kind)) {
+            errors.push(`Entity '${entityName}', relation '${relationName}': kind must be 'one' or 'many'`);
+        }
+        return errors;
+    }
+    /**
+     * Detect circular dependencies in relationships
+     */
+    detectCircularDependencies() {
+        const visited = new Set();
+        const recursionStack = new Set();
+        const cycles = [];
+        const dfs = (entityType, path) => {
+            if (recursionStack.has(entityType)) {
+                const cycleStart = path.indexOf(entityType);
+                const cycle = path.slice(cycleStart).concat(entityType);
+                cycles.push(cycle.join(' -> '));
+                return;
+            }
+            if (visited.has(entityType)) {
+                return;
+            }
+            visited.add(entityType);
+            recursionStack.add(entityType);
+            const schema = this.entitySchemas.get(entityType);
+            if (schema?.relations) {
+                for (const relation of Object.values(schema.relations)) {
+                    if (this.hasEntitySchema(relation.type)) {
+                        dfs(relation.type, [...path, entityType]);
+                    }
+                }
+            }
+            recursionStack.delete(entityType);
+        };
+        for (const entityType of Array.from(this.entitySchemas.keys())) {
+            if (!visited.has(entityType)) {
+                dfs(entityType, []);
+            }
+        }
+        return cycles;
+    }
+    /**
+     * Generate Redis key for entity
+     */
+    generateEntityKey(entityType, id) {
+        const schema = this.getEntitySchema(entityType);
+        return schema.key(id);
+    }
+    /**
+     * Generate Redis key for list
+     */
+    generateListKey(listType, ...params) {
+        const schema = this.getListSchema(listType);
+        return schema.key(...params);
+    }
+    /**
+     * Get entity ID field name
+     */
+    getEntityIdField(entityType) {
+        const schema = this.getEntitySchema(entityType);
+        return schema.id;
+    }
+    /**
+     * Get list ID field name
+     */
+    getListIdField(listType) {
+        const schema = this.getListSchema(listType);
+        return schema.idField;
+    }
+    /**
+     * Check if field is defined in entity schema
+     */
+    hasEntityField(entityType, fieldName) {
+        const schema = this.getEntitySchema(entityType);
+        return schema.fields ? fieldName in schema.fields : false;
+    }
+    /**
+     * Check if relation is defined in entity schema
+     */
+    hasEntityRelation(entityType, relationName) {
+        const schema = this.getEntitySchema(entityType);
+        return schema.relations ? relationName in schema.relations : false;
+    }
+    /**
+     * Get entity relation definition
+     */
+    getEntityRelation(entityType, relationName) {
+        const schema = this.getEntitySchema(entityType);
+        if (!schema.relations || !(relationName in schema.relations)) {
+            throw new types_1.InvalidOperationError('getEntityRelation', `Relation '${relationName}' not found in entity '${entityType}'`, { entityType, relationName });
+        }
+        return schema.relations[relationName];
+    }
+}
+exports.SchemaManager = SchemaManager;
+/**
+ * Internal namespace prefix used for membership back-index keys. Kept
+ * isolated so user schemas cannot accidentally collide with it.
+ */
+SchemaManager.MEMBERSHIP_PREFIX = '__rse_membership';

package/dist/core/serializer.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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`.
+ */
+/**
+ * Minimal contract every serializer must satisfy. The engine never
+ * inspects intermediate forms; it only ever calls `stringify` to
+ * produce the on-wire string and `parse` to recover the structured
+ * value.
+ */
+export interface Serializer {
+    /** Serialize a structured value to the string Redis stores. */
+    stringify(value: any): string;
+    /** Deserialize a string read from Redis back to a structured value. */
+    parse(value: string): any;
+}
+/**
+ * Default serializer. Lossless for `Date`, `BigInt`, `Map`, `Set`,
+ * `RegExp`, `Buffer`, `NaN`, `+Infinity`, `-Infinity`. Identical to
+ * plain JSON for all other values.
+ */
+export declare const TAGGED_SERIALIZER: Serializer;
+/**
+ * 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.
+ */
+export declare const JSON_SERIALIZER: Serializer;