@v-ibe/core 0.1.0

package/dist/custom-components/for.js

@@ -0,0 +1,313 @@
+import { effect } from "../reactivity/signals/effect.js";
+import { ReactiveArray } from "../reactivity/signals/reactive-array.js";
+import { CompositeSignal } from "../reactivity/signals/composite.js";
+function For(props) {
+  const container = document.createDocumentFragment();
+  const mainAnchor = document.createComment("for-list");
+  container.appendChild(mainAnchor);
+  const arrayState = {
+    keyMap: /* @__PURE__ */ new Map(),
+    nodeOrder: [],
+    reactiveEntries: /* @__PURE__ */ new Map()
+  };
+  const effectCleanups = /* @__PURE__ */ new Map();
+  const reactiveArray = unwrapReactiveArray(props.each);
+  if (reactiveArray) {
+    renderGranular(
+      mainAnchor,
+      reactiveArray,
+      props.children,
+      props.getKey,
+      props.fallback,
+      arrayState,
+      effectCleanups
+    );
+  } else {
+    renderStandard(
+      mainAnchor,
+      props.each,
+      props.children,
+      props.getKey,
+      props.fallback,
+      arrayState,
+      effectCleanups
+    );
+  }
+  return container;
+}
+function renderGranular(mainAnchor, reactiveArray, renderFn, getKey, fallback, arrayState, effectCleanups) {
+  console.log("[For] Using GRANULAR rendering (ReactiveArray detected)");
+  effect(() => {
+    const currentLength = reactiveArray.length;
+    console.log(`[For] Structural effect - length: ${currentLength}`);
+    if (currentLength === 0 && fallback) {
+      renderFallback(mainAnchor, arrayState, effectCleanups, fallback);
+      return;
+    }
+    if (currentLength > 0 && arrayState.nodeOrder.includes("__fallback__")) {
+      removeKey(arrayState, effectCleanups, "__fallback__");
+    }
+    const newNodeOrder = [];
+    const existingKeys = new Set(arrayState.nodeOrder);
+    for (let i = 0; i < currentLength; i++) {
+      const key = `__index_${i}`;
+      newNodeOrder.push(key);
+      if (!existingKeys.has(key)) {
+        createItemEffect(
+          mainAnchor,
+          arrayState,
+          effectCleanups,
+          key,
+          i,
+          reactiveArray,
+          renderFn,
+          getKey
+        );
+      }
+    }
+    for (const oldKey of existingKeys) {
+      if (!newNodeOrder.includes(oldKey)) {
+        removeKey(arrayState, effectCleanups, oldKey);
+      }
+    }
+    reorderNodes(mainAnchor, arrayState.keyMap, newNodeOrder);
+    arrayState.nodeOrder = newNodeOrder;
+  });
+}
+function renderStandard(mainAnchor, arraySource, renderFn, getKey, fallback, arrayState, effectCleanups) {
+  console.log("[For] Using STANDARD rendering (non-ReactiveArray)");
+  effect(() => {
+    const items = resolveArray(arraySource);
+    console.log(`[For] Standard effect - ${items.length} items`);
+    if (items.length === 0 && fallback) {
+      renderFallback(mainAnchor, arrayState, effectCleanups, fallback);
+      return;
+    }
+    if (items.length > 0 && arrayState.nodeOrder.includes("__fallback__")) {
+      removeKey(arrayState, effectCleanups, "__fallback__");
+    }
+    const newNodeOrder = [];
+    const usedNodes = /* @__PURE__ */ new Set();
+    items.forEach((item, index) => {
+      const key = extractKey(item, index, getKey);
+      newNodeOrder.push(key);
+      const renderedElement = renderFn(item, index);
+      let node = reuseOrCreateNode(
+        arrayState.keyMap,
+        key,
+        renderedElement
+      );
+      usedNodes.add(node);
+    });
+    removeUnusedNodes(arrayState.keyMap, usedNodes);
+    reorderNodes(mainAnchor, arrayState.keyMap, newNodeOrder);
+    arrayState.nodeOrder = newNodeOrder;
+  });
+}
+function createItemEffect(mainAnchor, arrayState, effectCleanups, key, index, reactiveArray, renderFn, getKey) {
+  console.log(`[For] Creating item effect for index ${index}`);
+  const anchor = document.createComment(`for-item-${key}`);
+  mainAnchor.parentNode?.appendChild(anchor);
+  const entry = {
+    anchor,
+    currentNode: null,
+    effectHandle: null
+  };
+  arrayState.reactiveEntries.set(key, entry);
+  const effectHandle = effect(() => {
+    console.log(`[For] Item effect running for index ${index}`);
+    let item = reactiveArray.at(index);
+    if (item && typeof item === "object" && item.isSignal) {
+      if (item instanceof CompositeSignal) {
+        item = item.getPlainValue();
+      }
+    }
+    if (item == null || typeof item === "boolean") {
+      if (entry.currentNode) {
+        entry.currentNode.parentNode?.removeChild(entry.currentNode);
+        entry.currentNode = null;
+        arrayState.keyMap.set(key, anchor);
+      }
+      return;
+    }
+    const renderedElement = renderFn(item, index);
+    const newNode = elementToNode(renderedElement);
+    if (entry.currentNode !== newNode) {
+      replaceNode(anchor, entry.currentNode, newNode);
+      entry.currentNode = newNode;
+      arrayState.keyMap.set(key, newNode);
+    }
+  });
+  entry.effectHandle = effectHandle;
+  effectCleanups.set(key, effectHandle.dispose);
+}
+function renderFallback(mainAnchor, arrayState, effectCleanups, fallback) {
+  if (arrayState.nodeOrder.includes("__fallback__")) {
+    return;
+  }
+  for (const key of arrayState.nodeOrder) {
+    removeKey(arrayState, effectCleanups, key);
+  }
+  const fallbackNode = elementToNode(fallback);
+  mainAnchor.parentNode?.insertBefore(fallbackNode, mainAnchor.nextSibling);
+  arrayState.keyMap.set("__fallback__", fallbackNode);
+  arrayState.nodeOrder = ["__fallback__"];
+}
+function removeKey(arrayState, effectCleanups, key) {
+  console.log(`[For] Removing key: ${key}`);
+  const cleanup = effectCleanups.get(key);
+  if (cleanup) {
+    cleanup();
+    effectCleanups.delete(key);
+  }
+  const entry = arrayState.reactiveEntries.get(key);
+  if (entry) {
+    if (entry.currentNode) {
+      entry.currentNode.parentNode?.removeChild(entry.currentNode);
+    }
+    if (entry.anchor && entry.anchor.parentNode) {
+      entry.anchor.parentNode.removeChild(entry.anchor);
+    }
+    arrayState.reactiveEntries.delete(key);
+  }
+  const node = arrayState.keyMap.get(key);
+  if (node && node.parentNode) {
+    node.parentNode.removeChild(node);
+  }
+  arrayState.keyMap.delete(key);
+}
+function reorderNodes(anchor, keyMap, newOrder) {
+  let previousNode = anchor;
+  newOrder.forEach((key) => {
+    const node = keyMap.get(key);
+    if (!node) return;
+    if (!node.parentNode) {
+      anchor.parentNode?.insertBefore(node, previousNode.nextSibling);
+    } else if (previousNode.nextSibling !== node) {
+      previousNode.parentNode?.insertBefore(node, previousNode.nextSibling);
+    }
+    previousNode = node;
+  });
+}
+function unwrapReactiveArray(source) {
+  if (source instanceof ReactiveArray) {
+    return source;
+  }
+  if (typeof source === "function") {
+    const value = source();
+    return unwrapReactiveArray(value);
+  }
+  if (source && typeof source === "object") {
+    const getReactive = source.__getReactiveArray;
+    if (getReactive instanceof ReactiveArray) {
+      return getReactive;
+    }
+    const internal = source.__reactiveArray__;
+    if (internal instanceof ReactiveArray) {
+      return internal;
+    }
+    const symbolKey = Symbol.for("reactiveArray");
+    const viaSymbol = source[symbolKey];
+    if (viaSymbol instanceof ReactiveArray) {
+      return viaSymbol;
+    }
+  }
+  if (source && typeof source === "object" && source.isSignal) {
+    const value = source.get();
+    return unwrapReactiveArray(value);
+  }
+  return null;
+}
+function resolveArray(source) {
+  if (source && typeof source === "object" && source.isSignal) {
+    const value = source.get();
+    return Array.isArray(value) ? value : [];
+  }
+  if (typeof source === "function") {
+    const value = source();
+    return Array.isArray(value) ? value : [];
+  }
+  if (Array.isArray(source)) {
+    return source;
+  }
+  return [];
+}
+function extractKey(item, index, getKey) {
+  if (getKey) {
+    return String(getKey(item, index));
+  }
+  if (item && typeof item === "object") {
+    const obj = item;
+    if (obj.id != null) return String(obj.id);
+    if (obj.key != null) return String(obj.key);
+    if (obj._id != null) return String(obj._id);
+    if (obj.uuid != null) return String(obj.uuid);
+  }
+  return `__index_${index}`;
+}
+function reuseOrCreateNode(keyMap, key, element) {
+  const existingNode = keyMap.get(key);
+  const newNode = elementToNode(element);
+  if (existingNode && existingNode.nodeName === newNode.nodeName) {
+    if (existingNode.nodeType === Node.TEXT_NODE && newNode.nodeType === Node.TEXT_NODE) {
+      existingNode.textContent = newNode.textContent;
+      return existingNode;
+    }
+    existingNode.parentNode?.replaceChild(newNode, existingNode);
+    keyMap.set(key, newNode);
+    return newNode;
+  }
+  keyMap.set(key, newNode);
+  return newNode;
+}
+function removeUnusedNodes(keyMap, usedNodes) {
+  for (const [key, node] of keyMap.entries()) {
+    if (!usedNodes.has(node)) {
+      node.parentNode?.removeChild(node);
+      keyMap.delete(key);
+    }
+  }
+}
+function elementToNode(element) {
+  if (element == null || typeof element === "boolean") {
+    return document.createTextNode("");
+  }
+  if (typeof element === "string" || typeof element === "number") {
+    return document.createTextNode(String(element));
+  }
+  if (element instanceof Node) {
+    return element;
+  }
+  if (typeof element === "function") {
+    const result = element();
+    return elementToNode(result);
+  }
+  if (element instanceof DocumentFragment) {
+    if (element.childNodes.length === 1) {
+      const child = element.firstChild;
+      element.removeChild(child);
+      return child;
+    }
+    const wrapper = document.createElement("span");
+    wrapper.style.display = "contents";
+    while (element.firstChild) {
+      wrapper.appendChild(element.firstChild);
+    }
+    return wrapper;
+  }
+  if (element && typeof element === "object") {
+    console.warn("[For] Received unknown object type:", element);
+    return document.createTextNode(JSON.stringify(element));
+  }
+  return document.createTextNode("");
+}
+function replaceNode(anchor, oldNode, newNode) {
+  if (oldNode) {
+    anchor.parentNode?.replaceChild(newNode, oldNode);
+  } else {
+    anchor.parentNode?.insertBefore(newNode, anchor.nextSibling);
+  }
+}
+export {
+  For
+};

