#mizchi/js_web

• Browsers (Chrome, Firefox, Safari, Edge)
• Server-side runtimes (Node.js 18+, Deno, Bun)
• Edge runtimes (Vercel Edge, Netlify Edge, and others)
• Any WinterCG-compliant runtime

#Web API Support Status

#Status Legend

• 🆗 Reviewed: Human reviewed (AI agents cannot change this status)
• 🧪 Tested: Comprehensive test coverage
• 🧪 Experimental: Early stage, limited platform support
• 🤖 AI Generated: FFI bindings created, needs testing
• 📅 Planned: Scheduled for future implementation

#Overview

#Why Use web/* Packages?

• Write Once, Run Anywhere: Code using these APIs works in browsers, Node.js, Deno, and other modern runtimes
• Server-Side JavaScript: Build backend services with the same APIs you use in the browser
• Edge Computing: Deploy to edge runtimes without platform-specific code
• Future-Proof: Based on living standards that continue to evolve
• Type-Safe: MoonBit's type system ensures compile-time safety
• Well-Tested: Comprehensive test coverage across environments

#Included APIs

• HTTP/Networking: fetch, Request/Response, Headers, FormData, URL APIs, WebSocket
• Streams: ReadableStream, WritableStream, TransformStream for efficient data processing
• Cryptography: Web Crypto API for secure operations (hashing, encryption, key generation)
• Workers: Web Workers and MessageChannel for concurrency (browser and Node.js)
• WebGPU: GPU compute and rendering — every GPU* interface, including GPUCanvasContext for drawing to a canvas. Browsers expose it directly; Deno needs --unstable-webgpu.
• WebNN: neural-network inference via navigator.ml — graph building, compilation and device tensors. Model formats and runtimes live a layer up, in mizchi/webnn-mbt.

#Installation

import {
  "mizchi/js_core@0.13.0",
  "mizchi/js_web@0.13.0",
}

import {
  "mizchi/js_core" @core,
  "mizchi/js_web/blob",
  "mizchi/js_web/crypto",
  "mizchi/js_web/encoding",
  "mizchi/js_web/event",
  "mizchi/js_web/http",
  "mizchi/js_web/streams",
  "mizchi/js_web/url",
  "mizchi/js_web/webassembly",
  "mizchi/js_web/webgpu",
  "mizchi/js_web/websocket",
  "mizchi/js_web/worker",
}

#Usage Examples

#Fetch API (Universal - Browser & Server)

// Simple GET request - works in browser, Node.js, Deno, and edge runtimes
let response = @http.fetch("https://api.example.com/data")
let json = response.json()

// POST request with JSON body
let request = @http.Request("https://api.example.com/users", 
  method="POST",
  body="{\"name\":\"Alice\"}",
  headers=headers
)
let response = @http.fetch_with_request(request)

// Server-side API handler example (Cloudflare Workers, Vercel Edge, etc.)
fn handle_request(request : @http.Request) -> @http.Response {
  let url = request.url()
  if url.pathname == "/api/hello" {
    @http.Response(
      body="{\"message\":\"Hello World\"}",
      status=200,
      headers=...
    )
  } else {
    @http.Response(body="Not Found", status=404)
  }
}

#Streams (Server-Side Data Processing)

// Streaming API responses - efficient for large datasets
fn stream_large_file(file_path : String) -> @http.Response {
  let stream = @streams.ReadableStream(...)
  @http.Response(
    body=stream,
    headers=...
  )
}

// Transform streams for data processing pipelines
fn process_stream(input : @streams.ReadableStream) -> @streams.ReadableStream {
  let transform = @streams.TransformStream()
  input.pipe_through(transform)
}

// Server-sent events (SSE) example
fn create_sse_stream() -> @streams.ReadableStream {
  @streams.ReadableStream(controller => {
    // Send periodic updates
    controller.enqueue("data: {\"time\": \"...\"}\n\n")
  })
}

// Compression streams - compress data on the fly
fn compress_response(data : String) -> @streams.ReadableStream {
  let compressor = @streams.CompressionStream("gzip")
  let encoder = @encoding.TextEncoder()

  // Create a readable stream from data
  let readable = create_stream_from_string(data)

  // Pipe through compression
  readable.pipeThrough(compressor)
  compressor.readable()
}

// Decompression streams - decompress streamed data
fn decompress_request(compressed_stream : @streams.ReadableStream) -> @streams.ReadableStream {
  let decompressor = @streams.DecompressionStream("gzip")
  compressed_stream.pipeThrough(decompressor)
  decompressor.readable()
}

#Web Crypto (Secure Server-Side Operations)

// Password hashing (server-side authentication)
async fn hash_password(password : String) -> @arraybuffer.ArrayBuffer {
  let subtle = @crypto.Crypto::get().subtle
  let data = @encoding.TextEncoder().encode(password)
  subtle.digest("SHA-256", data.as_any())
}

// Generate JWT tokens (API authentication)
async fn sign_jwt(payload : String, secret : String) -> @arraybuffer.ArrayBuffer {
  let subtle = @crypto.Crypto::get().subtle
  let encoder = @encoding.TextEncoder()

  // Algorithm descriptors are plain JS objects
  let algorithm = @core.from_entries([
    ("name", @core.any("HMAC")),
    ("hash", @core.any("SHA-256")),
  ])

  // Import the HMAC key, then sign
  let key = subtle.import_key(
    "raw",
    encoder.encode(secret).as_any(),
    algorithm,
    false,
    ["sign"],
  )
  subtle.sign(algorithm, key.as_any(), encoder.encode(payload).as_any())
}

