feat: add print method for DataFrame display

Author: a3ka

.changeset/short-owls-tap.md

@@ -0,0 +1,25 @@
+---
+'tinyframejs': major
+---
+
+# First minimal working version
+
+## WHAT
+This is the first stable release of TinyFrameJS with a complete API for DataFrame operations. Major changes include:
+- Replacement of the vulnerable xlsx library (v0.18.5) with exceljs (v4.4.0)
+- Fixed imports of non-existent modules
+- Added proper export of the cloneFrame function
+- Fixed bug in sort.js where it called non-existent frame.clone() method
+
+## WHY
+These changes were necessary to:
+- Address security vulnerabilities in the xlsx dependency
+- Fix critical bugs that prevented proper library usage
+- Ensure consistent API across the library
+- Improve overall stability and reliability
+
+## HOW TO UPDATE
+If you were using a previous version:
+- Replace any calls to frame.clone() with cloneFrame(frame)
+- If you were directly using xlsx functionality, update to the exceljs API
+- Review any import statements that might have been relying on the previously non-existent modules

.npmignore

@@ -42,3 +42,13 @@ benchmarks/
 
 # Dependencies
 node_modules/
+build/
+dist/
+.DS_Store
+
+# Documentation
+../tinyframejs-docs/
+tinyframejs-docs/
+docs-site/
+docs/
+typedoc.json

examples/print-example.js

@@ -0,0 +1,41 @@
+// examples/print-example.js
+
+import { DataFrame } from '../src/core/DataFrame.js';
+
+// Create test data
+const data = [
+  { name: 'Alice', age: 25, city: 'New York', salary: 75000 },
+  { name: 'Bob', age: 30, city: 'Boston', salary: 85000 },
+  { name: 'Charlie', age: 35, city: 'Chicago', salary: 95000 },
+  { name: 'David', age: 40, city: 'Denver', salary: 105000 },
+  { name: 'Eve', age: 45, city: 'El Paso', salary: 115000 },
+  { name: 'Frank', age: 50, city: 'Fresno', salary: 125000 },
+  { name: 'Grace', age: 55, city: 'Greensboro', salary: 135000 },
+  { name: 'Hannah', age: 60, city: 'Houston', salary: 145000 },
+  { name: 'Ian', age: 65, city: 'Indianapolis', salary: 155000 },
+  { name: 'Julia', age: 70, city: 'Jacksonville', salary: 165000 },
+  { name: 'Kevin', age: 75, city: 'Kansas City', salary: 175000 },
+  { name: 'Laura', age: 80, city: 'Los Angeles', salary: 185000 },
+];
+
+// Create DataFrame
+const df = DataFrame.create(data);
+
+// Use the print method to display data in the console
+console.log('Standard output (default 10 rows):');
+df.print();
+
+console.log('\nOutput with row limit:');
+df.print({ maxRows: 5 });
+
+console.log('\nOutput with column limit:');
+df.print({ maxCols: 2 });
+
+console.log('\nOutput without indices:');
+df.print({ showIndex: false });
+
+console.log('\nFull output:');
+df.print({ maxRows: 20, maxCols: 10 });
+
+// Example of using in a method chain (when they are implemented)
+// df.sort('age').filter(row => row.salary > 100000).print();

src/methods/display/index.js

@@ -0,0 +1 @@
+export { print } from './print.js';

src/methods/display/print.js

@@ -0,0 +1,99 @@
+/**
+ * Formats the DataFrame as a string table for console display.
+ * @param frame
+ * @param {Object} options - Display options
+ * @param {number} [options.maxRows=10] - Maximum number of rows to display
+ * @param {number} [options.maxCols=Infinity] - Maximum number of columns to display
+ * @param {boolean} [options.showIndex=true] - Whether to show row indices
+ * @returns {string} Formatted table string
+ */
+function formatTable(frame, options = {}) {
+  const { maxRows = 10, maxCols = Infinity, showIndex = true } = options;
+
+  // Convert frame to array of objects for easier processing
+  const columns = Object.keys(frame.columns);
+  const rowCount = frame.rowCount;
+  const columnNames = columns.slice(0, maxCols);
+
+  // Create data array with limited rows
+  const data = [];
+  for (let i = 0; i < Math.min(rowCount, maxRows); i++) {
+    const row = {};
+    for (const name of columnNames) {
+      row[name] = frame.columns[name][i];
+    }
+    data.push(row);
+  }
+
+  // Calculate column widths
+  const colWidths = {};
+  columnNames.forEach((col) => {
+    colWidths[col] = Math.max(
+      String(col).length,
+      ...data.map((row) => String(row[col] ?? '').length),
+    );
+  });
+
+  if (showIndex) {
+    const indexWidth = String(data.length - 1).length;
+    colWidths['index'] = Math.max(indexWidth, 5); // Minimum width for index column
+  }
+
+  // Build header
+  let result = '';
+  if (showIndex) {
+    result += ' '.repeat(colWidths['index'] + 1) + '| ';
+  }
+
+  columnNames.forEach((col) => {
+    result += String(col).padEnd(colWidths[col] + 2);
+  });
+  result += '\n';
+
+  // Add separator
+  if (showIndex) {
+    result += '-'.repeat(colWidths['index'] + 1) + '+ ';
+  }
+
+  columnNames.forEach((col) => {
+    result += '-'.repeat(colWidths[col] + 2);
+  });
+  result += '\n';
+
+  // Add data rows
+  data.forEach((row, i) => {
+    if (showIndex) {
+      result += String(i).padStart(colWidths['index']) + ' | ';
+    }
+
+    columnNames.forEach((col) => {
+      result += String(row[col] ?? '').padEnd(colWidths[col] + 2);
+    });
+    result += '\n';
+  });
+
+  // Add footer if there are more rows
+  if (rowCount > maxRows) {
+    result += `\n... ${rowCount - maxRows} more rows`;
+  }
+
+  // Add footer if there are more columns
+  if (columns.length > maxCols) {
+    result += `\n... ${columns.length - maxCols} more columns`;
+  }
+
+  return result;
+}
+
+/**
+ * Prints the DataFrame to the console.
+ * @param {{ validateColumn(frame, column): void }} deps
+ * @returns {(frame: TinyFrame, options?: Object) => void}
+ */
+export const print =
+  () =>
+  (frame, options = {}) => {
+    const formattedTable = formatTable(frame, options);
+    console.log(formattedTable);
+    return frame; // Return the frame for method chaining
+  };