package/dist/custom-components/index.d.ts

@@ -0,0 +1,2 @@
+export { For, type ForProps } from './for';
+export { Show, type ShowProps } from './show';

package/dist/custom-components/show.d.ts

@@ -0,0 +1,78 @@
+/**
+ * SHOW COMPONENT - Conditional Rendering with Untracked Children
+ *
+ * Este componente separa la evaluación de la condición del rendering del contenido,
+ * evitando loops infinitos cuando el hijo crea dependencias reactivas que invalidarían
+ * al padre.
+ *
+ * Características clave:
+ * - La condición `when` se evalúa CON tracking
+ * - El contenido `children` se ejecuta SIN tracking (untrack)
+ * - Previene loops infinitos en casos como RouteView anidados
+ * - Soporta fallback para el caso false
+ *
+ * Transformación JSX:
+ *   <Show when={() => condition}>{() => content}</Show>
+ *
+ * Compila a:
+ *   Show({ when: () => condition, children: () => content })
+ */
+/**
+ * Props del componente Show
+ */
+export interface ShowProps {
+    /**
+     * Condición reactiva a evaluar.
+     * Debe ser una función que retorne boolean.
+     * Esta función SE TRACKEA - cambios en sus dependencias re-evalúan el Show.
+     */
+    when: () => boolean;
+    /**
+     * Contenido a renderizar cuando la condición es true.
+     * Debe ser una función que retorne el contenido.
+     * Esta función NO SE TRACKEA - previene loops infinitos.
+     */
+    children: () => any;
+    /**
+     * Contenido a mostrar cuando la condición es false.
+     * Opcional. También se ejecuta sin tracking.
+     */
+    fallback?: () => any;
+}
+/**
+ * Show - Helper para rendering condicional sin loops
+ *
+ * @example Prevenir loop en RouteView
+ * ```tsx
+ * @Component
+ * class RouteView extends BaseComponent {
+ *   @Resource(...)
+ *   componentClass!: IResource<any>;
+ *
+ *   view() {
+ *     return (
+ *       <>
+ *         <Show when={() => this.componentClass.state === 'pending'}>
+ *           {() => <div>Loading...</div>}
+ *         </Show>
+ *
+ *         <Show when={() => this.componentClass.state === 'ready'}>
+ *           {() => this.jsx(this.componentClass.get(), {})}
+ *         </Show>
+ *       </>
+ *     );
+ *   }
+ * }
+ * ```
+ *
+ * @example Con fallback
+ * ```tsx
+ * <Show
+ *   when={() => this.user.isLoggedIn}
+ *   fallback={() => <LoginButton />}
+ * >
+ *   {() => <UserProfile user={this.user} />}
+ * </Show>
+ * ```
+ */
+export declare function Show(props: ShowProps): DocumentFragment;

