🍫 Tastier cookies and local/session storage in 1.7kb. Includes subscribe() events for changes.
Switch branches/tags
Clone or download
Latest commit 1f4803a Nov 14, 2018

readme.md

Brownies npm install brownies gzip size dependencies support playground

Tastier cookies and local/session storage in 1.7kb:

import { cookies, local } from 'brownies';

cookies.token = 42;      // Set it
const t = cookies.token; // Get it
delete cookies.token;    // Eat it

local.token = 42;        // Set it
const t = local.token;   // Get it
delete local.token;      // Del it

Subscribe to changes in any of the objects:

import { session, subscribe } from 'brownies';

subscribe(session, 'token', value => {
  console.log(value);   // 42, 'Hello', null
});

session.token = 42;
session.token = 'Hello';
delete session.token;

You can also iterate them as expected with Object.keys(), Object.values(), etc:

cookies.token = 42;
cookies.name = 'Francisco';

console.log(Object.keys(cookies)); // token, name

for (let val of cookies) {
  console.log(val); // 42, 'Francisco'
}

Getting started

Install it with npm:

npm install brownies

Then import the different parts:

import { cookies, local, ... } from 'brownies';
const { cookies, local, ... } = require('brownies');

Or use a CDN for the browser:

<script src="https://cdn.jsdelivr.net/npm/brownies"></script>
<script>
  // Extract it since we only define `brownies` globally
  const { cookies, local, ... } = brownies;
</script>

If you just want to play, go to the JSFiddle playground.

Cookies

Manipulate cookies with the simple getter/setter interface:

import { cookies } from 'brownies';

cookies.token = 42;          // Set it
const res = cookies.token;   // Get it
delete cookies.token;        // Eat it

Cookies will retain the types that is set. This is possible thanks to the underlying library:

cookies.id = 1;
cookies.accepted = true;
cookies.name = 'Francisco';
cookies.friends = [3, 5];
cookies.user = { id: 1, accepted: true, name: 'Francisco' };
console.log(typeof cookies.id);               // 'number'
console.log(typeof cookies.accepted);         // 'boolean'
console.log(typeof cookies.name);             // 'string'
console.log(Array.isArray(cookies.friends));  // true
console.log(typeof cookies.user);             // 'object'
Warning: Manually setting cookies with document.cookie or server-side [click for details]

Values are encoded first with JSON.stringify() to allow for different types, and then with encodeURIComponent() to remain RFC 6265 compliant. See the details in the underlying library. If you are setting cookies manually, you'll have to follow the same process:

import { cookies } from 'brownies';
document.cookie = `name=${encodeURIComponent(JSON.stringify('Francisco'))}`
console.log(cookies.name);  // Francisco

To delete a item, you have to call delete on it as you would normally do with object properties:

console.log(cookies.id);  // null
cookies.id = 1;
console.log(cookies.id);  // 1
delete cookies.id;
console.log(cookies.id);  // null

Note: the default value for deleted cookies is set to null to be consistent with other local storage technologies.

You can iterate over the cookies in many different standard ways as normal:

Object.keys(cookies);
Object.values(cookies);
Object.entries(cookies);
for (let key in cookies) {}
for (let val of cookies) {}

Options

You can change the cookies options globally:

import { cookies, options } from 'brownies';

// Options with its defaults. Note that expires is set to 100 days
cookies[options] = {
  expires: 100 * 24 * 3600,     // The time to expire in seconds
  domain: false,                // The domain for the cookie
  path: '/',                    // The path for the cookie
  secure: https ? true : false  // Require the use of https
};

cookies.token = 24;  // Will be stored for ~100 days

WARNING: you should import options and then use it as a variable like cookies[options]. You CANNOT do cookies.options nor cookies['options'].

LocalStorage

For localStorage, we define local to simplify the interface:

import { local } from 'brownies';

local.token = 42;          // Set it
const res = local.token;   // Get it
delete local.token;        // Remove it

localStorage items can be set to many different standard values, and they will retain the types:

local.id = 1;
local.accepted = true;
local.name = 'Francisco';
local.friends = [3, 5];
local.user = { id: 1, accepted: true, name: 'Francisco' };
console.log(typeof local.id);               // 'number'
console.log(typeof local.accepted);         // 'boolean'
console.log(typeof local.name);             // 'string'
console.log(Array.isArray(local.friends));  // true
console.log(typeof local.user);             // 'object'
Warning: Manually setting values with localStorage [click for details]

The values are encoded by brownies with JSON.stringify() to maintain the types. If you are want to manually set a value with localStorage.setItem() that you will later read with brownies, you'll have to stringify it first:

localStorage.setItem('name', JSON.stringify('Francisco'));
console.log(local.name);  // Francisco

Same the other way around, if you want to read a value set by brownies with plain Javascript, you'll have to parse it first:

