@v-ibe/core 0.1.0

package/dist/data-management/cache/cache-update.decorator.d.ts

@@ -0,0 +1,28 @@
+import { CacheProvider } from './cache-provider.interface';
+export type Constructor<T> = new (...args: any[]) => T;
+export type TagExtractor = (result: any, args: any[]) => string[];
+/**
+ * @CacheUpdate Decorator
+ *
+ * Actualiza las entradas del cache que coincidan con los tags extraídos del resultado
+ * de un método. Útil para mantener el cache sincronizado después de operaciones de
+ * actualización (PUT, PATCH, etc.).
+ *
+ * Preserva el TTL original de cada entrada del cache.
+ *
+ * @param ProviderClass - La clase del cache provider a usar
+ * @param tagExtractor - Función que extrae tags del resultado y argumentos
+ *
+ * @example
+ * ```typescript
+ * @CacheUpdate(
+ *   LocalStorageCache,
+ *   (result) => [`user:${result.id}`]
+ * )
+ * async updateUser(userId: string, data: any): Promise<User> {
+ *   const response = await this.httpClient.put(`/users/${userId}`, data);
+ *   return response.data;
+ * }
+ * ```
+ */
+export declare function CacheUpdate(ProviderClass: Constructor<CacheProvider>, tagExtractor: TagExtractor): (originalMethod: Function, context: ClassMethodDecoratorContext) => (this: any, ...args: any[]) => Promise<any>;

package/dist/data-management/cache/cache-update.decorator.js

@@ -0,0 +1,21 @@
+function CacheUpdate(ProviderClass, tagExtractor) {
+  return function(originalMethod, context) {
+    return async function(...args) {
+      const result = await originalMethod.apply(this, args);
+      const provider = this.__container.get(ProviderClass);
+      if (!provider) {
+        console.warn(`[CacheUpdate] Provider ${ProviderClass.name} not found in DI container`);
+        return result;
+      }
+      const tags = tagExtractor(result, args);
+      if (!tags || tags.length === 0) {
+        return result;
+      }
+      provider.updateByTags(tags, result);
+      return result;
+    };
+  };
+}
+export {
+  CacheUpdate
+};

package/dist/data-management/cache/cache.decorator.d.ts

@@ -0,0 +1,28 @@
+import { Constructor } from '../../DI/types';
+import { CacheProvider } from './cache-provider.interface';
+/**
+ * @Cache DECORATOR
+ *
+ * Define qué cache provider usar para un método.
+ * El provider debe estar decorado con @Service.
+ *
+ * Si no se especifica @Cache, se usa MemoryCache por defecto.
+ */
+/**
+ * @Cache - Define el provider de cache para un método
+ *
+ * @param ProviderClass - Clase del cache provider (debe tener @Service)
+ *
+ * @example
+ * // Cache en LocalStorage
+ * @Cache(LocalStorageCache)
+ * @TTL(5000)
+ * async getUserPreferences() { }
+ *
+ * @example
+ * // Cache en SessionStorage
+ * @Cache(SessionStorageCache)
+ * @TTL(3000)
+ * async getFilterState() { }
+ */
+export declare function Cache<T extends CacheProvider>(ProviderClass: Constructor<T>): (target: any, context: ClassMethodDecoratorContext) => void;

package/dist/data-management/cache/cache.decorator.js

@@ -0,0 +1,13 @@
+function Cache(ProviderClass) {
+  return function(target, context) {
+    const metadata = context.metadata;
+    const methodName = String(context.name);
+    if (!metadata.cacheProviders) {
+      metadata.cacheProviders = {};
+    }
+    metadata.cacheProviders[methodName] = ProviderClass;
+  };
+}
+export {
+  Cache
+};

package/dist/data-management/cache/index.d.ts

