Versión: 4.1.1

Descripción

Emerald es una librería JavaScript extensible, creada para uso experimental, útil para:

IMPORTANTE: Esta librería está OBSOLETA, NO ES APTA PARA PRODUCCIÓN, FUE PROTOTIPO del framework actual Estructura.

Instalación

Compatible con cualquier intérprete JavaScript o browser moderno. Requiere conocimiento sólido del lenguaje de programación JavaScript.

Colocar dentro de la etiqueta head del HTML:

<script src="https://okzgn.github.io/emerald-prototype-2024-js/emerald-v-4-1-1.js"></script>

Funciones

  1. Función principal para manejar datos.
  2. Deep. Función para recorrer objetos/arrays multinivel con índices textuales.
  3. Each. Función para recorrer arrays/nodos multinivel con índices numéricos.
  4. Is/Are. Función para identificar tipos de datos.
  5. Método is/are. Función para comparar/comprobar tipos de datos.
  6. Run. Función para ejecutar todas las funciones dentro de objetos/arrays.
  7. Type. Función para identificar el tipo de datos primitivo.
  8. Assign. Función para extender/fusionar objetos de manera personalizada.
  9. Count. Función para contar varios tipos de datos.
  10. Lista de tipos de datos genéricos disponibles.
  11. Constructor de tipos de datos personalizados.
  12. Funciones autoasignables para tipos de datos.
  13. Funciones para el DOM, para seleccionar y manipular nodos.
  14. $. Función para ejecutarse al cargar el DOM.
  15. On. Función para vincular un evento y un manejador con un nodo del DOM.
  16. Off. Función para desvincular eventos y manejadores de un nodo del DOM.
  17. DomQuery. Tipo de dato para seleccionar nodos del DOM.
  18. DomQuery.on. Función para vincular eventos y manejadores con nodos seleccionados del DOM.
  19. DomQuery.off. Función para desvincular eventos y manejadores de nodos seleccionados del DOM.
  20. DomQuery.each. Función para aplicar callbacks a nodos seleccionados del DOM.
  21. DomQuery.attr. Función para obtener un atributo de un nodo seleccionado del DOM.
  22. DomQuery.property. Función para obtener una propiedad de un nodo seleccionado del DOM.

Documentación

_( ):Función principal para manejar datos.

Encierra datos de cualquier tipo para manejarse o procesarse, soporta múltiples argumentos. Se infieren los tipos de datos y sus funciones correspondientes a partir de el/los argumento(s).

Sintaxis normal:
_(cualquier_dato);
Sintaxis multiargumento:
_(cualquier_dato_1, /* ..., */ cualquier_dato_n);
Retorno:

Objeto con las siguientes propiedades y funciones:

Ejemplo:
_([], 2, { n: false }, new Date(), /[a-z]/, null);

_({ }).deep( ):Función para recorrer objetos/arrays multinivel con índices textuales.

Recorre el objeto/array del primer argumento de la función principal, ejecutando un callback para cada ítem de cada nivel. El primer argumento puede contener datos mixtos.

Sintaxis:
_(objeto).deep(FUNCION, NIVEL, INDICE);
Argumentos:
Retorno:

Objeto con propiedad count con el número de ítems recorridos.

Ejemplo:
_({
	a: 1,
	b: {
		c: '2',
		d: [3, { e: '4', f: 5 }],
		g: '6'
	},
	h: 7
}).deep(function(llave, valor, indice, nivel){
	console.log(llave, valor, indice, nivel);
}, true);

_([ ]).each( ):Función para recorrer arrays/nodos multinivel con índices numéricos.

Recorre el array o lista de nodos del primer argumento de la función principal, ejecutando un callback para cada ítem de cada nivel. El primer argumento puede contener datos mixtos.

Sintaxis:
_(array).each(FUNCION, OPCIONES, INDICE);
Argumentos:
Retorno:

Objeto con propiedad count con el número de ítems recorridos.

Ejemplo:
_([
	'1',
	2,
	'3',
	/5/,
	[6, 7, 8, 9],
	document.querySelectorAll('a'),
	'11'
]).each(function(indice, valor, indice_particular){
	console.log(indice, valor, indice_particular);
}, { simple: true, reverse: true }, 1);

is( )
are( ):Función para identificar tipos de datos.

Identifica todos los tipos de datos que corresponden al primer argumento o a los argumentos de la función (en caso de tipos multiargumentos). La función are es un alias de is. Los tipos de datos primitivos y predefinidos utilizan solo el primer argumento.

Sintaxis normal:
is(cualquier_dato);
are(cualquier_dato);
Sintaxis multiargumento:
is(cualquier_dato, /* ...,*/ cualquier_dato_n);
are(cualquier_dato, /* ...,*/ cualquier_dato_n);
Retorno:

Array con los nombres en minúsculas de los tipos de datos identificados.

Ejemplo:
is(/[a-z]/);

_( ).is( )
_( ).are( ):Función para comparar/comprobar tipos de datos.

