Popsicle Cookie Jar Middleware

Common errors

• Error: Cannot find module 'servie'

  cause The `servie` package is a peer dependency but has not been installed.
  fix Install `servie`: `npm install servie`.

• TypeError: Cannot read properties of undefined (reading 'headers') at cookiesMiddleware

  cause The `popsicle-cookie-jar` middleware expects the `context.request` object to exist, typically populated by a preceding middleware or the initial Popsicle client call.
  fix Ensure `popsicle-cookie-jar` is used within a valid Popsicle/Servie middleware chain where the `context.request` object is properly initialized before `cookies()` is called.

Warnings

• gotcha When using `cookies()` without an argument, an *in-memory* `CookieJar` is created. If you create multiple middleware instances this way (e.g., for different requests or clients), they will each have their own independent cookie stores, which might not be the desired behavior for persistent sessions. To share cookies, pass the same `CookieJar` instance.
  Fix: Initialize a `new CookieJar()` once and pass that same instance to `cookies()` for all related middleware compositions: `const myJar = new CookieJar(); const mw = compose([cookies(myJar), transport()]);`
• breaking The `popsicle` library (which this middleware extends) moved its core cookie functionality into `popsicle-cookie-jar` starting from `popsicle` v10.0.0. If you are upgrading `popsicle` from an older version, you must now explicitly install and include `popsicle-cookie-jar` middleware to retain cookie support.
  Fix: Install `popsicle-cookie-jar` (`npm install popsicle-cookie-jar`) and include `cookies()` in your middleware chain: `compose([cookies(), transport()])`.
• gotcha While `popsicle-cookie-jar` provides cookie functionality, it relies on `tough-cookie` for the actual cookie parsing and storage logic. Developers should be aware of `tough-cookie`'s API and limitations, especially concerning cookie domain matching and path rules, as well as any security advisories related to `tough-cookie` itself.
  Fix: Regularly update `popsicle-cookie-jar` to ensure you benefit from `tough-cookie` security patches. Consult the `tough-cookie` documentation for advanced cookie management needs or debugging.
• deprecated As this package is middleware for `popsicle`, users should be aware that `popsicle` itself appears to be in a maintenance-only state with no recent feature development, suggesting this middleware will likely follow a similar pattern. Consider alternatives if active development and a robust feature roadmap are critical.
  Fix: Evaluate newer, actively maintained HTTP clients and their cookie management solutions if starting a new project or if long-term feature support is a concern.

Install

• npm install popsicle-cookie-jar npm
• yarn add popsicle-cookie-jar yarn
• pnpm add popsicle-cookie-jar pnpm

Imports

• cookies
  wrong:

  const cookies = require('popsicle-cookie-jar').cookies;

  correct:

  import { cookies } from 'popsicle-cookie-jar';

  The library primarily uses named exports. While CommonJS `require` works, the recommended approach in modern Node.js is ESM `import`.
• CookieJar
  wrong:

  const { CookieJar } = require('popsicle-cookie-jar');

  correct:

  import { CookieJar } from 'popsicle-cookie-jar';

  Used for explicitly providing a custom `tough-cookie` compatible `CookieJar` instance to the middleware.
• compose
  wrong:

  import { compose } from 'popsicle-cookie-jar';

  correct:

  import { compose } from 'servie';

  While used in examples for `popsicle-cookie-jar`, `compose` is a utility typically provided by `servie` itself or a similar middleware orchestration library, not directly from this package. Make sure to import it from the correct source, usually `servie`.

Quickstart

This quickstart demonstrates how to apply `popsicle-cookie-jar` middleware to a Popsicle client to enable automatic cookie handling, showing both default in-memory and custom `CookieJar` usage.

import { cookies, CookieJar } from "popsicle-cookie-jar";
import { compose } from 'servie';
// Assume 'transport' is another middleware, e.g., from 'popsicle-transport-http'
// For demonstration, we'll create a dummy transport and Popsicle client.

interface Context {
  request: { url: string; headers?: Record<string, string>; };
  response?: { status: number; headers: Record<string, string>; body?: any; };
}

async function dummyTransport(ctx: Context, next: () => Promise<void>) {
  console.log(`Sending request to: ${ctx.request.url}`);
  ctx.response = {
    status: 200,
    headers: { 'Set-Cookie': 'session=abc; Path=/; HttpOnly' },
    body: 'Hello World'
  };
  await next();
}

// Create an in-memory cookie jar
const myCookieJar = new CookieJar();

// Compose the middleware with a custom cookie jar
const middlewareWithJar = compose([cookies(myCookieJar), dummyTransport]);

// Or let it create a default in-memory jar
const middlewareDefault = compose([cookies(), dummyTransport]);

async function makeRequest(middleware: (ctx: Context, next: () => Promise<void>) => Promise<void>) {
  const ctx: Context = { request: { url: 'http://example.com/login' } };
  await middleware(ctx, async () => {}); // No further middleware after transport
  console.log('Response headers:', ctx.response?.headers);
  console.log('Cookies in jar (after request):', myCookieJar.getCookiesSync('http://example.com/login'));
}

console.log('--- Using custom CookieJar ---');
await makeRequest(middlewareWithJar);

console.log('\n--- Using default (new) CookieJar instance for separate calls ---');
// Each call to cookies() without an argument creates a new jar
await makeRequest(compose([cookies(), dummyTransport]));