{"_id":"@adalink/spark-cookie","name":"@adalink/spark-cookie","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@adalink/spark-cookie","version":"1.0.0","description":"Cookie utilities for web development","type":"module","license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/Adalink-ai/spark_cookie.git"},"bugs":{"url":"https://github.com/Adalink-ai/spark_cookie/issues"},"homepage":"https://github.com/Adalink-ai/spark_cookie#readme","author":{"name":"Cleber de Moraes Goncalves","email":"cleber.engineer@gmail.com","url":"https://github.com/deMGoncalves"},"exports":{".":{"import":"./dist/cookie.js","require":"./dist/cookie.cjs"}},"keywords":["cookie","web-development","browser","utilities"],"devDependencies":{"@biomejs/biome":"2.4.7","@commitlint/cli":"^20.5.0","@commitlint/config-conventional":"^20.5.0","esbuild":"^0.27.2","husky":"^9.1.7","lint-staged":"^16.4.0","vite":"^8.0.0"},"scripts":{"build":"vite build","dev":"vite","lint":"biome check .","prepare":"husky"},"_id":"@adalink/spark-cookie@1.0.0","gitHead":"e2a97b8ed31d92cf010de1b435681c85025c7901","_nodeVersion":"20.20.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-JA8HsoiqL8YtVUsBKDPsC9SrVeKyPk87icwF0XKS8e52BkoAmU7rwJ17eYlaaKGphB6vU7lX84F5QB/boVjWig==","shasum":"ccb991a8c45e77194333c2777c7243e8aa75baad","tarball":"https://registry.npmjs.org/@adalink/spark-cookie/-/spark-cookie-1.0.0.tgz","fileCount":5,"unpackedSize":29880,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIB4G5bpgwpIRZaxXvJcjjUlZelHQzEVwn9/L8WNoufpGAiEA8o7d9qwpX/gPS+2ab48lCoawSWRScBxMcKk/83js62g="}]},"_npmUser":{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"},"directories":{},"maintainers":[{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/spark-cookie_1.0.0_1774371672303_0.5432863734728739"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-24T17:01:12.203Z","1.0.0":"2026-03-24T17:01:12.445Z","modified":"2026-03-24T17:01:12.661Z"},"maintainers":[{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"}],"description":"Cookie utilities for web development","homepage":"https://github.com/Adalink-ai/spark_cookie#readme","keywords":["cookie","web-development","browser","utilities"],"repository":{"type":"git","url":"git+https://github.com/Adalink-ai/spark_cookie.git"},"author":{"name":"Cleber de Moraes Goncalves","email":"cleber.engineer@gmail.com","url":"https://github.com/deMGoncalves"},"bugs":{"url":"https://github.com/Adalink-ai/spark_cookie/issues"},"license":"Apache-2.0","readme":"# 🍪 Spark Cookie\n\n[![npm version](https://img.shields.io/npm/v/@adalink/spark-cookie?style=flat-square)](https://www.npmjs.com/package/@adalink/spark-cookie)\n[![License](https://img.shields.io/npm/l/@adalink/spark-cookie?style=flat-square)](LICENSE)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/Adalink-ai/spark_cookie/ci.yml?style=flat-square)](https://github.com/Adalink-ai/spark_cookie/actions)\n[![Code Style](https://img.shields.io/badge/code_style-biome-purple?style=flat-square)](https://biomejs.dev)\n[![Ecosystem](https://img.shields.io/badge/Spark_Ecosystem-compatible-blue?style=flat-square)](https://github.com/Adalink-ai)\n\n**Cookie utilities for web development. Zero dependencies, tree-shakeable.**\n\n---\n\n## 📖 What is Spark Cookie?\n\nSpark Cookie is a modern, lightweight library for managing browser cookies with a clean, simple API. Built on native Web Platform APIs, it provides powerful utilities for creating, reading, and updating cookies without framework overhead.\n\n### 🎯 Why Choose Spark Cookie?\n\n- **Zero Dependencies** - No runtime dependencies, just pure Web Platform APIs\n- **Simple API** - Clean, intuitive interface for cookie operations\n- **Framework Agnostic** - Works with any framework or vanilla JavaScript\n- **Performance First** - Minimal bundle size (~300B)\n- **Developer Experience** - Automatic URL encoding/decoding\n- **Production Ready** - Battle-tested in real-world applications\n\n### 🚀 Perfect For\n\n- **Web Components Projects** - Manage cookies in custom elements\n- **Progressive Enhancement** - Build on web standards\n- **Performance-Critical Apps** - Minimal overhead, maximum speed\n- **Cross-Framework Projects** - Consistent cookie management\n- **Authentication** - Secure cookie handling\n\n---\n\n## ✨ Key Features\n\n### 🍪 Simple API\n\nHandle cookies with ease:\n\n```javascript\nimport cookie from '@adalink/spark-cookie';\n\n// Set a cookie\ncookie.setItem('theme', 'dark');\n\n// Get a cookie\nconst theme = cookie.getItem('theme');\nconsole.log(theme); // 'dark'\n```\n\n### 🔐 Secure Options\n\nFull support for modern cookie security:\n\n```javascript\nimport cookie from '@adalink/spark-cookie';\n\n// Secure cookie with all options\ncookie.setItem('session', 'abc123', {\n  expires: new Date('2026-12-31'),\n  maxAge: 3600,\n  domain: '.example.com',\n  path: '/',\n  secure: true,\n  httpOnly: true,\n  sameSite: 'strict'\n});\n```\n\n### ⚡ Automatic Encoding\n\nURL encoding and decoding handled automatically:\n\n```javascript\n// Values with special characters\ncookie.setItem('name', ' João Silva');\nconst value = cookie.getItem('name');\n// ' João Silva'\n```\n\n---\n\n## 🔗 Integração com Spark Ecosystem\n\nO Spark Cookie é parte do Spark Ecosystem, trabalhando em harmonia com outras bibliotecas Spark para criar aplicações web completas.\n\n### 📦 Pacotes Relacionados\n\n**[@adalink/spark-std](https://github.com/Adalink-ai/spark_std)** - Biblioteca padrão com decorators para Web Components\n\nUse Spark Cookie para gerenciar cookies em componentes criados com Spark Std:\n\n```javascript\nimport { define, connected, disconnected } from '@adalink/spark-std';\nimport { paint, html, css } from '@adalink/spark-std/dom';\nimport { event } from '@adalink/spark-std/event';\nimport cookie from '@adalink/spark-cookie';\n\n@define('spark-theme-switcher')\n@paint(template, styles)\nclass ThemeSwitcher extends HTMLElement {\n  #currentTheme = 'light';\n\n  connectedCallback() {\n    // Load theme from cookie\n    const savedTheme = cookie.getItem('theme');\n    if (savedTheme) {\n      this.#currentTheme = savedTheme;\n    }\n    this.updateTheme();\n  }\n\n  @event.click('button')\n  toggleTheme() {\n    this.#currentTheme = this.#currentTheme === 'light' ? 'dark' : 'light';\n    \n    // Save theme to cookie\n    cookie.setItem('theme', this.#currentTheme, {\n      expires: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000),\n      path: '/'\n    });\n    \n    this.updateTheme();\n  }\n\n  updateTheme() {\n    this.dispatchEvent(new CustomEvent('theme-changed', {\n      detail: this.#currentTheme,\n      bubbles: true,\n      composed: true\n    }));\n  }\n}\n\nfunction template(component) {\n  return html`\n    <button class=\"theme-toggle\">\n      Current theme: ${component.#currentTheme}\n    </button>\n  `;\n}\n\nfunction styles(component) {\n  return css`\n    .theme-toggle {\n      padding: 0.5rem 1rem;\n      background: #667eea;\n      color: white;\n      border: none;\n      border-radius: 4px;\n      cursor: pointer;\n    }\n    .theme-toggle:hover {\n      background: #764ba2;\n    }\n  `;\n}\n```\n\n**Funcionalidades Combinadas:**\n- ✅ Spark Std fornece decorators (`@define`, `@paint`, `@event`)\n- ✅ Spark Cookie fornece gerenciamento de cookies\n- ✅ Use decorators para definir comportamento do componente\n- ✅ Use cookies para persistir configurações entre sessões\n- ✅ Ambos funcionam com Web Components nativos\n\n**Ecosystem Diagram:**\n\n```\n┌─────────────────────────────────────────────────────┐\n│                  Application Layer                 │\n└───────────────────┬─────────────────────────────────┘\n                    │\n┌───────────────────▼─────────────────────────────────┐\n│              Spark Framework Layer                 │\n│  ┌──────────────────────────────────────────────┐  │\n│  │          @adalink/spark-std                  │  │\n│  │  ┌──────────┐  ┌─────┐  ┌────────┐         │  │\n│  │  │Directive │  │ DOM │  │ Event  │         │  │\n│  │  └──────────┘  └─────┘  └────────┘         │  │\n│  └──────────────────────────────────────────────┘  │\n│  ┌──────────────────────────────────────────────┐  │\n│  │         @adalink/spark-cookie                │  │\n│  │  ┌──────────┐  ┌──────────┐                 │  │\n│  │  │ getItem  │  │ setItem  │                 │  │\n│  │  └──────────┘  └──────────┘                 │  │\n│  └──────────────────────────────────────────────┘  │\n└───────────────────┬─────────────────────────────────┘\n                    │\n┌───────────────────▼─────────────────────────────────┐\n│              Web Platform APIs                     │\n│  document.cookie API                                 │\n└─────────────────────────────────────────────────────┘\n```\n\n---\n\n## 🚀 Quick Start\n\n### Installation\n\n#### Option 1: Install from npm (Recommended)\n\n```bash\n# Using npm\nnpm install @adalink/spark-cookie\n\n# Using yarn\nyarn add @adalink/spark-cookie\n\n# Using pnpm\npnpm add @adalink/spark-cookie\n\n# Using bun\nbun add @adalink/spark-cookie\n```\n\n#### Option 2: Install from GitHub (Alternative)\n\n```bash\n# Install directly from GitHub repository\nnpm install github:Adalink-ai/spark_cookie#v1.0.0\n```\n\n#### Option 3: Import from CDN (Browser Only)\n\n```javascript\n// Import modules from unpkg or jsDelivr (ESM)\nimport cookie from \"https://unpkg.com/@adalink/spark-cookie@1.0.0/dist/cookie.js\";\n```\n\n**⚠️ Important Notice:**\nThis package is **private** and published to npm. To install it:\n1. Have an npm account\n2. Request access to the `@adalink` scope from the maintainers\n3. Configure npm authentication in your environment\n\n**Installation Options:**\n- **npm registry** (recommended) - Requires npm authentication and scope access\n- **GitHub** (alternative) - Works without npm authentication, installs directly from repository\n- **CDN** (browser only) - Import modules directly from unpkg or jsDelivr, no build step required\n\n---\n\n### Basic Usage\n\n#### Setting Cookies\n\n```javascript\n// Simple cookie\ncookie.setItem('theme', 'dark');\n\n// Cookie with expiration (7 days)\ncookie.setItem('session', 'abc123', {\n  expires: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)\n});\n\n// Cookie with max-age (1 hour)\ncookie.setItem('token', 'xyz789', {\n  maxAge: 3600\n});\n```\n\n#### Getting Cookies\n\n```javascript\n// Get a cookie\nconst theme = cookie.getItem('theme');\nconsole.log(theme); // 'dark' or null if not found\n\n// Handle missing cookies\nconst session = cookie.getItem('session');\nif (!session) {\n  // Handle missing session\n}\n```\n\n#### Secure Cookies\n\n```javascript\n// Secure cookie (HTTPS only)\ncookie.setItem('token', 'secure-token', {\n  secure: true\n});\n\n// HTTP-only cookie (not accessible via JavaScript)\ncookie.setItem('session', 'session-id', {\n  httpOnly: true\n});\n\n// SameSite cookie (prevents CSRF)\ncookie.setItem('user', 'user-id', {\n  sameSite: 'strict' // or 'lax' or 'none'\n});\n\n// Combined security options\ncookie.setItem('auth', 'auth-token', {\n  secure: true,\n  httpOnly: true,\n  sameSite: 'strict',\n  expires: new Date(Date.now() + 24 * 60 * 60 * 1000)\n});\n```\n\n#### Domain and Path\n\n```javascript\n// Cookie for entire domain\ncookie.setItem('language', 'pt-BR', {\n  domain: '.example.com',\n  path: '/'\n});\n\n// Cookie for specific path\ncookie.setItem('preference', 'value', {\n  path: '/app/settings'\n});\n```\n\n#### Deleting Cookies\n\n```javascript\n// Delete by setting max-age to 0\ncookie.setItem('theme', '', {\n  maxAge: 0\n});\n\n// Delete with domain/path matching\ncookie.setItem('session', '', {\n  domain: '.example.com',\n  path: '/',\n  maxAge: 0\n});\n```\n\n---\n\n## 📦 API Reference\n\n### `cookie.getItem(name)`\n\nRetrieves a cookie value by name.\n\n**Parameters:**\n- `name` (string) - Name of the cookie\n\n**Returns:**\n- `string | null` - Cookie value or null if not found\n\n**Example:**\n```javascript\nconst value = cookie.getItem('session');\nif (value !== null) {\n  console.log('Session:', value);\n}\n```\n\n---\n\n### `cookie.setItem(name, value, options?)`\n\nCreates or updates a cookie.\n\n**Parameters:**\n- `name` (string) - Name of the cookie\n- `value` (string) - Value to store\n- `options` (object, optional)\n  - `expires` (Date) - Expiration date\n  - `maxAge` (number) - Max age in seconds\n  - `domain` (string) - Cookie domain\n  - `path` (string) - Cookie path\n  - `secure` (boolean) - HTTPS only\n  - `httpOnly` (boolean) - Not accessible via JavaScript\n  - `sameSite` (string) - `'lax'`, `'strict'`, or `'none'`\n\n**Example:**\n```javascript\ncookie.setItem('theme', 'dark', {\n  expires: new Date('2026-12-31'),\n  path: '/'\n});\n```\n\n---\n\n## 🎯 Real-World Use Cases\n\n### Theme Persistence\n\n```javascript\nimport cookie from '@adalink/spark-cookie';\n\nfunction saveTheme(theme) {\n  cookie.setItem('theme', theme, {\n    expires: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000),\n    path: '/'\n  });\n}\n\nfunction loadTheme() {\n  return cookie.getItem('theme') || 'light';\n}\n\n// Usage\nconst currentTheme = loadTheme();\ndocument.documentElement.setAttribute('data-theme', currentTheme);\n```\n\n### Session Management\n\n```javascript\nimport cookie from '@adalink/spark-cookie';\n\nfunction createSession(userId, duration = 3600) {\n  const sessionId = generateSessionId();\n  cookie.setItem('session', sessionId, {\n    maxAge: duration,\n    httpOnly: true,\n    secure: true,\n    sameSite: 'strict'\n  });\n  return sessionId;\n}\n\nfunction getSession() {\n  return cookie.getItem('session');\n}\n\nfunction destroySession() {\n  cookie.setItem('session', '', {\n    maxAge: 0\n  });\n}\n```\n\n### User Preferences\n\n```javascript\nimport cookie from '@adalink/spark-cookie';\n\nconst prefs = {\n  setLanguage(lang) {\n    cookie.setItem('language', lang, {\n expires: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),\n      path: '/'\n    });\n    document.documentElement.lang = lang;\n  },\n  \n  getLanguage() {\n    return cookie.getItem('language') || 'en';\n  },\n  \n  setTimezone(tz) {\n    cookie.setItem('timezone', tz, {\n      expires: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),\n      path: '/'\n    });\n    document.documentElement.dataset.timezone = tz;\n  },\n  \n  getTimezone() {\n    return cookie.getItem('timezone') || 'UTC';\n  }\n};\n\n// Usage\nprefs.setLanguage('pt-BR');\nprefs.setTimezone('America/Sao_Paulo');\n```\n\n---\n\n## 📊 Why Spark Cookie Over Alternatives?\n\n| Feature | Spark Cookie | js-cookie | Cookie.js |\n|---------|--------------|-----------|-----------|\n| Zero Dependencies | ✅ | ✅ | ✅ |\n| Bundle Size | ~300B | ~1.2KB | ~800B |\n| Auto Encoding | ✅ | ✅ | ✅ |\n| Secure Options | ✅ | ✅ | ⚠️ |\n| SameSite Support | ✅ | ✅ | ❌ |\n| Interface | Modern | Callback-based | Callback-based |\n| TypeScript Ready | ✅ | ✅ | ❌ |\n\n---\n\n## 🌐 Usage in Frameworks\n\n### With React\n\n```javascript\nimport cookie from '@adalink/spark-cookie';\n\nfunction ThemeToggle() {\n  const [theme, setTheme] = React.useState(() => \n    cookie.getItem('theme') || 'light'\n  );\n\n  const toggle = () => {\n    const newTheme = theme === 'light' ? 'dark' : 'light';\n    setTheme(newTheme);\n    cookie.setItem('theme', newTheme);\n  };\n\n  return <button onClick={toggle}>{theme}</button>;\n}\n```\n\n### With Vue\n\n```javascript\nimport cookie from '@adalink/spark-cookie';\n\nexport default {\n  data() {\n    return {\n      theme: cookie.getItem('theme') || 'light'\n    }\n  },\n  methods: {\n    toggleTheme() {\n      this.theme = this.theme === 'light' ? 'dark' : 'light';\n      cookie.setItem('theme', this.theme);\n    }\n  }\n}\n```\n\n---\n\n## 🛠️ Development\n\n### Prerequisites\n\n- Node.js 18+\n\n### Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/Adalink-ai/spark_cookie.git\ncd spark_cookie\n\n# Install dependencies\nnpm install\n\n# Build package\nnpm run build\n\n# Start development server\nnpm run dev\n\n# Lint and format\nnpx biome check .\nnpx biome check --write .\n```\n\n---\n\n## 📚 Documentation\n\n- **Architecture:** [ARCHITECTURE.md](ARCHITECTURE.md) - Design decisions and patterns\n- **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md) - Development guidelines\n- **Security:** [SECURITY.md](SECURITY.md) - Security policies\n- **Changelog:** [CHANGELOG.md](CHANGELOG.md) - Project changes\n- **Authors:** [AUTHORS.md](AUTHORS.md) - Author information\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please read our [Contributing Guide](CONTRIBUTING.md) before getting started.\n\n**Ways to contribute:**\n- 🐛 [Report bugs](https://github.com/Adalink-ai/spark_cookie/issues/new?template=bug_report.md)\n- 💡 [Suggest features](https://github.com/Adalink-ai/spark_cookie/issues/new?template=feature_request.md)\n- 📖 [Improve documentation](https://github.com/Adalink-ai/spark_cookie/issues/new?template=documentation.md)\n- 🔧 [Submit pull requests](https://github.com/Adalink-ai/spark_cookie/pulls)\n\n---\n\n## 👥 Author & Community\n\n**Cleber de Moraes Goncalves** - Creator & Lead Maintainer\n\n- 📧 Email: cleber.engineer@gmail.com\n- 🐙 GitHub: [deMGoncalves](https://github.com/deMGoncalves)\n- 💼 LinkedIn: [deMGoncalves](https://linkedin.com/in/deMGoncalves)\n- 📸 Instagram: [deMGoncalves](https://instagram.com/deMGoncalves)\n\n### 🌟 Star the Project\n\nIf you find Spark Cookie useful, please ⭐ star it on GitHub!\n\n### 📢 Share\n\nShare Spark Cookie with your network:\n- [Twitter](https://twitter.com/intent/tweet?text=Check%20out%20@adalink/spark-cookie%20-%20A%20modern%20cookie%20library!&url=https://github.com/Adalink-ai/spark_cookie)\n- [LinkedIn](https://www.linkedin.com/shareArticle?mini=true&url=https://github.com/Adalink-ai/spark_cookie&title=Spark%20Cookie&summary=Modern%20cookie%20library%20for%20web%20development)\n\n---\n\n## 🌐 Spark Ecosystem\n\nO Spark Ecosystem é um conjunto de bibliotecas para desenvolvimento web reativo:\n\n- **[@adalink/spark-std](https://github.com/Adalink-ai/spark_std)** - Biblioteca padrão com decorators para Web Components\n- **[@adalink/spark-echo](https://github.com/Adalink-ai/spark_echo)** - Sistema de comunicação reativa entre componentes\n\n**Mais pacotes em breve:**\n- [@adalink/spark-form](https://github.com/Adalink-ai/spark_form) - Componentes de formulário reativos (em breve)\n- [@adalink/spark-router](https://github.com/Adalink-ai/spark_router) - Roteamento SPA (em breve)\n\n---\n\n## 📄 License\n\n[Apache-2.0](LICENSE) © 2026 Adalink\n\n---\n\n## 🔗 Links\n\n- **Repository:** [github.com/Adalink-ai/spark_cookie](https://github.com/Adalink-ai/spark_cookie)\n- **NPM Package:** [npmjs.com/package/@adalink/spark-cookie](https://www.npmjs.com/package/@adalink/spark-cookie)\n- **Organization:** [github.com/Adalink-ai](https://github.com/Adalink-ai)\n\n---\n\n**Built with ❤️ by [Adalink](https://github.com/Adalink-ai)**\n\n**Spark Cookie** - Manage cookies with ease. 🍪\n","readmeFilename":"README.md","_rev":"1-3e6b233049d5c5bdd458687250cb0d0f"}