package/dist/custom-components/show.js

@@ -0,0 +1,88 @@
+import { effect } from "../reactivity/signals/effect.js";
+import { reactiveContext } from "../reactivity/reactive-context.js";
+function Show(props) {
+  const container = document.createDocumentFragment();
+  const anchor = document.createComment("show");
+  container.appendChild(anchor);
+  let currentNode = null;
+  let currentBranch = "empty";
+  effect(() => {
+    if (!anchor.parentNode) {
+      return;
+    }
+    const condition = Boolean(props.when());
+    const shouldShowTruthy = condition;
+    const shouldShowFalsy = !shouldShowTruthy && props.fallback;
+    if (shouldShowTruthy) {
+      if (currentBranch === "truthy") {
+        return;
+      }
+      if (currentNode) {
+        anchor.parentNode?.removeChild(currentNode);
+      }
+      const content = reactiveContext.untrack(() => props.children());
+      const newNode = elementToNode(content);
+      anchor.parentNode?.insertBefore(newNode, anchor.nextSibling);
+      currentNode = newNode;
+      currentBranch = "truthy";
+    } else if (shouldShowFalsy) {
+      if (currentBranch === "falsy") {
+        return;
+      }
+      if (currentNode) {
+        anchor.parentNode?.removeChild(currentNode);
+      }
+      const content = reactiveContext.untrack(() => props.fallback());
+      const newNode = elementToNode(content);
+      anchor.parentNode?.insertBefore(newNode, anchor.nextSibling);
+      currentNode = newNode;
+      currentBranch = "falsy";
+    } else {
+      if (currentBranch === "empty") {
+        return;
+      }
+      if (currentNode) {
+        currentNode.parentNode?.removeChild(currentNode);
+        currentNode = null;
+      }
+      currentBranch = "empty";
+    }
+  });
+  return container;
+}
+function elementToNode(element) {
+  if (element == null || typeof element === "boolean") {
+    return document.createTextNode("");
+  }
+  if (typeof element === "string" || typeof element === "number") {
+    return document.createTextNode(String(element));
+  }
+  if (element instanceof Node) {
+    return element;
+  }
+  if (typeof element === "function") {
+    const result = element();
+    return elementToNode(result);
+  }
+  if (element instanceof DocumentFragment) {
+    if (element.childNodes.length === 1) {
+      const child = element.firstChild;
+      element.removeChild(child);
+      return child;
+    }
+    const wrapper = document.createElement("span");
+    wrapper.style.display = "contents";
+    while (element.firstChild) {
+      wrapper.appendChild(element.firstChild);
+    }
+    return wrapper;
+  }
+  if (element && typeof element === "object") {
+    console.warn("[Show] Received unknown object type:", element);
+    return document.createTextNode(JSON.stringify(element));
+  }
+  return document.createTextNode("");
+}
+export {
+  Show
+};

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

