@codeleap/styles 5.8.2 → 5.8.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeleap/styles",
-  "version": "5.8.2",
+  "version": "5.8.4",
   "main": "src/index.ts",
   "license": "UNLICENSED",
   "repository": {
@@ -9,28 +9,22 @@
     "directory": "packages/styles"
   },
   "devDependencies": {
-    "@codeleap/config": "5.8.2",
+    "@codeleap/config": "5.8.4",
     "ts-node-dev": "^1.1.8"
   },
   "scripts": {
-    "build": "echo 'No build needed'",
-    "lint": "eslint -c  .eslintrc.js --fix \"./src/**/*.{ts,tsx,js,jsx}\"",
-    "test": "./node_modules/.bin/mocha --require ts-node/register src/tests/**/*.spec.ts",
-    "run-sc": "tsnd --transpile-only",
-    "test:watch": "./node_modules/.bin/mocha --require ts-node/register ./src/tests/**/*.spec.ts -w --watch-files ./src/tests/**/*.spec.ts",
-    "createStyleSheets": "bun run-sc src/scripts/createStyleSheets.ts"
+    "build": "echo 'No build needed'"
   },
   "peerDependencies": {
     "react": "18.2.0",
     "typescript": "5.0.4"
   },
   "dependencies": {
-    "@fastify/deepmerge": "1.3.0",
-    "@nanostores/persistent": "^1.1.0",
-    "@nanostores/react": "^1.0.0",
-    "js-sha256": "0.11.0",
-    "lz-string": "^1.5.0",
-    "nanostores": "^1.0.1",
-    "rfdc": "^1.4.1"
+    "@fastify/deepmerge": "3.1.0",
+    "@nanostores/react": "1.0.0",
+    "js-sha256": "0.11.1",
+    "lz-string": "1.5.0",
+    "nanostores": "1.0.1",
+    "rfdc": "1.4.1"
   }
 }

package/package.json.bak

@@ -1,6 +1,6 @@
 {
   "name": "@codeleap/styles",
-  "version": "5.8.2",
+  "version": "5.8.4",
   "main": "src/index.ts",
   "license": "UNLICENSED",
   "repository": {
@@ -13,24 +13,18 @@
     "ts-node-dev": "^1.1.8"
   },
   "scripts": {
-    "build": "echo 'No build needed'",
-    "lint": "eslint -c  .eslintrc.js --fix \"./src/**/*.{ts,tsx,js,jsx}\"",
-    "test": "./node_modules/.bin/mocha --require ts-node/register src/tests/**/*.spec.ts",
-    "run-sc": "tsnd --transpile-only",
-    "test:watch": "./node_modules/.bin/mocha --require ts-node/register ./src/tests/**/*.spec.ts -w --watch-files ./src/tests/**/*.spec.ts",
-    "createStyleSheets": "bun run-sc src/scripts/createStyleSheets.ts"
+    "build": "echo 'No build needed'"
   },
   "peerDependencies": {
     "react": "18.2.0",
     "typescript": "5.0.4"
   },
   "dependencies": {
-    "@fastify/deepmerge": "1.3.0",
-    "@nanostores/persistent": "^1.1.0",
-    "@nanostores/react": "^1.0.0",
-    "js-sha256": "0.11.0",
-    "lz-string": "^1.5.0",
-    "nanostores": "^1.0.1",
-    "rfdc": "^1.4.1"
+    "@fastify/deepmerge": "3.1.0",
+    "@nanostores/react": "1.0.0",
+    "js-sha256": "0.11.1",
+    "lz-string": "1.5.0",
+    "nanostores": "1.0.1",
+    "rfdc": "1.4.1"
   }
 }

package/src/classes/Cacher.ts

