@rokkit/data 1.0.1 → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jerry Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/benchmark/fixtures.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Generate sales rows: { region, product, year, revenue, units, status }
+ */
+export function generateSalesData(n: any): {
+    region: string;
+    product: string;
+    year: number;
+    revenue: number;
+    units: number;
+    status: string;
+}[];
+/**
+ * Generate orders/customers pair for join benchmarks.
+ */
+export function generateJoinData(n: any): {
+    customers: {
+        id: number;
+        name: string;
+        tier: string;
+    }[];
+    orders: {
+        orderId: number;
+        customerId: number;
+        amount: number;
+        year: number;
+    }[];
+};
+export function generateAlignData(n: any): {
+    revenue: number;
+    region: string;
+    product: string;
+    year: number;
+}[];

package/dist/benchmark/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/benchmark/runner.d.ts

@@ -0,0 +1,10 @@
+export function runBenchmarks(phase?: string): {
+    phase: string;
+    timestamp: string;
+    environment: {
+        runtime: string;
+        platform: NodeJS.Platform;
+        arch: NodeJS.Architecture;
+    };
+    results: never[];
+};

package/dist/src/aggregators.d.ts

@@ -0,0 +1,2 @@
+export function counter(values: any[]): number;
+export function violin(values: number[]): Object;

package/dist/src/constants.d.ts

@@ -0,0 +1,45 @@
+export function pickAllowedConfig(obj: any): {};
+/** @type {import('./types').DataFrameConfig */
+export const defaultConfig: import("./types").DataFrameConfig;
+export namespace defaultPathOptions {
+    let path: null;
+    let separator: string;
+    let currencySuffix: string;
+}
+export namespace defaultViewOptions {
+    let expanded: boolean;
+    let actions: never[];
+    let language: string;
+    let scanMode: string;
+}
+export namespace defaultActionOrder {
+    export let select: number;
+    export let edit: number;
+    let _delete: number;
+    export { _delete as delete };
+}
+/**
+ * Returns the default properties for a column
+ * @param {string} key - the key to use for the column
+ * @returns {Object} the default properties for a column
+ */
+export const filterOperations: {
+    '=': (value: any, pattern: any) => boolean;
+    '<': (value: any, pattern: any) => boolean;
+    '>': (value: any, pattern: any) => boolean;
+    '<=': (value: any, pattern: any) => boolean;
+    '>=': (value: any, pattern: any) => boolean;
+    '~*': (value: any, pattern: any) => any;
+    '~': (value: any, pattern: any) => any;
+    '!=': (value: any, pattern: any) => boolean;
+    '!~*': (value: any, pattern: any) => boolean;
+    '!~': (value: any, pattern: any) => boolean;
+};
+export namespace typeConverters {
+    function string(value: any): string;
+    function number(value: any): number;
+    function boolean(value: any): boolean;
+    function date(value: any): Date;
+    function mixed(x: any): any;
+}
+export function includeAll(): boolean;

package/dist/src/convert.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Converts an array of objects into a columnar structure, returning an object with two attributes:
+ *
+ * - columns, which contains an array of column names
+ * - data, which is an object with column names as keys and arrays as values.
+ *
+ * @param {Array<Object>} input
+ * @returns {import('./types').Dataframe}
+ */
+export function fromArray(input: Array<Object>): import("./types").Dataframe;

package/dist/src/dataset.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Returns the default aggregator which rolls up non-group_by columns into a children array.
+ */
+export function defaultAggregator(config: any): {
+    mapper: (row: any) => {};
+    reducers: {
+        field: any;
+        formula: (x: any) => any;
+    }[];
+};
+export function dataset(data: any, options?: {}): DataSet;
+export class DataSet {
+    constructor(data: any);
+    set data(values: any[]);
+    get data(): any[];
+    set config(props: any);
+    override(props: any): this;
+    where(condition: any): this;
+    apply(callback: any): this;
+    sortBy(...fields: any[]): this;
+    rename(how: any): this;
+    drop(...fields: any[]): DataSet;
+    fillNA(value: any): this;
+    remove(): this;
+    update(value: any): this;
+    groupBy(...fields: any[]): this;
+    alignBy(...fields: any[]): this;
+    usingTemplate(template: any): this;
+    summarize(from: any, fields: any): this;
+    rollup(): DataSet;
+    select(...cols: any[]): any;
+    /**
+     * Derive column definitions from the current data.
+     *
+     * Returns `{ name, type, scale, sortable, filterable, fields, formatter }` for each
+     * column, plus any user-supplied properties from `options.enhancements`.
+     *
+     * @param {Object} [options]
+     * @param {Array<Object>} [options.enhancements=[]] - Per-column overrides keyed by name.
+     * @param {string} [options.language='en-US'] - Locale for formatters.
+     * @param {string} [options.scanMode='fast'] - 'fast' or 'deep'.
+     * @returns {Array<Object>}
+     */
+    columnDefs(options?: {
+        enhancements?: Object[] | undefined;
+        language?: string | undefined;
+        scanMode?: string | undefined;
+    }): Array<Object>;
+    union(other: any): DataSet;
+    minus(other: any): DataSet;
+    intersect(other: any): DataSet;
+    innerJoin(other: any, condition: any): DataSet;
+    leftJoin(other: any, condition: any): DataSet;
+    rightJoin(other: any, condition: any): DataSet;
+    fullJoin(other: any, condition: any): DataSet;
+    crossJoin(other: any): DataSet;
+    semiJoin(other: any, condition: any): DataSet;
+    antiJoin(other: any, condition: any): DataSet;
+    nestedJoin(other: any, condition: any): DataSet;
+    #private;
+}

