feat: replace console output with structured pino logging (#48)

## Summary
- replace runtime console logging with structured Pino logging
- add optional custom logger support in transformer options and
TypeScript types
- apply the same logging pattern to tests, examples, and release script
- update documentation snippets to use structured logging examples

## Validation
- [x] yarn lint
- [x] yarn test
- [x] yarn test:cross-version
- [x] yarn test:types

## Notes
- includes a dedicated changeset: .changeset/pino-structured-logging.md

Author: walterra

.changeset/pino-structured-logging.md

@@ -0,0 +1,5 @@
+---
+"node-es-transformer": minor
+---
+
+Replace console logging with structured Pino logging and add optional custom logger support.

PERFORMANCE.md

@@ -292,17 +292,20 @@ GET /_cluster/health
 Track ingestion progress using events:
 
 ```javascript
+const pino = require('pino');
+const logger = pino({ name: 'my-app', level: process.env.LOG_LEVEL || 'info' });
+
 const result = await transformer({
   /* options */
 });
 
 let indexed = 0;
 result.events.on('indexed', count => {
   indexed += count;
-  console.log(`Indexed: ${indexed}`);
+  logger.info({ indexed }, 'Progress update');
 });
 
 result.events.on('complete', () => {
-  console.log(`Total: ${indexed} documents`);
+  logger.info({ indexed }, 'Ingestion complete');
 });
 ```

README.md

@@ -387,7 +387,8 @@ When `inferMappings` is enabled, the target cluster must allow `/_text_structure
   - Parquet/Arrow: ignored
   - Default: `false`
   - Applies only to `fileName`/`stream` sources
-- **`verbose`** (boolean): Enable logging and progress bars. Default: `true`.
+- **`verbose`** (boolean): Enable verbose logging and progress bars when using the built-in logger. Default: `true`.
+- **`logger`** (object): Optional custom Pino-compatible logger. If omitted, the library creates an internal Pino logger (`name: node-es-transformer`) and uses `LOG_LEVEL` (if set) or `info`/`error` based on `verbose`.
 
 ### Return Value
 
@@ -400,16 +401,19 @@ The `transformer()` function returns a Promise that resolves to an object with:
   - `'error'`: Error occurred
 
 ```javascript
+const pino = require('pino');
+const logger = pino({ name: 'my-app', level: process.env.LOG_LEVEL || 'info' });
+
 const result = await transformer({
   /* options */
 });
 
 result.events.on('complete', () => {
-  console.log('Ingestion complete!');
+  logger.info('Ingestion complete');
 });
 
 result.events.on('error', err => {
-  console.error('Error:', err);
+  logger.error({ err }, 'Ingestion failed');
 });
 ```
 
@@ -447,20 +451,23 @@ See [examples/typescript-example.ts](examples/typescript-example.ts) for more ex
 Always handle errors when using the library:
 
 ```javascript
+const pino = require('pino');
+const logger = pino({ name: 'my-app', level: process.env.LOG_LEVEL || 'info' });
+
 transformer({
   /* options */
 })
-  .then(() => console.log('Success'))
-  .catch(err => console.error('Error:', err));
+  .then(() => logger.info('Success'))
+  .catch(err => logger.error({ err }, 'Transformer failed'));
 
 // Or with async/await
 try {
   await transformer({
     /* options */
   });
-  console.log('Success');
+  logger.info('Success');
 } catch (err) {
-  console.error('Error:', err);
+  logger.error({ err }, 'Transformer failed');
 }
 ```
 

RELEASE.md

@@ -203,8 +203,8 @@ npm init -y
 # Install latest version
 npm install node-es-transformer
 
-# Verify version
-node -e "console.log(require('node-es-transformer'))"
+# Verify package can be required
+node -e "require('node-es-transformer')"
 
 # Check TypeScript definitions exist
 ls node_modules/node-es-transformer/index.d.ts

__tests__/cross_version_reindex.test.js

@@ -11,6 +11,12 @@ const transformer = require('../dist/node-es-transformer.cjs');
 const { Client: Client8 } = require('es8');
 const { Client: Client9 } = require('es9');
 const { readFileSync } = require('fs');
+const pino = require('pino');
+
+const logger = pino({
+  name: 'node-es-transformer-test',
+  level: process.env.LOG_LEVEL || 'info',
+});
 
 const testIndexPrefix = 'test-cross-version-';
 
@@ -34,8 +40,8 @@ describe('Cross-version reindexing (ES 8.x to 9.x)', () => {
     client8 = new Client8({ node: url8 });
     client9 = new Client9({ node: url9 });
 
-    console.log(`Testing with ES 8.x at ${url8}`);
-    console.log(`Testing with ES 9.x at ${url9}`);
+    logger.info({ url8 }, 'Testing with ES 8.x');
+    logger.info({ url9 }, 'Testing with ES 9.x');
   });
 
   afterAll(async () => {

__tests__/utils/elasticsearch.js

@@ -2,6 +2,12 @@ const { Client: Client9 } = require('es9');
 const { Client: Client8 } = require('es8');
 const fs = require('fs');
 const path = require('path');
+const pino = require('pino');
+
+const logger = pino({
+  name: 'node-es-transformer-test',
+  level: process.env.LOG_LEVEL || 'info',
+});
 
 /**
  * Get Elasticsearch URL from testcontainer config file or fallback to localhost
@@ -14,8 +20,8 @@ function getElasticsearchUrl() {
     try {
       const config = JSON.parse(fs.readFileSync(configFile, 'utf-8'));
       return config.url;
-    } catch (error) {
-      console.warn('Failed to read testcontainer config, falling back to localhost:', error);
+    } catch (err) {
+      logger.warn({ err }, 'Failed to read testcontainer config, falling back to localhost');
     }
   }
 

examples/README.md

@@ -103,9 +103,12 @@ transformer({
 Wrap transformer calls with try/catch or use .catch():
 
 ```javascript
+const pino = require('pino');
+const logger = pino({ name: 'my-app', level: process.env.LOG_LEVEL || 'info' });
+
 transformer({ /* options */ })
-  .then(() => console.log('Success!'))
-  .catch(err => console.error('Error:', err));
+  .then(() => logger.info('Success'))
+  .catch(err => logger.error({ err }, 'Transformer failed'));
 ```
 
 ### Progress Monitoring

examples/_logger.js

@@ -0,0 +1,13 @@
+const pino = require('pino');
+
+const logger = pino({
+  name: 'node-es-transformer-example',
+  level: process.env.LOG_LEVEL || 'info',
+  timestamp: pino.stdTimeFunctions.isoTime,
+  serializers: {
+    err: pino.stdSerializers.err,
+    error: pino.stdSerializers.err,
+  },
+});
+
+module.exports = logger;

examples/basic-file-ingestion.js

@@ -1,11 +1,12 @@
 /**
  * Basic File Ingestion Example
- * 
+ *
  * Demonstrates how to ingest a JSON or CSV file into Elasticsearch
  * with custom field mappings.
  */
 
 const transformer = require('node-es-transformer');
+const logger = require('./_logger');
 
 // Example 1: Ingest JSON file
 transformer({
@@ -14,24 +15,26 @@ transformer({
   mappings: {
     properties: {
       '@timestamp': {
-        type: 'date'
+        type: 'date',
       },
-      'user_name': {
-        type: 'keyword'
+      user_name: {
+        type: 'keyword',
       },
-      'message': {
-        type: 'text'
+      message: {
+        type: 'text',
       },
-      'count': {
-        type: 'integer'
-      }
-    }
-  }
-}).then(() => {
-  console.log('Ingestion complete!');
-}).catch(err => {
-  console.error('Error during ingestion:', err);
-});
+      count: {
+        type: 'integer',
+      },
+    },
+  },
+})
+  .then(() => {
+    logger.info('Ingestion complete');
+  })
+  .catch(err => {
+    logger.error({ err }, 'Error during ingestion');
+  });
 
 // Example 2: Ingest with custom Elasticsearch connection
 /*

examples/cross-version-reindex.js

@@ -1,42 +1,45 @@
 /**
  * Cross-Version Reindex Example
- * 
+ *
  * Demonstrates reindexing from Elasticsearch 8.x to 9.x.
  * The library automatically detects the ES version and uses the appropriate client.
  */
 
 const transformer = require('node-es-transformer');
+const logger = require('./_logger');
 
 // Example 1: Auto-detection (recommended)
 transformer({
   sourceClientConfig: {
     node: 'https://es8-cluster.example.com:9200',
     auth: {
-      apiKey: process.env.ES8_API_KEY
-    }
+      apiKey: process.env.ES8_API_KEY,
+    },
   },
   targetClientConfig: {
     node: 'https://es9-cluster.example.com:9200',
     auth: {
-      apiKey: process.env.ES9_API_KEY
-    }
+      apiKey: process.env.ES9_API_KEY,
+    },
   },
   sourceIndexName: 'my-index-v1',
   targetIndexName: 'my-index-v1',
-  
+
   // Optional: Transform data during migration
   transform(doc) {
     // Clean up deprecated fields, add new fields, etc.
     return {
       ...doc,
-      migrated_at: new Date().toISOString()
+      migrated_at: new Date().toISOString(),
     };
-  }
-}).then(() => {
-  console.log('Cross-version reindex complete!');
-}).catch(err => {
-  console.error('Error during cross-version reindex:', err);
-});
+  },
+})
+  .then(() => {
+    logger.info('Cross-version reindex complete');
+  })
+  .catch(err => {
+    logger.error({ err }, 'Error during cross-version reindex');
+  });
 
 // Example 2: Using pre-instantiated clients (advanced)
 /*