dataorganizer v1.0.10
DataOrganizer Documentation
The DataOrganizer class is a utility for organizing, transforming, and formatting data sets. It provides various methods to group, filter, modify, and format data, as well as to manage the history of operations performed on the data.
Table of Contents
Installation
To install the DataOrganizer class, run the following command:
npm i dataorganizer
This command installs the dataorganizer package, which includes the DataOrganizer class and its dependencies. You can then import and use the class in your TypeScript or JavaScript project as shown in the examples below.
To use the DataOrganizer, you need to import it into your TypeScript or JavaScript file.
import DataOrganizer from './path/to/DataOrganizer';
Ensure that all dependencies like formatters and utility functions (formatNumbers, getTimeRange, etc.) are properly implemented and imported in the project.
Constructor
new DataOrganizer(data: Data, options?: DataOrganizerOptions)
Parameters:
data: An array of data rows (each row is an object with key-value pairs).options: Optional configuration object (DataOrganizerOptions), which may include:headerDictionary: An optional dictionary for translating header keys.historySize: The maximum size of the history stack (default: 10).cellFormats: An optional mapping of keys to cell formatters.locale: Locale used for formatting (default: "en").decimals: Number of decimal places for number formatting (default: 3).
Example:
const data = [
{
id: 1,
name: "John Doe",
timestamp: "2024-01-01T10:00:00Z",
amount: 100.5,
profession: "Engineer",
},
{
id: 2,
name: "Jane Smith",
timestamp: "2024-01-02T12:30:00Z",
amount: 200.75,
profession: "Designer",
},
{
id: 3,
name: "Jane Doe",
timestamp: "2024-01-02T14:45:00Z",
amount: 150.0,
profession: "Engineer",
},
];
const options = {
locale: "en-US",
decimals: 2,
headerDictionary: {
id: "ID",
name: "Full Name",
timestamp: "Date",
amount: "Total",
},
};
const organizer = new DataOrganizer(data, options);Methods
getTables(showSummary?: Partial<Record<keyof Summary, boolean>>): TableData[]
Returns the current data sets as tables, optionally including summary data.
Parameters:
showSummary: An optional object specifying which summary metrics to display (total,min,max,average).
Returns:
- An array of
TableDataobjects.
Example:
const tables = organizer.getTables({ total: true, min: true }); console.log(tables);
getHistory(): DataSet[][]
Returns the history of data operations as an array of DataSet arrays.
Example:
const history = organizer.getHistory(); console.log(history);
getData(): DataSet[]
Returns the current data sets.
Example:
const dataSets = organizer.getData(); console.log(dataSets);
getOriginalData(): Data
Returns the original data passed to the constructor.
Example:
const originalData = organizer.getOriginalData(); console.log(originalData);
reset(): this
Resets the data organizer to its initial state.
Example:
organizer.reset();
undo(): this
Reverts the last data operation.
Example:
organizer.undo();
redo(): this
Re-applies the last undone data operation.
Example:
organizer.redo();
removeKey(key: keyof DataRow): this
Removes a specific key from all data rows.
Parameters:
key: The key to remove from each data row.
Example:
organizer.removeKey('name');
removeKeys(key: (keyof DataRow)[]): this
Removes a specific keys from all data rows.
Parameters:
keys: The keys to remove from each data row.
Example:
organizer.removeKeys(['name', 'timestamp']);
groupByDate<T extends keyof DataRow>(timeRange: TimeRange = 'DAY', key: T = 'timestamp' as T): this
Groups the data by a date key, optionally specifying a time range (e.g., DAY, MONTH, YEAR).
Parameters:
timeRange: The time range to group by (TimeRange).key: The date key to group by.
Example:
organizer.groupByDate('MONTH', 'timestamp');
groupByKey<T extends keyof DataRow>(key: T): this
Groups the data by a specific key.
Parameters:
key: The key to group by.
Example:
organizer.groupByKey('name');
groupByKeys<T extends keyof DataRow>(keys: T[]): this
Groups the data by multiple keys.
Parameters:
keys: An array of keys to group by.
Example:
organizer.groupByKeys(['name', 'timestamp']);
filterByKey<T extends keyof DataRow>(key: T, values: DataRow[T][]): this
Filters the data by a specific key and its values.
Parameters:
key: The key to filter by.values: An array of values to match.
Example:
organizer.filterByKey('id', [1, 2]);
contains(value: string): this
Filters the data to include only rows containing the specified value.
Parameters:
value: The value to search for.
Example:
organizer.contains('Doe');
modifyValue<T extends keyof DataRow>(key: T, callback: (value: any) => any): this
Modifies a specific key's values using a callback function.
Parameters:
key: The key whose values will be modified.callback: A function that takes the current value and returns the new value.
Example:
organizer.modifyValue('amount', (value) => value * 2);
sortByKey(key: keyof DataRow, direction: 'asc' | 'desc' = 'asc'): this
Sorts the data by a specific key in ascending or descending order.
Parameters:
key: The key to sort by.direction: The direction to sort (ascordesc).
Example:
organizer.sortByKey('timestamp', 'desc');
frequencyByKeysValue(keys: (keyof DataRow)[], frequencyKey: string = "frequency", aggregatesKey?: (keyof DataRow)[])
Calculates the frequency of each value for the specified keys, using the frequencyKey. Optionally, it can also aggregate additional values provided as an array in the aggregatesKey.
Parameters:
keys: The keys to calculate the frequency of.frequencyKey: The key to store the frequency. If not provided, all values will be aggregated into thefrequencyKeyvalue.aggregatesKey: The key to store the aggregated values. If not provided, all values will be aggregated into thefrequencyKeyvalue.
Example:
organizer.frequencyByKeysValue('profession');
reorderColumns(keys: (keyof DataRow)[], addMissing: boolean): void
Calculates the frequency of each value for the specified keys, using the frequencyKey. Optionally, it can also aggregate additional values provided as an array in the aggregatesKey.
Parameters:
keys: The keys to calculate the frequency of.frequencyKey: The key to store the frequency. If not provided, all values will be aggregated into thefrequencyKeyvalue.aggregatesKey: The key to store the aggregated values. If not provided, all values will be aggregated into thefrequencyKeyvalue.
Example:
organizer.frequencyByKeysValue('profession');
Examples
Basic Usage
const data = [
{
id: 1,
name: "John Doe",
timestamp: "2024-01-01T10:00:00Z",
amount: 100.5,
profession: "Engineer",
},
{
id: 2,
name: "Jane Smith",
timestamp: "2024-01-02T12:30:00Z",
amount: 200.75,
profession: "Designer",
},
{
id: 3,
name: "Jane Doe",
timestamp: "2024-01-02T14:45:00Z",
amount: 150.0,
profession: "Engineer",
},
];
const organizer = new DataOrganizer(data); // Group by date
organizer.groupByDate("DAY", "timestamp"); // Filter by ID
organizer.filterByKey("id", [1]); // Get tables with summary
const tablesWithSummary = organizer.getTables({total: true, min: true});
console.log(tablesWithSummary); // Modify values
organizer.modifyValue("amount", (value) => value + 10);Advanced Usage
// Group by multiple keys
organizer.groupByKeys(["name", "timestamp"]); // Remove a key
organizer.removeKey("id"); // Check data history
const history = organizer.getHistory();
console.log(history); // Undo the last operation
organizer.undo(); // Redo the last operation
organizer.redo();Working with History
// Perform some operations
organizer.sortByKey('amount');
organizer.modifyValue('amount', (value) => value - 5); // Undo the last modification
organizer.undo(); // Get the current state of data
const currentData = organizer.getData(); console.log(currentData); // Redo the last modification
organizer.redo();