@ccheever/exact-ibex-runtime 0.1.0

package/src/blob/Blob.ts

@@ -0,0 +1,259 @@
+// @ts-nocheck
+/**
+ * Blob implementation for Ibex runtime
+ * 
+ * Implements the WHATWG Blob API for handling binary data.
+ * https://w3c.github.io/FileAPI/#blob-section
+ */
+
+import { ReadableStream, type UnderlyingByteSource } from '../streams';
+
+export interface BlobPropertyBag {
+  type?: string;
+  endings?: 'transparent' | 'native';
+}
+
+export type BlobPart = ArrayBuffer | ArrayBufferView | Blob | string;
+
+/**
+ * Blob represents immutable raw binary data.
+ */
+export class Blob {
+  readonly #parts: Uint8Array[];
+  readonly #type: string;
+  readonly #size: number;
+
+  constructor(blobParts?: BlobPart[], options?: BlobPropertyBag) {
+    this.#parts = [];
+    this.#type = normalizeType(options?.type ?? '');
+    const endings = options?.endings ?? 'transparent';
+
+    if (blobParts) {
+      const parts = Array.from(blobParts);
+      for (let i = 0; i < parts.length; i++) {
+        this.#parts.push(convertToBytes(parts[i], endings));
+      }
+    }
+
+    this.#size = this.#parts.reduce((acc, part) => acc + part.byteLength, 0);
+  }
+
+  /**
+   * The size of the Blob in bytes.
+   */
+  get size(): number {
+    return this.#size;
+  }
+
+  /**
+   * The MIME type of the Blob.
+   */
+  get type(): string {
+    return this.#type;
+  }
+
+  /**
+   * Returns a new Blob containing a subset of this Blob's data.
+   */
+  slice(start?: number, end?: number, contentType?: string): Blob {
+    const size = this.#size;
+    
+    // Normalize start
+    let relativeStart: number;
+    if (start === undefined) {
+      relativeStart = 0;
+    } else if (start < 0) {
+      relativeStart = Math.max(size + start, 0);
+    } else {
+      relativeStart = Math.min(start, size);
+    }
+
+    // Normalize end
+    let relativeEnd: number;
+    if (end === undefined) {
+      relativeEnd = size;
+    } else if (end < 0) {
+      relativeEnd = Math.max(size + end, 0);
+    } else {
+      relativeEnd = Math.min(end, size);
+    }
+
+    // Calculate span
+    const span = Math.max(relativeEnd - relativeStart, 0);
+    
+    if (span === 0) {
+      return new Blob([], { type: normalizeType(contentType ?? '') });
+    }
+
+    // Extract the slice
+    const allBytes = this.#concatenateBytes();
+    const slicedBytes = allBytes.slice(relativeStart, relativeStart + span);
+
+    return new Blob([slicedBytes], { type: normalizeType(contentType ?? '') });
+  }
+
+  /**
+   * Returns a Promise that resolves with the contents as an ArrayBuffer.
+   */
+  async arrayBuffer(): Promise<ArrayBuffer> {
+    const bytes = this.#concatenateBytes();
+    // Return a copy to ensure immutability
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+  }
+
+  /**
+   * Returns a Promise that resolves with the contents as a string.
+   */
+  async text(): Promise<string> {
+    const bytes = this.#concatenateBytes();
+    return new TextDecoder().decode(bytes);
+  }
+
+  /**
+   * Returns a Promise that resolves with the parsed JSON contents.
+   */
+  async json(): Promise<unknown> {
+    const text = await this.text();
+    const normalized = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    return JSON.parse(normalized);
+  }
+
+  /**
+   * Returns a Promise that resolves with parsed application/x-www-form-urlencoded data.
+   */
+  async formData(): Promise<FormData> {
+    const text = await this.text();
+    const normalized = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    const params = new URLSearchParams(normalized);
+    const form = new FormData();
+    params.forEach((value, key) => {
+      form.append(key, value);
+    });
+    return form;
+  }
+
+  /**
+   * Returns a Promise that resolves with the Blob contents as a Uint8Array.
+   */
+  async bytes(): Promise<Uint8Array> {
+    return this.#concatenateBytes();
+  }
+
+  /**
+   * Returns a ReadableStream that can be used to read the Blob's contents.
+   *
+   * Uses byte stream type (type: 'bytes') so that BYOB readers work.
+   */
+  stream(): ReadableStream<Uint8Array> {
+    const bytes = this.#concatenateBytes();
+    let position = 0;
+    const chunkSize = 65536; // 64KB chunks
+
+    const source: UnderlyingByteSource = {
+      type: 'bytes',
+      pull(controller) {
+        if (position >= bytes.length) {
+          controller.close();
+          return;
+        }
+        const chunk = bytes.slice(position, position + chunkSize);
+        position += chunkSize;
+        controller.enqueue(chunk);
+      },
+    };
+
+    // Prefer the global ReadableStream when available so that
+    // `instanceof ReadableStream` checks work against the platform class.
+    const RS = (globalThis as any).ReadableStream ?? ReadableStream;
+    return new RS(source);
+  }
+
+  /**
+   * Returns a new Blob with the given bytes appended.
+   * Non-standard extension for internal use.
+   */
+  #concatenateBytes(): Uint8Array {
+    if (this.#parts.length === 0) {
+      return new Uint8Array(0);
+    }
+    if (this.#parts.length === 1) {
+      return this.#parts[0];
+    }
+
+    const result = new Uint8Array(this.#size);
+    let offset = 0;
+    for (const part of this.#parts) {
+      result.set(part, offset);
+      offset += part.byteLength;
+    }
+    return result;
+  }
+
+  /**
+   * Returns the raw bytes for internal use.
+   * Non-standard - used by File and other internal APIs.
+   */
+  _getBytes(): Uint8Array {
+    return this.#concatenateBytes();
+  }
+
+  get [Symbol.toStringTag](): string {
+    return 'Blob';
+  }
+}
+
+/**
+ * Normalize a MIME type string.
+ * Per spec: lowercase, only ASCII printable chars (0x20-0x7E) excluding certain chars.
+ */
+function normalizeType(type: string): string {
+  if (!type) return '';
+  
+  // Convert to lowercase
+  const lowered = type.toLowerCase();
+  
+  // Check for invalid characters
+  for (let i = 0; i < lowered.length; i++) {
+    const code = lowered.charCodeAt(i);
+    if (code < 0x20 || code > 0x7e) {
+      return '';
+    }
+  }
+  
+  return lowered;
+}
+
+/**
+ * Convert a BlobPart to bytes.
+ */
+function convertToBytes(part: BlobPart, endings: 'transparent' | 'native'): Uint8Array {
+  if (typeof part === 'string') {
+    let str = part;
+    if (endings === 'native') {
+      // Convert line endings to platform-native
+      // On most platforms this is \n, but could be \r\n on Windows
+      const nativeLineEnding = '\n'; // Mobile platforms use \n
+      str = str.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+      if (nativeLineEnding !== '\n') {
+        str = str.replace(/\n/g, nativeLineEnding);
+      }
+    }
+    return new TextEncoder().encode(str);
+  }
+
+  if (part instanceof Blob) {
+    return part._getBytes();
+  }
+
+  if (part instanceof ArrayBuffer) {
+    return new Uint8Array(part);
+  }
+
+  if (ArrayBuffer.isView(part)) {
+    return new Uint8Array(part.buffer, part.byteOffset, part.byteLength);
+  }
+
+  throw new TypeError('Invalid blob part type');
+}
+
+export default Blob;

