feat: add CSV export format support

- Add --format flag to choose between json and csv output
- Implement CSV converter in utils.ts
- Add format option to interactive mode
- Update README with CSV export examples
- Default format is json for backward compatibility

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: maxgfr

README.md

@@ -43,18 +43,32 @@ binance-historical download \
   --interval 4h \
   --start 2024-01-01 \
   --end 2024-12-31 \
-  --output ./data/
+  --output ./data/ \
+  --format json
+```
+
+Export as CSV:
+
+```sh
+binance-historical download \
+  --pair ETHUSDT \
+  --interval 1h \
+  --start 2024-01-01 \
+  --end 2024-01-31 \
+  --output ./data/ \
+  --format csv
 ```
 
 #### CLI Options
 
 | Option | Alias | Description |
-|--------|-------|-------------|
+| ------ | ----- | ----------- |
 | `--pair <symbol>` | `-p` | Trading pair (e.g., BTCUSDT, ETHUSDT) |
 | `--interval <interval>` | `-i` | Kline interval (1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w) |
 | `--start <date>` | `-s` | Start date (YYYY-MM-DD or ISO 8601) |
 | `--end <date>` | `-e` | End date (YYYY-MM-DD or ISO 8601) |
 | `--output <path>` | `-o` | Output directory path (filename is auto-generated) |
+| `--format <format>` | `-f` | Output format (json or csv, default: json) |
 | `--help` | `-h` | Display help |
 | `--version` | `-V` | Display version |
 

src/cli.ts

@@ -1,8 +1,8 @@
 import prompts from 'prompts';
-import type { PromptResult, BinanceInterval } from './types';
+import { Command } from 'commander';
+import type { BinanceInterval, OutputFormat, PromptResult } from './types';
 import { getKline } from './klines';
 import { formatDate, saveKline } from './utils';
-import { Command } from 'commander';
 
 const VALID_INTERVALS: BinanceInterval[] = [
   '1m',
@@ -68,6 +68,16 @@ const questions: Array<prompts.PromptObject> = [
     message: 'The path of the file that will be saved:',
     initial: `${process.cwd()}/`,
   },
+  {
+    type: 'select',
+    name: 'format',
+    message: 'Output format:',
+    choices: [
+      { title: 'JSON', value: 'json' },
+      { title: 'CSV', value: 'csv' },
+    ],
+    initial: 0,
+  },
 ];
 
 interface CliOptions {
@@ -76,12 +86,17 @@ interface CliOptions {
   start?: string;
   end?: string;
   output?: string;
+  format?: string;
 }
 
 function isValidInterval(interval: string): interval is BinanceInterval {
   return VALID_INTERVALS.includes(interval as BinanceInterval);
 }
 
+function isValidFormat(format: string): format is OutputFormat {
+  return format === 'json' || format === 'csv';
+}
+
 function parseDate(dateStr: string): Date | null {
   const date = new Date(dateStr);
   if (Number.isNaN(date.getTime())) {
@@ -122,6 +137,10 @@ function validateOptions(options: CliOptions): {
     }
   }
 
+  if (options.format && !isValidFormat(options.format)) {
+    errors.push(`Invalid format "${options.format}". Valid formats: json, csv`);
+  }
+
   return { valid: errors.length === 0, errors };
 }
 
@@ -131,14 +150,15 @@ function hasAllRequiredOptions(options: CliOptions): boolean {
     options.interval &&
     options.start &&
     options.end &&
-    options.output
+    options.output &&
+    options.format
   );
 }
 
 async function promptUser(): Promise<Partial<PromptResult>> {
-  const { pair, interval, startDate, endDate, fileName } =
+  const { pair, interval, startDate, endDate, fileName, format } =
     await prompts(questions);
-  return { pair, interval, startDate, endDate, fileName };
+  return { pair, interval, startDate, endDate, fileName, format };
 }
 
 async function promptMissingOptions(
@@ -187,6 +207,12 @@ async function promptMissingOptions(
     missingQuestions.push(questions[4]);
   }
 
+  if (options.format && isValidFormat(options.format)) {
+    providedValues.format = options.format;
+  } else {
+    missingQuestions.push(questions[5]);
+  }
+
   if (missingQuestions.length > 0) {
     const answers = await prompts(missingQuestions);
     return { ...providedValues, ...answers };
@@ -196,7 +222,7 @@ async function promptMissingOptions(
 }
 
 async function downloadKlines(config: PromptResult): Promise<void> {
-  const { pair, interval, startDate, endDate, fileName } = config;
+  const { pair, interval, startDate, endDate, fileName, format } = config;
 
   const kLines = await getKline(pair, interval, startDate, endDate).catch(
     (error) => {
@@ -206,10 +232,11 @@ async function downloadKlines(config: PromptResult): Promise<void> {
   );
 
   if (kLines) {
+    const extension = format === 'csv' ? 'csv' : 'json';
     const outputPath =
       fileName +
-      `${pair}_${interval}_${formatDate(startDate)}_${formatDate(endDate)}.json`;
-    saveKline(outputPath, kLines);
+      `${pair}_${interval}_${formatDate(startDate)}_${formatDate(endDate)}.${extension}`;
+    saveKline(outputPath, kLines, format);
     console.log(`Downloaded ${kLines.length} klines to ${outputPath}`);
   }
 }
@@ -229,16 +256,18 @@ async function processWithOptions(options: CliOptions): Promise<void> {
     const startDate = parseDate(options.start as string) as Date;
     const endDate = parseDate(options.end as string) as Date;
     const fileName = options.output as string;
+    const format = options.format as OutputFormat;
 
-    await downloadKlines({ pair, interval, startDate, endDate, fileName });
+    await downloadKlines({ pair, interval, startDate, endDate, fileName, format });
   } else {
     const result = await promptMissingOptions(options);
     if (
       !result.pair ||
       !result.interval ||
       !result.startDate ||
       !result.endDate ||
-      !result.fileName
+      !result.fileName ||
+      !result.format
     ) {
       console.error('Missing required information');
       process.exit(1);
@@ -254,7 +283,8 @@ async function processInteractive(): Promise<void> {
     !result.interval ||
     !result.startDate ||
     !result.endDate ||
-    !result.fileName
+    !result.fileName ||
+    !result.format
   ) {
     console.error('Missing required information');
     process.exit(1);
@@ -273,7 +303,7 @@ export async function runCommand(): Promise<void> {
   program
     .command('download')
     .description(
-      'Download a JSON file containing historical klines from Binance API',
+      'Download historical klines from Binance API',
     )
     .option('-p, --pair <symbol>', 'Trading pair (e.g., BTCUSDT, ETHUSDT)')
     .option(
@@ -286,6 +316,7 @@ export async function runCommand(): Promise<void> {
       '-o, --output <path>',
       'Output directory path (filename is auto-generated)',
     )
+    .option('-f, --format <format>', 'Output format (json, csv)', 'json')
     .action(async (options: CliOptions) => {
       const hasAnyOption =
         options.pair ||

src/types.ts

@@ -46,10 +46,13 @@ export type BinanceResponseData = [
   string,
 ];
 
+export type OutputFormat = 'json' | 'csv';
+
 export type PromptResult = {
   pair: string;
   interval: BinanceInterval;
   startDate: Date;
   endDate: Date;
   fileName: string;
+  format: OutputFormat;
 };

src/utils.ts

@@ -1,9 +1,51 @@
-import { BinanceInterval, Kline } from './types';
+import type { BinanceInterval, Kline, OutputFormat } from './types';
 
 import fs = require('fs');
 
-export const saveKline = (fileName: string, jsonArray: Array<Kline>) => {
-  fs.writeFileSync(fileName, JSON.stringify(jsonArray, null, 2));
+const convertToCSV = (klines: Array<Kline>): string => {
+  const headers = [
+    'openTime',
+    'open',
+    'high',
+    'low',
+    'close',
+    'volume',
+    'closeTime',
+    'quoteAssetVolume',
+    'trades',
+    'takerBaseAssetVolume',
+    'takerQuoteAssetVolume',
+    'ignored',
+  ].join(',');
+
+  const rows = klines.map((kline) =>
+    [
+      kline.openTime,
+      kline.open,
+      kline.high,
+      kline.low,
+      kline.close,
+      kline.volume,
+      kline.closeTime,
+      kline.quoteAssetVolume,
+      kline.trades,
+      kline.takerBaseAssetVolume,
+      kline.takerQuoteAssetVolume,
+      kline.ignored,
+    ].join(','),
+  );
+
+  return [headers, ...rows].join('\n');
+};
+
+export const saveKline = (
+  fileName: string,
+  jsonArray: Array<Kline>,
+  format: OutputFormat = 'json',
+): void => {
+  const content =
+    format === 'csv' ? convertToCSV(jsonArray) : JSON.stringify(jsonArray, null, 2);
+  fs.writeFileSync(fileName, content);
 };
 
 export const formatDate = (date: Date, withHour = false): string => {