@rokkit/data 1.0.0-next.94

package/src/parser.js

@@ -0,0 +1,110 @@
+/**
+ * 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() {
+	const column = '[\\w]+'
+	const operator = ':|>|<|>=|<=|=<|=>|=|!=|~|~\\*|!~|!~\\*'
+	const value = '("[^"]+"|[^\\s=:<>!~*]+)'
+
+	const pattern = `(?<group>((?<column>${column})\\s?(?<operator>${operator})\\s?)(?<value>${value}))`
+
+	return new RegExp(pattern, 'gm')
+}
+
+/**
+ * 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) {
+	const results = []
+	const regex = getRegex()
+
+	// Split the string into an array of tokens
+	const tokens = string.matchAll(regex)
+	let search = string
+
+	// Iterate over the tokens
+	for (const token of tokens) {
+		// Extract the named groups from the token
+		let { group, column, operator, value } = token.groups
+		search = search.replace(group, '').trim()
+
+		operator = replaceOperators(operator)
+		value = processValue(value, operator)
+
+		if (column && value) results.push({ column, operator, value })
+	}
+
+	if (search.length > 0) {
+		results.push({
+			operator: '~*',
+			value: new RegExp(removeQuotes(search), 'i')
+		})
+	}
+
+	return results
+}
+
+/**
+ * Replaces various shorthand operators with their standardized equivalent for filtering.
+ *
+ * @param {string} operator - The operator to be replaced.
+ * @returns {string} - The replaced operator string.
+ */
+function replaceOperators(operator) {
+	return operator.replace(':', '~*').replace('=>', '>=').replace('=<', '<=')
+}
+
+/**
+ * Processes the filter value provided, converting it into a format suitable for filtering.
+ * If the operator includes a tilde (~), the value is converted to a RegExp.
+ *
+ * @param {string|number} value - The value to be processed. It could be a string needing quote removal or a number that needs parsing.
+ * @param {string} operator - The operator that determines the type of processing to be applied to the value.
+ * @returns {string|number|RegExp} - The processed value, which may be a RegExp if the operator involves pattern matching.
+ */
+function processValue(value, operator) {
+	// If the value can be parsed as an integer, do so. Otherwise, strip quotes if present.
+
+	value = !isNaN(parseInt(value)) ? parseInt(value) : removeQuotes(value)
+	// If the operator includes a tilde (~), treat the value as a regular expression,
+	// case-insensitive if '*' is present, sensitive otherwise.
+	if (operator.includes('~')) {
+		value = operator.includes('*') ? new RegExp(value, 'i') : new RegExp(value)
+	}
+
+	return value
+}
+
+/**
+ * Removes double quotes from the start and end of a string.
+ *
+ * @param {string} str - The input string from which the surrounding quotes should be removed.
+ * @returns {string} - The unquoted string.
+ */
+function removeQuotes(str) {
+	const quoteMatch = str.match(/^"([^"]+)"$/)
+	return quoteMatch ? quoteMatch[1] : str
+}

package/src/renamer.js