package/dist/src/dataset.svelte.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Factory function for `ReactiveDataSet`.
+ *
+ * @param {any[]} [data=[]] - Initial source rows.
+ * @returns {ReactiveDataSet}
+ */
+export function reactiveDataset(data?: any[]): ReactiveDataSet;
+export class ReactiveDataSet {
+    /**
+     * @param {any[]} data - Initial source rows.
+     */
+    constructor(data?: any[]);
+    /**
+     * Reactive computed result of filter + transforms + sort.
+     * Bind to this in templates instead of calling `.select()`.
+     */
+    get rows(): any;
+    /**
+     * Reactive derived column definitions: name, type, scale (discrete|continuous),
+     * sortable, filterable, fields, formatter — merged with any `withColumns` overrides.
+     *
+     * Re-computes when source data or column enhancements change.
+     * Bind to this in templates for Table / TreeTable column specs.
+     */
+    get columns(): Object[];
+    /**
+     * Set the filter predicate. Replaces any previous filter.
+     * @param {Function|null} fn
+     */
+    where(fn: Function | null): this;
+    /**
+     * Append a row transform. Each call to `apply` adds a new stage.
+     * @param {Function} fn
+     */
+    apply(fn: Function): this;
+    /**
+     * Set sort fields. Replaces any previous sort.
+     * @param {...string} fields
+     */
+    sortBy(...fields: string[]): this;
+    /**
+     * Set per-column enhancements / overrides for the reactive `columns` property.
+     *
+     * Each entry is matched by `name` and merged into the auto-derived column def.
+     * Unknown names are appended as synthetic columns (useful for action columns).
+     *
+     * @param {Array<Object>} enhancements - e.g. [{ name: 'revenue', label: 'Revenue ($)', scale: 'continuous' }]
+     * @param {Object} [options] - Options forwarded to deriveColumnDefs (language, scanMode).
+     */
+    withColumns(enhancements: Array<Object>, options?: Object): this;
+    /** Clear the current filter. */
+    clearFilter(): this;
+    /** Clear all transforms. */
+    clearTransforms(): this;
+    /**
+     * Replace the entire source dataset.
+     * @param {any[]} rows
+     */
+    setData(rows: any[]): this;
+    /**
+     * Append a single row to the source.
+     * @param {any} row
+     */
+    push(row: any): this;
+    /**
+     * Remove rows matching the predicate from the source.
+     * @param {Function} predicate
+     */
+    remove(predicate: Function): this;
+    /**
+     * Update rows matching the predicate with patch (object or function).
+     * @param {Function} predicate
+     * @param {Object|Function} patch
+     */
+    update(predicate: Function, patch: Object | Function): this;
+    /** Return a plain snapshot of the current reactive result (non-reactive copy). */
+    snapshot(): any[];
+    #private;
+}

package/dist/src/filter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Filters an array of objects based on a specified condition defined in the options.
+ * If a column is provided, it filters based on the value of that column. Otherwise, it filters
+ * based on a value present in any of the object's properties.
+ *
+ * @param {Object[]} data - The array of objects to filter.
+ * @param {Object} options - The filtering options that define the condition.
+ * @param {string} [options.column] - The property name in the objects to filter by. If omitted, all properties are considered.
+ * @param {string|number} [options.value] - The value to compare against when filtering.
+ * @param {string} [options.operator] - The operator to use for comparison, should match a key in the filterOperations object.
+ * @returns {Object[]} - The filtered array of objects.
+ */
+export function filterObjectArray(data: Object[], options: {
+    column?: string | undefined;
+    value?: string | number | undefined;
+    operator?: string | undefined;
+}): Object[];
+/**
+ * Applies multiple filtering conditions to an array of objects. This function iterates through each filter option,
+ * successively narrowing down the data.
+ *
+ * @param {Object[]} data - The array of objects to filter.
+ * @param {Object[]} filters - An array of filtering options to apply to the data.
+ * @returns {Object[]} - The filtered array of objects that meet all conditions specified by the filters.
+ */
+export function filterData(data: Object[], filters: Object[]): Object[];

package/dist/src/formatter.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Creates a formatter function that formats a value according to the specified type and optional locale settings.
+ * Supported types include 'default' (no formatting), 'integer', 'number', 'date', 'time',, 'object', 'array', 'currency' & 'ellipsis''
+ *
+ * @param {string} type               - The type of the formatter to use (e.g., 'integer', 'number', 'date', 'time', 'currency').
+ * @param {string} [language='en-US'] - Optional IETF language tag used for locale-specific formatting.
+ * @param {number} [decimalPlaces=2]  - Optional number of decimal places to show with number and currency formatting.
+ * @returns {*}                       - A format function that takes a value and returns a formatted string.
+ */
+export function createFormatter(type: string, language?: string, decimalPlaces?: number): any;

package/dist/src/hierarchy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Removes objects from an array where the parent attribute is not null.
+ * @param {Array<Object>} arr - The array of objects.
+ */
+export function removeChildren(arr: Array<Object>): void;
+/**
+ * Flatten nested children arrays within an array of objects.
+ * @param {Array<Object>} arr - The array of objects.
+ */
+export function flattenNestedChildren(arr: Array<Object>): void;
+/**
+ * Applies a hierarchical filter to an array of objects.
+ * @param {Array<Object>} arr - The array of objects.
+ * @param {Function} filterFn - The filter function to apply on each object.
+ */
+export function hierarchicalFilter(arr: Array<Object>, filterFn: Function): void;
+/**
+ * Derives the hierarchy from the data.
+ *
+ * @param {Array} data - The data to derive the hierarchy from.
+ * @param {string} path - The column name to be used as hierarchical path.
+ * @param {string} separator - The separator to be used in the path.
+ * @returns {Array<import('./types').Hierarchy>} - The derived hierarchy.
+ */
+export function deriveHierarchy(data: any[], options: any): Array<import("./types").Hierarchy>;
+/**
+ * Toggles the expansion state of a node and updates the visibility of its children accordingly.
+ * If the node is a parent (has child nodes), it will invert its 'isExpanded' property and call
+ * 'changeVisibilityForChildren' to reflect changes to its child nodes.
+ *
+ * @param {Object} node - The node to toggle expansion for. The node is expected to have an
+ *                        'isParent' property indicating if the node has children, an
+ *                        'isExpanded' property indicating if the node is expanded, and an array
+ *                        of child nodes under the 'children' property if it is a parent.
+ */
+export function toggleExpansion(node: Object): void;

