redis-graph-cache 1.0.0

package/dist/types/config.types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Configuration types for Redis Schema Engine
+ */
+import type { RedisOptions } from 'ioredis';
+import type { Serializer } from '../core';
+export interface RedisClient {
+    get(key: string): Promise<string | null>;
+    mget(...keys: string[]): Promise<Array<string | null>>;
+    set(key: string, value: string): Promise<'OK'>;
+    del(...keys: string[]): Promise<number>;
+    ping(): Promise<'PONG'>;
+    quit(): Promise<'OK'>;
+    flushdb(): Promise<'OK'>;
+    pipeline(): any;
+    on(event: string, listener: (...args: any[]) => void): void;
+}
+export interface RedisConnectionPoolConfig {
+    min: number;
+    max: number;
+    acquireTimeoutMillis: number;
+    idleTimeoutMillis: number;
+}
+export interface RedisConfig extends RedisOptions {
+    keyPrefix?: string;
+    connectionPool?: RedisConnectionPoolConfig;
+    /**
+     * Number of ioredis clients to open against the same Redis instance.
+     * Each client is an independent TCP connection; commands are
+     * round-robined across them. Increases throughput at high concurrency
+     * by reducing head-of-line blocking on a single socket and using more
+     * of Redis's parallelism. Default 1 preserves current behaviour.
+     *
+     * Recommended: 1 for dev / low traffic, 4-8 for typical production
+     * workloads, 8-16 for sustained >10k ops/sec single-instance loads.
+     * Going much higher rarely helps and consumes Redis connection slots.
+     */
+    poolSize?: number;
+}
+export interface PerformanceLimits {
+    maxHydrationDepth: number;
+    maxEntitiesPerRequest: number;
+    maxMemoryUsagePerOperation: number;
+    maxConcurrentOperations: number;
+    batchSize: number;
+}
+export interface CircuitBreakerConfig {
+    threshold: number;
+    timeout: number;
+    resetTimeout: number;
+}
+export interface RetryConfig {
+    maxAttempts: number;
+    baseDelay: number;
+    maxDelay: number;
+    backoffFactor: number;
+}
+export type FallbackStrategy = 'null' | 'empty' | 'cached' | 'custom';
+export interface FallbackConfig {
+    enabled: boolean;
+    strategy: FallbackStrategy;
+}
+export interface ResilienceConfig {
+    circuitBreaker: CircuitBreakerConfig;
+    retry: RetryConfig;
+    fallback: FallbackConfig;
+}
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+export interface MonitoringConfig {
+    enableMetrics: boolean;
+    enableDebugMode: boolean;
+    enableAuditLog: boolean;
+    metricsInterval: number;
+    logLevel: LogLevel;
+}
+export interface CacheConfig {
+    defaultTTL: number;
+    enableL1Cache: boolean;
+    l1CacheSize: number;
+    enableCompression: boolean;
+    compressionThreshold: number;
+    /**
+     * (De)serializer used for entity payloads. Defaults to the engine's
+     * lossless tagged JSON serializer, which preserves `Date`, `BigInt`,
+     * `Map`, `Set`, `RegExp`, `Buffer`, `NaN`, and `±Infinity` across
+     * cache round-trips while remaining backward-compatible with plain
+     * JSON values written by older versions or other producers.
+     *
+     * Pass `JSON_SERIALIZER` to opt out (raw `JSON.stringify`/`parse`,
+     * fastest but lossy for the types listed above), or supply any
+     * `{ stringify, parse }` pair (e.g. wrapping `superjson`) to plug in
+     * a third-party codec. The same instance is used for writes and
+     * reads, so consistency is the consumer's responsibility when
+     * swapping serializers against an existing cache.
+     *
+     * Note: list bodies (the JSON id-array stored under a `list`
+     * schema's key) are intentionally NOT routed through this serializer
+     * because Lua scripts on the Redis side parse them directly. Lists
+     * always use plain JSON. Entity values (which contain user data)
+     * are the only thing the serializer touches.
+     */
+    serializer?: Serializer;
+}
+/**
+ * Safety guards for destructive operations. Kept in a dedicated config
+ * block so the engine itself never has to read `process.env` at runtime
+ * — important for npm-distributed builds where consumers' build systems
+ * may not set NODE_ENV the way Node apps do.
+ */
+export interface SafetyConfig {
+    /**
+     * When true, `clearAllCache()` requires an additional
+     * `{ allowProduction: true }` argument to succeed. Intended as a
+     * safety net so a stray call from a test harness or a mis-targeted
+     * CLI cannot wipe a production database.
+     *
+     * Defaults to `process.env.NODE_ENV === 'production'` at engine
+     * construction time so existing consumers keep the same behaviour
+     * with no config change. Library consumers should pass this
+     * explicitly rather than relying on the env default.
+     */
+    productionMode: boolean;
+}
+export interface RedisSchemaEngineConfig {
+    redis: RedisConfig;
+    limits: PerformanceLimits;
+    resilience: ResilienceConfig;
+    monitoring: MonitoringConfig;
+    cache: CacheConfig;
+    safety: SafetyConfig;
+}
+export type PartialRedisSchemaEngineConfig = Partial<RedisSchemaEngineConfig> & {
+    redis?: Partial<RedisConfig>;
+    limits?: Partial<PerformanceLimits>;
+    resilience?: Partial<ResilienceConfig>;
+    monitoring?: Partial<MonitoringConfig>;
+    cache?: Partial<CacheConfig>;
+    safety?: Partial<SafetyConfig>;
+};

