Skip to content
/ generaljs Public

General.JS es una librería JavaScript de alto rendimiento diseñada para desarrolladores que exigen control total, velocidad extrema y una arquitectura extensible.

3 stars 2 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

arturo21/generaljs

BranchesTags

Repository files navigation

⚙️ General.JS v2

Librería JavaScript modular, encadenable y extensible para soluciones de alto rendimiento
DOM, eventos, AJAX, WebSockets, WebWorkers, rutas, componentes, ámbitos, extensiones y más

Versión v2 Estado del proyecto Licencia MIT

🚀 ¿Qué es General.JS?

General.JS v2 es una librería JavaScript ligera, modular y sin dependencias externas. Refactorizada con el patrón Module Revealed, permite encadenamiento fluido, extensión dinámica, integración con Web Components y control total sobre el DOM, eventos, rutas, ámbitos y comunicación asincrónica.

✨ Novedades en generaljs v2

  • 🔧 Encapsulación segura con patrón Module Revealed
    Lógica privada protegida, API pública revelada con control total.

  • 🔗 Encadenamiento fluido de métodos
    Todos los métodos devuelven genrl para composición elegante:
    genrl.log().setScope().ready()

  • 🧩 Ámbitos dinámicos con setScope(nombre) y createScope()
    Define entornos de aplicación únicos por instancia.

  • 🧠 Sistema de extensión modular con fn.extend({...})
    Permite registrar múltiples módulos (como cripto, ajaxapi, gdom) en una sola llamada.

  • 🧬 Integración profunda con gdom(selector)
    Acceso fluido a métodos DOM como addClass, removeClass, on, attr, html, appendTo, etc.

  • 🧱 Compatibilidad con CommonJS y entorno navegador
    Exportación dual con module.exports y window.genrl para uso universal.

  • 🧠 Alias global g para gdom
    Disponible como window.g(selector) para manipulación directa del DOM.

  • 🔐 Ejecución segura con safeEval(fn)
    Captura errores silenciosamente sin romper el flujo.

  • 🕒 Tiempos precisos con now(), nowFloat(), timestamp()
    Ideal para medición de rendimiento y trazabilidad.

  • 📦 Registro dinámico de Web Components
    Soporte para plantillas externas, mount, unmount, setDefaults, y loadAll.

  • 🧠 Utilitarios robustos
    Incluye uuid(), sanitize, validate.email/url, base64_encode/decode, utf8_encode/decode, parseHTML, parseJSON, stringifyJSON.

  • 🔍 Observación reactiva con watch(obj, path, callback)
    Define propiedades reactivas y dispara eventos ante cambios profundos.

  • 🧪 Depuración integrada con log, warn, info, error
    Registro interno (_logStore) accesible para trazabilidad.

  • 🧩 Extensión de prototipos con genrl.__proto__
    Métodos como watch_, unwatch_, ajax, isReady, getelem, getelems, empty.

🧩 Función 📘 Descripción
Module Revealed Encapsula funciones privadas y expone solo lo necesario.
Encadenamiento fluido Todos los métodos retornan this o el módulo para llamadas encadenadas.
setScope(nombre) Define el ámbito activo en el DOM (data-scope).
createScope() Inicializa atributos id, name, data-scope, data-gapp en <html>.
safeEval(fn) Ejecuta funciones de forma segura (sin eval() inseguro).
now() Devuelve tiempo de ejecución como entero positivo.
uuid() / timestamp() Genera identificadores únicos y marcas de tiempo ISO.
validate / sanitize Validación de email, URL y sanitización de HTML, texto y JSON.
logEvent(), getLog(), clearLog() Registro interno de eventos para depuración.

Submódulo Components

🧩 Función 📘 Descripción
register(tag, class) Registra un Web Component personalizado.
addcomponent(tag, url, cb, opts) Carga plantilla externa y la asocia al componente.
loadAll(manifest) Carga múltiples componentes desde un manifiesto.
mount(tag, selector) Inserta el componente en el DOM.
unmount(tag) Elimina instancias del componente del DOM.
setDefaults(opts) Define estilos y atributos comunes para todos los componentes.
isRegistered(tag) Verifica si un componente ya fue registrado.

