{"id":19006958,"url":"https://github.com/yowainwright/mini-cookies","last_synced_at":"2025-04-22T19:24:49.785Z","repository":{"id":37710997,"uuid":"454646060","full_name":"yowainwright/mini-cookies","owner":"yowainwright","description":"A mini Document.cookie package 🍪","archived":false,"fork":false,"pushed_at":"2025-04-11T15:45:06.000Z","size":21196,"stargazers_count":11,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-17T13:29:43.159Z","etag":null,"topics":["cookie","cookies","document-cookie","document-cookies","localstorage","no-dependencies","state-machines","state-management","typescript","vanilla-javascript"],"latest_commit_sha":null,"homepage":"https://jeffry.in/mini-cookies/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yowainwright.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["yowainwright"]}},"created_at":"2022-02-02T04:47:10.000Z","updated_at":"2025-04-07T05:05:34.000Z","dependencies_parsed_at":"2023-09-25T07:13:23.604Z","dependency_job_id":"bab07cb4-6b2e-48e4-ae5e-ba7c19dc2851","html_url":"https://github.com/yowainwright/mini-cookies","commit_stats":{"total_commits":144,"total_committers":5,"mean_commits":28.8,"dds":"0.23611111111111116","last_synced_commit":"bdedf2c4fe694dd4e712279171e94085632a53fa"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yowainwright%2Fmini-cookies","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yowainwright%2Fmini-cookies/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yowainwright%2Fmini-cookies/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yowainwright%2Fmini-cookies/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yowainwright","download_url":"https://codeload.github.com/yowainwright/mini-cookies/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250307202,"owners_count":21409050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cookie","cookies","document-cookie","document-cookies","localstorage","no-dependencies","state-machines","state-management","typescript","vanilla-javascript"],"created_at":"2024-11-08T18:35:28.058Z","updated_at":"2025-04-22T19:24:49.760Z","avatar_url":"https://github.com/yowainwright.png","language":"TypeScript","funding_links":["https://github.com/sponsors/yowainwright"],"categories":[],"sub_categories":[],"readme":"![mini-cookies](https://user-images.githubusercontent.com/1074042/183312781-79fe7561-5c45-4010-ac2c-14dbf3dbe423.svg)\n\n# [Mini Cookies](https://jeffry.in/mini-cookies) 🍪\n\n![Typed with TypeScript](https://flat.badgen.net/badge/icon/Typed?icon=typescript\u0026label\u0026labelColor=blue\u0026color=555555)\n![ci](https://github.com/yowainwright/mini-cookies/actions/workflows/ci.yml/badge.svg)\n[![npm](https://img.shields.io/npm/v/mini-cookies)](https://www.npmjs.com/package/mini-cookies)\n[![unpkg](https://img.shields.io/badge/unpkg-link-blue.svg)](https://unpkg.com/mini-cookies@latest/dist/mini-cookies.umd.js)\n[![Github](https://badgen.net/badge/icon/github?icon=github\u0026label\u0026color=black)](https://github.com/yowainwright/mini-cookies)\n\nA mini JS Document.cookie manager to help you write your cookies right! 🎯\n\nUse (or try) it in your \\*browser's console right now!\n\n```js\neval(await (await fetch('https://unpkg.com/mini-cookies@latest/dist/mini-cookies.umd.js')).text())\nconst cookies = miniCookies();\ncookies.set('mini', 'cookies!');\ncookies.get('mini'); // cookies!\n```\n\n\\*Evaling won't work on sites that don't allow the`unpkg` domain.\n\n---\n\n## Why Mini Cookies?\n\nMini Cookie's API is very small. It's size is also very small.\nEven though Mini Cookies is super small, it's built to make using [`document.cookie`](https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie)'s API easy!\n\n### How?\n\n1. It [smartly assists](#smartly-assist-constructing-cookies) in contructing `document.cookie` attributes.\n2. And, it store's your `document.cookie` [state](opt-in-cookie-state-management) so you can access/review your `document.cookie`'s state later—including attributes!\n\n---\n\n## Install\n\n```bash\nnpm install mini-cookies --save\n# pnpm/yarn add mini-cookies --save\n```\n\n---\n\n## Use\n\nBasic usage\n\n```typescript\nimport miniCookies from 'mini-cookies';\n\nconst cookies = miniCookies();\ncookies.set('mini', 'cookies!!!');\ncookies.get('mini'); // 'cookies!!!'\ncookies.remove('mini'); // no cookie!!! 😫\n```\n\nWith Mini Cookie state management\n\n```typescript\nimport miniCookies from 'mini-cookies';\n\nconst cookies = miniCookies({ hasState: true });\ncookies.set('mini', 'cookies!!!');\ncookies.get('mini'); // 'cookies!!!'\ncookies.review(); // mini-cookies-🍪: { mini: { value: 'cookies!!!' } }\ncookies.remove('mini'); // no cookie!!! 😫\n```\n\nWith debugging\n\n```typescript\nimport miniCookies from 'mini-cookies';\n\nconst cookies = miniCookies({ hasState: true, debug: true });\ncookies.set('mini', 'cookies!!!');\ncookies.get('mini'); // 'cookies!!!' + logs\ncookies.review(); // mini-cookies-🍪: { mini: { value: 'cookies!!!' } }\ncookies.remove('mini'); // no cookie!!! 😫 + logs\n```\n\n---\n\n## API\n\n### `miniCookies({options})`\n\n**`{options}`** an object argument of **Mini Cookies** options.\n\n- `{hasState: boolean}`: Whether or not to enable Mini Cookie state management.\n- `{debug: boolean}`: Whether or not to enable debugging.\n- \\*`{id: string}`: The unique identifier for each mini-cookie instance.\n\n---\n\n##### \\* `id`: unique identifier for each mini-cookie instance\n\nThe unique identifier is important to consider when considering mini-cookie state management. It provides a way to identify unique mini-cookie instances. **If** you're dealing with a scenerio where you have multiple mini-cookie instances, insuring you have a unique `id` for your mini-cookie instance is required for accurate mini-cookie state management.\n\n---\n\n| Option | Type | Default | Description |\n| :------: | :----: | :-------: | :----------- |\n| `id` | `string` | `'mini-cookies-key'` | The unique identifier for each mini-cookie instance. |\n| `hasState` | `boolean` | `false` | Whether or not to enable Mini Cookie state management. |\n| `debug` | `boolean` | `false` | Whether or not to enable debugging. |\n\n---\n\n### `miniCookies({options}).set(\u003ckey\u003e, \u003cvalue\u003e), {attributes})`\n\nSet a cookie.\n\n#### params\n\n- `\u003ckey\u003e`: a string\n- `\u003cvalue\u003e`: a string\n- `{attributes}`: an object of cookie attributes.\n\n---\n\n### `miniCookies({options}).get(\u003ckey\u003e)`\n\nGets a cookie by string.\n\n#### param\n\n- `\u003ckey\u003e`: a string\n\n---\n\n### `miniCookies({options}).remove(\u003ckey\u003e)`\n\nRemoves a cookie by string.\n\n#### param\n\n- `\u003ckey\u003e`: a string\n\n---\n\n### `miniCookies({options}).review()`\n\nReturns mini-cookie state.\n\n\\***`hasState`** must be enabled for this to work!\n\n---\n\n### `miniCookies({options}).clearState()`\nClears mini-cookie state.\n\n*hasState must be enabled for this to work!\n\n---\n\n## Smartly Assist Constructing Cookies\n\nThe ability to smartly assist in constructing cookie attributes and store cookie state is awesome because `document.cookie` cookies can't be updated (only overwritten) and `document.cookie` cookies attributes can't be read (only written). With Mini Cookies, `document.cookie` state is accessible and writing the `document.cookie` you want is easy. More to diagrams and such on this to come!\n\n---\n\n## Opt-in Cookie State Management\n\nYou don't need to use Mini Cookies state! It is opt-in only! This is good for your app's maintainability. The recommended pattern is using Mini Cookies state management to get your `document.cookie`'s working how you want and then turning off Mini Cookies State Management when your cookies are working how you want. More state diagrams and such to come!\n\n---\n\n## Recipes\n\nMini Cookies is built form ease of use. It provides ways to keep track of the Cookie attributes and the state of the Cookies you set. Furthermore, Cookie attributes can be confusing. Using simplified convenience attributes, **\"smart attributes\"**, making the right attribute decisions is just a bit easier.\n\n### Smart attributes\n\nMini Cookies provides smart attributes which are built to be intuitive to how we generally set cookies.\n\n---\n\n#### `days`\n\n\u003e `days` creates an `expires` cookie attribute.\n\nBy adding the `days` attribute, you can set the `expires` attribute to the number of days from now vs having to think about dates, etc.\n\n```typescript\n// set expires to 1 day useing `days`\nconst cookies = miniCookies();\ncookies.set('mini', 'cookies!!!', { days: 1 });\n```\n\nIf you want to explicitly set the `expires` attribute, you can still use `expires` attribute.\n\n```typescript\n// set expires manually\nconst timeToAdd = 1000 * 60 * 60 * 24 * 7 * 4 * 6;\nconst date = new Date();\nconst expiryTime = `${parseInt(date.getTime())}${timeToAdd}`;\ndate.setTime(expiryTime);\nconst expires = date.toUTCString();\nconst cookies = miniCookies();\ncookies.set('mini', 'cookies!!!', { expires });\n```\n\n---\n\n#### `isSecure`\n\n\u003e `isSecure` creates `secure`, `__Secure-`, and `samesite=strict` cookie attributes.\n\n```typescript\n// set isSecure\nconst cookies = miniCookies();\ncookies.set('mini', 'cookies!!!', { isSecure: true });\n```\n\nIf you want to explicitly set secure cookie attributes, you can still provide the following attributes.\n\n```typescript\n// set secure attributes manually\ncookies.set('mini', 'cookies!!!', { secure: true, __Secure__: true, samesite: 'strict' });\n```\n\n---\n\n#### `isStrictSecure`\n\n\u003e `isStrictSecure` creates `secure`, `__Secure-`, `__Host-`, `path=/` and `samesite=strict` cookie attributes.\n\n```typescript\n// set isStrictSecure\nconst cookies = miniCookies();\ncookies.set('mini', 'cookies!!!', { isStrictSecure: true });\n```\n\nIf you want to explicitly set secure cookie attributes, you can still provide the following attributes.\n\n```typescript\n// set secure attributes manually\ncookies.set('mini', 'cookies!!!', { secure: true, __Secure__: true, samesite: 'strict', __Host__: true, path: '/' });\n```\n\n---\n\n### Opt-in State\n\nA huge benefit to Mini-Cookies is the ability to opt-in for state management. Although, `document.cookies` is only a string api, the fact that attributes are `write-only` and that there is often a misunderstanding that cookies can't be overwritten can be a problem.\n\nWith Mini Cookies, you can opt-in for state management.\n\n```typescript\nconst cookies = miniCookies({ hasState: true });\ncookies.set('mini', 'cookies!!!');\ncookies.review(); // { mini: 'cookies!!!' }\n```\n\nIf you don't want opt-in state management, you can still use Mini Cookies without it.\n\n```typescript\nconst cookies = miniCookies();\ncookies.set('mini', 'cookies!!!');\ncookies.review(); // \u003cvoid\u003e\n```\n\n---\n\n## Sandbox Environments\n\n**Note:** cookies are not supported in sandbox environments. Within the StackBlitz sandbox, click the \"Open in New Tab\" button to view mini-cookies in action! See the image below for visual UI reference.\n\n---\n\n![mini-cooies-stackblitz](https://user-images.githubusercontent.com/1074042/184686402-a880f134-5aaf-4b58-939d-42c4bbc38450.gif)\n\n---\n\n- [mini-cookies basic demo](https://stackblitz.com/edit/mini-cookies?file=index.js)\n- [mini-cookies multi-state instance demo](https://stackblitz.com/edit/mini-cookies-multi-state-instances?file=index.js)\n\n[![Mini Cookies—A document.cookie manager - Watch Video](https://cdn.loom.com/sessions/thumbnails/a77bdd325bcf4c399c93d7297988d42b-with-play.gif)](https://www.loom.com/share/a77bdd325bcf4c399c93d7297988d42b)\n\n---\n## Comparisons\n\n| name | file size | key features |\n| :--- | --- | :--- |\n| mini-cookies | ![size](https://img.shields.io/bundlephobia/minzip/mini-cookies) | state management, smart attributes |\n| js-cookie | ![size](https://img.shields.io/bundlephobia/minzip/js-cookie/3) | well known, simple api |\n\n---\n\n## Feature Requests\n\nYes! I'm happy to add more utility to Mini Cookies!\n\n---\n\nMade by [@yowainwright](https://github.com/yowainwright), MIT 2022\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyowainwright%2Fmini-cookies","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyowainwright%2Fmini-cookies","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyowainwright%2Fmini-cookies/lists"}