@@ -0,0 +1,35 @@
+import { CacheProvider } from './cache-provider.interface';
+export type Constructor<T> = new (...args: any[]) => T;
+export type TagExtractor = (result: any, args: any[]) => string[];
+/**
+ * @CacheInvalidate Decorator
+ *
+ * Invalida (elimina) las entradas del cache que coincidan con los tags extraídos del
+ * resultado de un método. Útil para limpiar el cache después de operaciones de
+ * escritura que afectan a múltiples entradas relacionadas.
+ *
+ * @param ProviderClass - La clase del cache provider a usar
+ * @param tagExtractor - Función que extrae tags del resultado y argumentos
+ *
+ * @example
+ * ```typescript
+ * @CacheInvalidate(
+ *   LocalStorageCache,
+ *   (result) => ['users-list', `org:${result.organizationId}`]
+ * )
+ * async deleteUser(userId: string): Promise<void> {
+ *   await this.httpClient.delete(`/users/${userId}`);
+ * }
+ * ```
+ *
+ * @example Combinar con @CacheUpdate
+ * ```typescript
+ * @CacheUpdate(LocalStorageCache, (result) => [`user:${result.id}`])
+ * @CacheInvalidate(LocalStorageCache, (result) => ['users-list', `org:${result.organizationId}`])
+ * async updateUser(id: string, data: any): Promise<User> {
+ *   const response = await this.httpClient.put(`/users/${id}`, data);
+ *   return response.data;
+ * }
+ * ```
+ */
+export declare function CacheInvalidate(ProviderClass: Constructor<CacheProvider>, tagExtractor: TagExtractor): (originalMethod: Function, context: ClassMethodDecoratorContext) => (this: any, ...args: any[]) => Promise<any>;

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