local.name = 'Francisco';
console.log(JSON.parse(localStorage.getItem('name'))); // Francisco

Of course we recommend to stick to the library as much as possible for a cleaner interface:

import { local } from 'brownies';
local.name = 'Francisco';
console.log(local.name);  // Francisco

To delete a item, you have to call delete on it as you would normally do with object properties:

console.log(local.id);  // null
local.id = 1;
console.log(local.id);  // 1
delete local.id;
console.log(local.id);  // null

You can iterate over the items in many different standard ways as normal:

Object.keys(local);
Object.values(local);
Object.entries(local);
for (let key in local) {}
for (let val of local) {}

So if you wanted to delete them all, you can do so by looping them easily:

for (let key in local) {
  console.log('Deleting:', key, local[key]);
  delete local[key];
}

SessionStorage

For the sessionStorage, we define session to simplify the interface:

import { session } from 'brownies';

session.token = 42;          // Set it
const res = session.token;   // Get it
delete session.token;        // Remove it

sessionStorage items can be set to many different standard values, and they will retain the types:

session.id = 1;
session.accepted = true;
session.name = 'Francisco';
session.friends = [3, 5];
session.user = { id: 1, accepted: true, name: 'Francisco' };
console.log(typeof session.id);               // 'number'
console.log(typeof session.accepted);         // 'boolean'
console.log(typeof session.name);             // 'string'
console.log(Array.isArray(session.friends));  // true
console.log(typeof session.user);             // 'object'
Warning: Manually setting values with sessionStorage [click for details]

The values are encoded by brownies with JSON.stringify() to maintain the types. If you are want to manually set a value with sessionStorage.setItem() that you will later read with brownies, you'll have to stringify it first:

sessionStorage.setItem('name', JSON.stringify('Francisco'));
console.log(session.name);  // Francisco

Same the other way around, if you want to read a value set by brownies with plain Javascript, you'll have to parse it first:

session.name = 'Francisco';
console.log(JSON.parse(sessionStorage.getItem('name'))); // Francisco

Of course we recommend to stick to the library as much as possible for a cleaner interface:

import { session } from 'brownies';
session.name = 'Francisco';
console.log(session.name);  // Francisco

To delete a item, you have to call delete on it as you would normally do with object properties:

console.log(session.id);  // null
session.id = 1;
console.log(session.id);  // 1
delete session.id;
console.log(session.id);  // null

You can iterate over the items in many different standard ways as normal:

Object.keys(session);
Object.values(session);
Object.entries(session);
for (let key in session) {}
for (let val of session) {}

So if you wanted to delete them all, you can do so by looping them easily:

for (let key in session) {
  console.log('Deleting:', key, session[key]);
  delete session[key];
}

Subscribe

Subscribe allows you to listen to changes to any object, including yours:

import { local, subscribe } from 'brownies';

subscribe(local, 'token', value => {
  console.log(value);   // 42, null, 'Hello'
});

local.token = 42;
delete local.token;
local.token = 'Hello';

Warning: subscribe() cannot assure that it is synchronous nor that the order is maintained, so the above might not trigger if the end value is the same as the initial value or middle steps might not be shown.

Changes work even if you use the native API to change the values, or even if the changes happen on another tab:

import { local, subscribe } from 'brownies';

subscribe(local, 'token', value => {
  console.log(value);   // 42 (number)
});

// Note that this is the native one:
localStorage.setItem('token', JSON.stringify(42));

To unsubscribe, store the value returned by subscribe() and then use it with unsubscribe():

import { cookies, subscribe, unsubscribe } from 'brownies';

const id = subscribe(cookies, 'token', token => {
  console.log(token);
});

unsubscribe(id);

You can also unsubscribe by the callback, which is very useful in a React context:

import { cookies, subscribe, unsubscribe } from 'brownies';

const cb = token => console.log('NEW TOKEN:', token);
subscribe(cookies, 'token', cb);
unsubscribe(cb);

For instance, if you want to keep the user points synced across tabs with localStorage:

import { local, subscribe, unsubscribe } from 'brownies';

export default class extends React.Component {
  constructor (props) {
    super(props);
    this.state = { points: local.points };
    this.updatePoints = this.updatePoints.bind(this);
    subscribe(local, 'points', this.updatePoints);
  }
  updatePoints (points) {
    this.setState({ points });
  }
  componentWillUnmount () {
    unsubscribe(this.updatePoints);
  }
  render () {
    return <div>Points: {this.state.points}</div>;
  }
}

Trivia

My former coworker made delicious brownies when leaving the company and asked me to name a library brownies. I thought it was a fantastic idea, since brownies are tastier cookies after all 🙂.

Brownies are technically cookies because they are finger food.

This library was previously named clean-store, but I never really liked that name.

The stars in this repository were transferred from the previous repository.