package/dist/types/config.types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Configuration types for Redis Schema Engine
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/error.types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Error types and classification for Redis Schema Engine
+ */
+export declare enum RedisSchemaEngineErrorType {
+    SCHEMA_VALIDATION = "SCHEMA_VALIDATION",
+    ENTITY_NOT_FOUND = "ENTITY_NOT_FOUND",
+    INVALID_OPERATION = "INVALID_OPERATION",
+    REDIS_CONNECTION = "REDIS_CONNECTION",
+    MEMORY_LIMIT = "MEMORY_LIMIT",
+    TIMEOUT = "TIMEOUT",
+    CONCURRENT_MODIFICATION = "CONCURRENT_MODIFICATION",
+    CIRCUIT_BREAKER_OPEN = "CIRCUIT_BREAKER_OPEN",
+    HYDRATION_DEPTH_EXCEEDED = "HYDRATION_DEPTH_EXCEEDED",
+    INVALID_SCHEMA = "INVALID_SCHEMA",
+    MISSING_RELATION = "MISSING_RELATION"
+}
+export declare class RedisSchemaEngineError extends Error {
+    readonly type: RedisSchemaEngineErrorType;
+    readonly context?: any;
+    readonly cause?: Error;
+    readonly timestamp: number;
+    readonly requestId?: string;
+    constructor(type: RedisSchemaEngineErrorType, message: string, context?: any, cause?: Error, requestId?: string);
+    toJSON(): {
+        name: string;
+        type: RedisSchemaEngineErrorType;
+        message: string;
+        context: any;
+        timestamp: number;
+        requestId: string | undefined;
+        stack: string | undefined;
+    };
+}
+export declare class SchemaValidationError extends RedisSchemaEngineError {
+    constructor(message: string, context?: any, requestId?: string);
+}
+export declare class EntityNotFoundError extends RedisSchemaEngineError {
+    constructor(entityType: string, id: string | number, requestId?: string);
+}
+export declare class InvalidOperationError extends RedisSchemaEngineError {
+    constructor(operation: string, reason: string, context?: any, requestId?: string);
+}
+export declare class RedisConnectionError extends RedisSchemaEngineError {
+    constructor(message: string, cause?: Error, requestId?: string);
+}
+export declare class MemoryLimitError extends RedisSchemaEngineError {
+    constructor(currentUsage: number, limit: number, requestId?: string);
+}
+export declare class CircuitBreakerOpenError extends RedisSchemaEngineError {
+    constructor(requestId?: string);
+}
+export declare class HydrationDepthExceededError extends RedisSchemaEngineError {
+    constructor(currentDepth: number, maxDepth: number, requestId?: string);
+}