package/dist/src/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./types";
+export { typeOf } from "./utils";
+export { renamer } from "./renamer";
+export { model } from "./model";
+export { dataset } from "./dataset";
+export { dataview } from "./view";
+export { parseFilters } from "./parser";
+export { innerJoin, leftJoin, rightJoin, fullJoin, crossJoin, antiJoin, semiJoin } from "./join";
+export { deriveColumns, deriveMetadata, deriveSortableColumn, inferScale, addScales, deriveColumnDefs, mergeColumnEnhancements } from "./infer";
+export { filterData, filterObjectArray } from "./filter";

package/dist/src/infer.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Derives the sorting information for a column based on the type of the input value.
+ *
+ * @param {import('./types').SortableColumn} value - The value that determines the sorting behavior of the column.
+ * @returns {import('./types').ColumnSorter}         An object containing the 'name' of the column and a 'sorter' function.
+ * @throws {Error} Throws an error if the value type is not supported or the value format is invalid.
+ */
+export function deriveSortableColumn(value: import("./types").SortableColumn): import("./types").ColumnSorter;
+/**
+ * Creates a deep scan sample object that contains a union of all keys from all
+ * objects in the array, pulling the values from the last item that contains the key.
+ *
+ * @param {Array<Object>} data - An array of objects to deep scan and collect sample values.
+ * @returns {Object} A sample object consolidating all unique keys with their latest non-null values.
+ */
+export function getSample(data: Array<Object>, deepScan?: boolean): Object;
+/**
+ * Derives a unique list of column names from an array of data objects.
+ * Each data object represents a row and this function compiles a list of all unique property keys
+ * present across these objects.
+ *
+ * @param {Object[]} data - The array of data objects to analyze for column names.
+ * @returns {string[]} - An array of strings representing the unique column names found across all data objects.
+ */
+export function deriveColumns(data: Object[], options: any): string[];
+/**
+ * Derives the data types of columns based on the data provided in an array of objects.
+ * The function assumes that all values of a single field (column) are of the same type. It uses
+ * the first object in the data array as a reference for the field names. Each field is categorized
+ * as either 'string' or 'number' based on whether any of the field values in the data set are non-numeric.
+ *
+ * @param {Object[]} data - The array of data objects to assess for column data types.
+ * @returns {Object} - An object with keys being the data types ('string' & 'number') and values
+ *                     being arrays of field names that correspond to that data type.
+ */
+export function deriveDataTypes(data: Object[]): Object;
+/**
+ * Infers the data type of a set of values by examining the values in the array.
+ * Assumes all values in the array should have the same type, unless they are 'null'.
+ * If multiple types are detected (excluding 'null'), the function will return 'mixed'.
+ * If all values are 'null', it returns 'null', and it returns 'undefined' for an empty array.
+ *
+ * @param {Array} values - An array of values for which the data type is to be inferred.
+ * @returns {string} - A string representing the inferred data type. Possible values are
+ *                     'undefined', 'null', 'mixed', or any data type returned by the getType function.
+ */
+export function inferDataType(values: any[]): string;
+/**
+ * Adds a formatter function to each column in the array based on the column type. If a formatter
+ * function is already present, it will not be overwritten. The formatter is created based on the
+ * override formatter if present, or the column type and language.
+ *
+ * @param {Array<import('./types').ColumnMetadata>} columns - The array of column metadata to add formatters to.
+ * @param {string} language - The language to use for formatting.
+ * @returns {Array<import('./types').ColumnMetadata>} - The array of column metadata with formatters added.
+ */
+export function addFormatters(columns: Array<import("./types").ColumnMetadata>, language: string): Array<import("./types").ColumnMetadata>;
+/**
+ * Converts an array of action names to an array of action objects.
+ *
+ * @param {Array<string|import('./types').Action>} input - The input to convert to actions.
+ * @returns {Array<import('./types').Action>} - The converted actions.
+ */
+export function convertToActions(input: Array<string | import("./types").Action>): Array<import("./types").Action>;
+/**
+ * Adds actions to the column metadata. This function updates the columns array in place.
+ *
+ * @param {Array<import('./types').ColumnMetadata>} columns - The column metadata to update.
+ * @param {Array<string|import('./types').Action>}  input   - The actions to add to the column metadata.
+ * @returns {Array<import('./types').ColumnMetadata>} - The updated column metadata.
+ */
+export function deriveActions(columns: Array<import("./types").ColumnMetadata>, input: Array<string | import("./types").Action>): Array<import("./types").ColumnMetadata>;
+/**
+ * Derives column metadata from the data to be used in a tabular component.
+ *
+ * @param {Array} data - The data to derive column metadata from.
+ * @param {Object} [options] - The options to use when deriving column metadata.
+ * @returns {Array<import('./types').ColumnMetadata>} - The derived column metadata.
+ */
+export function deriveMetadata(dataArray: any, options?: Object): Array<import("./types").ColumnMetadata>;
+export function inferScale(values: any): any;
+/**
+ * Adds a `scale` property to each column definition.
+ *
+ * @param {Array<Object>} columns - Column definitions (from deriveColumns / deriveMetadata).
+ * @param {any[]} data - Source rows.
+ * @returns {Array<Object>} Column definitions with `scale` added.
+ */
+export function addScales(columns: Array<Object>, data: any[]): Array<Object>;
+/**
+ * Merges user-provided enhancements into auto-derived column definitions.
+ * Enhancements are matched by `name` and merged (user values win).
+ * Enhancements for unknown column names are appended as synthetic columns.
+ *
+ * @param {Array<Object>} derived - Auto-derived column definitions.
+ * @param {Array<Object>} enhancements - User-provided overrides/additions.
+ * @returns {Array<Object>} Merged column definitions.
+ */
+export function mergeColumnEnhancements(derived: Array<Object>, enhancements: Array<Object>): Array<Object>;
+/**
+ * Full column definition pipeline: derive → format → scale → merge enhancements.
+ *
+ * Produces column descriptors suitable for use in Table, TreeTable, and chart
+ * components. Each column gets: name, type, scale, sortable, filterable, fields,
+ * formatter — plus any user-supplied properties from `enhancements`.
+ *
+ * @param {any[]} data - Source rows.
+ * @param {Object} [options] - Options forwarded to deriveColumns / addFormatters.
+ * @param {Array<Object>} [options.enhancements=[]] - Per-column overrides keyed by name.
+ *        Use to override scale, add a label, attach a custom formatter, etc.
+ * @param {string} [options.language='en-US'] - Locale for formatters.
+ * @param {string} [options.scanMode='fast'] - 'fast' (first row) or 'deep' (all rows).
+ * @returns {Array<Object>} Column definitions with scale and formatters.
+ */
+export function deriveColumnDefs(data: any[], options?: {
+    enhancements?: Object[] | undefined;
+    language?: string | undefined;
+    scanMode?: string | undefined;
+}): Array<Object>;