@@ -0,0 +1,11 @@
+export type { CacheProvider, CacheEntry } from './cache-provider.interface';
+export { MemoryCache } from './memory-cache';
+export { LocalStorageCache } from './local-storage-cache';
+export { SessionStorageCache } from './session-storage-cache';
+export { Cache } from './cache.decorator';
+export { TTL } from './ttl.decorator';
+export { CacheTags } from './cache-tags.decorator';
+export type { TagExtractor } from './cache-tags.decorator';
+export { getCacheMetadata, setCacheProviderClass, setTagExtractor } from './cache-metadata';
+export { CacheUpdate } from './cache-update.decorator';
+export { CacheInvalidate } from './cache-invalidate.decorator';

package/dist/data-management/cache/local-storage-cache.d.ts

@@ -0,0 +1,40 @@
+import { CacheProvider, CacheEntry } from './cache-provider.interface';
+/**
+ * LOCALSTORAGE CACHE PROVIDER
+ *
+ * Provider de cache en LocalStorage.
+ *
+ * CARACTERÍSTICAS:
+ * - Persistente (sobrevive recargas y cierres de navegador)
+ * - Límite ~5-10MB (depende del navegador)
+ * - Sincrónico (puede bloquear si hay mucha data)
+ * - Ideal para: preferencias de usuario, datos que persisten entre sesiones
+ *
+ * IMPORTANTE: Los datos deben ser serializables a JSON.
+ */
+export declare class LocalStorageCache implements CacheProvider {
+    private readonly prefix;
+    private readonly tagIndexKey;
+    get tagIndex(): Map<string, Set<string>>;
+    get cache(): Map<string, CacheEntry<any>>;
+    private getStorageKey;
+    private getTagIndex;
+    private saveTagIndex;
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T, ttl: number, tags?: string[]): void;
+    delete(key: string): void;
+    clear(): void;
+    invalidatePattern(pattern: RegExp): void;
+    invalidateTag(tag: string): void;
+    getKeysByTag(tag: string): string[];
+    updateByTags<T>(tags: string[], value: T): void;
+    invalidateTags(tags: string[]): void;
+    /**
+     * Limpia entradas expiradas (útil para liberar espacio).
+     */
+    clearExpired(): void;
+    /**
+     * Lifecycle hook - se ejecuta cuando el container se destruye
+     */
+    onDestroy(): void;
+}

package/dist/data-management/cache/local-storage-cache.js

