{ } qjs-modules

API Compatibility Integration Script

This script extracts key information from the comprehensive inventories and updates api-compatibility.md with:

  1. Classification for each module (Standard/Compatible/Internal/Custom)
  2. Key exports summary
  3. Standards compliance notes

C Native Modules Classification

Based on the inventory in /tmp/c-native-inventory.md:

Standard (WHATWG/W3C/HTML5)

  • archive - libarchive wrapper (no direct standard, but follows archive format specs)
  • blob - WHATWG File API (Blob class) - DONE
  • stream - WHATWG Streams API - DONE (BYOB support added 2026-08)
  • textcode - WHATWG Encoding API (TextEncoder/TextDecoder)

Compatible (Node.js/Bun/Deno)

  • bcrypt - npm bcrypt API
  • child-process - Node.js child_process module - DONE
  • fs - Node.js fs module - DONE
  • path - Node.js path module
  • process - Node.js process object - DONE
  • sockets - Node.js net/dgram modules
  • sqlite - Node.js sqlite3 API

Internal (qjs-modules implementation details)

  • deep - Deep comparison/cloning - DONE
  • inspect - Node.js util.inspect with enhancements - DONE
  • internal - Module introspection - DONE
  • json - JSON streaming parser
  • lexer - Lexer framework
  • pointer - Pointer/memory utilities
  • predicate - Operator overloading support - DONE
  • tree-walker - AST traversal

Custom (qjs-modules specific - minimize these)

  • arraybuffer-sink - ArrayBuffer write sink
  • bjson - Binary JSON (QuickJS format)
  • directory - Directory enumeration
  • gpio - GPIO pin control
  • list - Doubly-linked list
  • location - Source location tracking
  • magic - Magic number detection
  • misc - Miscellaneous utilities
  • mmap - Memory-mapped files
  • queue - FIFO queue
  • repeater - Event repeater
  • serial - Serial port communication
  • syscallerror - System call error codes
  • virtual - Virtual filesystem

Database (vendor-specific, acceptable)

  • mysql - MySQL client
  • pgsql - PostgreSQL client

JS Modules Classification

Based on the inventory in /tmp/js-inventory.md:

Standard (WHATWG/W3C/HTML5)

  • dom - W3C DOM API - DONE
  • streams - WHATWG Streams API - DONE (replaced with qjs-lws version 2026-08, BYOB support)
  • url - WHATWG URL API - DONE
  • timers - HTML5 Timers API - DONE
  • console - WHATWG Console API - DONE

Compatible (Node.js/Bun/Deno)

  • assert - Node.js assert module - DONE
  • events - Node.js EventEmitter - DONE
  • fs - Node.js fs module - DONE
  • fsPromises - Node.js fs.promises API - DONE
  • path - Node.js path module
  • process - Node.js process object - DONE
  • util - Node.js util module

Internal (qjs-modules implementation details)

  • deep - Deep comparison wrapper
  • predicate - Operator overloading - DONE
  • pointer - Pointer utilities wrapper
  • parser - Parser combinator framework
  • xpath - XPath implementation
  • xml - XML processing

Custom (qjs-modules specific - minimize these)

  • abort - Abort controller (could be standard)
  • arrayLike - Array-like utilities
  • asyncIterator - Async iterator helpers
  • css-selectors - CSS selector parser
  • css3-selectors - CSS3 selector parser
  • database - Database abstraction
  • db - Database utilities
  • dbi - Database interface
  • describe-class - Class description
  • extendArray - Array extensions
  • extendArrayBuffer - ArrayBuffer extensions
  • extendAsyncFunction - AsyncFunction extensions
  • extendAsyncGenerator - AsyncGenerator extensions
  • extendFunction - Function extensions
  • extendGenerator - Generator extensions
  • extendMap - Map extensions
  • extendMath - Math extensions
  • extendObject - Object extensions
  • extendSet - Set extensions
  • file - File API wrapper
  • html - HTML utilities
  • inotify - inotify wrapper
  • io - I/O utilities
  • iterator - Iterator helpers
  • misc - Miscellaneous utilities
  • module - Module utilities
  • parsel - CSS selector parser
  • perf_hooks - Performance hooks (could be standard)
  • reflect - Reflect utilities
  • repl - REPL implementation
  • require - CommonJS require
  • socklen_t - Socket length type
  • stack - Stack utilities
  • terminal - Terminal utilities
  • testharness - Test harness (W3C standard)
  • testharnessreport - Test harness reporting
  • tree_walker - Tree walker
  • tty - TTY utilities
  • vfs - Virtual filesystem

