Documentation for Projections

[curran]

As projections are still a feature in ShareDB, perhaps they should be documented?

In docs/upgrading-from-sharejs.md, I see "addProjection() no longer takes an OT type in the third argument".

I found the content below in a commented out part of the README indicating that it is old documentation that came from ShareJS. Perhaps this could be used as a starting point for adding new documentation for projections?

Projections

ShareDB supports exposing a projection of a real collection, with a specified
(limited) set of allowed fields. Once configured, the projected collection
looks just like a real collection - except documents only have the fields
you've requested.

Operations (gets, queries, sets, etc) on the fake collection work, but you only
see a small portion of the data. You can use this to drop server & db load
dramatically and speed up page times. Its similar to SQL VIEWs. For now, this
only works on JSON documents. (I don't know what it would look like for text
documents).

For example, you could make a users_limited projection which lets users view
each other's names and profile pictures, but not password hashes. You would
configure this by calling:

sharedb.addProjection('users_limited', 'users', 'json0', {name:true, profileUrl:true});

However, be aware that on its own this is not sufficient for access control. If
users are still allowed to make arbitrary mongo queries against the projected
collection, they can find out any data in the hidden fields.

Configure a projection by calling addProjection(projCName, realCName, type, fields).

• projCName: The projected collection name. (Eg, users_limited)
• realCName: The underlying collection name
• type: The OT type. Only JSON0 is supported for now.
• fields: A map of the allowed fields in documents. The keys in this map
  represent the field names, and the values should be true.

Limitations:

• You can only whitelist fields (not blacklist them).
• Projections can only limit / allow fields at the top level of the document

[curran]

Here's a rough draft of an edited version of the above copy, including the migration modification.

Projections

ShareDB supports exposing a projection of a real collection, with a specified (limited) set of allowed fields. Once configured, the projected collection looks just like a real collection - except documents only have the fields you've requested. Operations (gets, queries, sets, etc) on the fake collection work, but you only see a small portion of the data.

Configure a projection by calling addProjection(projectedCollectionName, realCollectionName, fields) where fields is A map of the allowed fields in documents. The keys in this map represent the field names, and the values should be true.

For example, you could make a users_limited projection which lets users view each other's names and profile pictures, but not password hashes. You would configure this by calling:

sharedb.addProjection('users_limited', 'users', 'json0', {name:true, profileUrl:true});

Note that only the JSON0 OT type is supported for projections.

[minicuper]

If projections will be in 1.0 than it maybe makes sense to reopen #59?

[curran]

@nateps Are projections slated for inclusion in 1.0?

[hdavidzhu]

I had to hunt down projections documentation in the commented-out section of the README.md

https://raw.githubusercontent.com/share/sharedb/4991b58f7a168d3ad61ed15c0e247fb51bf9d253/README.md

I think this documentation would be important for future developers. Thanks!