@@ -0,0 +1,268 @@
+import { Service } from "../../DI/decorators/service.js";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __decoratorStart = (base) => [, , , __create(null)];
+var __decoratorStrings = ["class", "method", "getter", "setter", "accessor", "field", "value", "get", "set"];
+var __expectFn = (fn) => fn !== void 0 && typeof fn !== "function" ? __typeError("Function expected") : fn;
+var __decoratorContext = (kind, name, done, metadata, fns) => ({ kind: __decoratorStrings[kind], name, metadata, addInitializer: (fn) => done._ ? __typeError("Already initialized") : fns.push(__expectFn(fn || null)) });
+var __decoratorMetadata = (array, target) => __defNormalProp(target, __knownSymbol("metadata"), array[3]);
+var __runInitializers = (array, flags, self, value) => {
+  for (var i = 0, fns = array[flags >> 1], n = fns && fns.length; i < n; i++) fns[i].call(self);
+  return value;
+};
+var __decorateElement = (array, flags, name, decorators, target, extra) => {
+  var it, done, ctx, k = flags & 7, p = false;
+  var j = 0;
+  var extraInitializers = array[j] || (array[j] = []);
+  var desc = k && (target = target.prototype, k < 5 && (k > 3 || !p) && __getOwnPropDesc(target, name));
+  __name(target, name);
+  for (var i = decorators.length - 1; i >= 0; i--) {
+    ctx = __decoratorContext(k, name, done = {}, array[3], extraInitializers);
+    it = (0, decorators[i])(target, ctx), done._ = 1;
+    __expectFn(it) && (target = it);
+  }
+  return __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
+};
+var _LocalStorageCache_decorators, _init;
+_LocalStorageCache_decorators = [Service];
+class LocalStorageCache {
+  constructor() {
+    this.prefix = "cache";
+    this.tagIndexKey = "cache:tagIndex";
+  }
+  // Exposed for CacheUpdate decorator
+  get tagIndex() {
+    return this.getTagIndex();
+  }
+  // Exposed for CacheUpdate decorator  
+  get cache() {
+    const cacheMap = /* @__PURE__ */ new Map();
+    for (let i = 0; i < localStorage.length; i++) {
+      const storageKey = localStorage.key(i);
+      if (storageKey && storageKey.startsWith(`${this.prefix}:`)) {
+        try {
+          const item = localStorage.getItem(storageKey);
+          if (item) {
+            const key = storageKey.substring(this.prefix.length + 1);
+            cacheMap.set(key, JSON.parse(item));
+          }
+        } catch (error) {
+        }
+      }
+    }
+    return cacheMap;
+  }
+  getStorageKey(key) {
+    return `${this.prefix}:${key}`;
+  }
+  getTagIndex() {
+    try {
+      const data = localStorage.getItem(this.tagIndexKey);
+      if (!data) {
+        return /* @__PURE__ */ new Map();
+      }
+      const parsed = JSON.parse(data);
+      return new Map(
+        Object.entries(parsed).map(([tag, keys]) => [tag, new Set(keys)])
+      );
+    } catch {
+      return /* @__PURE__ */ new Map();
+    }
+  }
+  saveTagIndex(tagIndex) {
+    try {
+      const obj = {};
+      tagIndex.forEach((keys, tag) => {
+        obj[tag] = Array.from(keys);
+      });
+      localStorage.setItem(this.tagIndexKey, JSON.stringify(obj));
+    } catch (error) {
+      console.error("[LocalStorageCache] Error saving tag index:", error);
+    }
+  }
+  get(key) {
+    try {
+      const storageKey = this.getStorageKey(key);
+      const item = localStorage.getItem(storageKey);
+      if (!item) {
+        return null;
+      }
+      const entry = JSON.parse(item);
+      const now = Date.now();
+      const age = now - entry.timestamp;
+      if (age > entry.ttl) {
+        this.delete(key);
+        return null;
+      }
+      return entry.value;
+    } catch (error) {
+      console.error("[LocalStorageCache] Error getting item:", error);
+      return null;
+    }
+  }
+  set(key, value, ttl, tags = []) {
+    try {
+      const storageKey = this.getStorageKey(key);
+      const entry = {
+        value,
+        timestamp: Date.now(),
+        ttl,
+        tags
+      };
+      const serialized = JSON.stringify(entry);
+      localStorage.setItem(storageKey, serialized);
+      if (tags.length > 0) {
+        const tagIndex = this.getTagIndex();
+        tags.forEach((tag) => {
+          if (!tagIndex.has(tag)) {
+            tagIndex.set(tag, /* @__PURE__ */ new Set());
+          }
+          tagIndex.get(tag).add(key);
+        });
+        this.saveTagIndex(tagIndex);
+      }
+    } catch (error) {
+      console.error("[LocalStorageCache] Error setting item:", error);
+      this.clearExpired();
+    }
+  }
+  delete(key) {
+    try {
+      const storageKey = this.getStorageKey(key);
+      const item = localStorage.getItem(storageKey);
+      if (item) {
+        const entry = JSON.parse(item);
+        if (entry.tags && entry.tags.length > 0) {
+          const tagIndex = this.getTagIndex();
+          entry.tags.forEach((tag) => {
+            tagIndex.get(tag)?.delete(key);
+            if (tagIndex.get(tag)?.size === 0) {
+              tagIndex.delete(tag);
+            }
+          });
+          this.saveTagIndex(tagIndex);
+        }
+      }
+      localStorage.removeItem(storageKey);
+    } catch (error) {
+      console.error("[LocalStorageCache] Error deleting item:", error);
+    }
+  }
+  clear() {
+    const keysToRemove = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (key && key.startsWith(`${this.prefix}:`)) {
+        keysToRemove.push(key);
+      }
+    }
+    keysToRemove.forEach((key) => localStorage.removeItem(key));
+    localStorage.removeItem(this.tagIndexKey);
+  }
+  invalidatePattern(pattern) {
+    const keysToRemove = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const storageKey = localStorage.key(i);
+      if (storageKey && storageKey.startsWith(`${this.prefix}:`)) {
+        const key = storageKey.substring(this.prefix.length + 1);
+        if (pattern.test(key)) {
+          keysToRemove.push(key);
+        }
+      }
+    }
+    keysToRemove.forEach((key) => this.delete(key));
+  }
+  invalidateTag(tag) {
+    const tagIndex = this.getTagIndex();
+    const keysToInvalidate = tagIndex.get(tag);
+    if (!keysToInvalidate) {
+      return;
+    }
+    const keys = Array.from(keysToInvalidate);
+    keys.forEach((key) => this.delete(key));
+  }
+  getKeysByTag(tag) {
+    const tagIndex = this.getTagIndex();
+    const keys = tagIndex.get(tag);
+    return keys ? Array.from(keys) : [];
+  }
+  updateByTags(tags, value) {
+    const tagIndex = this.getTagIndex();
+    const keysToUpdate = /* @__PURE__ */ new Set();
+    tags.forEach((tag) => {
+      const keys = tagIndex.get(tag);
+      if (keys) {
+        keys.forEach((key) => keysToUpdate.add(key));
+      }
+    });
+    keysToUpdate.forEach((key) => {
+      const storageKey = this.getStorageKey(key);
+      const item = localStorage.getItem(storageKey);
+      if (item) {
+        try {
+          const fullEntry = JSON.parse(item);
+          this.set(key, value, fullEntry.ttl, fullEntry.tags);
+        } catch (error) {
+          console.error(`[LocalStorageCache] Error parsing entry for ${key}:`, error);
+        }
+      }
+    });
+  }
+  invalidateTags(tags) {
+    const tagIndex = this.getTagIndex();
+    const keysToInvalidate = /* @__PURE__ */ new Set();
+    tags.forEach((tag) => {
+      const keys = tagIndex.get(tag);
+      if (keys) {
+        keys.forEach((key) => keysToInvalidate.add(key));
+      }
+    });
+    keysToInvalidate.forEach((key) => this.delete(key));
+  }
+  /**
+   * Limpia entradas expiradas (útil para liberar espacio).
+   */
+  clearExpired() {
+    const now = Date.now();
+    const keysToRemove = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const storageKey = localStorage.key(i);
+      if (storageKey && storageKey.startsWith(`${this.prefix}:`)) {
+        try {
+          const item = localStorage.getItem(storageKey);
+          if (item) {
+            const entry = JSON.parse(item);
+            const age = now - entry.timestamp;
+            if (age > entry.ttl) {
+              const key = storageKey.substring(this.prefix.length + 1);
+              keysToRemove.push(key);
+            }
+          }
+        } catch (error) {
+          const key = storageKey.substring(this.prefix.length + 1);
+          keysToRemove.push(key);
+        }
+      }
+    }
+    keysToRemove.forEach((key) => this.delete(key));
+  }
+  /**
+   * Lifecycle hook - se ejecuta cuando el container se destruye
+   */
+  onDestroy() {
+    this.clearExpired();
+  }
+}
+_init = __decoratorStart();
+LocalStorageCache = __decorateElement(_init, 0, "LocalStorageCache", _LocalStorageCache_decorators, LocalStorageCache);
+__runInitializers(_init, 1, LocalStorageCache);
+export {
+  LocalStorageCache
+};

