.. _workflow-base64:

Base64 Encode/Decode
=====================

- Through the Base64 feature, you can encode and decode data using the Base64 encoding method.
- The main supported features are as follows:

    - **Base64 Encoding** : Encodes data using the Base64 encoding method.
    - **Base64 Decoding** : Decodes data using the Base64 encoding method.
    - **Base64 URL Encoding** : Encodes data using the Base64 URL encoding method.
    - **Base64 URL Decoding** : Decodes data using the Base64 URL encoding method.

Standard Base64 vs URL-safe Base64
-----------------------------------

There are two types of Base64 encoding available:

**Standard Base64**
    - Uses characters: ``A-Z``, ``a-z``, ``0-9``, ``+``, ``/``, ``=`` (for padding)
    - Suitable for general data storage and transmission
    - May cause issues when used in URLs due to special characters

**URL-safe Base64**
    - Uses characters: ``A-Z``, ``a-z``, ``0-9``, ``-``, ``_`` (no padding)
    - Character substitutions: ``+`` → ``-``, ``/`` → ``_``, padding ``=`` removed
    - Safe for use in URLs, JWT tokens, and file names
    - Recommended for web applications and API tokens

Character Mapping
------------------

.. list-table:: Base64 Character Differences
   :header-rows: 1
   :widths: 30 35 35

   * - Purpose
     - Standard Base64
     - URL-safe Base64
   * - Plus character
     - ``+``
     - ``-``
   * - Slash character
     - ``/``
     - ``_``
   * - Padding
     - ``=`` (included)
     - (removed)
   * - Use cases
     - General encoding
     - URLs, JWT, filenames

Examples with Different Results
-------------------------------

Here are examples showing when standard and URL-safe encoding produce different results:

**Example 1: Special characters**

.. code-block:: javascript

   Input: "Hello>World?"
   ${_base64.encode('Hello>World?')}      // Result: SGVsbG8+V29ybGQ/
   ${_base64.urlEncode('Hello>World?')}   // Result: SGVsbG8-V29ybGQ_

**Example 2: Padding differences**

.. code-block:: javascript

   Input: "Test+Data/Info"
   ${_base64.encode('Test+Data/Info')}      // Result: VGVzdCtEYXRhL0luZm8=
   ${_base64.urlEncode('Test+Data/Info')}   // Result: VGVzdCtEYXRhL0luZm8

**Example 3: Complex special characters**

.. code-block:: javascript

   Input: "Data??>><<++//=="
   ${_base64.encode('Data??>><<++//==')}      // Result: RGF0YT8/Pj48PCsrLy89PQ==
   ${_base64.urlEncode('Data??>><<++//==')}   // Result: RGF0YT8_Pj48PCsrLy89PQ

URL Usage Examples
------------------

**Problematic: Standard Base64 in URLs**

.. code-block:: text

   https://example.com/api?token=dXNlcjpwYXNzd29yZEBkb21haW4uY29tL3BhdGg/cXVlcnk9dmFsdWU=
   
   Issues:
   - '+' character interpreted as space in URLs
   - '/' character interpreted as path separator
   - '=' character can cause parsing issues

**Recommended: URL-safe Base64 in URLs**

.. code-block:: text

   https://example.com/api?token=dXNlcjpwYXNzd29yZEBkb21haW4uY29tL3BhdGg_cXVlcnk9dmFsdWU
   
   Benefits:
   - Safe for URL parameters
   - No special character conflicts
   - Cleaner appearance without padding

Basic Usage Examples
--------------------

.. code-block:: javascript

   // Standard Base64 encoding/decoding
   ${_base64.encode('hello world! base64 test')}
   ${_base64.decode('aGVsbG8gd29ybGQhIGJhc2U2NCB0ZXN0')}
   
   // URL-safe Base64 encoding/decoding  
   ${_base64.urlEncode('hello world! base64 test')}
   ${_base64.urlDecode('aGVsbG8gd29ybGQhIGJhc2U2NCB0ZXN0')}

When to Use Which Method
------------------------

**Use Standard Base64 (encode/decode) when:**
    - Storing data in databases
    - General data transmission
    - Email attachments
    - No URL/filename restrictions

**Use URL-safe Base64 (urlEncode/urlDecode) when:**
    - Passing data in URL parameters
    - Creating JWT tokens
    - Generating file names
    - API authentication tokens
    - Any web-based application