marcello3d / falcor-shapes

object-based falcor pathset generator

falcor-shapes

falcor-shapes is a convenience function for generating Falcor PathSets.

It converts a "Shape" into an array of Falcor PathSets.

For example:

{
 name: {
    first: true,
    last: true
  },
  location: {
    city: true,
    region: true,
    country: true
  }
}

becomes

[
  [ 'name', 'first' ],
  [ 'name', 'last' ],
  [ 'location', 'city' ],
  [ 'location', 'region' ],
  [ 'location', 'country' ]
]

Install

npm install falcor-shapes

Background

I built this function while playing around with falcor for the first time a few days ago. I found it easier to think of data in terms of a hierarchical structure rather than a list of string paths.

It also allows you to split up the list of what fields you need across multiple files (similar to GraphQL/Relay in React).

What is a "Shape"?

A shape is a recursive structure that resembles the JavaScript structure you're expecting. Shapes are simply JavaScript objects with keys and values. If a value is a nested JavaScript object, it will be expanded into multiple PathSets.

• { <key>: true } is a leaf value, and becomes the path [ '<key>' ]
• { <key>: <Shape> } recurses
• $ is a special key that expects an array: { $: [ <range>, <Shape> ] } and becomes [ <range>, <Shape> ]

Example:

{
  people: {
    length: true,
    $: [
      {from: 0, to: 100},
      {
        name: {
          first: true,
          last: true
        },
        age: true
      }
    ]
  }
}

becomes:

[ 'people', 'length' ],
[ 'people', { from: 0, to: 100 }, 'name', 'first' ],
[ 'people', { from: 0, to: 100 }, 'name', 'last' ],
[ 'people', { from: 0, to: 100 }, 'age' ]

See more examples in test/test.js.

Usage

var shapeToSet = require('falcor-shapes')

var sets = shapeToSet({
  people: {
    length: true,
    $: [
      {from: 0, to: 100},
      {
        name: {
          first: true,
          last: true
        },
        age: true
      }
    ]
  }
})

// falcor's model.get expects each path as separate arguments, so we need to call 'apply'
model.get.apply(model, sets).then( ... )

We can make a helper function to simplify this:

function getWithShape(shape) {
  return model.get.apply(model, shape)
}

getWithShape({
  people: {
    length: true,
    $: [
      {from: 0, to: 100},
      {
        name: {
          first: true,
          last: true
        },
        age: true
      }
    ]
  }
}).then( ... )

Development and Test

# Clone the repo
git clone [email protected]:marcello3d/falcor-shapes.git

# Install dependencies
npm install

# Run tests
npm test

Contributing

Feel free to submit pull requests!

License

zlib

falcor-shapes's Issues

Support for `false` as a value, or falsy values to be ignored

It would be nice to have a shape like

{
    alpha: true,
    bravo: false
}

Where it would boil down to

{
    alpha: true
}

In practice, this would be used as such:

{
    name: true,
    desc: showingDescription(user)
}

Feature Request: Dynamic Shapes

Love the tool! One thing missing which I'd really like to see is dynamic shapes.

For example, taking the example in the README:

{
  people: {
    length: true,
    $: [
      {from: 0, to: 100},
      {
        name: {
          first: true,
          last: true
        },
        age: true
      }
    ]
  }
}

Could become:

var page = 1,
    perPage = 10,
    showFullName = true;

{
  people: {
    length: true,
    $: [
      _ => {
        return {
          from: (page - 1) * perPage,
          to: page * perPage - 1
        }
      },
      {
        name: _ => {
          var result = {
            first: true
          }
          if (showFullName) {
            result.last = true;
          }
          return result;
        },
        age: true
      }
    ]
  }
}

I imagine it being used in a component based system where the user can interact with the page and change the shape of the data displayed.