vtlab-importer-core

Núcleo genérico para lambdas de importación asíncrona de entidades (template method + hooks), agnóstico de infraestructura vía inyección de dependencias (S3, SQS, Mongo).

• Runtime: CommonJS, target Node.js 18+.
• Vos escribís map() (y opcionalmente algunos hooks); la clase base se encarga del resto del pipeline: descargar el archivo, parsearlo, validar, deduplicar, guardar y encolar.

Instalación

npm install vtlab-importer-core

# peer deps que provee tu lambda
npm install @aws-sdk/client-s3 @aws-sdk/client-sqs

Uso básico

const Joi = require('joi');
const { LambdaImporter, IMPORT_PROCESS_STATUS } = require('vtlab-importer-core');

class MyImporter extends LambdaImporter {
  // Único método obligatorio: recibe todas las filas parseadas, devuelve todas las entidades.
  async map(rows, ctx) {
    return rows.map((row, index) => ({
      index,
      payload: {
        accountUuid: ctx.accountUuid,
        docReference: row.docReference,
      },
    }));
  }

  // Validación opcional con Joi.
  get schemas() {
    return {
      default: Joi.object({
        accountUuid: Joi.string().required(),
        docReference: Joi.string().required(),
      }).unknown(true),
    };
  }
}

exports.handler = async (event) => {
  const importer = new MyImporter({
    s3Client,
    sqsClient,
    bucket: process.env.IMPORT_BUCKET,
    creationQueueUrl: process.env.CREATION_QUEUE_URL,
    db, // conexión Mongo; la clase arma los adapters por default
    logger: { log: (msg, meta) => console.log(msg, JSON.stringify(meta || {})) },
  });
  const result = await importer.handle(event);
  if (result.status === IMPORT_PROCESS_STATUS.FAILED) {
    return { success: false, error: { message: 'Import processing failed' }, result };
  }
  return { success: true, result };
};

handle() devuelve el resumen del pipeline. El handler de la Lambda lo envuelve en { success, result }, que es el contrato esperado por el Import Worker.

Ver examples/ para casos completos: StandardCsvImporter.js (el mínimo) y JobsImporterLambda.js (con hooks y agrupación N:1).

Qué resuelve

• Descarga del archivo desde S3 (xlsx, csv, txt) con detección de encoding y separador.
• Resolución de referencias por lote (sin N+1) contra colecciones Mongo.
• Validación por fila con Joi, acumulando todos los errores.
• Deduplicación (hook opcional).
• Persistencia de las entidades y encolado en SQS, con fallback a S3 para payloads grandes.
• Seguimiento del envío en ImportEntity.queue (pending, sent o failed, intentos, error y fecha confirmada por SQS).

Dependencias

• dependencies: csvtojson, node-xlsx, jschardet, iconv-lite, joi, camelcase, iso-datestring-validator.
• peerDependencies: @aws-sdk/client-s3, @aws-sdk/client-sqs.
• mongodb no es una dependencia del package.

Tests

npm test

Licencia

UNLICENSED — uso interno.