@@ -0,0 +1,98 @@
+import { omit, identity } from 'ramda'
+
+/**
+ *
+ *
+ * @typedef {Object} OptionsToRenameKeys
+ * @property {string} [prefix]        - The prefix to add to the key.
+ * @property {string} [suffix]        - The suffix to add to the key.
+ * @property {string} [separator='_'] - The separator to use between the key and the prefix or suffix.
+ * @property {Array}  [keys]          - The keys to rename.
+ */
+
+/**
+ * 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 = {}) {
+	const { prefix, suffix, separator = '_', keys = [] } = options
+	const rename = getRenamer(prefix, suffix, separator)
+	const renameObject = getObjectRenamer(rename, keys)
+
+	return {
+		get: () => ({ rename, renameObject }),
+		setPrefix: (value) => renamer({ ...omit(['suffix'], options), prefix: value }),
+		setSuffix: (value) => renamer({ ...omit(['prefix'], options), suffix: value }),
+		setKeys: (value) => renamer({ ...options, keys: value }),
+		setSeparator: (value) => renamer({ ...options, separator: value })
+	}
+}
+
+/**
+ * Generates a renamer function which adds a prefix or suffix to a string.
+ *
+ * @param {string} prefix    - The prefix to add to the key.
+ * @param {string} suffix    - The suffix to add to the key.
+ * @param {string} separator - The separator to use between the key and the prefix or suffix.
+ * @returns {Function} - A function that takes a string and adds a prefix or suffix.
+ */
+function getRenamer(prefix, suffix, separator) {
+	let rename = identity
+
+	if (prefix) {
+		rename = (x) => [prefix, x].join(separator)
+	} else if (suffix) {
+		rename = (x) => [x, suffix].join(separator)
+	}
+	return rename
+}
+
+/**
+ * Returns a function that renames the keys of an object.
+ *
+ * @param {Function} rename - The function to rename the keys.
+ * @param {Array}    keys   - The keys to rename.
+ * @returns {Function}      - A function that takes an object and renames the keys.
+ */
+function getObjectRenamer(rename, keys) {
+	if (rename === identity) return identity
+	if (keys.length > 0) {
+		const lookup = keys.reduce((acc, key) => ({ ...acc, [key]: rename(key) }), {})
+		return usingLookup(lookup)
+	}
+	return forObject(rename)
+}
+
+/**
+ * Renames the keys of an object using a lookup table.
+ *
+ * @param {Object} lookup - The lookup table.
+ * @returns {Function} - A function that takes an object and renames the keys using the lookup table.
+ */
+function usingLookup(lookup) {
+	return (row) => Object.keys(row).reduce((acc, key) => ({ ...acc, [lookup[key]]: row[key] }), {})
+}
+
+/**
+ * Renames the keys of an object using a function.
+ *
+ * @param {Function} rename - The function to rename the keys.
+ * @returns {Function} - A function that takes an object and renames the keys using the function.
+ */
+function forObject(rename) {
+	return (row) => Object.keys(row).reduce((acc, key) => ({ ...acc, [rename(key)]: row[key] }), {})
+}

package/src/rollup.js

@@ -0,0 +1,138 @@
+import { omit, pick, mergeLeft, map, difference, uniq, pipe } from 'ramda'
+
+/**
+ * Groups data by specified keys.
+ *
+ * @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, groupByKeys, summaries) {
+	const keysExtractor = pick(groupByKeys)
+	const groupedData = data.reduce((grouped, row) => {
+		const key = JSON.stringify(keysExtractor(row))
+		if (!grouped[key]) {
+			grouped[key] = { ...keysExtractor(row), ...initialValues(summaries) }
+		}
+		addToSummaries(grouped[key], row, summaries)
+		return grouped
+	}, {})
+
+	return Object.values(groupedData)
+}
+
+/**
+ * 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) {
+	const fields = summaries.map(({ reducers }) => reducers.map((r) => r.field)).flat()
+	return fields.reduce((acc, name) => ({ ...acc, [name]: [] }), {})
+}
+
+/**
+ * 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, row, summaries) {
+	summaries.forEach(({ mapper, reducers }) => {
+		const value = mapper(row)
+		reducers.forEach((r) => {
+			group[r.field].push(value)
+		})
+	})
+}
+
+/**
+ * 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, config, fillRowsFunc) {
+	// const fillRowsFunc = getAlignGenerator(df.data, config)
+	const { actual_flag, children } = config
+	return Object.values(groupedData).map((row) => ({
+		...row,
+		[children]: [
+			...row[children].map((value) => ({ ...value, [actual_flag]: 1 })),
+			...fillRowsFunc(row[children])
+		]
+	}))
+}
+
+/**
+ * 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, summaries) {
+	const fields = summaries.map(({ name, reducers }) => reducers.map((r) => ({ name, ...r }))).flat()
+	return dataArray.map((row) => ({
+		...row,
+		...fields.reduce(
+			(acc, { field, formula }) => ({
+				...acc,
+				[field]: formula(row[field])
+			}),
+			{}
+		)
+	}))
+}
+
+/**
+ * Creates a generator that produces missing rows in a dataset based on specified columns.
+ * The function determines all unique combinations of the specified columns in config.align_by
+ * and returns a generator function to create the missing combinations, potentially with default
+ * values for other columns.
+ * @param {Array<Object>} data - The array of objects representing the dataset.
+ * @param {Object} config - The configuration object.
+ *
+ * @returns {Function} A generator function that when called, produces the missing rows.
+ */
+export function getAlignGenerator(data, config) {
+	const { align_by, group_by, actual_flag } = config
+	const template = { ...omit([...align_by, ...group_by], config.template), [actual_flag]: 0 }
+	const subset = pipe(map(pick(align_by)), uniq)(data)
+
+	return pipe(map(pick(align_by)), uniq, difference(subset), map(mergeLeft(template)))
+}
+
+/**
+ * Returns an aggregator object with a mapper and reducer function.
+ *
+ * @param {Array<string>} from  - The key or keys to aggregate.
+ * @param {Function}      using - The aggregation function.
+ * @returns {import('./types').SummaryConfig}  - An object with a mapper and reducer function.
+ */
+// export function getAggregator(from, into, using = identity) {
+// 	// const mapper = pick(Array.isArray ? from : [from])
+// 	return {
+// 		mapper: pick(from),
+// 		reducers: [{ field: into, formula: using }]
+// 	}
+// }
+
+/**
+ * Returns the default aggregator which rolls up the columns other than the group_by columns into a single object.
+ *
+ * @param {import('./types').Metadata} metadata - The metadata for the columns to be aggregated.
+ * @param {Object} config                       - The configuration used to build the aggregator.
+ *
+ * @returns {Object} An object containing the default aggregator for the specified metadata and configuration.
+ */
+// export function defaultAggregator(metadata, config) {
+// 	const child = metadata.filter((col) => !config.group_by.includes(col.name))
+// 	const keys = child.map((col) => col.name)
+
+// 	return { ...getAggregator(keys, config.children), metadata: child }
+// }

