@hemia/codex

v0.0.2

Published

2 months ago

Paquete generado por Hemia CLI: @hemia/codex

Downloads

0High
0Medium
0Low

cristian.mendez

marcosaraos

hemia-codex

@hemia/codex
Librería profesional para generación y gestión de SKUs (Stock Keeping Units) con múltiples estrategias y formatos personalizables. Ademas de generacion de codigos de barras.

Paquete generado con Hemia CLI

📦 Instalación

npm install @hemia/codex

🚀 Inicio Rápido

import { SKUGenerator } from '@hemia/codex';

// Método unificado - Modo aleatorio (por defecto)
const generator = new SKUGenerator();
const sku = generator.generate(); // "A3F7B2K9"

// Modo secuencial
const seqGen = new SKUGenerator({ mode: 'sequential' });
console.log(seqGen.generate()); // "000001"
console.log(seqGen.generate()); // "000002"

// Modo formato personalizado
const formatGen = new SKUGenerator({
  mode: 'format',
  format: '{brand:3}-{category:3}-####'
});
console.log(formatGen.generate({ brand: 'Nike', category: 'Shoes' })); 
// "NIK-SHO-X7Y9"

📚 Conceptos

¿Qué es un SKU?

Un SKU (Stock Keeping Unit) es un código único utilizado para identificar y rastrear productos en inventarios, sistemas de punto de venta y gestión de almacenes. Los SKUs son fundamentales para:

🏷️ Identificación única de productos
📊 Control de inventario
🛒 Gestión de comercio electrónico
📦 Seguimiento de variantes (color, tamaño, modelo)
🔍 Búsqueda y organización eficiente

Características de un buen SKU

✅ Único: No debe repetirse
✅ Corto: Fácil de leer y escribir
✅ Consistente: Sigue un formato estandarizado
✅ Significativo: Puede incluir información del producto
✅ Escalable: Permite crecimiento del catálogo

🎯 Método Principal: `generate()`

El método generate() es el punto de entrada unificado que automáticamente selecciona la estrategia de generación según la configuración.

Modos Disponibles

| Modo | Descripción | Mejor Para | |------|-------------|------------| | random | SKUs aleatorios alfanuméricos (por defecto) | Productos genéricos | | sequential | SKUs secuenciales con contador | Inventarios locales, órdenes | | timebased | SKUs basados en timestamp | Logs, eventos temporales | | unique | SKUs únicos UUID-based | Sistemas distribuidos | | format | SKUs personalizados con metadatos | E-commerce, catálogos |

📖 Ejemplos por Modo

1. Modo `random` (Por Defecto)

Genera SKUs aleatorios alfanuméricos.

const generator = new SKUGenerator({
  mode: 'random',  // Opcional, es el modo por defecto
  length: 10,
  prefix: 'PRD-',
  suffix: '-V1',
  includeChecksum: true
});

const sku = generator.generate();
// Result: "PRD-A3F7B2K9XY45-V1"

Uso simple:

const gen = new SKUGenerator();
gen.generate(); // "A3F7B2K9"
gen.generate(); // "X9K2M5N8" (diferente cada vez)

2. Modo `sequential`

Genera SKUs secuenciales con contador automático.

const generator = new SKUGenerator({
  mode: 'sequential',
  prefix: 'ORD-'
});

console.log(generator.generate()); // "ORD-000001"
console.log(generator.generate()); // "ORD-000002"
console.log(generator.generate()); // "ORD-000003"

// Control del contador
generator.resetCounter();
console.log(generator.generate()); // "ORD-000001"

generator.setCounter(99);
console.log(generator.generate()); // "ORD-000100"

3. Modo `timebased`

Genera SKUs basados en timestamp, ordenables cronológicamente.

const generator = new SKUGenerator({
  mode: 'timebased',
  prefix: 'LOG-'
});

const sku1 = generator.generate(); // "LOG-LNX8J4M2"
const sku2 = generator.generate(); // "LOG-LNX8J4M3"

// Los SKUs son ordenables cronológicamente
console.log(sku1 < sku2); // true

4. Modo `unique`

Genera SKUs únicos basados en UUID v4 (RFC 4122).

const generator = new SKUGenerator({
  mode: 'unique',
  length: 16,
  prefix: 'UNIQ-'
});

const sku = generator.generate();
// Result: "UNIQ-A3F7B2K9XY45MN78"

