ccusage / data-loader
data-loader
Fileoverview
Data loading utilities for Claude Code usage analysis
This module provides functions for loading and parsing Claude Code usage data from JSONL files stored in Claude data directories. It handles data aggregation for daily, monthly, and session-based reporting.
Variables
| Variable | Description |
|---|---|
| usageDataSchema | Zod schema for validating Claude usage data from JSONL files |
| modelBreakdownSchema | Zod schema for model-specific usage breakdown data |
| dailyUsageSchema | Zod schema for daily usage aggregation data |
| sessionUsageSchema | Zod schema for session-based usage aggregation data |
| monthlyUsageSchema | Zod schema for monthly usage aggregation data |
Functions
| Function | Description |
|---|---|
| getClaudePaths | Get all Claude data directories to search for usage data Supports multiple paths: environment variable (comma-separated), new default, and old default |
| formatDate | Formats a date string to YYYY-MM-DD format |
| formatDateCompact | Formats a date string to compact format with year on first line and month-day on second |
| createUniqueHash | Create a unique identifier for deduplication using message ID and request ID |
| getEarliestTimestamp | Extract the earliest timestamp from a JSONL file Scans through the file until it finds a valid timestamp |
| sortFilesByTimestamp | Sort files by their earliest timestamp Files without valid timestamps are placed at the end |
| calculateCostForEntry | Calculates cost for a single usage data entry based on the specified cost calculation mode |
| loadDailyUsageData | Loads and aggregates Claude usage data by day Processes all JSONL files in the Claude projects directory and groups usage by date |
| loadSessionData | Loads and aggregates Claude usage data by session Groups usage data by project path and session ID based on file structure |
| loadMonthlyUsageData | Loads and aggregates Claude usage data by month Uses daily usage data as the source and groups by month |
| loadSessionBlockData | Loads usage data and organizes it into session blocks (typically 5-hour billing periods) Processes all usage data and groups it into time-based blocks for billing analysis |
Type Aliases
| Type Alias | Description |
|---|---|
| UsageData | Type definition for Claude usage data entries from JSONL files |
| ModelBreakdown | Type definition for model-specific usage breakdown |
| DailyUsage | Type definition for daily usage aggregation |
| SessionUsage | Type definition for session-based usage aggregation |
| MonthlyUsage | Type definition for monthly usage aggregation |
| DateFilter | Date range filter for limiting usage data by date |
| LoadOptions | Configuration options for loading usage data |