@usefy/use-cookie 0.19.0

package/README.md

@@ -0,0 +1,182 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mirunamu00/usefy/master/assets/logo.png" alt="usefy logo" width="120" />
+</p>
+
+<h1 align="center">@usefy/use-cookie</h1>
+
+<p align="center">
+  <strong>Read and write a browser cookie as React state — SSR-aware, JSON-friendly, with full cookie attribute support</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@usefy/use-cookie"><img src="https://img.shields.io/npm/v/@usefy/use-cookie.svg?style=flat-square&color=007acc" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@usefy/use-cookie"><img src="https://img.shields.io/npm/dm/@usefy/use-cookie.svg?style=flat-square&color=007acc" alt="npm downloads" /></a>
+  <a href="https://bundlephobia.com/package/@usefy/use-cookie"><img src="https://img.shields.io/bundlephobia/minzip/@usefy/use-cookie?style=flat-square&color=007acc" alt="bundle size" /></a>
+  <a href="https://github.com/mirunamu00/usefy/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/@usefy/use-cookie.svg?style=flat-square&color=007acc" alt="license" /></a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#api">API</a> •
+  <a href="#testing">Testing</a> •
+  <a href="#license">License</a>
+</p>
+
+<p align="center">
+  <a href="https://mirunamu00.github.io/usefy/?path=/docs/hooks-usecookie--docs" target="_blank" rel="noopener noreferrer">
+    <strong>📚 View Storybook Demo</strong>
+  </a>
+</p>
+
+---
+
+## Overview
+
+`useCookie` is part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem — a collection of production-ready, TypeScript-first, SSR-safe React hooks. It reads and writes a browser cookie with a `useState`-like API, and completes the storage trio alongside [`@usefy/use-local-storage`](https://www.npmjs.com/package/@usefy/use-local-storage) and [`@usefy/use-session-storage`](https://www.npmjs.com/package/@usefy/use-session-storage) — the three feel like siblings.
+
+## Features
+
+- **`useState`-like tuple** — `[value, setValue, remove]`, with a functional updater `(prev) => next`
+- **Full cookie attributes** — `expires` (Date or days), `maxAge` (seconds), `path`, `domain`, `secure`, `sameSite`
+- **Safe (de)serialization** — JSON by default, with a graceful fallback to the raw string so plain (non-JSON) cookies never throw
+- **SSR-safe** — guards all `document` access and returns `initialValue` on the server (built on `useSyncExternalStore`, exactly like its storage siblings, to avoid hydration mismatches)
+- **Same-document sync** — multiple `useCookie(key)` instances stay in sync when any of them writes or removes
+- **Stable references** — `setValue` and `remove` are memoized
+- **TypeScript-first** — full type inference and exported types
+- **Tiny & tree-shakeable** — zero dependencies, published as its own package
+
+## Installation
+
+```bash
+# npm
+npm install @usefy/use-cookie
+
+# yarn
+yarn add @usefy/use-cookie
+
+# pnpm
+pnpm add @usefy/use-cookie
+```
+
+Requires React 18 or 19 (`peerDependencies: "react": "^18.0.0 || ^19.0.0"`).
+
+## Quick Start
+
+```tsx
+import { useCookie } from "@usefy/use-cookie";
+
+function ThemeToggle() {
+  const [theme, setTheme, removeTheme] = useCookie("theme", {
+    initialValue: "light",
+  });
+
+  return (
+    <div>
+      <p>Current theme: {theme}</p>
+      <button onClick={() => setTheme("dark")}>Dark</button>
+      <button onClick={removeTheme}>Reset</button>
+    </div>
+  );
+}
+```
+
+## API
+
+### `useCookie<T>(key, options?)`
+
+Reads and writes the cookie named `key`, returning a `[value, setValue, remove]` tuple.
+
+#### Parameters
+
+| Parameter | Type                  | Description               |
+| --------- | --------------------- | ------------------------- |
+| `key`     | `string`              | The cookie name           |
+| `options` | `UseCookieOptions<T>` | Configuration (see below) |
+
+#### Options
+
+| Option         | Type                     | Default          | Description                                                              |
+| -------------- | ------------------------ | ---------------- | ----------------------------------------------------------------------- |
+| `initialValue` | `T \| (() => T)`         | `undefined`      | Value when the cookie is absent (and on the server); also the reset target for `remove()`. Supports a lazy initializer. |
+| `serializer`   | `(value: T) => string`   | `JSON.stringify` | Convert the value to the stored cookie string                           |
+| `deserializer` | `(value: string) => T`   | JSON-or-raw\*    | Parse the stored cookie string back to a value                          |
+| `onError`      | `(error: Error) => void` | —                | Called on a serialization/deserialization error                         |
+| `expires`      | `Date \| number`         | —                | Absolute `Date`, or a number of **days** from now. Omit for a session cookie. |
+| `maxAge`       | `number`                 | —                | `Max-Age` in **seconds**. Use `0`/negative to expire immediately.       |
+| `path`         | `string`                 | `"/"`            | Path the cookie is scoped to                                            |
+| `domain`       | `string`                 | —                | Domain the cookie is scoped to (e.g. `.example.com`)                    |
+| `secure`       | `boolean`                | —                | Send the cookie over HTTPS only                                         |
+| `sameSite`     | `'strict' \| 'lax' \| 'none'` | —           | `SameSite` policy. `'none'` requires `secure: true`.                    |
+
+\* **Default deserialization:** the value is written with `JSON.stringify` and read with `JSON.parse`. Because cookies are very often plain, non-JSON strings (set by a server or another library), the default deserializer **falls back to the raw string** when `JSON.parse` throws — so `foo=bar` reads back as `"bar"` and never crashes, while `'{"a":1}'` reads back as `{ a: 1 }`.
+
+#### Returns `[T | undefined, SetValue, Remove]`
+
+| Index | Type                                            | Description                                                    |
+| ----- | ----------------------------------------------- | ------------------------------------------------------------- |
+| `[0]` | `T \| undefined`                                | Current value (`undefined` when absent and no `initialValue`) |
+| `[1]` | `Dispatch<SetStateAction<T \| undefined>>`      | Set the cookie; accepts a value or `(prev) => next`           |
+| `[2]` | `() => void`                                    | Delete the cookie and reset state to `initialValue`           |
+
+### SSR / hydration
+
+On the server there is no `document`, so `useCookie` returns `initialValue`. Like `@usefy/use-local-storage`, it reads through `useSyncExternalStore` with a server snapshot, so the first client render is consistent and there is no hydration mismatch.
+
+### Cross-tab limitation
+
+Cookies have **no `storage` event**, so writes made in *other* browser tabs cannot be observed without polling — `useCookie` does not fake this. It does keep every `useCookie(key)` instance **within the same document** in sync via an internal subscription (mirroring `@usefy/use-local-storage`'s same-tab store). If you need cross-tab reactivity for a cookie, poll `document.cookie` yourself or store the value in `localStorage` instead.
+
+## Examples
+
+### Cookie attributes
+
+```tsx
+import { useCookie } from "@usefy/use-cookie";
+
+// A secure, same-site session token that expires in a week.
+const [token, setToken, clearToken] = useCookie<string>("token", {
+  expires: 7, // days (a Date also works)
+  path: "/",
+  secure: true,
+  sameSite: "strict",
+});
+```
+
+### Object value (JSON)
+
+```tsx
+import { useCookie } from "@usefy/use-cookie";
+
+interface Prefs {
+  lang: string;
+  compact: boolean;
+}
+
+const [prefs, setPrefs] = useCookie<Prefs>("prefs", {
+  initialValue: { lang: "en", compact: false },
+  maxAge: 60 * 60 * 24 * 30, // 30 days
+});
+
+setPrefs((prev) => ({ ...prev!, compact: true }));
+```
+
+### Reading a plain server-set cookie
+
+```tsx
+import { useCookie } from "@usefy/use-cookie";
+
+// Cookie set by the backend as `consent=accepted` (not JSON) — reads back as
+// the raw string, no throw.
+const [consent] = useCookie<string>("consent");
+```
+
+## Testing
+
+📊 <a href="https://mirunamu00.github.io/usefy/coverage/use-cookie/src/index.html" target="_blank" rel="noopener noreferrer"><strong>View Detailed Coverage Report</strong></a> (GitHub Pages) — **47 tests**, 96% statement coverage.
+
+## License
+
+MIT © [mirunamu](https://github.com/mirunamu00)
+
+This package is part of the [usefy](https://github.com/mirunamu00/usefy) monorepo.

package/dist/index.d.mts

@@ -0,0 +1,174 @@
+/**
+ * Pure, framework-agnostic helpers for reading and writing `document.cookie`.
+ * These are unit-tested in isolation and used by {@link useCookie}.
+ */
+/**
+ * The `SameSite` cookie attribute values.
+ *
+ * - `"strict"` — cookie is sent only for same-site requests.
+ * - `"lax"` — cookie is sent on same-site requests and top-level navigations.
+ * - `"none"` — cookie is sent on all requests; **requires `secure: true`**.
+ */
+type SameSite = "strict" | "lax" | "none";
+/**
+ * Cookie write attributes, mirroring the standard `Set-Cookie` directives.
+ * These control how the cookie is persisted by the browser.
+ */
+interface CookieAttributes {
+    /**
+     * Expiry of the cookie. Either an absolute `Date`, or a number of **days**
+     * from now (e.g. `7` = expires in a week). Omit for a session cookie.
+     */
+    expires?: Date | number;
+    /**
+     * `Max-Age` in **seconds** from now. Takes precedence over `expires` in
+     * browsers that support it. Use `0` or a negative number to expire immediately.
+     */
+    maxAge?: number;
+    /**
+     * The URL path the cookie is scoped to.
+     * @default "/"
+     */
+    path?: string;
+    /** The domain the cookie is scoped to (e.g. `.example.com`). */
+    domain?: string;
+    /** When `true`, the cookie is only sent over HTTPS. */
+    secure?: boolean;
+    /** The `SameSite` policy. `"none"` requires `secure: true`. */
+    sameSite?: SameSite;
+}
+/**
+ * Parse a raw `document.cookie` string and return the **decoded** value for
+ * `key`, or `undefined` when the key is absent. Pure — does not touch
+ * `document`, so it is trivially testable.
+ *
+ * @param cookieString - The raw `document.cookie` value (e.g. `"a=1; b=2"`).
+ * @param key - The (un-encoded) cookie name to look up.
+ */
+declare function parseCookie(cookieString: string, key: string): string | undefined;
+/**
+ * Build a `document.cookie` assignment string for a cookie, encoding the name
+ * and value and appending the standard attributes. Pure and testable.
+ *
+ * @example
+ * buildCookieString("theme", "dark", { path: "/", maxAge: 3600 })
+ * // => "theme=dark; Path=/; Max-Age=3600"
+ */
+declare function buildCookieString(name: string, value: string, attributes?: CookieAttributes): string;
+/**
+ * Build the `document.cookie` assignment string that **deletes** a cookie. The
+ * value is emptied and the cookie is expired in the past (`Max-Age=-1` plus an
+ * epoch `Expires`). The same `path`/`domain` used to write it must be provided,
+ * otherwise the browser treats it as a different cookie and deletion is a no-op.
+ */
+declare function buildRemovalCookieString(name: string, attributes?: Pick<CookieAttributes, "path" | "domain">): string;
+
+/**
+ * Type for the initial value that can be a value or a function returning a value
+ * (lazy initialization).
+ */
+type InitialValue<T> = T | (() => T);
+/**
+ * Options for the {@link useCookie} hook. Combines serialization/lifecycle
+ * options (aligned with `@usefy/use-local-storage`) with the cookie-specific
+ * write attributes from {@link CookieAttributes}.
+ */
+interface UseCookieOptions<T> extends CookieAttributes {
+    /**
+     * Initial value used when the cookie is absent (or on the server). Supports a
+     * lazy initializer function. This is also the value the state resets to when
+     * {@link UseCookieReturn} `remove()` is called.
+     */
+    initialValue?: InitialValue<T>;
+    /**
+     * Custom serializer for converting the value to the stored cookie string.
+     * @default JSON.stringify
+     */
+    serializer?: (value: T) => string;
+    /**
+     * Custom deserializer for parsing the stored cookie string back to a value.
+     * The default tries `JSON.parse` and **falls back to the raw string** for
+     * non-JSON cookies (so a plain `foo=bar` cookie never throws).
+     * @default (value) => { try { return JSON.parse(value) } catch { return value } }
+     */
+    deserializer?: (value: string) => T;
+    /** Callback invoked when a serialization/deserialization error occurs. */
+    onError?: (error: Error) => void;
+}
+/**
+ * Return type for {@link useCookie} — a tuple similar to `useState`.
+ */
+type UseCookieReturn<T> = readonly [
+    /** Current cookie value (`undefined` when the cookie is absent and no `initialValue` was given). */
+    T | undefined,
+    /** Update the cookie value. Accepts a value or a functional updater `(prev) => next`. */
+    React.Dispatch<React.SetStateAction<T | undefined>>,
+    /** Delete the cookie and reset state to `initialValue` (or `undefined`). */
+    () => void
+];
+/**
+ * A hook for reading and writing a browser **cookie** as React state — the
+ * cookie sibling of `@usefy/use-local-storage` and `@usefy/use-session-storage`.
+ * Works like `useState` but the value is persisted in `document.cookie`.
+ *
+ * Features:
+ * - **`useState`-like tuple**: `[value, setValue, remove]`.
+ * - **Same-document sync**: multiple `useCookie(key)` instances stay in sync.
+ * - **SSR-safe**: guards all `document` access and returns `initialValue` on the
+ *   server (uses `useSyncExternalStore`, identical to its storage siblings, to
+ *   avoid hydration mismatches).
+ * - **Cookie attributes**: `expires`, `maxAge`, `path`, `domain`, `secure`,
+ *   `sameSite`.
+ * - **Safe (de)serialization**: JSON by default, with a graceful fallback to the
+ *   raw string for plain (non-JSON) cookies.
+ *
+ * > **Cross-tab note:** cookies have no `storage` event, so writes in *other*
+ * > tabs are not observed without polling. Same-document instances always sync.
+ *
+ * @template T - The type of the stored value
+ * @param key - The cookie name
+ * @param options - Serialization, initial value, and cookie write attributes
+ * @returns A tuple of `[value, setValue, remove]`
+ *
+ * @example
+ * ```tsx
+ * // Basic usage — a string cookie
+ * function ThemeToggle() {
+ *   const [theme, setTheme, removeTheme] = useCookie("theme", {
+ *     initialValue: "light",
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <p>Current theme: {theme}</p>
+ *       <button onClick={() => setTheme("dark")}>Dark</button>
+ *       <button onClick={removeTheme}>Reset</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With cookie attributes — persist for a week over HTTPS only
+ * const [token, setToken] = useCookie<string>("token", {
+ *   expires: 7, // days (or a Date)
+ *   path: "/",
+ *   secure: true,
+ *   sameSite: "strict",
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Object value with a functional update (JSON serialized)
+ * interface Prefs { lang: string; compact: boolean }
+ * const [prefs, setPrefs] = useCookie<Prefs>("prefs", {
+ *   initialValue: { lang: "en", compact: false },
+ * });
+ * setPrefs((prev) => ({ ...prev!, compact: true }));
+ * ```
+ */
+declare function useCookie<T = string>(key: string, options?: UseCookieOptions<T>): UseCookieReturn<T>;
+
+export { type CookieAttributes, type InitialValue, type SameSite, type UseCookieOptions, type UseCookieReturn, buildCookieString, buildRemovalCookieString, parseCookie, useCookie };

package/dist/index.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Pure, framework-agnostic helpers for reading and writing `document.cookie`.
+ * These are unit-tested in isolation and used by {@link useCookie}.
+ */
+/**
+ * The `SameSite` cookie attribute values.
+ *
+ * - `"strict"` — cookie is sent only for same-site requests.
+ * - `"lax"` — cookie is sent on same-site requests and top-level navigations.
+ * - `"none"` — cookie is sent on all requests; **requires `secure: true`**.
+ */
+type SameSite = "strict" | "lax" | "none";
+/**
+ * Cookie write attributes, mirroring the standard `Set-Cookie` directives.
+ * These control how the cookie is persisted by the browser.
+ */
+interface CookieAttributes {
+    /**
+     * Expiry of the cookie. Either an absolute `Date`, or a number of **days**
+     * from now (e.g. `7` = expires in a week). Omit for a session cookie.
+     */
+    expires?: Date | number;
+    /**
+     * `Max-Age` in **seconds** from now. Takes precedence over `expires` in
+     * browsers that support it. Use `0` or a negative number to expire immediately.
+     */
+    maxAge?: number;
+    /**
+     * The URL path the cookie is scoped to.
+     * @default "/"
+     */
+    path?: string;
+    /** The domain the cookie is scoped to (e.g. `.example.com`). */
+    domain?: string;
+    /** When `true`, the cookie is only sent over HTTPS. */
+    secure?: boolean;
+    /** The `SameSite` policy. `"none"` requires `secure: true`. */
+    sameSite?: SameSite;
+}
+/**
+ * Parse a raw `document.cookie` string and return the **decoded** value for
+ * `key`, or `undefined` when the key is absent. Pure — does not touch
+ * `document`, so it is trivially testable.
+ *
+ * @param cookieString - The raw `document.cookie` value (e.g. `"a=1; b=2"`).
+ * @param key - The (un-encoded) cookie name to look up.
+ */
+declare function parseCookie(cookieString: string, key: string): string | undefined;
+/**
+ * Build a `document.cookie` assignment string for a cookie, encoding the name
+ * and value and appending the standard attributes. Pure and testable.
+ *
+ * @example
+ * buildCookieString("theme", "dark", { path: "/", maxAge: 3600 })
+ * // => "theme=dark; Path=/; Max-Age=3600"
+ */
+declare function buildCookieString(name: string, value: string, attributes?: CookieAttributes): string;
+/**
+ * Build the `document.cookie` assignment string that **deletes** a cookie. The
+ * value is emptied and the cookie is expired in the past (`Max-Age=-1` plus an
+ * epoch `Expires`). The same `path`/`domain` used to write it must be provided,
+ * otherwise the browser treats it as a different cookie and deletion is a no-op.
+ */
+declare function buildRemovalCookieString(name: string, attributes?: Pick<CookieAttributes, "path" | "domain">): string;
+
+/**
+ * Type for the initial value that can be a value or a function returning a value
+ * (lazy initialization).
+ */
+type InitialValue<T> = T | (() => T);
+/**
+ * Options for the {@link useCookie} hook. Combines serialization/lifecycle
+ * options (aligned with `@usefy/use-local-storage`) with the cookie-specific
+ * write attributes from {@link CookieAttributes}.
+ */
+interface UseCookieOptions<T> extends CookieAttributes {
+    /**
+     * Initial value used when the cookie is absent (or on the server). Supports a
+     * lazy initializer function. This is also the value the state resets to when
+     * {@link UseCookieReturn} `remove()` is called.
+     */
+    initialValue?: InitialValue<T>;
+    /**
+     * Custom serializer for converting the value to the stored cookie string.
+     * @default JSON.stringify
+     */
+    serializer?: (value: T) => string;
+    /**
+     * Custom deserializer for parsing the stored cookie string back to a value.
+     * The default tries `JSON.parse` and **falls back to the raw string** for
+     * non-JSON cookies (so a plain `foo=bar` cookie never throws).
+     * @default (value) => { try { return JSON.parse(value) } catch { return value } }
+     */
+    deserializer?: (value: string) => T;
+    /** Callback invoked when a serialization/deserialization error occurs. */
+    onError?: (error: Error) => void;
+}
+/**
+ * Return type for {@link useCookie} — a tuple similar to `useState`.
+ */
+type UseCookieReturn<T> = readonly [
+    /** Current cookie value (`undefined` when the cookie is absent and no `initialValue` was given). */
+    T | undefined,
+    /** Update the cookie value. Accepts a value or a functional updater `(prev) => next`. */
+    React.Dispatch<React.SetStateAction<T | undefined>>,
+    /** Delete the cookie and reset state to `initialValue` (or `undefined`). */
+    () => void
+];
+/**
+ * A hook for reading and writing a browser **cookie** as React state — the
+ * cookie sibling of `@usefy/use-local-storage` and `@usefy/use-session-storage`.
+ * Works like `useState` but the value is persisted in `document.cookie`.
+ *
+ * Features:
+ * - **`useState`-like tuple**: `[value, setValue, remove]`.
+ * - **Same-document sync**: multiple `useCookie(key)` instances stay in sync.
+ * - **SSR-safe**: guards all `document` access and returns `initialValue` on the
+ *   server (uses `useSyncExternalStore`, identical to its storage siblings, to
+ *   avoid hydration mismatches).
+ * - **Cookie attributes**: `expires`, `maxAge`, `path`, `domain`, `secure`,
+ *   `sameSite`.
+ * - **Safe (de)serialization**: JSON by default, with a graceful fallback to the
+ *   raw string for plain (non-JSON) cookies.
+ *
+ * > **Cross-tab note:** cookies have no `storage` event, so writes in *other*
+ * > tabs are not observed without polling. Same-document instances always sync.
+ *
+ * @template T - The type of the stored value
+ * @param key - The cookie name
+ * @param options - Serialization, initial value, and cookie write attributes
+ * @returns A tuple of `[value, setValue, remove]`
+ *
+ * @example
+ * ```tsx
+ * // Basic usage — a string cookie
+ * function ThemeToggle() {
+ *   const [theme, setTheme, removeTheme] = useCookie("theme", {
+ *     initialValue: "light",
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <p>Current theme: {theme}</p>
+ *       <button onClick={() => setTheme("dark")}>Dark</button>
+ *       <button onClick={removeTheme}>Reset</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With cookie attributes — persist for a week over HTTPS only
+ * const [token, setToken] = useCookie<string>("token", {
+ *   expires: 7, // days (or a Date)
+ *   path: "/",
+ *   secure: true,
+ *   sameSite: "strict",
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Object value with a functional update (JSON serialized)
+ * interface Prefs { lang: string; compact: boolean }
+ * const [prefs, setPrefs] = useCookie<Prefs>("prefs", {
+ *   initialValue: { lang: "en", compact: false },
+ * });
+ * setPrefs((prev) => ({ ...prev!, compact: true }));
+ * ```
+ */
+declare function useCookie<T = string>(key: string, options?: UseCookieOptions<T>): UseCookieReturn<T>;
+
+export { type CookieAttributes, type InitialValue, type SameSite, type UseCookieOptions, type UseCookieReturn, buildCookieString, buildRemovalCookieString, parseCookie, useCookie };

package/dist/index.js

@@ -0,0 +1,252 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  buildCookieString: () => buildCookieString,
+  buildRemovalCookieString: () => buildRemovalCookieString,
+  parseCookie: () => parseCookie,
+  useCookie: () => useCookie
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useCookie.ts
+var import_react = require("react");
+
+// src/store.ts
+var listeners = /* @__PURE__ */ new Map();
+function subscribe(key, listener) {
+  if (!listeners.has(key)) {
+    listeners.set(key, /* @__PURE__ */ new Set());
+  }
+  const keyListeners = listeners.get(key);
+  keyListeners.add(listener);
+  return () => {
+    keyListeners.delete(listener);
+    if (keyListeners.size === 0) {
+      listeners.delete(key);
+    }
+  };
+}
+function notifyListeners(key) {
+  const keyListeners = listeners.get(key);
+  if (keyListeners) {
+    keyListeners.forEach((listener) => listener());
+  }
+}
+
+// src/utils.ts
+function isDocumentAvailable() {
+  return typeof document !== "undefined";
+}
+function capitalizeSameSite(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+function defaultSerializer(value) {
+  return JSON.stringify(value);
+}
+function defaultDeserializer(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+function parseCookie(cookieString, key) {
+  if (!cookieString) return void 0;
+  const pairs = cookieString.split("; ");
+  for (const pair of pairs) {
+    const eqIndex = pair.indexOf("=");
+    const rawName = eqIndex > -1 ? pair.slice(0, eqIndex) : pair;
+    let name;
+    try {
+      name = decodeURIComponent(rawName);
+    } catch {
+      name = rawName;
+    }
+    if (name === key) {
+      const rawValue = eqIndex > -1 ? pair.slice(eqIndex + 1) : "";
+      try {
+        return decodeURIComponent(rawValue);
+      } catch {
+        return rawValue;
+      }
+    }
+  }
+  return void 0;
+}
+function readRawCookie(key) {
+  if (!isDocumentAvailable()) return void 0;
+  return parseCookie(document.cookie, key);
+}
+function buildCookieString(name, value, attributes = {}) {
+  const { expires, maxAge, path = "/", domain, secure, sameSite } = attributes;
+  let str = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
+  if (expires !== void 0) {
+    const date = typeof expires === "number" ? new Date(Date.now() + expires * 864e5) : expires;
+    str += `; Expires=${date.toUTCString()}`;
+  }
+  if (maxAge !== void 0) {
+    str += `; Max-Age=${maxAge}`;
+  }
+  if (path) {
+    str += `; Path=${path}`;
+  }
+  if (domain) {
+    str += `; Domain=${domain}`;
+  }
+  if (secure) {
+    str += "; Secure";
+  }
+  if (sameSite) {
+    str += `; SameSite=${capitalizeSameSite(sameSite)}`;
+  }
+  return str;
+}
+function buildRemovalCookieString(name, attributes = {}) {
+  const { path = "/", domain } = attributes;
+  let str = `${encodeURIComponent(name)}=; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Max-Age=-1`;
+  if (path) {
+    str += `; Path=${path}`;
+  }
+  if (domain) {
+    str += `; Domain=${domain}`;
+  }
+  return str;
+}
+
+// src/useCookie.ts
+function resolveInitialValue(initialValue) {
+  return typeof initialValue === "function" ? initialValue() : initialValue;
+}
+function useCookie(key, options = {}) {
+  const {
+    initialValue,
+    serializer = defaultSerializer,
+    deserializer = defaultDeserializer,
+    onError,
+    expires,
+    maxAge,
+    path,
+    domain,
+    secure,
+    sameSite
+  } = options;
+  const serializerRef = (0, import_react.useRef)(serializer);
+  const deserializerRef = (0, import_react.useRef)(deserializer);
+  const onErrorRef = (0, import_react.useRef)(onError);
+  const initialValueRef = (0, import_react.useRef)(initialValue);
+  serializerRef.current = serializer;
+  deserializerRef.current = deserializer;
+  onErrorRef.current = onError;
+  initialValueRef.current = initialValue;
+  const attributesRef = (0, import_react.useRef)({});
+  attributesRef.current = { expires, maxAge, path, domain, secure, sameSite };
+  const cacheRef = (0, import_react.useRef)(null);
+  const isClient = isDocumentAvailable();
+  const subscribeToStore = (0, import_react.useCallback)(
+    (onStoreChange) => {
+      return subscribe(key, onStoreChange);
+    },
+    [key]
+  );
+  const getSnapshot = (0, import_react.useCallback)(() => {
+    if (!isClient) {
+      return resolveInitialValue(initialValueRef.current);
+    }
+    try {
+      const rawValue = readRawCookie(key);
+      if (cacheRef.current && cacheRef.current.rawValue === rawValue) {
+        return cacheRef.current.parsedValue;
+      }
+      let parsedValue;
+      if (rawValue !== void 0) {
+        parsedValue = deserializerRef.current(rawValue);
+      } else {
+        parsedValue = resolveInitialValue(initialValueRef.current);
+      }
+      cacheRef.current = { rawValue, parsedValue };
+      return parsedValue;
+    } catch (error) {
+      onErrorRef.current?.(error);
+      const fallbackValue = resolveInitialValue(initialValueRef.current);
+      cacheRef.current = { rawValue: void 0, parsedValue: fallbackValue };
+      return fallbackValue;
+    }
+  }, [key, isClient]);
+  const getServerSnapshot = (0, import_react.useCallback)(() => {
+    return resolveInitialValue(initialValueRef.current);
+  }, []);
+  const storedValue = (0, import_react.useSyncExternalStore)(
+    subscribeToStore,
+    getSnapshot,
+    getServerSnapshot
+  );
+  const setValue = (0, import_react.useCallback)(
+    (value) => {
+      try {
+        if (!isDocumentAvailable()) return;
+        const currentValue = (() => {
+          try {
+            const raw = readRawCookie(key);
+            if (raw !== void 0) {
+              return deserializerRef.current(raw);
+            }
+            return resolveInitialValue(initialValueRef.current);
+          } catch {
+            return resolveInitialValue(initialValueRef.current);
+          }
+        })();
+        const valueToStore = value instanceof Function ? value(currentValue) : value;
+        const serialized = serializerRef.current(valueToStore);
+        document.cookie = buildCookieString(
+          key,
+          serialized,
+          attributesRef.current
+        );
+        cacheRef.current = { rawValue: serialized, parsedValue: valueToStore };
+        notifyListeners(key);
+      } catch (error) {
+        onErrorRef.current?.(error);
+      }
+    },
+    [key]
+  );
+  const removeValue = (0, import_react.useCallback)(() => {
+    try {
+      if (!isDocumentAvailable()) return;
+      document.cookie = buildRemovalCookieString(key, attributesRef.current);
+      const initialVal = resolveInitialValue(initialValueRef.current);
+      cacheRef.current = { rawValue: void 0, parsedValue: initialVal };
+      notifyListeners(key);
+    } catch (error) {
+      onErrorRef.current?.(error);
+    }
+  }, [key]);
+  return [storedValue, setValue, removeValue];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildCookieString,
+  buildRemovalCookieString,
+  parseCookie,
+  useCookie
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/useCookie.ts","../src/store.ts","../src/utils.ts"],"sourcesContent":["export {\n  useCookie,\n  type UseCookieOptions,\n  type UseCookieReturn,\n  type InitialValue,\n  type CookieAttributes,\n  type SameSite,\n} from \"./useCookie\";\n\nexport {\n  buildCookieString,\n  buildRemovalCookieString,\n  parseCookie,\n} from \"./utils\";\n","import { useCallback, useRef, useSyncExternalStore } from \"react\";\nimport { subscribe, notifyListeners } from \"./store\";\nimport {\n  buildCookieString,\n  buildRemovalCookieString,\n  defaultDeserializer,\n  defaultSerializer,\n  isDocumentAvailable,\n  readRawCookie,\n  type CookieAttributes,\n} from \"./utils\";\n\nexport type { CookieAttributes, SameSite } from \"./utils\";\n\n/**\n * Type for the initial value that can be a value or a function returning a value\n * (lazy initialization).\n */\nexport type InitialValue<T> = T | (() => T);\n\n/**\n * Options for the {@link useCookie} hook. Combines serialization/lifecycle\n * options (aligned with `@usefy/use-local-storage`) with the cookie-specific\n * write attributes from {@link CookieAttributes}.\n */\nexport interface UseCookieOptions<T> extends CookieAttributes {\n  /**\n   * Initial value used when the cookie is absent (or on the server). Supports a\n   * lazy initializer function. This is also the value the state resets to when\n   * {@link UseCookieReturn} `remove()` is called.\n   */\n  initialValue?: InitialValue<T>;\n  /**\n   * Custom serializer for converting the value to the stored cookie string.\n   * @default JSON.stringify\n   */\n  serializer?: (value: T) => string;\n  /**\n   * Custom deserializer for parsing the stored cookie string back to a value.\n   * The default tries `JSON.parse` and **falls back to the raw string** for\n   * non-JSON cookies (so a plain `foo=bar` cookie never throws).\n   * @default (value) => { try { return JSON.parse(value) } catch { return value } }\n   */\n  deserializer?: (value: string) => T;\n  /** Callback invoked when a serialization/deserialization error occurs. */\n  onError?: (error: Error) => void;\n}\n\n/**\n * Return type for {@link useCookie} — a tuple similar to `useState`.\n */\nexport type UseCookieReturn<T> = readonly [\n  /** Current cookie value (`undefined` when the cookie is absent and no `initialValue` was given). */\n  T | undefined,\n  /** Update the cookie value. Accepts a value or a functional updater `(prev) => next`. */\n  React.Dispatch<React.SetStateAction<T | undefined>>,\n  /** Delete the cookie and reset state to `initialValue` (or `undefined`). */\n  () => void\n];\n\n/**\n * Resolve an initial value, supporting a lazy initializer function.\n */\nfunction resolveInitialValue<T>(\n  initialValue: InitialValue<T> | undefined\n): T | undefined {\n  return typeof initialValue === \"function\"\n    ? (initialValue as () => T)()\n    : initialValue;\n}\n\n/**\n * A hook for reading and writing a browser **cookie** as React state — the\n * cookie sibling of `@usefy/use-local-storage` and `@usefy/use-session-storage`.\n * Works like `useState` but the value is persisted in `document.cookie`.\n *\n * Features:\n * - **`useState`-like tuple**: `[value, setValue, remove]`.\n * - **Same-document sync**: multiple `useCookie(key)` instances stay in sync.\n * - **SSR-safe**: guards all `document` access and returns `initialValue` on the\n *   server (uses `useSyncExternalStore`, identical to its storage siblings, to\n *   avoid hydration mismatches).\n * - **Cookie attributes**: `expires`, `maxAge`, `path`, `domain`, `secure`,\n *   `sameSite`.\n * - **Safe (de)serialization**: JSON by default, with a graceful fallback to the\n *   raw string for plain (non-JSON) cookies.\n *\n * > **Cross-tab note:** cookies have no `storage` event, so writes in *other*\n * > tabs are not observed without polling. Same-document instances always sync.\n *\n * @template T - The type of the stored value\n * @param key - The cookie name\n * @param options - Serialization, initial value, and cookie write attributes\n * @returns A tuple of `[value, setValue, remove]`\n *\n * @example\n * ```tsx\n * // Basic usage — a string cookie\n * function ThemeToggle() {\n *   const [theme, setTheme, removeTheme] = useCookie(\"theme\", {\n *     initialValue: \"light\",\n *   });\n *\n *   return (\n *     <div>\n *       <p>Current theme: {theme}</p>\n *       <button onClick={() => setTheme(\"dark\")}>Dark</button>\n *       <button onClick={removeTheme}>Reset</button>\n *     </div>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // With cookie attributes — persist for a week over HTTPS only\n * const [token, setToken] = useCookie<string>(\"token\", {\n *   expires: 7, // days (or a Date)\n *   path: \"/\",\n *   secure: true,\n *   sameSite: \"strict\",\n * });\n * ```\n *\n * @example\n * ```tsx\n * // Object value with a functional update (JSON serialized)\n * interface Prefs { lang: string; compact: boolean }\n * const [prefs, setPrefs] = useCookie<Prefs>(\"prefs\", {\n *   initialValue: { lang: \"en\", compact: false },\n * });\n * setPrefs((prev) => ({ ...prev!, compact: true }));\n * ```\n */\nexport function useCookie<T = string>(\n  key: string,\n  options: UseCookieOptions<T> = {}\n): UseCookieReturn<T> {\n  const {\n    initialValue,\n    serializer = defaultSerializer,\n    deserializer = defaultDeserializer,\n    onError,\n    expires,\n    maxAge,\n    path,\n    domain,\n    secure,\n    sameSite,\n  } = options;\n\n  // Store options in refs for stable references and access to the latest values.\n  const serializerRef = useRef(serializer);\n  const deserializerRef = useRef(deserializer);\n  const onErrorRef = useRef(onError);\n  const initialValueRef = useRef(initialValue);\n\n  serializerRef.current = serializer;\n  deserializerRef.current = deserializer;\n  onErrorRef.current = onError;\n  initialValueRef.current = initialValue;\n\n  // Latest cookie write attributes, so setValue/remove stay stable across renders.\n  const attributesRef = useRef<CookieAttributes>({});\n  attributesRef.current = { expires, maxAge, path, domain, secure, sameSite };\n\n  // Cache for getSnapshot so it returns a stable reference when the raw cookie\n  // value is unchanged — required by useSyncExternalStore to avoid loops.\n  const cacheRef = useRef<{\n    rawValue: string | undefined;\n    parsedValue: T | undefined;\n  } | null>(null);\n\n  const isClient = isDocumentAvailable();\n\n  // Subscribe to same-document changes via the internal store.\n  const subscribeToStore = useCallback(\n    (onStoreChange: () => void) => {\n      return subscribe(key, onStoreChange);\n    },\n    [key]\n  );\n\n  // getSnapshot: read the current value from document.cookie with caching.\n  const getSnapshot = useCallback((): T | undefined => {\n    if (!isClient) {\n      return resolveInitialValue(initialValueRef.current);\n    }\n\n    try {\n      const rawValue = readRawCookie(key);\n\n      if (cacheRef.current && cacheRef.current.rawValue === rawValue) {\n        return cacheRef.current.parsedValue;\n      }\n\n      let parsedValue: T | undefined;\n      if (rawValue !== undefined) {\n        parsedValue = deserializerRef.current(rawValue);\n      } else {\n        parsedValue = resolveInitialValue(initialValueRef.current);\n      }\n\n      cacheRef.current = { rawValue, parsedValue };\n      return parsedValue;\n    } catch (error) {\n      onErrorRef.current?.(error as Error);\n      const fallbackValue = resolveInitialValue(initialValueRef.current);\n      cacheRef.current = { rawValue: undefined, parsedValue: fallbackValue };\n      return fallbackValue;\n    }\n  }, [key, isClient]);\n\n  // getServerSnapshot: return the initial value for SSR.\n  const getServerSnapshot = useCallback((): T | undefined => {\n    return resolveInitialValue(initialValueRef.current);\n  }, []);\n\n  const storedValue = useSyncExternalStore(\n    subscribeToStore,\n    getSnapshot,\n    getServerSnapshot\n  );\n\n  // setValue — stable reference that writes the cookie and notifies listeners.\n  const setValue = useCallback<React.Dispatch<React.SetStateAction<T | undefined>>>(\n    (value) => {\n      try {\n        if (!isDocumentAvailable()) return;\n\n        // Resolve the current value for functional updates.\n        const currentValue = (() => {\n          try {\n            const raw = readRawCookie(key);\n            if (raw !== undefined) {\n              return deserializerRef.current(raw);\n            }\n            return resolveInitialValue(initialValueRef.current);\n          } catch {\n            return resolveInitialValue(initialValueRef.current);\n          }\n        })();\n\n        const valueToStore =\n          value instanceof Function ? value(currentValue) : value;\n\n        const serialized = serializerRef.current(valueToStore as T);\n        document.cookie = buildCookieString(\n          key,\n          serialized,\n          attributesRef.current\n        );\n\n        // Invalidate cache so the next getSnapshot reads the fresh value.\n        cacheRef.current = { rawValue: serialized, parsedValue: valueToStore };\n\n        notifyListeners(key);\n      } catch (error) {\n        onErrorRef.current?.(error as Error);\n      }\n    },\n    [key]\n  );\n\n  // remove — stable reference that deletes the cookie and resets to initial.\n  const removeValue = useCallback(() => {\n    try {\n      if (!isDocumentAvailable()) return;\n\n      document.cookie = buildRemovalCookieString(key, attributesRef.current);\n\n      const initialVal = resolveInitialValue(initialValueRef.current);\n      cacheRef.current = { rawValue: undefined, parsedValue: initialVal };\n\n      notifyListeners(key);\n    } catch (error) {\n      onErrorRef.current?.(error as Error);\n    }\n  }, [key]);\n\n  return [storedValue, setValue, removeValue] as const;\n}\n","/**\n * Internal Store Manager for cookie synchronization.\n * This module manages listeners for same-document synchronization across\n * components using the same cookie key.\n *\n * Unlike `localStorage`, cookies have no native `storage` event, so there is no\n * way to observe cross-tab writes without polling. This store therefore keeps\n * every `useCookie(key)` instance **within the same document** in sync: when one\n * instance writes or removes a cookie it notifies the others. Cross-tab\n * synchronization is intentionally not attempted (see the README).\n *\n * @internal This module is not exported publicly\n */\n\n/** Map of key -> Set of listener callbacks */\nconst listeners = new Map<string, Set<() => void>>();\n\n/**\n * Subscribe a listener to changes for a specific key\n * @param key - The cookie key to subscribe to\n * @param listener - Callback to invoke when the key's value changes\n * @returns Unsubscribe function\n */\nexport function subscribe(key: string, listener: () => void): () => void {\n  if (!listeners.has(key)) {\n    listeners.set(key, new Set());\n  }\n\n  const keyListeners = listeners.get(key)!;\n  keyListeners.add(listener);\n\n  return () => {\n    keyListeners.delete(listener);\n\n    // Cleanup: remove the key entry if no more listeners\n    if (keyListeners.size === 0) {\n      listeners.delete(key);\n    }\n  };\n}\n\n/**\n * Notify all listeners subscribed to a specific key.\n * This is called when setValue or removeValue is invoked to synchronize all\n * components using the same key in the same document.\n *\n * @param key - The cookie key that was updated\n */\nexport function notifyListeners(key: string): void {\n  const keyListeners = listeners.get(key);\n  if (keyListeners) {\n    keyListeners.forEach((listener) => listener());\n  }\n}\n\n/**\n * Get the count of listeners for a key (for testing purposes)\n * @internal\n */\nexport function getListenerCount(key: string): number {\n  return listeners.get(key)?.size ?? 0;\n}\n\n/**\n * Clear all listeners (for testing purposes)\n * @internal\n */\nexport function clearAllListeners(): void {\n  listeners.clear();\n}\n","/**\n * Pure, framework-agnostic helpers for reading and writing `document.cookie`.\n * These are unit-tested in isolation and used by {@link useCookie}.\n */\n\n/**\n * The `SameSite` cookie attribute values.\n *\n * - `\"strict\"` — cookie is sent only for same-site requests.\n * - `\"lax\"` — cookie is sent on same-site requests and top-level navigations.\n * - `\"none\"` — cookie is sent on all requests; **requires `secure: true`**.\n */\nexport type SameSite = \"strict\" | \"lax\" | \"none\";\n\n/**\n * Cookie write attributes, mirroring the standard `Set-Cookie` directives.\n * These control how the cookie is persisted by the browser.\n */\nexport interface CookieAttributes {\n  /**\n   * Expiry of the cookie. Either an absolute `Date`, or a number of **days**\n   * from now (e.g. `7` = expires in a week). Omit for a session cookie.\n   */\n  expires?: Date | number;\n  /**\n   * `Max-Age` in **seconds** from now. Takes precedence over `expires` in\n   * browsers that support it. Use `0` or a negative number to expire immediately.\n   */\n  maxAge?: number;\n  /**\n   * The URL path the cookie is scoped to.\n   * @default \"/\"\n   */\n  path?: string;\n  /** The domain the cookie is scoped to (e.g. `.example.com`). */\n  domain?: string;\n  /** When `true`, the cookie is only sent over HTTPS. */\n  secure?: boolean;\n  /** The `SameSite` policy. `\"none\"` requires `secure: true`. */\n  sameSite?: SameSite;\n}\n\n/** `true` when running in an environment that exposes `document`. */\nexport function isDocumentAvailable(): boolean {\n  return typeof document !== \"undefined\";\n}\n\n/** Capitalize the first letter (e.g. `\"lax\"` → `\"Lax\"`) for the `SameSite` directive. */\nfunction capitalizeSameSite(value: SameSite): string {\n  return value.charAt(0).toUpperCase() + value.slice(1);\n}\n\n/**\n * Default serializer — JSON-encodes any value.\n * @default JSON.stringify\n */\nexport function defaultSerializer<T>(value: T): string {\n  return JSON.stringify(value);\n}\n\n/**\n * Default deserializer — tries `JSON.parse`, and **falls back to the raw\n * string** if the value is not valid JSON. Cookies are very often plain,\n * non-JSON strings (set by a server or another library), so this never throws\n * on a legacy/plain value: `\"bar\"` stays `\"bar\"`, while `'{\"a\":1}'` becomes\n * `{ a: 1 }`.\n */\nexport function defaultDeserializer<T>(value: string): T {\n  try {\n    return JSON.parse(value) as T;\n  } catch {\n    return value as unknown as T;\n  }\n}\n\n/**\n * Parse a raw `document.cookie` string and return the **decoded** value for\n * `key`, or `undefined` when the key is absent. Pure — does not touch\n * `document`, so it is trivially testable.\n *\n * @param cookieString - The raw `document.cookie` value (e.g. `\"a=1; b=2\"`).\n * @param key - The (un-encoded) cookie name to look up.\n */\nexport function parseCookie(\n  cookieString: string,\n  key: string\n): string | undefined {\n  if (!cookieString) return undefined;\n\n  const pairs = cookieString.split(\"; \");\n  for (const pair of pairs) {\n    const eqIndex = pair.indexOf(\"=\");\n    const rawName = eqIndex > -1 ? pair.slice(0, eqIndex) : pair;\n\n    let name: string;\n    try {\n      name = decodeURIComponent(rawName);\n    } catch {\n      name = rawName;\n    }\n\n    if (name === key) {\n      const rawValue = eqIndex > -1 ? pair.slice(eqIndex + 1) : \"\";\n      try {\n        return decodeURIComponent(rawValue);\n      } catch {\n        return rawValue;\n      }\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Read the decoded value of a cookie from `document.cookie`, guarding for SSR.\n * Returns `undefined` on the server or when the cookie is absent.\n */\nexport function readRawCookie(key: string): string | undefined {\n  if (!isDocumentAvailable()) return undefined;\n  return parseCookie(document.cookie, key);\n}\n\n/**\n * Build a `document.cookie` assignment string for a cookie, encoding the name\n * and value and appending the standard attributes. Pure and testable.\n *\n * @example\n * buildCookieString(\"theme\", \"dark\", { path: \"/\", maxAge: 3600 })\n * // => \"theme=dark; Path=/; Max-Age=3600\"\n */\nexport function buildCookieString(\n  name: string,\n  value: string,\n  attributes: CookieAttributes = {}\n): string {\n  const { expires, maxAge, path = \"/\", domain, secure, sameSite } = attributes;\n\n  let str = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;\n\n  if (expires !== undefined) {\n    const date =\n      typeof expires === \"number\"\n        ? new Date(Date.now() + expires * 864e5)\n        : expires;\n    str += `; Expires=${date.toUTCString()}`;\n  }\n\n  if (maxAge !== undefined) {\n    str += `; Max-Age=${maxAge}`;\n  }\n\n  if (path) {\n    str += `; Path=${path}`;\n  }\n\n  if (domain) {\n    str += `; Domain=${domain}`;\n  }\n\n  if (secure) {\n    str += \"; Secure\";\n  }\n\n  if (sameSite) {\n    str += `; SameSite=${capitalizeSameSite(sameSite)}`;\n  }\n\n  return str;\n}\n\n/**\n * Build the `document.cookie` assignment string that **deletes** a cookie. The\n * value is emptied and the cookie is expired in the past (`Max-Age=-1` plus an\n * epoch `Expires`). The same `path`/`domain` used to write it must be provided,\n * otherwise the browser treats it as a different cookie and deletion is a no-op.\n */\nexport function buildRemovalCookieString(\n  name: string,\n  attributes: Pick<CookieAttributes, \"path\" | \"domain\"> = {}\n): string {\n  const { path = \"/\", domain } = attributes;\n\n  let str = `${encodeURIComponent(name)}=; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Max-Age=-1`;\n\n  if (path) {\n    str += `; Path=${path}`;\n  }\n\n  if (domain) {\n    str += `; Domain=${domain}`;\n  }\n\n  return str;\n}\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -0,0 +1,222 @@
+// src/useCookie.ts
+import { useCallback, useRef, useSyncExternalStore } from "react";
+
+// src/store.ts
+var listeners = /* @__PURE__ */ new Map();
+function subscribe(key, listener) {
+  if (!listeners.has(key)) {
+    listeners.set(key, /* @__PURE__ */ new Set());
+  }
+  const keyListeners = listeners.get(key);
+  keyListeners.add(listener);
+  return () => {
+    keyListeners.delete(listener);
+    if (keyListeners.size === 0) {
+      listeners.delete(key);
+    }
+  };
+}
+function notifyListeners(key) {
+  const keyListeners = listeners.get(key);
+  if (keyListeners) {
+    keyListeners.forEach((listener) => listener());
+  }
+}
+
+// src/utils.ts
+function isDocumentAvailable() {
+  return typeof document !== "undefined";
+}
+function capitalizeSameSite(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+function defaultSerializer(value) {
+  return JSON.stringify(value);
+}
+function defaultDeserializer(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+function parseCookie(cookieString, key) {
+  if (!cookieString) return void 0;
+  const pairs = cookieString.split("; ");
+  for (const pair of pairs) {
+    const eqIndex = pair.indexOf("=");
+    const rawName = eqIndex > -1 ? pair.slice(0, eqIndex) : pair;
+    let name;
+    try {
+      name = decodeURIComponent(rawName);
+    } catch {
+      name = rawName;
+    }
+    if (name === key) {
+      const rawValue = eqIndex > -1 ? pair.slice(eqIndex + 1) : "";
+      try {
+        return decodeURIComponent(rawValue);
+      } catch {
+        return rawValue;
+      }
+    }
+  }
+  return void 0;
+}
+function readRawCookie(key) {
+  if (!isDocumentAvailable()) return void 0;
+  return parseCookie(document.cookie, key);
+}
+function buildCookieString(name, value, attributes = {}) {
+  const { expires, maxAge, path = "/", domain, secure, sameSite } = attributes;
+  let str = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
+  if (expires !== void 0) {
+    const date = typeof expires === "number" ? new Date(Date.now() + expires * 864e5) : expires;
+    str += `; Expires=${date.toUTCString()}`;
+  }
+  if (maxAge !== void 0) {
+    str += `; Max-Age=${maxAge}`;
+  }
+  if (path) {
+    str += `; Path=${path}`;
+  }
+  if (domain) {
+    str += `; Domain=${domain}`;
+  }
+  if (secure) {
+    str += "; Secure";
+  }
+  if (sameSite) {
+    str += `; SameSite=${capitalizeSameSite(sameSite)}`;
+  }
+  return str;
+}
+function buildRemovalCookieString(name, attributes = {}) {
+  const { path = "/", domain } = attributes;
+  let str = `${encodeURIComponent(name)}=; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Max-Age=-1`;
+  if (path) {
+    str += `; Path=${path}`;
+  }
+  if (domain) {
+    str += `; Domain=${domain}`;
+  }
+  return str;
+}
+
+// src/useCookie.ts
+function resolveInitialValue(initialValue) {
+  return typeof initialValue === "function" ? initialValue() : initialValue;
+}
+function useCookie(key, options = {}) {
+  const {
+    initialValue,
+    serializer = defaultSerializer,
+    deserializer = defaultDeserializer,
+    onError,
+    expires,
+    maxAge,
+    path,
+    domain,
+    secure,
+    sameSite
+  } = options;
+  const serializerRef = useRef(serializer);
+  const deserializerRef = useRef(deserializer);
+  const onErrorRef = useRef(onError);
+  const initialValueRef = useRef(initialValue);
+  serializerRef.current = serializer;
+  deserializerRef.current = deserializer;
+  onErrorRef.current = onError;
+  initialValueRef.current = initialValue;
+  const attributesRef = useRef({});
+  attributesRef.current = { expires, maxAge, path, domain, secure, sameSite };
+  const cacheRef = useRef(null);
+  const isClient = isDocumentAvailable();
+  const subscribeToStore = useCallback(
+    (onStoreChange) => {
+      return subscribe(key, onStoreChange);
+    },
+    [key]
+  );
+  const getSnapshot = useCallback(() => {
+    if (!isClient) {
+      return resolveInitialValue(initialValueRef.current);
+    }
+    try {
+      const rawValue = readRawCookie(key);
+      if (cacheRef.current && cacheRef.current.rawValue === rawValue) {
+        return cacheRef.current.parsedValue;
+      }
+      let parsedValue;
+      if (rawValue !== void 0) {
+        parsedValue = deserializerRef.current(rawValue);
+      } else {
+        parsedValue = resolveInitialValue(initialValueRef.current);
+      }
+      cacheRef.current = { rawValue, parsedValue };
+      return parsedValue;
+    } catch (error) {
+      onErrorRef.current?.(error);
+      const fallbackValue = resolveInitialValue(initialValueRef.current);
+      cacheRef.current = { rawValue: void 0, parsedValue: fallbackValue };
+      return fallbackValue;
+    }
+  }, [key, isClient]);
+  const getServerSnapshot = useCallback(() => {
+    return resolveInitialValue(initialValueRef.current);
+  }, []);
+  const storedValue = useSyncExternalStore(
+    subscribeToStore,
+    getSnapshot,
+    getServerSnapshot
+  );
+  const setValue = useCallback(
+    (value) => {
+      try {
+        if (!isDocumentAvailable()) return;
+        const currentValue = (() => {
+          try {
+            const raw = readRawCookie(key);
+            if (raw !== void 0) {
+              return deserializerRef.current(raw);
+            }
+            return resolveInitialValue(initialValueRef.current);
+          } catch {
+            return resolveInitialValue(initialValueRef.current);
+          }
+        })();
+        const valueToStore = value instanceof Function ? value(currentValue) : value;
+        const serialized = serializerRef.current(valueToStore);
+        document.cookie = buildCookieString(
+          key,
+          serialized,
+          attributesRef.current
+        );
+        cacheRef.current = { rawValue: serialized, parsedValue: valueToStore };
+        notifyListeners(key);
+      } catch (error) {
+        onErrorRef.current?.(error);
+      }
+    },
+    [key]
+  );
+  const removeValue = useCallback(() => {
+    try {
+      if (!isDocumentAvailable()) return;
+      document.cookie = buildRemovalCookieString(key, attributesRef.current);
+      const initialVal = resolveInitialValue(initialValueRef.current);
+      cacheRef.current = { rawValue: void 0, parsedValue: initialVal };
+      notifyListeners(key);
+    } catch (error) {
+      onErrorRef.current?.(error);
+    }
+  }, [key]);
+  return [storedValue, setValue, removeValue];
+}
+export {
+  buildCookieString,
+  buildRemovalCookieString,
+  parseCookie,
+  useCookie
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useCookie.ts","../src/store.ts","../src/utils.ts"],"sourcesContent":["import { useCallback, useRef, useSyncExternalStore } from \"react\";\nimport { subscribe, notifyListeners } from \"./store\";\nimport {\n  buildCookieString,\n  buildRemovalCookieString,\n  defaultDeserializer,\n  defaultSerializer,\n  isDocumentAvailable,\n  readRawCookie,\n  type CookieAttributes,\n} from \"./utils\";\n\nexport type { CookieAttributes, SameSite } from \"./utils\";\n\n/**\n * Type for the initial value that can be a value or a function returning a value\n * (lazy initialization).\n */\nexport type InitialValue<T> = T | (() => T);\n\n/**\n * Options for the {@link useCookie} hook. Combines serialization/lifecycle\n * options (aligned with `@usefy/use-local-storage`) with the cookie-specific\n * write attributes from {@link CookieAttributes}.\n */\nexport interface UseCookieOptions<T> extends CookieAttributes {\n  /**\n   * Initial value used when the cookie is absent (or on the server). Supports a\n   * lazy initializer function. This is also the value the state resets to when\n   * {@link UseCookieReturn} `remove()` is called.\n   */\n  initialValue?: InitialValue<T>;\n  /**\n   * Custom serializer for converting the value to the stored cookie string.\n   * @default JSON.stringify\n   */\n  serializer?: (value: T) => string;\n  /**\n   * Custom deserializer for parsing the stored cookie string back to a value.\n   * The default tries `JSON.parse` and **falls back to the raw string** for\n   * non-JSON cookies (so a plain `foo=bar` cookie never throws).\n   * @default (value) => { try { return JSON.parse(value) } catch { return value } }\n   */\n  deserializer?: (value: string) => T;\n  /** Callback invoked when a serialization/deserialization error occurs. */\n  onError?: (error: Error) => void;\n}\n\n/**\n * Return type for {@link useCookie} — a tuple similar to `useState`.\n */\nexport type UseCookieReturn<T> = readonly [\n  /** Current cookie value (`undefined` when the cookie is absent and no `initialValue` was given). */\n  T | undefined,\n  /** Update the cookie value. Accepts a value or a functional updater `(prev) => next`. */\n  React.Dispatch<React.SetStateAction<T | undefined>>,\n  /** Delete the cookie and reset state to `initialValue` (or `undefined`). */\n  () => void\n];\n\n/**\n * Resolve an initial value, supporting a lazy initializer function.\n */\nfunction resolveInitialValue<T>(\n  initialValue: InitialValue<T> | undefined\n): T | undefined {\n  return typeof initialValue === \"function\"\n    ? (initialValue as () => T)()\n    : initialValue;\n}\n\n/**\n * A hook for reading and writing a browser **cookie** as React state — the\n * cookie sibling of `@usefy/use-local-storage` and `@usefy/use-session-storage`.\n * Works like `useState` but the value is persisted in `document.cookie`.\n *\n * Features:\n * - **`useState`-like tuple**: `[value, setValue, remove]`.\n * - **Same-document sync**: multiple `useCookie(key)` instances stay in sync.\n * - **SSR-safe**: guards all `document` access and returns `initialValue` on the\n *   server (uses `useSyncExternalStore`, identical to its storage siblings, to\n *   avoid hydration mismatches).\n * - **Cookie attributes**: `expires`, `maxAge`, `path`, `domain`, `secure`,\n *   `sameSite`.\n * - **Safe (de)serialization**: JSON by default, with a graceful fallback to the\n *   raw string for plain (non-JSON) cookies.\n *\n * > **Cross-tab note:** cookies have no `storage` event, so writes in *other*\n * > tabs are not observed without polling. Same-document instances always sync.\n *\n * @template T - The type of the stored value\n * @param key - The cookie name\n * @param options - Serialization, initial value, and cookie write attributes\n * @returns A tuple of `[value, setValue, remove]`\n *\n * @example\n * ```tsx\n * // Basic usage — a string cookie\n * function ThemeToggle() {\n *   const [theme, setTheme, removeTheme] = useCookie(\"theme\", {\n *     initialValue: \"light\",\n *   });\n *\n *   return (\n *     <div>\n *       <p>Current theme: {theme}</p>\n *       <button onClick={() => setTheme(\"dark\")}>Dark</button>\n *       <button onClick={removeTheme}>Reset</button>\n *     </div>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // With cookie attributes — persist for a week over HTTPS only\n * const [token, setToken] = useCookie<string>(\"token\", {\n *   expires: 7, // days (or a Date)\n *   path: \"/\",\n *   secure: true,\n *   sameSite: \"strict\",\n * });\n * ```\n *\n * @example\n * ```tsx\n * // Object value with a functional update (JSON serialized)\n * interface Prefs { lang: string; compact: boolean }\n * const [prefs, setPrefs] = useCookie<Prefs>(\"prefs\", {\n *   initialValue: { lang: \"en\", compact: false },\n * });\n * setPrefs((prev) => ({ ...prev!, compact: true }));\n * ```\n */\nexport function useCookie<T = string>(\n  key: string,\n  options: UseCookieOptions<T> = {}\n): UseCookieReturn<T> {\n  const {\n    initialValue,\n    serializer = defaultSerializer,\n    deserializer = defaultDeserializer,\n    onError,\n    expires,\n    maxAge,\n    path,\n    domain,\n    secure,\n    sameSite,\n  } = options;\n\n  // Store options in refs for stable references and access to the latest values.\n  const serializerRef = useRef(serializer);\n  const deserializerRef = useRef(deserializer);\n  const onErrorRef = useRef(onError);\n  const initialValueRef = useRef(initialValue);\n\n  serializerRef.current = serializer;\n  deserializerRef.current = deserializer;\n  onErrorRef.current = onError;\n  initialValueRef.current = initialValue;\n\n  // Latest cookie write attributes, so setValue/remove stay stable across renders.\n  const attributesRef = useRef<CookieAttributes>({});\n  attributesRef.current = { expires, maxAge, path, domain, secure, sameSite };\n\n  // Cache for getSnapshot so it returns a stable reference when the raw cookie\n  // value is unchanged — required by useSyncExternalStore to avoid loops.\n  const cacheRef = useRef<{\n    rawValue: string | undefined;\n    parsedValue: T | undefined;\n  } | null>(null);\n\n  const isClient = isDocumentAvailable();\n\n  // Subscribe to same-document changes via the internal store.\n  const subscribeToStore = useCallback(\n    (onStoreChange: () => void) => {\n      return subscribe(key, onStoreChange);\n    },\n    [key]\n  );\n\n  // getSnapshot: read the current value from document.cookie with caching.\n  const getSnapshot = useCallback((): T | undefined => {\n    if (!isClient) {\n      return resolveInitialValue(initialValueRef.current);\n    }\n\n    try {\n      const rawValue = readRawCookie(key);\n\n      if (cacheRef.current && cacheRef.current.rawValue === rawValue) {\n        return cacheRef.current.parsedValue;\n      }\n\n      let parsedValue: T | undefined;\n      if (rawValue !== undefined) {\n        parsedValue = deserializerRef.current(rawValue);\n      } else {\n        parsedValue = resolveInitialValue(initialValueRef.current);\n      }\n\n      cacheRef.current = { rawValue, parsedValue };\n      return parsedValue;\n    } catch (error) {\n      onErrorRef.current?.(error as Error);\n      const fallbackValue = resolveInitialValue(initialValueRef.current);\n      cacheRef.current = { rawValue: undefined, parsedValue: fallbackValue };\n      return fallbackValue;\n    }\n  }, [key, isClient]);\n\n  // getServerSnapshot: return the initial value for SSR.\n  const getServerSnapshot = useCallback((): T | undefined => {\n    return resolveInitialValue(initialValueRef.current);\n  }, []);\n\n  const storedValue = useSyncExternalStore(\n    subscribeToStore,\n    getSnapshot,\n    getServerSnapshot\n  );\n\n  // setValue — stable reference that writes the cookie and notifies listeners.\n  const setValue = useCallback<React.Dispatch<React.SetStateAction<T | undefined>>>(\n    (value) => {\n      try {\n        if (!isDocumentAvailable()) return;\n\n        // Resolve the current value for functional updates.\n        const currentValue = (() => {\n          try {\n            const raw = readRawCookie(key);\n            if (raw !== undefined) {\n              return deserializerRef.current(raw);\n            }\n            return resolveInitialValue(initialValueRef.current);\n          } catch {\n            return resolveInitialValue(initialValueRef.current);\n          }\n        })();\n\n        const valueToStore =\n          value instanceof Function ? value(currentValue) : value;\n\n        const serialized = serializerRef.current(valueToStore as T);\n        document.cookie = buildCookieString(\n          key,\n          serialized,\n          attributesRef.current\n        );\n\n        // Invalidate cache so the next getSnapshot reads the fresh value.\n        cacheRef.current = { rawValue: serialized, parsedValue: valueToStore };\n\n        notifyListeners(key);\n      } catch (error) {\n        onErrorRef.current?.(error as Error);\n      }\n    },\n    [key]\n  );\n\n  // remove — stable reference that deletes the cookie and resets to initial.\n  const removeValue = useCallback(() => {\n    try {\n      if (!isDocumentAvailable()) return;\n\n      document.cookie = buildRemovalCookieString(key, attributesRef.current);\n\n      const initialVal = resolveInitialValue(initialValueRef.current);\n      cacheRef.current = { rawValue: undefined, parsedValue: initialVal };\n\n      notifyListeners(key);\n    } catch (error) {\n      onErrorRef.current?.(error as Error);\n    }\n  }, [key]);\n\n  return [storedValue, setValue, removeValue] as const;\n}\n","/**\n * Internal Store Manager for cookie synchronization.\n * This module manages listeners for same-document synchronization across\n * components using the same cookie key.\n *\n * Unlike `localStorage`, cookies have no native `storage` event, so there is no\n * way to observe cross-tab writes without polling. This store therefore keeps\n * every `useCookie(key)` instance **within the same document** in sync: when one\n * instance writes or removes a cookie it notifies the others. Cross-tab\n * synchronization is intentionally not attempted (see the README).\n *\n * @internal This module is not exported publicly\n */\n\n/** Map of key -> Set of listener callbacks */\nconst listeners = new Map<string, Set<() => void>>();\n\n/**\n * Subscribe a listener to changes for a specific key\n * @param key - The cookie key to subscribe to\n * @param listener - Callback to invoke when the key's value changes\n * @returns Unsubscribe function\n */\nexport function subscribe(key: string, listener: () => void): () => void {\n  if (!listeners.has(key)) {\n    listeners.set(key, new Set());\n  }\n\n  const keyListeners = listeners.get(key)!;\n  keyListeners.add(listener);\n\n  return () => {\n    keyListeners.delete(listener);\n\n    // Cleanup: remove the key entry if no more listeners\n    if (keyListeners.size === 0) {\n      listeners.delete(key);\n    }\n  };\n}\n\n/**\n * Notify all listeners subscribed to a specific key.\n * This is called when setValue or removeValue is invoked to synchronize all\n * components using the same key in the same document.\n *\n * @param key - The cookie key that was updated\n */\nexport function notifyListeners(key: string): void {\n  const keyListeners = listeners.get(key);\n  if (keyListeners) {\n    keyListeners.forEach((listener) => listener());\n  }\n}\n\n/**\n * Get the count of listeners for a key (for testing purposes)\n * @internal\n */\nexport function getListenerCount(key: string): number {\n  return listeners.get(key)?.size ?? 0;\n}\n\n/**\n * Clear all listeners (for testing purposes)\n * @internal\n */\nexport function clearAllListeners(): void {\n  listeners.clear();\n}\n","/**\n * Pure, framework-agnostic helpers for reading and writing `document.cookie`.\n * These are unit-tested in isolation and used by {@link useCookie}.\n */\n\n/**\n * The `SameSite` cookie attribute values.\n *\n * - `\"strict\"` — cookie is sent only for same-site requests.\n * - `\"lax\"` — cookie is sent on same-site requests and top-level navigations.\n * - `\"none\"` — cookie is sent on all requests; **requires `secure: true`**.\n */\nexport type SameSite = \"strict\" | \"lax\" | \"none\";\n\n/**\n * Cookie write attributes, mirroring the standard `Set-Cookie` directives.\n * These control how the cookie is persisted by the browser.\n */\nexport interface CookieAttributes {\n  /**\n   * Expiry of the cookie. Either an absolute `Date`, or a number of **days**\n   * from now (e.g. `7` = expires in a week). Omit for a session cookie.\n   */\n  expires?: Date | number;\n  /**\n   * `Max-Age` in **seconds** from now. Takes precedence over `expires` in\n   * browsers that support it. Use `0` or a negative number to expire immediately.\n   */\n  maxAge?: number;\n  /**\n   * The URL path the cookie is scoped to.\n   * @default \"/\"\n   */\n  path?: string;\n  /** The domain the cookie is scoped to (e.g. `.example.com`). */\n  domain?: string;\n  /** When `true`, the cookie is only sent over HTTPS. */\n  secure?: boolean;\n  /** The `SameSite` policy. `\"none\"` requires `secure: true`. */\n  sameSite?: SameSite;\n}\n\n/** `true` when running in an environment that exposes `document`. */\nexport function isDocumentAvailable(): boolean {\n  return typeof document !== \"undefined\";\n}\n\n/** Capitalize the first letter (e.g. `\"lax\"` → `\"Lax\"`) for the `SameSite` directive. */\nfunction capitalizeSameSite(value: SameSite): string {\n  return value.charAt(0).toUpperCase() + value.slice(1);\n}\n\n/**\n * Default serializer — JSON-encodes any value.\n * @default JSON.stringify\n */\nexport function defaultSerializer<T>(value: T): string {\n  return JSON.stringify(value);\n}\n\n/**\n * Default deserializer — tries `JSON.parse`, and **falls back to the raw\n * string** if the value is not valid JSON. Cookies are very often plain,\n * non-JSON strings (set by a server or another library), so this never throws\n * on a legacy/plain value: `\"bar\"` stays `\"bar\"`, while `'{\"a\":1}'` becomes\n * `{ a: 1 }`.\n */\nexport function defaultDeserializer<T>(value: string): T {\n  try {\n    return JSON.parse(value) as T;\n  } catch {\n    return value as unknown as T;\n  }\n}\n\n/**\n * Parse a raw `document.cookie` string and return the **decoded** value for\n * `key`, or `undefined` when the key is absent. Pure — does not touch\n * `document`, so it is trivially testable.\n *\n * @param cookieString - The raw `document.cookie` value (e.g. `\"a=1; b=2\"`).\n * @param key - The (un-encoded) cookie name to look up.\n */\nexport function parseCookie(\n  cookieString: string,\n  key: string\n): string | undefined {\n  if (!cookieString) return undefined;\n\n  const pairs = cookieString.split(\"; \");\n  for (const pair of pairs) {\n    const eqIndex = pair.indexOf(\"=\");\n    const rawName = eqIndex > -1 ? pair.slice(0, eqIndex) : pair;\n\n    let name: string;\n    try {\n      name = decodeURIComponent(rawName);\n    } catch {\n      name = rawName;\n    }\n\n    if (name === key) {\n      const rawValue = eqIndex > -1 ? pair.slice(eqIndex + 1) : \"\";\n      try {\n        return decodeURIComponent(rawValue);\n      } catch {\n        return rawValue;\n      }\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Read the decoded value of a cookie from `document.cookie`, guarding for SSR.\n * Returns `undefined` on the server or when the cookie is absent.\n */\nexport function readRawCookie(key: string): string | undefined {\n  if (!isDocumentAvailable()) return undefined;\n  return parseCookie(document.cookie, key);\n}\n\n/**\n * Build a `document.cookie` assignment string for a cookie, encoding the name\n * and value and appending the standard attributes. Pure and testable.\n *\n * @example\n * buildCookieString(\"theme\", \"dark\", { path: \"/\", maxAge: 3600 })\n * // => \"theme=dark; Path=/; Max-Age=3600\"\n */\nexport function buildCookieString(\n  name: string,\n  value: string,\n  attributes: CookieAttributes = {}\n): string {\n  const { expires, maxAge, path = \"/\", domain, secure, sameSite } = attributes;\n\n  let str = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;\n\n  if (expires !== undefined) {\n    const date =\n      typeof expires === \"number\"\n        ? new Date(Date.now() + expires * 864e5)\n        : expires;\n    str += `; Expires=${date.toUTCString()}`;\n  }\n\n  if (maxAge !== undefined) {\n    str += `; Max-Age=${maxAge}`;\n  }\n\n  if (path) {\n    str += `; Path=${path}`;\n  }\n\n  if (domain) {\n    str += `; Domain=${domain}`;\n  }\n\n  if (secure) {\n    str += \"; Secure\";\n  }\n\n  if (sameSite) {\n    str += `; SameSite=${capitalizeSameSite(sameSite)}`;\n  }\n\n  return str;\n}\n\n/**\n * Build the `document.cookie` assignment string that **deletes** a cookie. The\n * value is emptied and the cookie is expired in the past (`Max-Age=-1` plus an\n * epoch `Expires`). The same `path`/`domain` used to write it must be provided,\n * otherwise the browser treats it as a different cookie and deletion is a no-op.\n */\nexport function buildRemovalCookieString(\n  name: string,\n  attributes: Pick<CookieAttributes, \"path\" | \"domain\"> = {}\n): string {\n  const { path = \"/\", domain } = attributes;\n\n  let str = `${encodeURIComponent(name)}=; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Max-Age=-1`;\n\n  if (path) {\n    str += `; Path=${path}`;\n  }\n\n  if (domain) {\n    str += `; Domain=${domain}`;\n  }\n\n  return str;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@usefy/use-cookie",
+  "version": "0.19.0",
+  "description": "A React hook for reading and writing browser cookies as React state, SSR-aware",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
+    "jsdom": "^27.3.0",
+    "react": "^19.0.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mirunamu00/usefy.git",
+    "directory": "packages/hooks/use-cookie"
+  },
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "hooks",
+    "cookie",
+    "cookies",
+    "document.cookie",
+    "storage",
+    "state",
+    "persistence",
+    "ssr"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}