cookick

A simple utilities for browser cookies APIs

为什么
安装
- 运行环境要求
如何使用
参考文档
- document.cookie MDN 规范说明
- maxAge sameSite等新属性的兼容性

为什么

已经有非常多的 cookie 相关工具了，甚至多年以前，在我初次接触 js 学习之处，也折腾过 COOKIE 这么个小玩意儿。

但是当我现在需要一个足够简单（现代 web 开发中，有着更多强大、丰富的本地存储方案，js 对于 cookie 的依赖越来越少）、支持标准的 cookie 工具时，我发现目前我能找到的各类 cookie 库（例如 js-cookie、jquery-cookie甚至还有react-cookie？？？）都或多或少存在一些问题，有些破坏了标准，有些不支持较新的标准，有些是过度设计，过于繁重（COOKIE就是过度设计了）。

而直到我发现了 jshttp/cookie 这个标准库，虽然其是针对 HTTP cookies 规范定制，但是可以几乎完整适用于浏览器端。所以我基于该库做了稍微的修改定制，也就有了现在这个 cookick（名字由 cookie 和 kick 组合而来）

安装

// use npm
$ npm install cookick --save
 
// use yarn
$ yarn add cookick

注意：cookick也提供了umd格式的包，你可以将cookick的umd包传到服务器上，然后通过script标签在页面中引入，直接通过window.cookick调用。

<!-- from self hosted cdn -->
<script src="{{ YOUR_CDN_URL }}/cookick.umd.production.js"></script>
 
<!-- from unpkg -->
<script src="https://unpkg.com/cookick/dist/cookick.umd.production.js"></script>
 
<!-- from jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/cookick/dist/cookick.umd.production.js"></script>

运行环境要求

cookick采用TypeScript开发，并用rollup和babel进行构建成 ES5 代码后发布。要保证cookick在所有平台都能正常运行，请确保你的运行环境中支持以下必要条件：

Object.assign IE*要求
Object.defineProperty < IE9要求
Object.freeze < IE9要求

注：在create-react-app或者vue-cli构建的项目中，都是可以安全运行cookick的。

cookick也可以在服务端中运行，但是不推荐。建议优先选择其它与服务端框架结合更紧密的其它 cookie 方法，例如 Express.js 推荐的 cookie-parser。

如何使用

cookick提供了一组方法用于获取或者设置 cookie。

`getCookie`

服务端在调用该方法前，需要先调用 updateCookieSource 设置 cookie 解析来源。

declare function getCookie(name: string): string | undefined;

使用示例：

import { getCookie } from 'cookick';
 
getCookie('foo'); // 获取名称为 foo 的cookie

`setCookie`

仅在浏览器端生效，服务端应当利用其返回值自行设置响应头来处理 cookie。

interface CookieOptions {
    path?: string;
    domain?: string;
    expires?: Date; // 必须是Date对象
    maxAge?: number; // 整数，表示maxAge秒后过期。建议总是使用maxAge，不要使用expires。maxAge和expires如果同时存在，会忽略expires参数
    httpOnly?: boolean;
    secure?: boolean;
    sameSite?: boolean | 'lax' | 'strict' | 'none';
}
 
declare function setCookie(name: string, val: string | number, options?: CookieOptions): string;

使用示例：

import { setCookie } from 'cookick';
 
// 默认调用：在当前域下，path=/， 创建foo=bar的cookie
setCookie('foo', 'bar');
 
// 指定path参数
setCookie('foo', 'bar', {
    path: '/sub'
    // 甚至可以使用相对路径
    // path: '../another/sub'
});
 
// 设置doamin
setCookie('foo', 'bar', {
    domain: 'cookie.com'
});
 
// 设置过期时间，建议使用maxAge参数，设置过期秒数: https://javascript.info/cookie#expires-max-age
setCookie('foo', 'bar', {
    maxAge: 60 * 60 * 24 * 7
});
 
// 设置 secure、httpOnly、sameSite等
// 这些属性并不是所有浏览器都支持，有些目前仅在 server-http 协议支持，请使用前慎重考虑
setCookie('foo', 'bar', {
    secure: true,
    httpOnly: true,
    sameSite: 'strict'
});
 
/*=================服务端==================*/
req.setHeader('set-cookie', setCookie('foo', 'bar'));

`delCookie`

仅在浏览器端生效，服务端应当利用其返回值自行设置响应头来处理 cookie。

declare function delCookie(
    name: string,
    options?: {
        path?: string;
        domain?: string;
    }
): string;

使用示例：

import { delCookie } from 'cookick';
 
delCookie('foo'); // 删除名称为 foo 的cookie
 
// 如果cookie在其他子路径或者domain下，需要指定明确的path或者domain才能删除
delCookie('foo', {
    path: '/sub'
});
 
/*=================服务端==================*/
req.setHeader('set-cookie', delCookie('foo'));

`getAllCookies`

服务端在调用该方法前，需要先调用 updateCookieSource 设置 cookie 解析来源。

declare function getAllCookies(): {
    [P: string]: string | undefined;
};

使用示例：

import { getAllCookies } from 'cookick';
 
getAllCookies(); // 解析所有的cookie为一个object对象

`serialize`

declare function serialize(name: string, val: string | number, options?: CookieOptions): string;

序列化一个新的 cookie 为字符串，你可以将其用于在服务端或者浏览器端设置 cookie：

const newCookieStr = serialize('foo', 'bar', {
    path: '/'
});
 
// 浏览器端
document.cookie = newCookieStr;
 
// 服务端
response.setHeader('set-cookie', newCookieStr);

`setDefault`

设置默认参数

declare function setDefault(options: CookieOptions): CookieOptions;

使用示例：

import { setDefault } from 'cookick';
 
// 在调用 setCookie 没有传递path、domain情况下，会总是将cookie根据默认参数进行设置
setDefault({
    path: '/basename',
    domain: '.root.domain'
});

`updateCookieSource`

该方法建议仅在服务端调用，在调用getCookie getAllCookies等方法前，通过该方法将服务端请求的 cookie 字符串更新到cookick：

const { updateCookieSource, getCookie } = require('cookick');
 
app.get('/', (req, res) => {
    udpateCookieSource(req.headers.cookie);
 
    console.log(getCookie('foo'));
});

参考文档

document.cookie MDN 规范说明

https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie

cookick

cookick

为什么

安装

运行环境要求

如何使用

`getCookie`

`setCookie`

`delCookie`

`getAllCookies`

`serialize`

`setDefault`

`updateCookieSource`

参考文档

document.cookie MDN 规范说明

`maxAge` `sameSite`等新属性的兼容性

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

cookick

cookick

为什么

安装

运行环境要求

如何使用

getCookie

setCookie

delCookie

getAllCookies

serialize

setDefault

updateCookieSource

参考文档

document.cookie MDN 规范说明

maxAge sameSite等新属性的兼容性

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

`getCookie`

`setCookie`

`delCookie`

`getAllCookies`

`serialize`

`setDefault`

`updateCookieSource`

`maxAge` `sameSite`等新属性的兼容性

Weekly Downloads