package/dist/types/error.types.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Error types and classification for Redis Schema Engine
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HydrationDepthExceededError = exports.CircuitBreakerOpenError = exports.MemoryLimitError = exports.RedisConnectionError = exports.InvalidOperationError = exports.EntityNotFoundError = exports.SchemaValidationError = exports.RedisSchemaEngineError = exports.RedisSchemaEngineErrorType = void 0;
+var RedisSchemaEngineErrorType;
+(function (RedisSchemaEngineErrorType) {
+    RedisSchemaEngineErrorType["SCHEMA_VALIDATION"] = "SCHEMA_VALIDATION";
+    RedisSchemaEngineErrorType["ENTITY_NOT_FOUND"] = "ENTITY_NOT_FOUND";
+    RedisSchemaEngineErrorType["INVALID_OPERATION"] = "INVALID_OPERATION";
+    RedisSchemaEngineErrorType["REDIS_CONNECTION"] = "REDIS_CONNECTION";
+    RedisSchemaEngineErrorType["MEMORY_LIMIT"] = "MEMORY_LIMIT";
+    RedisSchemaEngineErrorType["TIMEOUT"] = "TIMEOUT";
+    RedisSchemaEngineErrorType["CONCURRENT_MODIFICATION"] = "CONCURRENT_MODIFICATION";
+    RedisSchemaEngineErrorType["CIRCUIT_BREAKER_OPEN"] = "CIRCUIT_BREAKER_OPEN";
+    RedisSchemaEngineErrorType["HYDRATION_DEPTH_EXCEEDED"] = "HYDRATION_DEPTH_EXCEEDED";
+    RedisSchemaEngineErrorType["INVALID_SCHEMA"] = "INVALID_SCHEMA";
+    RedisSchemaEngineErrorType["MISSING_RELATION"] = "MISSING_RELATION";
+})(RedisSchemaEngineErrorType || (exports.RedisSchemaEngineErrorType = RedisSchemaEngineErrorType = {}));
+class RedisSchemaEngineError extends Error {
+    constructor(type, message, context, cause, requestId) {
+        super(message);
+        this.name = 'RedisSchemaEngineError';
+        this.type = type;
+        this.context = context;
+        this.cause = cause;
+        this.timestamp = Date.now();
+        this.requestId = requestId;
+        // Maintain proper stack trace (Node.js / V8 specific). On
+        // non-V8 runtimes `captureStackTrace` is undefined and the
+        // optional chain short-circuits cleanly.
+        Error.captureStackTrace?.(this, RedisSchemaEngineError);
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            type: this.type,
+            message: this.message,
+            context: this.context,
+            timestamp: this.timestamp,
+            requestId: this.requestId,
+            stack: this.stack,
+        };
+    }
+}
+exports.RedisSchemaEngineError = RedisSchemaEngineError;
+class SchemaValidationError extends RedisSchemaEngineError {
+    constructor(message, context, requestId) {
+        super(RedisSchemaEngineErrorType.SCHEMA_VALIDATION, message, context, undefined, requestId);
+    }
+}
+exports.SchemaValidationError = SchemaValidationError;
+class EntityNotFoundError extends RedisSchemaEngineError {
+    constructor(entityType, id, requestId) {
+        super(RedisSchemaEngineErrorType.ENTITY_NOT_FOUND, `Entity '${entityType}' with id '${id}' not found`, { entityType, id }, undefined, requestId);
+    }
+}
+exports.EntityNotFoundError = EntityNotFoundError;
+class InvalidOperationError extends RedisSchemaEngineError {
+    constructor(operation, reason, context, requestId) {
+        super(RedisSchemaEngineErrorType.INVALID_OPERATION, `Invalid operation '${operation}': ${reason}`, { operation, reason, ...context }, undefined, requestId);
+    }
+}
+exports.InvalidOperationError = InvalidOperationError;
+class RedisConnectionError extends RedisSchemaEngineError {
+    constructor(message, cause, requestId) {
+        super(RedisSchemaEngineErrorType.REDIS_CONNECTION, `Redis connection error: ${message}`, undefined, cause, requestId);
+    }
+}
+exports.RedisConnectionError = RedisConnectionError;
+class MemoryLimitError extends RedisSchemaEngineError {
+    constructor(currentUsage, limit, requestId) {
+        super(RedisSchemaEngineErrorType.MEMORY_LIMIT, `Memory limit exceeded: ${currentUsage}MB > ${limit}MB`, { currentUsage, limit }, undefined, requestId);
+    }
+}
+exports.MemoryLimitError = MemoryLimitError;
+class CircuitBreakerOpenError extends RedisSchemaEngineError {
+    constructor(requestId) {
+        super(RedisSchemaEngineErrorType.CIRCUIT_BREAKER_OPEN, 'Circuit breaker is OPEN - Redis operations are temporarily disabled', undefined, undefined, requestId);
+    }
+}
+exports.CircuitBreakerOpenError = CircuitBreakerOpenError;
+class HydrationDepthExceededError extends RedisSchemaEngineError {
+    constructor(currentDepth, maxDepth, requestId) {
+        super(RedisSchemaEngineErrorType.HYDRATION_DEPTH_EXCEEDED, `Hydration depth exceeded: ${currentDepth} > ${maxDepth}`, { currentDepth, maxDepth }, undefined, requestId);
+    }
+}
+exports.HydrationDepthExceededError = HydrationDepthExceededError;

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Barrel export for all Redis Schema Engine types
+ */
+export * from './schema.types';
+export * from './config.types';
+export * from './operation.types';
+export * from './internal.types';
+export * from './error.types';