@@ -0,0 +1,169 @@
+import { CacheType } from '../types/cache'
+import { StateStorage } from '../types/store'
+import { StyleConstants } from '../constants'
+import { hashKey } from '../tools'
+
+/**
+ * Generates a stale time date by adding 7 days to the current date
+ * @returns {Date} The future date representing the stale time
+ */
+function generateStaleTime() {
+  const time = 7
+
+  let currentTime = new Date()
+
+  currentTime.setDate(currentTime.getDate() + time)
+
+  return currentTime
+}
+
+/**
+ * Generic cache implementation with persistence and stale time management
+ * @template T - The type of values stored in the cache
+ */
+export class Cache<T extends any = any> {
+  /** In-memory cache storage */
+  cache: Record<string, T> = {}
+
+  /**
+   * Gets the persistence key for cache data
+   * @returns {string} The storage key for cache data
+   */
+  get persistKeyCache() {
+    return `@styles.caches.${this.registryName}.cache`
+  }
+
+  /**
+   * Gets the persistence key for stale time
+   * @returns {string} The storage key for stale time
+   */
+  get persistKeyStaleTime() {
+    return `@styles.caches.${this.registryName}.staleTime`
+  }
+
+  /**
+   * Creates a new Cache instance
+   * @param {CacheType} registryName - The name/type of the cache registry
+   * @param {StateStorage} [storage=null] - The storage implementation for persistence
+   * @param {boolean} [persistCache=!!storage] - Whether to persist cache to storage
+   */
+  constructor(
+    public registryName: CacheType,
+    private storage: StateStorage = null,
+    public persistCache: boolean = !!storage,
+  ) {
+    if (!persistCache || !StyleConstants.STORE_CACHE_ENABLED) return
+
+    const { persistedCache, persistedStaleTime } = this.loadStorage()
+
+    const currentTime = new Date()
+
+    const isStaled = currentTime > persistedStaleTime
+
+    if (isStaled) {
+      this.clearStorage()
+      return
+    }
+
+    if (StyleConstants.LOG) {
+      console.log('Cache [constructor] ->', { persistedCache, persistedStaleTime, registryName })
+    }
+
+    this.setCache(persistedCache)
+    this.storeStaleTime(persistedStaleTime)
+  }
+
+  /**
+   * Generates a cache key and retrieves the cached value
+   * @param {string} cacheBaseKey - The base key for cache generation
+   * @param {Array<any> | any} data - The data to use for key generation
+   * @returns {{ key: string, value: T | null }} Object containing the cache key and value
+   */
+  keyFor(cacheBaseKey: string, data: Array<any> | any) {
+    const values = [cacheBaseKey, data]
+
+    const cacheKey = hashKey(values)
+    const cachedValue = this.cache[cacheKey] ?? null
+
+    return {
+      key: cacheKey,
+      value: cachedValue,
+    }
+  }
+
+  /**
+   * Stores a value in the cache and optionally persists it
+   * @param {string} key - The cache key
+   * @param {T} cache - The value to cache
+   * @returns {T} The cached value
+   */
+  cacheFor(key: string, cache: T) {
+    this.cache[key] = cache
+    if (this.persistCache) this.storeCache()
+    return cache
+  }
+
+  /**
+   * Replaces the entire cache with new data
+   * @param {Record<string, T>} cache - The new cache data
+   */
+  setCache(cache: Record<string, T>) {
+    this.cache = cache ?? {}
+  }
+
+  /**
+   * Clears both in-memory and persistent cache
+   */
+  clear() {
+    this.cache = {}
+    this.clearStorage()
+  }
+
+  /**
+   * Loads cache data and stale time from persistent storage
+   * @returns {{ persistedStaleTime: Date, persistedCache: any }} Loaded data from storage
+   */
+  loadStorage() {
+    if (!this.persistCache) return { persistedStaleTime: generateStaleTime(), persistedCache: {} }
+
+    const persistedStaleTime = this.storage.getItem(this.persistKeyStaleTime)
+    const persistedCache = this.storage.getItem(this.persistKeyCache)
+
+    return {
+      persistedStaleTime: !persistedStaleTime ? generateStaleTime() : new Date(persistedStaleTime),
+      persistedCache,
+    }
+  }
+
+  /**
+   * Clears cache data from persistent storage
+   */
+  clearStorage() {
+    if (!this.persistCache) return
+
+    this.storage.removeItem(this.persistKeyStaleTime)
+    this.storage.removeItem(this.persistKeyCache)
+  }
+
+  /**
+   * Stores cache data to persistent storage
+   * @param {Record<string, T>} [cache=null] - Cache data to store (uses current cache if not provided)
+   */
+  storeCache(cache: Record<string, T> = null) {
+    if (!this.persistCache) return
+
+    const value = cache ?? this.cache
+    this.storage.setItem(this.persistKeyCache, value)
+  }
+
+  /**
+   * Stores stale time to persistent storage
+   * @param {Date} staleTime - The stale time to store
+   */
+  storeStaleTime(staleTime: Date) {
+    if (!this.persistCache) return
+
+    const value = staleTime.toISOString()
+    this.storage.setItem(this.persistKeyStaleTime, value)
+  }
+}