package/dist/src/join.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Filters the results of the first dataset based on the condition using the second dataset.
+ *
+ * @param {Array<Object>}    first     - The first dataset to filter.
+ * @param {Array<Object>}    second    - The second dataset to filter by.
+ * @param {Function}        condition - The condition to filter the first dataset by.
+ * @returns {Array<Object>}            - The filtered dataset.
+ */
+export function antiJoin(first: Array<Object>, second: Array<Object>, condition: Function): Array<Object>;
+/**
+ * Joins two datasets together based on a condition. Result includes all rows from the first
+ * dataset and matching rows from the second dataset. In case of multiple matches, all
+ * combinations are returned. When combining the rows, the columns from the first dataset take
+ * precedence.
+ *
+ * @param {Array<Object>}    first     - The first dataset to join.
+ * @param {Array<Object>}    second    - The second dataset to join.
+ * @param {Function}      condition - The condition to join the datasets on.
+ * @returns {Array<Object>}            - The joined dataset.
+ */
+export function innerJoin(first: Array<Object>, second: Array<Object>, condition: Function): Array<Object>;
+/**
+ * Performs a left join on two datasets based on a condition.
+ *
+ * - Result includes all rows from the first dataset and matching rows from the second dataset.
+ * - In case of multiple matches, all combinations are returned.
+ * - When combining the rows, the columns from the first dataset take precedence.
+ * - If there is no match in the second dataset, only the row from the first dataset is returned.
+ *
+ * This can be used to perform a right join by swapping the datasets.
+ *
+ * @param {Array<Object>}    first     - The first dataset to join.
+ * @param {Array<Object>}    second    - The second dataset to join.
+ * @param {Function}         condition - The condition to join the datasets on.
+ * @returns {Array<Object>}            - The joined dataset.
+ */
+export function leftJoin(first: Array<Object>, second: Array<Object>, condition: Function): Array<Object>;
+/**
+ * Performs a right join on two datasets based on a condition.
+ *
+ * - Result includes all rows from both datasets.
+ * - In case of multiple matches, all combinations are returned.
+ * - When combining the rows, the columns from the second dataset take precedence.
+ * - If there is no match in the first dataset, only the row from the second dataset is returned.
+ *
+ * @param {Array<Object>}    first     - The first dataset to join.
+ * @param {Array<Object>}    second    - The second dataset to join.
+ * @param {Function}   condition - The condition to join the datasets on.
+ * @returns {Array<Object>}            - The joined dataset.
+ */
+export function rightJoin(first: Array<Object>, second: Array<Object>, condition: Function): Array<Object>;
+/**
+ * Performs a full join on two datasets based on a condition.
+ *
+ * - Result includes all rows from both datasets.
+ * - In case of multiple matches, all combinations are returned.
+ * - When combining the rows, the columns from the second dataset take precedence.
+ * - If there is no match in the first dataset, only the row from the second dataset is returned.
+ *
+ * @param {Array<Object>}    first     - The first dataset to join.
+ * @param {Array<Object>}    second    - The second dataset to join.
+ * @param {Function}         condition - The condition to join the datasets on.
+ * @returns {Array<Object>}            - The joined dataset.
+ */
+export function fullJoin(first: Array<Object>, second: Array<Object>, condition: Function): Array<Object>;
+/**
+ * Performs a cross join on two datasets. Result includes all combinations of rows from both datasets.
+ *
+ * @param {Array<Object>} first  - The first dataset to join.
+ * @param {Array<Object>} second - The second dataset to join.
+ * @returns {Array<Object>}      - The joined dataset.
+ */
+export function crossJoin(first: Array<Object>, second: Array<Object>): Array<Object>;
+/**
+ * Performs a semi join on two datasets based on a condition. Result includes all rows from the first
+ * dataset that have a match in the second dataset.
+ *
+ * @param {Array<Object>}    first     - The first dataset to join.
+ * @param {Array<Object>}    second    - The second dataset to join.
+ * @param {Function}     condition - The condition to join the datasets on.
+ * @returns {Array<Object>}            - The joined dataset.
+ */
+export function semiJoin(first: Array<Object>, second: Array<Object>, condition: Function): Array<Object>;
+/**
+ * Performs a nested join on two datasets based on a condition. Result includes all rows from the first
+ * dataset that have a match in the second dataset. The result is nested with the matching rows from the
+ * second dataset.
+ *
+ * @param {Array<Object>}    first            - The first dataset to join.
+ * @param {Array<Object>}    second           - The second dataset to join.
+ * @param {Function}         condition        - The condition to join the datasets on.
+ * @param {String}   [key='children'] - The key to nest the matching rows under.
+ * @returns {Array<Object>}            - The joined dataset.
+ */
+export function nestedJoin(first: Array<Object>, second: Array<Object>, condition: Function, key?: string): Array<Object>;

