@v-ibe/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Julian Vargas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# v-ibe
+
+Modern framework for single page applications.
+
+> **Alpha** — Core is stable but the API may change before 1.0. Not recommended for production yet.
+
+---
+
+**v-ibe** is an opinionated front-end framework for building SPAs using persistent class-based components, signals, and direct DOM updates. No virtual DOM, no hooks, no re-renders.
+
+## Hello World
+
+```typescript
+@Component()
+export class HelloWorld extends BaseComponent {
+  @State name = 'World';
+
+  view() {
+    return (
+      <h1 onClick={() => this.name = 'Signals'}>
+        Hello {this.name}
+      </h1>
+    );
+  }
+}
+```
+
+## Installation
+
+```bash
+npm install @v-ibe/core
+```
+
+## Documentation
+
+[https://v-ibe.com](https://v-ibe.com)
+
+## License
+
+MIT

package/dist/DI/__tests__/scoped-container-dependencies.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/DI/bootstrap.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Bootstrap function to register all services marked with @Service decorator
+ * and initialize them in topological order.
+ *
+ * This should be called once at application startup, before rendering components.
+ *
+ * @example
+ * ```typescript
+ * import { bootstrap } from './framework';
+ *
+ * // Register all services and bootstrap
+ * await bootstrap();
+ *
+ * // Now render your app
+ * document.getElementById('root')!.innerHTML = '<my-app></my-app>';
+ * ```
+ */
+export declare function bootstrap(): Promise<void>;

package/dist/DI/decorators/inject.d.ts

@@ -0,0 +1,37 @@
+import { Constructor } from '../types';
+/**
+ * Decorator to inject a service dependency from the global DI container
+ *
+ * Works by creating a lazy getter that retrieves the service from the container
+ * associated with the instance. The value is cached after first access.
+ *
+ * @param ctor - Constructor of the service to inject
+ *
+ * @example In a service
+ * ```typescript
+ * @Service
+ * class AuthService {
+ *   @Inject(HttpClient) http!: HttpClient;
+ *   @Inject(ConfigService) config!: ConfigService;
+ *
+ *   async login(credentials: Credentials) {
+ *     const url = this.config.getApiUrl();
+ *     return this.http.post(url, credentials);
+ *   }
+ * }
+ * ```
+ *
+ * @example In a component
+ * ```typescript
+ * @Component
+ * class MyComponent extends BaseComponent {
+ *   @Inject(Router) router!: Router;
+ *   @Inject(AuthService) auth!: AuthService;
+ *
+ *   view() {
+ *     return <div>Usuario: {this.auth.currentUser}</div>;
+ *   }
+ * }
+ * ```
+ */
+export declare function Inject(ctor: Constructor): (_: undefined, ctx: ClassFieldDecoratorContext) => void;

package/dist/DI/decorators/inject.js

@@ -0,0 +1,45 @@
+import { DEPENDENCIES_KEY } from "./service.js";
+function Inject(ctor) {
+  return function(_, ctx) {
+    if (ctx.kind !== "field") {
+      throw new Error("@Inject solo puede usarse en fields");
+    }
+    if (!ctx.metadata[DEPENDENCIES_KEY]) {
+      ctx.metadata[DEPENDENCIES_KEY] = /* @__PURE__ */ new Set();
+    }
+    ctx.metadata[DEPENDENCIES_KEY].add(ctor);
+    ctx.addInitializer(function() {
+      const privateKey = Symbol(`__injected_${String(ctx.name)}`);
+      Object.defineProperty(this, ctx.name, {
+        enumerable: true,
+        configurable: true,
+        get() {
+          if (this[privateKey]) {
+            return this[privateKey];
+          }
+          const container = this.__container;
+          if (!container) {
+            throw new Error(
+              `@Inject(${ctor.name}): No container found on ${this.constructor?.name || "unknown"}. Ensure this instance is within a component tree that provides ${ctor.name}.`
+            );
+          }
+          const inst = container.get(ctor);
+          Object.defineProperty(this, ctx.name, {
+            value: inst,
+            writable: true,
+            // ← Permitir override en tests
+            configurable: true
+            // ← Permitir redefinir en tests
+          });
+          return inst;
+        },
+        set(value) {
+          this[privateKey] = value;
+        }
+      });
+    });
+  };
+}
+export {
+  Inject
+};

package/dist/DI/decorators/service.d.ts

@@ -0,0 +1,24 @@
+import { Constructor } from '../types';
+declare const DEPENDENCIES_KEY: unique symbol;
+/**
+ * Decorator to mark a class as a Service
+ * Only stores metadata - actual registration happens when container is created
+ * All services are bootstrapped eagerly during container bootstrap
+ *
+ * @example
+ * ```typescript
+ * @Service
+ * class AuthService {
+ *   @Inject(HttpClient) http!: HttpClient;
+ *
+ *   async login(credentials: Credentials) {
+ *     return this.http.post('/auth/login', credentials);
+ *   }
+ * }
+ * ```
+ */
+export declare function Service<T extends Constructor>(ctor: T, ctx: ClassDecoratorContext): T;
+/**
+ * Export the dependencies key for use by @Inject decorator
+ */
+export { DEPENDENCIES_KEY };

package/dist/DI/decorators/service.js

@@ -0,0 +1,13 @@
+import { registerServiceMetadata } from "../service-metadata.js";
+const DEPENDENCIES_KEY = Symbol("dependencies");
+function Service(ctor, ctx) {
+  const dependencies = ctx.metadata[DEPENDENCIES_KEY];
+  registerServiceMetadata(ctor, {
+    dependencies: dependencies || /* @__PURE__ */ new Set()
+  });
+  return ctor;
+}
+export {
+  DEPENDENCIES_KEY,
+  Service
+};

package/dist/DI/di-container.d.ts

@@ -0,0 +1,53 @@
+import { Constructor } from './types';
+/**
+ * Singleton global dependency injection container
+ *
+ * Uses topological sort (Kahn's algorithm) to bootstrap services in correct dependency order.
+ * All services are eagerly initialized during bootstrap.
+ */
+export declare class DIContainer {
+    #private;
+    /**
+     * Register a service constructor
+     */
+    register(token: Constructor): void;
+    /**
+     * Register a dependency relationship between services
+     * @param parent - The service that depends on another
+     * @param dependency - The service that parent depends on
+     */
+    registerDependency(parent: Constructor, dependency: Constructor): void;
+    /**
+     * Bootstrap all services in dependency order
+     * All services are eagerly initialized during bootstrap
+     * Each instance is associated with this container for property injection
+     */
+    bootstrap(): Promise<void>;
+    /**
+     * Get the container associated with an instance
+     * Useful for property injection (fallback for @Inject)
+     */
+    static getContainerForInstance(instance: any): DIContainer | undefined;
+    /**
+     * Get a service instance
+     * All services must be bootstrapped before calling get()
+     */
+    get<T>(ctor: Constructor<T>): T;
+    /**
+     * Get all service instances
+     * Useful for collecting metadata from all services after bootstrap
+     */
+    getAllInstances(): any[];
+    /**
+     * Check if bootstrap has been called
+     */
+    get isReady(): boolean;
+    /**
+     * Dispose all services and reset container
+     */
+    dispose(): void;
+}
+/**
+ * Global singleton container instance
+ */
+export declare const services: DIContainer;

package/dist/DI/di-container.js

@@ -0,0 +1,158 @@
+import { hasLifecycle } from "./lifecycle.js";
+class DIContainer {
+  #singletons = /* @__PURE__ */ new Map();
+  #registered = /* @__PURE__ */ new Set();
+  // Dependency graph for topological sort
+  #dependencies = /* @__PURE__ */ new Map();
+  // What each service depends on
+  #dependents = /* @__PURE__ */ new Map();
+  // What depends on each service
+  #ready = false;
+  /**
+   * Register a service constructor
+   */
+  register(token) {
+    this.#registered.add(token);
+    if (!this.#dependencies.has(token)) {
+      this.#dependencies.set(token, /* @__PURE__ */ new Set());
+    }
+    if (!this.#dependents.has(token)) {
+      this.#dependents.set(token, /* @__PURE__ */ new Set());
+    }
+  }
+  /**
+   * Register a dependency relationship between services
+   * @param parent - The service that depends on another
+   * @param dependency - The service that parent depends on
+   */
+  registerDependency(parent, dependency) {
+    if (!this.#registered.has(parent)) {
+      throw new Error(
+        `Cannot register dependency: ${parent.name} is not registered. Use @Service decorator first.`
+      );
+    }
+    if (!this.#registered.has(dependency)) {
+      throw new Error(
+        `Cannot register dependency: ${dependency.name} is not registered. Use @Service decorator first.`
+      );
+    }
+    if (!this.#dependencies.has(parent)) {
+      this.#dependencies.set(parent, /* @__PURE__ */ new Set());
+    }
+    this.#dependencies.get(parent).add(dependency);
+    if (!this.#dependents.has(dependency)) {
+      this.#dependents.set(dependency, /* @__PURE__ */ new Set());
+    }
+    this.#dependents.get(dependency).add(parent);
+  }
+  /**
+   * Get bootstrap order using topological sort (Kahn's algorithm)
+   * This ensures dependencies are initialized before dependents
+   */
+  async *#getBootstrapOrder() {
+    const inDegree = /* @__PURE__ */ new Map();
+    const queue = [];
+    for (const service of this.#registered) {
+      const deps = this.#dependencies.get(service) || /* @__PURE__ */ new Set();
+      inDegree.set(service, deps.size);
+      if (deps.size === 0) {
+        queue.push(service);
+      }
+    }
+    while (queue.length > 0) {
+      const service = queue.shift();
+      yield service;
+      const dependents = this.#dependents.get(service) || /* @__PURE__ */ new Set();
+      for (const dependent of dependents) {
+        const newInDegree = inDegree.get(dependent) - 1;
+        inDegree.set(dependent, newInDegree);
+        if (newInDegree === 0) {
+          queue.push(dependent);
+        }
+      }
+    }
+    const remaining = Array.from(inDegree.entries()).filter(
+      ([_, degree]) => degree > 0
+    );
+    if (remaining.length > 0) {
+      const cycleServices = remaining.map(([service]) => service.name).join(", ");
+      throw new Error(
+        `Circular dependency detected. Services with unresolved dependencies: ${cycleServices}`
+      );
+    }
+  }
+  /**
+   * Bootstrap all services in dependency order
+   * All services are eagerly initialized during bootstrap
+   * Each instance is associated with this container for property injection
+   */
+  async bootstrap() {
+    if (this.#ready) return;
+    for await (const ctor of this.#getBootstrapOrder()) {
+      const inst = new ctor();
+      inst.__container = this;
+      this.#singletons.set(ctor, inst);
+      if (hasLifecycle(inst)) {
+        await inst.onBootstrap();
+      }
+    }
+    this.#ready = true;
+  }
+  /**
+   * Get the container associated with an instance
+   * Useful for property injection (fallback for @Inject)
+   */
+  static getContainerForInstance(instance) {
+    return instance.__container;
+  }
+  /**
+   * Get a service instance
+   * All services must be bootstrapped before calling get()
+   */
+  get(ctor) {
+    if (!this.#registered.has(ctor)) {
+      throw new Error(`Service not registered: ${ctor.name}`);
+    }
+    if (!this.#singletons.has(ctor)) {
+      throw new Error(
+        `Service ${ctor.name} not found in singletons. Make sure bootstrap() has been called.`
+      );
+    }
+    return this.#singletons.get(ctor);
+  }
+  /**
+   * Get all service instances
+   * Useful for collecting metadata from all services after bootstrap
+   */
+  getAllInstances() {
+    return Array.from(this.#singletons.values());
+  }
+  /**
+   * Check if bootstrap has been called
+   */
+  get isReady() {
+    return this.#ready;
+  }
+  /**
+   * Dispose all services and reset container
+   */
+  dispose() {
+    for (const instance of this.#singletons.values()) {
+      if (typeof instance.onDestroy === "function") {
+        try {
+          instance.onDestroy();
+        } catch (error) {
+          console.error("[DIContainer] Error en onDestroy:", error);
+        }
+      }
+    }
+    this.#singletons.clear();
+    this.#registered.clear();
+    this.#dependencies.clear();
+    this.#dependents.clear();
+    this.#ready = false;
+  }
+}
+export {
+  DIContainer
+};

package/dist/DI/lifecycle.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Interfaz para servicios que requieren inicialización asíncrona
+ *
+ * Los servicios que implementan esta interfaz tendrán su método onBootstrap
+ * llamado automáticamente cuando el componente que los provee se monte.
+ *
+ * @example
+ * ```typescript
+ * class Router implements LifeCycle {
+ *   async onBootstrap() {
+ *     await this.loadRoutes();
+ *     console.log('Router initialized');
+ *   }
+ * }
+ * ```
+ */
+export interface LifeCycle {
+    /**
+     * Método llamado automáticamente durante el bootstrap del componente
+     * Permite inicialización asíncrona como cargar configuración, conectar a APIs, etc.
+     */
+    onBootstrap(): Promise<void>;
+}
+/**
+ * Type guard para verificar si un objeto implementa la interfaz LifeCycle
+ *
+ * @param obj - Objeto a verificar
+ * @returns true si el objeto tiene un método onBootstrap que es una función
+ *
+ * @example
+ * ```typescript
+ * if (hasLifecycle(service)) {
+ *   await service.onBootstrap();
+ * }
+ * ```
+ */
+export declare function hasLifecycle(obj: any): obj is LifeCycle;

package/dist/DI/lifecycle.js

@@ -0,0 +1,6 @@
+function hasLifecycle(obj) {
+  return obj != null && typeof obj.onBootstrap === "function";
+}
+export {
+  hasLifecycle
+};

package/dist/DI/scoped-container.d.ts

@@ -0,0 +1,68 @@
+import { Constructor } from './types';
+/**
+ * Hierarchical DI container that supports parent-chain resolution.
+ *
+ * Each component with `services: [...]` in its @Component config
+ * gets a ScopedContainer. Services not found locally are resolved
+ * by walking up the parent chain.
+ *
+ * Uses topological sort (Kahn's algorithm) to bootstrap services
+ * in correct dependency order — same algorithm as DIContainer.
+ */
+export declare class ScopedContainer {
+    #private;
+    constructor(parent?: ScopedContainer);
+    /**
+     * Register a service constructor in this scope
+     */
+    register(token: Constructor): void;
+    /**
+     * Register a dependency relationship between services in this scope.
+     * Only for dependencies that are BOTH registered locally.
+     * Cross-scope dependencies are resolved via parent chain at get() time.
+     */
+    registerDependency(parent: Constructor, dependency: Constructor): void;
+    /**
+     * Bootstrap all locally registered services in dependency order.
+     * Each instance is associated with this container via __container.
+     *
+     * Services with async onBootstrap() are launched as fire-and-forget.
+     * Use the reactive pattern (@Store with isLoading) to handle async state.
+     */
+    bootstrapSync(): void;
+    /**
+     * Bootstrap all locally registered services, awaiting async onBootstrap hooks.
+     * Use this in the DOM init() path where async is available.
+     */
+    bootstrap(): Promise<void>;
+    /**
+     * Resolve a service by walking up the parent chain.
+     * Checks local scope first, then parent, then grandparent, etc.
+     */
+    get<T>(ctor: Constructor<T>): T;
+    /**
+     * Check if a service exists in this scope or any parent scope.
+     */
+    has(ctor: Constructor): boolean;
+    /**
+     * Check if a service is registered locally (not including parents).
+     */
+    hasLocal(ctor: Constructor): boolean;
+    /**
+     * Check if bootstrap has been called.
+     */
+    get isReady(): boolean;
+    /**
+     * Get the parent container.
+     */
+    get parent(): ScopedContainer | undefined;
+    /**
+     * Get all locally instantiated service instances.
+     */
+    getAllInstances(): any[];
+    /**
+     * Dispose all local services and reset container.
+     * Calls onDestroy() on services that implement it.
+     */
+    dispose(): void;
+}