UUID Reference Generator

Una librería de NestJS para generar referencias únicas con formato personalizable.

Compatible con NestJS 11.x

Requisitos

• NestJS 11.0.0 o superior
• Node.js 18 o superior
• TypeScript 5.0 o superior

Instalación

npm install uuid-reference-generator

Uso

Importar el módulo

import { Module } from '@nestjs/common';
import { UuidReferenceGeneratorModule } from 'uuid-reference-generator';

@Module({
  imports: [UuidReferenceGeneratorModule],
})
export class AppModule {}

Inyectar el servicio

import { Injectable } from '@nestjs/common';
import { UuidReferenceGeneratorService } from 'uuid-reference-generator';

@Injectable()
export class MyService {
  constructor(
    private readonly referenceGenerator: UuidReferenceGeneratorService,
  ) {}

  generateRef() {
    // Genera una referencia con valores por defecto (30 caracteres, prefijo "REF")
    const defaultRef = this.referenceGenerator.generateReference();
    // Ejemplo: REF-20250822-bhsxlzo5ylp915g0u (30 caracteres)

    // Genera una referencia con prefijo personalizado (mantiene 30 caracteres)
    const customPrefix = this.referenceGenerator.generateReference({ 
      prefix: 'MEDRF' 
    });
    // Ejemplo: MEDRF-20250822-cem9byrf29zmpi2 (30 caracteres)

    // Genera una referencia con longitud personalizada
    const customLength = this.referenceGenerator.generateReference({ 
      length: 25 
    });
    // Ejemplo: REF-20250822-35b4mm2rwout (25 caracteres)

    // Genera una referencia completamente personalizada
    const custom = this.referenceGenerator.generateReference({ 
      prefix: 'MEDRF', 
      length: 35 
    });
    // Ejemplo: MEDRF-20250822-w3bg0g4058i6gwl2jq1q (35 caracteres)

    return { defaultRef, customPrefix, customLength, custom };
  }
}

API

generateReference(options?: ReferenceOptions): string

Genera una referencia con el formato: PREFIJO-AAAAMMDD-ALEATORIO

Parámetros

• options (opcional): Objeto con las siguientes propiedades:
  • prefix (string, opcional): Prefijo personalizado. Por defecto: "REF"
  • length (number, opcional): Longitud total de la referencia. Por defecto: 30

Retorna

Una cadena con la referencia generada.

validateReference(reference: string): boolean

Valida si una referencia tiene el formato correcto.

Parámetros

• reference (string): La referencia a validar

Retorna

true si la referencia es válida, false en caso contrario.

parseReference(reference: string): { prefix: string; date: string; random: string } | null

Extrae las partes de una referencia válida.

Parámetros

• reference (string): La referencia a analizar

Retorna

Un objeto con las partes de la referencia o null si es inválida.

Ejemplos

const service = new UuidReferenceGeneratorService();

// Referencia por defecto (30 caracteres)
const ref1 = service.generateReference();
// "REF-20250822-bhsxlzo5ylp915g0u"

// Con prefijo personalizado (30 caracteres)
const ref2 = service.generateReference({ prefix: 'MEDRF' });
// "MEDRF-20250822-cem9byrf29zmpi2"

// Con longitud personalizada (20 caracteres)
const ref3 = service.generateReference({ length: 20 });
// "REF-20250822-yy0sfqr"

// Validación
const isValid = service.validateReference(ref1); // true

// Análisis
const parsed = service.parseReference(ref1);
// { prefix: 'REF', date: '20250822', random: 'bhsxlzo5ylp915g0u' }

Estructura de la Referencia

La referencia generada sigue el formato: PREFIJO-AAAAMMDD-ALEATORIO

• PREFIJO: Identificador personalizable (por defecto "REF")
• AAAAMMDD: Fecha actual en formato año-mes-día (8 caracteres)
• ALEATORIO: Cadena aleatoria de caracteres alfanuméricos en minúsculas para completar la longitud especificada

Cálculo de Longitudes

La longitud total se distribuye de la siguiente manera:

• PREFIJO + - + AAAAMMDD + - + ALEATORIO = Longitud total
• La parte aleatoria se ajusta automáticamente: longitud_aleatoria = longitud_total - longitud_prefijo - 1 - 8 - 1

Ejemplos de cálculo:

• REF-20250822-random: 3 + 1 + 8 + 1 + 17 = 30 caracteres
• MEDRF-20250822-random: 5 + 1 + 8 + 1 + 15 = 30 caracteres
• REF-20250822-random: 3 + 1 + 8 + 1 + 7 = 20 caracteres

Desarrollo

Compilar

npm run build

Ejecutar tests

npm test

Ejecutar tests en modo watch

npm run test:watch

Coverage de tests

npm run test:coverage

Licencia

MIT