# @alicloud/cookie

> ConsoleBase Cookie

Latest version **1.6.2** (published 2024-07-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @alicloud/cookie
pnpm add @alicloud/cookie
yarn add @alicloud/cookie
bun add @alicloud/cookie
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.6.2 |
| Published | 2024-07-01 |
| First published | 2020-12-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 27.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Jianchun Wang |
| Keywords | util, cookie |

## Links

- npm: https://www.npmjs.com/package/@alicloud/cookie
- npm.io page: https://npm.io/package/@alicloud/cookie

## Alternatives

- [lodash.assign](https://npm.io/package/lodash.assign.md) — 2.3M weekly downloads
- [lodash.chunk](https://npm.io/package/lodash.chunk.md) — 1.8M weekly downloads
- [react-native-ios-utilities](https://npm.io/package/react-native-ios-utilities.md) — 138.5K weekly downloads
- [@technically/lodash](https://npm.io/package/@technically/lodash.md) — 50.9K weekly downloads
- [@fluid-topics/ft-icon](https://npm.io/package/@fluid-topics/ft-icon.md) — 20.6K weekly downloads

## Recent versions

- 1.6.2 (latest) — 2024-07-01
- 1.7.0-beta.1 (beta) — 2024-08-29
- 1.6.0-alpha.2 (alpha) — 2024-01-03
- 1.6.3-beta.1 — 2024-07-01
- 1.6.1 — 2024-06-21
- 1.6.0 — 2024-06-12
- 1.6.0-beta.2 — 2024-06-06
- 1.6.0-beta.1 — 2024-04-30
- 1.6.0-alpha.1 — 2023-12-28
- 1.5.3 — 2023-03-24
- 1.5.2 — 2023-01-19
- 1.5.1 — 2023-01-05
- 1.5.0 — 2022-11-28
- 1.4.6 — 2022-11-08
- 1.4.5 — 2022-11-08
- … 108 more at https://npm.io/package/@alicloud/cookie/versions

## README

# @alicloud/cookie

yet... another 饼干的获取和操作工具

## INSTALL

```shell
tnpm i @alicloud/cookie -S
```

## APIs

## getAllCookies

获取当前页面可以访问到的全部 cookie。

```typescript
function getAllCookies(): object;
```

## getCookie

获取单个 cookie

```typescript
function getCookie(name: string): string | undefined;
```

## setCookie

设置 cookie，设置 cookie，默认为时间为 180 天，设置 extra.days 为 0 可以保存为 session cookie（expires 为空）

```typescript
function setCookie(name: string, value: string, extra: {
  domain?: string; // 默认为当前页面的二级域名，如 `.aliyun.com`，如果是 IP 则为 IP，如 `127.0.0.1`
  path?: string; // 默认 '/'
  days?: number; // 默认 180，传入 `days: 0` 成为 session cookie
  encoding?: boolean; // 默认 true，传入 `false` 可保存原始的值（比如 value 已经经过 base64 编码过）
} = {}): void;
```

## deleteCookie

删除 cookie，其实设置一个过期时间为此刻之前的时间，浏览器会自动清理过期的 cookie

```typescript
function deleteCookie(name: string, extra: {
  domain?: string;
  path?: string;
} = {}): void;
```

## SameSite + Secure 以及 HTTPS 和 Iframe 的影响

以下条件下：

* 协议
  + `http://`
  + `https://`
* iframe
  + 无
  + 不跨域
  + 跨子域
  + 跨全域

SameSite 和 Secure 各值：

* SameSite
  + undefined
  + Lax
  + Strict
  + None
* Secure
  + true
  + false

在各个浏览器：

* 浏览器
  + Firefox
  + Chrome
  + Safari

下对 set cookie 的影响。

### 测试脚本

注意，在 Iframe 下，需通过浏览器的 Console 切换到对应的 Iframe 上下文。

```javascript
(() => {
  function setCookie(name, value, {
    path = '/',
    sameSite,
    secure
  } = {}) {
    const parts = [
      `${name}=${encodeURIComponent(value)}`,
      // `domain=${domain}`,
      `path=${path}`
    ];
    
    if (sameSite !== undefined) {
      parts.push(`sameSite=${sameSite}`);
    }
    
    if (secure !== undefined) {
      parts.push(`secure=${secure}`);
    }
    
    document.cookie = parts.join('; ');
  }
  
  function getCookie(name) {
    return document.cookie.split(/\s*;\s*/).reduce((result, v) => {
      const [cookieName, cookieValue] = v.split('=');
      
      try {
        result[cookieName] = decodeURIComponent(cookieValue);
      } catch (err) {
      }
      
      return result;
    }, {})[name];
  }
  
  const TIME = Date.now();
  
  const ITEMS = [undefined, 'Lax', 'Strict', 'None'].reduce((result, sameSite) => {
    [undefined, true, false].forEach(secure => {
      const name = `TEST_SameSite_${sameSite}__Secure_${secure}`;
      const value = `${sameSite}_${secure}_${TIME}`;
      
      setCookie(name, value, {
        sameSite,
        secure
      });
      
      const valueGet = getCookie(name);
      
      result.push({
        name,
        value,
        valueGet,
        sameSite,
        secure,
        result: valueGet === value ? '✅' : '❌'
      });
    });
    
    return result;
  }, []);
  
  console.table(ITEMS, ['sameSite', 'secure', 'result']);
})();
```

### HTTP 非 Iframe

| SameSite     | Secure      | Firefox | Chrome | Safari |
|--------------|-------------|---------|--------|--------|
| `undefined`  | `undefined` | ✅       | ✅      | ✅      |
| `undefined`  | `true`      | ❌       | ❌      | ❌      |
| `undefined`  | `false`     | ❌       | ❌      | ❌      |
| Lax          | `undefined` | ✅       | ✅      | ✅      |
| Lax          | `true`      | ❌       | ❌      | ❌      |
| Lax          | `false`     | ❌       | ❌      | ❌      |
| Strict       | `undefined` | ✅       | ✅      | ✅      |
| Strict       | `true`      | ❌       | ❌      | ❌      |
| Strict       | `false`     | ❌       | ❌      | ❌      |
| None         | `undefined` | ❌       | ❌      | ✅      |
| None         | `true`      | ❌       | ❌      | ❌      |
| None         | `false`     | ❌       | ❌      | ❌      |

### HTTP Iframe 不跨域

| SameSite     | Secure      | Firefox | Chrome | Safari |
|--------------|-------------|---------|--------|--------|
| `undefined`  | `undefined` | ✅       | ✅      | ✅      |
| `undefined`  | `true`      | ❌       | ❌      | ❌      |
| `undefined`  | `false`     | ❌       | ❌      | ❌      |
| Lax          | `undefined` | ✅       | ✅      | ✅      |
| Lax          | `true`      | ❌       | ❌      | ❌      |
| Lax          | `false`     | ❌       | ❌      | ❌      |
| Strict       | `undefined` | ✅       | ✅      | ✅      |
| Strict       | `true`      | ❌       | ❌      | ❌      |
| Strict       | `false`     | ❌       | ❌      | ❌      |
| None         | `undefined` | ❌       | ❌      | ✅      |
| None         | `true`      | ❌       | ❌      | ❌      |
| None         | `false`     | ❌       | ❌      | ❌      |

### HTTP（Iframe 跨子域）

| SameSite     | Secure      | Firefox | Chrome | Safari |
|--------------|-------------|---------|--------|--------|
| `undefined`  | `undefined` | ✅       | ✅      | ✅      |
| `undefined`  | `true`      | ❌       | ❌      | ❌      |
| `undefined`  | `false`     | ❌       | ❌      | ❌      |
| Lax          | `undefined` | ✅       | ✅      | ✅      |
| Lax          | `true`      | ❌       | ❌      | ❌      |
| Lax          | `false`     | ❌       | ❌      | ❌      |
| Strict       | `undefined` | ✅       | ✅      | ✅      |
| Strict       | `true`      | ❌       | ❌      | ❌      |
| Strict       | `false`     | ❌       | ❌      | ❌      |
| None         | `undefined` | ❌       | ❌      | ✅      |
| None         | `true`      | ❌       | ❌      | ❌      |
| None         | `false`     | ❌       | ❌      | ❌      |

### HTTP（Iframe 跨全域）

| SameSite     | Secure      | Firefox | Chrome | Safari |
|--------------|-------------|---------|--------|--------|
| `undefined`  | `undefined` | ❌       | ❌      | ❌      |
| `undefined`  | `true`      | ❌       | ❌      | ❌      |
| `undefined`  | `false`     | ❌       | ❌      | ❌      |
| Lax          | `undefined` | ❌       | ❌      | ❌      |
| Lax          | `true`      | ❌       | ❌      | ❌      |
| Lax          | `false`     | ❌       | ❌      | ❌      |
| Strict       | `undefined` | ❌       | ❌      | ❌      |
| Strict       | `true`      | ❌       | ❌      | ❌      |
| Strict       | `false`     | ❌       | ❌      | ❌      |
| None         | `undefined` | ❌       | ❌      | ❌      |
| None         | `true`      | ❌       | ❌      | ❌      |
| None         | `false`     | ❌       | ❌      | ❌      |

### HTTPS 非 Iframe

| SameSite     | Secure      | Firefox | Chrome | Safari |
|--------------|-------------|---------|--------|--------|
| `undefined`  | `undefined` | ✅       | ✅      | ✅      |
| `undefined`  | `true`      | ✅       | ✅      | ✅      |
| `undefined`  | `false`     | ✅       | ✅      | ✅      |
| Lax          | `undefined` | ✅       | ✅      | ✅      |
| Lax          | `true`      | ✅       | ✅      | ✅      |
| Lax          | `false`     | ✅       | ✅      | ✅      |
| Strict       | `undefined` | ✅       | ✅      | ✅      |
| Strict       | `true`      | ✅       | ✅      | ✅      |
| Strict       | `false`     | ✅       | ✅      | ✅      |
| None         | `undefined` | ❌       | ❌      | ✅      |
| None         | `true`      | ✅       | ✅      | ✅      |
| None         | `false`     | ✅       | ✅      | ✅      |

### HTTPS 在 Iframe 下（不跨域）

`a.com` 页面通过 Iframe 内嵌 `a.com` 页面，在内层 `a.com` 页面上进行测试。

| SameSite     | Secure      | Firefox | Chrome | Safari |
|--------------|-------------|---------|--------|--------|
| `undefined`  | `undefined` | ✅       | ✅      | ✅      |
| `undefined`  | `true`      | ✅       | ✅      | ✅      |
| `undefined`  | `false`     | ✅       | ✅      | ✅      |
| Lax          | `undefined` | ✅       | ✅      | ✅      |
| Lax          | `true`      | ✅       | ✅      | ✅      |
| Lax          | `false`     | ✅       | ✅      | ✅      |
| Strict       | `undefined` | ✅       | ✅      | ✅      |
| Strict       | `true`      | ✅       | ✅      | ✅      |
| Strict       | `false`     | ✅       | ✅      | ✅      |
| None         | `undefined` | ❌       | ❌      | ✅      |
| None         | `true`      | ✅       | ✅      | ✅      |
| None         | `false`     | ✅       | ✅      | ✅      |

### HTTPS 在 Iframe 下（跨子域）

`xx.a.com` 页面通过 Iframe 内嵌 `yy.a.com` 页面，在 `yy.a.com` 页面上进行测试。

| SameSite     | Secure      | Firefox | Chrome | Safari |
|--------------|-------------|---------|--------|--------|
| `undefined`  | `undefined` | ✅       | ❌      | ✅      |
| `undefined`  | `true`      | ✅       | ❌      | ✅      |
| `undefined`  | `false`     | ✅       | ❌      | ✅      |
| Lax          | `undefined` | ❌       | ❌      | ✅      |
| Lax          | `true`      | ❌       | ❌      | ✅      |
| Lax          | `false`     | ❌       | ❌      | ✅      |
| Strict       | `undefined` | ❌       | ❌      | ✅      |
| Strict       | `true`      | ❌       | ❌      | ✅      |
| Strict       | `false`     | ❌       | ❌      | ✅      |
| None         | `undefined` | ❌       | ❌      | ✅      |
| None         | `true`      | ✅       | ✅      | ✅      |
| None         | `false`     | ✅       | ✅      | ✅      |

### HTTPS 在 Iframe 下（跨全域）

`a.com` 页面通过 Iframe 内嵌 `b.com` 页面，在 `b.com` 页面上进行测试。

| SameSite     | Secure      | Firefox | Chrome | Safari |
|--------------|-------------|---------|--------|--------|
| `undefined`  | `undefined` | ✅       | ❌      | ❌      |
| `undefined`  | `true`      | ✅       | ❌      | ❌      |
| `undefined`  | `false`     | ✅       | ❌      | ❌      |
| Lax          | `undefined` | ❌       | ❌      | ❌      |
| Lax          | `true`      | ❌       | ❌      | ❌      |
| Lax          | `false`     | ❌       | ❌      | ❌      |
| Strict       | `undefined` | ❌       | ❌      | ❌      |
| Strict       | `true`      | ❌       | ❌      | ❌      |
| Strict       | `false`     | ❌       | ❌      | ❌      |
| None         | `undefined` | ❌       | ❌      | ❌      |
| None         | `true`      | ✅       | ✅      | ❌      |
| None         | `false`     | ✅       | ✅      | ❌      |

## 总结

HTTP 下，非 Iframe、Iframe 不跨域、Iframe 跨子域（跨全域都不行）成功的测试用例：

| SameSite     | Secure      | Firefox | Chrome | Safari |
|--------------|-------------|---------|--------|--------|
| `undefined`  | `undefined` | ✅       | ✅      | ✅      |
| Lax          | `undefined` | ✅       | ✅      | ✅      |
| Strict       | `undefined` | ✅       | ✅      | ✅      |

HTTPS 下，非 Iframe、Iframe 不跨域、Iframe 跨子域、Iframe 跨全域（Safari 都不行）成功的测试用例：

| SameSite     | Secure      | Firefox | Chrome | Safari |
|--------------|-------------|---------|--------|--------|
| None         | `true`      | ✅       | ✅      | ✅      |
| None         | `false`     | ✅       | ✅      | ✅      |

默认逻辑：

1. 若 HTTP，则 `SameSite` 和 `secure` 不设置
2. 若 HTTPS，则 `sameSite=None; secure=true`（前提是使用者不设置 `sameSite` 和 `secure`）

---
_Source: https://npm.io/package/@alicloud/cookie · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._