refactor: reorganise cookie handling utilities

src/core/cookies/cookieQueryOptions.ts

@@ -1,46 +1,42 @@
 import type { CookieQueryStrategy } from "../../types/CookieQueryStrategy";
 
 /**
- * Options for querying cookies
- *
+ * Options for querying cookies.
  * @example
  * // Basic usage with 'all' strategy
  * const allCookiesOptions: CookieQueryOptions<'all'> = {
  *   strategy: 'all',
  *   limit: 10,
  *   removeExpired: true
  * };
- *
  * @example
  * // Query with 'name' strategy
  * const nameQueryOptions: CookieQueryOptions<'name'> = {
  *   strategy: 'name',
  *   removeExpired: false
  * };
- *
  * @example
  * // Query with pagination
  * const paginatedOptions: CookieQueryOptions<'all'> = {
  *   strategy: 'all',
  *   limit: 5,  // Only return 5 cookies
  *   removeExpired: true
  * };
- *
  * @example
  * // Create options for Chrome cookie query
  * const chromeOptions: CookieQueryOptions<ChromeCookieQueryStrategy> = {
  *   strategy: new ChromeCookieQueryStrategy(),
  *   limit: 10,
  *   removeExpired: true
  * };
- *
+ * @example
  * // Create options for Firefox cookie query
  * const firefoxOptions: CookieQueryOptions<FirefoxCookieQueryStrategy> = {
  *   strategy: new FirefoxCookieQueryStrategy(),
  *   profiles: ['default', 'dev'],
  *   removeExpired: true
  * };
- *
+ * @example
  * // Create options for composite query
  * const compositeOptions: CookieQueryOptions<CompositeCookieQueryStrategy> = {
  *   strategy: new CompositeCookieQueryStrategy([

src/core/cookies/cookieSpecsFromUrl.ts

@@ -3,7 +3,10 @@ import type { CookieSpec } from "../../types/CookieSpec";
 /**
  * Generate cookie specifications from a URL by creating specs for both the exact domain
  * and its parent domains. This allows for proper cookie matching across domain levels.
- *
+ * @internal
+ * @param url - The URL to generate cookie specs from (e.g., 'https://example.com')
+ * @returns An array of cookie specifications for the URL and its parent domains
+ * @throws {Error} If the URL is invalid or cannot be parsed
  * @example
  * // Basic usage with a simple URL
  * cookieSpecsFromUrl('https://sub.example.com')
@@ -12,21 +15,13 @@ import type { CookieSpec } from "../../types/CookieSpec";
  * //   { name: '%', domain: '%.example.com' },
  * //   { name: '%', domain: 'example.com' }
  * // ]
- *
  * @example
  * // Error handling
  * try {
  *   cookieSpecsFromUrl('invalid-url')
  * } catch (error) {
  *   console.error(error.message) // "Invalid URL"
  * }
- *
- * @internal
- * @param url - The URL to generate cookie specs from (e.g., 'https://example.com')
- *
- * @returns An array of cookie specifications for the URL and its parent domains
- *
- * @throws {Error} If the URL is invalid or cannot be parsed
  */
 export function cookieSpecsFromUrl(url: string): CookieSpec[] {
   if (!url) {

src/core/cookies/dynamicImports.ts

@@ -3,68 +3,60 @@ import type { CookieSpec } from "../../types/CookieSpec";
 import type { ExportedCookie } from "../../types/ExportedCookie";
 
 /**
- * Dynamic import for the getCookie function
- *
+ * Dynamic import for the getCookie function.
+ * @internal
+ * @returns Promise resolving to the getCookie function
  * @example
  * ```typescript
  * const getCookieFn = await getCookie();
  * const cookies = await getCookieFn({ domain: 'example.com' });
  * // Returns: [{ name: 'sessionId', value: 'abc123', domain: 'example.com' }, ...]
  * ```
- *
- * @internal
- * @returns Promise resolving to the getCookie function
  */
 export const getCookie = (): Promise<
   (cookieSpec: CookieSpec) => Promise<ExportedCookie[]>
 > => import("./getCookie").then((module) => module.getCookie);
 
 /**
- * Dynamic import for Chrome-specific cookie retrieval
- *
+ * Dynamic import for Chrome-specific cookie retrieval.
+ * @internal
+ * @returns Promise resolving to the getChromeCookie function
  * @example
  * ```typescript
  * const chromeCookieFn = await getChromeCookie();
  * const cookies = await chromeCookieFn({ domain: 'example.com', secure: true });
  * // Returns Chrome-format cookies: [{ name: 'auth', value: 'xyz789', secure: true }, ...]
  * ```
- *
- * @internal
- * @returns Promise resolving to the getChromeCookie function
  */
 export const getChromeCookie = (): Promise<
   (cookieSpec: CookieSpec) => Promise<ExportedCookie[]>
 > => import("./getChromeCookie").then((module) => module.getChromeCookie);
 
 /**
- * Dynamic import for Firefox-specific cookie retrieval
- *
+ * Dynamic import for Firefox-specific cookie retrieval.
+ * @internal
+ * @returns Promise resolving to the getFirefoxCookie function
  * @example
  * ```typescript
  * const firefoxCookieFn = await getFirefoxCookie();
  * const cookies = await firefoxCookieFn({ path: '/api' });
  * // Returns Firefox-format cookies: [{ name: 'token', value: 'def456', path: '/api' }, ...]
  * ```
- *
- * @internal
- * @returns Promise resolving to the getFirefoxCookie function
  */
 export const getFirefoxCookie = (): Promise<
   (cookieSpec: CookieSpec) => Promise<ExportedCookie[]>
 > => import("./getFirefoxCookie").then((module) => module.getFirefoxCookie);
 
 /**
- * Dynamic import for retrieving grouped and rendered cookies
- *
+ * Dynamic import for retrieving grouped and rendered cookies.
+ * @internal
+ * @returns Promise resolving to the getGroupedRenderedCookies function
  * @example
  * ```typescript
  * const groupedCookiesFn = await getGroupedRenderedCookies();
  * const cookieStrings = await groupedCookiesFn({ domain: 'example.com' });
  * // Returns: ['sessionId=abc123; Domain=example.com', 'auth=xyz789; Domain=example.com']
  * ```
- *
- * @internal
- * @returns Promise resolving to the getGroupedRenderedCookies function
  */
 export const getGroupedRenderedCookies = (): Promise<
   (cookieSpec: CookieSpec) => Promise<string[]>
@@ -74,8 +66,9 @@ export const getGroupedRenderedCookies = (): Promise<
   );
 
 /**
- * Dynamic import for retrieving merged and rendered cookies
- *
+ * Dynamic import for retrieving merged and rendered cookies.
+ * @internal
+ * @returns Promise resolving to the getMergedRenderedCookies function
  * @example
  * ```typescript
  * const mergedCookiesFn = await getMergedRenderedCookies();
@@ -85,9 +78,6 @@ export const getGroupedRenderedCookies = (): Promise<
  * );
  * // Returns: "sessionId=abc123; auth=xyz789"
  * ```
- *
- * @internal
- * @returns Promise resolving to the getMergedRenderedCookies function
  */
 export const getMergedRenderedCookies = (): Promise<
   (

src/core/cookies/getChromeCookie.ts

@@ -5,14 +5,12 @@ import { ChromeCookieQueryStrategy } from "../browsers/chrome/ChromeCookieQueryS
 
 /**
  * Retrieves cookies from Chrome browser storage that match the specified criteria.
- *
- * @param cookieSpec - The cookie specification containing search criteria:
- *                     - name: The name of the cookie to search for
- *                     - domain: (optional) The domain to filter cookies by
- * @returns An array of ExportedCookie objects that match the specification.
- *          Returns an empty array if no matches are found or if an error occurs.
+ * @param cookieSpec - The cookie specification containing search criteria
+ * @param cookieSpec.name - The name of the cookie to search for
+ * @param cookieSpec.domain - (optional) The domain to filter cookies by
+ * @returns An array of ExportedCookie objects that match the specification
  * @throws Will catch and handle any errors during cookie querying, logging a warning
- *         to the console without throwing to the caller.
+ * to the console without throwing to the caller
  * @example
  * ```typescript
  * // Get all cookies named "sessionId" from Chrome
@@ -23,18 +21,6 @@ import { ChromeCookieQueryStrategy } from "../browsers/chrome/ChromeCookieQueryS
  *   name: "userPref",
  *   domain: "example.com"
  * });
- *
- * // Get authentication cookies from a specific subdomain
- * const authCookies = await getChromeCookie({
- *   name: "auth-token",
- *   domain: "auth.myapp.com"
- * });
- *
- * // Get tracking cookies from any .com domain
- * const trackingCookies = await getChromeCookie({
- *   name: "tracking-id",
- *   domain: ".com"
- * });
  * ```
  */
 export async function getChromeCookie(
@@ -54,21 +40,14 @@ export async function getChromeCookie(
 }
 
 /**
- * Default export of the getChromeCookie function
- *
+ * Default export of the getChromeCookie function.
  * @example
  * ```typescript
  * import getChromeCookie from './getChromeCookie';
- *
- * // Get all instances of a cookie named "session"
- * const sessionCookies = await getChromeCookie({ name: "session" });
- *
- * // Get cookies from multiple domains
- * const promises = [
- *   getChromeCookie({ name: "userId", domain: "app1.example.com" }),
- *   getChromeCookie({ name: "userId", domain: "app2.example.com" })
- * ];
- * const [app1Cookies, app2Cookies] = await Promise.all(promises);
+ * const cookies = await getChromeCookie({
+ *   name: "sessionId",
+ *   domain: "example.com"
+ * });
  * ```
  */
 export default getChromeCookie;

src/core/cookies/getCookie.ts

@@ -7,14 +7,12 @@ import { queryCookies } from "./queryCookies";
 /**
  * Retrieves browser cookies that match the specified cookie name and domain criteria.
  * This function provides a way to search and filter cookies based on given specifications.
- *
- * @param cookieSpec - The cookie specification containing search criteria:
- *                     - name: The name of the cookie to search for
- *                     - domain: (optional) The domain to filter cookies by
- * @returns An array of ExportedCookie objects that match the specification.
- *          Returns an empty array if no matches are found or if an error occurs.
+ * @param cookieSpec - The cookie specification containing search criteria
+ * @param cookieSpec.name - The name of the cookie to search for
+ * @param cookieSpec.domain - (optional) The domain to filter cookies by
+ * @returns An array of ExportedCookie objects that match the specification
  * @throws Will catch and handle any errors during cookie querying, logging a warning
- *         to the console without throwing to the caller.
+ * to the console without throwing to the caller
  * @example
  * ```typescript
  * // Get all cookies named "sessionId"
@@ -27,13 +25,6 @@ import { queryCookies } from "./queryCookies";
  *   domain: "example.com"
  * });
  * // Returns: [{ name: "userPref", value: "darkMode", domain: "example.com", ... }]
- *
- * // Get cookies with partial domain match
- * const subdomainCookies = await getCookie({
- *   name: "tracking",
- *   domain: ".example.com"
- * });
- * // Returns cookies from example.com and its subdomains
  * ```
  */
 export async function getCookie(
@@ -52,20 +43,14 @@ export async function getCookie(
 }
 
 /**
- * Default export of the getCookie function
- *
+ * Default export of the getCookie function.
  * @example
  * ```typescript
  * import getCookie from './getCookie';
- *
- * // Get authentication cookies
  * const authCookies = await getCookie({
  *   name: "auth-token",
  *   domain: "api.example.com"
  * });
- *
- * // Get all preference cookies across domains
- * const prefCookies = await getCookie({ name: "preferences" });
  * ```
  */
 export default getCookie;

src/core/cookies/getFirefoxCookie.ts

@@ -5,14 +5,12 @@ import { FirefoxCookieQueryStrategy } from "../browsers/firefox/FirefoxCookieQue
 
 /**
  * Retrieves cookies from Firefox browser storage that match the specified criteria.
- *
- * @param cookieSpec - The cookie specification containing search criteria:
- *                     - name: The name of the cookie to search for
- *                     - domain: (optional) The domain to filter cookies by
- * @returns An array of ExportedCookie objects that match the specification.
- *          Returns an empty array if no matches are found or if an error occurs.
+ * @param cookieSpec - The cookie specification containing search criteria
+ * @param cookieSpec.name - The name of the cookie to search for
+ * @param cookieSpec.domain - (optional) The domain to filter cookies by
+ * @returns An array of ExportedCookie objects that match the specification
  * @throws Will catch and handle any errors during cookie querying, logging a warning
- *         to the console without throwing to the caller.
+ * to the console without throwing to the caller
  * @example
  * ```typescript
  * // Get all cookies named "sessionId" from Firefox
@@ -23,18 +21,6 @@ import { FirefoxCookieQueryStrategy } from "../browsers/firefox/FirefoxCookieQue
  *   name: "userPref",
  *   domain: "example.com"
  * });
- *
- * // Get authentication cookies from a specific subdomain
- * const authCookies = await getFirefoxCookie({
- *   name: "auth_token",
- *   domain: "auth.myapp.com"
- * });
- *
- * // Get tracking cookies from any .com domain
- * const trackingCookies = await getFirefoxCookie({
- *   name: "_ga",
- *   domain: ".com"
- * });
  * ```
  */
 export async function getFirefoxCookie(
@@ -57,21 +43,14 @@ export async function getFirefoxCookie(
 }
 
 /**
- * Default export of the getFirefoxCookie function
- *
+ * Default export of the getFirefoxCookie function.
  * @example
  * ```typescript
  * import getFirefoxCookie from './getFirefoxCookie';
- *
- * // Get all session cookies
- * const sessionCookies = await getFirefoxCookie({ name: "PHPSESSID" });
- *
- * // Get cookies from multiple domains
- * const promises = [
- *   getFirefoxCookie({ name: "token", domain: "api.example.com" }),
- *   getFirefoxCookie({ name: "token", domain: "auth.example.com" })
- * ];
- * const [apiCookies, authCookies] = await Promise.all(promises);
+ * const sessionCookies = await getFirefoxCookie({
+ *   name: "PHPSESSID",
+ *   domain: "example.com"
+ * });
  * ```
  */
 export default getFirefoxCookie;