Skip to content

shmolf/cuki

Repository files navigation

🍪 (cuki)

Commitizen friendly npm-size

This library is designed to help facilitate the creation, retrieval, and deletion of browser cookies.

Install

npm i cuki
yarn add cuki

Documentation

Current Documentation

Usage

Creating a Cookie

Creating a Cuki instance is meant for preparation of a browser cookie's properties before storing (persist) it within the browser. However, so long as you have that instance available, you can always tweak and re-persist. However, if the cookie name is changed, after having already called persist, then this will simply create a new cookie by the new name.

Simplest way to create a new browser cookie

new Cuki({
  name: 'your-cookie-name',
  value: 'value should be a string, boolean, or number',
  daysAlive: 365
}).persist();

If you prefer to specify a specific date when the cookie should expire, the specify a Date object for the expirationDate field. ie:

new Cuki({
  name: 'your-cookie-name',
  value: 'value should be a string, boolean, or number',
  expirationDate: new Date('December 31, 2042 03:24:00')
}).persist();

List of options

name: string,
value: string|number|boolean,
expirationDate: Date,
daysAlive: number,
secure: boolean,
httpOnly: boolean,
domain: string,
path: string,
sameSite: string,

Technically name is optional. But if it's not specified, a random emoji-character name will be created.
value is also optional, but this'll default to an empty string.

If none of the following options are provided, then the library will rely on browser defaults:

expirationDate: Date,
daysAlive: number,
httpOnly: boolean,
domain: string,
path: string,
sameSite: string,
secure: boolean, // If `sameSite` is set to `none`, then `secure` will be enabled.

Deleting a Cookie

Deletion is performed by setting the expiration date into the past.

Simply call deleteCookie(name)

Getting a Cookie Value

Simply call getCookie(name)

Example App Library

import { Cuki, getCookie, deleteCookie } from 'cuki';

function cookieSaveWrapper(name, value, duration) {
  (new Cuki({name, value, daysAlive: (duration ?? 365)})).persist();
}

function cookieGetWrapper(name) {
  return getCookie(name);
}

function cookieDeleteWrapper(name) {
  deleteCookie(name);
}

export default {
  store: cookieSaveWrapper,
  get: cookieGetWrapper,
  remove: cookieDeleteWrapper,
};

Loading for an ES5 application

<script src="https://unpkg.com/cuki@latest/dist/cuki.min.js"></script>
<pre id="output"></pre>
var cukiLibrary = window.cuki;
var output = document.getElementById('output');

var cookie = new cukiLibrary.Cuki({
  value: 'value should be a string, boolean, or number',
  daysAlive: 365,
});

cookie.persist();

console.log({
  cookieName: cookie.name, // '🗾🏠🦴🪨👩‍🔧🍋🧍🦅👩‍🦼👨‍💻' - example of random emoji name
  // This will return `null` when ran within JSFiddle
  value: cukiLibrary.getCookie(cookie.name) // 'value should be a string, boolean, or number'
});

output.innerText = cukiLibrary.getCookie(cookie.name)
  || 'Are you running this within JSFiddle? If so, it will not work.';

Contributing

Setup

npx yarn install

Run npx yarn build to generate the bundled output (will be found in dist/ directory).

There is not yet any tests.

Commits

Please encapsulate your changes into discrete commits, where each commit's changes are cohesive (clearly related), and of a similar nature. ie, commit changes to documentation along with changes to the code. Don't commit significant whitespace fixes, along with logic changes.

Commitlint

This repo is setup to use commitlint, so that the semantic-release library can auto-generate release documentation, and publish to npm.

Commitizen

If you're not familiar with the Conventional Commit format, then feel free to use the commitizen interactive terminal. This library should already have hooks setup. So if you run git commit in your terminal, then theorhetically, commitizen will take over and ask you questions.

  • If you're having issues, or don't quite understand how to use commitizen, please let me know. I'll do what I can to help, until I have better documentation setup.

Auto-Generate docs/* files

To generate documentation, you'll need to have node_modules (😭), and therefor need to run npm install.
Then, you can run the TypeDoc command.

npx typedoc

Please have the documentation updated, after any changes to code.