package/dist/src/list.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Compares two items for sorting. When grouped, uses group comparison before item comparison
+ *
+ * @param {*} a first item
+ * @param {*} b second item
+ * @param {*} data
+ * @returns
+ */
+export function compare(a: any, b: any, data: any): number;
+/**
+ * Search the data for existence of string in the data
+ *
+ * @param {List} data
+ * @param {string} value
+ * @returns
+ */
+export function quickSearch(data: List, value: string): object[];
+/**
+ * Create a new list
+ *
+ * @param {Array<object>} data
+ * @returns
+ */
+export function list(data: Array<object>): List;
+/**
+ * Implements a list containing data and functionality for sorting, filtering, and grouping.
+ */
+export class List {
+    /**
+     * Creates a List instance with initial data and default settings for keys and functions.
+     * @param {Array<object>} data - The initial array of objects to populate the list.
+     */
+    constructor(data: Array<object>);
+    data: object[];
+    primaryKey: string;
+    filterKey: string | undefined;
+    sortKey: string | undefined;
+    groupKey: string | undefined;
+    lookup: {};
+    searchText: string;
+    filterUsing: Function | undefined;
+    sortUsing: Function | undefined;
+    filtered: import("svelte/store").Writable<object[]>;
+    /**
+     * Sets a primary key attribute for list items and assigns a unique identifier if not present.
+     *
+     * @param {string} value - The property name to be set as the primary key.
+     * @returns {List} This list instance for method chaining.
+     */
+    key(value: string): List;
+    /**
+     * Configures sorting by a given key and sorting function.
+     *
+     * @param {string} key - The property name to sort by.
+     * @param {Function} [using=compare] - The function used to sort the list items.
+     * @returns {List} This list instance for method chaining.
+     */
+    sortBy(key: string, using?: Function): List;
+    /**
+     * Groups list items by a given key and maps group keys for display using an optional lookup object.
+     *
+     * @param {string} key - The property name to group by.
+     * @param {object|null} [lookup=null] - An object mapping group keys to display names.
+     * @returns {List} This list instance for method chaining.
+     */
+    groupBy(key: string, lookup?: object | null): List;
+    /**
+     * Sets the key and function for filtering list items.
+     *
+     * @param {string} key - The property name to filter by.
+     * @param {Function} [using=quickSearch] - The function used to filter the list items.
+     * @returns {List} This list instance for method chaining.
+     */
+    filterBy(key: string, using?: Function): List;
+    /**
+     * Sorts the list based on the configured sorting function.
+     *
+     * @returns {List} This list instance for method chaining.
+     */
+    sort(): List;
+    /**
+     * Adds a new item to the list, assigning a primary key if necessary, and then sorts and refreshes the list.
+     *
+     * @param {object} item - The item to add to the list.
+     * @returns {List} This list instance for method chaining.
+     */
+    add(item: object): List;
+    /**
+     * Removes an item from the list by primary key and refreshes the list.
+     *
+     * @param {object} item - The item to remove from the list.
+     * @returns {List} This list instance for method chaining.
+     */
+    remove(item: object): List;
+    /**
+     * Modifies an existing item in the list, identified by primary key, and then sorts and refreshes the list.
+     *
+     * @param {object} item - The item to modify in the list.
+     * @returns {List} This list instance for method chaining.
+     */
+    modify(item: object): List;
+    /**
+     * Sets the text to search for in the list's items and then refreshes the list.
+     *
+     * @param {string} text - The text to search for.
+     * @returns {List} This list instance for method chaining.
+     */
+    search(text: string): List;
+    /**
+     * Refreshes the list based on current sorting, grouping, and filtering configuration.
+     *
+     * @returns {List} This list instance for method chaining.
+     */
+    refresh(): List;
+    /**
+     * Gets the current state of the filtered list data.
+     *
+     * @returns {Array<object>} The current filtered data of the list.
+     */
+    current(): Array<object>;
+}

package/dist/src/metadata.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Adds a path modifier to column definitions that match a specific path.
+ *
+ * @param {Array<Object>} columns - The original array of column definitions.
+ * @param {string|null} path - The path used to identify columns that require path modifiers.
+ * @param {string} separator - The separator used in conjunction with the path.
+ * @returns {Array<Object>} The array of column definitions with path modifiers added as needed.
+ */
+export function addPathModifier(columns: Array<Object>, path: string | null, separator: string): Array<Object>;
+/**
+ * Derives column properties for a given sample and options.
+ *
+ * @param {Object} sample - The sample object used to derive column properties.
+ * @param {Object} options - The options used to modify column properties.
+ *        It can specify path, separator, and currencySuffix for column customization.
+ * @returns {Array<Object>} An array of derived column definitions.
+ */
+export function deriveColumnProperties(sample: Object, options: Object): Array<Object>;
+/**
+ * Derives the column metadata from the provided data and options.
+ *
+ * @param {Array} data                       - The data to derive the column metadata from.
+ * @param {Object} [options]                 - Optional parameters to control the metadata derivation.
+ * @param {Array} [options.metadata]         - The metadata to use instead of deriving it from the data.
+ * @param {boolean} [options.deepScan=false] - Determines if the metadata derivation should perform a deep scan of the data.
+ *
+ * @returns {import('./types').Metadata} The derived column metadata.
+ */
+export function deriveColumnMetadata(data: any[], options?: {
+    metadata?: any[] | undefined;
+    deepScan?: boolean | undefined;
+}): import("./types").Metadata;

