ts-prorm-orm 1.1.0 → 1.2.0

package/dist/cache/cache-manager.d.ts

@@ -0,0 +1,341 @@
+/**
+ * Cache Manager - Abstract CacheBackend interface
+ *
+ * Defines the contract for cache backends used in query result caching.
+ * Supports L1 (in-memory) and L2 (distributed) caching layers.
+ */
+/**
+ * Redis cluster node configuration
+ */
+export interface RedisClusterNodeConfig {
+    /**
+     * Host of the Redis node
+     */
+    host: string;
+    /**
+     * Port of the Redis node
+     */
+    port: number;
+    /**
+     * Password for the Redis node (optional)
+     */
+    password?: string;
+    /**
+     * Enable TLS for this node
+     */
+    tls?: boolean;
+}
+/**
+ * Redis cluster options
+ */
+export interface RedisClusterOptions {
+    /**
+     * Array of Redis cluster node addresses
+     */
+    nodes?: RedisClusterNodeConfig[];
+    /**
+     * Array of read replica nodes (for read scaling)
+     */
+    replicaNodes?: RedisClusterNodeConfig[];
+    /**
+     * Cluster password (used for all nodes)
+     */
+    password?: string;
+    /**
+     * Enable reading from replicas
+     */
+    enableReadFromReplicas?: boolean;
+    /**
+     * Maximum number of redirects
+     */
+    maxRedirections?: number;
+    /**
+     * Enable Redis keyspace notifications
+     */
+    enableKeyspaceNotifications?: boolean;
+    /**
+     * Redis database number (0-15)
+     */
+    db?: number;
+    /**
+     * Connection timeout in milliseconds
+     */
+    connectTimeout?: number;
+    /**
+     * Command timeout in milliseconds
+     */
+    commandTimeout?: number;
+    /**
+     * Enable TLS for all connections
+     */
+    tls?: boolean;
+}
+/**
+ * Abstract interface for cache backend implementations
+ */
+export interface CacheBackend {
+    /**
+     * Get a value from cache
+     * @param key - Cache key
+     * @returns Cached value or null if not found
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Set a value in cache
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param ttl - Time to live in seconds (optional)
+     * @returns True if successful
+     */
+    set(key: string, value: string, ttl?: number): Promise<boolean>;
+    /**
+     * Delete a key from cache
+     * @param key - Cache key
+     * @returns True if key was deleted
+     */
+    del(key: string): Promise<boolean>;
+    /**
+     * Check if a key exists in cache
+     * @param key - Cache key
+     * @returns True if key exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Invalidate all keys matching a pattern
+     * @param pattern - Key pattern (supports glob patterns like user:*)
+     * @returns Number of keys invalidated
+     */
+    invalidatePattern(pattern: string): Promise<number>;
+    /**
+     * Clear all cache entries (use with caution)
+     * @returns True if successful
+     */
+    clear(): Promise<boolean>;
+    /**
+     * Get multiple keys at once
+     * @param keys - Array of cache keys
+     * @returns Array of values (null for missing keys)
+     */
+    mget(keys: string[]): Promise<(string | null)[]>;
+    /**
+     * Set multiple keys at once
+     * @param entries - Array of {key, value, ttl?} objects
+     * @returns True if successful
+     */
+    mset(entries: Array<{
+        key: string;
+        value: string;
+        ttl?: number;
+    }>): Promise<boolean>;
+    /**
+     * Close the cache backend connection
+     * @returns Promise that resolves when connection is closed
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if cache backend is connected
+     * @returns True if connected
+     */
+    isConnected(): boolean;
+}
+/**
+ * L1 Cache options for in-memory cache layer
+ */
+export interface L1CacheOptions {
+    /**
+     * Enable L1 (in-memory) cache
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Maximum number of entries in L1 cache
+     * @default 1000
+     */
+    maxEntries?: number;
+    /**
+     * L1 cache TTL in seconds (for LRU eviction)
+     * @default 60
+     */
+    ttl?: number;
+}
+/**
+ * L2 Cache options for distributed cache layer
+ */
+export interface L2CacheOptions {
+    /**
+     * Enable L2 (Redis) cache
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Default TTL for L2 cache entries in seconds
+     * @default 3600 (1 hour)
+     */
+    defaultTtl?: number;
+}
+/**
+ * Cache key prefix configuration
+ */
+export interface CacheKeyOptions {
+    /**
+     * Prefix for all cache keys
+     * @default 'orm:cache:'
+     */
+    prefix?: string;
+    /**
+     * Separator between prefix and key
+     * @default ':'
+     */
+    separator?: string;
+}
+/**
+ * Combined cache manager options
+ */
+export interface CacheManagerOptions {
+    /**
+     * L1 (in-memory) cache options
+     */
+    l1?: L1CacheOptions;
+    /**
+     * L2 (Redis cluster) cache options
+     */
+    l2?: L2CacheOptions;
+    /**
+     * Cache key prefix options
+     */
+    key?: CacheKeyOptions;
+    /**
+     * Enable read-from-replicas for Redis cluster
+     * @default false
+     */
+    readFromReplicas?: boolean;
+    /**
+     * Redis cluster nodes configuration
+     */
+    clusterNodes?: RedisClusterNodeConfig[];
+    /**
+     * Additional Redis cluster options
+     */
+    clusterOptions?: Omit<RedisClusterOptions, 'nodes'>;
+    /**
+     * Maximum number of connections in the connection pool
+     * @default 10
+     */
+    maxConnections?: number;
+    /**
+     * Connect timeout in milliseconds
+     * @default 10000
+     */
+    connectTimeout?: number;
+    /**
+     * Command timeout in milliseconds
+     * @default 5000
+     */
+    commandTimeout?: number;
+    /**
+     * Retry strategy configuration
+     */
+    retryStrategy?: (times: number) => number | Error | null;
+    /**
+     * Database number (0-15)
+     * @default 0
+     */
+    db?: number;
+    /**
+     * Enable keyspace notifications for cache invalidation
+     * @default false
+     */
+    enableKeyspaceNotifications?: boolean;
+}
+/**
+ * Cache entry metadata
+ */
+export interface CacheEntry<T = any> {
+    /**
+     * The cached value
+     */
+    value: T;
+    /**
+     * Timestamp when entry was created
+     */
+    createdAt: number;
+    /**
+     * Timestamp when entry was last accessed
+     */
+    accessedAt: number;
+    /**
+     * Time to live in seconds
+     */
+    ttl?: number;
+}
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    /**
+     * Number of hits
+     */
+    hits: number;
+    /**
+     * Number of misses
+     */
+    misses: number;
+    /**
+     * Number of L1 hits
+     */
+    l1Hits: number;
+    /**
+     * Number of L2 hits
+     */
+    l2Hits: number;
+    /**
+     * Number of keys stored
+     */
+    keys: number;
+    /**
+     * Hit rate (0-1)
+     */
+    hitRate: number;
+}
+/**
+ * Abstract cache manager with L1/L2 support
+ */
+export declare abstract class AbstractCacheManager implements CacheBackend {
+    protected options: Required<CacheManagerOptions>;
+    protected stats: CacheStats;
+    constructor(options?: CacheManagerOptions);
+    /**
+     * Normalize and set default options
+     */
+    protected normalizeOptions(options: CacheManagerOptions): Required<CacheManagerOptions>;
+    /**
+     * Build a full cache key with prefix
+     */
+    protected buildKey(key: string): string;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset cache statistics
+     */
+    resetStats(): void;
+    abstract get(key: string): Promise<string | null>;
+    abstract set(key: string, value: string, ttl?: number): Promise<boolean>;
+    abstract del(key: string): Promise<boolean>;
+    abstract exists(key: string): Promise<boolean>;
+    abstract invalidatePattern(pattern: string): Promise<number>;
+    abstract clear(): Promise<boolean>;
+    abstract mget(keys: string[]): Promise<(string | null)[]>;
+    abstract mset(entries: Array<{
+        key: string;
+        value: string;
+        ttl?: number;
+    }>): Promise<boolean>;
+    abstract disconnect(): Promise<void>;
+    abstract isConnected(): boolean;
+}
+/**
+ * Factory function type for creating cache backends
+ */
+export type CacheBackendFactory = (options: CacheManagerOptions) => CacheBackend;