src/methods/raw.js

@@ -4,3 +4,4 @@ export { count } from './aggregation/count.js';
 export { mean } from './aggregation/mean.js';
 export { sort } from './aggregation/sort.js';
 export { first } from './aggregation/first.js';
+export { print } from './display/print.js';

test/methods/display/print.test.js

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi } from 'vitest';
+import { DataFrame } from '../../../src/core/DataFrame.js';
+import { print } from '../../../src/methods/display/print.js';
+
+describe('DataFrame print method', () => {
+  // Create test data frame
+  const testData = [
+    { name: 'Alice', age: 25, city: 'New York' },
+    { name: 'Bob', age: 30, city: 'Boston' },
+    { name: 'Charlie', age: 35, city: 'Chicago' },
+    { name: 'David', age: 40, city: 'Denver' },
+    { name: 'Eve', age: 45, city: 'El Paso' },
+  ];
+
+  const df = DataFrame.create(testData);
+
+  it('should format data as a table string', () => {
+    // Mock console.log to check output
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    // Call print function directly
+    const printFn = print();
+    printFn(df._frame);
+
+    // Check that console.log was called
+    expect(consoleSpy).toHaveBeenCalled();
+
+    // Get the argument passed to console.log
+    const output = consoleSpy.mock.calls[0][0];
+
+    // Check that the output contains column headers
+    expect(output).toContain('name');
+    expect(output).toContain('age');
+    expect(output).toContain('city');
+
+    // Check that the output contains data
+    expect(output).toContain('Alice');
+    expect(output).toContain('25');
+    expect(output).toContain('New York');
+
+    // Restore console.log
+    consoleSpy.mockRestore();
+  });
+
+  it('should return the frame for method chaining', () => {
+    // Mock console.log
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    // Call print function directly
+    const printFn = print();
+    const result = printFn(df._frame);
+
+    // Check that the function returns the frame
+    expect(result).toBe(df._frame);
+
+    // Restore console.log
+    consoleSpy.mockRestore();
+  });
+
+  it('should respect maxRows option', () => {
+    // Create a frame with many rows
+    const largeData = Array.from({ length: 20 }, (_, i) => ({
+      id: i,
+      value: i * 10,
+    }));
+
+    const largeDf = DataFrame.create(largeData);
+
+    // Mock console.log
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    // Call print function with row limit
+    const printFn = print();
+    printFn(largeDf._frame, { maxRows: 5 });
+
+    // Get the output
+    const output = consoleSpy.mock.calls[0][0];
+
+    // Check that the output contains message about additional rows
+    expect(output).toContain('more rows');
+
+    // Restore console.log
+    consoleSpy.mockRestore();
+  });
+
+  it('should respect maxCols option', () => {
+    // Create a frame with many columns
+    const wideData = [{ col1: 1, col2: 2, col3: 3, col4: 4, col5: 5, col6: 6 }];
+
+    const wideDf = DataFrame.create(wideData);
+
+    // Mock console.log
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    // Call print function with column limit
+    const printFn = print();
+    printFn(wideDf._frame, { maxCols: 3 });
+
+    // Get the output
+    const output = consoleSpy.mock.calls[0][0];
+
+    // Check that the output contains message about additional columns
+    expect(output).toContain('more columns');
+
+    // Restore console.log
+    consoleSpy.mockRestore();
+  });
+});

tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": false,
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*"]
+}