package/dist/src/model.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A model is a representation of a dataset
+ * @returns an object with methods to manipulate the model
+ */
+export function model(): {
+    get: () => any[];
+    clone: (other: any) => /*elided*/ any;
+    /**
+     * Renames the reference names using a renamer
+     * @param {Function} rename - the renamer function
+     */
+    renameUsing: (rename: Function) => /*elided*/ any;
+    /**
+     * Analyzes the input data and derives a model from it
+     *
+     * @param {Array|Object} value      - the data to derive the model from
+     * @param {boolean}      sparseData - indicates that rows may have missing attributes
+     * @returns {Object}     this
+     */
+    from: (value: any[] | Object, sparseData: boolean) => Object;
+    /**
+     * Merges the model with another model
+     *
+     * @param {Array}   other    - the model to merge with
+     * @param {Boolean} override - whether to override the type of the first model
+     * @returns {Object} this
+     */
+    merge: (other: any[], override?: boolean) => Object;
+};

package/dist/src/parser.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Constructs a regular expression pattern for matching search filter strings.
+ * The pattern captures "column", "operator", and "value" groups for filter expressions.
+ * Supported operators include common comparison and wildcard operators.
+ *
+ * Examples of valid expressions this regex can match:
+ * - "username:john_doe"
+ * - "age>30"
+ * - "status!=active"
+ * - "title~\"Product Manager\""
+ * - "completed!~*yes"
+ *
+ * The "column" group matches one or more word characters.
+ * The "operator" group matches one among the specified comparison or wildcard operators:
+ * :, >, <, >=, <=, =<, =>, =, !=, ~, ~*, !~, !~*.
+ * The "value" group matches either a double-quoted string or a single unquoted word
+ * that doesn't include whitespace or any of the operator characters.
+ *
+ * @returns {RegExp} - The regular expression pattern to identify search filter elements.
+ */
+export function getRegex(): RegExp;
+/**
+ * Parses a search string and extracts filters based on a predefined regular expression pattern.
+ * Each filter captures column, operator, and value components. Any remaining text that
+ * does not fit the pattern is considered a general search term.
+ *
+ * @param {string} string - The search string to parse for filters.
+ * @returns {Object[]} - An array of filter objects each containing the column, operator, and value,
+ *                       plus an additional object for general search if there is remaining text.
+ */
+export function parseFilters(string: string): Object[];

package/dist/src/pipeline.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Sort an array in-place by one or more field specs.
+ * @param {any[]} data - Array to sort (mutated in place).
+ * @param {...string|Object|Array} fields - Sort field specs (same as DataSet.sortBy).
+ * @returns {any[]}
+ */
+export function sortDataByFields(data: any[], ...fields: (string | Object | any[])[]): any[];
+export function executeFused(data: any, ops: any): any;

package/dist/src/renamer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A generator function that produces a function to rename keys.
+ *
+ * @param {OptionsToRenameKeys} options - Options to rename keys
+ * @returns {Object}                    - A renamer object.
+ *
+ * Example:
+ *
+ * renamer({ prefix: 'a', keys: ['a', 'b'] }).get()
+ * renamer({ prefix: 'a', separator: '-' }).get()
+ * renamer().setPrefix('a')
+ *          .setSeparator('-')
+ *          .setKeys(['a', 'b'])
+ *          .get()
+ * renamer().setPrefix('a').get()
+ * renamer().setSuffix('b').get()
+ * renamer().setKeys(['a', 'b']).get()
+ */
+export function renamer(options?: OptionsToRenameKeys): Object;
+export type OptionsToRenameKeys = {
+    /**
+     * - The prefix to add to the key.
+     */
+    prefix?: string | undefined;
+    /**
+     * - The suffix to add to the key.
+     */
+    suffix?: string | undefined;
+    /**
+     * - The separator to use between the key and the prefix or suffix.
+     */
+    separator?: string | undefined;
+    /**
+     * - The keys to rename.
+     */
+    keys?: any[] | undefined;
+};

package/dist/src/rollup.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Sets initial values for summaries.
+ *
+ * @param {Array} summaries - An array of summary objects.
+ * @returns {Object} An object with keys for each summary initialized to empty arrays.
+ */
+export function initialValues(summaries: any[]): Object;
+/**
+ * Adds data to summary aggregation arrays.
+ *
+ * @param {Object} group - The group object to add data to.
+ * @param {Object} row - The data row being processed.
+ * @param {Array} summaries - An array of summary objects.
+ */
+export function addToSummaries(group: Object, row: Object, summaries: any[]): void;
+/**
+ * Groups data by specified keys using a composite string key (Phase 3: replaces JSON.stringify).
+ *
+ * @param {Array} data - An array of data points.
+ * @param {Array} groupByKeys - Keys to group the data by.
+ * @param {Array} summaries - An array of summary objects to define aggregation operations.
+ * @returns {Object} Grouped data object with aggregation placeholders.
+ */
+export function groupDataByKeys(data: any[], groupByKeys: any[], summaries: any[]): Object;
+/**
+ * Fills grouped data with aligned data if specified in configuration.
+ *
+ * @param {Object} groupedData - The grouped data object.
+ * @param {Object} config - Configuration object containing alignment settings.
+ * @returns {Array} Aligned data array.
+ */
+export function fillAlignedData(groupedData: Object, config: Object, fillRowsFunc: any): any[];
+export function getAlignGenerator(data: any, config: any): (children: any) => any[];
+/**
+ * Performs aggregation operations on grouped data.
+ *
+ * @param {Array} dataArray - An array of grouped data with aggregation arrays.
+ * @param {Array} summaries - An array of summary objects with reducer functions.
+ * @returns {Array} Aggregated data array with computed summary values.
+ */
+export function aggregateData(dataArray: any[], summaries: any[]): any[];

package/dist/src/types.d.ts

