import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/en/functional-basic/Classes/Cookie - Cookie Management'/>

# Cookie Class

A seamless wrapper for managing browser cookies. Automatically syncs between memory and the `document.cookie` DOM API, allowing reactive setting, retrieval, and deletion of cookies while ensuring consistent fallback values.

Includes tight integration with `CookieStorage` for low-level management and respects global blocking via `CookieBlock`.

## Key Features

- **Memory Sync** — maintains an in-memory record of cookies to prevent unnecessary DOM traversals
- **Environment Aware** — detects if running in a DOM environment. In SSR or testing, elegantly degrades to memory-only storage
- **Global Blocking Control** — integrates securely with `CookieBlock`. If cookie writing is globally disabled, the class respects this and suspends all DOM changes
- **Default/Fallback Logic** — getting a value can lazily initialize it with a default if it doesn't already exist

## Constructor

A `Cookie` instance can be created to manage a specific cookie. If an instance with the same name already exists, it will be returned.

**Parameters:**
- `name: string` — the cookie name to manage

## Methods

### Action

#### `get`

Reads the cookie value. If the value doesn't exist and a default is provided, it will be saved and returned. Supports functions for lazy default value computation.

**Parameters:**
- `defaultValue?: T | string | (() => T | string)` — default value or function returning the value
- `options?: CookieOptions` — cookie options (used when setting default value)

**Returns:** `T | string | undefined` — the cookie value or the assigned default

#### `set`

Stores or updates a cookie value with specified options. Supports functions for dynamic value computation. If blocking is active via `CookieBlock`, the value is stored in memory only.

**Parameters:**
- `value?: T | string | (() => T | string)` — the value to store or a function returning the value
- `options?: CookieOptions` — cookie options (lifetime, SameSite, additional arguments)

**Returns:** `void`

#### `remove`

Removes a cookie by overwriting it with an empty string and setting Max-Age to `-1`, instructing the browser to instantly delete the record.

**Returns:** `void`

### Static Methods

- `getInstance<T>(name: string): Cookie<T>` — Returns an existing instance or creates a new one by name

### Auxiliary

- `CookieStorage.update()` — Updates data from `document.cookie`

## Types

### `CookieOptions`

Configuration object for cookie parameters:

- `age?: number` — lifetime in seconds (Max-Age attribute). Default: 7 days (604800 sec)
- `sameSite?: 'strict' | 'lax'` — SameSite policy. Default: `'strict'`
- `arguments?: string[]` — additional directives appended to the cookie string

## Examples

### Basic Usage

```typescript
import { Cookie } from '@dxtmisha/functional'

// Create instance to manage 'theme' cookie
const themeCookie = new Cookie('theme')

// Read with default value
const currentTheme = themeCookie.get('dark')

// Set value
themeCookie.set('light')

// Set with options
themeCookie.set('dark', {
  age: 60 * 60 * 24 * 30, // 30 days
  sameSite: 'lax'
})

// Remove
themeCookie.remove()
```

### Using getInstance

```typescript
import { Cookie } from '@dxtmisha/functional'

// Get or create instance
const cookie = Cookie.getInstance<string>('user')

// All getInstance calls with the same name return the same instance
const sameCookie = Cookie.getInstance<string>('user')

console.log(cookie === sameCookie) // true
```

### CookieBlock Integration

```typescript
import { Cookie, CookieBlock } from '@dxtmisha/functional'

// Block all write operations
CookieBlock.set(true)

const cookie = new Cookie('blocked')

// Value is saved in memory, but not in DOM
cookie.set('value')

// Unblock
CookieBlock.set(false)

// Now writes work normally
cookie.set('newValue')
```