// Garantiza unicidad incluso en alta concurrencia
const skus = new Set();
for (let i = 0; i < 1000; i++) {
  skus.add(generator.generate());
}
console.log(skus.size); // 1000 (todos únicos)

5. Modo `format` (Más Potente)

Genera SKUs personalizados con formato y metadatos del producto.

Patrones de formato:

| Patrón | Descripción | Ejemplo | |--------|-------------|---------| | # | Carácter alfanumérico (A-Z, 0-9) | A, 3, Z | | @ | Solo letras (A-Z) | A, B, Z | | 9 | Solo números (0-9) | 1, 5, 9 | | {property} | Cualquier propiedad del objeto | NIKE, SAMSUNG | | {property:n} | Propiedad truncada a n caracteres | NIK, SAM | | {variant.property} | Propiedad anidada | Blue, 128GB | | {variant.property:n} | Propiedad anidada truncada | BL, 12 |

Ejemplos:

Configuración con formato predefinido:

const generator = new SKUGenerator({
  mode: 'format',
  format: '{brand:3}-{category:3}-####',
  prefix: 'PROD-'
});

const product = {
  category: 'Electronics',
  brand: 'Samsung'
};

const sku = generator.generate(product);
// Result: "PROD-SAM-ELE-A3F7"

Formato dinámico con longitudes personalizadas:

const generator = new SKUGenerator({
  mode: 'format',
  format: '{brand:3}-{model:4}-{variant.color:2}{variant.size}-####'
});

const product = {
  brand: 'Samsung',
  model: 'Galaxy S23',
  variant: {
    color: 'Blue',
    size: '128GB'
  }
};

const sku = generator.generate(product);
// Result: "SAM-GALA-BL128GB-X7Y9"

Propiedades personalizadas:

const generator = new SKUGenerator({
  mode: 'format',
  format: '{warehouse:2}-{supplier:4}-{region:3}-9999'
});

const info = {
  warehouse: 'WH-North',
  supplier: 'ACME Corporation',
  region: 'Europe'
};

const sku = generator.generate(info);
// Result: "WH-ACME-EUR-5678"

Sobrescribir formato en tiempo de ejecución:

const generator = new SKUGenerator({
  mode: 'format',
  format: '{brand:3}-####'  // Formato por defecto
});

// Usar formato por defecto
generator.generate({ brand: 'Nike' }); // "NIK-A3F7"

// Sobrescribir formato
generator.generate({ brand: 'Adidas', category: 'Shoes' }, '{brand:3}-{category:3}-@@##');
// "ADI-SHO-AB12"

⚙️ Configuración Completa

Opciones del Constructor

interface SKUConfig {
  // Modo de generación
  mode?: 'random' | 'sequential' | 'timebased' | 'unique' | 'format';
  
  // Para modo 'format'
  format?: string;              // Patrón de formato personalizado
  productInfo?: ProductInfo;    // Información del producto por defecto
  
  // Opciones generales
  separator?: string;           // Separador por defecto: '-'
  prefix?: string;              // Prefijo para todos los SKUs
  suffix?: string;              // Sufijo para todos los SKUs
  length?: number;              // Longitud del cuerpo del SKU (default: 8)
  includeTimestamp?: boolean;   // Incluir timestamp en SKU
  includeChecksum?: boolean;    // Incluir checksum de validación
}

Ejemplos de Configuración:

Configuración simple con prefijo y sufijo:

const generator = new SKUGenerator({
  mode: 'random',
  prefix: 'PROD-',
  suffix: '-2024',
  length: 8
});

generator.generate(); // "PROD-A3F7B2K9-2024"

Con checksum para validación:

const generator = new SKUGenerator({
  mode: 'sequential',
  prefix: 'INV-',
  includeChecksum: true
});

const sku = generator.generate(); // "INV-00000145"
// Los últimos 2 dígitos (45) son el checksum

// Validar integridad
const parsed = generator.parse(sku);
console.log(parsed.checksum); // "45"

Configuración completa multi-modo:

const generator = new SKUGenerator({
  mode: 'format',
  format: '{brand:3}-{category:3}-####',
  prefix: 'SKU-',
  suffix: '-V1',
  separator: '_',
  includeChecksum: true
});

const sku = generator.generate({ brand: 'Nike', category: 'Shoes' });
// Result: "SKU-NIK-SHO-X7Y945-V1"

🔧 Utilidades

