@stacksjs/ts-cloud-core 0.1.1

package/src/utils/cache.ts

@@ -0,0 +1,291 @@
+/**
+ * Caching utilities for performance optimization
+ * Caches CloudFormation templates, credentials, and other data
+ */
+
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+export interface CacheOptions {
+  ttl?: number // Time to live in milliseconds
+  maxSize?: number // Maximum cache size
+}
+
+export interface CacheEntry<T> {
+  value: T
+  timestamp: number
+  hash?: string
+}
+
+/**
+ * Simple in-memory cache with TTL support
+ */
+export class Cache<T = any> {
+  private cache: Map<string, CacheEntry<T>>
+  private ttl: number
+  private maxSize: number
+
+  constructor(options: CacheOptions = {}) {
+    this.cache = new Map()
+    this.ttl = options.ttl || 5 * 60 * 1000 // Default: 5 minutes
+    this.maxSize = options.maxSize || 100 // Default: 100 entries
+  }
+
+  /**
+   * Get value from cache
+   */
+  get(key: string): T | undefined {
+    const entry = this.cache.get(key)
+
+    if (!entry) {
+      return undefined
+    }
+
+    // Check if entry has expired
+    if (Date.now() - entry.timestamp > this.ttl) {
+      this.cache.delete(key)
+      return undefined
+    }
+
+    return entry.value
+  }
+
+  /**
+   * Set value in cache
+   */
+  set(key: string, value: T, hash?: string): void {
+    // If cache is full, remove oldest entry
+    if (this.cache.size >= this.maxSize) {
+      const firstKey = this.cache.keys().next().value
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey)
+      }
+    }
+
+    this.cache.set(key, {
+      value,
+      timestamp: Date.now(),
+      hash,
+    })
+  }
+
+  /**
+   * Check if cache has key and it's not expired
+   */
+  has(key: string): boolean {
+    return this.get(key) !== undefined
+  }
+
+  /**
+   * Clear cache
+   */
+  clear(): void {
+    this.cache.clear()
+  }
+
+  /**
+   * Remove expired entries
+   */
+  prune(): void {
+    const now = Date.now()
+    for (const [key, entry] of this.cache.entries()) {
+      if (now - entry.timestamp > this.ttl) {
+        this.cache.delete(key)
+      }
+    }
+  }
+
+  /**
+   * Get cache stats
+   */
+  stats(): { size: number, ttl: number, maxSize: number } {
+    return {
+      size: this.cache.size,
+      ttl: this.ttl,
+      maxSize: this.maxSize,
+    }
+  }
+}
+
+/**
+ * File-based cache for persistent caching
+ */
+export class FileCache<T = any> {
+  private cacheDir: string
+  private ttl: number
+
+  constructor(cacheDir: string, options: CacheOptions = {}) {
+    this.cacheDir = cacheDir
+    this.ttl = options.ttl || 24 * 60 * 60 * 1000 // Default: 24 hours
+
+    // Create cache directory if it doesn't exist
+    if (!fs.existsSync(cacheDir)) {
+      fs.mkdirSync(cacheDir, { recursive: true })
+    }
+  }
+
+  /**
+   * Get cache file path for key
+   */
+  private getCachePath(key: string): string {
+    const hash = createHash('sha256').update(key).digest('hex')
+    return path.join(this.cacheDir, `${hash}.json`)
+  }
+
+  /**
+   * Get value from cache
+   */
+  get(key: string): T | undefined {
+    const cachePath = this.getCachePath(key)
+
+    if (!fs.existsSync(cachePath)) {
+      return undefined
+    }
+
+    try {
+      const data = fs.readFileSync(cachePath, 'utf-8')
+      const entry: CacheEntry<T> = JSON.parse(data)
+
+      // Check if entry has expired
+      if (Date.now() - entry.timestamp > this.ttl) {
+        fs.unlinkSync(cachePath)
+        return undefined
+      }
+
+      return entry.value
+    }
+    catch {
+      // If cache file is corrupted, delete it
+      fs.unlinkSync(cachePath)
+      return undefined
+    }
+  }
+
+  /**
+   * Set value in cache
+   */
+  set(key: string, value: T, hash?: string): void {
+    const cachePath = this.getCachePath(key)
+
+    const entry: CacheEntry<T> = {
+      value,
+      timestamp: Date.now(),
+      hash,
+    }
+
+    fs.writeFileSync(cachePath, JSON.stringify(entry), 'utf-8')
+  }
+
+  /**
+   * Check if cache has key and it's not expired
+   */
+  has(key: string): boolean {
+    return this.get(key) !== undefined
+  }
+
+  /**
+   * Clear all cache files
+   */
+  clear(): void {
+    const files = fs.readdirSync(this.cacheDir)
+    for (const file of files) {
+      fs.unlinkSync(path.join(this.cacheDir, file))
+    }
+  }
+
+  /**
+   * Remove expired entries
+   */
+  prune(): void {
+    const files = fs.readdirSync(this.cacheDir)
+    const now = Date.now()
+
+    for (const file of files) {
+      const filePath = path.join(this.cacheDir, file)
+
+      try {
+        const data = fs.readFileSync(filePath, 'utf-8')
+        const entry: CacheEntry<any> = JSON.parse(data)
+
+        if (now - entry.timestamp > this.ttl) {
+          fs.unlinkSync(filePath)
+        }
+      }
+      catch {
+        // If file is corrupted, delete it
+        fs.unlinkSync(filePath)
+      }
+    }
+  }
+}
+
+/**
+ * Template cache for CloudFormation templates
+ */
+export class TemplateCache {
+  private cache: FileCache<string>
+
+  constructor(cacheDir: string = '.ts-cloud/cache/templates') {
+    this.cache = new FileCache<string>(cacheDir, {
+      ttl: 24 * 60 * 60 * 1000, // 24 hours
+    })
+  }
+
+  /**
+   * Get template from cache
+   */
+  getTemplate(stackName: string): string | undefined {
+    return this.cache.get(`template:${stackName}`)
+  }
+
+  /**
+   * Save template to cache
+   */
+  setTemplate(stackName: string, template: string): void {
+    const hash = this.hashTemplate(template)
+    this.cache.set(`template:${stackName}`, template, hash)
+  }
+
+  /**
+   * Check if template has changed
+   */
+  hasChanged(stackName: string, newTemplate: string): boolean {
+    const cached = this.cache.get(`template:${stackName}`)
+
+    if (!cached) {
+      return true
+    }
+
+    const cachedHash = this.hashTemplate(cached)
+    const newHash = this.hashTemplate(newTemplate)
+
+    return cachedHash !== newHash
+  }
+
+  /**
+   * Hash template for comparison
+   */
+  private hashTemplate(template: string): string {
+    return createHash('sha256').update(template).digest('hex')
+  }
+
+  /**
+   * Clear all templates
+   */
+  clear(): void {
+    this.cache.clear()
+  }
+
+  /**
+   * Prune expired templates
+   */
+  prune(): void {
+    this.cache.prune()
+  }
+}
+
+/**
+ * Global template cache instance
+ */
+export const templateCache: TemplateCache = new TemplateCache()

