@mherod/get-cookie 4.0.3 → 4.1.0

package/dist/index.d.cts

@@ -1,189 +1,201 @@
+import { z } from 'zod';
+
 /**
- * Type guard to check if an object matches the CookieRenderOptions interface.
- * Used to validate render options before processing cookie output.
- * @param obj - The object to check.
- * @returns True if the object contains valid render options.
+ * Schema for cookie specification parameters
+ * Defines the required fields for identifying a cookie
  * @example
  * ```typescript
- * import { isCookieRenderOptions } from 'get-cookie';
- *
- * // Valid render options
- * console.log(isCookieRenderOptions({ format: "json" })); // true
- * console.log(isCookieRenderOptions({
- *   format: "text",
- *   separator: "\n",
- *   showFilePaths: true
- * })); // true
+ * // Validate a cookie specification
+ * const spec = {
+ *   name: 'session',
+ *   domain: 'example.com'
+ * };
+ * const result = CookieSpecSchema.safeParse(spec);
+ * if (result.success) {
+ *   console.log('Valid cookie spec:', result.data);
+ * } else {
+ *   console.error('Invalid cookie spec:', result.error);
+ * }
  *
- * // Invalid examples
- * console.log(isCookieRenderOptions({ format: "csv" })); // false - invalid format
- * console.log(isCookieRenderOptions({ separator: "\n" })); // false - missing format
- * console.log(isCookieRenderOptions(null)); // false
+ * // Invalid spec (empty name)
+ * const invalidSpec = {
+ *   name: '',
+ *   domain: 'example.com'
+ * };
+ * // Throws: "Cookie name cannot be empty"
+ * CookieSpecSchema.parse(invalidSpec);
  * ```
  */
-type RenderFormat = "merged" | "grouped";
+declare const CookieSpecSchema: z.ZodObject<{
+    name: z.ZodEffects<z.ZodString, string, string>;
+    domain: z.ZodEffects<z.ZodString, string, string>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    domain: string;
+}, {
+    name: string;
+    domain: string;
+}>;
 /**
- * Options for rendering cookies.
+ * Type definition for cookie specification
+ * Used for specifying which cookie to query
  * @example
  * ```typescript
- * import { RenderOptions } from 'get-cookie';
- *
- * // Basic rendering options
- * const basicOptions: RenderOptions = {
- *   format: 'merged',
- *   separator: '; ',
- *   showFilePaths: false
+ * // Basic cookie spec
+ * const spec: CookieSpec = {
+ *   name: 'auth',
+ *   domain: 'api.example.com'
  * };
  *
- * // Grouped format with file paths
- * const groupedOptions: RenderOptions = {
- *   format: 'grouped',
- *   separator: '; ',
- *   showFilePaths: true
- * };
+ * // Use in function parameters
+ * function queryCookie(spec: CookieSpec): Promise<ExportedCookie[]> {
+ *   return getCookie(spec);
+ * }
  *
- * // Custom separator
- * const customOptions: RenderOptions = {
- *   format: 'merged',
- *   separator: ' && ',
- *   showFilePaths: false
- * };
+ * // Array of specs
+ * const specs: CookieSpec[] = [
+ *   { name: 'session', domain: 'app.example.com' },
+ *   { name: 'theme', domain: 'example.com' }
+ * ];
  * ```
  */