package/src/types.js

@@ -0,0 +1,208 @@
+/**
+ * Options for the sort order of the column.
+ *
+ * @typedef {'ascending'|'descending'|'none'} SortOptions
+ */
+
+/**
+ * Options for aligning text in a column.
+ * @typedef {'left'|'center'|'right'|'justify'} HorizontalAlignOptions
+ */
+
+/**
+ * Options for the action type of the column.
+ * @typedef {'edit'|'delete'|'select'} ActionTypes
+ */
+
+/**
+ * @typedef {'checked'|'unchecked'|'indeterminate'} SelectionState
+ */
+
+/**
+ * @typedef {string|[string,boolean]|ColumnSorter} SortableColumn
+ */
+
+/**
+ * @typedef {Object} ColumnSorter
+ * @property {string}   name
+ * @property {function} sorter
+ */
+
+/**
+ * @typedef {Object} ColumnAggregator
+ * @property {string}   name
+ * @property {function} aggregator
+ * @property {string}   suffix
+ */
+
+/**
+ * Options for joining two data sets
+ *
+ * @typedef OptionsToRenameKeys
+ * @property {string} [prefix]         - Prefix to be added to each attribute
+ * @property {string} [suffix]         - Suffix to be added to each attribute
+ * @property {string} [separator='_']  - Separator to be used when adding prefix or suffix. defaults to _
+ */
+
+/**
+ * Structure to map custom fields for rendering. This is used to identofy the attributes for various purposes.
+ *
+ * @typedef FieldMapping
+ * @property {string} [id='id']              Unique id for the item
+ * @property {string} [text='text']          the text to render
+ * @property {string} [value='value']        the value associated with the item
+ * @property {string} [url='url']            a URL
+ * @property {string} [icon='icon']          icon to render
+ * @property {string} [image='image']        the image to render
+ * @property {string} [children='children']  children of the item
+ * @property {string} [summary='summary']    summary of the item
+ * @property {string} [notes='notes']        notes for the item
+ * @property {string} [props='props']        additional properties
+ * @property {string} [isOpen='_open']       item is open or closed
+ * @property {string} [level='level']        level of item
+ * @property {string} [parent='parent']      item is a parent
+ * @property {string} [currency='currency]   column specifying currency to be used for the current value
+ * @property {string} [isDeleted='_deleted'] item is deleted
+ * @property {FieldMapping} [fields]         Field mapping to be used on children in the next level
+ */
+
+/**
+ * Column metadata for the table.
+ *
+ * @typedef {Object} ColumnMetadata
+ *
+ * @property {string}                 name        - The name of the column.
+ * @property {string}                 type        - The data type of the column (e.g., "string", "number", "date").
+ * @property {FieldMapping}           [field] - The field mapping for the column.
+ * @property {number}                 [digits=0]  - The number of digits for numeric values (defaults to 0).
+ * @property {Function}               formatter   - A function to format the column value.
+ * @property {boolean}                [sortable]  - Indicates if the column is sortable (true/false).
+ * @property {SortOptions}            [sortOrder] - The sort order of the column.
+ * @property {HorizontalAlignOptions} [align]     - The alignment of the column content.
+ * @property {ActionTypes}            [action]    - Action attribute for action columns.
+ */
+
+/**
+ * @typedef {Array<ColumnMetadata>} Metadata
+ */
+
+/**
+ * @typedef {Object<string,number} ColumnIndexMap
+ */
+
+/**
+ * Track the state of a row in the table.
+ *
+ * @typedef {Object} TreeTableNode
+ * @property {number}         row          - Reference to actual row in the data.
+ * @property {number}         depth        - The depth of the node in the hierarchy.
+ * @property {string}         [value]      - The value of the hierarchy node.
+ * @property {boolean}        [isHidden]   - Indicates whether the node is visible (true/false).
+ * @property {boolean}        [isParent]   - Indicates if this node is a parent (true/false).
+ * @property {boolean}        [isExpanded] - Indicates whether the node is expanded (true/false).
+ * @property {number}         [parent]     - Reference to the parent node in the flat list.
+ * @property {SelectionState} [selected]   - Indicates whether the node is selected (true/false/indeterminate).
+ * @property {Array<any>}     children     - Reference to the children nodes in the flat list.
+ */
+
+/**
+ * Track the state of all rows in the table.
+ *
+ * @typedef {Object} TreeTable
+ * @property {TreeTableNode[]} rows - Flat list of hierarchy nodes.
+ */
+
+/**
+ * @typedef {Object} OverrideConfig
+ * @property {string} actual_flag - the field used for identifying filler rows in the data
+ * @property {string} children    - the field used for collecting children of a node in rollup
+ */
+
+/**
+ * @typedef {Object} ReducerConfig
+ * @property {string}   field - The target field to hold the reduced value
+ * @property {Function} using - The function to use for reducing the data
+ */
+
+/**
+ * @typedef {Object} SummaryConfig
+ * @property {Function}            mapper     - A function used to collect the data for the summary
+ * @property {Array<ReducerConfig} reducers   - Array of reducer configurations
+ * @property {Metadata}            [metadata] - Array of column metadata for the summary
+ */
+
+/**
+ * @typedef {Object} DataFrameConfig
+ * @property {Array<string>} group_by=[]         - The columns to group by.
+ * @property {Array<string>} align_by=[]         - The columns to be aligned during rollup.
+ * @property {Array<SummaryConfig>} summaries=[] - Array of summary configurations.
+ * @property {any} template={}                   - Template row to be used for filling in missing rows.
+ * @extends OverrideConfig
+ */
+
+/**
+ * @typedef {Function} SortBy
+ * @description Sort the DataFrame by the specified columns.
+ * @param {SortableColumn} columns - The columns to sort by.
+ * @returns {DataFrame}            - The sorted DataFrame.
+ */
+
+/**
+ * DataFrame-like object with data manipulation methods.
+ *
+ * @typedef {Object} DataFrame
+ * @property {Array<Object>}                         data       - Array of objects representing the rows of data.
+ * @property {Metadata}                              metadata   - Array of column metadata for the data.
+ * @property {DataFrameConfig}                       config     - Configuration options for the DataFrame.
+ * @property {ColumnIndexMap}                        columns    - A map of column names to their index in the metadata.
+ * @property {function(OverrideConfig):DataFrame}    override   - Method to override the configuration of the DataFrame.
+ * @property {function(...string):DataFrame}         groupBy    - Method to group the DataFrame by specified columns.
+ * @property {function(function(any)):DataFrame}     where      - Sets the filter function for the DataFrame
+ * @property {function():DataFrame}                  align      - Method to align the DataFrame.
+ * @property {function():DataFrame}                  using      - set the template to be used for filling in missing rows.
+ * @property {function():DataFrame}                  summarize  - add a summarizer to be used during rollup
+ * @property {function(...SortableColumn):DataFrame} sortBy     - Method to sort the DataFrame by specified columns.
+ * @property {function():DataFrame}                  join       - perform join with another DataFrame returning a new DataFrmae. Defaults to innerJoin, other join types can be specified.
+ * @property {function():DataFrame}                  innerJoin  - perform an ineer join with another DataFrame and return a new DataFrame.
+ * @property {function():DataFrame}                  leftJoin   - perform a left join with another DataFrame and return a new DataFrame.
+ * @property {function():DataFrame}                  rightJoin  - perform a right join with another DataFrame returning a new DataFrame.
+ * @property {function():DataFrame}                  fullJoin   - perform a full join with another DataFrame returning a new DataFrame.
+ * @property {function():DataFrame}                  nestedJoin - perform a nested join with another DataFrame returning a new DataFrame.
+ * @property {function():DataFrame}                  rename     - Method to rename the columns of the DataFrame.
+ * @property {function():DataFrame}                  drop       - Method to drop the columns of the DataFrame.
+ * @property {function():DataFrame}                  delete     - Method to delete the rows of the DataFrame.
+ * @property {function():DataFrame}                  update     - Method to update the rows of the DataFrame.
+ * @property {function():DataFrame}                  union      - Method to combine the rows of the DataFrame with another DataFrame.
+ * @property {function():DataFrame}                  minus      - Method to remove the rows of the DataFrame which are present in another DataFrame.
+ * @property {function():DataFrame}                  intersect  - Method to keep the rows of the DataFrame which are present in another DataFrame.
+ * @property {function():DataFrame}                  rollup     - Method to rollup the DataFrame.
+ * @property {function():Arrat<Object>}              select     - Method to select the columns of the DataFrame.
+
+ */
+
+/**
+ * @typedef {inner|outer|full|nested} JoinType
+ */
+/**
+ * Options for joining two data sets
+ *
+ * @typedef JoinOptions
+ * @property {boolean} [inner]                - Flag indicating inner join
+ * @property {JoinType} [type='inner]         - The join type to use (inner, outer, full, nested).
+ * @property {string} [prefix]                - prefix to be used for renaming keys in the second data set.
+ * @property {string} [suffix]                - suffix to be used for renaming keys in the second data set.
+ * @property {string} [separator='_']         - separator to be used for renaming keys in the second data set.
+ */
+
+/**
+ * DataView
+ * @typedef {Object} DataView
+ * @property {TreeTable} hierarchy - The state of the rows in the table.
+ * @property {Metadata} columns      - The metadata for the columns in the table.
+ * @property {Function} sortBy       - Sort the DataView by the specified columns.
+ * @property {Function} clearSort    - Clear the sorting of the DataView.
+ * @property {Function} filter       - Filter the DataView by the specified columns.
+ * @property {Function} toggle      - toggle expand or collapse the DataView by the specified columns.
+ * @property {Function} select      - select the DataView by the specified columns.
+ */
+export {}

package/src/utils.js

@@ -0,0 +1,31 @@
+/**
+ * Check if a value is a date string
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isDateString(value) {
+	return !isNaN(Date.parse(value))
+}
+
+/**
+ * Infer the type of a value as array, date or the default type
+ * @param {any} value
+ * @returns {string}
+ */
+function inferArrayAndDateTypes(value) {
+	if (Array.isArray(value)) return 'array'
+	if (value instanceof Date) return 'date'
+
+	return typeof value
+}
+/**
+ * Derive the type of a value
+ * @param {any} value
+ * @returns {string}
+ */
+export function getType(value) {
+	const type = inferArrayAndDateTypes(value)
+	if (type === 'string' && isDateString(value)) return 'date'
+	if (type === 'number' && Number.isInteger(value)) return 'integer'
+	return type
+}