component / enumerable

Enumerable mixin

Enumerable

Enumerable mixin.

users
  .map('friends')
  .select('age > 20')
  .map('name.first')
  .select(/^T/)

Installation

$ component install component/enumerable

Implementation

Nearly all methods utilize the to-function component, which converts the argument passed to a function. For example .map('name.first') expands to a function effectively defined as return obj.name.first, likewise .select(/^Tobi/) expands to return /^Tobi/.test(str) and so on. For details check out to-function's Readme and familiarize yourself since all of that is applicable to Enumerable.

API

• mixin()
• .each()
• .map()
• .select()
• .unique()
• .reject()
• .compact()
• .find()
• .findLast()
• .none()
• .any()
• .count()
• .indexOf()
• .has()
• .reduce()
• .max()
• .sum()
• .first()
• .last()
• .inGroupsOf()
• .at()
• .value()

mixin()

Mixin to obj.

 var Enumerable = require('enumerable');
 Enumerable(Something.prototype);

.each(fn:Function)

Iterate each value and invoke fn(val, i).

 users.each(function(val, i){

 })

.map(fn:Function)

Map each return value from fn(val, i).

Passing a callback function:

 users.map(function(user){
   return user.name.first
 })

Passing a property string:

 users.map('name.first')

.select(fn:Function|String)

Select all values that return a truthy value of fn(val, i).

 users.select(function(user){
   return user.age > 20
 })

With a property:

 items.select('complete')

.unique()

Select all unique values.

 nums.unique()

.reject(fn:Function|String|Mixed)

Reject all values that return a truthy value of fn(val, i).

Rejecting using a callback:

 users.reject(function(user){
   return user.age < 20
 })

Rejecting with a property:

 items.reject('complete')

Rejecting values via ==:

 data.reject(null)
 users.reject(toni)

.compact()

Reject null and undefined.

 [1, null, 5, undefined].compact()
 // => [1,5]

.find(fn:Function)

Return the first value when fn(val, i) is truthy, otherwise return undefined.

 users.find(function(user){
   return user.role == 'admin'
 })

.findLast(fn:Function)

Return the last value when fn(val, i) is truthy, otherwise return undefined.

 users.findLast(function(user){
   return user.role == 'admin'
 })

.none(fn:Function|String)

Assert that none of the invocations of fn(val, i) are truthy.

For example ensuring that no pets are admins:

 pets.none(function(p){ return p.admin })
 pets.none('admin')

.any(fn:Function)

Assert that at least one invocation of fn(val, i) is truthy.

For example checking to see if any pets are ferrets:

 pets.any(function(pet){
   return pet.species == 'ferret'
 })

.count(fn:Function)

Count the number of times fn(val, i) returns true.

 var n = pets.count(function(pet){
   return pet.species == 'ferret'
 })

.indexOf(obj:Mixed)

Determine the indexof obj or return -1.

.has(obj:Mixed)

Check if obj is present in this enumerable.

.reduce(fn:Function, [val]:Mixed)

Reduce with fn(accumulator, val, i) using optional init value defaulting to the first enumerable value.

.max(fn:Function|String)

Determine the max value.

With a callback function:

 pets.max(function(pet){
   return pet.age
 })

With property strings:

 pets.max('age')

With immediate values:

 nums.max()

.sum(fn:Function|String)

Determine the sum.

With a callback function:

 pets.sum(function(pet){
   return pet.age
 })

With property strings:

 pets.sum('age')

With immediate values:

 nums.sum()

.first([n]:Number|Function)

Return the first value, or first n values.

.last([n]:Number|Function)

Return the last value, or last n values.

.inGroupsOf(n:Number)

Return values in groups of n.

.at(i:Number)

Return the value at the given index.

.value()

Return the enumerable value.

License

MIT

enumerable's Issues

mixing directly into an array?

It'd be really sweet to be able to do something like this:

