Brownies
Tastier cookies
, local
, session
, and db
storage in a tiny package:
; cookiestoken = 42; // Set itlet t = cookiestoken; // Get itdelete cookiestoken; // Eat it localtoken = 42; // Set itlet t = localtoken; // Get itdelete localtoken; // Del it // db is ASYNC so read is differentdbtoken = 42; // Set itlet t = await dbtoken; // Get itdelete dbtoken; // Del it
Subscribe to changes in any of the objects:
; ; sessiontoken = 42;sessiontoken = 'Hello';delete sessiontoken;
You can also iterate them as expected with Object.keys()
, Object.values()
, etc:
cookiestoken = 42;cookiesname = 'Francisco'; console; // token, name for let val of cookies console; // 42, 'Francisco'
Getting started
Install it with npm:
npm install brownies
Then import the different parts:
;const cookies local ... = ;
Or use a CDN for the browser:
If you just want to play, go to the JSFiddle playground.
Cookies
Manipulate cookies with the simple getter/setter interface:
; cookiestoken = 42; // Set itconst res = cookiestoken; // Get itdelete cookiestoken; // Eat it
Cookies will retain the types that is set. This is possible thanks to the underlying library:
cookiesid = 1;cookiesaccepted = true;cookiesname = 'Francisco';cookiesfriends = 3 5;cookiesuser = id: 1 accepted: true name: 'Francisco' ;console; // 'number'console; // 'boolean'console; // 'string'console; // trueconsole; // '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:
;documentcookie = `name=`console; // Francisco
To delete a item, you have to call delete
on it as you would normally do with object properties:
console; // nullcookiesid = 1;console; // 1delete cookiesid;console; // 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;Object;Object;for let key in cookies {}for let val of cookies {}
Options
You can change the cookies options globally:
; // Options with its defaults. Note that expires is set to 100 dayscookiesoptions = 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; cookiestoken = 24; // Will be stored for ~100 days
WARNING: you should import
options
and then use it as a variable likecookies[options]
. You CANNOT donorcookies.options
.cookies['options']
LocalStorage
For localStorage
, we define local
to simplify the interface:
; localtoken = 42; // Set itconst res = localtoken; // Get itdelete localtoken; // Remove it
localStorage items can be set to many different standard values, and they will retain the types:
localid = 1;localaccepted = true;localname = 'Francisco';localfriends = 3 5;localuser = id: 1 accepted: true name: 'Francisco' ;console; // 'number'console; // 'boolean'console; // 'string'console; // trueconsole; // 'object'
Since 2.0 we are using custom data storage to keep the types consistent, but this means that you cannot read items that were set by
brownies
like. Please use thelocalStorage.getItem(KEY)
local.KEY
provided bybrownies
API instead.
To delete a item, you have to call delete
on it as you would normally do with object properties:
console; // nulllocalid = 1;console; // 1delete localid;console; // null
You can iterate over the items in many different standard ways as normal:
Object;Object;Object;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; delete localkey;
SessionStorage
For the sessionStorage
, we define session
to simplify the interface:
; sessiontoken = 42; // Set itconst res = sessiontoken; // Get itdelete sessiontoken; // Remove it
sessionStorage items can be set to many different standard values, and they will retain the types:
sessionid = 1;sessionaccepted = true;sessionname = 'Francisco';sessionfriends = 3 5;sessionuser = id: 1 accepted: true name: 'Francisco' ;console; // 'number'console; // 'boolean'console; // 'string'console; // trueconsole; // 'object'
Since 2.0 we are using custom data storage to keep the types consistent, but this means that you cannot read items that were set by
brownies
like. Please use thelocalStorage.getItem(KEY)
local.KEY
provided bybrownies
API instead.
To delete a item, you have to call delete
on it as you would normally do with object properties:
console; // nullsessionid = 1;console; // 1delete sessionid;console; // null
You can iterate over the items in many different standard ways as normal:
Object;Object;Object;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; delete sessionkey;
Subscribe
Subscribe allows you to listen to changes to any object, including yours:
; ; localtoken = 42;delete localtoken;localtoken = 'Hello';
Warning: subscribe()
cannot guarantee being sync, 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:
; ; // Note that this is the native one:localStorage;
To unsubscribe, store the value returned by subscribe()
and then use it with unsubscribe()
:
; const id = ; ;
You can also unsubscribe by the callback, which is very useful in a React context:
; const cb = console;;;
For instance, if you want to keep the user points synced across tabs with localStorage:
; Component { superprops; thisstate = points: localpoints ; thisupdatePoints = thisupdatePoints; ; } { this; } { ; } { return <div>Points: thisstatepoints</div>; }
Warning: try to keep the number of subscriptions low since each will incur in a performance cost.
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 🙂.
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.