@rokkit/data 1.0.0-next.94

package/src/index.js

@@ -0,0 +1,6 @@
+import './types'
+export * 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 { getType } 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 = getType(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 = getType(nonNullValues[0])
+
+	for (let i = 1; i < nonNullValues.length; i++) {
+		if (getType(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]
+}

package/src/list.js

@@ -0,0 +1,232 @@
+import { writable, get } from 'svelte/store'
+import { ascending } from 'd3-array'
+import { nest } from 'd3-collection'
+import { v4 as uuid } from '@lukeed/uuid'
+
+/**
+ * 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, b, data) {
+	let result = 0
+
+	if (data.groupKey) {
+		result = ascending(data.lookup[a[data.groupKey]], data.lookup[b[data.groupKey]])
+	}
+	if (result === 0) {
+		result = ascending(a[data.sortKey], b[data.sortKey])
+	}
+	return result
+}
+
+/**
+ * Search the data for existence of string in the data
+ *
+ * @param {List} data
+ * @param {string} value
+ * @returns
+ */
+export function quickSearch(data, value) {
+	return data.data.filter((d) => d[data.filterKey].toLowerCase().includes(value.toLowerCase()))
+}
+
+/**
+ * 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) {
+		this.data = data
+
+		this.primaryKey = 'id'
+		this.filterKey = undefined
+		this.sortKey = undefined
+		this.groupKey = undefined
+		this.lookup = {}
+		this.searchText = ''
+
+		this.filterUsing = undefined
+		this.sortUsing = undefined
+		this.filtered = writable(data)
+	}
+
+	/**
+	 * 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) {
+		this.primaryKey = value
+		this.data = this.data.map((item) => (value in item ? item : { ...item, [value]: uuid() }))
+
+		return this
+	}
+
+	/**
+	 * 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, using = compare) {
+		this.sortKey = key
+		this.sortUsing = using
+
+		return this.sort().refresh()
+	}
+
+	/**
+	 * 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, lookup = null) {
+		this.groupKey = key
+
+		if (lookup) this.lookup = lookup
+		else
+			this.lookup = this.data
+				.map((item) => item[key])
+				.reduce((obj, value) => ({ ...obj, [value]: value }), {})
+
+		return this.sort().refresh()
+	}
+
+	/**
+	 * 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, using = quickSearch) {
+		this.filterKey = key
+		this.filterUsing = using
+		return this
+	}
+
+	/**
+	 * Sorts the list based on the configured sorting function.
+	 *
+	 * @returns {List} This list instance for method chaining.
+	 */
+	sort() {
+		if (this.sortUsing) this.data.sort((a, b) => this.sortUsing(a, b, this))
+		return this
+	}
+
+	/**
+	 * 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) {
+		const index = this.data.findIndex((d) => d[this.primaryKey] === item[this.primaryKey])
+		if (index === -1) {
+			if (!(this.primaryKey in item)) {
+				item[this.primaryKey] = uuid()
+			}
+			this.data.push(item)
+			this.sort().refresh()
+		}
+		return this
+	}
+
+	/**
+	 * 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) {
+		const index = this.data.findIndex((d) => d[this.primaryKey] === item[this.primaryKey])
+		if (index > -1) {
+			this.data = [...this.data.slice(0, index), ...this.data.slice(index + 1)]
+			this.refresh()
+		}
+		return this
+	}
+
+	/**
+	 * 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) {
+		const index = this.data.findIndex((d) => d[this.primaryKey] === item[this.primaryKey])
+		if (index > -1) {
+			this.data[index] = { ...item }
+			this.sort().refresh()
+		}
+		return this
+	}
+
+	/**
+	 * 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) {
+		this.searchText = text
+		return this.refresh()
+	}
+
+	/**
+	 * Refreshes the list based on current sorting, grouping, and filtering configuration.
+	 *
+	 * @returns {List} This list instance for method chaining.
+	 */
+	refresh() {
+		let data = [...this.data]
+
+		if (this.filterKey && this.searchText) {
+			data = this.filterUsing(this, this.searchText)
+		}
+
+		if (this.groupKey) {
+			data = nest()
+				.key((d) => d[this.groupKey])
+				.entries(data)
+				.map(({ key, values }) => ({
+					key,
+					name: this.lookup[key],
+					data: values
+				}))
+		}
+
+		this.filtered.set(data)
+		return this
+	}
+	/**
+	 * Gets the current state of the filtered list data.
+	 *
+	 * @returns {Array<object>} The current filtered data of the list.
+	 */
+	current() {
+		return get(this.filtered)
+	}
+}
+
+/**
+ * Create a new list
+ *
+ * @param {Array<object>} data
+ * @returns
+ */
+export function list(data) {
+	return new List(data)
+}

package/src/metadata.js

@@ -0,0 +1,106 @@
+import { defaultPathOptions } from './constants'
+import { getDeepScanSample } from './infer'
+import { getType } from './utils'
+
+/**
+ * Merges currency-related attributes into the corresponding base columns.
+ *
+ * @param {Array<Object>} input - An array of column definitions.
+ * @param {string} currencySuffix - The suffix used to identify currency columns.
+ * @returns {Array<Object>} A new array of merged column definitions.
+ */
+function mergeCurrencyAttributes(input, currencySuffix) {
+	let currencyColumns = input.filter((col) => col.name.endsWith(currencySuffix))
+	const columns = input.filter((col) => !col.name.endsWith(currencySuffix))
+
+	currencyColumns = currencyColumns
+		.map((col) => {
+			const matched = columns.find((column) => column.name === col.name.replace(currencySuffix, ''))
+			if (matched) {
+				matched.fields.currency = col.name
+				matched.type = 'currency'
+				matched.digits = 2
+				return null
+			}
+			return col
+		})
+		.filter((col) => col !== null)
+
+	return [...columns, ...currencyColumns]
+}
+
+/**
+ * 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, path, separator) {
+	if (!path) return columns
+
+	const index = columns.findIndex((col) => col.name === path)
+	if (index > -1) {
+		return [
+			{ ...columns[index], path: true, separator },
+			...columns.slice(0, index),
+			...columns.slice(index + 1)
+		]
+	}
+	return columns
+}
+
+/**
+ * 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, options) {
+	const { path, separator, currencySuffix } = { ...defaultPathOptions, ...options }
+
+	let columns = Object.keys(sample).map((key) => ({
+		name: key,
+		type: getType(sample[key]),
+		sortable: true,
+		filterable: true,
+		sorted: 'none',
+		fields: { text: key }
+	}))
+
+	columns = addPathModifier(columns, path, separator)
+	return mergeCurrencyAttributes(columns, currencySuffix)
+}
+
+/**
+ * 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, options = {}) {
+	const { metadata, deepScan = false } = options
+	if (Array.isArray(metadata) && metadata.length > 0) return metadata
+	if (data.length === 0) return []
+	const sample = deepScan ? getDeepScanSample(data) : data[0]
+	return Object.entries(sample).map(([name, value]) => ({ name, type: getType(value) }))
+}
+
+/**
+ * Derive column index from metadata.
+ * @param {Array} metadata - The metadata array.
+ * @returns {Object} - The column index object.
+ */
+// export function deriveColumnIndex(metadata) {
+// 	return metadata.reduce((acc, col, index) => {
+// 		acc[col.name] = index
+// 		return acc
+// 	}, {})
+// }

package/src/model.js

@@ -0,0 +1,100 @@
+import { identity, clone as copy } from 'ramda'
+import { getDeepScanSample } from './infer'
+import { getType } from './utils'
+
+/**
+ * A model is a representation of a dataset
+ * @returns an object with methods to manipulate the model
+ */
+export function model() {
+	let data = []
+
+	const actions = {
+		get: () => data,
+		/*
+		 * Creates a clone from another model
+		 * @param {Object} other - the other model object to clone from
+		 */
+		clone: (other) => {
+			data = copy(other.get())
+			return actions
+		},
+		/**
+		 * Renames the reference names using a renamer
+		 * @param {Function} rename - the renamer function
+		 */
+		renameUsing: (rename = identity) => {
+			if (rename !== identity) {
+				data = data.map((x) => ({ ...x, name: rename(x.name) }))
+			}
+			return actions
+		},
+		/**
+		 * 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, sparseData) => {
+			data = deriveModel(value, sparseData)
+			return actions
+		},
+		/**
+		 * 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, override = false) => {
+			data = mergeModels(data, other.get(), override)
+			return actions
+		}
+	}
+	return actions
+}
+
+/**
+ * Derives a model from the input data
+ *
+ * @param {Array|Object} data  - the data to derive the model from
+ * @param {Boolean}      sparse - whether the data set contains sparse data
+ * @returns {Array}             - the derived model
+ */
+function deriveModel(data, sparse = false) {
+	const model = []
+	let item = data
+
+	if (Array.isArray(data)) item = sparse ? getDeepScanSample(data) : data[0]
+
+	const kv = Object.entries(item)
+	kv.forEach(([key, value]) => {
+		model.push({
+			name: key,
+			type: getType(value)
+		})
+	})
+	return model
+}
+
+/**
+ * Merges two models, returning a new model
+ *
+ * @param {Array} first      - the first model
+ * @param {Array} second     - the second model
+ * @param {Boolean} override - whether to override the type of the first model
+ * @returns {Array}      - the merged model
+ */
+function mergeModels(first, second, override = false) {
+	second.forEach(({ name, type }) => {
+		const existing = first.find((x) => x.name === name)
+		if (existing) {
+			if (existing.type !== type) existing.mixedTypes = true
+			if (override) existing.type = type
+		} else {
+			first.push({ name, type })
+		}
+	})
+	return first
+}