package/dist/types/index.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Barrel export for all Redis Schema Engine types
+ */
+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 });
+// Schema types
+__exportStar(require("./schema.types"), exports);
+// Configuration types
+__exportStar(require("./config.types"), exports);
+// Operation types
+__exportStar(require("./operation.types"), exports);
+// Internal types and utilities
+__exportStar(require("./internal.types"), exports);
+// Error types
+__exportStar(require("./error.types"), exports);

package/dist/types/internal.types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Internal data structures and metadata types for Redis Schema Engine
+ */
+export interface EntityMetadata {
+    entityType: string;
+    originalId: string | number;
+    relationshipIds: Record<string, any>;
+    lastUpdated: number;
+    source: string;
+    version?: string;
+}
+export interface NormalizedEntity {
+    [key: string]: any;
+    __rse_version?: string;
+    __rse_timestamp?: number;
+    __rse_metadata?: EntityMetadata;
+}
+export interface HydrationContext {
+    visitedEntities: Set<string>;
+    currentDepth: number;
+    maxDepth: number;
+    memoryUsage: number;
+    maxMemory: number;
+    requestId: string;
+    selectiveFields?: string[];
+    excludeRelations?: string[];
+}
+export interface PipelineOperation {
+    type: 'GET' | 'SET' | 'DEL' | 'MGET' | 'MSET';
+    key?: string;
+    keys?: string[];
+    value?: string;
+    values?: Record<string, string>;
+}
+export interface PipelineResult {
+    success: boolean;
+    results: any[];
+    errors: Error[];
+    operationCount: number;
+    executionTime: number;
+}
+export interface CircuitBreakerState {
+    state: 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+    failures: number;
+    lastFailureTime: number;
+    lastSuccessTime: number;
+}
+export interface RetryOptions {
+    maxAttempts?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    backoffFactor?: number;
+}
+export interface FallbackOptions {
+    enableFallback?: boolean;
+    strategy?: 'null' | 'empty' | 'cached' | 'custom';
+    customFallback?: () => Promise<any>;
+}
+export declare const INTERNAL_FIELD_PREFIX = "__rse_";
+export declare const VERSION_FIELD = "__rse_version";
+export declare const TIMESTAMP_FIELD = "__rse_timestamp";
+export declare const METADATA_FIELD = "__rse_metadata";
+export declare const generateEntityKey: (entityType: string, id: string | number) => string;
+export declare const generateListKey: (listType: string, ...params: any[]) => string;
+export declare const generateRelationIdField: (relationName: string, kind: "one" | "many") => string;
+export declare const isInternalField: (fieldName: string) => boolean;
+export declare const stripInternalFields: (obj: any) => any;

