diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index c2c320a4..35d84c14 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -8,9 +8,9 @@ jstime is a minimal and performant JavaScript runtime built on top of the V8 Jav - **`jstime_core`** (`core/`): The core runtime library that wraps V8 and provides JavaScript APIs - Built-in APIs organized by standards: - - **WHATWG**: console, timers, fetch, URL, events (Event/EventTarget), base64, structured clone, microtask queue - - **W3C**: performance - - **Node.js compatible**: file system (fs/promises) + - **WHATWG**: console, timers, fetch, URL, events (Event/EventTarget), base64, structured clone, microtask queue, streams, text encoding + - **W3C**: performance, crypto (Web Cryptography API subset) + - **Node.js compatible**: file system (fs/promises), process - Module loading system with ES modules and JSON modules support - Event loop implementation for async operations - WebAssembly support via V8 @@ -48,6 +48,8 @@ jstime is a minimal and performant JavaScript runtime built on top of the V8 Jav - **urlencoding** (2.1): URL encoding/decoding utilities - **rustc-hash** (2.1): Fast non-cryptographic hashing for module maps - **filetime** (0.2): File timestamp manipulation for fs API +- **ring** (0.17): Cryptographic operations for crypto API +- **align-data** (0.1.0): Data alignment utilities - **lazy_static** (1.5.0): Lazy static initialization - **rustyline** (17.0.2): REPL implementation with line editing (in cli crate) - **structopt** (0.3.26): CLI argument parsing (in cli crate) @@ -94,12 +96,19 @@ Built-in APIs are located in `core/src/builtins/` and organized by standards bod - **base64_impl.rs / base64.js**: atob() and btoa() for base64 encoding/decoding - **structured_clone_impl.rs / structured_clone.js**: structuredClone() for deep cloning - **queue_microtask_impl.rs / queue_microtask.js**: queueMicrotask() +- **streams_impl.rs / streams.js**: ReadableStream, WritableStream, TransformStream +- **text_encoding_impl.rs / text_encoding.js**: TextEncoder and TextDecoder for UTF-8 **W3C Standards** (`w3c/`): - **performance_impl.rs / performance.js**: performance.now() and performance.timeOrigin +- **crypto_impl.rs / crypto.js**: crypto.getRandomValues(), crypto.randomUUID(), crypto.subtle.digest() **Node.js Compatible** (`node/`): - **fs_impl.rs / fs.js**: File system API (node:fs/promises module) +- **process_impl.rs / process.js**: process.env, process.argv, process.cwd(), process.exit(), process.stdout, process.stderr, process.stdin + +**Polyfills** (`polyfills/`): +- **date_locale.js**: Date.prototype.toLocaleString() and related methods ### Adding New Built-ins @@ -128,15 +137,18 @@ Built-in APIs are located in `core/src/builtins/` and organized by standards bod - **`core/tests/test_conformance_*.rs`**: WHATWG/W3C spec conformance tests - `test_conformance_base64.rs`: Base64 encoding (29 tests) - `test_conformance_console.rs`: Console API (13 tests) - - `test_conformance_event.rs`: Event and EventTarget (tests) + - `test_conformance_crypto.rs`: Crypto API (17 tests) + - `test_conformance_event.rs`: Event and EventTarget (33 tests) - `test_conformance_fetch.rs`: Fetch API (32 tests) + - `test_conformance_json_modules.rs`: JSON module imports (12 tests) - `test_conformance_performance.rs`: Performance API (19 tests) + - `test_conformance_streams.rs`: Streams API (26 tests) + - `test_conformance_structured_clone.rs`: Structured clone (21 tests) + - `test_conformance_text_encoding.rs`: Text Encoding API (39 tests) - `test_conformance_timers.rs`: Timers API (17 tests) - `test_conformance_url.rs`: URL API (26 tests) - `test_conformance_webassembly.rs`: WebAssembly API (28 tests) - - `test_conformance_structured_clone.rs`: Structured clone (tests) - - `test_conformance_json_modules.rs`: JSON module imports (tests) -- **`core/tests/test_*.rs`**: Feature-specific tests (timers, fetch, fs, webassembly) +- **`core/tests/test_*.rs`**: Feature-specific tests (timers, fetch, fs, process, crypto, webassembly) - **`core/tests/common/mod.rs`**: Shared test utilities (setup guards, helper functions) - **`core/tests/fixtures/`**: Test data and sample files organized by feature diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index ba83341b..d0be5b6a 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -27,7 +27,7 @@ jstime is a minimal JavaScript runtime built on top of the V8 JavaScript engine. ### Technology Stack -- **Language**: Rust (2021 edition) +- **Language**: Rust (2024 edition) - **JavaScript Engine**: V8 (v140.2.0) - **Build System**: Cargo - **Testing**: Rust's built-in test framework @@ -61,8 +61,9 @@ jstime is a minimal JavaScript runtime built on top of the V8 JavaScript engine. │ └──────────────────────────────────────────────────────┘ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Built-in APIs (builtins/) │ │ -│ │ console | timers | fetch | url | performance │ │ -│ │ base64 | events | structured_clone | fs | wasm │ │ +│ │ console | timers | fetch | streams | url │ │ +│ │ performance | events | base64 | structured_clone │ │ +│ │ text_encoding | crypto | fs | process | wasm │ │ │ └──────────────────────────────────────────────────────┘ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Core Runtime Components │ │ @@ -239,21 +240,29 @@ Each API follows a two-part structure: - Console: Logging and debugging - Timers: setTimeout, setInterval - Performance: High-resolution timing +- Microtask: queueMicrotask **Web APIs**: - Fetch: HTTP client +- Streams: ReadableStream, WritableStream, TransformStream - URL: URL parsing and manipulation - Events: Event and EventTarget **Data APIs**: - Base64: Encoding and decoding - Structured Clone: Deep object cloning +- Text Encoding: TextEncoder and TextDecoder + +**Crypto APIs**: +- Web Crypto: getRandomValues, randomUUID, subtle.digest **System APIs**: - File System: Node.js-compatible fs/promises API +- Process: Environment variables, arguments, working directory **Advanced APIs**: - WebAssembly: WASM module execution (via V8) +- JSON Modules: Import JSON files as ES modules ## Module System diff --git a/core/tests/CONFORMANCE_TESTS.md b/core/tests/CONFORMANCE_TESTS.md index 1acc386f..9688be5e 100644 --- a/core/tests/CONFORMANCE_TESTS.md +++ b/core/tests/CONFORMANCE_TESTS.md @@ -96,6 +96,23 @@ This directory contains conformance tests for jstime's implementation of standar - Argument passing to timer callbacks - Timer ordering and execution +### Event and EventTarget +- **File**: `test_conformance_event.rs` +- **Specification**: [DOM Standard - Events](https://dom.spec.whatwg.org/#events) +- **Tests**: 33 tests +- **Coverage**: + - `Event` constructor and properties (type, target, currentTarget, eventPhase) + - Event state properties (bubbles, cancelable, defaultPrevented, composed, isTrusted, timeStamp) + - Event methods (preventDefault, stopPropagation, stopImmediatePropagation) + - Event phase constants (NONE, CAPTURING_PHASE, AT_TARGET, BUBBLING_PHASE) + - `EventTarget` constructor + - Event listener registration (addEventListener) + - Event listener removal (removeEventListener) + - Event dispatching (dispatchEvent) + - Multiple listeners on same target + - Listener execution order + - Event propagation control + ### Streams API - **File**: `test_conformance_streams.rs` - **Specification**: [WHATWG Streams Standard](https://streams.spec.whatwg.org/) @@ -113,12 +130,71 @@ This directory contains conformance tests for jstime's implementation of standar - Integration with Fetch API (`Response.body`) - Data transformation through pipelines +### Text Encoding API +- **File**: `test_conformance_text_encoding.rs` +- **Specification**: [WHATWG Encoding Standard](https://encoding.spec.whatwg.org/) +- **Tests**: 39 tests +- **Coverage**: + - `TextEncoder` constructor and encoding property + - `TextEncoder.encode()` method with UTF-8 encoding + - `TextEncoder.encodeInto()` method for efficient encoding + - `TextDecoder` constructor with encoding label support + - `TextDecoder` properties (encoding, fatal, ignoreBOM) + - `TextDecoder.decode()` method + - Multi-byte character encoding (2-byte, 3-byte, 4-byte UTF-8) + - Empty string and buffer handling + - Special characters and emoji encoding/decoding + - Buffer overflow handling in encodeInto + - Round-trip encoding and decoding + +### Structured Clone API +- **File**: `test_conformance_structured_clone.rs` +- **Specification**: [HTML Standard - Structured Clone](https://html.spec.whatwg.org/multipage/structured-data.html#structured-cloning) +- **Tests**: 21 tests +- **Coverage**: + - `structuredClone()` global function + - Primitive types (strings, numbers, booleans, null, undefined, BigInt) + - Object cloning with deep copy + - Array cloning with nested structures + - Date object cloning + - RegExp cloning with flags + - Map cloning + - Set cloning + - ArrayBuffer and TypedArray cloning + - Circular reference handling + - Error handling for non-cloneable types (functions, symbols) + +### Crypto API +- **File**: `test_conformance_crypto.rs` +- **Specification**: [W3C Web Cryptography API](https://w3c.github.io/webcrypto/) +- **Tests**: 17 tests +- **Coverage**: + - `crypto` global object + - `crypto.getRandomValues()` with various TypedArray types + - `crypto.randomUUID()` UUID v4 generation + - `crypto.subtle.digest()` with SHA-256, SHA-384, SHA-512 + - Hash output sizes and formats + - Error handling for invalid algorithm names + - Error handling for non-TypedArray inputs + +### JSON Modules +- **File**: `test_conformance_json_modules.rs` +- **Specification**: [JSON modules proposal](https://github.com/tc39/proposal-json-modules) +- **Tests**: 12 tests +- **Coverage**: + - JSON module imports with `import` statement + - Default export behavior + - Object and array JSON imports + - Nested JSON structure imports + - Module resolution for JSON files + - Error handling for invalid JSON + ## Running Conformance Tests To run all conformance tests: ```bash -cargo test --test test_conformance_base64 --test test_conformance_console --test test_conformance_fetch --test test_conformance_performance --test test_conformance_streams --test test_conformance_timers --test test_conformance_url --test test_conformance_webassembly +cargo test test_conformance_ ``` To run a specific conformance test suite: @@ -130,15 +206,30 @@ cargo test --test test_conformance_base64 # Console conformance tests cargo test --test test_conformance_console +# Crypto conformance tests +cargo test --test test_conformance_crypto + +# Event conformance tests +cargo test --test test_conformance_event + # Fetch conformance tests cargo test --test test_conformance_fetch +# JSON modules conformance tests +cargo test --test test_conformance_json_modules + # Performance conformance tests cargo test --test test_conformance_performance # Streams conformance tests cargo test --test test_conformance_streams +# Structured Clone conformance tests +cargo test --test test_conformance_structured_clone + +# Text Encoding conformance tests +cargo test --test test_conformance_text_encoding + # Timers conformance tests cargo test --test test_conformance_timers @@ -181,8 +272,8 @@ When adding new conformance tests: ## Total Coverage -- **Total Test Files**: 8 -- **Total Tests**: 190 -- **APIs Covered**: Base64 Encoding, Console, Fetch, Performance, Streams, Timers, URL, WebAssembly +- **Total Test Files**: 13 +- **Total Tests**: 312 +- **APIs Covered**: Base64 Encoding, Console, Crypto, Event and EventTarget, Fetch, JSON Modules, Performance, Streams, Structured Clone, Text Encoding, Timers, URL, WebAssembly All tests pass ✓ diff --git a/docs/apis/modules.md b/docs/apis/modules.md index d64308e3..75717f84 100644 --- a/docs/apis/modules.md +++ b/docs/apis/modules.md @@ -5,6 +5,7 @@ This document describes the module system support in jstime, including ES Module ## Table of Contents - [ES Modules](#es-modules) +- [JSON Modules](#json-modules) - [WebAssembly](#webassembly) @@ -276,3 +277,83 @@ $ jstime main.js # The runtime automatically handles module imports ``` +## JSON Modules + +jstime supports importing JSON files as ES modules, following the [JSON modules proposal](https://github.com/tc39/proposal-json-modules). This allows you to import JSON data directly into your JavaScript code. + +**📁 Example:** See [examples/json-import-example.js](../../examples/json-import-example.js) for a complete demonstration. + +### Features + +- Import JSON files using standard `import` syntax +- JSON data is parsed and available as the default export +- Type-safe: imported values are standard JavaScript objects/arrays +- Automatic file resolution with `.json` extension + +### Examples + +**data.json** +```json +{ + "name": "jstime", + "version": "0.60.0", + "features": ["ES Modules", "WebAssembly", "Fetch API"] +} +``` + +**app.js** +```javascript +// Import JSON data as the default export +import data from './data.json'; + +console.log(data.name); // "jstime" +console.log(data.version); // "0.60.0" +console.log(data.features[0]); // "ES Modules" +``` + +**config-example.js** +```javascript +// Import JSON configuration +import config from './config.json'; + +// Use the configuration data +console.log(`App: ${config.app.name}`); +console.log(`Environment: ${config.environment}`); +console.log(`API URL: ${config.api.url}`); + +// JSON data is a regular JavaScript object +const features = config.features.map(f => f.toUpperCase()); +console.log('Features:', features); +``` + +**array-example.js** +```javascript +// Import a JSON array +import users from './users.json'; + +// Work with the imported array +users.forEach(user => { + console.log(`${user.name}: ${user.email}`); +}); + +// Filter and transform +const admins = users.filter(u => u.role === 'admin'); +console.log(`Found ${admins.length} administrators`); +``` + +### Usage Notes + +- JSON modules are read-only: the imported data is a constant +- The JSON file must be valid JSON (trailing commas are not allowed) +- JSON modules use the default export pattern +- The imported data is deeply frozen (immutable) + +### Running JSON Module Examples + +```bash +# Run a module that imports JSON +$ jstime app.js + +# The runtime automatically handles JSON module imports +``` + diff --git a/docs/runtime.md b/docs/runtime.md index 043f869a..626cf3c0 100644 --- a/docs/runtime.md +++ b/docs/runtime.md @@ -126,17 +126,16 @@ $ jstime module.mjs ## Limitations and Future Work -While jstime provides a solid foundation for JavaScript execution, there are some limitations: +While jstime provides a solid foundation for JavaScript execution with many web standard APIs, there are some limitations: -- **No file system API**: Currently no built-in API for reading/writing files -- **No process API**: No access to environment variables or process information -- **Limited streaming**: Fetch API doesn't support streaming response bodies - **No WebSocket support**: WebSocket API not yet implemented +- **Limited DOM APIs**: No DOM APIs (this is a server-side runtime) +- **Limited Node.js compatibility**: Only a subset of Node.js APIs are available Future enhancements being considered: -- **WASI (WebAssembly System Interface)**: Support for WASI to enable WebAssembly modules to access file system and other system APIs +- **WASI (WebAssembly System Interface)**: Support for WASI to enable WebAssembly modules to access additional system APIs - **Additional Web APIs**: More browser APIs as they become relevant -- **Node.js compatibility layer**: Compatibility APIs for running Node.js code +- **Expanded Node.js compatibility**: Additional Node.js APIs where applicable ## Additional Resources