@spfn/core 0.1.0-alpha.64 → 0.1.0-alpha.68

package/README.md

@@ -85,7 +85,7 @@ npm run spfn:dev
 
 ## Architecture Pattern
 
-SPFN follows a **layered architecture** that separates concerns and keeps code maintainable:
+Superfunction follows a **layered architecture** that separates concerns and keeps code maintainable:
 
 ```
 ┌─────────────────────────────────────────┐
@@ -323,7 +323,7 @@ Drizzle ORM integration with type-safe helper functions and automatic transactio
 - **Function schema auto-discovery** (see below)
 
 ### 📦 Function Schema Discovery
-Automatic discovery of database schemas from SPFN ecosystem functions.
+Automatic discovery of database schemas from Superfunction ecosystem functions.
 
 **[→ Read Database Manager Documentation](./src/db/manager/README.md)**
 
@@ -347,7 +347,7 @@ Functions declare their schemas in `package.json`:
 }
 ```
 
-SPFN automatically discovers and merges these schemas during migration generation:
+Superfunction automatically discovers and merges these schemas during migration generation:
 ```typescript
 import { getDrizzleConfig } from '@spfn/core'
 
@@ -364,7 +364,7 @@ pnpm spfn add @spfn/cms
 # ✅ Shows setup guide
 ```
 