Submódulo AjaxAPI

🧩 Función 📘 Descripción
get(url) Realiza una petición GET.
getJSON(url) Realiza una petición GET y parsea JSON.
post(url, data) Envía datos por POST.
upload(url, FormData) Sube archivos mediante POST asincrónico.
load(url) Carga contenido externo en el DOM.

Submódulo bind

🧩 Función 📘 Descripción
setData(key, value) Asocia un valor a un elemento DOM.
getData(key) Recupera el valor asociado.
rmData(key) Elimina el valor asociado.
bind(selector, model) Enlaza datos a elementos DOM dinámicamente.

Submódulo Animate

🧩 Función 📘 Descripción
animate(type, duration, cb) Aplica animaciones con duración y callback.
smooth(target, opts) Realiza scroll suave hacia un objetivo.
setAnimationDuration(el, speed) Establece duración de animación con prefijo de navegador.

Submódulo Cripto

🧩 Función 📘 Descripción
base64_encode(str) Codifica en base64.
base64_decode(str) Decodifica base64.
utf8_encode(str) Codifica UTF-8.
utf8_decode(str) Decodifica UTF-8.

Submódulo WebSockets

🧩 Función 📘 Descripción
connect(url) Establece conexión WebSocket.
send(data) Envía datos por WebSocket.
onMessage(cb) Escucha mensajes entrantes.

Submódulo WebWorkers

🧩 Función 📘 Descripción
createWorker(script) Crea un Web Worker.
postMessage(data) Envía datos al worker.
onMessage(cb) Escucha respuesta del worker. 
                          |

Submódulo Routing.general

🧩 Función 📘 Descripción
map(route).to(fn) Asocia una ruta hash a una función.
listen() Activa el sistema de rutas y escucha cambios.
navigate(url) Navega programáticamente a una ruta.
getCurrent() Obtiene la ruta actual.

Métodos Nuevos

genrl.setScope("pedagogico");
genrl.safeEval(() => console.log("Ejecutando código seguro"));
genrl.now(); // → número entero positivo
genrl.extend("saludar", () => console.log("¡Hola Arturo!")).saludar();

🔧 Extensibilidad de la clase genrl

🧩 Método de extensión 📘 Descripción
genrl.extend(nombre, fn) Agrega una función pública directamente al objeto genrl.
genrl.fn.extend(nombre, fn) Agrega una función privada o interna que puede ser invocada desde genrl.fn.
g(selector).extend(nombre, fn) Agrega una función personalizada a un selector DOM específico.

Ejemplos de uso

1. Extender genrl con una función pública

genrl.extend("saludar", function(nombre){
  console.log("¡Hola " + nombre + "!");
  return this;
});

2. Extender genrl.fn con una función interna (recomendado para plugins)

genrl.fn.extend("multiplicar", function(a, b){
  return a * b;
});

// Invocación
let resultado = genrl.fn("multiplicar")(3, 4); // → 12

3. Extender un selector DOM con una función personalizada

g("#miBoton").extend("activar", function(){
  this.addClass("activo");
  console.log("Botón activado");
});

// Invocación
g("#miBoton").activar();
✅ Ventaja 📘 Descripción
Encadenamiento fluido Las funciones extendidas pueden encadenarse con otras llamadas (genrl.fn1().fn2()).
Modularidad Puedes agregar funciones específicas sin alterar el núcleo original.
Separación público/privado genrl.extend() para funciones públicas, genrl.fn.extend() para internas.
Adaptación contextual g(selector).extend() permite extender elementos DOM individualmente.
Seguridad Las extensiones respetan el patrón Module Revealed y no exponen variables internas.
Reusabilidad Las funciones extendidas pueden reutilizarse en múltiples contextos del sistema.
Integración pedagógica Permite crear funciones adaptadas a fichas, sliders, rutas y ámbitos educativos.

🔌 Sistema de plugins en General.JS v2

Métodos disponibles

