Buffer Operations

/**
 * Minimal Buffer implementation for cross-platform compatibility
 * In Node.js: Alias for Node.js Buffer
 * In Browser: Custom implementation extending Uint8Array
 */
interface IsoBuffer extends Uint8Array {
  /**
   * Convert buffer contents to string
   * @param encoding - Output encoding ("utf8" or "base64")
   * @returns String representation of buffer contents
   */
  toString(encoding?: "utf8" | "base64"): string;
  
  /**
   * Create IsoBuffer from various input types
   * @param data - Input data (string or ArrayBufferLike)
   * @param encoding - Input encoding for string data
   * @returns New IsoBuffer instance
   */
  static from(data: string | ArrayBufferLike, encoding?: "utf8" | "base64"): IsoBuffer;
}

/**
 * IsoBuffer constructor/type
 * In Node.js: References Node.js Buffer
 * In Browser: Custom Uint8Array-based implementation
 */
declare const IsoBuffer: {
  new (size: number): IsoBuffer;
  from(data: string | ArrayBufferLike, encoding?: "utf8" | "base64"): IsoBuffer;
};

import { IsoBuffer } from "@fluidframework/common-utils";

// Create from string
const buffer1 = IsoBuffer.from("Hello World", "utf8");
const buffer2 = IsoBuffer.from("SGVsbG8gV29ybGQ=", "base64");

// Create empty buffer
const buffer3 = new IsoBuffer(10);

// Convert to string
const text = buffer1.toString("utf8");
const base64 = buffer1.toString("base64");

// Works the same in both Node.js and Browser
console.log(buffer1.length); // 11
console.log(buffer1[0]); // 72 (ASCII code for 'H')

/**
 * Native Node.js Buffer class (only available in Node.js environment)
 * Provides the full Node.js Buffer API with all methods and optimizations
 * Note: This is not available in browser builds - use IsoBuffer for cross-platform code
 */
class Buffer extends Uint8Array {
  // Full Node.js Buffer API available
  // See Node.js Buffer documentation for complete method list
  static from(data: string | ArrayBufferLike, encoding?: BufferEncoding): Buffer;
  static alloc(size: number, fill?: string | Buffer | Uint8Array | number): Buffer;
  static allocUnsafe(size: number): Buffer;
  toString(encoding?: BufferEncoding): string;
  // ... plus all other Node.js Buffer methods
}

// Only available in Node.js environment
import { Buffer } from "@fluidframework/common-utils";

// Node.js-specific Buffer operations
const nodeBuffer = Buffer.from("Hello Node.js", "utf8");
const allocatedBuffer = Buffer.alloc(10, 0);
const unsafeBuffer = Buffer.allocUnsafe(10);

// All Node.js Buffer methods available
console.log(nodeBuffer.toString("hex"));
console.log(nodeBuffer.readUInt32BE(0));

// For cross-platform code, prefer IsoBuffer:
if (typeof Buffer !== 'undefined') {
  // Node.js environment - can use Buffer
  const buffer = Buffer.from(data);
} else {
  // Browser environment - use IsoBuffer
  const buffer = IsoBuffer.from(data);
}

/**
 * Converts string to ArrayBuffer
 * @param str - Input string
 * @param encoding - String encoding ("utf8" or "base64")
 * @returns ArrayBuffer containing encoded string data
 */
function stringToBuffer(str: string, encoding?: "utf8" | "base64"): ArrayBuffer;

import { stringToBuffer } from "@fluidframework/common-utils";

// Convert UTF-8 string to buffer
const buffer1 = stringToBuffer("Hello World", "utf8");

// Convert base64 string to buffer
const buffer2 = stringToBuffer("SGVsbG8gV29ybGQ=", "base64");

// Default encoding is UTF-8
const buffer3 = stringToBuffer("Hello");

console.log(buffer1.byteLength); // 11

/**
 * Converts binary data to string
 * @param buffer - Input binary data (ArrayBufferLike)
 * @param encoding - Output encoding ("utf8" or "base64")
 * @returns String representation of binary data
 */
function bufferToString(buffer: ArrayBufferLike, encoding?: "utf8" | "base64"): string;

import { bufferToString, stringToBuffer } from "@fluidframework/common-utils";

// Round-trip string conversion
const original = "Hello World";
const buffer = stringToBuffer(original);
const restored = bufferToString(buffer, "utf8");
console.log(restored === original); // true

// Convert to base64
const base64 = bufferToString(buffer, "base64");
console.log(base64); // "SGVsbG8gV29ybGQ="

/**
 * Converts Uint8Array to string with specified encoding
 * Node.js version uses Buffer.isBuffer optimization
 * Browser version uses standard TextEncoder/base64 conversion
 * @param arr - Input Uint8Array
 * @param encoding - Output encoding ("utf8" or "base64")
 * @returns String representation
 */
function Uint8ArrayToString(arr: Uint8Array, encoding: "utf8" | "base64"): string;

import { Uint8ArrayToString } from "@fluidframework/common-utils";

// Convert typed array to string
const data = new Uint8Array([72, 101, 108, 108, 111]); // "Hello"
const text = Uint8ArrayToString(data, "utf8");
console.log(text); // "Hello"

// Convert to base64
const base64 = Uint8ArrayToString(data, "base64");
console.log(base64); // "SGVsbG8="

/**
 * Converts Uint8Array to ArrayBuffer, handling byteOffset and proper slicing
 * @param array - Input Uint8Array (may be a view of a larger buffer)
 * @returns New ArrayBuffer containing only the array's data
 */
function Uint8ArrayToArrayBuffer(array: Uint8Array): ArrayBuffer;

import { Uint8ArrayToArrayBuffer } from "@fluidframework/common-utils";

// Convert full array
const array1 = new Uint8Array([1, 2, 3, 4, 5]);
const buffer1 = Uint8ArrayToArrayBuffer(array1);
console.log(buffer1.byteLength); // 5

// Convert array view (handles byteOffset correctly)
const largeBuffer = new ArrayBuffer(100);
const view = new Uint8Array(largeBuffer, 10, 5); // View of bytes 10-14
const buffer2 = Uint8ArrayToArrayBuffer(view);
console.log(buffer2.byteLength); // 5 (not 100)

/**
 * Type guard to determine if object is ArrayBuffer
 * Specifically rejects TypedArrays (Uint8Array, etc.)
 * @param value - Value to test
 * @returns true if value is ArrayBuffer, false otherwise
 */
function isArrayBuffer(value: any): value is ArrayBuffer;

import { isArrayBuffer } from "@fluidframework/common-utils";

const buffer = new ArrayBuffer(10);
const array = new Uint8Array(buffer);

console.log(isArrayBuffer(buffer)); // true
console.log(isArrayBuffer(array)); // false
console.log(isArrayBuffer(array.buffer)); // true

// Use in type narrowing
function processData(data: ArrayBuffer | Uint8Array) {
  if (isArrayBuffer(data)) {
    // TypeScript knows data is ArrayBuffer
    console.log(`ArrayBuffer of ${data.byteLength} bytes`);
  } else {
    // TypeScript knows data is Uint8Array
    console.log(`Uint8Array of ${data.length} elements`);
  }
}