package/dist/cache/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Cache Module
+ *
+ * Provides caching functionality for query results using Redis Cluster
+ * with L1 (in-memory) and L2 (distributed Redis) cache layers.
+ */
+export { CacheBackend, AbstractCacheManager, type CacheManagerOptions, type L1CacheOptions, type L2CacheOptions, type CacheKeyOptions, type CacheEntry, type CacheStats, type CacheBackendFactory, type RedisClusterOptions, type RedisClusterNodeConfig, } from './cache-manager';
+export { RedisClusterCache, createRedisClusterCache, type RedisClusterCacheOptions, type RedisClusterNode, } from './redis-cluster-cache';

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

@@ -0,0 +1,164 @@
+/**
+ * Redis Cluster Cache Backend
+ *
+ * Implements CacheBackend using ioredis cluster with L1 (in-memory) and L2 (Redis cluster) caching.
+ */
+import type Redis from 'ioredis';
+import type { Cluster } from 'ioredis';
+import { AbstractCacheManager, type CacheManagerOptions, type CacheStats } from './cache-manager';
+/**
+ * Redis cluster node configuration
+ */
+export interface RedisClusterNode {
+    /**
+     * Host of the Redis node
+     */
+    host: string;
+    /**
+     * Port of the Redis node
+     */
+    port: number;
+    /**
+     * Password for the Redis node (optional)
+     */
+    password?: string;
+    /**
+     * Enable TLS for this node
+     */
+    tls?: boolean;
+}
+/**
+ * Extended options for Redis cluster cache
+ */
+export interface RedisClusterCacheOptions extends CacheManagerOptions {
+    /**
+     * Redis cluster nodes configuration
+     */
+    clusterNodes?: RedisClusterNode[];
+    /**
+     * Maximum number of connections in the connection pool
+     * @default 10
+     */
+    maxConnections?: number;
+    /**
+     * Enable read-from-replicas for Redis cluster
+     * @default false
+     */
+    readFromReplicas?: boolean;
+    /**
+     * Connect timeout in milliseconds
+     * @default 10000
+     */
+    connectTimeout?: number;
+    /**
+     * Command timeout in milliseconds
+     * @default 5000
+     */
+    commandTimeout?: number;
+    /**
+     * Retry strategy configuration
+     */
+    retryStrategy?: (times: number) => number | Error | null;
+    /**
+     * Enable keyspace notifications for cache invalidation
+     * @default false
+     */
+    enableKeyspaceNotifications?: boolean;
+    /**
+     * Database number (0-15)
+     * @default 0
+     */
+    db?: number;
+}
+/**
+ * Redis Cluster Cache implementation with L1/L2 support
+ */
+export declare class RedisClusterCache extends AbstractCacheManager {
+    private redisCluster;
+    private redisReplicas;
+    private l1Cache;
+    private connected;
+    protected get clusterOptions(): RedisClusterCacheOptions;
+    constructor(options?: RedisClusterCacheOptions);
+    /**
+     * Initialize Redis cluster connection
+     */
+    private initializeCluster;
+    /**
+     * Initialize read replicas for read-from-replicas functionality
+     */
+    private initializeReplicas;
+    /**
+     * Get a value from cache, checking L1 first then L2
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Set a value in cache (both L1 and L2)
+     */
+    set(key: string, value: string, ttl?: number): Promise<boolean>;
+    /**
+     * Delete a key from cache (both L1 and L2)
+     */
+    del(key: string): Promise<boolean>;
+    /**
+     * Check if a key exists in cache
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Invalidate all keys matching a pattern
+     */
+    invalidatePattern(pattern: string): Promise<number>;
+    /**
+     * Clear all cache entries
+     */
+    clear(): Promise<boolean>;
+    /**
+     * Get multiple keys at once
+     */
+    mget(keys: string[]): Promise<(string | null)[]>;
+    /**
+     * Set multiple keys at once
+     */
+    mset(entries: Array<{
+        key: string;
+        value: string;
+        ttl?: number;
+    }>): Promise<boolean>;
+    /**
+     * Get the appropriate Redis client (master or replica)
+     */
+    private getRedisClient;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Close all Redis connections
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if cache backend is connected
+     */
+    isConnected(): boolean;
+    /**
+     * Get the underlying Redis cluster instance
+     */
+    getRedisCluster(): Cluster | null;
+    /**
+     * Get all replica connections
+     */
+    getReplicas(): Redis[];
+    /**
+     * Manually invalidate L1 cache (useful for testing)
+     */
+    clearL1(): void;
+    /**
+     * Convert glob pattern to regex
+     */
+    private patternToRegex;
+}
+/**
+ * Create a RedisClusterCache instance with simplified options
+ */
+export declare function createRedisClusterCache(nodes: RedisClusterNode[], options?: Partial<RedisClusterCacheOptions>): RedisClusterCache;
+export default RedisClusterCache;

