meteor/docs/client/basic/sections/methods.md

{{#template name="basicMethods"}}

Methods

Methods are server functions that can be called from the client. They are useful in situations where you want to do something more complicated than insert, update or remove, or when you need to do data validation that is difficult to achieve with just allow and deny.

Methods can return values and throw errors.

{{> autoApiBox "Meteor.methods"}}

Calling Meteor.methods on the server defines functions that can be called remotely by clients. Here's an example of a method that checks its arguments and throws an error:

// On the server
Meteor.methods({
  commentOnPost: function (comment, postId) {
    // Check argument types
    check(comment, String);
    check(postId, String);

    if (! this.userId) {
      throw new Meteor.Error("not-logged-in",
        "Must be logged in to post a comment.");
    }

    // ... do stuff ...

    return "something";
  },

  otherMethod: function () {
    // ... do other stuff ...
  }
});

The check function is a convenient way to enforce the expected types and structure of method arguments.

Inside your method definition, this is bound to a method invocation object, which has several useful properties, including this.userId, which identifies the currently logged-in user.

Latency Compensation

Calling a method on the server requires a round-trip over the network. It would be really frustrating if users had to wait a whole second to see their comment show up due to this delay. That's why Meteor has a feature called method stubs. If you define a method on the client with the same name as a server method, Meteor will run it to attempt to predict the outcome of the server method. When the code on the server actually finishes, the prediction generated on the client will be replaced with the actual outcome of the server method.

The client versions of insert, update, and remove, which are implemented as methods, use this feature to make client-side interactions with the database appear instant.

{{> autoApiBox "Meteor.Error"}}

If you want to return an error from a method, throw an exception. Methods can throw any kind of exception, but Meteor.Error is the only kind of error that will be sent to the client. If a method function throws a different exception, the client gets Meteor.Error(500, 'Internal server error').

{{> autoApiBox "Meteor.call"}}

This is how you call a method.

On the client

On the client you should pass a callback and the method will run asynchronously: it will return nothing and instead deliver its results to the callback function. The callback will be called with two arguments: error and result.

// Asynchronous call with a callback on the client
Meteor.call('commentOnPost', comment, postId, function (error, result) {
  if (error) {
    // handle error
  } else {
    // all good!
  }
});

Meteor tracks the database writes performed by methods and does not invoke the callback until all of the server's writes have been sent to the client.

On the server

On the server, you don't have to pass a callback - the method invocation will block until the method is complete. It will return the return value of the method or throw an exception, just like if you had called the function directly.

// Synchronous call on the server with no callback
var result = Meteor.call('foo', comment, postId);

{{/template}}