Kitten

Explore Kitten’s built-in session support and how to store data scoped to individual sessions.

Topics covered

We’ve just seen how we can keep a persisted count of kittens.

The count, however, will be the same at any given time for anyone who visits the site.

So, if I visit the site from my computer and see 10 kittens and you visit the site right afterwards from your phone, you’ll see 11 kittens (because my visit raised the count by one).

This is because we’re persisting a single kitten count.

But what if we wanted every person who visits the site to have their own kitten count, as special and unique as they are?

Enter, sessions.

Kitten has built-in session support to make implementing sessions trivial in your sites.

Since the protocol of the web (HTTP) is stateless, each request arrives on its own. But what if we want to keep different information for each person that visits our site, from one request to the next?

Or, more precisely, for each browser that visits our site. (More precisely, you will get two different sessions if your browser has as persisted/regular mode and a temporary/private/incognito mode.)

Clearly, we need a way for our server to know that the request that just came in belongs to the same browser that sent that other request a few minutes ago. While there are different ways to do this, the method that Kitten uses is based on cookies.

Wait a minute… aren’t cookies evil things that Big Tech uses to violate your privacy?

Yes, and no.

You see, there are two types of cookies: first-party and third-party. The latter are what’s used to track you. The former enable sites to implement basic functionality like sessions.

To make it easier to remember, think of first-party cookies as the ones your mom bakes for your birthday and third-party cookies as the ones a wicked witch makes to lure little kids into her hut.

The great thing about having built-in support for sessions is that you don’t have to worry about any of this. Whenever a request comes into one of your routes, you can simply access the session object for it using:

request.session

So what it that object?

It’s simply an object that Kitten keeps in memory for each browser.

Kitten stores the session, and sets its cookie, the first time your route writes to it or reads its id property, when a live page renders, and when you sign in. (Until then, each request has a new session, so a page that never uses its session sets no cookie.)

You can pop your data straight into the session object, but be careful not to overwrite the properties and methods that are Kitten’s: id, createdAt, authenticated, hasExpired(), signIn(), and signOut(). (Sessions are also EventEmitter instances, so avoid the names of its methods too.) Apart from these, you can name your properties anything you want and it’s a good idea to namespace them under your own objects to minimise the risk of name clashes.

Your own data on the session lasts until the server restarts. For data that must last, use your app’s own database (e.g., a database app module), keyed by something you control.

Session objects are EventEmitter instances so you can .emit() and listen for events on them. This is useful, for example, if you have a Streaming HTML handler and you want it to be notified from other routes – like a POST route used to upload files, for example. In fact, this is exactly what Kitten’s own internal Settings app does when you upload a database backup during a database restore.

You can check if the owner of the site is signed in by seeing if the request.session.authenticated property is true or not. And you can manually direct people to sign in and out by redirecting them to the /šŸ’•/sign-in and /šŸ’•/sign-out routes.

So letā€˜s update our original persisted Kitten example to keep a separate count of Kittens for each browser that accesses it:

export default function ({ request }) {
  request.session.kittens ??= { count: 1 }

  return kitten.html`
    <h1>Kitten count</h1>
    <p>${'šŸ±ļø'.repeat(request.session.kittens.count++)}</p>
  `
}

Now run the example using the kitten command and hit it from different browsers. You should see that each has a different count of kittens. (The counts reset when the server restarts, as Kitten keeps session data in memory.)

To see the cookie that Kitten sets, open up the Storage tab of your browser’s developer tools and look under the Cookies section.

Screenshot of Storage → Cookies section of Safari’s Web Inspector, showing the cookie for our example on localhost
You can view and delete any cookies set for a domain in your browser’s developer tools panel.

Delete the cookie and see what happens.

You can find this example in the examples/kitten-count-sessions folder of the Kitten source code. There’s also a more complicated session-based example in examples/trivia that uses the session to store a person’s game state.

Right, now that you know how you can easily work with sessions in Kitten, how about we take a peek at an advanced feature – Database App Modules – a way of working with your app’s own database that lets you store instances of custom classes and take advantage of type safety in your databases.

Next tutorial: Database App Modules

Like this? Fund us!

Small Technology Foundation is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share our vision and want to support our work, please become a patron or donate to us today and help us continue to exist.