@@ -0,0 +1,346 @@
+declare const _default: {};
+export default _default;
+export type FieldMapping = import("@rokkit/core").FieldMapping;
+export type SortOptions = import("@rokkit/core").SortOptions;
+export type HorizontalAlignOptions = import("@rokkit/core").HorizontalAlignOptions;
+export type ActionTypes = import("@rokkit/core").ActionTypes;
+export type SelectionState = import("@rokkit/core").SelectionState;
+export type ColumnSorter = {
+    name: string;
+    sorter: Function;
+};
+export type SortableColumn = string | [string, boolean] | ColumnSorter;
+export type ColumnAggregator = {
+    name: string;
+    aggregator: Function;
+    suffix: string;
+};
+/**
+ * Options for joining two data sets
+ */
+export type OptionsToRenameKeys = {
+    /**
+     * - Prefix to be added to each attribute
+     */
+    prefix?: string | undefined;
+    /**
+     * - Suffix to be added to each attribute
+     */
+    suffix?: string | undefined;
+    /**
+     * - Separator to be used when adding prefix or suffix. defaults to _
+     */
+    separator?: string | undefined;
+};
+/**
+ * Column metadata for the table.
+ */
+export type ColumnMetadata = {
+    /**
+     * - The name of the column.
+     */
+    name: string;
+    /**
+     * - The data type of the column (e.g., "string", "number", "date").
+     */
+    type: string;
+    /**
+     * - The field mapping for the column.
+     */
+    field?: import("@rokkit/core").FieldMapping | undefined;
+    /**
+     * - The number of digits for numeric values (defaults to 0).
+     */
+    digits?: number | undefined;
+    /**
+     * - A function to format the column value.
+     */
+    formatter: Function;
+    /**
+     * - Indicates if the column is sortable (true/false).
+     */
+    sortable?: boolean | undefined;
+    /**
+     * - The sort order of the column.
+     */
+    sortOrder?: import("@rokkit/core").SortOptions | undefined;
+    /**
+     * - The alignment of the column content.
+     */
+    align?: import("@rokkit/core").HorizontalAlignOptions | undefined;
+    /**
+     * - Action attribute for action columns.
+     */
+    action?: import("@rokkit/core").ActionTypes | undefined;
+};
+export type Metadata = Array<ColumnMetadata>;
+export type ColumnIndexMap = {
+    [x: string]: number;
+};
+/**
+ * Track the state of a row in the table.
+ */
+export type TreeTableNode = {
+    /**
+     * - Reference to actual row in the data.
+     */
+    row: number;
+    /**
+     * - The depth of the node in the hierarchy.
+     */
+    depth: number;
+    /**
+     * - The value of the hierarchy node.
+     */
+    value?: string | undefined;
+    /**
+     * - Indicates whether the node is visible (true/false).
+     */
+    isHidden?: boolean | undefined;
+    /**
+     * - Indicates if this node is a parent (true/false).
+     */
+    isParent?: boolean | undefined;
+    /**
+     * - Indicates whether the node is expanded (true/false).
+     */
+    isExpanded?: boolean | undefined;
+    /**
+     * - Reference to the parent node in the flat list.
+     */
+    parent?: number | undefined;
+    /**
+     * - Indicates whether the node is selected (true/false/indeterminate).
+     */
+    selected?: import("@rokkit/core").SelectionState | undefined;
+    /**
+     * - Reference to the children nodes in the flat list.
+     */
+    children: Array<any>;
+};
+/**
+ * Track the state of all rows in the table.
+ */
+export type TreeTable = {
+    /**
+     * - Flat list of hierarchy nodes.
+     */
+    rows: TreeTableNode[];
+};
+export type OverrideConfig = {
+    /**
+     * - the field used for identifying filler rows in the data
+     */
+    actual_flag: string;
+    /**
+     * - the field used for collecting children of a node in rollup
+     */
+    children: string;
+};
+export type ReducerConfig = {
+    /**
+     * - The target field to hold the reduced value
+     */
+    field: string;
+    /**
+     * - The function to use for reducing the data
+     */
+    using: Function;
+};
+export type SummaryConfig = {
+    /**
+     * - A function used to collect the data for the summary
+     */
+    mapper: Function;
+    /**
+     * - Array of reducer configurations
+     */
+    reducers: Array<ReducerConfig>;
+    /**
+     * - Array of column metadata for the summary
+     */
+    metadata?: Metadata | undefined;
+};
+export type DataFrameConfig = {
+    /**
+     * =[]         - The columns to group by.
+     */
+    group_by: Array<string>;
+    /**
+     * =[]         - The columns to be aligned during rollup.
+     */
+    align_by: Array<string>;
+    /**
+     * =[] - Array of summary configurations.
+     */
+    summaries: Array<SummaryConfig>;
+    /**
+     * ={}                   - Template row to be used for filling in missing rows.
+     */
+    template: any;
+};
+export type SortBy = Function;
+/**
+ * DataFrame-like object with data manipulation methods.
+ */
+export type DataFrame = {
+    /**
+     * - Array of objects representing the rows of data.
+     */
+    data: Array<Object>;
+    /**
+     * - Array of column metadata for the data.
+     */
+    metadata: Metadata;
+    /**
+     * - Configuration options for the DataFrame.
+     */
+    config: DataFrameConfig;
+    /**
+     * - A map of column names to their index in the metadata.
+     */
+    columns: ColumnIndexMap;
+    /**
+     * - Method to override the configuration of the DataFrame.
+     */
+    override: (arg0: OverrideConfig) => DataFrame;
+    /**
+     * - Method to group the DataFrame by specified columns.
+     */
+    groupBy: (...args: string[]) => DataFrame;
+    /**
+     * - Sets the filter function for the DataFrame
+     */
+    where: (arg0: (arg0: any) => any) => DataFrame;
+    /**
+     * - Method to align the DataFrame.
+     */
+    align: () => DataFrame;
+    /**
+     * - set the template to be used for filling in missing rows.
+     */
+    using: () => DataFrame;
+    /**
+     * - add a summarizer to be used during rollup
+     */
+    summarize: () => DataFrame;
+    /**
+     * - Method to sort the DataFrame by specified columns.
+     */
+    sortBy: (...args: SortableColumn[]) => DataFrame;
+    /**
+     * - perform join with another DataFrame returning a new DataFrmae. Defaults to innerJoin, other join types can be specified.
+     */
+    join: () => DataFrame;
+    /**
+     * - perform an ineer join with another DataFrame and return a new DataFrame.
+     */
+    innerJoin: () => DataFrame;
+    /**
+     * - perform a left join with another DataFrame and return a new DataFrame.
+     */
+    leftJoin: () => DataFrame;
+    /**
+     * - perform a right join with another DataFrame returning a new DataFrame.
+     */
+    rightJoin: () => DataFrame;
+    /**
+     * - perform a full join with another DataFrame returning a new DataFrame.
+     */
+    fullJoin: () => DataFrame;
+    /**
+     * - perform a nested join with another DataFrame returning a new DataFrame.
+     */
+    nestedJoin: () => DataFrame;
+    /**
+     * - Method to rename the columns of the DataFrame.
+     */
+    rename: () => DataFrame;
+    /**
+     * - Method to drop the columns of the DataFrame.
+     */
+    drop: () => DataFrame;
+    /**
+     * - Method to delete the rows of the DataFrame.
+     */
+    delete: () => DataFrame;
+    /**
+     * - Method to update the rows of the DataFrame.
+     */
+    update: () => DataFrame;
+    /**
+     * - Method to combine the rows of the DataFrame with another DataFrame.
+     */
+    union: () => DataFrame;
+    /**
+     * - Method to remove the rows of the DataFrame which are present in another DataFrame.
+     */
+    minus: () => DataFrame;
+    /**
+     * - Method to keep the rows of the DataFrame which are present in another DataFrame.
+     */
+    intersect: () => DataFrame;
+    /**
+     * - Method to rollup the DataFrame.
+     */
+    rollup: () => DataFrame;
+    /**
+     * - Method to select the columns of the DataFrame.
+     */
+    select: () => Arrat<Object>;
+};
+export type JoinType = inner | outer | full | nested;
+/**
+ * Options for joining two data sets
+ */
+export type JoinOptions = {
+    /**
+     * - Flag indicating inner join
+     */
+    inner?: boolean | undefined;
+    /**
+     * {string} [prefix]                - prefix to be used for renaming keys in the second data set.
+     */
+    type?: JoinType;
+    /**
+     * - suffix to be used for renaming keys in the second data set.
+     */
+    suffix?: string | undefined;
+    /**
+     * - separator to be used for renaming keys in the second data set.
+     */
+    separator?: string | undefined;
+};
+/**
+ * DataView
+ */
+export type DataView = {
+    /**
+     * - The state of the rows in the table.
+     */
+    hierarchy: TreeTable;
+    /**
+     * - The metadata for the columns in the table.
+     */
+    columns: Metadata;
+    /**
+     * - Sort the DataView by the specified columns.
+     */
+    sortBy: Function;
+    /**
+     * - Clear the sorting of the DataView.
+     */
+    clearSort: Function;
+    /**
+     * - Filter the DataView by the specified columns.
+     */
+    filter: Function;
+    /**
+     * - toggle expand or collapse the DataView by the specified columns.
+     */
+    toggle: Function;
+    /**
+     * - select the DataView by the specified columns.
+     */
+    select: Function;
+};