package/src/classes/StaleControl.ts

@@ -0,0 +1,125 @@
+/**
+ * @UNUSED_IMPLEMENTATION - Class available for future use
+ * Stale data controller with temporal expiration system
+ * 
+ * @description This implementation is complete but not currently being used.
+ * Developed for potential future need of time-based cache invalidation.
+ */
+ export class StaleControl {
+  private wiperId: Timer | null = null
+
+  /**
+   * @UNUSED_IMPLEMENTATION - Constructor available for future use
+   * @param staleTime - Expiration time in minutes (default: 60 minutes)
+   * @param staleTimeIdentifier - Separator to identify timestamp in value (default: '//:')
+   * @param wiperInterval - Expired data check interval in milliseconds (default: 30 minutes)
+   */
+  constructor(
+    private staleTime: number = 60, // minutes
+    private staleTimeIdentifier: string = '//:',
+    private wiperInterval: number = 30 * 60 * 1000, // 30 minutes
+  ) {}
+
+  /**
+   * @UNUSED_IMPLEMENTATION - Method available for future use
+   * Checks if a value is expired based on embedded timestamp
+   * @param value - Value with embedded timestamp
+   * @returns boolean indicating if value is expired
+   */
+  isStaled(value: string): boolean {
+    const { staleTime } = this.extractStaleTime(value)
+
+    const currentTime = new Date()
+
+    const isStaled = currentTime > staleTime
+
+    return isStaled
+  }
+
+  /**
+   * @UNUSED_IMPLEMENTATION - Method available for future use
+   * Inserts expiration timestamp into a value
+   * @param value - Original value without timestamp
+   * @returns Value with expiration timestamp embedded
+   */
+  insertStaleTime(value: string): string {
+    const currentTime = new Date()
+    currentTime.setMinutes(currentTime.getMinutes() + this.staleTime)
+
+    const staleTime = currentTime.toISOString()
+    const valueWithStaleTime = `${value}${this.staleTimeIdentifier}${staleTime}`
+
+    return valueWithStaleTime
+  }
+
+  /**
+   * @UNUSED_IMPLEMENTATION - Method available for future use
+   * Refreshes the expiration timestamp of a value
+   * @param value - Value with existing timestamp
+   * @returns Value with refreshed expiration timestamp
+   */
+  refreshStaleTime(value: string): string {
+    const { value: extractedValue } = this.extractStaleTime(value)
+    const refreshedValue = this.insertStaleTime(extractedValue)
+
+    return refreshedValue
+  }
+
+  /**
+   * @UNUSED_IMPLEMENTATION - Method available for future use
+   * Extracts expiration timestamp and original value
+   * @param value - Value with embedded timestamp
+   * @returns Object containing expiration date and original value
+   */
+  extractStaleTime(value: string): { staleTime: Date; value: string } {
+    const [extractedValue, _staleTime] = value?.split(this.staleTimeIdentifier) || []
+    const staleTime = new Date(_staleTime || 0)
+
+    return {
+      staleTime,
+      value: extractedValue || value,
+    }
+  }
+
+  /**
+   * @UNUSED_IMPLEMENTATION - Method available for future use
+   * Wipes expired cache; verifies isStaled values and removes them
+   * @throws Error indicating method is not implemented
+   */
+  cacheWiper(): void {
+    throw new Error('Cache Wiper not implemented - Requires storage integration for future use')
+  }
+
+  /**
+   * @UNUSED_IMPLEMENTATION - Method available for future use
+   * Registers periodic cache cleaning interval
+   */
+  registerCacheWiper(): void {
+    if (this.wiperId !== null) {
+      this.unregisterCacheWiper()
+    }
+
+    this.wiperId = setInterval(() => {
+      this.cacheWiper()
+    }, this.wiperInterval)
+  }
+
+  /**
+   * @UNUSED_IMPLEMENTATION - Method available for future use
+   * Unregisters periodic cache cleaning interval
+   */
+  unregisterCacheWiper(): void {
+    if (this.wiperId) {
+      clearInterval(this.wiperId)
+      this.wiperId = null
+    }
+  }
+
+  /**
+   * @UNUSED_IMPLEMENTATION - Method available for future use
+   * Cleanup method to clear intervals when instance is no longer needed
+   */
+  destroy(): void {
+    this.unregisterCacheWiper()
+  }
+}

