Documentación Técnica - Librería NPM Compartida

📋 Resumen Ejecutivo

Propósito del Proyecto

Esta librería NPM está diseñada para centralizar y compartir código reutilizable entre múltiples proyectos, especialmente para scripts frontend de Windmill.dev. Permite mantener modelos de base de datos, utilidades comunes y esquemas de Drizzle ORM en un solo lugar, con actualización automática mediante CDN.

Casos de Uso Principales

• Scripts de Windmill: Importación directa desde CDN en frontend scripts
• Proyectos Node.js: Instalación vía NPM para backend applications
• Aplicaciones Web: Uso directo en navegador via UMD build
• Desarrollo Multi-proyecto: Sincronización automática de modelos y utilidades

Beneficios Clave

• ✅ Centralización: Un solo punto de verdad para código compartido
• ✅ Actualización Automática: Cambios se propagan automáticamente vía CDN
• ✅ Versionado Semántico: Control preciso de releases y compatibilidad
• ✅ Modularidad: Importación selectiva de componentes específicos
• ✅ CI/CD Integrado: Pipeline automatizado de build y deploy

🏗️ Arquitectura del Sistema

Flujo de Trabajo General

graph TD
    A[Desarrollo Local] --> B[npm run patch/minor/major]
    B --> C[Build Automático]
    C --> D[Commit & Tag]
    D --> E[Push a GitHub]
    E --> F[GitHub Actions]
    F --> G[Publicación NPM]
    G --> H[CDN Actualización]
    H --> I[Scripts Windmill]
    I --> J[Uso Automático Nueva Versión]

Estructura de Directorios

mi-libreria-js/
├── src/                    # Código fuente modular
│   ├── index.js           # Punto de entrada principal
│   ├── models/            # Modelos de datos y entidades
│   ├── utils/             # Utilidades y helpers
│   └── drizzle/           # Esquemas y configuración Drizzle ORM
├── dist/                  # Builds compilados
│   ├── index.js          # CommonJS build
│   ├── index.esm.js      # ES Modules build
│   └── index.umd.js      # Universal Module Definition
├── scripts/               # Scripts de automatización
├── .github/workflows/     # GitHub Actions CI/CD
└── config files          # Configuración de build tools

🔧 Componentes Principales

1. Sistema de Build (Rollup)

Archivo: rollup.config.js

Función: Compilar el código fuente en múltiples formatos para máxima compatibilidad.

Configuración:

export default [
  // ES Module build - Para imports modernos
  {
    input: 'src/index.js',
    output: { file: 'dist/index.esm.js', format: 'es' }
  },
  // CommonJS build - Para Node.js
  {
    input: 'src/index.js', 
    output: { file: 'dist/index.js', format: 'cjs' }
  },
  // UMD build - Para navegadores y CDN
  {
    input: 'src/index.js',
    output: { file: 'dist/index.umd.js', format: 'umd', name: 'MiLibreria' }
  }
];

Plugins Utilizados:

• @rollup/plugin-node-resolve: Resolución de módulos NPM
• @rollup/plugin-commonjs: Conversión CommonJS → ES Modules
• @rollup/plugin-terser: Minificación para producción

2. Sistema de Versionado Automático

Archivo: scripts/update-version.js

Función: Automatizar el proceso completo de release desde actualización de versión hasta push del repositorio.

Flujo de Ejecución:

1. Lectura de versión actual desde package.json
2. Actualización semántica usando npm version
3. Build automático de la librería
4. Commit y tag con mensaje estándar
5. Push al repositorio incluyendo tags

Lógica Principal:

// Actualizar versión
execSync(`npm version ${updateType} --no-git-tag-version`);

// Build
execSync('npm run build');

// Git operations
execSync('git add .');
execSync(`git commit -m "chore: release v${newVersion}"`);
execSync(`git tag v${newVersion}`);
execSync('git push && git push --tags');

3. Pipeline CI/CD (GitHub Actions)

Archivo: .github/workflows/publish.yml

Función: Automatizar la publicación en NPM cuando se detecta un nuevo tag.

Trigger: Push de tags con formato v* (ej: v1.0.0, v2.1.3)

Proceso:

1. Checkout del código
2. Setup Node.js environment
3. Instalación de dependencias
4. Build de la librería
5. Publicación en NPM registry

Configuración de Seguridad:

• Usa secrets.NPM_TOKEN para autenticación
• Configuración de registry oficial de NPM
• Restricción a tags versionados únicamente

4. Arquitectura Modular del Código

4.1 Punto de Entrada (src/index.js)

Función: Centralizar y organizar todas las exportaciones de la librería.

Estrategia:

