@d3plus/data 3.0.0-alpha.0

package/README.md

@@ -0,0 +1,135 @@
+# @d3plus/data
+  
+JavaScript data loading, manipulation, and analysis functions.
+
+## Installing
+
+If using npm, `npm install @d3plus/data`. Otherwise, you can download the [latest release from GitHub](https://github.com/d3plus/d3plus/releases/latest) or load from a [CDN](https://cdn.jsdelivr.net/npm/@d3plus/data@3.0.0-alpha.0/+esm).
+
+```js
+import modules from "@d3plus/data";
+```
+
+In vanilla JavaScript, a `d3plus` global is exported from the pre-bundled version:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@d3plus/data@3.0.0-alpha.0"></script>
+<script>
+  console.log(d3plus);
+</script>
+```
+
+## Examples
+
+Live examples can be found on [d3plus.org](https://d3plus.org/), which includes a collection of example visualizations using @d3plus/react.
+
+## API Reference
+
+##### 
+* [isData](#isData) - Adds the provided value to the internal queue to be loaded, if necessary. This is used internally in new d3plus visualizations that fold in additional data sources, like the nodes and links of Network or the topojson of Geomap.
+* [dataConcat](#dataConcat) - Reduce and concat all the elements included in arrayOfArrays if they are arrays. If it is a JSON object try to concat the array under given key data. If the key doesn't exists in object item, a warning message is lauched to the console. You need to implement DataFormat callback to concat the arrays manually.
+* [dataFold](#dataFold) - Given a JSON object where the data values and headers have been split into separate key lookups, this function will combine the data values with the headers and returns one large array of objects.
+* [isData](#isData) - Returns true/false whether the argument provided to the function should be loaded using an internal XHR request. Valid data can either be a string URL or an Object with "url" and "headers" keys.
+* [dataLoad](#dataLoad) - Loads data from a filepath or URL, converts it to a valid JSON object, and returns it to a callback function.
+* [merge](#merge) - Combines an Array of Objects together and returns a new Object.
+* [unique](#unique) - ES5 implementation to reduce an Array of values to unique instances.
+
+---
+
+<a name="isData"></a>
+#### d3plus.**isData**(data, [data], data) [<>](https://github.com/d3plus/d3plus/blob/main/packages/data/src/addToQueue.js#L4)
+
+Adds the provided value to the internal queue to be loaded, if necessary. This is used internally in new d3plus visualizations that fold in additional data sources, like the nodes and links of Network or the topojson of Geomap.
+
+
+This is a global function
+
+---
+
+<a name="dataConcat"></a>
+#### d3plus.**dataConcat**(arrayOfArray, [data]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/data/src/concat.js#L1)
+
+Reduce and concat all the elements included in arrayOfArrays if they are arrays. If it is a JSON object try to concat the array under given key data. If the key doesn't exists in object item, a warning message is lauched to the console. You need to implement DataFormat callback to concat the arrays manually.
+
+
+This is a global function
+
+---
+
+<a name="dataFold"></a>
+#### d3plus.**dataFold**(json, [data], [headers]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/data/src/fold.js#L1)
+
+Given a JSON object where the data values and headers have been split into separate key lookups, this function will combine the data values with the headers and returns one large array of objects.
+
+
+This is a global function
+
+---
+
+<a name="isData"></a>
+#### d3plus.**isData**(dataItem) [<>](https://github.com/d3plus/d3plus/blob/main/packages/data/src/isData.js#L1)
+
+Returns true/false whether the argument provided to the function should be loaded using an internal XHR request. Valid data can either be a string URL or an Object with "url" and "headers" keys.
+
+
+This is a global function
+
+---
+
+<a name="dataLoad"></a>
+#### d3plus.**dataLoad**(path, [formatter], [key], [callback]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/data/src/load.js#L8)
+
+Loads data from a filepath or URL, converts it to a valid JSON object, and returns it to a callback function.
+
+
+This is a global function
+
+---
+
+<a name="merge"></a>
+#### d3plus.**merge**(objects, aggs) [<>](https://github.com/d3plus/d3plus/blob/main/packages/data/src/merge.js#L4)
+
+Combines an Array of Objects together and returns a new Object.
+
+
+This is a global function
+this
+
+```js
+merge([
+  {id: "foo", group: "A", value: 10, links: [1, 2]},
+  {id: "bar", group: "A", value: 20, links: [1, 3]}
+]);
+    
+```
+returns this
+
+```js
+{id: ["bar", "foo"], group: "A", value: 30, links: [1, 2, 3]}
+```
+
+---
+
+<a name="unique"></a>
+#### d3plus.**unique**(arr, [accessor]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/data/src/unique.js#L1)
+
+ES5 implementation to reduce an Array of values to unique instances.
+
+
+This is a global function
+this
+
+```js
+unique(["apple", "banana", "apple"]);
+    
+```
+returns this
+
+```js
+["apple", "banana"]
+```
+
+---
+
+
+###### <sub>Documentation generated on Thu, 13 Mar 2025 19:58:29 GMT</sub>

package/es/index.js

@@ -0,0 +1,8 @@
+export { default as addToQueue } from "./src/addToQueue.js";
+export { default as concat } from "./src/concat.js";
+export { default as fold } from "./src/fold.js";
+export { default as isData } from "./src/isData.js";
+export { default as merge } from "./src/merge.js";
+export { default as load } from "./src/load.js";
+export { default as nest } from "./src/nest.js";
+export { default as unique } from "./src/unique.js";

package/es/src/addToQueue.js

@@ -0,0 +1,36 @@
+function _instanceof(left, right) {
+    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+        return !!right[Symbol.hasInstance](left);
+    } else {
+        return left instanceof right;
+    }
+}
+import isData from "./isData.js";
+import load from "./load.js";
+/**
+  @function isData
+  @desc Adds the provided value to the internal queue to be loaded, if necessary. This is used internally in new d3plus visualizations that fold in additional data sources, like the nodes and links of Network or the topojson of Geomap.
+  @param {Array|String|Object} data The data to be loaded
+  @param {Function} [data] An optional data formatter/callback
+  @param {String} data The internal Viz method to be modified
+*/ export default function(_, f, key) {
+    if (!_instanceof(_, Array)) _ = [
+        _
+    ];
+    var needToLoad = _.find(isData);
+    if (needToLoad) {
+        var prev = this._queue.find(function(q) {
+            return q[3] === key;
+        });
+        var d = [
+            load.bind(this),
+            _,
+            f,
+            key
+        ];
+        if (prev) this._queue[this._queue.indexOf(prev)] = d;
+        else this._queue.push(d);
+    } else {
+        this["_".concat(key)] = _;
+    }
+}

package/es/src/concat.js

@@ -0,0 +1,22 @@
+/**
+  @function dataConcat
+  @desc Reduce and concat all the elements included in arrayOfArrays if they are arrays. If it is a JSON object try to concat the array under given key data. If the key doesn't exists in object item, a warning message is lauched to the console. You need to implement DataFormat callback to concat the arrays manually.
+  @param {Array} arrayOfArray Array of elements
+  @param {String} [data = "data"] The key used for the flat data array if exists inside of the JSON object.
+*/ export default function(arrayOfArrays) {
+    var data = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : "data";
+    return arrayOfArrays.reduce(function(acc, item) {
+        var dataArray = [];
+        if (Array.isArray(item)) {
+            dataArray = item;
+        } else {
+            if (item[data]) {
+                dataArray = item[data];
+            }
+        // else {
+        //   console.warn(`d3plus-viz: Please implement a "dataFormat" callback to concat the arrays manually (consider using the d3plus.dataConcat method in your callback). Currently unable to concatenate (using key: "${data}") the following response:`, item);
+        // }
+        }
+        return acc.concat(dataArray);
+    }, []);
+};

package/es/src/fold.js

@@ -0,0 +1,14 @@
+/**
+  @function dataFold
+  @desc Given a JSON object where the data values and headers have been split into separate key lookups, this function will combine the data values with the headers and returns one large array of objects.
+  @param {Object} json A JSON data Object with `data` and `headers` keys.
+  @param {String} [data = "data"] The key used for the flat data array inside of the JSON object.
+  @param {String} [headers = "headers"] The key used for the flat headers array inside of the JSON object.
+*/ export default function(json) {
+    var data = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : "data", headers = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : "headers";
+    return json[data].map(function(data) {
+        return json[headers].reduce(function(obj, header, i) {
+            return obj[header] = data[i], obj;
+        }, {});
+    });
+};

package/es/src/isData.js

@@ -0,0 +1,11 @@
+/**
+  @function isData
+  @desc Returns true/false whether the argument provided to the function should be loaded using an internal XHR request. Valid data can either be a string URL or an Object with "url" and "headers" keys.
+  @param {*} dataItem The value to be tested
+*/ function _type_of(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
+export default function(dataItem) {
+    return typeof dataItem === "string" || (typeof dataItem === "undefined" ? "undefined" : _type_of(dataItem)) === "object" && dataItem.url && dataItem.headers;
+};

package/es/src/load.js

@@ -0,0 +1,138 @@
+function _instanceof(left, right) {
+    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+        return !!right[Symbol.hasInstance](left);
+    } else {
+        return left instanceof right;
+    }
+}
+function _type_of(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
+import { csv, json, text, tsv } from "d3-request";
+import { isObject } from "@d3plus/dom";
+import fold from "./fold.js";
+import concat from "./concat.js";
+import isData from "./isData.js";
+/**
+  @function dataLoad
+  @desc Loads data from a filepath or URL, converts it to a valid JSON object, and returns it to a callback function.
+  @param {Array|String} path The path to the file or url to be loaded. Also support array of paths strings. If an Array of objects is passed, the xhr request logic is skipped.
+  @param {Function} [formatter] An optional formatter function that is run on the loaded data.
+  @param {String} [key] The key in the `this` context to save the resulting data to.
+  @param {Function} [callback] A function that is called when the final data is loaded. It is passed 2 variables, any error present and the data loaded.
+*/ export default function(path, formatter, key, callback) {
+    var _this = this;
+    var parser;
+    var getParser = function(path) {
+        var ext = path.slice(path.length - 4);
+        switch(ext){
+            case ".csv":
+                return csv;
+            case ".tsv":
+                return tsv;
+            case ".txt":
+                return text;
+            default:
+                return json;
+        }
+    };
+    var validateData = function(err, parser, data) {
+        if (parser !== json && !err && data && _instanceof(data, Array)) {
+            data.forEach(function(d) {
+                for(var k in d){
+                    if (!isNaN(d[k])) d[k] = parseFloat(d[k]);
+                    else if (d[k].toLowerCase() === "false") d[k] = false;
+                    else if (d[k].toLowerCase() === "true") d[k] = true;
+                    else if (d[k].toLowerCase() === "null") d[k] = null;
+                    else if (d[k].toLowerCase() === "undefined") d[k] = undefined;
+                }
+            });
+        }
+        return data;
+    };
+    var loadedLength = function(loadedArray) {
+        return loadedArray.reduce(function(prev, current) {
+            return current ? prev + 1 : prev;
+        }, 0);
+    };
+    var getPathIndex = function(url, array) {
+        return array.indexOf(url);
+    };
+    // If path param is a not an Array then convert path to a 1 element Array to re-use logic
+    if (!_instanceof(path, Array)) path = [
+        path
+    ];
+    var needToLoad = path.find(isData);
+    var loaded = new Array(path.length);
+    var toLoad = [];
+    // If there is a string I'm assuming is a Array to merge, urls or data
+    if (needToLoad) {
+        path.forEach(function(dataItem, ix) {
+            if (isData(dataItem)) toLoad.push(dataItem);
+            else loaded[ix] = dataItem;
+        });
+    } else {
+        loaded[0] = path;
+    }
+    // Load all urls an combine them with data arrays
+    var alreadyLoaded = loadedLength(loaded);
+    toLoad.forEach(function(dataItem) {
+        var headers = {}, url = dataItem;
+        if ((typeof dataItem === "undefined" ? "undefined" : _type_of(dataItem)) === "object") {
+            url = dataItem.url;
+            headers = dataItem.headers;
+        }
+        parser = getParser(url);
+        var request = parser(url);
+        for(var _$key in headers){
+            if (({}).hasOwnProperty.call(headers, _$key)) {
+                request.header(_$key, headers[_$key]);
+            }
+        }
+        request.get(function(err, data) {
+            data = err ? [] : data;
+            if (data && !_instanceof(data, Array) && data.data && data.headers) data = fold(data);
+            data = validateData(err, parser, data);
+            loaded[getPathIndex(url, path)] = data;
+            if (loadedLength(loaded) - alreadyLoaded === toLoad.length) {
+                // Format data
+                data = loadedLength(loaded) === 1 ? loaded[0] : loaded;
+                if (_this._cache) _this._lrucache.set("".concat(key, "_").concat(url), data);
+                if (formatter) {
+                    var formatterResponse = formatter(loadedLength(loaded) === 1 ? loaded[0] : loaded);
+                    if (key === "data" && isObject(formatterResponse)) {
+                        data = formatterResponse.data || [];
+                        delete formatterResponse.data;
+                        _this.config(formatterResponse);
+                    } else data = formatterResponse || [];
+                } else if (key === "data") {
+                    data = concat(loaded, "data");
+                }
+                if (key && "_".concat(key) in _this) _this["_".concat(key)] = data;
+                if (callback) callback(err, data);
+            }
+        });
+    });
+    // If there is no data to Load response is immediately
+    if (toLoad.length === 0) {
+        loaded = loaded.map(function(data) {
+            if (data && !_instanceof(data, Array) && data.data && data.headers) data = fold(data);
+            return data;
+        });
+        // Format data
+        var data = loadedLength(loaded) === 1 ? loaded[0] : loaded;
+        if (formatter) {
+            var formatterResponse = formatter(loadedLength(loaded) === 1 ? loaded[0] : loaded);
+            if (key === "data" && isObject(formatterResponse)) {
+                data = formatterResponse.data || [];
+                delete formatterResponse.data;
+                this.config(formatterResponse);
+            } else data = formatterResponse || [];
+        } else if (key === "data") {
+            data = concat(loaded, "data");
+        }
+        if (key && "_".concat(key) in this) this["_".concat(key)] = data;
+        if (callback) callback(null, data);
+    }
+}

package/es/src/merge.js

@@ -0,0 +1,71 @@
+function _instanceof(left, right) {
+    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+        return !!right[Symbol.hasInstance](left);
+    } else {
+        return left instanceof right;
+    }
+}
+import { merge, sum } from "d3-array";
+import unique from "./unique.js";
+/**
+    @function merge
+    @desc Combines an Array of Objects together and returns a new Object.
+    @param {Array} objects The Array of objects to be merged together.
+    @param {Object} aggs An object containing specific aggregation methods (functions) for each key type. By default, numbers are summed and strings are returned as an array of unique values.
+    @example <caption>this</caption>
+merge([
+  {id: "foo", group: "A", value: 10, links: [1, 2]},
+  {id: "bar", group: "A", value: 20, links: [1, 3]}
+]);
+    @example <caption>returns this</caption>
+{id: ["bar", "foo"], group: "A", value: 30, links: [1, 2, 3]}
+*/ function objectMerge(objects) {
+    var aggs = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {};
+    var availableKeys = unique(merge(objects.map(function(o) {
+        return Object.keys(o);
+    }))), newObject = {};
+    availableKeys.forEach(function(k) {
+        var value;
+        if (aggs[k]) value = aggs[k](objects, function(o) {
+            return o[k];
+        });
+        else {
+            var values = objects.map(function(o) {
+                return o[k];
+            });
+            var types = values.map(function(v) {
+                return v || v === false ? v.constructor : v;
+            }).filter(function(v) {
+                return v !== void 0;
+            });
+            if (!types.length) value = undefined;
+            else if (types.indexOf(Array) >= 0) {
+                value = merge(values.map(function(v) {
+                    return _instanceof(v, Array) ? v : [
+                        v
+                    ];
+                }));
+                value = unique(value);
+                if (value.length === 1) value = value[0];
+            } else if (types.indexOf(String) >= 0) {
+                value = unique(values);
+                if (value.length === 1) value = value[0];
+            } else if (types.indexOf(Number) >= 0) value = sum(values);
+            else if (types.indexOf(Object) >= 0) {
+                value = unique(values.filter(function(v) {
+                    return v;
+                }));
+                if (value.length === 1) value = value[0];
+                else value = objectMerge(value);
+            } else {
+                value = unique(values.filter(function(v) {
+                    return v !== void 0;
+                }));
+                if (value.length === 1) value = value[0];
+            }
+        }
+        newObject[k] = value;
+    });
+    return newObject;
+}
+export default objectMerge;

package/es/src/nest.js

@@ -0,0 +1,36 @@
+function _instanceof(left, right) {
+    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+        return !!right[Symbol.hasInstance](left);
+    } else {
+        return left instanceof right;
+    }
+}
+import { nest } from "d3-collection";
+/**
+    @function nest
+    @summary Extends the base behavior of d3.nest to allow for multiple depth levels.
+    @param {Array} *data* The data array to be nested.
+    @param {Array} *keys* An array of key accessors that signify each nest level.
+    @private
+*/ export default function(data, keys) {
+    if (!_instanceof(keys, Array)) keys = [
+        keys
+    ];
+    var dataNest = nest();
+    for(var i = 0; i < keys.length; i++)dataNest.key(keys[i]);
+    var nestedData = dataNest.entries(data);
+    return bubble(nestedData);
+}
+/**
+    Bubbles up values that do not nest to the furthest key.
+    @param {Array} *values* The "values" of a nest object.
+    @private
+*/ function bubble(values) {
+    return values.map(function(d) {
+        if (d.key && d.values) {
+            if (d.values[0].key === "undefined") return d.values[0].values[0];
+            else d.values = bubble(d.values);
+        }
+        return d;
+    });
+}

package/es/src/unique.js

@@ -0,0 +1,28 @@
+/**
+    @function unique
+    @desc ES5 implementation to reduce an Array of values to unique instances.
+    @param {Array} arr The Array of objects to be filtered.
+    @param {Function} [accessor] An optional accessor function used to extract data points from an Array of Objects.
+    @example <caption>this</caption>
+unique(["apple", "banana", "apple"]);
+    @example <caption>returns this</caption>
+["apple", "banana"]
+*/ function _instanceof(left, right) {
+    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+        return !!right[Symbol.hasInstance](left);
+    } else {
+        return left instanceof right;
+    }
+}
+export default function(arr) {
+    var accessor = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : function(d) {
+        return d;
+    };
+    var values = arr.map(accessor).map(function(d) {
+        return _instanceof(d, Date) ? +d : d;
+    });
+    return arr.filter(function(obj, i) {
+        var d = accessor(obj);
+        return values.indexOf(_instanceof(d, Date) ? +d : d) === i;
+    });
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@d3plus/data",
+  "version": "3.0.0-alpha.0",
+  "description": "JavaScript data loading, manipulation, and analysis functions.",
+  "license": "MIT",
+  "type": "module",
+  "exports": "./es/index.js",
+  "browser": "./umd/d3plus-data.full.js",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "files": [
+    "umd",
+    "es"
+  ],
+  "homepage": "https://d3plus.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/d3plus/d3plus.git",
+    "directory": "packages/data"
+  },
+  "keywords": [
+    "data",
+    "d3",
+    "d3plus",
+    "data",
+    "visualization"
+  ],
+  "scripts": {
+    "build:esm": "node ../../scripts/build-esm.js",
+    "build:umd": "node ../../scripts/build-umd.js",
+    "dev": "node ../../scripts/dev.js",
+    "test": "eslint index.js src/**/*.js && eslint --global=it test && mocha 'test/**/*-test.js'"
+  },
+  "dependencies": {
+    "@d3plus/dom": "3.0.0-alpha.0",
+    "d3-array": "^3.2.4",
+    "d3-collection": "^1.0.7",
+    "d3-request": "^1.0.6"
+  }
+}