`validate(sku: string)`

Valida el formato de un SKU generado.

const generator = new SKUGenerator({ 
  mode: 'random',
  prefix: 'PRD-' 
});

const sku = generator.generate();
generator.validate(sku);              // true
generator.validate('PRD-A3F7B2K9');   // true
generator.validate('INVALID@SKU');    // false
generator.validate('');               // false

`parse(sku: string)`

Extrae información de un SKU generado (prefix, body, suffix, checksum).

const generator = new SKUGenerator({
  mode: 'sequential',
  prefix: 'PRD-',
  suffix: '-V1',
  includeChecksum: true
});

const sku = generator.generate();
const parsed = generator.parse(sku);

console.log(parsed);
// {
//   prefix: 'PRD-',
//   body: '000001',
//   suffix: '-V1',
//   checksum: '45'
// }

Métodos de acceso directo

Si prefieres usar métodos específicos en lugar del método unificado generate():

const generator = new SKUGenerator();

// Métodos individuales (todavía disponibles)
generator.random();              // SKU aleatorio
generator.createSequential();    // SKU secuencial
generator.createTimeBased();     // SKU con timestamp
generator.createUnique();        // SKU único UUID-based
generator.fromFormat(info, fmt); // SKU con formato personalizado

Nota: Se recomienda usar generate() con configuración de modo para mayor claridad y consistencia.

🎨 Casos de Uso Reales

1. E-commerce con múltiples variantes

import { SKUGenerator, VariantManager } from '@hemia/codex';

const generator = new SKUGenerator({
  mode: 'format',
  format: '{category:3}-{brand:3}-{model:4}-{variant.color:2}{variant.size}-####',
  prefix: 'SHOP-'
});

const manager = new VariantManager();

const baseProduct = {
  category: 'Clothing',
  brand: 'Nike',
  model: 'AirMax'
};

const variants = {
  color: ['Red', 'Blue', 'Black'],
  size: ['S', 'M', 'L']
};

const skus = manager.generateVariantSKUs(
  baseProduct,
  variants,
  generator,
  '{category:3}-{brand:3}-{model:4}-{variant.color:2}{variant.size}-####'
);

console.log(skus);
// [
//   { variant: { color: 'Red', size: 'S' }, sku: 'SHOP-CLO-NIK-AIRM-RES-A3F7' },
//   { variant: { color: 'Red', size: 'M' }, sku: 'SHOP-CLO-NIK-AIRM-REM-X9K2' },
//   { variant: { color: 'Blue', size: 'S' }, sku: 'SHOP-CLO-NIK-AIRM-BLS-M5N8' },
//   ...
// ]

2. Sistema de inventario híbrido

// Productos regulares: sequential
const regularGen = new SKUGenerator({
  mode: 'sequential',
  prefix: 'INV-',
  includeChecksum: true
});

// Productos premium: format-based
const premiumGen = new SKUGenerator({
  mode: 'format',
  format: '{brand:3}-{model:4}-PREMIUM-####',
  prefix: 'PREM-'
});

// Productos temporales: time-based
const tempGen = new SKUGenerator({
  mode: 'timebased',
  prefix: 'TEMP-'
});

// Generar SKUs según tipo de producto
const inventory = [
  { type: 'regular', sku: regularGen.generate() },    // "INV-00000145"
  { type: 'premium', sku: premiumGen.generate({ brand: 'Apple', model: 'MacBook' }) }, // "PREM-APP-MACB-PREMIUM-X7Y9"
  { type: 'temp', sku: tempGen.generate() }           // "TEMP-LNX8J4M2"
];

console.log(inventory);

3. Sistema de órdenes con tracking

class OrderSystem {
  private orderGen: SKUGenerator;
  private itemGen: SKUGenerator;
  private trackingGen: SKUGenerator;

  constructor() {
    // Órdenes: secuencial con año
    this.orderGen = new SKUGenerator({
      mode: 'sequential',
      prefix: `ORD-${new Date().getFullYear()}-`
    });

    // Items: UUID único
    this.itemGen = new SKUGenerator({
      mode: 'unique',
      length: 12,
      prefix: 'ITEM-'
    });

    // Tracking: timestamp
    this.trackingGen = new SKUGenerator({
      mode: 'timebased',
      prefix: 'TRK-'
    });
  }

