@alessiofrittoli/web-utils/dist/storage/Cookie.d.ts

Common TypeScript web utilities

import { TypedMap } from '../map.js';

/** The Cookie Priority. */
declare enum Priority {
    /** Low priority. */
    Low = "Low",
    /** Medium priority (default). */
    Medium = "Medium",
    /** High priority. */
    High = "High"
}
/**
 * Controls whether or not a cookie is sent with cross-site requests, providing some protection against cross-site request forgery attacks ([CSRF](https://developer.mozilla.org/en-US/docs/Glossary/CSRF)).
 *
 * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value)
 */
declare enum SameSite {
    /**
     * The browser sends the cookie only for same-site requests.
     *
     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#strict)
     */
    Strict = "Strict",
    /**
     * The cookie is not sent on cross-site requests, such as on requests to load images or frames, but is sent when a user is navigating to the origin site from an external site.
     *
     * @warning Not all browsers set SameSite=Lax by default. See [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#browser_compatibility) for details.
     *
     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#lax)
     */
    Lax = "Lax",
    /**
     * The browser sends the cookie with both cross-site and same-site requests.
     *
     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#none)
     */
    None = "None"
}
/**
 * Interface representing Cookie properties before it get parsed.
 *
 */
interface RawCookie<K = string, V = unknown> {
    /**
     * The Cookie name.
     *
     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie-namecookie-value)
     */
    name: K;
    /**
     * The Cookie value.
     *
     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie-namecookie-value)
     */
    value?: V;
    /**
     * Defines the host to which the cookie will be sent.
     *
     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#domaindomain-value)
     */
    domain?: string;
    /**
     * Indicates the maximum lifetime of the cookie.
     *
     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#expiresdate)
     */
    expires?: string | number | Date;
    /**
     * Forbids JavaScript from accessing the cookie, for example, through the [`Document.cookie`](https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie) property.
     *
     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#httponly)
     */
    httpOnly?: boolean;
    /**
     * Indicates the number of seconds until the cookie expires.
     *
     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#max-agenumber)
     */
    maxAge?: number;
    /**
     * Indicates that the cookie should be stored using partitioned storage.
     *
     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#partitioned)
     */
    partitioned?: boolean;
    /**
     * Indicates the path that must exist in the requested URL for the browser to send the `Cookie` header.
     *
     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#pathpath-value)
     */
    path?: string;
    /**
     * Controls whether or not a cookie is sent with cross-site requests, providing some protection against cross-site request forgery attacks ([CSRF](https://developer.mozilla.org/en-US/docs/Glossary/CSRF)).
     *
     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value)
     */
    sameSite?: SameSite;
    /**
     * Indicates that the cookie is sent to the server only when a request is made with the https: scheme.
     *
     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#secure)
     */
    secure?: boolean;
    /**
     * Defines the Cookie priority.
     *
     */
    priority?: Priority;
}
/**
 * Interface representing Cookie properties after it get parsed.
 *
 */
interface ParsedCookie<K = string, V = unknown> extends Omit<RawCookie<K, V>, 'expires'> {
    /**
     * Indicates the maximum lifetime of the cookie.
     *
     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#expiresdate)
     */
    expires?: Date;
}
/**
 * Map representation of a parsed Cookie.
 *
 */
type ParsedCookieMap<K = string, V = unknown> = TypedMap<ParsedCookie<K, V>, false>;
/**
 * Easly handle cookies.
 *
 */
declare class Cookie {
    /**
     * Get a cookie by cookie name from `Document.cookie`.
     *
     * @param	name The name of the cookie.
     * @returns	The found parsed cookie or `undefined` if no cookie has been found in `Document.cookie`.
     */
    static get<T, K extends string | number | symbol = string>(name: K): (K extends infer T_1 extends keyof Record<K, T> ? { [P in T_1]: ParsedCookieMap<P, Record<K, T>[P]>; } : never)[K] | undefined;
    /**
     * Get all cookies from `Document.cookie`.
     *
     * @returns	The parsed cookie found in `Document.cookie`.
     */
    static getAll<T extends Record<string, unknown>>(): TypedMap<keyof T extends infer T_1 extends keyof T ? { [P in T_1]: ParsedCookieMap<P, T[P]>; } : never, true, keyof T>;
    /**
     * Set a cookie to `Document.cookie`.
     *
     * @param	options The cookie options or a parsed Cookie Map.
     * @returns	The set Cookie Map if successful, `false` otherwise.
     */
    static set<K = string, V = unknown>(options: RawCookie<K, V> | ParsedCookieMap<K, V>): false | ParsedCookieMap<K, V>;
    /**
     * Delete a cookie by cookie name from `Document.cookie`.
     *
     * @param name The name of the cookie.
     * @returns	`true` if successful, `false` otherwise.
     */
    static delete(name: string): boolean;
    /**
     * Parse the given cookie options to a Cookie Map.
     *
     * @param	options The cookie options or a parsed Cookie Map.
     * @returns	The parsed Cookie Map.
     */
    static parse<K = string, V = unknown>(options: RawCookie<K, V> | ParsedCookieMap<K, V>): ParsedCookieMap<K, V>;
    /**
     * Stringify a Cookie ready to be stored.
     *
     * @param	options The cookie options or a parsed Cookie Map.
     * @returns	The stringified Cookie ready to be stored.
     */
    static toString<K = string, V = unknown>(options: RawCookie<K, V> | ParsedCookieMap<K, V>): string;
    /**
     * Parse a cookie string to a Cookie Map.
     *
     * @param	cookie The cookie string.
     * @returns	The parsed Cookie Map or `null` if parsing fails.
     */
    static fromString<K = string, V = unknown>(cookie: string): ParsedCookieMap<K, V> | null;
    /**
     * Parse a cookie list string to a Map of cookies.
     *
     * @param	list The cookie list string.
     * @returns	The Map of parsed cookies indexed by the Cookie name.
     */
    static fromListString<T extends Record<string, unknown>, K extends keyof T = keyof T>(list: string): TypedMap<{ [P in K]: ParsedCookieMap<P, T[P]>; }, true, K>;
    /**
     * Parse a value based on the key.
     *
     * @param	value	The value to parse.
     * @param	key		The key associated with the value.
     *
     * @returns	The parsed value.
     */
    private static parseValue;
}

export { Cookie, type ParsedCookie, type ParsedCookieMap, Priority, type RawCookie, SameSite };