Data Utilities

/**
 * Converts a UTF-8 string to bytes
 * @param str - UTF-8 string to convert
 * @returns Uint8Array containing UTF-8 encoded bytes
 */
function from_string(str);

/**
 * Converts bytes to UTF-8 string
 * @param bytes - Uint8Array to convert to string
 * @returns UTF-8 decoded string
 * @throws TypeError if bytes contain invalid UTF-8
 */
function to_string(bytes);

/**
 * Converts hexadecimal string to bytes
 * @param hexString - Hex string (e.g., "48656c6c6f")
 * @returns Uint8Array with decoded bytes
 * @throws Error if hex string is invalid
 */
function from_hex(hexString);

/**
 * Converts bytes to hexadecimal string
 * @param bytes - Uint8Array to convert
 * @returns Lowercase hex string
 */
function to_hex(bytes);

/**
 * Converts base64 string to bytes
 * @param base64String - Base64 encoded string
 * @param variant - Base64 variant (see base64_variants)
 * @returns Uint8Array with decoded bytes
 */
function from_base64(base64String, variant);

/**
 * Converts bytes to base64 string
 * @param bytes - Uint8Array to encode
 * @param variant - Base64 variant (see base64_variants)
 * @returns Base64 encoded string
 */
function to_base64(bytes, variant);

// String conversion
const message = "Hello, World!";
const messageBytes = sodium.from_string(message);
const backToString = sodium.to_string(messageBytes);

// Hex conversion
const key = sodium.from_hex("0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef");
const keyHex = sodium.to_hex(key);

// Base64 conversion
const data = sodium.randombytes_buf(32);
const base64 = sodium.to_base64(data, sodium.base64_variants.URLSAFE);
const decodedData = sodium.from_base64(base64, sodium.base64_variants.URLSAFE);

/**
 * Constant-time comparison of two byte arrays
 * @param a - First byte array
 * @param b - Second byte array  
 * @returns -1 if a < b, 0 if a === b, 1 if a > b
 * @throws TypeError if arrays have different lengths
 */
function compare(a, b);

/**
 * Constant-time equality comparison
 * @param a - First byte array
 * @param b - Second byte array
 * @returns true if arrays are equal, false otherwise
 * @throws TypeError if arrays have different lengths
 */
function memcmp(a, b);

/**
 * Increments a byte array as a big-endian integer
 * @param bytes - Uint8Array to increment (modified in place)
 */
function increment(bytes);

/**
 * Adds two byte arrays as big-endian integers
 * @param a - First array (modified in place with result)
 * @param b - Second array to add
 * @throws TypeError if arrays have different lengths
 */
function add(a, b);

/**
 * Checks if all bytes in array are zero
 * @param bytes - Uint8Array to check
 * @returns true if all bytes are zero, false otherwise
 */
function is_zero(bytes);

// Secure comparison
const hash1 = sodium.crypto_generichash(32, data1);
const hash2 = sodium.crypto_generichash(32, data2);
const areEqual = sodium.memcmp(hash1, hash2);

// Increment nonce
const nonce = new Uint8Array(24);
sodium.increment(nonce); // nonce is now [0,0,0,...,0,1]
sodium.increment(nonce); // nonce is now [0,0,0,...,0,2]

// Add arrays
const a = new Uint8Array([255, 255]);
const b = new Uint8Array([0, 1]);
sodium.add(a, b); // a is now [0, 0] (overflow)

/**
 * Securely zeroes out memory
 * @param bytes - Uint8Array to zero (modified in place)
 */
function memzero(bytes);

/**
 * Pads data to a multiple of block size
 * @param buffer - Data to pad
 * @param blocksize - Block size for padding
 * @returns Padded data
 */
function pad(buffer, blocksize);

/**
 * Removes padding from data
 * @param buffer - Padded data
 * @param blocksize - Block size used for padding
 * @returns Unpadded data
 */
function unpad(buffer, blocksize);

// Secure memory clearing
const sensitiveKey = sodium.crypto_secretbox_keygen();
// ... use key ...
sodium.memzero(sensitiveKey); // Clear from memory

// Padding for block ciphers
const data = sodium.from_string("Hello");
const padded = sodium.pad(data, 16); // Pad to 16-byte blocks
const unpadded = sodium.unpad(padded, 16); // Remove padding

const base64_variants = {
  ORIGINAL: 1,           // Standard base64 with padding
  ORIGINAL_NO_PADDING: 3, // Standard base64 without padding
  URLSAFE: 5,            // URL-safe base64 with padding
  URLSAFE_NO_PADDING: 7  // URL-safe base64 without padding (recommended)
};

/**
 * Returns the libsodium version string
 * @returns Version string (e.g., "1.0.18")
 */
function sodium_version_string();

/**
 * Lists all available function names
 * @returns Array of function names sorted alphabetically
 */
function symbols();

/**
 * Returns available output formats
 * @returns Array of format names
 */
function output_formats();

/**
 * Promise that resolves when library is ready to use
 */
const ready;

// Check library version
console.log("libsodium version:", sodium.sodium_version_string());

// List all available functions
const allFunctions = sodium.symbols();
console.log("Available functions:", allFunctions.length);

// Wait for library initialization
await sodium.ready;
console.log("Library is ready!");

// Version information
const SODIUM_LIBRARY_VERSION_MAJOR;
const SODIUM_LIBRARY_VERSION_MINOR;
const SODIUM_VERSION_STRING;

// Comparison results
const COMPARE_LESS = -1;
const COMPARE_EQUAL = 0;
const COMPARE_GREATER = 1;

// Different output formats for the same operation
const key = sodium.crypto_secretbox_keygen();

const keyHex = sodium.to_hex(key);
const keyBase64 = sodium.to_base64(key, sodium.base64_variants.URLSAFE_NO_PADDING);

try {
  const decoded = sodium.from_hex("invalid_hex_string");
} catch (error) {
  console.error("Hex decoding failed:", error.message);
}

try {
  const decoded = sodium.from_base64("invalid_base64_string");
} catch (error) {
  console.error("Base64 decoding failed:", error.message);
}