Facetor

• 🔍 Facetor - NPM module to filter a list of objects by its fields. Useful for e-commerce style catalog pages.
• Version 2.x.x has arrived! with some major breaking changes

USAGE

• Facetor has two steps: - Build Index, by specifying array of Items to filter and the Items' filterable fields. - Build Results, from array of field.values to return, and array of attributes returned for each field.

Prep - Load the module

Let's load the module

• On Node.js / CommonJS:
  • in terminal: npm install facetor
  • in node: var Facetor = require('facetor')
• On the browser - html:
  • in html head tag: - BigInteger.js: <script src="//example.com/biginteger.js"></script> - Facetor.js: <script src="//example.com/facetor.js"></script>
• AMD is also supported.

Step 1

Build Index, by specifying array of Items to filter and the Items' filterable fields.

• EX: Here, we want to make the fields "style" and "category" available for filtering later:

var catalogFacetor = new Facetor({ separator: "|" });
catalogFacetor.buildIndex({
  facets: ["style", "category"],
  items: [
    {
      title: "Rural Apple",
      style: "rural",
      category: "apples"
    },
    {
      title: "Urban Apple",
      style: "urban",
      category: "apples"
    },
    {
      title: "Rural Orange",
      style: "rural",
      category: "oranges"
    },
    {
      title: "Urban Orange",
      style: "urban",
      category: "oranges"
    },
    {
      title: "A mega rural urban apple orange hybrid",
      style: ["rural", "urban"],
      category: ["apple", "oranges"]
    }
  ]
});

Step 2

Build Results, from array of field.values, and array of attributes returned for each field.

• Values in the same parent fields use "OR" binary logic, while fields use "AND" logic.
• EX: Here, we want to only get "style.rural" and "category.oranges" items.

var result = catalogFacetor.buildResult({
  facets: ["style|rural", "category|oranges"],
  attributes: ["path", "bitmap", "count", "increment", "status"]
});

• Results in

{
  "data": {
    "style": {
      "rural": {
        "path": "style|rural",
        "bitmap": "20",
        "count": 2,
        "increment": 0,
        "status": true
      },
      "urban": {
        "path": "style|urban",
        "bitmap": "28",
        "count": 3,
        "increment": 1,
        "status": false
      }
    },
    "category": {
      "apples": {
        "path": "category|apples",
        "bitmap": "21",
        "count": 3,
        "increment": 1,
        "status": false
      },
      "oranges": {
        "path": "category|oranges",
        "bitmap": "20",
        "count": 2,
        "increment": 0,
        "status": true
      },
      "apple": {
        "path": "category|apple",
        "bitmap": "20",
        "count": 2,
        "increment": 0,
        "status": false
      }
    }
  },
  "items": [
    {
      "title": "Rural Orange",
      "style": "rural",
      "category": "oranges"
    },
    {
      "title": "A mega rural urban apple orange hybrid",
      "style": ["rural", "urban"],
      "category": ["apple", "oranges"]
    }
  ]
}

Import and Export

Allows building of index ahead of time to save cpu and memory.

• Export current index

var indexJSON = catalogFacetor.exportIndex();

• Import index from json object

var newCatalogFacetor = new Facetor();
newCatalogFacetor.importIndex(indexJSON); // exported from above
var results = newCatalogFacetor.buildResult({
  facets: ["style|rural", "category|oranges"],
  attributes: ["path", "bitmap", "count", "increment", "status"]
});
// same results as step 2