package/dist/data-management/cache/memory-cache.d.ts

@@ -0,0 +1,37 @@
+import { CacheProvider, CacheEntry } from './cache-provider.interface';
+/**
+ * MEMORY CACHE PROVIDER
+ *
+ * Provider de cache en memoria (RAM).
+ *
+ * CARACTERÍSTICAS:
+ * - Rápido (acceso directo a Map)
+ * - No persistente (se pierde al recargar)
+ * - Ideal para: datos temporales, sesión actual
+ *
+ * Este es el provider por defecto cuando no se especifica @Cache.
+ */
+export declare class MemoryCache implements CacheProvider {
+    cache: Map<string, CacheEntry<any>>;
+    tagIndex: Map<string, Set<string>>;
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T, ttl: number, tags?: string[]): void;
+    delete(key: string): void;
+    clear(): void;
+    invalidatePattern(pattern: RegExp): void;
+    invalidateTag(tag: string): void;
+    getKeysByTag(tag: string): string[];
+    updateByTags<T>(tags: string[], value: T): void;
+    invalidateTags(tags: string[]): void;
+    /**
+     * Método de utilidad para debugging.
+     */
+    getStats(): {
+        size: number;
+        keys: string[];
+    };
+    /**
+     * Lifecycle hook - se ejecuta cuando el container se destruye
+     */
+    onDestroy(): void;
+}

