@ouroboros/browser 0.5.6 → 0.5.7

package/cookies.d.ts

@@ -7,6 +7,18 @@
  * @copyright Ouroboros Coding Inc.
  * @created 2018-11-24
  */
+export type setOptions = {
+    Domain?: string;
+    Expires?: number;
+    Path?: string;
+    Secure?: boolean;
+    SameSite?: 'Strict' | 'Lax' | 'None';
+    Partitioned?: boolean;
+};
+export type removeOptions = {
+    Domain?: string;
+    Path?: string;
+};
 /**
  * Get
  *
@@ -15,38 +27,38 @@
  * @name get
  * @access public
  * @param {string} name The name of the cookie to fetch
- * @param {string} defaulReturn The default value to return if no cookie is found
+ * @param {string} defaultReturn The default value to return if no cookie is found
  * @return {string | object | null}
  */
-declare function get(name: string, defaulReturn: string | null | undefined): string | object | null;
+declare function get(name?: string, defaultReturn?: string): string | object | null;
 /**
  * Remove
  *
- * Deletes a cookie
+ * Removes a cookie.
  *
- * @name remove
- * @access public
- * @param {string} name The name of the cookie to delete
- * @param {string?} domain The domain of the cookie
- * @param {string?} path The path of the cookie
- * @return {void}
+ * @deprecated The (domain, path) positional signature is deprecated and will be
+ * removed in a future version. Pass an options object instead:
+ * remove(name, { Domain, Path })
  */
 declare function remove(name: string, domain?: string, path?: string): void;
 /**
- * Set
+ * Remove
  *
- * Sets a cookie
+ * Removes a cookie using an options object.
+ */
+declare function remove(name: string, options?: removeOptions): void;
+/**
+ * Sets a cookie.
  *
- * @name set
- * @access public
- * @param {string} name The name of the cookie
- * @param {string} value The value to store
- * @param {number} expires The number of seconds before the cookie expires
- * @param {string?} domain The optional domain to set the cookie on
- * @param {string?} path The optional path of the cookie
- * @return {void}
+ * @deprecated The (expires, domain, path) positional signature is deprecated
+ * and will be removed in a future version. Pass an options object instead:
+ * set(name, value, { Expires, Domain, Path })
  */
 declare function set(name: string, value: string, expires?: number, domain?: string, path?: string): void;