package/src/classes/StyleCache.ts

@@ -0,0 +1,116 @@
+import { Cache } from './Cacher'
+import { hashKey, minifier } from '../tools'
+import { StyleConstants } from '../constants'
+import { CacheType } from '../types/cache'
+import { StateStorage } from '../types/store'
+
+/**
+ * StyleCache manages multiple cache instances for different style-related data.
+ * Provides centralized caching functionality with compression and key generation.
+ */
+export class StyleCache {
+  /** Base key used for cache key generation */
+  baseKey: string
+
+  /** Cache for style data */
+  styles = new Cache('styles')
+
+  /** Cache for style compositions */
+  compositions = new Cache('compositions')
+
+  /** Cache for responsive styles */
+  responsive = new Cache('responsive')
+
+  /** Cache for style variants with persistent storage */
+  variants: Cache
+
+  /** Cache for common styles with persistent storage */
+  common: Cache
+
+  /** Cache for component styles with persistent storage */
+  components: Cache
+
+  /**
+   * Creates a new StyleCache instance
+   * @param storage - State storage instance for persistent caches
+   */
+  constructor(storage: StateStorage) {
+    this.variants = new Cache('variants', storage)
+    this.common = new Cache('common', storage)
+    this.components = new Cache('components', storage)
+  }
+
+  /**
+   * Registers and generates a base key for cache operations
+   * @param keys - Array of values to include in base key generation
+   * @returns The generated base key hash
+   */
+  registerBaseKey(keys: Array<any>): string {
+    keys.push(StyleConstants.STORES_PERSIST_VERSION)
+
+    const baseKey = hashKey(keys)
+
+    this.baseKey = baseKey
+
+    return baseKey
+  }
+
+  /**
+   * Clears all cache instances
+   */
+  wipeCache(): void {
+    this.components.clear()
+    this.responsive.clear()
+    this.compositions.clear()
+    this.variants.clear()
+    this.common.clear()
+    this.styles.clear()
+  }
+
+  /**
+   * Generates a cache key and retrieves cached value if exists
+   * @param type - The cache type to use
+   * @param keyData - Data to use for key generation (array or object)
+   * @returns Object containing the generated key and cached value (if any)
+   */
+  keyFor(type: CacheType, keyData: Array<any> | any): { key: string; value: any } {
+    const cache = this[type]
+
+    const withFunctionsHash = Object.values(keyData).map((value) => {
+      if (typeof value === 'function') {
+        return value.toString()
+      }
+
+      return value
+    })
+
+    const values = [this.baseKey, ...withFunctionsHash]
+
+    const cacheKey = hashKey(values)
+    const cachedValue = minifier.decompress(cache.cache[cacheKey] ?? null)
+
+    return {
+      key: cacheKey,
+      value: cachedValue,
+    }
+  }
+
+  /**
+   * Stores a value in the specified cache with compression
+   * @param type - The cache type to use
+   * @param key - Cache key
+   * @param value - Value to cache
+   * @returns The cached value (compressed if caching is enabled)
+   */
+  cacheFor(type: CacheType, key: string, value: any): any {
+    if (!StyleConstants.CACHE_ENABLED) {
+      return value
+    }
+
+    const cache = this[type]
+
+    const minifiedValue = minifier.compress(value)
+
+    return cache.cacheFor(key, minifiedValue)
+  }
+}

