Vista General

Paquete: @tiendana/utils

Colección de utilidades TypeScript reutilizables y agnósticas de framework para validación, manipulación de datos, APIs del navegador y más.

Características

✅ Tree-shakeable - sideEffects: false: el bundler descarta lo que no importas
✅ TypeScript-first - Tipos completos y seguros
✅ Una sola dependencia - @tiendana/api-types, solo para el tipo Attachment de las utilidades AWS
✅ Navegador y Node.js - La mayoría de utilidades corre en ambos; las que tocan el DOM (cookies, portapapeles, descargas, snackbar, imágenes) son solo de navegador
✅ Logomark aparte - El símbolo de Tiendana vive en su propio punto de entrada y no pesa en el resto

Instalación

Autenticación Requerida

@tiendana/utils está alojado en AWS CodeArtifact privado. Autentica npm con Tiendana CLI (tdn auth npm) antes de instalar.

Configurar CodeArtifact

tdn auth npm

El proyecto necesita además el .npmrc del scope @tiendana. Consulta la guía de CodeArtifact.

Instalar el Paquete

npm install @tiendana/utils

Puntos de Entrada

El paquete define un mapa exports con estos puntos de entrada. No existen otros: los imports profundos como @tiendana/utils/dist/... o @tiendana/utils/patterns no se resuelven.

Import	Contenido
@tiendana/utils	Todas las utilidades generales de esta sección
@tiendana/utils/logomark	Logomark: motor de expresiones, canvas, exportación a archivos y el elemento <tdn-logomark>
@tiendana/utils/logomark/colourways	Mixin SCSS con los colourways del logomark (@use '@tiendana/utils/logomark/colourways')
@tiendana/utils/package.json	El package.json del paquete

// Utilidades generales
import { hasValue, stringToSlug } from '@tiendana/utils';

// Logomark: punto de entrada separado
import { defineLogomarkElement } from '@tiendana/utils/logomark';

El barrel raíz no reexporta el logomark: importar @tiendana/utils nunca arrastra su código. Gracias a sideEffects: false, un bundler elimina cualquier módulo cuyos exports no uses.

Uso Básico

import { hasValue, stringToSlug, setCookie } from '@tiendana/utils';

// Validación
if (hasValue(userName)) {
  console.log('Usuario válido');
}

// Strings
const slug = stringToSlug('Título con Ñ y Acentos');
// 'titulo-con-n-y-acentos'

// Browser: expires acepta un Date o un timestamp Unix en SEGUNDOS
setCookie('session', 'abc123', {
  expires: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
  path: '/'
});

expires no son días

Un número en expires es un timestamp Unix en segundos (new Date(expires * 1000)). { expires: 7 } expira la cookie al instante, porque equivale a 1970. Pasa un Date o Math.floor(Date.now() / 1000) + segundos.

Categorías de Utilidades

🔍 Validación

Verificación de valores y patrones comunes.

• hasValue - Type guard para null/undefined/''/NaN y arrays vacíos
• objHasValue - Verifica que un objeto tenga propiedades
• Patterns - Regex: EMAIL, PASSWORD, DOMAIN, IMAGE, NUMBER, CC

📋 Arrays

Manipulación y búsqueda en arrays.

• distinct - Elimina duplicados
• toArray - Convierte valores a array
• arrayGroupBy - Agrupa por campo
• getObjectByValue, getObjIndexByValue - Busca en un array de objetos por valor de un campo

📝 Strings

Transformación y formato de texto.

• truncateString - Corta a una longitud máxima (no agrega puntos suspensivos)
• stringToSlug - Slug URL-friendly
• removeDiacritics - Remueve acentos
• parseName - Separa nombres completos en nombre y apellidos

📦 Objetos

Operaciones sobre objetos.

• deepMerge - Merge recursivo que no muta el target (ni sus objetos anidados desde 0.2.10)
• emptyKeys - Devuelve los nombres de las claves, entre las indicadas, cuyo valor está vacío
• getPath - Acceso a propiedades anidadas por ruta

🌐 Browser

APIs del navegador y DOM.

• Cookies: getAllCookies, getCookie, setCookie, deleteCookie, deleteAllCookies
• copyTextToClipboard - Copia al portapapeles
• downloadFile - Descarga un archivo desde una URL

💾 Data

Conversión y formato de datos.

• tryJSONParse - Parse de JSON sin lanzar errores
• sanitizeEmail - Limpia un email (no lo valida)
• strToNumber - Conversión estricta de string a número

🔒 Security

Seguridad y autenticación.

• parseJwt - Decodifica el payload de un JWT, sin verificar la firma
• isSameDomain - Compara el host de dos URLs

🇨🇴 Colombia

• calculateDv - Dígito de verificación de un NIT

☁️ AWS

Construcción de URLs de assets.

• AwsAssetsResources, getCloudfrontUrl, getS3Url, getCdnPublicUrl y sus variantes *Attachment

🎨 UI/UX

Helpers para interfaz y experiencia.

• ImageCompressor - Compresión de imágenes en el navegador, con abort() y helpers de bajo nivel
• openSnackbar - Notificaciones con cola
• Constantes TDN_ICON_* - Iconos SVG como string

🔧 Misc

Otras utilidades especializadas.

• guid, uniqueId, getRandomInt, generatePassword (opciones en RandomPasswordOps)
• generateUTMUrl - Parámetros UTM para URLs
• noop - Función vacía
• debugLog - Log estilizado de modo debug
• getEnumValueByKey, getEnumKeyByValue - Helpers de enum
• ImageToBlackAndWhite - Imagen a blanco y negro en un canvas
• cvEasterEgg - Easter egg para DevTools

🧿 Logomark

El símbolo de Tiendana como código: motor de expresiones, renderizado en canvas, exportación a SVG/APNG/WebP y el elemento <tdn-logomark>. Se importa desde @tiendana/utils/logomark.

import { defineLogomarkElement } from '@tiendana/utils/logomark';

defineLogomarkElement();

<tdn-logomark clip="hello" loop size="96" label="Tiendana"></tdn-logomark>

Consulta la vista general del Logomark para el elemento, los clips, los colourways y las exportaciones.

Ejemplo Completo

import {
  hasValue,
  arrayGroupBy,
  stringToSlug,
  deepMerge,
  setCookie
} from '@tiendana/utils';

// Validar y procesar datos
function processUserData(data: any) {
  if (!hasValue(data.name)) {
    throw new Error('Nombre requerido');
  }

  // Generar slug del nombre
  const slug = stringToSlug(data.name);

  // Agrupar usuarios por rol
  const grouped = arrayGroupBy(users, 'role');

  // Merge de configuración
  const config = deepMerge(defaultConfig, userConfig);

  // Guardar sesión 30 días
  setCookie('user-slug', slug, {
    expires: Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60,
    path: '/'
  });

  return { slug, grouped, config };
}

Dependencias

@tiendana/utils solo depende de:

• @tiendana/api-types - Tipos e interfaces compartidas (el tipo Attachment de las utilidades AWS)

Compatibilidad

• TypeScript: 5.0+
• Node.js: 20+
• Navegadores: Chrome/Edge 90+, Firefox 88+, Safari 14+

Próximos Pasos

Explora las categorías en el menú lateral para ver la documentación completa de cada utilidad con ejemplos y casos de uso.