tessl/npm-arweave

JavaScript/TypeScript client library for the Arweave decentralized permanent data storage network

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Data Utilities

Name: tessl/npm-arweave
Author: tessl

Utility functions for data conversion, encoding/decoding, and buffer manipulation. Essential for working with Arweave's base64url encoding and various data formats.

Capabilities

Buffer and String Conversion

Convert between different data representations (strings, buffers, arrays).

/**
 * Convert string to Uint8Array buffer
 * @param string - Input string to convert
 * @returns Uint8Array buffer
 */
stringToBuffer(string: string): Uint8Array;

/**
 * Convert buffer to UTF-8 string
 * @param buffer - Buffer to convert (Uint8Array or ArrayBuffer)
 * @returns UTF-8 string
 */
bufferToString(buffer: Uint8Array | ArrayBuffer): string;

/**
 * Concatenate multiple buffers
 * @param buffers - Array of buffers to concatenate
 * @returns Single concatenated buffer
 */
concatBuffers(buffers: Uint8Array[] | ArrayBuffer[]): Uint8Array;

Usage Examples:

import Arweave from "arweave";

// String to buffer conversion
const text = "Hello, Arweave!";
const buffer = Arweave.utils.stringToBuffer(text);
console.log("Buffer:", buffer);

// Buffer to string conversion
const originalText = Arweave.utils.bufferToString(buffer);
console.log("Original text:", originalText);

// Concatenate multiple buffers
const buffer1 = Arweave.utils.stringToBuffer("Hello, ");
const buffer2 = Arweave.utils.stringToBuffer("Arweave!");
const combined = Arweave.utils.concatBuffers([buffer1, buffer2]);
const combinedText = Arweave.utils.bufferToString(combined);
console.log("Combined:", combinedText); // "Hello, Arweave!"

Base64 URL Encoding

Convert between buffers/strings and base64url encoding used throughout Arweave.

/**
 * Encode buffer to base64url string
 * @param buffer - Buffer to encode
 * @returns Base64url encoded string
 */
bufferTob64Url(buffer: Uint8Array): string;

/**
 * Decode base64url string to buffer
 * @param b64UrlString - Base64url string to decode
 * @returns Decoded buffer
 */
b64UrlToBuffer(b64UrlString: string): Uint8Array;

/**
 * Encode string to base64url
 * @param string - String to encode
 * @returns Base64url encoded string
 */
stringToB64Url(string: string): string;

/**
 * Decode base64url string to UTF-8 string
 * @param b64UrlString - Base64url string to decode
 * @returns Decoded UTF-8 string
 */
b64UrlToString(b64UrlString: string): string;

Usage Examples:

const text = "Hello, Arweave!";

// String to base64url
const encoded = Arweave.utils.stringToB64Url(text);
console.log("Encoded:", encoded);

// Base64url back to string
const decoded = Arweave.utils.b64UrlToString(encoded);
console.log("Decoded:", decoded);

// Buffer to base64url
const buffer = Arweave.utils.stringToBuffer(text);
const bufferEncoded = Arweave.utils.bufferTob64Url(buffer);
console.log("Buffer encoded:", bufferEncoded);

// Base64url to buffer
const bufferDecoded = Arweave.utils.b64UrlToBuffer(bufferEncoded);
console.log("Buffer decoded:", bufferDecoded);

Standard Base64 Operations

Work with standard base64 encoding (distinct from base64url).

/**
 * Encode buffer to standard base64
 * @param buffer - Buffer to encode
 * @returns Base64 encoded string
 */
bufferTob64(buffer: Uint8Array): string;

/**
 * Convert base64url to standard base64
 * @param b64UrlString - Base64url string
 * @returns Standard base64 string
 */
b64UrlDecode(b64UrlString: string): string;

/**
 * Convert standard base64 to base64url
 * @param b64String - Standard base64 string
 * @returns Base64url string
 */
b64UrlEncode(b64String: string): string;

Usage Examples:

const data = Arweave.utils.stringToBuffer("Hello, Arweave!");

// Standard base64 encoding
const base64 = Arweave.utils.bufferTob64(data);
console.log("Base64:", base64);

// Base64url encoding
const base64url = Arweave.utils.bufferTob64Url(data);
console.log("Base64url:", base64url);

// Convert between formats
const standardToUrl = Arweave.utils.b64UrlEncode(base64);
const urlToStandard = Arweave.utils.b64UrlDecode(base64url);

Advanced Usage Examples

Transaction Data Handling

// Prepare data for transaction
async function prepareTransactionData(content: string): Promise<string> {
  const buffer = Arweave.utils.stringToBuffer(content);
  return Arweave.utils.bufferTob64Url(buffer);
}

// Extract data from transaction
async function extractTransactionData(transactionId: string): Promise<string> {
  const data = await arweave.transactions.getData(transactionId);
  if (typeof data === 'string') {
    return Arweave.utils.b64UrlToString(data);
  } else {
    return Arweave.utils.bufferToString(data);
  }
}