package/dist/data-management/cache/memory-cache.js

@@ -0,0 +1,149 @@
+import { Service } from "../../DI/decorators/service.js";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __decoratorStart = (base) => [, , , __create(null)];
+var __decoratorStrings = ["class", "method", "getter", "setter", "accessor", "field", "value", "get", "set"];
+var __expectFn = (fn) => fn !== void 0 && typeof fn !== "function" ? __typeError("Function expected") : fn;
+var __decoratorContext = (kind, name, done, metadata, fns) => ({ kind: __decoratorStrings[kind], name, metadata, addInitializer: (fn) => done._ ? __typeError("Already initialized") : fns.push(__expectFn(fn || null)) });
+var __decoratorMetadata = (array, target) => __defNormalProp(target, __knownSymbol("metadata"), array[3]);
+var __runInitializers = (array, flags, self, value) => {
+  for (var i = 0, fns = array[flags >> 1], n = fns && fns.length; i < n; i++) fns[i].call(self);
+  return value;
+};
+var __decorateElement = (array, flags, name, decorators, target, extra) => {
+  var it, done, ctx, k = flags & 7, p = false;
+  var j = 0;
+  var extraInitializers = array[j] || (array[j] = []);
+  var desc = k && (target = target.prototype, k < 5 && (k > 3 || !p) && __getOwnPropDesc(target, name));
+  __name(target, name);
+  for (var i = decorators.length - 1; i >= 0; i--) {
+    ctx = __decoratorContext(k, name, done = {}, array[3], extraInitializers);
+    it = (0, decorators[i])(target, ctx), done._ = 1;
+    __expectFn(it) && (target = it);
+  }
+  return __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
+};
+var _MemoryCache_decorators, _init;
+_MemoryCache_decorators = [Service];
+class MemoryCache {
+  constructor() {
+    this.cache = /* @__PURE__ */ new Map();
+    this.tagIndex = /* @__PURE__ */ new Map();
+  }
+  // tag → cache keys
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      return null;
+    }
+    const now = Date.now();
+    const age = now - entry.timestamp;
+    if (age > entry.ttl) {
+      this.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+  set(key, value, ttl, tags = []) {
+    this.cache.set(key, {
+      value,
+      timestamp: Date.now(),
+      ttl,
+      tags
+    });
+    tags.forEach((tag) => {
+      if (!this.tagIndex.has(tag)) {
+        this.tagIndex.set(tag, /* @__PURE__ */ new Set());
+      }
+      this.tagIndex.get(tag).add(key);
+    });
+  }
+  delete(key) {
+    const entry = this.cache.get(key);
+    if (entry) {
+      entry.tags.forEach((tag) => {
+        this.tagIndex.get(tag)?.delete(key);
+        if (this.tagIndex.get(tag)?.size === 0) {
+          this.tagIndex.delete(tag);
+        }
+      });
+    }
+    this.cache.delete(key);
+  }
+  clear() {
+    this.cache.clear();
+    this.tagIndex.clear();
+  }
+  invalidatePattern(pattern) {
+    for (const key of this.cache.keys()) {
+      if (pattern.test(key)) {
+        this.delete(key);
+      }
+    }
+  }
+  invalidateTag(tag) {
+    const keysToInvalidate = this.tagIndex.get(tag);
+    if (!keysToInvalidate) {
+      return;
+    }
+    const keys = Array.from(keysToInvalidate);
+    keys.forEach((key) => this.delete(key));
+  }
+  getKeysByTag(tag) {
+    const keys = this.tagIndex.get(tag);
+    return keys ? Array.from(keys) : [];
+  }
+  updateByTags(tags, value) {
+    const keysToUpdate = /* @__PURE__ */ new Set();
+    tags.forEach((tag) => {
+      const keys = this.tagIndex.get(tag);
+      if (keys) {
+        keys.forEach((key) => keysToUpdate.add(key));
+      }
+    });
+    keysToUpdate.forEach((key) => {
+      const entry = this.cache.get(key);
+      if (entry) {
+        this.set(key, value, entry.ttl, entry.tags);
+      }
+    });
+  }
+  invalidateTags(tags) {
+    const keysToInvalidate = /* @__PURE__ */ new Set();
+    tags.forEach((tag) => {
+      const keys = this.tagIndex.get(tag);
+      if (keys) {
+        keys.forEach((key) => keysToInvalidate.add(key));
+      }
+    });
+    keysToInvalidate.forEach((key) => this.delete(key));
+  }
+  /**
+   * Método de utilidad para debugging.
+   */
+  getStats() {
+    return {
+      size: this.cache.size,
+      keys: Array.from(this.cache.keys())
+    };
+  }
+  /**
+   * Lifecycle hook - se ejecuta cuando el container se destruye
+   */
+  onDestroy() {
+    this.clear();
+  }
+}
+_init = __decoratorStart();
+MemoryCache = __decorateElement(_init, 0, "MemoryCache", _MemoryCache_decorators, MemoryCache);
+__runInitializers(_init, 1, MemoryCache);
+export {
+  MemoryCache
+};