+/**
+ * Sets a cookie using an options object.
+ */
+declare function set(name: string, value: string, options?: setOptions): void;
 declare const cookies: {
     get: typeof get;
     remove: typeof remove;

package/cookies.js

@@ -15,77 +15,153 @@
  * @name get
  * @access public
  * @param {string} name The name of the cookie to fetch
- * @param {string} defaulReturn The default value to return if no cookie is found
+ * @param {string} defaultReturn The default value to return if no cookie is found
  * @return {string | object | null}
  */
-function get(name, defaulReturn) {
+function get(name, defaultReturn) {
     // Set the default if no value is passed
-    if (typeof defaulReturn === 'undefined') {
-        defaulReturn = null;
-    }
+    const defRet = (typeof defaultReturn === 'undefined')
+        ? null
+        : defaultReturn;
     // Parse all cookies
     const oCookies = {};
     const lCookies = document.cookie.split(';');
     for (const s of lCookies) {
-        const l = s.split('=');
-        oCookies[l[0].trimStart()] = decodeURIComponent(l[1]);
+        const i = s.indexOf('=');
+        if (i === -1)
+            continue;
+        oCookies[s.slice(0, i).trimStart()] = decodeURIComponent(s.slice(i + 1));
     }
     // If there's no name, return all
     if (typeof name === 'undefined') {
         return oCookies;
     }
     // If the cookie exists return it, else return the default
-    return (name in oCookies) ? oCookies[name] : defaulReturn;
+    return (name in oCookies) ? oCookies[name] : defRet;
 }
 /**
  * Remove
  *
- * Deletes a cookie
+ * Removes a cookie.
  *
  * @name remove
  * @access public
- * @param {string} name The name of the cookie to delete
- * @param {string?} domain The domain of the cookie
- * @param {string?} path The path of the cookie
- * @return {void}
+ * @param name The name of the cookie to delete
+ * @param options The optional settings: Domain, Path
  */
-function remove(name, domain, path) {
-    set(name, '', -86400, domain, path);
+function remove(name, optionsOrDomain, ...rest) {
+    // Init options
+    let options = {};
+    // Detect new options-object format
+    if (optionsOrDomain !== null && typeof optionsOrDomain === 'object') {
+        options = { ...optionsOrDomain };
+    }
+    // Detect legacy (deprecated) format
+    else if (typeof optionsOrDomain === 'string' || rest.length > 0) {
+        console.warn('remove: passing (domain, path) as separate arguments is ' +
+            'deprecated and will be removed in a future version. Pass an ' +
+            'options object instead: remove(name, { Domain, Path })');
+        const [path] = rest;
+        options = {
+            Domain: optionsOrDomain,
+            Path: path
+        };
+    }
+    // No options passed
+    else {
+        options = {};
+    }
+    // Add the expires to clear it immediately
+    options.Expires = 0;
+    // Call set with no value and a time in the past
+    set(name, '', options);
 }
 /**
  * Set
  *
- * Sets a cookie
+ * Sets a cookie.
  *
- * @name set
- * @access public
- * @param {string} name The name of the cookie
- * @param {string} value The value to store
- * @param {number} expires The number of seconds before the cookie expires
- * @param {string?} domain The optional domain to set the cookie on
- * @param {string?} path The optional path of the cookie
- * @return {void}
+ * @param name The name of the cookie
+ * @param value The value to store
+ * @param options The optional settings: Domain, Expires, Path, Secure,
+ * SameSite, Partitioned
  */
-function set(name, value, expires, domain, path) {
+function set(name, value, optionsOrExpires, ...rest) {
+    // If no name was passed
+    if (!name) {
+        throw new Error('set: name is required');
+    }
+    // Init options
+    let options;
+    // Detect new options-object format
+    if (optionsOrExpires !== null && typeof optionsOrExpires === 'object') {
+        options = optionsOrExpires;
+    }
+    // Detect legacy (deprecated) format
+    else if (typeof optionsOrExpires === 'number' || rest.length > 0) {
+        // Warn the user to update the code
+        console.warn('set: passing (expires, domain, path) as separate arguments is ' +
+            'deprecated and will be removed in a future version. Pass an ' +
+            'options object instead: set(name, value, { Expires, Domain, ' +
+            'Path })');
+        // Pull out the domain and path if they exist
+        const [domain, path] = rest;
+        // Create the new format from the old format
+        options = {
+            Expires: optionsOrExpires,
+            Domain: domain,
+            Path: path,
+        };
+    }
+    // No options passed
+    else {
+        options = {};
+    }
     // Init the sections with the name and value
     const lSections = [
         `${name}=${encodeURIComponent(value)}`
     ];
     // If we have an expires
-    if (expires) {
+    if (options.Expires) {
         // Generate the expires time
         const d = new Date();
-        d.setTime(d.getTime() + (expires * 1000));
+        d.setTime(d.getTime() + (options.Expires * 1000));
         // Add it to the sections
-        lSections.push(`expires=${d.toUTCString()}`);
+        lSections.push(`Expires=${d.toUTCString()}`);
     }
     // If we have a domain
-    if (domain) {
-        lSections.push(`domain=${domain}`);
+    if (options.Domain) {
+        lSections.push(`Domain=${options.Domain}`);
     }
     // If we have a path
-    if (path) {
-        lSections.push(`path=${path}`);
+    if (options.Path) {
+        lSections.push(`Path=${options.Path}`);
+    }
+    // If we want secure
+    if (options.Secure) {
+        lSections.push('Secure');
+    }
+    // If we want SameSite
+    if (options.SameSite) {
+        // If the value is 'None' and Secure is not turned on
+        if (options.SameSite === 'None' && !options.Secure) {
+            // Warn the user this is invalid
+            console.warn('set: SameSite as None without Secure is invalid and the ' +
+                'browser will most likely fail to create the cookie.');
+        }
+        // Set it
+        lSections.push(`SameSite=${options.SameSite}`);
+    }
+    // If we want partitioned
+    if (options.Partitioned) {
+        // If the value is true and Secure is not turned on
+        if (options.Partitioned && !options.Secure) {
+            // Warn the user this is invalid
+            console.warn('set: Partitioned without Secure is invalid and the ' +
+                'browser will most likely fail to create the cookie.');
+        }
+        // Set it
+        lSections.push('Partitioned');
     }
     // Set the cookie by combining the sections
     document.cookie = lSections.join('; ');

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ouroboros/browser",
-	"version": "0.5.6",
+	"version": "0.5.7",
 	"description": "Package to handle common browser functionality.",
 	"main": "index.js",
 	"types": "index.d.ts",

package/src/cookies.ts

@@ -8,6 +8,20 @@
  * @created 2018-11-24
  */
 
+// Types
+export type setOptions = {
+	Domain?: string,
+	Expires?: number,
+	Path?: string,
+	Secure?: boolean,
+	SameSite?: 'Strict' | 'Lax' | 'None',
+	Partitioned?: boolean
+}
+export type removeOptions = {
+	Domain?: string,
+	Path?: string
+}
+
 /**
  * Get
  *
@@ -16,22 +30,26 @@
  * @name get
  * @access public
  * @param {string} name The name of the cookie to fetch
- * @param {string} defaulReturn The default value to return if no cookie is found
+ * @param {string} defaultReturn The default value to return if no cookie is found
  * @return {string | object | null}
  */
-function get(name: string, defaulReturn: string | null | undefined): string | object | null {
+function get(
+	name?: string,
+	defaultReturn?: string
+): string | object | null {
 
 	// Set the default if no value is passed
-	if(typeof defaulReturn === 'undefined') {
-		defaulReturn = null;
-	}
+	const defRet = (typeof defaultReturn === 'undefined')
+		? null
+		: defaultReturn;
 
 	// Parse all cookies
-	const oCookies: Record<string, string> = {};
+	const oCookies: Record<string, string> = { };
 	const lCookies = document.cookie.split(';');
 	for(const s of lCookies) {
-		const l = s.split('=');
-		oCookies[l[0].trimStart()] = decodeURIComponent(l[1]);
+		const i = s.indexOf('=');
+		if (i === -1) continue;
+		oCookies[s.slice(0, i).trimStart()] = decodeURIComponent(s.slice(i + 1));
 	}
 
 	// If there's no name, return all
@@ -40,40 +58,147 @@ function get(name: string, defaulReturn: string | null | undefined): string | ob
 	}
 
 	// If the cookie exists return it, else return the default
-	return (name in oCookies) ? oCookies[name] : defaulReturn;
+	return (name in oCookies) ? oCookies[name] : defRet;
 }
 
 /**
  * Remove
  *
- * Deletes a cookie
+ * Removes a cookie.
+ *
+ * @deprecated The (domain, path) positional signature is deprecated and will be
+ * removed in a future version. Pass an options object instead:
+ * remove(name, { Domain, Path })
+ */
+function remove(name: string, domain?: string, path?: string): void;
+
+/**
+ * Remove
+ *
+ * Removes a cookie using an options object.
+ */
+function remove(name: string, options?: removeOptions): void;
+
+/**
+ * Remove
+ *
+ * Removes a cookie.
  *
  * @name remove
  * @access public
- * @param {string} name The name of the cookie to delete
- * @param {string?} domain The domain of the cookie
- * @param {string?} path The path of the cookie
- * @return {void}
+ * @param name The name of the cookie to delete
+ * @param options The optional settings: Domain, Path
  */
-function remove(name: string, domain?: string, path?: string): void {
-	set(name, '', -86400, domain, path);
+function remove(
+	name: string,
+	optionsOrDomain?: removeOptions | string,
+	...rest: [ path?: string ]
+): void {
+
+	// Init options
+	let options: setOptions = { };
+
+	// Detect new options-object format
+	if(optionsOrDomain !== null && typeof optionsOrDomain === 'object') {
+		options = { ...optionsOrDomain };
+	}
+
+	// Detect legacy (deprecated) format
+	else if(typeof optionsOrDomain === 'string' || rest.length > 0) {
+		console.warn(
+			'remove: passing (domain, path) as separate arguments is ' +
+			'deprecated and will be removed in a future version. Pass an ' +
+			'options object instead: remove(name, { Domain, Path })'
+		);
+		const [ path ] = rest;
+		options = {
+			Domain: optionsOrDomain,
+			Path: path
+		}
+	}
+
+	// No options passed
+	else {
+		options = {};
+	}
+
+	// Add the expires to clear it immediately
+	options.Expires = 0;
+
+	// Call set with no value and a time in the past
+	set(name, '', options);
 }
 
+/**
+ * Sets a cookie.
+ *
+ * @deprecated The (expires, domain, path) positional signature is deprecated
+ * and will be removed in a future version. Pass an options object instead:
+ * set(name, value, { Expires, Domain, Path })
+ */
+function set(name: string, value: string, expires?: number, domain?: string, path?: string): void;
+
+/**
+ * Sets a cookie using an options object.
+ */
+function set(name: string, value: string, options?: setOptions): void;
+
 /**
  * Set
  *
- * Sets a cookie
+ * Sets a cookie.
  *
- * @name set
- * @access public
- * @param {string} name The name of the cookie
- * @param {string} value The value to store
- * @param {number} expires The number of seconds before the cookie expires
- * @param {string?} domain The optional domain to set the cookie on
- * @param {string?} path The optional path of the cookie
- * @return {void}
+ * @param name The name of the cookie
+ * @param value The value to store
+ * @param options The optional settings: Domain, Expires, Path, Secure,
+ * SameSite, Partitioned
  */
-function set(name: string, value: string, expires?: number, domain?: string, path?: string): void {
+function set(
+	name: string,
+	value: string,
+	optionsOrExpires?: setOptions | number,
+	...rest: [domain?: string, path?: string]
+): void {
+
+	// If no name was passed
+	if(!name) {
+		throw new Error('set: name is required');
+	}
+
+	// Init options
+	let options: setOptions;
+
+	// Detect new options-object format
+	if(optionsOrExpires !== null && typeof optionsOrExpires === 'object') {
+		options = optionsOrExpires;
+	}
+
+	// Detect legacy (deprecated) format
+	else if(typeof optionsOrExpires === 'number' || rest.length > 0) {
+
+		// Warn the user to update the code
+		console.warn(
+			'set: passing (expires, domain, path) as separate arguments is ' +
+			'deprecated and will be removed in a future version. Pass an ' +
+			'options object instead: set(name, value, { Expires, Domain, ' +
+			'Path })'
+		);
+
+		// Pull out the domain and path if they exist
+		const [domain, path] = rest;
+
+		// Create the new format from the old format
+		options = {
+			Expires: optionsOrExpires,
+			Domain: domain,
+			Path: path,
+		};
+	}
+
+	// No options passed
+	else {
+		options = {};
+	}
 
 	// Init the sections with the name and value
 	const lSections = [
@@ -81,24 +206,63 @@ function set(name: string, value: string, expires?: number, domain?: string, pat
 	];
 
 	// If we have an expires
-	if(expires) {
+	if(options.Expires) {
 
 		// Generate the expires time
 		const d = new Date();
-		d.setTime(d.getTime() + (expires * 1000))
+		d.setTime(d.getTime() + (options.Expires * 1000));
 
 		// Add it to the sections
-		lSections.push(`expires=${d.toUTCString()}`);
+		lSections.push(`Expires=${d.toUTCString()}`);
 	}
 
 	// If we have a domain
-	if(domain) {
-		lSections.push(`domain=${domain}`);
+	if(options.Domain) {
+		lSections.push(`Domain=${options.Domain}`);
 	}
 
 	// If we have a path
-	if(path) {
-		lSections.push(`path=${path}`);
+	if(options.Path) {
+		lSections.push(`Path=${options.Path}`);
+	}
+
+	// If we want secure
+	if(options.Secure) {
+		lSections.push('Secure');
+	}
+
+	// If we want SameSite
+	if(options.SameSite) {
+
+		// If the value is 'None' and Secure is not turned on
+		if(options.SameSite === 'None' && !options.Secure) {
+
+			// Warn the user this is invalid
+			console.warn(
+				'set: SameSite as None without Secure is invalid and the ' +
+				'browser will most likely fail to create the cookie.'
+			)
+		}
+
+		// Set it
+		lSections.push(`SameSite=${options.SameSite}`);
+	}
+
+	// If we want partitioned
+	if(options.Partitioned) {
+
+		// If the value is true and Secure is not turned on
+		if(options.Partitioned && !options.Secure) {
+
+			// Warn the user this is invalid
+			console.warn(
+				'set: Partitioned without Secure is invalid and the ' +
+				'browser will most likely fail to create the cookie.'
+			);
+		}
+
+		// Set it
+		lSections.push('Partitioned');
 	}
 
 	// Set the cookie by combining the sections
@@ -107,4 +271,4 @@ function set(name: string, value: string, expires?: number, domain?: string, pat
 
 // Default export
 const cookies = { get, remove, set };
-export default cookies;
+export default cookies;