package/dist/types/internal.types.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Internal data structures and metadata types for Redis Schema Engine
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripInternalFields = exports.isInternalField = exports.generateRelationIdField = exports.generateListKey = exports.generateEntityKey = exports.METADATA_FIELD = exports.TIMESTAMP_FIELD = exports.VERSION_FIELD = exports.INTERNAL_FIELD_PREFIX = void 0;
+// Internal field naming constants
+exports.INTERNAL_FIELD_PREFIX = '__rse_';
+exports.VERSION_FIELD = '__rse_version';
+exports.TIMESTAMP_FIELD = '__rse_timestamp';
+exports.METADATA_FIELD = '__rse_metadata';
+// Key generation utilities
+const generateEntityKey = (entityType, id) => {
+    return `${entityType}:${id}`;
+};
+exports.generateEntityKey = generateEntityKey;
+const generateListKey = (listType, ...params) => {
+    return `${listType}:${params.join(':')}`;
+};
+exports.generateListKey = generateListKey;
+const generateRelationIdField = (relationName, kind) => {
+    return kind === 'one'
+        ? `${exports.INTERNAL_FIELD_PREFIX}${relationName}Id`
+        : `${exports.INTERNAL_FIELD_PREFIX}${relationName}Ids`;
+};
+exports.generateRelationIdField = generateRelationIdField;
+const isInternalField = (fieldName) => {
+    return fieldName.startsWith(exports.INTERNAL_FIELD_PREFIX);
+};
+exports.isInternalField = isInternalField;
+/**
+ * Return true iff `value` is a plain `{ ... }` object literal (as
+ * opposed to an array, a Date/Map/Set/RegExp/Buffer, or some other
+ * class instance). Used by `stripInternalFields` to decide whether to
+ * recurse: recursing into a class instance would destroy it by copying
+ * its enumerable own properties into a fresh `{}` (a `Date` has none,
+ * so it becomes `{}` — a subtle data-loss bug the engine has to avoid
+ * now that the tagged serializer can surface real class instances).
+ */
+const isPlainObject = (value) => {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+};
+const stripInternalFields = (obj) => {
+    if (!obj || typeof obj !== 'object')
+        return obj;
+    if (Array.isArray(obj)) {
+        return obj.map((item) => (0, exports.stripInternalFields)(item));
+    }
+    // Preserve class instances (Date, Map, Set, RegExp, Buffer, or any
+    // user-supplied class) verbatim. Recursing into them would call
+    // `Object.entries` which returns `[]` for most built-ins, collapsing
+    // them into an empty `{}` and silently losing the value.
+    if (!isPlainObject(obj))
+        return obj;
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (!(0, exports.isInternalField)(key)) {
+            // Only recurse into plain objects / arrays. Class instances are
+            // assigned by reference so their identity and type survive.
+            result[key] =
+                value &&
+                    typeof value === 'object' &&
+                    (Array.isArray(value) || isPlainObject(value))
+                    ? (0, exports.stripInternalFields)(value)
+                    : value;
+        }
+    }
+    return result;
+};
+exports.stripInternalFields = stripInternalFields;

package/dist/types/operation.types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Operation result and context types for Redis Schema Engine
+ */
+export interface WriteResult {
+    success: boolean;
+    keys: string[];
+    operationId: string;
+    timestamp: number;
+    metadata?: Record<string, any>;
+}
+export interface ListWriteResult {
+    success: boolean;
+    key: string;
+    ids: any[];
+    operationId: string;
+    timestamp: number;
+}
+export interface BulkWriteOperation {
+    entityType: string;
+    id: string | number;
+    data: any;
+}
+export interface BulkDeleteOperation {
+    entityType: string;
+    id: string | number;
+}
+export interface BulkWriteResult {
+    success: boolean;
+    totalOperations: number;
+    successfulOperations: number;
+    failedOperations: BulkOperationFailure[];
+    operationId: string;
+    timestamp: number;
+}
+export interface BulkDeleteResult {
+    success: boolean;
+    totalOperations: number;
+    successfulOperations: number;
+    failedOperations: BulkOperationFailure[];
+    operationId: string;
+    timestamp: number;
+}
+export interface BulkOperationFailure {
+    operation: BulkWriteOperation | BulkDeleteOperation;
+    error: string;
+    index: number;
+}
+export interface CacheMetrics {
+    cacheHits: number;
+    cacheMisses: number;
+    hitRate: number;
+    totalOperations: number;
+    avgResponseTime: number;
+    memoryUsage: number;
+    activeConnections: number;
+    failedOperations: number;
+    lastUpdated: number;
+}
+export interface HealthStatus {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    redis: {
+        connected: boolean;
+        latency: number;
+        memoryUsage: number;
+    };
+    engine: {
+        activeOperations: number;
+        memoryUsage: number;
+        errorRate: number;
+    };
+    timestamp: number;
+}
+export interface HydrationOptions {
+    maxDepth?: number;
+    selectiveFields?: string[];
+    excludeRelations?: string[];
+    memoryLimit?: number;
+}
+export interface WriteContext {
+    entityType: string;
+    id: string | number;
+    data: any;
+    options?: any;
+    requestId: string;
+    timestamp: number;
+}
+export interface ReadContext {
+    entityType: string;
+    id: string | number;
+    options?: HydrationOptions;
+    requestId: string;
+    timestamp: number;
+}
+export interface OperationContext {
+    operation: string;
+    entityType?: string;
+    id?: string | number;
+    requestId: string;
+    timestamp: number;
+    metadata?: Record<string, any>;
+}

