dpankros / meteor-autojoin

A simple join mechanism for Meteor

WARNING: DEPRECATED

I will not be maintaining this package moving forward. If you use it and want to take it over, please let me know. If nobody steps up to take over the project, I reserve the right to delete it after 1 Aug 2017.

AutoJoin

A simple join mechanism for meteor, SimpleSchema and Collection2.

• Installation
• Basic Usage
• Advanced Usage
• Notes

Instalation

In your meteor app directory, enter:

meteor add dpankros:autojoin

Basic Usage

AutoJoin exposes a global AutoJoin object that mainly exposes default preferences that you may never even have to access. To use AutoJoin, define a Simple-Schema for your data and add an autojoin property object to it. For example:

Children = new Mongo.Collection("children");

ChildSchema = new SimpleSchema({
  name: {
    type: String,
    label: "Name",
  }
});

Children.attachSchema(ChildSchema);


Parents = new Mongo.Collection("parents");

ParentSchema = new SimpleSchema({
  name: {
    type: String,
    label: "Name",
  },
  child: {
    type: String,
    label: 'Child',
    autojoin: {
      collection: Children, //references the Children global variable
      id: '_id' //(optional) the id of the target(i.e. Children) collection
    }
  }
});

Parents.attachSchema(ParentSchema);

Then you just fetch your data as you normally would

var allParents = Parents.find({});

And the parents will have their child property replaced with the value of the corresponding child object.

Thus, instead of

//parent
{
 _id:  '00parent_id00',
 name: 'parent',
 child: '00child_id00'
}
//and child
{
 _id: '00child_id00,
 name: 'child',
}

A query for the same parent would return

{
  _id:  '00parent_id00',
  name: 'parent',
  child: {
    _id: '00child_id00,
    name: 'child',
  }
}

Arrays work in the same way, just define an array property in your Simple-Schema.

Advanced Usage

AutoJoin has basic configuration capabilities. These are done be setting properties in the AutoJoin.prefs object. E.g.:

//Don't join unless we tell you to
AutoJoin.prefs.automatic = false;

//Recurse up to four levels deep
AutoJoin.prefs.depth = 4;

Additionally, these options can be set on a case-by-case basis by specifying options to Collection.Find or Collection.FindOne. For example:

//don't perform a join at all, regardless of the default depth
Parents.find({}, {autojoin:{join:false}});

//if we join, only recurse one level deep.  If automatic is false, no join
will be performed regardless of depth
Parents.find({}, {autojoin:{depth:1}};

//force a join to be performed and five levels deep
Parents.find({}, {autojoin:{join:true, depth:5}});

To extend the above example, let's say our datamodel was changed to:

Children = new Mongo.Collection("children");

ChildSchema = new SimpleSchema({
  name: {
    type: String,
    label: "Name",
  },
  parent: {
    type: String,
    label: 'Parent',
    autojoin: {
      collection: Parents
    }
  }
});

Children.attachSchema(ChildSchema);


Parents = new Mongo.Collection("parents");

ParentSchema = new SimpleSchema({
  name: {
    type: String,
    label: "Name",
  },
  child: {
    type: String,
    label: 'Child',
    autojoin: {
      collection: Children
    }
  }
});

Parents.attachSchema(ParentSchema);

In this case, queries to parent with a depth of 1 will return basically the same object as in our basic example, namely:

{
  _id:  '00parent_id00',
  name: 'parent',
  child: {  //<<-- LEVEL 1: expands to the child object
    _id: '00child_id00,
    name: 'child',
    parent: '00parent_id00'
  }
}

If we specified a depth of 2, however, things change:

{
  _id:  '00parent_id00',
  name: 'parent',
  child: {  // <<-- LEVEL 1: Expands the child object
    _id: '00child_id00,
    name: 'child',
    parent: {  //<<-- LEVEL 2: Expands the parent object (again)
      _id:  '00parent_id00',
      name: 'parent',
      child: '00child_id00'
    }
  }
}

Notes

There are a few things to note:

1. The collection property refers to the name of the Mongo.Collection object that is created (e.g. Children = new Mongo.Collection... ) and not the name of the collection stored internally in Mongo (e.g. "children").
2. Internally, the joins are performed using findOne and will continue to recurse through schemas up until the joinDepth is reached. If the joinDepth is 0, no join will be performed. If the joinDepth is 1, one level of joins will be performed, and so on.
3. The id property is optional and will default to _id if not specified. It is included in the basic example for completeness.
4. Specifying a depth of -1 or any negative number will cause infinite expansion, even in the case of infinte loops. I don't recommend it.
5. This was coded in a few hours so many use cases are still omitted, I'm sure.

meteor-autojoin's Issues

problem with findOne()?

problem with findOne()?

Throws error when installed

Just installing this module throws the following error?

ReferenceError: __orig is not defined
W20150317-14:08:42.494(11)? (STDERR)     at Package (packages/dpankros:autojoin/meteor-autojoin.js:40:1)

I'm using the following versions:

• Meteor 1.0.3.2
• aldeed:collection2 2.3.2
• aldeed:simple-schema 1.3.0

Fetch, Map, and forEach not working

Joins are not occurring when these methods are used.

This is a known issue and I am working to correct it. It seems that these functions become unwrapped at runtime (somehow) or I am just not wrapping the correct method.

Add Array Support

Add support for joins with multiple children in an array.