// Usage
const content = "My important data";
const encodedData = await prepareTransactionData(content);
console.log("Encoded for transaction:", encodedData);

File Upload Processing

// Handle file upload with proper encoding
async function processFileUpload(file: File): Promise<Uint8Array> {
  const arrayBuffer = await file.arrayBuffer();
  const uint8Array = new Uint8Array(arrayBuffer);
  
  console.log("File size:", uint8Array.length);
  console.log("File base64url:", Arweave.utils.bufferTob64Url(uint8Array));
  
  return uint8Array;
}

// Create transaction from file
async function createFileTransaction(file: File, key: JWKInterface) {
  const fileData = await processFileUpload(file);
  
  const transaction = await arweave.createTransaction({
    data: fileData,
    tags: [
      { name: "Content-Type", value: file.type },
      { name: "File-Name", value: file.name }
    ]
  }, key);
  
  return transaction;
}

Data Integrity Verification

// Verify data integrity using hash comparison
async function verifyDataIntegrity(originalData: string, retrievedData: string): Promise<boolean> {
  const originalBuffer = Arweave.utils.stringToBuffer(originalData);
  const retrievedBuffer = Arweave.utils.stringToBuffer(retrievedData);
  
  const originalHash = await Arweave.crypto.hash(originalBuffer);
  const retrievedHash = await Arweave.crypto.hash(retrievedBuffer);
  
  const originalHashStr = Arweave.utils.bufferTob64Url(originalHash);
  const retrievedHashStr = Arweave.utils.bufferTob64Url(retrievedHash);
  
  return originalHashStr === retrievedHashStr;
}

// Usage
const original = "Important data";
const retrieved = await extractTransactionData("tx-id");
const isIntact = await verifyDataIntegrity(original, retrieved);
console.log("Data integrity:", isIntact);

Batch Data Processing

// Process multiple data items efficiently
function processBatchData(items: string[]): { encoded: string[], concatenated: Uint8Array } {
  const buffers = items.map(item => Arweave.utils.stringToBuffer(item));
  const encoded = buffers.map(buffer => Arweave.utils.bufferTob64Url(buffer));
  const concatenated = Arweave.utils.concatBuffers(buffers);
  
  return { encoded, concatenated };
}

// Usage
const dataItems = ["Item 1", "Item 2", "Item 3"];
const processed = processBatchData(dataItems);
console.log("Encoded items:", processed.encoded);
console.log("Combined size:", processed.concatenated.length);

JSON Data Handling

// Serialize and deserialize JSON data for Arweave
function serializeJsonForArweave(obj: any): string {
  const jsonString = JSON.stringify(obj);
  return Arweave.utils.stringToB64Url(jsonString);
}

function deserializeJsonFromArweave(encoded: string): any {
  const jsonString = Arweave.utils.b64UrlToString(encoded);
  return JSON.parse(jsonString);
}

// Usage
const data = { 
  message: "Hello, Arweave!", 
  timestamp: Date.now(),
  version: "1.0"
};

const encoded = serializeJsonForArweave(data);
const decoded = deserializeJsonFromArweave(encoded);
console.log("Original:", data);
console.log("Recovered:", decoded);

Types

Base64UrlString

/** Type alias for base64url encoded strings */
type Base64UrlString = string;

Utility Constants

/** UTF-8 text encoder instance */
const TEXT_ENCODER: TextEncoder;

/** UTF-8 text decoder instance */
const TEXT_DECODER: TextDecoder;

Best Practices

Memory Efficiency

// ✅ Good: Process large files in chunks
async function processLargeFile(file: File) {
  const chunkSize = 64 * 1024; // 64KB chunks
  const chunks: Uint8Array[] = [];
  
  for (let i = 0; i < file.size; i += chunkSize) {
    const chunk = file.slice(i, i + chunkSize);
    const buffer = new Uint8Array(await chunk.arrayBuffer());
    chunks.push(buffer);
  }
  
  return Arweave.utils.concatBuffers(chunks);
}

// ❌ Bad: Load entire large file into memory at once
async function processLargeFileBad(file: File) {
  return new Uint8Array(await file.arrayBuffer());
}

Encoding Safety

// ✅ Good: Always validate decoded data
function safeB64UrlToString(encoded: string): string | null {
  try {
    return Arweave.utils.b64UrlToString(encoded);
  } catch (error) {
    console.error("Invalid base64url encoding:", error);
    return null;
  }
}

// ✅ Good: Handle different input types
function normalizeToBuffer(input: string | Uint8Array | ArrayBuffer): Uint8Array {
  if (typeof input === 'string') {
    return Arweave.utils.stringToBuffer(input);
  } else if (input instanceof ArrayBuffer) {
    return new Uint8Array(input);
  } else {
    return input;
  }
}