  createOrder(items: any[]) {
    return {
      orderId: this.orderGen.generate(),
      trackingNumber: this.trackingGen.generate(),
      items: items.map(item => ({
        ...item,
        itemId: this.itemGen.generate()
      }))
    };
  }
}

const system = new OrderSystem();
const order = system.createOrder([
  { product: 'Laptop', quantity: 1 },
  { product: 'Mouse', quantity: 2 }
]);

console.log(order);
// {
//   orderId: 'ORD-2025-000001',
//   trackingNumber: 'TRK-LNX8J4M2',
//   items: [
//     { product: 'Laptop', quantity: 1, itemId: 'ITEM-A3F7B2K9XY45' },
//     { product: 'Mouse', quantity: 2, itemId: 'ITEM-Z9K1P5Q2RT89' }
//   ]
// }

4. Catálogo de productos con metadatos

const generator = new SKUGenerator({
  mode: 'format',
  format: '{brand:3}-{category:3}-{year:2}-{variant.color:2}-####'
});

const products = [
  { brand: 'Samsung', category: 'Electronics', year: 2024, variant: { color: 'Blue' } },
  { brand: 'Nike', category: 'Shoes', year: 2024, variant: { color: 'Red' } },
  { brand: 'Apple', category: 'Tech', year: 2024, variant: { color: 'Black' } }
];

const catalog = products.map(product => ({
  ...product,
  sku: generator.generate(product)
}));

console.log(catalog);
// [
//   { brand: 'Samsung', ..., sku: 'SAM-ELE-24-BL-A3F7' },
//   { brand: 'Nike', ..., sku: 'NIK-SHO-24-RE-X9K2' },
//   { brand: 'Apple', ..., sku: 'APP-TEC-24-BL-M5N8' }
// ]

� Generador de Códigos de Barras

El BarcodeGenerator permite generar y validar códigos de barras estándar internacionales como EAN-13 y UPC-A, ampliamente utilizados en retail y comercio global.

¿Qué es un código de barras?

Un código de barras es una representación visual de datos mediante líneas paralelas de diferentes anchos que pueden ser escaneados por lectores ópticos. Los formatos más comunes son:

EAN-13: Estándar europeo de 13 dígitos (usado globalmente)
UPC-A: Estándar norteamericano de 12 dígitos

🎯 Funciones de BarcodeGenerator

1. `generateEAN13()`

Genera códigos de barras EAN-13 válidos con checksum automático.

Estructura EAN-13:

3 dígitos: Código de país
5 dígitos: Código de fabricante
4 dígitos: Código de producto
1 dígito: Checksum (calculado automáticamente)

import { BarcodeGenerator } from '@hemia/codex';

const generator = new BarcodeGenerator();

// Generar EAN-13 con códigos por defecto
const barcode1 = generator.generateEAN13();
console.log(barcode1); // "0000001234567"

// Generar con código de país y fabricante personalizados
const barcode2 = generator.generateEAN13('978', '12345');
console.log(barcode2); // "9781234512348" (libros ISBN)

const barcode3 = generator.generateEAN13('750', '85942');
console.log(barcode3); // "7508594234561" (México)

Códigos de país comunes:

000-019: EE.UU. y Canadá
300-379: Francia
400-440: Alemania
460-469: Rusia
500-509: Reino Unido
750: México
850: Cuba
978-979: Libros (ISBN)

2. `generateUPC()`

Genera códigos UPC-A de 12 dígitos, el estándar predominante en Estados Unidos y Canadá.

Estructura UPC-A:

1 dígito: Sistema numérico (0 = estándar)
5 dígitos: Código de fabricante
5 dígitos: Código de producto
1 dígito: Checksum (calculado automáticamente)

const generator = new BarcodeGenerator();

const upc1 = generator.generateUPC();
console.log(upc1); // "012345678905"

const upc2 = generator.generateUPC();
console.log(upc2); // "098765432106"

3. `validateEAN13()`

Valida la integridad de códigos de barras EAN-13.

const generator = new BarcodeGenerator();

// Validar códigos reales
generator.validateEAN13('4006381333931'); // true (Nutella)
generator.validateEAN13('5449000000996'); // true (Coca-Cola)
generator.validateEAN13('8711327371309'); // true (Válido)

// Validar códigos inválidos
generator.validateEAN13('1234567890123'); // false (checksum incorrecto)
generator.validateEAN13('123456789012');  // false (muy corto)
generator.validateEAN13('ABC1234567890'); // false (contiene letras)