Devuelve true o false si todos los tipos de datos especificados en los argumentos del método coinciden o no, con: el primer argumento o los argumentos de la función principal (en caso de tipos multiargumentos).

Sintaxis normal:
_(cualquier_dato).is(nombre_tipo_datos);
_(cualquier_dato).are(nombre_tipo_datos);
Sintaxis multiargumento:
_(cualquier_dato, /* ...,*/ cualquier_dato_n).is(nombre_tipo_datos, /*...,*/ nombre_tipo_datos_n);
_(cualquier_dato, /* ...,*/ cualquier_dato_n).are(nombre_tipo_datos, /*...,*/ nombre_tipo_datos_n);
Argumentos:
Retorno:

true o false.

Ejemplo:
_(/[a-z]/).is('regexp', 'defined');

_( ).run( ):Función para ejecutar todas las funciones dentro de objetos/arrays.

Ejecuta cualquier función directa o que esté dentro de un objeto/array del primer argumento de la función principal, opcionalmente, con referencia para el contexto this y para argumentos.

Sintaxis:
_(funcion_u_objeto_array).run(contexto_this, argumentos);
Argumentos:
Retorno:

Devuelve true.

Ejemplo:
_(function(){ console.log(this, arguments) }).run(123, ['4', 5, '6', 7]);

type( ):Función para identificar el tipo de datos primitivo.

Identifica el tipo de datos primitivo del primer argumento, no soporta múltiples argumentos.

Sintaxis:
type(cualquier_dato);
Retorno:

Uno de los siguientes string:

Ejemplo:
type(document.querySelector('a'));

assign( ):Función para extender/fusionar objetos de manera personalizada.

Extiende y fusiona de forma recursiva las propiedades de uno o más objetos o arrays fuentes en un objeto destino. Permite configurar niveles de profundidad y modos estrictos mediante el contexto.

Sintaxis:
assign(destino, objeto_fuente_1, /* ..., */ objeto_fuente_n);
Argumentos:
Opciones de Contexto (vía assign.call):
Retorno:

El objeto o array destino modificado.

Ejemplo:
var base = { a: 1, b: { c: 2 } };
var extra = { b: { d: 3 }, e: 4 };
assign(base, extra);
console.log(base);

count( ):Función para contar varios tipos de datos.

Calcula el tamaño, longitud o número de elementos de cualquier tipo de dato. En objetos y arrays realiza un conteo recursivo multinivel por defecto.

Sintaxis:
count(cualquier_dato, opcion);
Argumentos:
Retorno:

Número entero (number) con el total de elementos o longitud contabilizada.

Ejemplo:
console.log(count('Emerald'));
console.log(count({ a: 1, b: [2, 3, { c: 4 }] }));
console.log(count({ a: 1, b: [2, 3, { c: 4 }] }, true));

type:Lista de tipos de datos genéricos disponibles.

Catálogo de tipos de datos derivados y evaluadores de rango numérico reconocidos globalmente por las funciones is(), are() y el envoltorio principal _():

Ejemplo:
console.log(is(120));
console.log(is.char(200));
console.log(is.signed.char(-50));
console.log(_('123.45').is('numerical', 'decimal'));

type[ ]:Constructor de tipos de datos personalizados.

Permite registrar nuevos tipos de datos personalizados dentro de la estructura de Emerald. Al definir una función de reconocimiento (recognition), el nuevo tipo es integrado automáticamente en el motor de inferencia de _() e is().

Sintaxis:
type.nuevo_tipo_dato = {
	prepare: function(){ /* Inicialización única */ },
	before: function(){ /* Gancho previo a cada método */ },
	fn: { /* Métodos autoasignables */ },
	recognition: function(a, b, c){
		return a == 1 && b == 2 && c == 3;
	}
};
Propiedades del Objeto de Definición:
Retorno:

El objeto del nuevo tipo registrado en type.

Ejemplo:
type.coordenada = {
	recognition: function(x, y){
		return is.number(x) && is.number(y);
	}
};
console.log(is(10, 20));
console.log(_(10, 20).is('coordenada'));

type[ ].before[ ]
type[ ].fn[ ]:Funciones autoasignables para tipos de datos.

Permite asociar nuevos métodos ejecutables (fn) o interceptores previos (before) a tipos de datos existentes o personalizados. Estos métodos se vuelven accesibles mediante encadenamiento en _().

Sintaxis:
type.nombre_tipo.fn.metodo_nuevo = function(arg1, /* ..., */ argN){
	// this.data: contiene el primer argumento
	// this.args: contiene todos los argumentos
};
Argumentos y Contexto (this):
Retorno:

El valor que retorne la función asignada, o el propio contexto para encadenamiento.

Ejemplo:
type.string.fn.invertir = function(){
	return this.data.split('').reverse().join('');
};
console.log(_('Emerald').invertir());

_( ):Funciones para el DOM, para seleccionar y manipular nodos.

