Home

Awesome

Enhanced Methods

This fork makes ValidatedMethod compatible with enhanced Methods provided by the pub-sub-lite package.

Enhanced Methods can be used by passing { enhanced: true }, { cacheMethodResult: true }, or { cacheMethodResultInMinimongo: true } to the applyOptions of ValidatedMethod.

The enhanced option

const method = new ValidatedMethod({
  name, 
  applyOptions: { enhanced: true }, 
  run 
});

This is equivalent to defining the Method with Meteor.methodsEnhanced and then call it with Meteor.applyEnhanced.

The cacheMethodResult option

const method = new ValidatedMethod({
  name, 
  applyOptions: { cacheMethodResult: true }, 
  run 
});

This is equivalent to defining the Method with Meteor.methodsEnhanced, calling it with Meteor.applyEnhanced, and then calling PubSubLite.cacheMethodResult on the result data. This option should be used for Methods whose result data is non-document. The data will be cached but will not be merged into Minimongo.

The cacheMethodResultInMinimongo option

const method = new ValidatedMethod({
  name, 
  applyOptions: { 
    cacheMethodResultInMinimongo: true,
    // When result data is a document or an array of documents, a collection name
    // must be provided for Minimongo merging
    collectionName: 'collectionA',  
  }, 
  run 
});

This is equivalent to defining the Method with Meteor.methodsEnhanced, calling it with Meteor.applyEnhanced, and then calling PubSubLite.cacheMethodResultInMinimongo on the result data. Result data will be cached and merged with Minimongo.

Result data can be either a document, an array of documents, or a dictionary of collection names and their documents. When data is a document or an array of documents, a collectionName key must also be defined in applyOptions.

Comparison

The cacheDurationMs option:

Caching duration can be set individually for each Method:

const method = new ValidatedMethod({
  name, 
  applyOptions: { 
    cacheMethodResult: true,
    cacheDurationMs: 60000, // Cache duration in millisecond, or 0 to disable caching
  }, 
  run 
});

For more information, see the pub-sub-lite package.

Original Documentation

Define Meteor methods in a structured way, with mixins

// Method definition
const method = new ValidatedMethod({
  name, // DDP method name
  mixins, // Method extensions
  validate, // argument validation
  applyOptions, // options passed to Meteor.apply
  run // Method body
});

// Method call
method.call({ arg1, arg2 });

This is a simple wrapper package for Meteor.methods. The need for such a package came when the Meteor Guide was being written and we realized there was a lot of best-practices boilerplate around methods that could be easily abstracted away.

Note: the code samples in this README use the Meteor 1.3 import/export syntax, but this package works great in Meteor 1.2 as well. In that case, we recommend attaching your ValidatedMethod objects to the relevant collection, like Lists.methods.insert = new ValidatedMethod(...).

Benefits of ValidatedMethod

  1. Have an object that represents your method. Refer to it through JavaScript scope rather than by a magic string name.
  2. Built-in validation of arguments through aldeed:simple-schema, or roll your own argument validation.
  3. Easily call your method from tests or server-side code, passing in any user ID you want. No need for two-tiered methods anymore!
  4. Throw errors from the client-side method simulation to prevent execution of the server-side method - this means you can do complex client-side validation in the body on the client, and not waste server-side resources.
  5. Get the return value of the stub by default, to take advantage of consistent ID generation. This way you can implement a custom insert method with optimistic UI.
  6. Install Method extensions via mixins.

See extensive code samples in the Todos example app.

Defining a method

Using SimpleSchema

Let's examine a method from the new Todos example app which makes a list private and takes the listId as an argument. The method also does permissions checks based on the currently logged-in user. Note this code uses new ES2015 JavaScript syntax features.

// Export your method from this module
export const makePrivate = new ValidatedMethod({
  // The name of the method, sent over the wire. Same as the key provided
  // when calling Meteor.methods
  name: 'Lists.methods.makePrivate',

  // Validation function for the arguments. Only keyword arguments are accepted,
  // so the arguments are an object rather than an array. The SimpleSchema validator
  // throws a ValidationError from the mdg:validation-error package if the args don't
  // match the schema
  validate: new SimpleSchema({
    listId: { type: String }
  }).validator(),

  // This is optional, but you can use this to pass options into Meteor.apply every
  // time this method is called.  This can be used, for instance, to ask meteor not
  // to retry this method if it fails.
  applyOptions: {
    noRetry: true,
  },

  // This is the body of the method. Use ES2015 object destructuring to get
  // the keyword arguments
  run({ listId }) {
    // `this` is the same method invocation object you normally get inside
    // Meteor.methods
    if (!this.userId) {
      // Throw errors with a specific error code
      throw new Meteor.Error('Lists.methods.makePrivate.notLoggedIn',
        'Must be logged in to make private lists.');
    }

    const list = Lists.findOne(listId);

    if (list.isLastPublicList()) {
      throw new Meteor.Error('Lists.methods.makePrivate.lastPublicList',
        'Cannot make the last public list private.');
    }

    Lists.update(listId, {
      $set: { userId: this.userId }
    });

    Lists.userIdDenormalizer.set(listId, this.userId);
  }
});

The validator function called in the example requires SimpleSchema version 1.4+.

Be aware that by default the validator function does not clean the method parameters before checking them. This behavior differs from that of aldeed:collection2, which always cleans the input data before inserts, updates, or upserts.

If you want the validator to clean its inputs before checking, make sure to pass the { clean: true } option to the validator function:

  validate: new SimpleSchema({
    listId: { type: String }
  }).validator({ clean: true }),

Using your own argument validation function