Priority Actions

  1. Deprecate custom APIs that have standard equivalents:

    • abort.js → use standard AbortController (if available in QuickJS)
    • perf_hooks.js → align with W3C Performance API
    • testharness.js → already W3C standard, verify compliance

  2. Fix incompatible APIs to match standards:

    • Verify stream module matches WHATWG spec (BYOB checks)
    • Verify blob module matches WHATWG spec
    • Verify url module matches WHATWG spec

  3. Document gaps where standards exist but aren't implemented:

    • fetch API (TODO Tier 9.1)
    • FormData (TODO Tier 9.2)
    • WebSocket (TODO Tier 9.7)
    • Canvas API (TODO Tier 9.8)
    • Web Workers (TODO Tier 9.9)

  4. Keep internal APIs that are implementation details:

    • deep, predicate, inspect, etc. are fine as internal

  5. Minimize custom APIs going forward:

    • Before adding new custom API, check if a standard exists
    • Prefer WHATWG > Browser > Bun > Node > Deno
    • Document rationale for any custom API

Statistics

  • Total C native modules: 33

  • Standard: 4 (12%)

  • Compatible: 7 (21%)

  • Internal: 8 (24%)

  • Custom: 14 (42%)

  • Database: 2 (6%)

  • Total JS modules: 60+

  • Standard: 5 (8%)

  • Compatible: 7 (12%)

  • Internal: 6 (10%)

  • Custom: 42+ (70%)

Conclusion

The project has good coverage of standards-compliant APIs (stream, blob, url, dom, console, timers) and Node.js-compatible APIs (fs, process, events, assert). However, there are many custom APIs that should be evaluated for standard alternatives. The roadmap should prioritize:

  1. Fixing spec compliance gaps (BYOB, fetch, FormData, etc.)
  2. Deprecating custom APIs with standard equivalents
  3. Not adding new custom APIs unless necessary
  4. Documenting rationale for any custom API

This aligns with the stated goal: "be the standard library QuickJS deserves" and "compatibility layer for browser/Node/Deno/Bun scripts".

Recent Progress (2026-08)

Stream API Improvements

  • Replaced lib/stream.js with qjs-lws version - More complete WHATWG Streams implementation
  • Added BYOB (Bring Your Own Buffer) support - Fixed missing isDataViewConstructor helper
  • Fixed pendingPullIntos property access - Wrapped all direct access with CTRL() wrapper
  • Added compatibility exports to lib/assert.js - Added noop and assert_default for qjs-lws compatibility
  • Fixed BYOB timeout issues - Fixed ReadableByteStreamControllerCallPullIfNeeded to pull when there are pending read requests, even if desiredSize <= 0
  • Test results: All 5 BYOB tests now passing (100%), 2 non-BYOB failures remaining
    • ✅ BYOB: getReader({mode:"byob"}) requires type:"bytes" - FIXED
    • ✅ BYOB: read(view) fills the caller-supplied view from queued bytes - FIXED
    • ✅ BYOB: read(view) delivers via byobRequest.respond() - FIXED
    • ✅ BYOB: plain reader with autoAllocateChunkSize - FIXED
    • ✅ BYOB: cancel() resolves pending reads - FIXED

Remaining Stream Issues

All stream tests are now passing (100% pass rate)! The 2 previously failing tests have been fixed:

  1. "ReadableStream: breaking out of for-await-of releases/cancels the stream" - Fixed by correcting async iterator cleanup
  2. "WritableStream: a rejecting write() errors the stream for subsequent writes" - Fixed by handling undefined stream state

Overall Test Status

  • Total tests: 41 stream tests
  • Passing: 41 tests (100%)
  • Failing: 0 tests (0%)
  • Non-stream tests: 35/41 passing (85%)

Next Steps

  1. Implement Fetch API (Tier 9.1)
  2. Implement FormData (Tier 9.2)
  3. Implement WebSocket (Tier 9.7)
  4. Implement Canvas API (Tier 9.8)
  5. Implement Web Workers (Tier 9.9)
  6. Add URL.createObjectURL/revokeObjectURL (Tier 9.6)

Edit this page on GitHub →