{"id":21195625,"url":"https://github.com/qiqiboy/cookick","last_synced_at":"2025-07-10T04:30:28.822Z","repository":{"id":57206971,"uuid":"225760247","full_name":"qiqiboy/cookick","owner":"qiqiboy","description":"A simple utilities for browser cookies APIs.","archived":false,"fork":false,"pushed_at":"2024-09-26T22:16:36.000Z","size":112,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-15T00:38:22.727Z","etag":null,"topics":["browser-cookie","cookie","cookie-tools","cookie-utilities","dom-cookie","js-cookie","typescript"],"latest_commit_sha":null,"homepage":"","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/qiqiboy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-12-04T02:21:57.000Z","updated_at":"2024-09-18T07:17:51.000Z","dependencies_parsed_at":"2022-09-08T17:01:52.600Z","dependency_job_id":null,"html_url":"https://github.com/qiqiboy/cookick","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qiqiboy%2Fcookick","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qiqiboy%2Fcookick/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qiqiboy%2Fcookick/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qiqiboy%2Fcookick/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qiqiboy","download_url":"https://codeload.github.com/qiqiboy/cookick/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225618274,"owners_count":17497489,"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":["browser-cookie","cookie","cookie-tools","cookie-utilities","dom-cookie","js-cookie","typescript"],"created_at":"2024-11-20T19:29:17.996Z","updated_at":"2024-11-20T19:29:18.828Z","avatar_url":"https://github.com/qiqiboy.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cookick\n\nA simple utilities for browser cookies APIs\n\n[![npm](https://img.shields.io/npm/v/cookick.svg?style=flat)](https://npm.im/cookick)\n[![definitionTypes](https://img.shields.io/npm/types/cookick.svg)](https://github.com/qiqiboy/cookick/blob/master/index.d.ts)\n[![gzip](http://img.badgesize.io/https://unpkg.com/cookick/dist/cookick.umd.production.js?compression=gzip\u0026color=green)](https://npm.im/cookick)\n[![download](https://img.shields.io/npm/dm/cookick.svg)](https://npm.im/cookick)\n[![issues](https://img.shields.io/github/issues/qiqiboy/cookick.svg)](https://github.com/qiqiboy/cookick/issues)\n[![license](https://img.shields.io/github/license/qiqiboy/cookick.svg)](https://github.com/qiqiboy/cookick/blob/master/LICENSE)\n[![github](https://img.shields.io/github/last-commit/qiqiboy/cookick.svg)](https://github.com/qiqiboy/cookick)\n[![github](https://img.shields.io/github/commit-activity/m/qiqiboy/cookick.svg)](https://github.com/qiqiboy/cookick/commits/master)\n[![github](https://img.shields.io/github/stars/qiqiboy/cookick.svg?style=social)](https://github.com/qiqiboy/cookick)\n\n\u003c!-- vim-markdown-toc GFM --\u003e\n\n* [为什么](#为什么)\n* [安装](#安装)\n    - [运行环境要求](#运行环境要求)\n* [如何使用](#如何使用)\n    - [`getCookie`](#getcookie)\n    - [`setCookie`](#setcookie)\n    - [`delCookie`](#delcookie)\n    - [`getAllCookies`](#getallcookies)\n    - [`serialize`](#serialize)\n    - [`setDefault`](#setdefault)\n* [参考文档](#参考文档)\n    - [document.cookie MDN 规范说明](#documentcookie-mdn-规范说明)\n    - [`maxAge` `sameSite`等新属性的兼容性](#maxage-samesite等新属性的兼容性)\n\n\u003c!-- vim-markdown-toc --\u003e\n\n## 为什么\n\n已经有非常多的 cookie 相关工具了，甚至多年以前，在我初次接触 js 学习之处，也折腾过 [`COOKIE`](https://github.com/qiqiboy/COOKIE) 这么个小玩意儿。\n\n但是当我现在需要一个足够简单（现代 web 开发中，有着更多强大、丰富的本地存储方案，js 对于 cookie 的依赖越来越少）、支持标准的 cookie 工具时，我发现目前我能找到的各类 cookie 库（例如 `js-cookie`、`jquery-cookie`甚至还有`react-cookie`？？？）都或多或少存在一些问题，有些破坏了标准，有些不支持较新的标准，有些是过度设计，过于繁重（[`COOKIE`](https://github.com/qiqiboy/COOKIE)就是过度设计了）。\n\n而直到我发现了 [jshttp/cookie](https://github.com/jshttp/cookie) 这个标准库，虽然其是针对 `HTTP cookies` 规范定制，但是可以几乎完整适用于浏览器端。所以我基于该库做了稍微的修改定制，也就有了现在这个 `cookick`（名字由 `cookie` 和 `kick` 组合而来）\n\n## 安装\n\n[![cookick](https://nodei.co/npm/cookick.png?compact=true)](https://npm.im/cookick)\n\n```bash\n// use npm\n$ npm install cookick --save\n\n// use yarn\n$ yarn add cookick\n```\n\n**注意**：`cookick`也提供了`umd`格式的包，你可以将`cookick`的`umd`包传到服务器上，然后通过`script`标签在页面中引入，直接通过`window.cookick`调用。\n\n```html\n\u003c!-- from self hosted cdn --\u003e\n\u003cscript src=\"{{ YOUR_CDN_URL }}/browser.umd.js\"\u003e\u003c/script\u003e\n\n\u003c!-- from unpkg --\u003e\n\u003cscript src=\"https://unpkg.com/cookick/dist/browser.umd.js\"\u003e\u003c/script\u003e\n\n\u003c!-- from jsDelivr --\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/cookick/dist/browser.umd.js\"\u003e\u003c/script\u003e\n```\n\n### 运行环境要求\n\n`cookick`支持在浏览器端和服务器端(`express`+`Nodejs`)运行。如果要在服务器端运行，需要在调用前挂载 middleware：\n\n```typescript\nimport { middleware } from 'cookick';\n\napp.use(middleware);\n```\n\nnodejs 需要支持`AsyncLocalStorage`，最低版本要求为`v12.17.0`。\n\n## 如何使用\n\n`cookick`提供了一组方法用于获取或者设置 cookie。浏览器和服务器端调用签名均完全一致，**如果是 SSR，在组件中也可以放心调用**。\n\n### `getCookie`\n\n```typescript\ndeclare function getCookie(name: string): string | undefined;\n```\n\n使用示例：\n\n```typescript\nimport { getCookie } from 'cookick';\n\ngetCookie('foo'); // 获取名称为 foo 的cookie\n```\n\n### `setCookie`\n\n```typescript\ninterface CookieOptions {\n    path?: string;\n    domain?: string;\n    expires?: Date; // 必须是Date对象\n    maxAge?: number; // 整数，表示maxAge秒后过期。建议总是使用maxAge，不要使用expires。maxAge和expires如果同时存在，会忽略expires参数\n    httpOnly?: boolean;\n    secure?: boolean;\n    sameSite?: boolean | 'lax' | 'strict' | 'none';\n}\n\ndeclare function setCookie(name: string, val: string | number, options?: CookieOptions): void;\n```\n\n使用示例：\n\n```typescript\nimport { setCookie } from 'cookick';\n\n// 默认调用：在当前域下，path=/， 创建foo=bar的cookie\nsetCookie('foo', 'bar');\n\n// 指定path参数\nsetCookie('foo', 'bar', {\n    path: '/sub'\n    // 甚至可以使用相对路径\n    // path: '../another/sub'\n});\n\n// 设置doamin\nsetCookie('foo', 'bar', {\n    domain: 'cookie.com'\n});\n\n// 设置过期时间，建议使用maxAge参数，设置过期秒数: https://javascript.info/cookie#expires-max-age\nsetCookie('foo', 'bar', {\n    maxAge: 60 * 60 * 24 * 7\n});\n\n// 设置 secure、httpOnly、sameSite等\n// 这些属性并不是所有浏览器都支持，有些目前仅在 server-http 协议支持，请使用前慎重考虑\nsetCookie('foo', 'bar', {\n    secure: true,\n    httpOnly: true,\n    sameSite: 'strict'\n});\n```\n\n### `delCookie`\n\n```typescript\ndeclare function delCookie(\n    name: string,\n    options?: {\n        path?: string;\n        domain?: string;\n    }\n): void;\n```\n\n使用示例：\n\n```typescript\nimport { delCookie } from 'cookick';\n\ndelCookie('foo'); // 删除名称为 foo 的cookie\n\n// 如果cookie在其他子路径或者domain下，需要指定明确的path或者domain才能删除\ndelCookie('foo', {\n    path: '/sub'\n});\n```\n\n### `getAllCookies`\n\n```typescript\ndeclare function getAllCookies(): {\n    [P: string]: string | undefined;\n};\n```\n\n使用示例：\n\n```typescript\nimport { getAllCookies } from 'cookick';\n\ngetAllCookies(); // 解析所有的cookie为一个object对象\n```\n\n### `serialize`\n\n```typescript\ndeclare function serialize(name: string, val: string | number, options?: CookieOptions): string;\n```\n\n序列化一个新的 cookie 为字符串，你可以将其用于在服务端或者浏览器端设置 cookie：\n\n```typescript\nconst newCookieStr = serialize('foo', 'bar', {\n    path: '/'\n});\n\n// 浏览器端\ndocument.cookie = newCookieStr;\n\n// 服务端\nresponse.setHeader('set-cookie', newCookieStr);\n```\n\n### `setDefault`\n\n设置默认参数\n\n```typescript\ndeclare function setDefault(options: CookieOptions): CookieOptions;\n```\n\n使用示例：\n\n```typescript\nimport { setDefault } from 'cookick';\n\n// 在调用 setCookie 没有传递path、domain情况下，会总是将cookie根据默认参数进行设置\nsetDefault({\n    path: '/basename',\n    domain: '.root.domain'\n});\n```\n\n## 参考文档\n\n### document.cookie MDN 规范说明\n\n-   https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie\n\n### `maxAge` `sameSite`等新属性的兼容性\n\n-   https://javascript.info/cookie#expires-max-age\n-   https://caniuse.com/#feat=mdn-http_headers_set-cookie_max-age\n-   https://caniuse.com/#feat=same-site-cookie-attribute\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqiqiboy%2Fcookick","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqiqiboy%2Fcookick","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqiqiboy%2Fcookick/lists"}