@rokkit/data 1.0.0-next.100

package/src/filter.js

@@ -0,0 +1,57 @@
+import { filterOperations } from './constants'
+
+/**
+ * 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, options) {
+	const { column, value, operator } = options
+	// If no operator or value is given, return the data unchanged.
+	if (!operator || !value) return data
+	// If a column is specified, perform the filtering on that specific column.
+	if (column) return data.filter((row) => filterOperations[operator](row[column], value))
+
+	return data.filter((row) => findMatchingRow(row, value, operator))
+}
+
+/**
+ * Checks if a row matches the given value based on the specified operator.
+ * Supports both standard and negated operators by checking the operator string
+ * for a leading '!' character, which indicates negation.
+ *
+ * @param {Object} row - The row object in which to search for the value match.
+ * @param {any} value - The value to match against the row's properties.
+ * @param {string} operator - The operator used to compare the row's properties to the value.
+ *                            When operator starts with '!', it negates the result of the comparison.
+ * @returns {boolean} - Returns true if the row matches the condition; otherwise, returns false.
+ */
+function findMatchingRow(row, value, operator) {
+	const op = operator.startsWith('!') ? operator.slice(1) : operator
+	const matched = Object.keys(row).some((key) => filterOperations[op](row[key], value))
+
+	return operator.startsWith('!') ? !matched : matched
+}
+
+/**
+ * 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, filters) {
+	let filteredData = data
+	filters.forEach((filter) => {
+		filteredData = filterObjectArray(filteredData, filter)
+	})
+	return filteredData
+}

package/src/formatter.js

@@ -0,0 +1,56 @@
+import { identity } from 'ramda'
+
+const formatterMap = {
+	currency: getCurrencyFormatter,
+	integer: (language) => (val) => val.toLocaleString(language, { maximumFractionDigits: 0 }),
+	number: (language, decimalPlaces) => (val) =>
+		val.toLocaleString(language, {
+			minimumFractionDigits: decimalPlaces,
+			maximumFractionDigits: decimalPlaces
+		}),
+	date: (language) => (val) => val.toLocaleDateString(language),
+	time: (language) => (val) => val.toLocaleTimeString(language),
+	object: () => JSON.stringify,
+	array: () => JSON.stringify, // Combined formatter for 'object' and 'array'
+	ellipsis: () => () => '...' // Static formatter, no need for parameters
+}
+
+/**
+ * Returns a currency formatter function that formats a value as a currency string.
+ * @param {string} language       - The IETF language tag used for locale-specific formatting.
+ * @param {number} decimalPlaces  - The number of decimal places to show with currency formatting.
+ * @returns {function}            - A currency formatter function that takes a value and returns a formatted string.
+ */
+function getCurrencyFormatter(language, decimalPlaces) {
+	/**
+	 * Formats a value as a currency string with the desired decimal places.
+	 *
+	 * @param {number} val              - The value to format as a currency string.
+	 * @param {string} [currency='USD'] - The currency code to use for formatting.
+	 * @returns {string}                - The formatted currency string.
+	 */
+	const formatter = (val, currency = 'USD') =>
+		val.toLocaleString(language, {
+			style: 'currency',
+			currency,
+			minimumFractionDigits: decimalPlaces,
+			maximumFractionDigits: decimalPlaces
+		})
+	return formatter
+}
+
+/**
+ * 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, language = 'en-US', decimalPlaces = 2) {
+	const formatter = formatterMap[type]
+	if (formatter) return formatter(language, decimalPlaces)
+
+	return identity
+}

package/src/hierarchy.js

@@ -0,0 +1,136 @@
+import { defaultViewOptions } from './constants'
+/**
+ * Removes objects from an array where the parent attribute is not null.
+ * @param {Array<Object>} arr - The array of objects.
+ */
+export function removeChildren(arr) {
+	for (let i = arr.length - 1; i >= 0; i--) {
+		if (arr[i].parent) arr.splice(i, 1)
+	}
+}
+/**
+ * Flatten nested children arrays within an array of objects.
+ * @param {Array<Object>} arr - The array of objects.
+ */
+export function flattenNestedChildren(arr) {
+	let index = 0
+	while (index < arr.length) {
+		if (Array.isArray(arr[index].children) && arr[index].children.length > 0) {
+			const children = arr[index].children
+			arr.splice(index + 1, 0, ...children)
+		}
+		index++
+	}
+}
+
+/**
+ * Recursively updates parent items' flags based on the child's flags.
+ * @param {Object} item - The current object.
+ */
+function updateParentFlags(item) {
+	if (!item.parent) return
+	if (item.parent.excluded) {
+		item.parent.excluded = false
+		item.parent.retainedByChild = true
+
+		updateParentFlags(item.parent)
+	}
+}
+
+/**
+ * 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, filterFn) {
+	arr.forEach((item) => {
+		item.excluded = !filterFn(item)
+	})
+
+	arr.forEach((item) => {
+		if (!item.excluded) updateParentFlags(item)
+	})
+}
+
+/**
+ * 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, options) {
+	const { expanded, path, separator } = { ...defaultViewOptions, ...options }
+	if (!path) return data.map((row) => ({ depth: 0, row }))
+
+	const hierarchy = data.map((row) => {
+		const parts = row[path].split(separator).filter((part) => part.length > 0)
+		const depth = parts.length
+		const value = depth > 0 ? parts[depth - 1] : ''
+		return { depth, value, path: row[path], row }
+	})
+
+	hierarchy.forEach((row) => {
+		row.children = hierarchy.filter(
+			(child) => child.path.startsWith(row.path) && row.depth === child.depth - 1
+		)
+
+		row.isParent = row.children.length > 0
+		if (row.isParent) {
+			row.isExpanded = expanded
+			row.isHidden = !row.parent ? false : row.parent.isHidden || !row.parent.isExpanded
+		}
+		row.children.forEach((child) => {
+			child.parent = row
+			child.isHidden = row.isHidden || !row.isExpanded
+		})
+	})
+	return hierarchy
+}
+
+/**
+ * Recursively sets the visibility of child nodes based on the hidden and expanded state
+ * of their parent node.
+ *
+ * @param {Object} node - The parent node whose children's visibility will be changed.
+ *                        The node is expected to have a 'children' property which is an
+ *                        array of child nodes, a 'isHidden' property indicating if the
+ *                        node is hidden, and a 'isExpanded' property indicating if the
+ *                        node is expanded.
+ */
+function changeVisibilityForChildren(node) {
+	if (node.children) {
+		node.children.forEach((child) => {
+			child.isHidden = node.isHidden || !node.isExpanded
+			changeVisibilityForChildren(child)
+		})
+	}
+}
+
+/**
+ * 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) {
+	if (node.isParent) {
+		node.isExpanded = !node.isExpanded
+		changeVisibilityForChildren(node)
+	}
+}
+
+// function hierarchy(data, options){
+//   const nodes = deriveHierarchy(data, options)
+
+//   return {
+//     nodes,
+//     filter: (fn) => hierarchicalFilter(nodes, fn),
+//     selection:
+//   }
+// }

package/src/index.js

@@ -0,0 +1,7 @@
+// skipcq: JS-E1004 - Needed for exposing all types
+export * from './types'
+export { typeOf } from './utils'
+export { renamer } from './renamer'
+export { model } from './model'
+export { dataset } from './dataset'
+export { dataview } from './view'

package/src/infer.js

@@ -0,0 +1,263 @@
+import { ascending, descending } from 'd3-array'
+import { compact } from '@rokkit/core'
+import { omit } from 'ramda'
+import { createFormatter } from './formatter'
+import { defaultViewOptions, defaultActionOrder } from './constants'
+import { typeOf } from './utils'
+import { deriveColumnProperties } from './metadata'
+
+/**
+ * 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) {
+	const type = typeOf(value)
+
+	const configGenerators = {
+		array: arrayConfigGenerator,
+		object: objectConfigGenerator,
+		string: stringConfigGenerator
+	}
+
+	const configGenerator = configGenerators[type]
+	if (!configGenerator) {
+		throw new Error(`Invalid value type: ${type}`)
+	}
+
+	return configGenerator(value)
+}
+
+/**
+ * Generates a sorting configuration for an array value.
+ *
+ * @param {Array} value - The array from which to derive a sorting configuration.
+ * @returns {Object} A validated sorting configuration based on the array.
+ */
+function arrayConfigGenerator(value) {
+	arrayValidator(value)
+	return { name: value[0], sorter: value[1] ? ascending : descending }
+}
+
+/**
+ * Generates a sorting configuration for an object value.
+ *
+ * @param {Object} value - The object from which to derive a sorting configuration.
+ * @returns {Object} A validated sorting configuration based on the object.
+ */
+function objectConfigGenerator(value) {
+	objectValidator(value)
+	return { name: value.name, sorter: value.sorter ?? ascending }
+}
+
+/**
+ * Generates a sorting configuration for a string value.
+ *
+ * @param {string} value - The string from which to derive a sorting configuration.
+ * @returns {Object} A sorting configuration using the string name and ascending sort function.
+ */
+function stringConfigGenerator(value) {
+	return { name: value, sorter: ascending }
+}
+
+/**
+ * Validates an array to ensure it can be used to create a sorting configuration.
+ *
+ * @param {Array} value - The array to validate.
+ * @throws {Error} Throws an error if the array does not correspond to a [string, boolean] pair.
+ */
+function arrayValidator(value) {
+	if (value.length !== 2 || typeof value[0] !== 'string' || typeof value[1] !== 'boolean') {
+		throw new Error('Array should be a pair of [string, boolean]')
+	}
+}
+
+/**
+ * Validates an object to ensure it has the necessary properties for creating a sorting configuration.
+ *
+ * @param {Object} value - The object to validate.
+ * @throws {Error} Throws an error if the object does not have a 'name' property or has an invalid 'sorter'.
+ */
+function objectValidator(value) {
+	if (typeof value.name !== 'string') {
+		throw new Error('The property "name" is required and must be a string')
+	}
+	if (value.sorter !== undefined && typeof value.sorter !== 'function') {
+		throw new Error('Sorter should be a function')
+	}
+}
+
+/**
+ * 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 getDeepScanSample(data) {
+	return data.reduce(
+		(acc, cur) => ({
+			...acc,
+			...compact(omit(Object.keys(acc), cur))
+		}),
+		{}
+	)
+}
+/**
+ * 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, options) {
+	if (data.length === 0) return []
+
+	const { scanMode } = { ...defaultViewOptions, ...options }
+	const sample = scanMode === 'fast' ? data[0] : getDeepScanSample(data)
+
+	return deriveColumnProperties(sample, options)
+}
+
+/**
+ * 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) {
+	const dataTypes = Object.keys(data[0])
+		.map((field) => ({
+			field,
+			type: data.map((d) => d[field]).some(isNaN) ? 'string' : 'number'
+		}))
+		.reduce((acc, cur) => ({ ...acc, [cur.type]: [...acc[cur.type], cur.field] }), {
+			string: [],
+			number: []
+		})
+	return dataTypes
+}
+
+/**
+ * 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) {
+	if (values.length === 0) {
+		return 'undefined'
+	}
+
+	const nonNullValues = values.filter((value) => value !== null)
+
+	if (nonNullValues.length === 0) {
+		return 'null'
+	}
+
+	let type = typeOf(nonNullValues[0])
+
+	for (let i = 1; i < nonNullValues.length; i++) {
+		if (typeOf(nonNullValues[i]) !== type) {
+			type = 'mixed'
+			break
+		}
+	}
+
+	return type
+}
+
+/**
+ * Derives column metadata from the data to be used in a tabular component.
+ *
+ * @param {Array} data - The data to derive column metadata from.
+ * @returns {Array<import('./types').ColumnMetadata>} - The derived column metadata.
+ */
+export function deriveMetadata(dataArray, options = {}) {
+	let { columns = [] } = options
+	if (dataArray.length === 0) return columns
+	const { actions, language } = { ...defaultViewOptions, ...options }
+
+	if (columns.length === 0) {
+		columns = deriveColumns(dataArray, options)
+	} else {
+		columns.forEach((col) => {
+			// if (col.sortable && !col.order) col.order = 'none'
+			if (!col.fields) col.fields = { text: col.name }
+		})
+	}
+	columns = addFormatters(columns, language)
+	if (actions.length > 0) columns = deriveActions(columns, actions)
+
+	return columns
+}
+
+/**
+ * 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, language) {
+	return columns.map((column) => {
+		const formatter = column.formatter ?? column.type
+		if (typeof formatter !== 'function') {
+			const digits = column.digits ?? (['number', 'currency'].includes(column.type) ? 2 : 0)
+			column.formatter = createFormatter(formatter, language, digits)
+		}
+		return column
+	})
+}
+
+/**
+ * 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) {
+	if (!Array.isArray(input)) throw new Error('Actions must be an array')
+	const actions = input
+		.map((action) => {
+			if (typeof action === 'string') {
+				return { name: action, label: action, order: defaultActionOrder[action] }
+			}
+			return { order: defaultActionOrder[action.name], ...action }
+		})
+		.sort((a, b) => a.order - b.order)
+	return actions
+}
+/**
+ * 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, input) {
+	// convert array of strings to array of objects
+	const actions = convertToActions(input)
+	const existing = columns.filter(({ action }) => action).map(({ action }) => action)
+
+	const actionColumns = actions
+		.filter(({ name }) => !existing.includes(name))
+		.map(({ name, label }) => ({
+			label,
+			action: name
+		}))
+	return [...actionColumns, ...columns]
+}