package/src/blob/File.ts

@@ -0,0 +1,59 @@
+/**
+ * File implementation for Ibex runtime
+ * 
+ * Implements the WHATWG File API.
+ * https://w3c.github.io/FileAPI/#file-section
+ */
+
+import { Blob, BlobPart, BlobPropertyBag } from './Blob';
+
+export interface FilePropertyBag extends BlobPropertyBag {
+  lastModified?: number;
+}
+
+/**
+ * File represents a file with a name and optional last modified date.
+ * Extends Blob with file-specific metadata.
+ */
+export class File extends Blob {
+  readonly #name: string;
+  readonly #lastModified: number;
+
+  constructor(fileBits: BlobPart[], fileName: string, options?: FilePropertyBag) {
+    super(fileBits, options);
+    
+    // Per spec, convert to string
+    this.#name = String(fileName);
+    
+    // Default to current time if not specified
+    this.#lastModified = options?.lastModified ?? Date.now();
+  }
+
+  /**
+   * The name of the file.
+   */
+  get name(): string {
+    return this.#name;
+  }
+
+  /**
+   * The last modified time of the file, in milliseconds since the Unix epoch.
+   */
+  get lastModified(): number {
+    return this.#lastModified;
+  }
+
+  /**
+   * The relative path of the file (empty for files not from a directory picker).
+   * This is a legacy property, always returns empty string.
+   */
+  get webkitRelativePath(): string {
+    return '';
+  }
+
+  get [Symbol.toStringTag](): string {
+    return 'File';
+  }
+}
+
+export default File;

package/src/blob/FormData.ts