// Encrypt sensitive data (database encryption)
async fn encrypt_data(data : String) -> @arraybuffer.ArrayBuffer {
  let subtle = @crypto.Crypto::get().subtle

  // Generate an AES-GCM key
  let key = subtle.generate_key(
    @core.from_entries([
      ("name", @core.any("AES-GCM")),
      ("length", @core.any(256)),
    ]),
    true,
    ["encrypt", "decrypt"],
  )

  // Encrypt -- AES-GCM needs a 12-byte iv
  let iv = @crypto.Crypto::get().getRandomValues(
    @arraybuffer.Uint8Array::from_size(12),
  )
  let algorithm = @core.from_entries([
    ("name", @core.any("AES-GCM")),
    ("iv", iv.as_any()),
  ])
  subtle.encrypt(algorithm, key, @encoding.TextEncoder().encode(data).as_any())
}

#WebSocket (Real-Time Communication)

// Client-side (browser) or server-side (Node.js, Bun)
let ws = @websocket.WebSocket("wss://api.example.com/ws")

ws.addEventListener("open", fn(event) {
  ws.send("{\"type\":\"subscribe\",\"channel\":\"updates\"}")
})

ws.addEventListener("message", fn(event) {
  let data = event.data()
  // Process real-time updates
  console.log(data)
})

ws.addEventListener("error", fn(event) {
  console.error("WebSocket error")
})

// Cloudflare Workers Durable Objects WebSocket example
fn handle_websocket(request : @http.Request) -> @http.Response {
  let upgrade = request.headers()._get("Upgrade")
  if upgrade == Some("websocket") {
    // Upgrade connection to WebSocket
    // Handle WebSocket messages
  }
  @http.Response(body="Not a WebSocket request", status=400)
}

#Web Workers

let worker = @worker.Worker("worker.js")

worker.addEventListener("message", fn(event) {
  let result = event.data()
  console.log(result)
})

worker.postMessage("Start processing")

#Common Use Cases

#🌐 Universal API Client

// Same code runs in browser, Node.js, Deno, Cloudflare Workers
fn fetch_user(id : Int) -> @js.Promise[@core.Any] {
  let response = @http.fetch("https://api.example.com/users/\(id)")
  response.json()
}

#🔐 Authentication & Security

fn verify_jwt(token : String) -> Bool {
  // Web Crypto works everywhere
  let crypto = @crypto.get_crypto()
  // Verify signature
}

#📡 Edge Computing

// Deploy to Cloudflare Workers, Vercel Edge, Netlify Edge
fn handle(request : @http.Request) -> @http.Response {
  let path = request.url().pathname
  match path {
    "/api/data" => fetch_and_transform_data()
    _ => @http.Response(body="Not Found", status=404)
  }
}

#🔄 Data Streaming

// Stream processing works on server and client
fn process_large_file(url : String) -> @stream.ReadableStream {
  let response = @http.fetch(url)
  response.body()
}

#💬 Real-Time Communication

// Same code for browser client and Node.js backend
fn connect_to_server() -> @websocket.WebSocket {
  @websocket.WebSocket("wss://api.example.com/ws")
}

#Platform Compatibility

#When to Use web/* vs Other Packages

#Use mizchi/js_web/* when:

• ✅ Building cross-platform libraries
• ✅ Writing code for edge computing (Cloudflare Workers, Vercel Edge)
• ✅ Creating universal API clients
• ✅ Need standard HTTP/fetch APIs
• ✅ Working with streams for data processing
• ✅ Implementing authentication/cryptography

#Use mizchi/js_browser/* when:

• 🌐 Manipulating the DOM (Document, Element, Events)
• 🌐 Browser-specific APIs (Window, Navigator, Storage)
• 🌐 Canvas rendering
• 🌐 Browser-only features (MutationObserver, etc.)

#Use mizchi/js_node/* when:

• 🟢 Accessing file system (fs)
• 🟢 Process management (child_process)
• 🟢 Node.js-specific modules (path, os, etc.)

#Use mizchi/js/cloudflare/* when:

• ⚡ Using Cloudflare Workers APIs (KV, D1, R2)
• ⚡ Durable Objects
• ⚡ Workers-specific features

#Related Packages

• mizchi/js - Core JavaScript FFI and built-in objects
• mizchi/js_browser/dom - Browser-specific DOM and rendering APIs
• mizchi/js_node - Node.js-specific runtime APIs
• mizchi/js/cloudflare - Cloudflare Workers platform APIs
• mizchi/js_deno - Deno runtime APIs (separate module)

#Standards Compliance

• Fetch Standard - HTTP requests and responses
• Streams Standard - Streaming data processing
• Compression Streams API - GZIP/Deflate compression and decompression
• Web Crypto API - Cryptographic operations
• WebSocket API - Real-time bidirectional communication
• Web Workers - Background processing
• URL Standard - URL parsing and manipulation
• WebAssembly JavaScript Interface - WASM integration
• WebGPU API - GPU compute and rendering (experimental)

• Minimum Common Web Platform API - Core APIs that work across all JavaScript runtimes
• Runtime Keys - Runtime detection and capabilities

#License