Módulo de manipulación y vinculación reactiva para elementos individuales del DOM, listas de nodos o consultas directas mediante selectores CSS.

Sintaxis:
_(nodo_o_selector).metodo();
Argumentos:
Retorno:

Instancia de Emerald (_) con métodos de manipulación del DOM habilitados (on, off, each, attr, property).

Ejemplo:
var enlace = document.querySelector('a');
_(enlace).on('click', function(e){
	e.preventDefault();
	console.log('Enlace presionado:', this.href);
});

$( ):Función para ejecutarse al cargar el DOM.

Encola una función para que sea ejecutada de forma segura una vez que el árbol DOM del documento esté completamente cargado y parseado (evento DOMContentLoaded).

Sintaxis:
$(function(){ /* Código que interactúa con el DOM */ });
Argumentos:
Retorno:

Indefinido (undefined).

Ejemplo:
$(function(){
	console.log('El DOM está listo para ser manipulado por Emerald.');
});

_( ).on( ):Función para vincular un evento y un manejador con un nodo del DOM.

Vincula un manejador de eventos a un elemento del DOM o al objeto window. Admite identificadores únicos mediante puntos para su posterior remoción selectiva.

Sintaxis:
_(nodo_dom).on(ID_EVENTO, FUNCION);
Argumentos:
Retorno:

Indefinido (undefined).

Ejemplo:
_(document.querySelector('button')).on('click.log', function(event){
	console.log('Botón clickeado en coordenadas:', event.clientX, event.clientY);
});

_( ).off( ):Función para desvincular eventos y manejadores de un nodo del DOM.

Elimina uno, varios o todos los manejadores de eventos vinculados previamente mediante .on() a un elemento del DOM.

Sintaxis:
_(nodo_dom).off(); // Elimina todos los eventos del nodo
_(nodo_dom).off(ID_EVENTO); // Elimina por tipo o identificador
Argumentos:
Retorno:

Indefinido (undefined).

Ejemplo:
var btn = document.querySelector('button');
_(btn).off('click.log');

_('>'):Tipo de dato para seleccionar nodos del DOM.

Selector de elementos integrado que utiliza querySelectorAll internamente. Se activa automáticamente cuando el primer argumento es una cadena que comienza con el caracter >.

Sintaxis:
_('>selector_css', contexto_opcional);
Argumentos:
Retorno:

Objeto Emerald con propiedad found (NodeList de elementos encontrados) y propiedad count con el total de nodos.

Ejemplo:
var enlaces = _('>nav a');
console.log('Enlaces encontrados:', enlaces.count);

_('>').on( ):Función para vincular eventos y manejadores con nodos seleccionados del DOM.

Vincula un manejador de eventos a todos los nodos coincidentes con la consulta del selector CSS.

Sintaxis:
_('>selector_css').on(ID_EVENTO, FUNCION);
Argumentos:
Retorno:

Indefinido (undefined).

Ejemplo:
_('>nav a').on('click', function(event){
	event.preventDefault();
	console.log('Navegando a:', this.getAttribute('href'));
});

_('>').off( ):Función para desvincular eventos y manejadores de nodos seleccionados del DOM.

Desvincula manejadores de eventos en todos los nodos que coinciden con el selector CSS.

Sintaxis:
_('>selector_css').off(ID_EVENTO);
Argumentos:
Retorno:

Indefinido (undefined).

Ejemplo:
_('>nav a').off('click');

_('>').each( ):Función para aplicar callbacks a nodos seleccionados del DOM.

Itera sobre la colección de nodos seleccionados ejecutando un callback para cada elemento coincidente.

Sintaxis:
_('>selector_css').each(FUNCION, OPCIONES);
Argumentos:
Retorno:

Objeto con la propiedad count con el total de nodos recorridos.

Ejemplo:
_('>h4').each(function(indice, elemento){
	console.log(indice + ':', elemento.innerText);
});

_('>').attr( ):Función para obtener un atributo de un nodo seleccionado del DOM.

Obtiene el valor del atributo HTML especificado del primer elemento coincidente con el selector.

Sintaxis:
_('>selector_css').attr(NOMBRE_ATRIBUTO);
Argumentos:
Retorno:

Cadena de texto (string) con el valor del atributo, o null si no existe o no se encontraron nodos.

Ejemplo:
console.log(_('>nav a').attr('href'));

_('>').property( ):Función para obtener una propiedad de un nodo seleccionado del DOM.

Obtiene el valor de una propiedad directa del objeto JavaScript del primer nodo coincidente con el selector.

Sintaxis:
_('>selector_css').property(NOMBRE_PROPIEDAD);
Argumentos:
Retorno:

El valor de la propiedad consultada, o undefined si no se encontraron nodos.

Ejemplo:
console.log(_('>h1').property('innerText'));

Pruebas (playground)

* Aparecerán primeras las últimas líneas impresas en consola (orden inverso).
* Luego de hacer clic en Ejecutar, haga clic en Detener para volver a empezar.
Salida de consola y resultado