DavidTPate / bloc

Functional Reactive array filtering and aggregation with a MongoDB inspired syntax.

Bloc

Functional Reactive array filtering and aggregation with a MongoDB inspired syntax.

• Usage
• Query Selectors
  • Comparison Operators
    • $eq
    • $ne
    • $gt
    • $gte
    • $lt
    • $lte
    • $in
    • $nin
  • Evaluation Operators
    • $mod
    • $regex
    • $where
  • Logical Operators
    • $or
    • $and
    • $not
    • $nor
  • Array Operators
    • $all
    • $elemMatch
    • $size

Usage

For normal usage arrays are returned with the results.

var Bloc = require('bloc');
var data = [
  {
    id: 1,
    region: 'us-east-1'
  },
  {
    id: 2,
    region: 'us-west-1'
  }
];
var filter = {
  region: {
    $eq: 'us-east-1'
  }
};

Bloc.filter(data, filter).then(function(results) {
  // Results contains all items in the `us-east-1` region.
}, function(reason) {
 // Something went wrong
});

If desired, a stream can be returned instead.

var Bloc = require('bloc');
var data = [
  {
    id: 1,
    region: 'us-east-1'
  },
  {
    id: 2,
    region: 'us-west-1'
  }
];
var filter = {
  region: {
    $eq: 'us-east-1'
  }
};

Bloc.filter(data, filter, { stream: true }).then(function(stream) {
  stream.subscribe(function(item) {
    // Stream will eventually contain all items in the `us-east-1` region.
  });
}, function(reason) {
 // Something went wrong
});

Query Selectors

Below is a list of all the supported query selectors.

Comparison Operators

Used for the comparison of different values for filters.

$eq

Matches all values that are equal to a specified value.

{
  <field>: { 
    $eq: <value>
  }
}

$ne

Matches all values that are not equal to a specified value.

{
  <field>: { 
    $ne: <value>
  }
}

$gt

Matches values that are greater than a specified value.

{
  <field>: { 
    $gt: <value>
  }
}

$gte

Matches values that are greater than or equal to a specified value.

{
  <field>: { 
    $gte: <value>
  }
}

$lt

Matches values that are less than a specified value.

{
  <field>: { 
    $lt: <value>
  }
}

$lte

Matches values that are less than or equal to a specified value.

{
  <field>: { 
    $lte: <value>
  }
}

$in

Matches any of the values specified in an array.

{
  <field>: { 
    $in: [ <value1>, <value2>, ... <valueN> ]
  }
}

$nin

Matches none of the values specified in an array.

{
  <field>: { 
    $nin: [ <value1>, <value2>, ... <valueN> ]
  }
}

Evaluation Operators

Operators which do some sort of evaluation.

$mod

Performs a modulo operation on the value of a field and selects documents with a specified result.

{
  <field>: {
    $mod: [
      divisor,
      remainder
    ]
  }
}

$regex

Selects documents where values match a specified regular expression.

{
  <field>: {
    $regex: <regular expression>
  }
}

$where

Matches documents that satisfy a JavaScript function.

{
  <field>: {
    $where: <function>
  }
}

Logical Operators

Used for grouping together filter clauses.

$or

Joins query clauses with a logical OR returns all documents that match the conditions of either clause.

{ 
  $or: [
    {
      <expression1>
    },
    {
      <expression2>
    },
    ...,
    {
      <expressionN>
    }
  ]
}

$and

Joins query clauses with a logical AND returns all documents that match the conditions of both clauses.

{ 
  $and: [
    {
      <expression1>
    },
    {
      <expression2>
    },
    ...,
    {
      <expressionN>
    }
  ]
}

$not

Inverts the effect of a query expression and returns documents that do not match the query expression.

{
  <field>: {
    $not: {
      <operator>: <value>
    }
  }
}

$nor

Joins query clauses with a logical NOR returns all documents that fail to match both clauses.

{ 
  $nor: [
    {
      <expression1>
    },
    {
      <expression2>
    },
    ...,
    {
      <expressionN>
    }
  ]
}

Array Operators

Operators to use when filtering arrays.

$all

Matches arrays that contain all elements specified in the query.

{
  <field>: {
    $all: [
      <value1>,
      <value2>,
      ...,
      <valueN>
    ]
  }
}

$elemMatch

Selects documents if element in the array field matches all the specified conditions.

{
  <field>: {
    $elemMatch: {
      <query1>,
      <query2>,
      ...,
      <queryN>
    }
  }
}

$size

Selects documents if the array field is the specified size.

{
  <field>: {
    $size: <number>
  }
}

Aggregation Operators

Operators to use when setting up pipeline stages.

$match

Filters the document stream to allow only matching documents to pass unmodified into the next pipeline stage. $match uses standard queries. For each input document, outputs either one document (a match) or zero documents (no match).

{
  $match: { 
    <query> 
  } 
}

$limit

Passes the first n documents unmodified to the pipeline where n is the specified limit. For each input document, outputs either one document (for the first n documents) or zero documents (after the first n documents).

{
  $limit: <positive integer> 
}

$skip

Skips the first n documents where n is the specified skip number and passes the remaining documents unmodified to the pipeline. For each input document, outputs either zero documents (for the first n documents) or one document (if after the first n documents).

{
  $skip: <positive integer> 
}