package/src/classes/StylePersistor.ts

@@ -0,0 +1,62 @@
+import { StateStorage } from '../types/store'
+import { minifier } from '../tools'
+import { StyleConstants } from '../constants'
+
+export type StoragePersistor = {
+  set: (key: string, value: any) => void
+  get: (key: string) => any
+  del: (key: string) => void
+}
+
+export class StylePersistor implements StateStorage {
+  /**
+   * Creates a new StylePersistor instance with compression capabilities
+   * @param {StoragePersistor} storage - The underlying storage implementation
+   */
+  constructor(
+    private storage: StoragePersistor
+  ) { }
+
+  /**
+   * Stores a value in the underlying storage with compression
+   * 
+   * @param {string} name - Storage key identifier
+   * @param {string} value - Value to store (will be compressed)
+   * @returns {void}
+   * @throws {Error} If the underlying storage fails to set the value
+   */
+  setItem(name: string, value: string): void {
+    const minifiedValue = minifier.compress(value)
+
+    return this.storage.set(name, minifiedValue)
+  }
+
+  /**
+   * Retrieves and decompresses a value from storage
+   * Returns null if key doesn't exist, value is null/undefined, or decompression fails
+   * 
+   * @param {string} name - Storage key identifier
+   * @returns {string | null} Decompressed value or null if not found/invalid
+   * @throws {Error} If the underlying storage fails to get the value
+   */
+  getItem(name: string): string | null {
+    const persistedValue = this.storage.get(name)
+
+    if (StyleConstants.LOG) {
+      console.log('StylePersistor [getItem] => ' + name, persistedValue)
+    }
+
+    return minifier.decompress(persistedValue ?? null)
+  }
+
+  /**
+   * Removes an item from storage
+   * 
+   * @param {string} name - Storage key identifier
+   * @returns {void}
+   * @throws {Error} If the underlying storage fails to delete the value
+   */
+  removeItem(name: string): void {
+    return this.storage.del(name)
+  }
+}

package/src/{lib → classes}/StyleRegistry.ts

@@ -1,17 +1,12 @@
 /* eslint-disable dot-notation */
-import { AnyRecord, AnyStyledComponent, ICSS, ITheme, StyleAggregator, StyleProp, VariantStyleSheet } from '../types'
-import { themeStore } from './themeStore'
-import deepmerge from '@fastify/deepmerge'
-import { MultiplierFunction } from './spacing'
-import { defaultVariants } from './defaultVariants'
-import { dynamicVariants } from './dynamicVariants'
-import { capitalize, ignoredStyleKeys, isSpacingKey } from './utils'
+import type { AnyRecord, AnyStyledComponent, ICSS, ITheme, StyleAggregator, StyleProp, VariantStyleSheet } from '../types'
+import type { StateStorage } from '../types/store'
+import type { MultiplierFunction } from '../variants'
+import { themeStore } from '../theme'
+import { defaultVariants, dynamicVariants } from '../variants'
+import { capitalize, ignoredStyleKeys, isSpacingKey } from '../utils'
 import { StyleCache } from './StyleCache'
-import { minifier } from './minifier'
-import rfdc from 'rfdc'
-import { StateStorage } from '../types/store'
-
-const deepClone = rfdc()
+import { minifier, deepClone, deepmerge } from '../tools'
 
 export class CodeleapStyleRegistry {
   stylesheets: Record<string, VariantStyleSheet> = {}

package/src/classes/index.ts

@@ -0,0 +1,2 @@
+export * from './StyleRegistry'
+export * from './StylePersistor'