-**Create your own SPFN packages:**
+**Create your own Superfunction packages:**
 ```typescript
 // 1. Define entities
 export const myTable = pgTable('my_table', { ... })
@@ -557,4 +557,4 @@ MIT
 
 ---
 
-Part of the [SPFN Framework](https://github.com/spfn/spfn)
+Part of the [Superfunction Framework](https://github.com/spfn/spfn)

package/dist/{auto-loader-CdsxOceW.d.ts → auto-loader-JFaZ9gON.d.ts}

@@ -47,14 +47,15 @@ declare class AutoRouteLoader {
     load(app: Hono): Promise<RouteStats>;
     /**
      * Load routes from an external directory (e.g., from SPFN function packages)
-     * Routes use contract-based absolute paths, so no basePath prefix needed
+     * Reads package.json spfn.prefix and mounts routes under that prefix
      *
      * @param app - Hono app instance
      * @param routesDir - Directory containing route handlers
      * @param packageName - Name of the package (for logging)
+     * @param prefix - Optional prefix to mount routes under (from package.json spfn.prefix)
      * @returns Route statistics
      */
-    loadExternalRoutes(app: Hono, routesDir: string, packageName: string): Promise<RouteStats>;
+    loadExternalRoutes(app: Hono, routesDir: string, packageName: string, prefix?: string): Promise<RouteStats>;
     getStats(): RouteStats;
     private scanFiles;
     private isValidRouteFile;

package/dist/cache/index.d.ts

@@ -0,0 +1,211 @@
+import { Redis, Cluster } from 'ioredis';
+
+/**
+ * Cache factory with automatic environment variable detection
+ * Supports Valkey and Redis with multiple deployment patterns
+ *
+ * Valkey is a Redis fork (7.2.4 base) with 100% protocol compatibility
+ * https://valkey.io
+ */
+
+interface CacheClients {
+    /** Primary cache for writes (or both read/write if no replica) */
+    write?: Redis | Cluster;
+    /** Replica cache for reads (optional, falls back to write) */
+    read?: Redis | Cluster;
+}
+/**
+ * Create cache client(s) from environment variables
+ *
+ * Supported patterns (priority order):
+ * 1. Single instance: VALKEY_URL or CACHE_URL or REDIS_URL
+ * 2. Master-Replica: VALKEY_WRITE_URL + VALKEY_READ_URL (or CACHE_*, REDIS_*)
+ * 3. Sentinel: VALKEY_SENTINEL_HOSTS + VALKEY_MASTER_NAME (or REDIS_*)
+ * 4. Cluster: VALKEY_CLUSTER_NODES (or REDIS_*)
+ *
+ * @returns Cache client(s) or undefined if no configuration found
+ *
+ * @example
+ * ```bash
+ * # Single (most common)
+ * VALKEY_URL=valkey://localhost:6379
+ * CACHE_URL=redis://localhost:6379
+ *
+ * # Legacy (still supported)
+ * REDIS_URL=redis://localhost:6379
+ * REDIS_URL=rediss://secure.redis.com:6380  # TLS
+ *
+ * # Master-Replica
+ * VALKEY_WRITE_URL=valkey://master:6379
+ * VALKEY_READ_URL=valkey://replica:6379
+ *
+ * # Sentinel
+ * VALKEY_SENTINEL_HOSTS=sentinel1:26379,sentinel2:26379
+ * VALKEY_MASTER_NAME=mymaster
+ * VALKEY_PASSWORD=secret
+ *
+ * # Cluster
+ * VALKEY_CLUSTER_NODES=node1:6379,node2:6379,node3:6379
+ * VALKEY_PASSWORD=secret
+ * ```
+ */
+declare function createCacheFromEnv(): Promise<CacheClients>;
+/**
+ * Create single cache client (backward compatibility)
+ * Only returns write instance
+ */
+declare function createSingleCacheFromEnv(): Promise<Redis | Cluster | undefined>;
+
+/**
+ * Global cache instance manager
+ * Provides singleton access to cache (Valkey/Redis) across all modules
+ * Supports Master-Replica pattern with separate read/write instances
+ *
+ * When cache is unavailable, falls back to disabled mode gracefully
+ */
+
+/**
+ * Get global cache write instance
+ *
+ * @returns Cache write instance or undefined if disabled/not initialized
+ *
+ * @example
+ * ```typescript
+ * import { getCache } from '@spfn/core/cache';
+ *
+ * const cache = getCache();
+ * if (cache) {
+ *   await cache.set('key', 'value');
+ * } else {
+ *   // Cache disabled - handle gracefully
+ *   console.log('Cache unavailable, skipping...');
+ * }
+ * ```
+ */
+declare function getCache(): Redis | Cluster | undefined;
+/**
+ * Get global cache read instance (falls back to write if no replica)
+ *
+ * @returns Cache read instance or write instance as fallback, undefined if disabled
+ *
+ * @example
+ * ```typescript
+ * import { getCacheRead } from '@spfn/core/cache';
+ *
+ * const cache = getCacheRead();
+ * if (cache) {
+ *   const value = await cache.get('key');
+ * }
+ * ```
+ */
+declare function getCacheRead(): Redis | Cluster | undefined;
+/**
+ * Check if cache is disabled (connection failed or not configured)
+ *
+ * @example
+ * ```typescript
+ * import { isCacheDisabled } from '@spfn/core/cache';
+ *
+ * if (isCacheDisabled()) {
+ *   // Use alternative strategy (e.g., in-memory cache, database)
+ *   return await fetchFromDatabase();
+ * }
+ * ```
+ */
+declare function isCacheDisabled(): boolean;
+/**
+ * Set global cache instances (for testing or manual configuration)
+ *
+ * @param write - Cache write instance
+ * @param read - Cache read instance (optional, defaults to write)
+ *
+ * @example
+ * ```typescript
+ * import { setCache } from '@spfn/core/cache';
+ * import Redis from 'ioredis';
+ *
+ * const write = new Redis('redis://master:6379');
+ * const read = new Redis('redis://replica:6379');
+ * setCache(write, read);
+ * ```
+ */
+declare function setCache(write: Redis | Cluster | undefined, read?: Redis | Cluster | undefined): void;
+/**
+ * Initialize cache from environment variables
+ * Automatically called by startServer()
+ *
+ * Supported environment variables (priority order):
+ * - VALKEY_URL / CACHE_URL (single instance)
+ * - VALKEY_WRITE_URL + VALKEY_READ_URL (master-replica)
+ * - VALKEY_SENTINEL_HOSTS + VALKEY_MASTER_NAME (sentinel)
+ * - VALKEY_CLUSTER_NODES (cluster)
+ * - VALKEY_TLS_REJECT_UNAUTHORIZED (TLS config)
+ * - Legacy: REDIS_* (backward compatibility)
+ *
+ * @returns Object with write and read instances, or undefined if disabled
+ *
+ * @example
+ * ```typescript
+ * import { initCache } from '@spfn/core/cache';
+ *
+ * // Manual initialization (not needed if using startServer)
+ * const { write, read, disabled } = await initCache();
+ * if (!disabled) {
+ *   console.log('Cache available');
+ * }
+ * ```
+ */
+declare function initCache(): Promise<{
+    write?: Redis | Cluster;
+    read?: Redis | Cluster;
+    disabled: boolean;
+}>;
+/**
+ * Close all cache connections and cleanup
+ *
+ * @example
+ * ```typescript
+ * import { closeCache } from '@spfn/core/cache';
+ *
+ * // During graceful shutdown
+ * await closeCache();
+ * ```
+ */
+declare function closeCache(): Promise<void>;
+/**
+ * Get cache connection info (for debugging)
+ *
+ * @example
+ * ```typescript
+ * import { getCacheInfo } from '@spfn/core/cache';
+ *
+ * const info = getCacheInfo();
+ * console.log(info);
+ * // {
+ * //   hasWrite: true,
+ * //   hasRead: true,
+ * //   isReplica: true,
+ * //   disabled: false
+ * // }
+ * ```
+ */
+declare function getCacheInfo(): {
+    hasWrite: boolean;
+    hasRead: boolean;
+    isReplica: boolean;
+    disabled: boolean;
+};
+/** @deprecated Use getCache() instead */
+declare const getRedis: typeof getCache;
+/** @deprecated Use getCacheRead() instead */
+declare const getRedisRead: typeof getCacheRead;
+/** @deprecated Use setCache() instead */
+declare const setRedis: typeof setCache;
+/** @deprecated Use initCache() instead */
+declare const initRedis: typeof initCache;
+/** @deprecated Use closeCache() instead */
+declare const closeRedis: typeof closeCache;
+/** @deprecated Use getCacheInfo() instead */
+declare const getRedisInfo: typeof getCacheInfo;
+
+export { type CacheClients, type CacheClients as RedisClients, closeCache, closeRedis, createCacheFromEnv, createCacheFromEnv as createRedisFromEnv, createSingleCacheFromEnv, createSingleCacheFromEnv as createSingleRedisFromEnv, getCache, getCacheInfo, getCacheRead, getRedis, getRedisInfo, getRedisRead, initCache, initRedis, isCacheDisabled, setCache, setRedis };