package/src/utils/diff.ts

@@ -0,0 +1,269 @@
+/**
+ * Template diff utilities for incremental deployments
+ * Detect changes between CloudFormation templates to optimize deployments
+ */
+
+import type { CloudFormationTemplate } from '../cloudformation/types'
+
+export interface TemplateDiff {
+  added: string[] // Resource logical IDs
+  modified: string[] // Resource logical IDs
+  deleted: string[] // Resource logical IDs
+  unchanged: string[] // Resource logical IDs
+  parametersChanged: boolean
+  outputsChanged: boolean
+  hasChanges: boolean
+}
+
+/**
+ * Compare two CloudFormation templates
+ */
+export function diffTemplates(
+  oldTemplate: CloudFormationTemplate,
+  newTemplate: CloudFormationTemplate,
+): TemplateDiff {
+  const added: string[] = []
+  const modified: string[] = []
+  const deleted: string[] = []
+  const unchanged: string[] = []
+
+  const oldResources = oldTemplate.Resources || {}
+  const newResources = newTemplate.Resources || {}
+
+  const oldResourceIds = new Set(Object.keys(oldResources))
+  const newResourceIds = new Set(Object.keys(newResources))
+
+  // Find added resources
+  for (const id of newResourceIds) {
+    if (!oldResourceIds.has(id)) {
+      added.push(id)
+    }
+  }
+
+  // Find deleted resources
+  for (const id of oldResourceIds) {
+    if (!newResourceIds.has(id)) {
+      deleted.push(id)
+    }
+  }
+
+  // Find modified resources
+  for (const id of newResourceIds) {
+    if (oldResourceIds.has(id)) {
+      const oldResource = oldResources[id]
+      const newResource = newResources[id]
+
+      if (JSON.stringify(oldResource) !== JSON.stringify(newResource)) {
+        modified.push(id)
+      }
+      else {
+        unchanged.push(id)
+      }
+    }
+  }
+
+  // Check if parameters changed
+  const parametersChanged = JSON.stringify(oldTemplate.Parameters || {})
+    !== JSON.stringify(newTemplate.Parameters || {})
+
+  // Check if outputs changed
+  const outputsChanged = JSON.stringify(oldTemplate.Outputs || {})
+    !== JSON.stringify(newTemplate.Outputs || {})
+
+  return {
+    added,
+    modified,
+    deleted,
+    unchanged,
+    parametersChanged,
+    outputsChanged,
+    hasChanges: added.length > 0 || modified.length > 0 || deleted.length > 0 || parametersChanged || outputsChanged,
+  }
+}
+
+/**
+ * Get diff summary string
+ */
+export function getDiffSummary(diff: TemplateDiff): string {
+  const lines: string[] = []
+
+  if (!diff.hasChanges) {
+    return 'No changes detected'
+  }
+
+  if (diff.added.length > 0) {
+    lines.push(`Added resources (${diff.added.length}):`)
+    for (const id of diff.added) {
+      lines.push(`  + ${id}`)
+    }
+  }
+
+  if (diff.modified.length > 0) {
+    lines.push(`Modified resources (${diff.modified.length}):`)
+    for (const id of diff.modified) {
+      lines.push(`  ~ ${id}`)
+    }
+  }
+
+  if (diff.deleted.length > 0) {
+    lines.push(`Deleted resources (${diff.deleted.length}):`)
+    for (const id of diff.deleted) {
+      lines.push(`  - ${id}`)
+    }
+  }
+
+  if (diff.parametersChanged) {
+    lines.push('Parameters changed')
+  }
+
+  if (diff.outputsChanged) {
+    lines.push('Outputs changed')
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Check if diff requires replacement (destructive changes)
+ */
+export function requiresReplacement(
+  diff: TemplateDiff,
+  oldTemplate: CloudFormationTemplate,
+  newTemplate: CloudFormationTemplate,
+): boolean {
+  // If any resources are deleted, it requires replacement
+  if (diff.deleted.length > 0) {
+    return true
+  }
+
+  // Check modified resources for replacement-requiring changes
+  for (const id of diff.modified) {
+    const oldResource = oldTemplate.Resources[id]
+    const newResource = newTemplate.Resources[id]
+
+    // If resource type changed, it requires replacement
+    if (oldResource.Type !== newResource.Type) {
+      return true
+    }
+
+    // Check if properties that require replacement changed
+    // This is a simplified check - in reality, each resource type has specific properties
+    const replacementProperties = getReplacementProperties(newResource.Type)
+
+    for (const prop of replacementProperties) {
+      const oldValue = oldResource.Properties?.[prop]
+      const newValue = newResource.Properties?.[prop]
+
+      if (JSON.stringify(oldValue) !== JSON.stringify(newValue)) {
+        return true
+      }
+    }
+  }
+
+  return false
+}
+
+/**
+ * Get properties that require replacement when changed
+ * This is a simplified version - production code should use CloudFormation property docs
+ */
+function getReplacementProperties(resourceType: string): string[] {
+  const replacementProps: Record<string, string[]> = {
+    'AWS::S3::Bucket': ['BucketName'],
+    'AWS::EC2::Instance': ['ImageId', 'InstanceType', 'KeyName'],
+    'AWS::RDS::DBInstance': ['DBInstanceIdentifier', 'Engine'],
+    'AWS::DynamoDB::Table': ['TableName', 'KeySchema'],
+    'AWS::Lambda::Function': ['FunctionName'],
+    'AWS::ECS::Service': ['ServiceName'],
+    'AWS::ElasticLoadBalancingV2::LoadBalancer': ['Name', 'Type'],
+  }
+
+  return replacementProps[resourceType] || []
+}
+
+/**
+ * Categorize changes by risk level
+ */
+export function categorizeChanges(diff: TemplateDiff): {
+  safe: string[]
+  caution: string[]
+  dangerous: string[]
+} {
+  const safe: string[] = []
+  const caution: string[] = []
+  const dangerous: string[] = []
+
+  // Additions are generally safe
+  safe.push(...diff.added)
+
+  // Modifications need to be categorized
+  // This is simplified - real implementation would analyze specific property changes
+  for (const id of diff.modified) {
+    // For now, mark all modifications as caution
+    caution.push(id)
+  }
+
+  // Deletions are dangerous
+  dangerous.push(...diff.deleted)
+
+  return { safe, caution, dangerous }
+}
+
+/**
+ * Get deployment strategy based on diff
+ */
+export function getDeploymentStrategy(diff: TemplateDiff): {
+  strategy: 'create' | 'update' | 'replace' | 'skip'
+  reason: string
+} {
+  if (!diff.hasChanges) {
+    return {
+      strategy: 'skip',
+      reason: 'No changes detected',
+    }
+  }
+
+  if (diff.deleted.length > 0) {
+    return {
+      strategy: 'replace',
+      reason: 'Resources will be deleted',
+    }
+  }
+
+  if (diff.added.length > 0 && diff.modified.length === 0) {
+    return {
+      strategy: 'update',
+      reason: 'Only new resources added',
+    }
+  }
+
+  return {
+    strategy: 'update',
+    reason: 'Resources will be updated',
+  }
+}
+
+/**
+ * Calculate diff statistics
+ */
+export function getDiffStats(diff: TemplateDiff): {
+  total: number
+  added: number
+  modified: number
+  deleted: number
+  unchanged: number
+  changePercentage: number
+} {
+  const total = diff.added.length + diff.modified.length + diff.deleted.length + diff.unchanged.length
+  const changes = diff.added.length + diff.modified.length + diff.deleted.length
+  const changePercentage = total > 0 ? (changes / total) * 100 : 0
+
+  return {
+    total,
+    added: diff.added.length,
+    modified: diff.modified.length,
+    deleted: diff.deleted.length,
+    unchanged: diff.unchanged.length,
+    changePercentage,
+  }
+}