If aldeed:simple-schema doesn't work for your validation needs, just define a custom validate method that throws a ValidationError instead:

const method = new ValidatedMethod({
  name: 'methodName',

  validate({ myArgument }) {
    const errors = [];

    if (myArgument % 2 !== 0) {
      errors.push({
        name: 'myArgument',
        type: 'not-even',
        details: {
          value: myArgument
        }
      });
    }

    if (errors.length) {
      throw new ValidationError(errors);
    }
  },

  // ...
});

Using check to validate arguments

You can use check in your validate function if you don't want to pass ValidationError objects to the client, like so:

const method = new ValidatedMethod({
  name: 'methodName',

  validate(args) {
    check(args, {
      myArgument: String
    });
  },

  // ...
});

Skipping argument validation

If your method does not need argument validation, perhaps because it does not take any arguments, you can use validate: null to skip argument validation.

Defining a method on a non-default connection

You can define a method on a non-default DDP connection by passing an extra connection option to the constructor.

Options to Meteor.apply

The validated method, when called, executes itself via Meteor.apply. The apply method also takes a few options which can be used to alter the way Meteor handles the method. If you want to use those options you can supply them to the validated method when it is created, using the applyOptions member. Pass it an object that will be used with Meteor.apply.

By default, ValidatedMethod uses the following options:

{
  // Make it possible to get the ID of an inserted item
  returnStubValue: true,

  // Don't call the server method if the client stub throws an error, so that we don't end
  // up doing validations twice
  throwStubExceptions: true,
};

Other options you might be interested in passing are:

Secret server code

If you want to keep some of your method code secret on the server, check out Served Files from the Meteor Guide.

Using a ValidatedMethod

method#call(args: Object)

Call a method like so:

import {
  makePrivate,
} from '/imports/api/lists/methods';

makePrivate.call({
  listId: list._id
}, (err, res) => {
  if (err) {
    handleError(err.error);
  }

  doSomethingWithResult(res);
});

The return value of the server-side method is available as the second argument of the method callback.

method#_execute(context: Object, args: Object)

Call this from your test code to simulate calling a method on behalf of a particular user:

it('only makes the list public if you made it private', () => {
  // Set up method arguments and context
  const context = { userId };
  const args = { listId };

  makePrivate._execute(context, args);

  const otherUserContext = { userId: Random.id() };

  assert.throws(() => {
    makePublic._execute(otherUserContext, args);
  }, Meteor.Error, /Lists.methods.makePublic.accessDenied/);

  // Make sure things are still private
  assertListAndTodoArePrivate();
});

Mixins

Every ValidatedMethod can optionally take an array of mixins. A mixin is simply a function that takes the options argument from the constructor, and returns a new object of options. For example, a mixin that enables a schema property and fills in validate for you would look like this:

function schemaMixin(methodOptions) {
  methodOptions.validate = methodOptions.schema.validator();
  return methodOptions;
}

Then, you could use it like this:

const methodWithSchemaMixin = new ValidatedMethod({
  name: 'methodWithSchemaMixin',
  mixins: [schemaMixin],
  schema: new SimpleSchema({
    int: { type: Number },
    string: { type: String },
  }),
  run() {
    return 'result';
  }
});

Community mixins

If you write a helpful ValidatedMethod mixin, please file an issue or PR so that it can be listed here!

Ideas

Discussion and in-depth info

Validation and throwStubExceptions

By default, using Meteor.call to call a Meteor method invokes the client-side simulation and the server-side implementation. If the simulation fails or throws an error, the server-side implementation happens anyway. However, we believe that it is likely that an error in the simulation is a good indicator that an error will happen on the server as well. For example, if there is a validation error in the arguments, or the user doesn't have adequate permissions to call that method, it's often easy to identify that ahead of time on the client.

If you already know the method will fail, why call it on the server at all? That's why this package turns on a hidden option to Meteor.apply called throwStubExceptions.

With this option enabled, an error thrown by the client simulation will stop the server-side method from being called at all.

Watch out - while this behavior is good for conserving server resources in the case where you know the call will fail, you need to make sure the simulation doesn't throw errors in the case where the server call would have succeeded. This means that if you have some permission logic that relies on data only available on the server, you should wrap it in an if (!this.isSimulation) { ... } statement.

ID generation and returnStubValue

One big benefit of the built-in client-side Collection#insert call is that you can get the ID of the newly inserted document on the client right away. This is sometimes listed as a benefit of using allow/deny over custom defined methods. Not anymore!

For a while now, Meteor has had a hard-to-find option to Meteor.apply called returnStubValue. This lets you return a value from a client-side simulation, and use that value immediately on the client. Also, Meteor goes to great lengths to make sure that ID generation on the client and server is consistent. Now, it's easy to take advantage of this feature since this package enables returnStubValue by default.

Here's an example of how you could implement a custom insert method, taken from the Todos example app we are working on for the Meteor Guide:

const insert = new ValidatedMethod({
  name: 'Lists.methods.insert',
  validate: new SimpleSchema({}).validator(),
  run() {
    return Lists.insert({});
  }
});

You can get the ID generated by insert by reading the return value of call:

import {
  insert,
} from '/imports/api/lists/methods';

// The return value of the stub is an ID generated on the client
const listId = insert.call((err) => {
  if (err) {
    // At this point, we have already redirected to the new list page, but
    // for some reason the list didn't get created. This should almost never
    // happen, but it's good to handle it anyway.
    FlowRouter.go('home');
    alert('Could not create list.');
  }
});

FlowRouter.go('listsShow', { _id: listId });

Running tests

meteor test-packages --driver-package practicalmeteor:mocha ./