Getting Started

Installation

npm install aggregator-toy
# or
pnpm add aggregator-toy
# or
yarn add aggregator-toy

Your First Pipeline

Let's build a simple pipeline that groups sales by category and sums the prices.

1. Define Your Data Type

interface Sale {
  category: string;
  product: string;
  price: number;
}

2. Create the Pipeline

import { createPipeline } from "aggregator-toy";

const builder = createPipeline<Sale>()
  .groupBy(["category"], "items")
  .sum("items", "price", "totalRevenue");

3. Connect State Management

// Get the type descriptor
const typeDescriptor = builder.getTypeDescriptor();

// Create state storage
let state = [];

// Build the pipeline with a state updater
const pipeline = builder.build(
  transform => { state = transform(state); },
  typeDescriptor
);

4. Add Data

pipeline.add("sale1", { category: "Electronics", product: "Phone", price: 500 });
pipeline.add("sale2", { category: "Electronics", product: "Laptop", price: 1200 });
pipeline.add("sale3", { category: "Clothing", product: "Shirt", price: 50 });

console.log(state);
// [
//   { key: "hash1", value: { category: "Electronics", totalRevenue: 1700, items: [...] } },
//   { key: "hash2", value: { category: "Clothing", totalRevenue: 50, items: [...] } }
// ]

5. Remove Data

pipeline.remove("sale1");

console.log(state);
// [
//   { key: "hash1", value: { category: "Electronics", totalRevenue: 1200, items: [...] } },
//   { key: "hash2", value: { category: "Clothing", totalRevenue: 50, items: [...] } }
// ]

Using with React

import { useState, useEffect } from "react";
import { createPipeline } from "aggregator-toy";

function usePipeline() {
  const [state, setState] = useState([]);
  const [pipeline] = useState(() => {
    const builder = createPipeline<Sale>()
      .groupBy(["category"], "items")
      .sum("items", "price", "totalRevenue");
    
    const typeDescriptor = builder.getTypeDescriptor();
    return builder.build(
      transform => setState(s => transform(s)),
      typeDescriptor
    );
  });

  return { state, pipeline };
}

function Dashboard() {
  const { state, pipeline } = usePipeline();

  return (
    <ul>
      {state.map(category => (
        <li key={category.key}>
          {category.value.category}: ${category.value.totalRevenue}
        </li>
      ))}
    </ul>
  );
}

Next Steps

• Core Concepts - Understand how pipelines work
• Vote Leaderboard - A more complex example
• API Reference - Complete API documentation