package/dist/types/operation.types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Operation result and context types for Redis Schema Engine
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/schema.types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Core schema type definitions for Redis Schema Engine
+ */
+/**
+ * Recognized field types for documentation / schema validation.
+ *
+ * IMPORTANT: field types are **advisory** — the engine does NOT coerce
+ * or transform values based on them. They exist so schemas are
+ * self-documenting and so obvious typos (e.g. `type: 'stirng'`) are
+ * caught at registration time. Actual type preservation across cache
+ * round-trips is handled by the configured `Serializer`.
+ *
+ * The first-class JSON types (`string`, `number`, `boolean`, `object`,
+ * `array`) round-trip through raw JSON unchanged. The extended types
+ * (`date`, `bigint`, `map`, `set`, `regexp`, `buffer`) require the
+ * default `TAGGED_SERIALIZER` (enabled by default) to round-trip
+ * losslessly; with `JSON_SERIALIZER` they degrade per the compatibility
+ * table in `USAGE.md`.
+ */
+export type FieldType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'date' | 'bigint' | 'map' | 'set' | 'regexp' | 'buffer';
+export type RelationKind = 'one' | 'many';
+export interface FieldDefinition {
+    type: FieldType;
+    required?: boolean;
+    validation?: (value: any) => boolean;
+}
+export interface RelationDefinition {
+    type: string;
+    kind: RelationKind;
+    cascade?: boolean;
+    lazy?: boolean;
+}
+export interface EntitySchema {
+    type: 'entity';
+    id: string;
+    key: (...args: any[]) => string;
+    fields?: Record<string, FieldDefinition>;
+    relations?: Record<string, RelationDefinition>;
+    ttl?: number;
+    version?: string;
+}
+export interface ListSchema {
+    type: 'list';
+    entityType: string;
+    key: (...args: any[]) => string;
+    idField: string;
+    ttl?: number;
+    version?: string;
+}
+/**
+ * ZSET-backed list schema. Use this instead of `ListSchema` for any list
+ * that may grow beyond a few hundred entries, needs paginated reads, needs
+ * efficient atomic add/remove, or needs to be sorted by something other
+ * than insertion order.
+ *
+ * Storage: a Redis sorted set (`ZSET`) where each member is the entity id
+ * and each score is either the value of `scoreField` on the entity (when
+ * specified and numeric) or the insertion timestamp in milliseconds.
+ *
+ * Why a separate type: keeping `ListSchema` and `IndexedListSchema`
+ * distinct lets existing code that uses the JSON-array list type keep
+ * working with no migration. New high-traffic lists adopt the indexed
+ * type, old ones stay where they are.
+ */
+export interface IndexedListSchema {
+    type: 'indexedList';
+    entityType: string;
+    key: (...args: any[]) => string;
+    idField: string;
+    /**
+     * Name of the entity field used as the ZSET score. Must resolve to a
+     * finite number on the entity (or a value that `Number()` converts to
+     * one — e.g. an ISO timestamp string, a numeric string, a Date). When
+     * omitted, members are scored by `Date.now()` at insertion time, which
+     * yields newest-first feeds when read in reverse order.
+     */
+    scoreField?: string;
+    /**
+     * Optional cap on list size. When set, every atomic insert trims the
+     * list back to at most `maxSize` entries by ZREMRANGEBYRANK, dropping
+     * the lowest-scored members. Use this for "latest N" feeds where older
+     * items can be discarded.
+     */
+    maxSize?: number;
+    /**
+     * When true, every insert also records a back-index entry mapping
+     * `entityId -> listKey` so `invalidateEntity` can cascade through and
+     * atomically remove the id from every tracked list it appears in.
+     * Default false (no overhead) since membership tracking only matters
+     * for entities that participate in many lists.
+     */
+    trackMembership?: boolean;
+    ttl?: number;
+    version?: string;
+}
+export type SchemaDefinition = EntitySchema | ListSchema | IndexedListSchema;
+export interface Schema {
+    [key: string]: SchemaDefinition;
+}
+export interface SchemaValidationResult {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+}