package/dist/cache/redis-cluster-cache.js

@@ -4,43 +4,25 @@
  *
  * Implements CacheBackend using ioredis cluster with L1 (in-memory) and L2 (Redis cluster) caching.
  */
-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.RedisClusterCache = void 0;
 exports.createRedisClusterCache = createRedisClusterCache;
-const ioredis_1 = __importStar(require("ioredis"));
+// Lazily-loaded `ioredis` driver. Required only when a cluster connection is
+// initialized, so importing this ORM never loads the ioredis driver.
+let ioredisModule = null;
+function loadIoRedis() {
+    if (!ioredisModule) {
+        try {
+            ioredisModule = require('ioredis');
+        }
+        catch (err) {
+            throw new Error("The 'ioredis' package is required to use the Redis cluster cache but could not be loaded. " +
+                'Install it with `npm install ioredis`. Original error: ' +
+                (err instanceof Error ? err.message : String(err)));
+        }
+    }
+    return ioredisModule;
+}
 const cache_manager_1 = require("./cache-manager");
 /**
  * LRU Map implementation for L1 cache
@@ -151,7 +133,7 @@ class RedisClusterCache extends cache_manager_1.AbstractCacheManager {
                 return Math.min(times * 200, 3000); // Max 3 seconds
             };
         }
-        this.redisCluster = new ioredis_1.Cluster(clusterNodes, clusterOptions);
+        this.redisCluster = new (loadIoRedis().Cluster)(clusterNodes, clusterOptions);
         this.redisCluster.on('connect', () => {
             this.connected = true;
             console.log('RedisClusterCache: Connected to cluster');
@@ -176,7 +158,8 @@ class RedisClusterCache extends cache_manager_1.AbstractCacheManager {
             return;
         }
         for (const node of this.options.clusterOptions.replicaNodes) {
-            const redis = new ioredis_1.default({
+            const RedisCtor = loadIoRedis().default ?? loadIoRedis();
+            const redis = new RedisCtor({
                 host: node.host,
                 port: node.port,
                 password: node.password,

package/dist/cli/cloud.d.ts

@@ -0,0 +1,55 @@
+export interface CliConfig {
+    apiUrl: string;
+    token?: string;
+    /** Set when the access token is held in the OS keychain, not in this file. */
+    tokenInKeychain?: boolean;
+    /** Optional refresh token for re-minting an expired access token. */
+    refreshToken?: string;
+    /** Currently-selected user or team context. */
+    user?: {
+        id: string;
+        email: string;
+        name?: string;
+    };
+    teamId?: string;
+    teamSlug?: string;
+    defaultDb?: string;
+}
+export declare function configPath(): string;
+export declare function loadConfig(): CliConfig;
+export declare function saveConfig(cfg: CliConfig): void;
+export declare function updateConfig(patch: Partial<CliConfig>): CliConfig;
+/**
+ * Store the access token, preferring the OS keychain. Returns whether the
+ * keychain was used (false = written to the config file as a fallback).
+ */
+export declare function storeToken(token: string, extra?: Partial<CliConfig>): boolean;
+export declare function clearAuth(): void;
+export declare function requireAuth(): CliConfig & {
+    token: string;
+};
+export declare class ApiError extends Error {
+    status: number;
+    /** Field-level validation details from the API response, if any. */
+    details?: unknown;
+    constructor(message: string, status: number, details?: unknown);
+}
+export declare class AuthError extends ApiError {
+    constructor(message: string);
+}
+export declare class NetworkError extends Error {
+    code: string;
+}
+export interface ApiOptions {
+    method?: string;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+    auth?: boolean;
+    token?: string;
+    /** Per-call timeout in ms (default: --timeout or 30s). */
+    timeoutMs?: number;
+    /** Max retry attempts on transient failures (default 3). */
+    retries?: number;
+}
+/** Call the dashboard API with timeout, retry/backoff, and typed errors. */
+export declare function api<T = unknown>(pathname: string, opts?: ApiOptions): Promise<T>;