-interface RenderOptions {
-    /** The format to use when rendering cookies. */
-    format?: RenderFormat;
-    /** The separator to use between cookies. */
-    separator?: string;
-    /** Whether to show file paths in the output. */
-    showFilePaths?: boolean;
-}
-
+type CookieSpec = z.infer<typeof CookieSpecSchema>;
 /**
- * Specification for identifying a cookie by its domain and name.
- * Used to query specific cookies from browser storage.
- * @remarks
- * - Domain matching is exact unless using wildcards.
- * - Name can be "*" to match all cookies for a domain.
- * - Leading dots in domains match all subdomains.
+ * Schema for exported cookie data
+ * Represents a cookie with all its properties and metadata
  * @example
  * ```typescript
- * import { CookieSpec } from 'get-cookie';
- *
- * // Basic cookie specification
- * const cookieSpec: CookieSpec = {
- *   domain: "example.com",
- *   name: "sessionId"
- * };
- *
- * // Using wildcards to match all cookies
- * const allCookies: CookieSpec = {
- *   domain: "example.com",
- *   name: "*"  // Match all cookies for example.com
- * };
- *
- * // Subdomain specification
- * const apiCookies: CookieSpec = {
- *   domain: "api.example.com",
- *   name: "auth"
- * };
- *
- * // Match cookies across all subdomains
- * const allSubdomainCookies: CookieSpec = {
- *   domain: ".example.com",  // Note the leading dot
- *   name: "tracking"
+ * // Validate an exported cookie
+ * const cookie = {
+ *   domain: 'example.com',
+ *   name: 'session',
+ *   value: 'abc123',
+ *   expiry: new Date('2024-12-31'),
+ *   meta: {
+ *     file: '/path/to/cookies.db'
+ *   }
  * };
+ * const result = ExportedCookieSchema.safeParse(cookie);
+ * if (result.success) {
+ *   console.log('Valid cookie:', result.data);
+ * } else {
+ *   console.error('Invalid cookie:', result.error);
+ * }
  *
- * // Multiple domain levels
- * const deepSubdomainCookie: CookieSpec = {
- *   domain: "dev.api.example.com",
- *   name: "debug"
+ * // Cookie with infinite expiry
+ * const infiniteCookie = {
+ *   ...cookie,
+ *   expiry: "Infinity"
  * };
+ * ExportedCookieSchema.parse(infiniteCookie); // OK
  * ```
  */