@@ -0,0 +1,21 @@
+function CacheInvalidate(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(`[CacheInvalidate] Provider ${ProviderClass.name} not found in DI container`);
+        return result;
+      }
+      const tags = tagExtractor(result, args);
+      if (!tags || tags.length === 0) {
+        return result;
+      }
+      provider.invalidateTags(tags);
+      return result;
+    };
+  };
+}
+export {
+  CacheInvalidate
+};

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

@@ -0,0 +1,15 @@
+import { Constructor } from '../../DI/types';
+import { CacheProvider } from './cache-provider.interface';
+import { TagExtractor } from './cache-tags.decorator';
+/**
+ * Metadata storage para cache decorators
+ * Usamos un WeakMap con el método como key para evitar colisiones
+ */
+interface CacheMethodMetadata {
+    cacheProviderClass?: Constructor<CacheProvider>;
+    tagExtractor?: TagExtractor;
+}
+export declare function setCacheProviderClass(method: Function, providerClass: Constructor<CacheProvider>): void;
+export declare function setTagExtractor(method: Function, extractor: TagExtractor): void;
+export declare function getCacheMetadata(method: Function): CacheMethodMetadata;
+export {};

package/dist/data-management/cache/cache-provider.interface.d.ts

@@ -0,0 +1,67 @@
+/**
+ * CACHE PROVIDER INTERFACE
+ *
+ * Todos los cache providers deben implementar esta interface.
+ */
+export interface CacheProvider {
+    /**
+     * Obtiene un valor del cache.
+     * @param key - La clave del cache
+     * @returns El valor cacheado o null si no existe o expiró
+     */
+    get<T>(key: string): T | null;
+    /**
+     * Almacena un valor en el cache con TTL.
+     * @param key - La clave del cache
+     * @param value - El valor a cachear
+     * @param ttl - Time-to-live en milisegundos
+     * @param tags - Tags para invalidación granular
+     */
+    set<T>(key: string, value: T, ttl: number, tags?: string[]): void;
+    /**
+     * Elimina una entrada específica del cache.
+     * @param key - La clave a eliminar
+     */
+    delete(key: string): void;
+    /**
+     * Elimina todas las entradas del cache.
+     */
+    clear(): void;
+    /**
+     * Elimina entradas que coincidan con un patrón.
+     * @param pattern - RegExp para matching de keys
+     */
+    invalidatePattern(pattern: RegExp): void;
+    /**
+     * Invalida todas las cache entries que tengan un tag específico.
+     * @param tag - El tag a invalidar
+     */
+    invalidateTag(tag: string): void;
+    /**
+     * Obtiene todas las cache keys que tienen un tag específico.
+     * @param tag - El tag a buscar
+     * @returns Array de cache keys que tienen ese tag
+     */
+    getKeysByTag(tag: string): string[];
+    /**
+     * Actualiza todas las cache entries que tengan cualquiera de los tags especificados.
+     * Preserva el TTL original de cada entrada.
+     * @param tags - Array de tags
+     * @param value - El nuevo valor a asignar
+     */
+    updateByTags<T>(tags: string[], value: T): void;
+    /**
+     * Invalida (elimina) todas las cache entries que tengan cualquiera de los tags especificados.
+     * @param tags - Array de tags a invalidar
+     */
+    invalidateTags(tags: string[]): void;
+}
+/**
+ * Estructura de una entrada en el cache.
+ */
+export interface CacheEntry<T> {
+    value: T;
+    timestamp: number;
+    ttl: number;
+    tags: string[];
+}

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

