Session

Documentation of Meteor's client-side session API.

Session provides a global object on the client that you can use to store an arbitrary set of key-value pairs. Use it to store things like the currently selected item in a list.

What's special about Session is that it's reactive. If you call Session.get('currentList') from inside a template, the template will automatically be rerendered whenever Session.set('currentList', x) is called.

To add Session to your application, run this command in your terminal:

meteor add session

Session.set

Client only

Summary:

Set a variable in the session. Notify any listeners that the value has changed (eg: redraw templates, and rerun any Tracker.autorun computations, that called Session.get on this key.)

Arguments:

Source code

Name	Type	Description	Required
key	String	The key to set, eg, selectedItem	Yes
value	EJSONable or undefined	The new value for key	Yes

import { Session } from 'meteor/session';
import { Tracker } from 'meteor/tracker';
import { Meteor } from 'meteor/meteor';

Tracker.autorun(() => {
  Meteor.subscribe('chatHistory', { room: Session.get('currentRoomId') });
});

// Causes the function passed to `Tracker.autorun` to be rerun, so that the
// 'chatHistory' subscription is moved to the room 'home'.
Session.set('currentRoomId', 'home');

Session.set can also be called with an object of keys and values, which is equivalent to calling Session.set individually on each key/value pair.

Session.set({
  a: 'foo',
  b: 'bar'
});

Session.setDefault

Client only

Summary:

Set a variable in the session if it hasn't been set before. Otherwise works exactly the same as Session.set.

Arguments:

Source code

Name	Type	Description	Required
key	String	The key to set, eg, selectedItem	Yes
value	EJSONable or undefined	The new value for key	Yes

import { Session } from "meteor/session";


const result = Session.setDefault();
  "key",
 { num:  42 , someProp:  "foo" },
);

This is useful in initialization code, to avoid re-initializing a session variable every time a new version of your app is loaded.

Session.get

Client only

Summary:

Get the value of a session variable. If inside a reactive computation, invalidate the computation the next time the value of the variable is changed by Session.set. This returns a clone of the session value, so if it's an object or an array, mutating the returned value has no effect on the value stored in the session.

Arguments:

Source code

Name	Type	Description	Required
key	String	The name of the session variable to return	Yes

This example in Blaze.js

main.html

<template name="main">
  <p>We've always been at war with {{theEnemy}}.</p>
</template>

main.js

Template.main.helpers({
  theEnemy() {
    return Session.get('enemy');
  }
});

Session.set('enemy', 'Eastasia');
// Page will say "We've always been at war with Eastasia"

Session.set('enemy', 'Eurasia');
// Page will change to say "We've always been at war with Eurasia"

Session.equals

Client only

Summary:

Test if a session variable is equal to a value. If inside a reactive computation, invalidate the computation the next time the variable changes to or from the value.

Arguments:

Source code

Name	Type	Description	Required
key	String	The name of the session variable to test	Yes
value	String, Number, Boolean, null or undefined	The value to test against	Yes

import { Session } from "meteor/session";


const result = Session.equals();
  "key",
  "value",
);

If value is a scalar, then these two expressions do the same thing:

Session.get('key') === value
Session.equals('key', value)

...but the second one is always better. It triggers fewer invalidations (template redraws), making your program more efficient.

This example in Blaze.js:

main.html

<template name="postsView">
  {{#each posts}}
    {{> postItem}}
  {{/each}}
</template>

<template name="postItem">
  <div class="{{postClass}}">{{title}}</div>
</template>

main.js

Template.postsView.helpers({
  posts() {
    return Posts.find();
  }
});

Template.postItem.helpers({
  postClass() {
    return Session.equals('selectedPost', this._id)
      ? 'selected'
      : '';
  }
});

Template.postItem.events({
  'click'() {
    Session.set('selectedPost', this._id);
  }
});

Using Session.equals here means that when the user clicks on an item and changes the selection, only the newly selected and the newly unselected items are re-rendered.

If Session.get had been used instead of Session.equals, then when the selection changed, all the items would be re-rendered.

For object and array session values, you cannot use Session.equals; instead, you need to use the underscore package and write _.isEqual(Session.get(key), value).