• Exportaciones nombradas: Para tree-shaking óptimo
• Exportación por defecto: Para compatibilidad con diferentes sistemas de módulos
• Organización por categorías: Agrupación lógica de funcionalidades

// Exportaciones planas para máxima flexibilidad
export * from './models/index.js';
export * from './utils/index.js';
export * from './drizzle/index.js';

// Exportación estructurada para uso organizado
export default {
  models: require('./models/index.js'),
  utils: require('./utils/index.js'),
  drizzle: require('./drizzle/index.js')
};

4.2 Sistema de Modelos (src/models/)

Función: Definir entidades de datos con validación y métodos asociados.

Patrón de Diseño:

• Clases ES6 para modelos de datos
• Factory functions para servicios
• Separación de responsabilidades (modelo vs. servicio)

Ejemplo - Modelo User:

export class User {
  constructor(data = {}) {
    this.id = data.id || null;
    this.name = data.name || '';
    this.email = data.email || '';
    this.createdAt = data.createdAt || new Date();
  }

  validate() {
    if (!this.name) throw new Error('Name is required');
    if (!this.email) throw new Error('Email is required');
    return true;
  }

  toJSON() {
    return {
      id: this.id,
      name: this.name,
      email: this.email,
      createdAt: this.createdAt
    };
  }
}

Características:

• Validación integrada: Cada modelo valida sus propios datos
• Serialización: Método toJSON() para APIs
• Inmutabilidad opcional: Constructor con defaults seguros
• Extensibilidad: Fácil agregar nuevos campos y métodos

4.3 Sistema de Utilidades (src/utils/)

Función: Proveer funciones helper reutilizables organizadas por categoría.

Organización:

• Por dominio: Cada archivo representa un área funcional
• Exportaciones nombradas: Para importación selectiva
• Funciones puras: Sin efectos secundarios cuando es posible

Ejemplo - Utilidades de Fecha:

export const formatDate = (date, format = 'YYYY-MM-DD') => {
  return new Date(date).toISOString().split('T')[0];
};

export const addDays = (date, days) => {
  const result = new Date(date);
  result.setDate(result.getDate() + days);
  return result;
};

export const isValidDate = (date) => {
  return date instanceof Date && !isNaN(date);
};

4.4 Integración Drizzle ORM (src/drizzle/)

Función: Centralizar esquemas y configuraciones de base de datos.

Propósito:

• Esquemas compartidos: Definiciones de tabla consistentes
• Configuración centralizada: Settings de DB en un lugar
• Versionado de esquemas: Control de cambios en estructura

Estructura:

export const userSchema = {
  id: 'serial primary key',
  name: 'varchar(100) not null',
  email: 'varchar(100) unique not null',
  createdAt: 'timestamp default now()'
};

export const schemas = {
  user: userSchema,
  product: productSchema
};

🔄 Lógica de Funcionamiento

Flujo de Desarrollo

1. Desarrollo Local

   • Modificar código en src/
   • Probar cambios con npm run dev
   • Validar funcionamiento

2. Release Process

   npm run patch   # Para bugfixes (1.0.0 → 1.0.1)
   npm run minor   # Para features (1.0.0 → 1.1.0)
   npm run major   # Para breaking changes (1.0.0 → 2.0.0)

3. Automatización

   • Script ejecuta build
   • Crea commit con mensaje estándar
   • Genera tag con nueva versión
   • Push activa GitHub Actions
   • Publicación automática en NPM

Consumo en Windmill

Importación Dinámica:

// Siempre última versión
const { Models, Utils } = await import(
  'https://cdn.jsdelivr.net/npm/@tu-usuario/mi-libreria-js@latest/dist/index.esm.js'
);

// Versión específica para estabilidad
const { Models } = await import(
  'https://cdn.jsdelivr.net/npm/@tu-usuario/[email protected]/dist/index.esm.js'
);

Uso Práctico:

// Crear y validar modelo
const user = new Models.User({ 
  name: 'Juan Pérez', 
  email: '[email protected]' 
});
user.validate();

// Usar utilidades
const formatted = Utils.Date.formatDate(new Date());
const isValid = Utils.Validation.isEmail(user.email);

// Trabajar con datos
const userData = user.toJSON();

Estrategia de Versionado

Semantic Versioning (SemVer):

• PATCH (x.x.X): Bugfixes, no breaking changes
• MINOR (x.X.x): Nuevas features, backward compatible
• MAJOR (X.x.x): Breaking changes, requiere actualización

Gestión de Compatibilidad:

• Usar @latest para desarrollo activo
• Fijar versiones en producción crítica
• Documentar breaking changes en releases