docs: encoding.ts

diff --git a/src/utils/encoding.ts b/src/utils/encoding.ts
index 939b85fe48ff97044e5fac1c0719b26afaf3c514..62732f66c93896ac3a4a00c1997b53c5c7697f3e 100644 (file)
--- a/src/utils/encoding.ts
+++ b/src/utils/encoding.ts
@@ -1,18 +1,19 @@
 import { warn } from 'vue'
 
 /**
- * Encoding Rules
- * ␣ = Space
- * Path: ␣ " < > # ? { }
- * Query: ␣ " < > # & =
- * Hash: ␣ " < > `
+ * Encoding Rules ␣ = Space Path: ␣ " < > # ? { } Query: ␣ " < > # & = Hash: ␣ "
+ * < > `
  *
- * On top of that the RFC3986 (https://tools.ietf.org/html/rfc3986#section-2.2) defines some extra characters to be encoded. Most browsers do not encode them in encodeURI https://github.com/whatwg/url/issues/369 so it may be safer to also encode !'()*. Leaving unencoded only ASCII alphanum plus -._~
- * This extra safety should be applied to query by patching the string returned by encodeURIComponent
- * encodeURI also encodes [\]^
- * \ should be encoded to avoid ambiguity. Browsers (IE, FF, C) transform a \ into a / if directly typed in
- * ` should also be encoded everywhere because some browsers like FF encode it when directly written while others don't
- * Safari and IE don't encode "<>{}` in hash
+ * On top of that, the RFC3986 (https://tools.ietf.org/html/rfc3986#section-2.2)
+ * defines some extra characters to be encoded. Most browsers do not encode them
+ * in encodeURI https://github.com/whatwg/url/issues/369, so it may be safer to
+ * also encode `!'()*`. Leaving unencoded only ASCII alphanumeric(`a-zA-Z0-9`)
+ * plus `-._~`. This extra safety should be applied to query by patching the
+ * string returned by encodeURIComponent encodeURI also encodes `[\]^`. `\`
+ * should be encoded to avoid ambiguity. Browsers (IE, FF, C) transform a `\`
+ * into a `/` if directly typed in. The _backtick_ (`````) should also be
+ * encoded everywhere because some browsers like FF encode it when directly
+ * written while others don't. Safari and IE don't encode ``"<>{}``` in hash.
  */
 // const EXTRA_RESERVED_RE = /[!'()*]/g
 // const encodeReservedReplacer = (c: string) => '%' + c.charCodeAt(0).toString(16)
@@ -31,6 +32,14 @@ const ENC_CURLY_OPEN_RE = /%7B/g // {
 const ENC_PIPE_RE = /%7C/g // |
 const ENC_CURLY_CLOSE_RE = /%7D/g // }
 
+/**
+ * Encode characters that need to be encoded on the path, search and hash
+ * sections of the URL.
+ *
+ * @internal
+ * @param text - string to encode
+ * @returns encoded string
+ */
 function commonEncode(text: string | number): string {
   return encodeURI('' + text)
     .replace(ENC_PIPE_RE, '|')
@@ -38,6 +47,12 @@ function commonEncode(text: string | number): string {
     .replace(ENC_BRACKET_CLOSE_RE, ']')
 }
 
+/**
+ * Encode characters that need to be encoded on the hash section of the URL.
+ *
+ * @param text - string to encode
+ * @returns encoded string
+ */
 export function encodeHash(text: string): string {
   return commonEncode(text)
     .replace(ENC_CURLY_OPEN_RE, '{')
@@ -45,6 +60,13 @@ export function encodeHash(text: string): string {
     .replace(ENC_CARET_RE, '^')
 }
 
+/**
+ * Encode characters that need to be encoded query keys and values on the query
+ * section of the URL.
+ *
+ * @param text - string to encode
+ * @returns encoded string
+ */
 export function encodeQueryProperty(text: string | number): string {
   return commonEncode(text)
     .replace(HASH_RE, '%23')
@@ -56,16 +78,37 @@ export function encodeQueryProperty(text: string | number): string {
     .replace(ENC_CARET_RE, '^')
 }
 
+/**
+ * Encode characters that need to be encoded on the path section of the URL.
+ *
+ * @param text - string to encode
+ * @returns encoded string
+ */
 export function encodePath(text: string): string {
   return commonEncode(text)
     .replace(HASH_RE, '%23')
     .replace(IM_RE, '%3F')
 }
 
+/**
+ * Encode characters that need to be encoded on the path section of the URL as a
+ * param. This function encodes everything {@link encodePath} does plus the
+ * slash (`/`) character.
+ *
+ * @param text - string to encode
+ * @returns encoded string
+ */
 export function encodeParam(text: string): string {
   return encodePath(text).replace(SLASH_RE, '%2F')
 }
 
+/**
+ * Decode text using `decodeURIComponent`. Returns the original text if it
+ * fails.
+ *
+ * @param text - string to decode
+ * @returns decoded string
+ */
 export function decode(text: string): string {
   try {
     return decodeURIComponent(text)