package/dist/data-management/cache/session-storage-cache.d.ts

@@ -0,0 +1,35 @@
+import { CacheProvider } from './cache-provider.interface';
+/**
+ * SESSIONSTORAGE CACHE PROVIDER
+ *
+ * Provider de cache en SessionStorage.
+ *
+ * CARACTERÍSTICAS:
+ * - Persistente solo durante la sesión del navegador
+ * - Se limpia al cerrar la pestaña/ventana
+ * - Límite ~5-10MB (depende del navegador)
+ * - Ideal para: datos temporales de la sesión, estado de UI
+ *
+ * IMPORTANTE: Los datos deben ser serializables a JSON.
+ */
+export declare class SessionStorageCache implements CacheProvider {
+    private readonly prefix;
+    private readonly tagIndexKey;
+    private getStorageKey;
+    private getTagIndex;
+    private saveTagIndex;
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T, ttl: number, tags?: string[]): void;
+    delete(key: string): void;
+    clear(): void;
+    invalidatePattern(pattern: RegExp): void;
+    invalidateTag(tag: string): void;
+    getKeysByTag(tag: string): string[];
+    updateByTags<T>(tags: string[], value: T): void;
+    invalidateTags(tags: string[]): void;
+    clearExpired(): void;
+    /**
+     * Lifecycle hook - se ejecuta cuando el container se destruye
+     */
+    onDestroy(): void;
+}