Getting started

Welcome to TinyFrameJS — a tiny, lightning‑fast dataframe engine for JavaScript inspired by pandas.

---

Installation

Use your favourite package manager:

npm

npm install tinyframejs

pnpm

pnpm add tinyframejs

yarn

yarn add tinyframejs

CDN / ESM

<script type="module">
  import { DataFrame } from 'https://cdn.jsdelivr.net/npm/tinyframejs/+esm';
</script>

Works everywhere: Node ≥ 16, modern browsers, Vite / Webpack, Deno.

---

First 1‑minute example

src/quick-start.js

import { DataFrame } from 'tinyframejs';

const df = new DataFrame([
  {ticker: 'AAPL', price: 187.2},
  {ticker: 'MSFT', price: 413.9},
  {ticker: 'NVDA', price: 875.4}
]);

df
  .sort('price', {ascending: false})
  .head(2)
  .print();

┌───────┬────────┬────────┐
│ index │ ticker │ price  │
├───────┼────────┼────────┤
│   2   │ NVDA   │ 875.4  │
│   1   │ MSFT   │ 413.9  │
└───────┴────────┴────────┘

---

Intro tutorials

What kind of data does TinyFrameJS handle?

TinyFrameJS reads JavaScript arrays / objects and turns them into a DataFrame — a table with labelled columns and automatic dtype inference.

Go to intro tutorial

How do I read and write tabular data?

Use readCsv, readJson, readSql & friends to import, or the matching to* methods to export (CSV, JSON, Arrow, Parquet soon).

Learn I/O

How do I select a subset of a table?

df.filter(row => …) for boolean masks, df.select(['colA','colB']) for column projection, and SQL‑like df.query() for complex conditions.

Filter & select

How to create plots in TinyFrameJS?

df.plot.scatter('x','y') uses lightweight Chart.js under the hood. No heavy python stacks involved!

Plotting

How to manipulate and reshape tables?

With TinyFrameJS you can:

• Add new columns with df.assign()
• Apply transforms with df.apply()
• Sort with df.sort()
• Reshape with df.melt() / df.pivot()
• Group & aggregate with df.groupby().agg()

Transform data

How to join and merge datasets?

Use df1.join(df2, 'key') for SQL-like joins, or df1.concat(df2) to stack tables vertically. Supports inner, left, right, and outer joins.

Join & merge

How to optimize performance?

TinyFrameJS is already fast, but you can make it even faster with typed columns, lazy evaluation, and parallel processing.

Performance tips

---

Comparison with other libraries

Feature	TinyFrameJS	Pandas	Danfo.js
Size	12 KB†	~50 MB	~180 KB
Speed	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐
API	pandas-like	reference	pandas-like
Dependencies	zero native	heavy (numpy)	TensorFlow.js
TypeScript	100%	Python	partial

_{† minified + gzip.}

TinyFrameJS aims to offer pandas‑like ergonomics at a fraction of the size, with zero native dependencies and 🤏 minimal learning curve.

---

Under the hood: Architecture & Design

Why TinyFrameJS is different

TinyFrameJS was built from the ground up with a focus on performance, modularity, and developer experience. Here's what makes it special:

Optimized Core Architecture

TinyFrameJS uses a modular architecture that separates concerns:

• Core data structures — optimized for memory efficiency using TypedArrays
• DataFrame API — high-level interface for data manipulation
• Utility functions — standalone helpers that can be tree-shaken

This separation allows for better tree-shaking, smaller bundle sizes, and clearer code organization.

Performance Optimizations

Several techniques make TinyFrameJS fast:

• Typed Arrays — numeric data is stored in native JavaScript TypedArrays
• Lazy evaluation — operations are deferred until results are needed
• Column-oriented storage — enables faster column operations and better memory usage
• Minimal copying — views and references are used when possible to avoid data duplication

Clean API Design

The API is designed for clarity and consistency:

• Method chaining — fluent interface for composing operations
• Immutable operations — most methods return new DataFrames
• Familiar patterns — similar to pandas for easy adoption
• TypeScript support — full type definitions for better developer experience

Recommended Code Organization

When contributing to or extending TinyFrameJS, follow these principles:

• Core functions like createFrame and cloneFrame should focus only on data structure creation
• DataFrame methods should handle user-facing operations and transformations
• Utility functions should be pure and focused on a single task
• Avoid duplication — define logic in one place and reuse it

This approach makes the codebase more maintainable and easier to understand.

Example: Core Architecture Separation

// src/core/createFrame.js - Focused on creation and core structure
export function createFrame(data, options) {
  // Core data structure creation logic
}

// src/DataFrame.js - User-facing API
class DataFrame {
  constructor(data, options) {
    this._frame = createFrame(data, options);
  }
  
  // Methods that operate on the internal structure
  filter(predicate) {
    // Implementation using the internal _frame
  }
}

This separation keeps the codebase clean, testable, and maintainable while delivering excellent performance.

---

Community & next steps

• ⭐ Star the project on GitHub
• 📖 Read the full API Reference
• ✍🏻 Contribute tutorials — submit a PR to /docs/getting-started.

Dive into User Guide →