-interface CookieSpec {
-    /** The domain the cookie belongs to. */
+declare const ExportedCookieSchema: z.ZodObject<{
+    domain: z.ZodEffects<z.ZodString, string, string>;
+    name: z.ZodEffects<z.ZodString, string, string>;
+    value: z.ZodPipeline<z.ZodEffects<z.ZodString, unknown, string>, z.ZodAny>;
+    expiry: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"Infinity">, z.ZodDate, z.ZodNumber]>>;
+    meta: z.ZodOptional<z.ZodObject<{
+        file: z.ZodOptional<z.ZodString>;
+        browser: z.ZodOptional<z.ZodString>;
+        decrypted: z.ZodOptional<z.ZodBoolean>;
+        secure: z.ZodOptional<z.ZodBoolean>;
+        httpOnly: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
+    }, "strict", z.ZodUnknown, z.objectOutputType<{
+        file: z.ZodOptional<z.ZodString>;
+        browser: z.ZodOptional<z.ZodString>;
+        decrypted: z.ZodOptional<z.ZodBoolean>;
+        secure: z.ZodOptional<z.ZodBoolean>;
+        httpOnly: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
+    }, z.ZodUnknown, "strict">, z.objectInputType<{
+        file: z.ZodOptional<z.ZodString>;
+        browser: z.ZodOptional<z.ZodString>;
+        decrypted: z.ZodOptional<z.ZodBoolean>;
+        secure: z.ZodOptional<z.ZodBoolean>;
+        httpOnly: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
+    }, z.ZodUnknown, "strict">>>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
     domain: string;
-    /** The name of the cookie. */
+    value?: any;
+    expiry?: number | Date | "Infinity" | undefined;
+    meta?: z.objectOutputType<{
+        file: z.ZodOptional<z.ZodString>;
+        browser: z.ZodOptional<z.ZodString>;
+        decrypted: z.ZodOptional<z.ZodBoolean>;
+        secure: z.ZodOptional<z.ZodBoolean>;
+        httpOnly: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
+    }, z.ZodUnknown, "strict"> | undefined;
+}, {
     name: string;
-}
-
+    value: string;
+    domain: string;
+    expiry?: number | Date | "Infinity" | undefined;
+    meta?: z.objectInputType<{
+        file: z.ZodOptional<z.ZodString>;
+        browser: z.ZodOptional<z.ZodString>;
+        decrypted: z.ZodOptional<z.ZodBoolean>;
+        secure: z.ZodOptional<z.ZodBoolean>;
+        httpOnly: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
+    }, z.ZodUnknown, "strict"> | undefined;
+}>;
 /**
- * Interface representing a cookie that has been exported from a browser's storage.
- * This is the core data structure used to represent cookies after they have been
- * retrieved from various browser storage mechanisms (Chrome, Firefox, etc.).
- * @remarks
- * - All cookies must have domain, name, and value properties.
- * - Expiry is optional and can be a Date, "Infinity", or undefined.
- * - Meta information is useful for tracking the cookie's origin and state.
+ * Type definition for exported cookie data
+ * Represents the structure of a cookie after it has been retrieved
  * @example
  * ```typescript
- * import { ExportedCookie } from 'get-cookie';
- *
- * // Basic cookie with required fields
- * const basicCookie: ExportedCookie = {
- *   domain: "example.com",
- *   name: "sessionId",
- *   value: "abc123"
- * };
- *
- * // Cookie with expiry and metadata
- * const detailedCookie: ExportedCookie = {
- *   domain: "api.example.com",
- *   name: "authToken",
- *   value: "xyz789",
- *   expiry: new Date("2024-12-31"),
+ * // Basic exported cookie
+ * const cookie: ExportedCookie = {
+ *   domain: 'example.com',
+ *   name: 'session',
+ *   value: 'abc123',
+ *   expiry: new Date('2024-12-31'),
  *   meta: {
- *     file: "Cookies.sqlite",
- *     browser: "Firefox",
- *     decrypted: true,
- *     secure: true,
- *     httpOnly: true,
- *     path: "/"
+ *     file: '/path/to/cookies.db'
  *   }
  * };
  *
- * // Cookie with infinite expiry (session cookie)
- * const persistentCookie: ExportedCookie = {
- *   domain: "app.example.com",
- *   name: "preferences",
- *   value: "theme=dark",
- *   expiry: "Infinity"
- * };
+ * // Process exported cookies
+ * function processCookies(cookies: ExportedCookie[]): string[] {
+ *   return cookies.map(cookie => `${cookie.name}=${cookie.value}`);
+ * }
  *
- * // Subdomain cookie example
- * const subdomainCookie: ExportedCookie = {
- *   domain: ".example.com",  // Note the leading dot for all subdomains
- *   name: "tracking",
- *   value: "user123",
- *   meta: {
- *     browser: "Chrome",
- *     decrypted: true
- *   }
- * };
+ * // Filter expired cookies
+ * function filterExpired(cookies: ExportedCookie[]): ExportedCookie[] {
+ *   const now = new Date();
+ *   return cookies.filter(cookie =>
+ *     cookie.expiry === "Infinity" ||
+ *     (cookie.expiry instanceof Date && cookie.expiry > now)
+ *   );
+ * }
  * ```
  */
-interface ExportedCookie {
-    /** The domain the cookie belongs to. */
-    domain: string;
-    /** The name of the cookie. */
-    name: string;
-    /** The value of the cookie. */
-    value: string;
-    /** When the cookie expires (Date object, "Infinity", or undefined). */
-    expiry?: Date | "Infinity";
-    /** Additional metadata about the cookie. */
-    meta?: {
-        /** Path to the file the cookie was exported from. */
-        file?: string;
-        /** Browser the cookie was exported from. */
-        browser?: string;
-        /** Whether the cookie value was decrypted. */
-        decrypted?: boolean;
-        /** Any additional metadata. */
-        [key: string]: unknown;
-    };
-}
+type ExportedCookie = z.infer<typeof ExportedCookieSchema>;
+/**
+ * Schema for cookie render options
+ */
+declare const RenderOptionsSchema: z.ZodObject<{
+    format: z.ZodOptional<z.ZodEnum<["merged", "grouped"]>>;
+    separator: z.ZodOptional<z.ZodString>;
+    showFilePaths: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    format?: "merged" | "grouped" | undefined;
+    separator?: string | undefined;
+    showFilePaths?: boolean | undefined;
+}, {
+    format?: "merged" | "grouped" | undefined;
+    separator?: string | undefined;
+    showFilePaths?: boolean | undefined;
+}>;
+/**
+ * Type definition for render options
+ */
+type RenderOptions = z.infer<typeof RenderOptionsSchema>;
 
 /**
  * Dynamic import for the getCookie function.