package/dist/src/utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Derive the type of a value
+ * @param {any} value
+ * @returns {string}
+ */
+export function typeOf(value: any): string;

package/dist/src/view.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Sorts a hierarchy based on a group of sorters.
+ *
+ * @param {Array<Object>} hierarchy - The hierarchy to sort.
+ * @param {Array<Array<string, boolean>>} sortGroup - The group of sorters to apply.
+ */
+export function groupSort(hierarchy: Array<Object>, sortGroup: Array<Array<string, boolean>>): void;
+/**
+ * Determines the selected state of a group of children in the hierarchy.
+ * If all children are checked, returns 'checked'.
+ * If all children are unchecked, returns 'unchecked'.
+ * Otherwise, returns 'indeterminate'.
+ *
+ * @param {Array<Object>} children - The array of child objects with a 'selected' property.
+ * @returns {string} The determined selected state: 'checked', 'unchecked', or 'indeterminate'.
+ */
+export function determineSelectedState(children: Array<Object>): string;
+/**
+ * Toggles the selection state of a node in the hierarchy.
+ * Depending on whether the node to toggle is a parent or child,
+ * it will either select or deselect all children, or update the parent's selection state based on its children's states.
+ *
+ * @param {import('./types').Hierarchy} item - The node to toggle.
+ *
+ */
+export function toggleSelection(item: import("./types").Hierarchy): void;
+/**
+ * Creates a view object for managing data presentation with metadata and hierarchy structures,
+ * as well as providing methods for sorting, selection, and toggling of data expansion.
+ *
+ * @param {Array<Object>} data    - The source data array to be presented by the view.
+ * @param {Object}        options - The configuration options used for deriving metadata and hierarchy from the data.
+ * @returns {import('svelte/store').Writable} An object representing the view, providing methods to manipulate and query the presentation state.
+ */
+export function dataview(data: Array<Object>, options: Object): import("svelte/store").Writable<any>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/data",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Contains generic data manipulation functions that can be used in various components.",
   "repository": {
     "type": "git",
@@ -38,7 +38,7 @@
   },
   "dependencies": {
     "@lukeed/uuid": "^2.0.1",
-    "@rokkit/core": "1.0.1",
+    "@rokkit/core": "1.0.3",
     "d3-array": "^3.2.4",
     "d3-collection": "^1.0.7",
     "ramda": "^0.32.0",