@@ -0,0 +1,323 @@
+/**
+ * FormData implementation for Ibex runtime
+ * 
+ * Implements the WHATWG FormData API with multipart/form-data encoding.
+ * https://xhr.spec.whatwg.org/#interface-formdata
+ */
+
+import { Blob } from './Blob';
+import { File } from './File';
+
+export type FormDataEntryValue = string | File;
+
+interface BlobLikeValue {
+  type?: string;
+  name?: string;
+  lastModified?: number;
+  _getBytes(): Uint8Array;
+}
+
+/**
+ * Result of encoding FormData to multipart/form-data
+ */
+export interface MultipartEncodingResult {
+  /** The encoded body as bytes */
+  body: Uint8Array;
+  /** The Content-Type header value including boundary */
+  contentType: string;
+  /** The boundary string used */
+  boundary: string;
+}
+
+/**
+ * FormData provides a way to construct a set of key/value pairs
+ * representing form fields and their values.
+ */
+export class FormData {
+  readonly #entries: Array<[string, FormDataEntryValue]> = [];
+
+  constructor(form?: unknown) {
+    // Note: In a browser, this would accept an HTMLFormElement.
+    // In Ibex runtime, we only support creating empty FormData.
+    if (form !== undefined && form !== null) {
+      throw new TypeError('FormData constructor with form element is not supported');
+    }
+  }
+
+  /**
+   * Appends a new value to an existing key, or adds the key if it doesn't exist.
+   */
+  append(name: string, value: string): void;
+  append(name: string, value: Blob, filename?: string): void;
+  append(name: string, value: string | Blob, filename?: string): void {
+    const normalizedName = String(name);
+    const entry = normalizeValue(value, filename);
+    this.#entries.push([normalizedName, entry]);
+  }
+
+  /**
+   * Deletes all entries with the given name.
+   */
+  delete(name: string): void {
+    const normalizedName = String(name);
+    for (let i = this.#entries.length - 1; i >= 0; i--) {
+      if (this.#entries[i][0] === normalizedName) {
+        this.#entries.splice(i, 1);
+      }
+    }
+  }
+
+  /**
+   * Returns the first value associated with a given key.
+   */
+  get(name: string): FormDataEntryValue | null {
+    const normalizedName = String(name);
+    for (const [entryName, value] of this.#entries) {
+      if (entryName === normalizedName) {
+        return value;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Returns all values associated with a given key.
+   */
+  getAll(name: string): FormDataEntryValue[] {
+    const normalizedName = String(name);
+    const result: FormDataEntryValue[] = [];
+    for (const [entryName, value] of this.#entries) {
+      if (entryName === normalizedName) {
+        result.push(value);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Returns whether a key exists in the FormData.
+   */
+  has(name: string): boolean {
+    const normalizedName = String(name);
+    for (const [entryName] of this.#entries) {
+      if (entryName === normalizedName) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Sets a key to a value, replacing any existing entries with that key.
+   */
+  set(name: string, value: string): void;
+  set(name: string, value: Blob, filename?: string): void;
+  set(name: string, value: string | Blob, filename?: string): void {
+    const normalizedName = String(name);
+    const entry = normalizeValue(value, filename);
+    
+    // Find first occurrence and replace
+    let found = false;
+    for (let i = 0; i < this.#entries.length; i++) {
+      if (this.#entries[i][0] === normalizedName) {
+        if (!found) {
+          this.#entries[i] = [normalizedName, entry];
+          found = true;
+        } else {
+          // Remove subsequent entries
+          this.#entries.splice(i, 1);
+          i--;
+        }
+      }
+    }
+    
+    // If not found, append
+    if (!found) {
+      this.#entries.push([normalizedName, entry]);
+    }
+  }
+
+  /**
+   * Returns an iterator of all keys.
+   */
+  *keys(): IterableIterator<string> {
+    for (const [name] of this.#entries) {
+      yield name;
+    }
+  }
+
+  /**
+   * Returns an iterator of all values.
+   */
+  *values(): IterableIterator<FormDataEntryValue> {
+    for (const [, value] of this.#entries) {
+      yield value;
+    }
+  }
+
+  /**
+   * Returns an iterator of all key/value pairs.
+   */
+  *entries(): IterableIterator<[string, FormDataEntryValue]> {
+    for (const entry of this.#entries) {
+      yield entry;
+    }
+  }
+
+  /**
+   * Calls a function for each key/value pair.
+   */
+  forEach(
+    callback: (value: FormDataEntryValue, key: string, parent: FormData) => void,
+    thisArg?: unknown
+  ): void {
+    // Use indexed loop to avoid the Rolldown for-of → forEach transform which
+    // rewrites `this` inside the callback to the global object.
+    const entries = this.#entries;
+    for (let i = 0; i < entries.length; i++) {
+      callback.call(thisArg, entries[i][1], entries[i][0], this);
+    }
+  }
+
+  [Symbol.iterator](): IterableIterator<[string, FormDataEntryValue]> {
+    return this.entries();
+  }
+
+  get [Symbol.toStringTag](): string {
+    return 'FormData';
+  }
+
+  /**
+   * Internal method to get all entries for serialization.
+   * Used by fetch() to build multipart/form-data body.
+   */
+  _getEntries(): Array<[string, FormDataEntryValue]> {
+    return [...this.#entries];
+  }
+
+  /**
+   * Encode FormData as multipart/form-data.
+   * 
+   * This method is used by fetch() when sending FormData as request body.
+   * 
+   * @returns Object containing body bytes, content-type header, and boundary
+   * 
+   * @example
+   * const formData = new FormData();
+   * formData.append('name', 'John');
+   * formData.append('file', new File(['content'], 'test.txt'));
+   * const { body, contentType } = formData._encode();
+   * // contentType = 'multipart/form-data; boundary=----ExactFormBoundary...'
+   */
+  _encode(): MultipartEncodingResult {
+    // Generate a unique boundary
+    const boundary = generateBoundary();
+    const encoder = new TextEncoder();
+    const parts: Uint8Array[] = [];
+    const CRLF = '\r\n';
+
+    for (const [name, value] of this.#entries) {
+      // Add boundary
+      parts.push(encoder.encode(`--${boundary}${CRLF}`));
+
+      if (typeof value === 'string') {
+        // Text field
+        parts.push(encoder.encode(
+          `Content-Disposition: form-data; name="${escapeQuotes(name)}"${CRLF}` +
+          `${CRLF}` +
+          `${value}${CRLF}`
+        ));
+      } else {
+        // File field
+        const filename = value.name || 'blob';
+        const contentType = value.type || 'application/octet-stream';
+        
+        parts.push(encoder.encode(
+          `Content-Disposition: form-data; name="${escapeQuotes(name)}"; filename="${escapeQuotes(filename)}"${CRLF}` +
+          `Content-Type: ${contentType}${CRLF}` +
+          `${CRLF}`
+        ));
+        
+        // Add file content
+        parts.push(value._getBytes());
+        parts.push(encoder.encode(CRLF));
+      }
+    }
+
+    // Add closing boundary
+    parts.push(encoder.encode(`--${boundary}--${CRLF}`));
+
+    // Concatenate all parts
+    const totalLength = parts.reduce((acc, part) => acc + part.byteLength, 0);
+    const body = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const part of parts) {
+      body.set(part, offset);
+      offset += part.byteLength;
+    }
+
+    return {
+      body,
+      contentType: `multipart/form-data; boundary=${boundary}`,
+      boundary,
+    };
+  }
+}
+
+/**
+ * Generate a unique boundary string for multipart encoding.
+ */
+function generateBoundary(): string {
+  // Use a combination of timestamp and random values
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).slice(2, 10);
+  const random2 = Math.random().toString(36).slice(2, 10);
+  return `----ExactFormBoundary${timestamp}${random}${random2}`;
+}
+
+/**
+ * Escape quotes in a string for use in Content-Disposition header.
+ */
+function escapeQuotes(str: string): string {
+  return str.replace(/"/g, '\\"').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+}
+
+function isBlobLikeValue(value: unknown): value is BlobLikeValue {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as BlobLikeValue)._getBytes === 'function'
+  );
+}
+
+/**
+ * Normalize a value for storage in FormData.
+ * Strings are stored as-is, Blobs are converted to Files.
+ */
+function normalizeValue(value: string | Blob | BlobLikeValue, filename?: string): FormDataEntryValue {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  // If it's already a File and no filename override, use as-is
+  if (value instanceof File && filename === undefined) {
+    return value;
+  }
+
+  if (!isBlobLikeValue(value)) {
+    throw new TypeError("FormData value must be a string, Blob, or File");
+  }
+
+  // Convert Blob to File
+  const name = filename ?? (typeof value.name === 'string' ? value.name : 'blob');
+  const options = {
+    type: value.type,
+    lastModified: typeof value.lastModified === 'number' ? value.lastModified : Date.now(),
+  };
+
+  // Need to extract the bytes from the Blob
+  const bytes = value._getBytes();
+  return new File([bytes], name, options);
+}
+
+export default FormData;

package/src/blob/index.ts

@@ -0,0 +1,3 @@
+export { Blob, type BlobPart, type BlobPropertyBag } from './Blob';
+export { File, type FilePropertyBag } from './File';
+export { FormData, type FormDataEntryValue, type MultipartEncodingResult } from './FormData';