4. `validateUPC()`

Valida la integridad de códigos UPC-A.

const generator = new BarcodeGenerator();

// Validar códigos reales
generator.validateUPC('012345678905'); // true
generator.validateUPC('036000291452'); // true (Coca-Cola)
generator.validateUPC('042100005264'); // true (Doritos)

// Validar códigos inválidos
generator.validateUPC('123456789012'); // false (checksum incorrecto)
generator.validateUPC('12345678901');  // false (muy corto)

🎨 Casos de Uso de Códigos de Barras

Sistema de punto de venta (POS)

import { BarcodeGenerator } from '@hemia/codex';

const generator = new BarcodeGenerator();

// Registrar nuevos productos con códigos de barras
const products = [
  { name: 'Laptop Dell', country: '840', manufacturer: '12345' },
  { name: 'Mouse Logitech', country: '750', manufacturer: '67890' },
  { name: 'Teclado HP', country: '400', manufacturer: '54321' }
];

const inventory = products.map(product => ({
  ...product,
  barcode: generator.generateEAN13(product.country, product.manufacturer)
}));

console.log(inventory);
// [
//   { name: 'Laptop Dell', country: '840', manufacturer: '12345', barcode: '8401234512348' },
//   { name: 'Mouse Logitech', country: '750', manufacturer: '67890', barcode: '7506789045671' },
//   { name: 'Teclado HP', country: '400', manufacturer: '54321', barcode: '4005432198760' }
// ]

Validación en sistema de escaneo

const generator = new BarcodeGenerator();

function scanProduct(barcode: string) {
  // Detectar tipo de código y validar
  if (barcode.length === 13) {
    const isValid = generator.validateEAN13(barcode);
    return {
      type: 'EAN-13',
      barcode,
      valid: isValid,
      message: isValid ? 'Código válido' : 'Código inválido - verificar entrada'
    };
  } else if (barcode.length === 12) {
    const isValid = generator.validateUPC(barcode);
    return {
      type: 'UPC-A',
      barcode,
      valid: isValid,
      message: isValid ? 'Código válido' : 'Código inválido - verificar entrada'
    };
  }
  
  return { type: 'UNKNOWN', barcode, valid: false, message: 'Formato no reconocido' };
}

// Simular escaneo
console.log(scanProduct('4006381333931')); // { type: 'EAN-13', valid: true, ... }
console.log(scanProduct('036000291452'));  // { type: 'UPC-A', valid: true, ... }
console.log(scanProduct('123'));           // { type: 'UNKNOWN', valid: false, ... }

Generación masiva para catálogo

const generator = new BarcodeGenerator();

// Generar códigos de barras para catálogo de libros (ISBN)
function generateBookBarcodes(count: number) {
  const barcodes = [];
  
  for (let i = 0; i < count; i++) {
    const barcode = generator.generateEAN13('978', '12345'); // 978 = ISBN
    const isValid = generator.validateEAN13(barcode);
    
    barcodes.push({
      id: i + 1,
      isbn: barcode,
      valid: isValid
    });
  }
  
  return barcodes;
}

const bookCatalog = generateBookBarcodes(10);
console.log(`Generados ${bookCatalog.length} códigos ISBN válidos`);

Integración con sistema de inventario

import { SKUGenerator, BarcodeGenerator } from '@hemia/codex';

const skuGen = new SKUGenerator({ prefix: 'PROD-' });
const barcodeGen = new BarcodeGenerator();

class Product {
  sku: string;
  barcode: string;
  name: string;
  
  constructor(name: string, countryCode: string, manufacturerCode: string) {
    this.name = name;
    this.sku = skuGen.random();
    this.barcode = barcodeGen.generateEAN13(countryCode, manufacturerCode);
  }
  
  validate(): boolean {
    return barcodeGen.validateEAN13(this.barcode);
  }
}

// Crear productos con SKU y código de barras
const product1 = new Product('Laptop', '750', '12345');
console.log(`SKU: ${product1.sku}, Barcode: ${product1.barcode}, Valid: ${product1.validate()}`);
// SKU: PROD-A3F7B2K9, Barcode: 7501234512348, Valid: true

�🛠️ Scripts disponibles

| Script | Descripción | |--------------|----------------------------------| | npm run build | Compila el paquete con Rollup | | npm run test | Ejecuta pruebas con Jest | | npm run clean | Limpia la carpeta dist/ |