Método Descripción
.extend(name, fn) Añade métodos directamente al núcleo de General.
.use(plugin, options) Registra e inicializa un plugin externo con configuración opcional.
.plugins() Devuelve un array con los nombres de los plugins registrados.

Ventajas del sistema de plugins (General.JS v2)

✅ Ventaja 📘 Descripción
Modularidad total Permite agregar funcionalidades sin alterar el núcleo de General.
Registro seguro Evita duplicaciones y colisiones mediante control de nombres únicos.
Inicialización flexible Cada plugin puede recibir opciones personalizadas al momento de registrarse.
Encadenamiento fluido Los métodos añadidos por plugins se integran al flujo encadenable de gdom.
Compatibilidad transversal Los plugins pueden interactuar con animate, bind, routing, reactive.
Trazabilidad clara .plugins() devuelve los nombres de todos los plugins activos.
Ideal para entornos pedagógicos Permite crear extensiones visuales, estructurales y educativas.
Listo para producción Soporta plugins visuales, de seguridad, AJAX, formularios y más.

|

Ejemplo de uso

function shakePlugin(General, opts) {
  General.shake = function (el, duration = 300) {
    el.style.transform = 'translateX(0)';
    animate.animate(-10, 10, duration / 2, 'easeOutQuad', val => {
      el.style.transform = `translateX(${val}px)`;
    }, () => {
      animate.animate(10, 0, duration / 2, 'easeInQuad', val => {
        el.style.transform = `translateX(${val}px)`;
      });
    });
  };
}

genrl.use(shakePlugin);
genrl.shake(document.querySelector("#boton"), 400);

📦 Instalación

npm i gnrl.js

Ejemplo de Inicialización

genrl.run(() => {
  genrl
    .createScope()
    .setScope("editorial")
    .theme("claro")
    .log("Ámbito y tema establecidos");
});

Registro de Web Components básico

components
  .setDefaults({
    styles: `.ficha { border-left: 4px solid #c25; padding: 1em; }`,
    attributes: { "data-tipo": "editorial" }
  })
  .loadAll([
    {
      tag: "mi-ficha",
      templateURL: "ficha.html",
      callback: (tpl) => {
        const el = document.createElement("mi-ficha");
        el.appendChild(tpl.content.cloneNode(true));
        document.body.appendChild(el);
      }
    }
  ])
  .mount("mi-ficha", "#contenedor")
  .unmount("mi-ficha");

Registro de Web Components con plantilla externa

components
  .register("mi-ficha", class extends HTMLElement {
    connectedCallback() {
      // El contenido se insertará desde ficha.html
    }
  })
  .addcomponent("mi-ficha", "ficha.html", (template) => {
    const instance = document.createElement("mi-ficha");
    instance.appendChild(template.content.cloneNode(true));
    document.querySelector("#contenedor").appendChild(instance);
  });

Ejemplo: Contador

genrl.run(() => {
  components
    .register("contador-js", class extends HTMLElement {
      constructor() {
        super();
        this.valor = 0;
        this.attachShadow({ mode: "open" });
      }

      connectedCallback() {
        components.addcomponent("contador-js", "contador.html", (template) => {
          this.shadowRoot.appendChild(template.content.cloneNode(true));
          this.input = this.shadowRoot.getElementById("valor");
          this.btnInc = this.shadowRoot.getElementById("incrementar");
          this.btnDec = this.shadowRoot.getElementById("decrementar");

          this.btnInc.onclick = () => this.incrementar();
          this.btnDec.onclick = () => this.decrementar();
          this.actualizar();
        });
      }

      incrementar() {
        this.valor++;
        this.actualizar();
      }

      decrementar() {
        this.valor--;
        this.actualizar();
      }

      actualizar() {
        this.input.value = this.valor;
      }
    });
});

Ejemplo de Uso en HTML

<contador-js></contador-js>

About

General.JS es una librería JavaScript de alto rendimiento diseñada para desarrolladores que exigen control total, velocidad extrema y una arquitectura extensible.

Topics

css components events library web modern js dom websockets ajax hash browsers webworkers webcomponent

Resources

Readme
Activity

Stars

3 stars

Watchers

2 watching

Forks

2 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages