{"id":24711179,"url":"https://github.com/borgar/aggro","last_synced_at":"2025-10-09T11:30:37.292Z","repository":{"id":57174476,"uuid":"73286234","full_name":"borgar/aggro","owner":"borgar","description":"Simple object data transformer utility","archived":false,"fork":false,"pushed_at":"2018-07-31T13:32:07.000Z","size":35,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-18T11:47:03.039Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/borgar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-11-09T13:25:14.000Z","updated_at":"2022-05-10T08:40:40.000Z","dependencies_parsed_at":"2022-08-29T00:10:56.597Z","dependency_job_id":null,"html_url":"https://github.com/borgar/aggro","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borgar%2Faggro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borgar%2Faggro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borgar%2Faggro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borgar%2Faggro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/borgar","download_url":"https://codeload.github.com/borgar/aggro/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235813569,"owners_count":19048989,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-27T07:14:05.520Z","updated_at":"2025-10-09T11:30:31.213Z","avatar_url":"https://github.com/borgar.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aggro\n\nAggro is a very basic utility to filter and sort a collection of items for use in reports or visualizations. It is very lightweight and has no external dependencies.\n\nIt is similar to [d3.nest](https://github.com/d3/d3-collection#nests) or [Crossfilter](square.github.com/crossfilter/), but for when you just need something small and simple.\n\nIt provides a few conveniences such as normalised date handling and built-in aggregations but does not have strong dimensional bindings.\n\n\n# Installing\n\n```\n$ npm install aggro\n```\n\nIt works in a browser as well, exposing itself into the global scope as `aggro` if it is included as a standalone library.\n\n\n## API Reference\n\n### Basic interface\n\nInput data is assumed to be a simple array of objects. Output data will be a single-level nested array compatible with the output from a d3.nest operator.\n\nGiven this input data:\n\n```\nconst population = [\n  { \"sex\": \"male\", \"age\": 35, \"eyes\": \"brown\" },\n  { \"sex\": \"female\", \"age\": 38, \"eyes\": \"brown\" },\n  { \"sex\": \"male\", \"age\": 29, \"eyes\": \"brown\" },\n  { \"sex\": \"female\", \"age\": 19, \"eyes\": \"blue\" },\n  { \"sex\": \"male\", \"age\": 31, \"eyes\": \"blue\" },\n  { \"sex\": \"female\", \"age\": 22, \"eyes\": \"brown\" },\n  { \"sex\": \"male\", \"age\": 22, \"eyes\": \"blue\" },\n  { \"sex\": \"female\", \"age\": 33, \"eyes\": \"blue\" }\n];\n```\n\nAnd this operator definition:\n\n```\naggro()\n    .filter('eyes', 'brown')\n    .groupBy('sex')\n    .data(population);\n```\n\nThe output would look like this: \n\n```\n[{ \"key\": \"male\",\n   \"values\": [\n      { \"sex\": \"male\", \"age\": 35, \"eyes\": \"brown\" },\n      { \"sex\": \"male\", \"age\": 29, \"eyes\": \"brown\" }]},\n  { \"key\": \"female\",\n    \"values\": [\n      { \"sex\": \"female\", \"age\": 38, \"eyes\": \"brown\" },\n      { \"sex\": \"female\", \"age\": 22, \"eyes\": \"brown\" }]}]\n```\n\n\n#### aggro()\n\nThe operation constructor. Calling this will return a new blank aggro operator function:\n\n```\nconst processor = aggro();\n```\n\nThe operator function has property methods to define its behavior, most of which return the operator function itself to enable chaining. The operator is a callable function.\n\n```\nconst dataShaper = aggro().filter('age', d =\u003e d \u003e 18).groupBy('eyes');\nconst byEyeColor = dataShaper(population);\n```\n\n\n#### .data()\n\nA function to pass data into the operator function in a slightly more readable way when chaining operations and using directly. This is the reccomended way of passing data.\n\n```\nconst byEyeColor = aggro()\n    .filter('age', d =\u003e d \u003e 18)\n    .groupBy('eyes')\n    .data(population);\n```\n\n\n#### .copy()\n\nThe operator object supports cloning itself through this method. This can be useful if you want to set up multiple operator functions that vary only slightly.\n\n```\nconst basics = aggro().filter(d =\u003e d.age \u003e= 30).groupBy('eyes');\n\nconst males = basics.copy().filter('sex', 'male');\nconst females = basics.copy().filter('sex', 'female');\n```\n\n\n### Filtering data\n\n\n#### .filter( [ propName ], test )\n\nExclude any item who's `propName` value does not pass `test`. Test may be either a function or any value other than undefined.\n\n* If `test` is a function, then value is passed to it and removed if the returned value is falsy.\n\n* If `test` is a value then all values must equal it (`===`). \n\n* If `test` is undefined then nothing will be done.\n\n`propName` may be omitted for simple filter functions which would be similar to prefiltering the input using Array#filter. This would be useful if you intend to reuse or copy the operator.\n\n\n#### .in( propName, array )\n\nPreclude any item who's `propName` value is not given in `array` of values.\n\nIf a single value is passed in, it is automatically wrapped in an array.\n\n\u003e Tip: The simplest shorthand to find items by undefined is `.in('foo', undefined)`\n\n\n#### .between( propName, array )\n\nInclusive range filter.\n\n`array` should contain 2 values, start and end. In case a larger value is provided it's min and max values are determined and used.\n\nThe input may be open ended: Providing `.between( \"foo\", [10, null] )` will remove all items where \"foo\" is less than 10. Similarily, `.between( \"foo\", [null, 10] )` will remove all items where \"foo\" is greater than 10.\n\n\n\n\n### Grouping data\n\n#### .groupBy( propName | propNames )\n\nAggro emits data as a list of groups objects. This happens even when no grouping is specified, in which case the list will only contain a single entry. Every group object will have at least two members, `key` and `values`.\n\n* `key` will be set to the property value found under the property given as `propName`.\n* `values` will be set a list of items which share the same property value for `propName`.\n\n```\naggro().groupBy('sex').data(population);\n\n[{ \"key\": \"male\",\n   \"values\": [\n      { \"sex\": \"male\", ... },\n      { \"sex\": \"male\", ... }]},\n  { \"key\": \"female\",\n    \"values\": [\n      { \"sex\": \"female\", ... },\n      { \"sex\": \"female\", ... }]}]\n```\n\nPropname may be set to `null` to clear it. If an array is passed in, the output will be nested in as many levels as there are keys:\n\n```\naggro().groupBy(['sex', 'eyes']).data(population);\n\n[{ \"key\": \"male\",\n   \"values\": [\n      { \"key\": \"brown\"\n        \"values\": [\n          { \"sex\": \"male\", \"eyes\", \"brown\", ... },\n          { \"sex\": \"male\", \"eyes\", \"brown\", ... }\n        ]},\n      { \"key\": \"blue\"\n        \"values\": [\n          { \"sex\": \"male\", \"eyes\", \"blue\", ... },\n          { \"sex\": \"male\", \"eyes\", \"blue\", ... }\n        ]}]},\n   ...\n   \n```\n\nOrder of the groups will be the same as the order of which the items are found. See *Sorting data* if this is not what you want.\n\n\n\n\n### Aggregating data\n\nAggregate values can be had for any returned group.\n\nAggregates can be computed from the values in any returned group. They will be attached to the grouping object using a general naming scheme of aggregate name + underscore + propName.\n\nGenerally the aggregate functions take 3 parameters:\n\n1. The `propName` to read the value from.\n\n1. A `postProcessor` function to allows formatting or altering (such as rounding) the value before assigning it to the group object. It defaults to using the value as-is.\n\n1. A `keyName` to allow changing the assignment property name of the aggregate value. It generally defaults to the aggregate method name + underscore + `propName`.\n\n\nReusing the general example from *Basic interface*:\n\n```\naggro()\n    .filter('eyes', 'brown')\n    .mean('age')\n    .groupBy('sex')\n    .data(population);\n```\n\nResults in added aggregates for the groups:\n\n```\n[{ \"key\": \"male\",\n   \"values\": [\n     { \"sex\": \"male\", \"age\": 35, \"eyes\": \"brown\" },\n     { \"sex\": \"male\", \"age\": 29, \"eyes\": \"brown\" }]\n   \"mean_age\": 32 },\n { \"key\": \"female\",\n   \"values\": [\n     { \"sex\": \"female\", \"age\": 38, \"eyes\": \"brown\" },\n     { \"sex\": \"female\", \"age\": 22, \"eyes\": \"brown\" }]\n   \"mean_age\": 32 }}]\n```\n\n\n#### .sum( propName, [ postProcessor, [ keyName ] ] )\n\nFinds the sum of all values in the group corresponding to `propName`.\n\nThe `keyName` defaults to the value of `propName` prefixed by `sum_`.\n\n```\naggro()\n    .groupBy('sex')\n    .sum('age')\n    .data(population);\n\n[{ \"key\": \"male\",\n   \"sum_age\": 117,\n   \"values\": [ ... ]},\n { \"key\": \"female\",\n   \"sum_age\": 112,\n   \"values\": [ ... ]}}]\n```\n\n\n#### .mean( propName, [ postProcessor, [ keyName ] ] )\n\nFinds the arithmetic mean, or average, for all values in the group corresponding to `propName`.\n\nThe `keyName` defaults to the value of `propName` prefixed by `mean_`.\n\n```\naggro()\n    .groupBy('sex')\n    .mean('age')\n    .data(population);\n\n[{ \"key\": \"male\",\n   \"mean_age\": 29.25,\n   \"values\": [ ... ]},\n { \"key\": \"female\",\n   \"mean_age\": 28,\n   \"values\": [ ... ]}}]\n```\n\n\n#### .uniq( propName, [ postProcessor, [ keyName ] ] )\n\nFinds an array of all unique values in the group corresponding to `propName`.\n\nThe `keyName` defaults to the value of `propName` prefixed by `uniq_`.\n\n```\naggro()\n    .groupBy('sex')\n    .uniq('age')\n    .data(population);\n\n[{ \"key\": \"male\",\n   \"uniq_age\": [ 35, 29, 31, 22 ],\n   \"values\": [ ... ]},\n { \"key\": \"female\",\n   \"uniq_age\": [ 38, 19, 22, 33 ],\n   \"values\": [ ... ]}}]\n```\n\n\n#### .count( propName, [ postProcessor, [ keyName ] ] )\n\nFinds the number of unique values in the group corresponding to `propName`.\n\nThe `keyName` defaults to the value of `propName` prefixed by `count_`.\n\n```\naggro()\n    .groupBy('sex')\n    .count('age')\n    .data(population);\n\n[{ \"key\": \"male\",\n   \"count_age\": 4,\n   \"values\": [ ... ]},\n { \"key\": \"female\",\n   \"count_age\": 4,\n   \"values\": [ ... ]}}]\n```\n\n\n#### .min( propName, [ postProcessor, [ keyName ] ] )\n\nFinds the lowest of the values in the group corresponding to `propName`.\n\nThe `keyName` defaults to the value of `propName` prefixed by `min_`.\n\n```\naggro()\n    .groupBy('sex')\n    .min('age')\n    .data(population);\n\n[{ \"key\": \"male\",\n   \"min_age\": 22,\n   \"values\": [ ... ]},\n { \"key\": \"female\",\n   \"min_age\": 19,\n   \"values\": [ ... ]}}]\n```\n\n\n#### .max( propName, [ postProcessor, [ keyName ] ] )\n\nFinds the highest of the values in the group corresponding to `propName`.\n\nThe `keyName` defaults to the value of `propName` prefixed by `max_`.\n\n```\naggro()\n    .groupBy('sex')\n    .max('age')\n    .data(population);\n\n[{ \"key\": \"male\",\n   \"max_age\": 35,\n   \"values\": [ ... ]},\n { \"key\": \"female\",\n   \"max_age\": 38,\n   \"values\": [ ... ]}}]\n```\n\n\n#### .range( propName, [ postProcessor, [ keyName ] ] )\n\nFinds the lowest and highest of the values in the group corresponding to `propName`. Result is returned as a two item array,\n\nThe `keyName` defaults to the value of `propName` prefixed by `range_`.\n\n```\naggro()\n    .groupBy('sex')\n    .range('age')\n    .data(population);\n\n[{ \"key\": \"male\",\n   \"range_age\": [22, 35],\n   \"values\": [ ... ]},\n { \"key\": \"female\",\n   \"range_age\": [19, 38],\n   \"values\": [ ... ]}}]\n```\n\n\n#### .one( propName, [ postProcessor, [ keyName ] ] )\n\nPromotes the first value corresponding to `propName` from the values to the group object.\n\nThe `keyName` defaults to the value of `propName`.\n\n```\naggro()\n    .groupBy('sex')\n    .one('sex')\n    .data(population);\n\n[{ \"key\": \"male\",\n   \"sex\": \"male\",\n   \"values\": [ ... ]},\n { \"key\": \"female\",\n   \"sex\": \"female\",\n   \"values\": [ ... ]}}]\n```\n\n\n\n#### .aggregate( propName, aggregator, [ postProcessor, [ keyName ] ] )\n\nAllows defining custom aggregations. This works pretty much the same as the built in aggregation functions except that it takes a function, `aggregator`, to compute the aggregate value. In fact, the built in functions use aggregate to preform their actions.\n\nThe `keyName` defaults to the value of `propName` prefixed by `aggr_`.\n\n\n##### Median aggregate example:\n\n```\nconst median = values =\u003e {\n  const sorted = values.filter(isFinite).sort((a, b) =\u003e a - b);\n  if (sorted.length % 2) {\n    return sorted[ Math.floor(sorted.length / 2) ];\n  }\n  else {\n    return sorted[ sorted.length / 2 - 1 ] / 2 + sorted[ sorted.length / 2 ] / 2;\n  }\n};\n\naggro()\n    .groupBy('sex')\n    .aggregate('age', median, null, 'median_age')\n    .data(population)\n\n[{ \"key\": \"male\",\n   \"mean_age\": 32,\n   \"values\": [ ... ]},\n { \"key\": \"female\",\n   \"mean_age\": 30,\n   \"values\": [ ... ]}}]\n```\n\n\n##### Frequencies aggregate example:\n\n```\nconst freq = values =\u003e {\n  return values.reduce((a, b) =\u003e {\n    a[b] = (b in a) ? a[b] + 1 : 1;\n    return a;\n  }, {});\n};\n\naggro()\n    .groupBy('sex')\n    .aggregate('eyes', freq, null, 'freq_eyes')\n    .data(population)\n\n[{ \"key\": \"male\",\n   \"freq_eyes\": { \"brown\": 2, \"blue\": 2 },\n   \"values\": [ ... ]},\n { \"key\": \"female\",\n   \"freq_eyes\": { \"brown\": 2, \"blue\": 2 },\n   \"values\": [ ... ]}}]\n```\n\n\n### Sorting data\n\nAggro assumes that you don't want your output automatically sorted so all values are returned in the order they are found. If you want the output sorted by value you should perform this on the data before passing it to the operator.\n\n\n#### .sortKeys( [ compareFunction ] )\n\nDespite having the data in order by value, you may still desire to re-order the groups. You could do this with the native `.sort()` on the output, but it may be easier to have Aggro to this for you.\n\nCalling `.sortKeys()` with no parameter or `true` activates default ascending sorting on grouping keys of the output. Calling it with a function uses that function to sort, just like `.sort()` on any regular array would, and calling it with `false` disables sorting.\n\nNote that key values themselves will be passed to the compare function, not the group objects.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fborgar%2Faggro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fborgar%2Faggro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fborgar%2Faggro/lists"}