@@ -0,0 +1,52 @@
+/**
+ * @CacheTags DECORATOR
+ *
+ * Asigna tags a las cache entries para invalidación granular.
+ * Los tags se extraen del resultado del método o de sus argumentos.
+ */
+/**
+ * Función que extrae tags del resultado y/o argumentos del método.
+ *
+ * @param result - El valor retornado por el método
+ * @param args - Los argumentos con los que se llamó el método
+ * @returns Array de tags (strings)
+ */
+export type TagExtractor = (result: any, args: any[]) => string[];
+/**
+ * @CacheTags - Asigna tags a cache entries para invalidación granular
+ *
+ * Los tags permiten invalidar selectivamente entries relacionadas sin
+ * necesitar eventos o regenerar cache keys.
+ *
+ * @param extractor - Función que extrae tags del resultado/args
+ *
+ * @example
+ * // Tag basado en el resultado
+ * @CacheTags((result) => [`product:${result.id}`])
+ * async getProduct(id: string) { }
+ *
+ * @example
+ * // Tag basado en argumentos
+ * @CacheTags((_, args) => [`product:${args[0]}`])
+ * async getProduct(id: string) { }
+ *
+ * @example
+ * // Múltiples tags
+ * @CacheTags((result) => [
+ *   `product:${result.id}`,
+ *   `category:${result.category}`,
+ *   `brand:${result.brand}`
+ * ])
+ * async getProduct(id: string) { }
+ *
+ * @example
+ * // Tags de array de resultados
+ * @CacheTags((result) => result.map(p => `product:${p.id}`))
+ * async getProducts() { }
+ *
+ * @example
+ * // Invalidar por tag
+ * await productService.updateProduct(id, data);
+ * cache.invalidateTag(`product:${id}`);
+ */
+export declare function CacheTags(extractor: TagExtractor): (target: any, context: ClassMethodDecoratorContext) => void;

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

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