var users = [];
enumerable(users);

var matt = {
  name : 'matt',
  age : 23
};

var jim = {
  name : 'jim',
  age : 42
};

users.push(matt, jim);

var names = users.map('name') // [ 'matt', 'jim' ]

mean median mode

getter-style methods should be invoked

for example users.max('age') where user.age() -> Number

sorting

.minmax()

Rename 'select' to 'filter' to match native method

Why not use the same name for filtering as the native ecmascript 5 method?

Another reason is that it's particularly confusing for .net developers since in .net the map method is called select.

http://msdn.microsoft.com/en-us/library/system.linq.enumerable.select.aspx

If you'd like to keep this rubyism, maybe it would be worth doing what underscore does and make it an alias for filter?

Idea: Advanced matching ala SugarJS

Sugar.js has this 'advanced matching' for its enumerable methods. You've already started down this path with the String|Function signatures for methods like find and reject, but this takes it a step further, introducing Regex and Object matching (among others).

I've adapted the example from the Sugar site for component/enumerable so you can get an idea of how it could work:

var people = Enumerable([
  { name: 'john', age: 21 },
  { name: 'jane', age: 54 },
  { name: 'bill', age: 16 },
  { name: 'john', age: 88 },
  { name: 'will', age: 8 }
]);

people.select({ name: 'john', age: 21 })
> [{"name":"john","age":21}]

people.select({ age: 21 })
> [{"name":"john","age":21}]

people.select({ name: 'john' })
> [{"name":"john","age":21},{"name":"john","age":88}]

people.select({ name: /ill$/ })
> [{"name":"bill","age":16},{"name":"will","age":8}]

people.select({
  age: function(age) {
    return age < 20;
  }
}) 
> [{"name":"bill","age":16},{"name":"will","age":8}]


Enumerable([1, 2, 3]).find(3)
> 3
Enumerable([55, 100, 55, 72]).count(55)
> 2
Enumerable([55, 100, 55, 72]).count(function(n) {
  return n > 80;
}) 
> 1

Enumerable(['a', 'b', 'c']).reject('b') 
> ["a","c"]

Enumerable(['a', 'b', 'c']).none('d') 
> true

Enumerable(['big', 'pig', 'bag']).count(/g$/)
> 3
Enumerable(['big', 'pig', 'bag']).count(/ig$/)
> 2

Enumerable([ [1,2], [2,3] ]).any([2,3])
> true

Enumerable([ [1,2], [2,3] ]).all([2,3])
> false

Had a quick look through the sugar code and doesn't look like this can be easily lifted straight from sugar, but also doesn't look like it would be too hard to implement as a separate 'matcher' component.

fix docs

dox --api needs to default to ignoring implicit titles, and wrap with github's code things for highlighting

search object

Is there room in enumerable for some kind of deep object select/search? For example...

var nick = { 
  name: 'nick', 
  other: {car: 'audi'},
  colours: ['red', 'blue', 'green']
};

Enumerable([nick])
  .search(/nick/)
  .search(/audi/)
  .search(/red/)
  .search('colours', /green/)
  .at(0)
  //= Object {name: "nick", other: Object, colours: Array[3]}

group by

Preserve collection type when filtering?

Would it be a bad idea to ensure that in the following example, given that collection is an instance of an Enumerable subtype, filteredCollection is of the same type instead of being a vanilla Enumerable?

var filteredCollection = collection.select(predicate)

Or another way to put it: Would it be reasonable to change https://github.com/component/enumerable/blob/master/index.js#L163
into new this.constructor(arr)?

async

I wonder if async support could be added using function.length check ala mocha.

Should this be broken down into smaller components?

I'm new to components and I was browsing through some libraries and fell on this one. I had the impression that stuff like map and any should reside in its own component. What's the convention here? I guess this is more of a component question in general, but I thought it'd be applicable here.

Thanks.

match generators

.next() and no index etc.. no random access