Skip to content

Commit 69f3087

Browse files
ssrlivessrlive
committed
Add documentation and publishing metadata
- Add comprehensive README.md with badges, features, usage examples, and API docs - Create MIT LICENSE file for open source distribution - Update Cargo.toml with crates.io publishing metadata (license, description, repository, keywords, categories) - Include README.md in crate documentation via lib.rs - Fix README.md doc tests and remove invalid codecov badge - Prepare project for crates.io publication and professional presentation
1 parent 646fd24 commit 69f3087

File tree

4 files changed

+216
-0
lines changed

4 files changed

+216
-0
lines changed

‎Cargo.toml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,14 @@
22
name = "javascript"
33
version = "0.1.0"
44
edition = "2024"
5+
license = "MIT"
6+
description = "A JavaScript engine implementation in Rust"
7+
repository = "https://github.com/ssrlive/javascript"
8+
homepage = "https://github.com/ssrlive/javascript"
9+
documentation = "https://docs.rs/javascript"
10+
readme = "README.md"
11+
keywords = ["javascript", "engine", "interpreter", "runtime"]
12+
categories = ["development-tools", "parsing"]
513

614
[dependencies]
715
chrono = { version = "0.4", features = ["serde"] }

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 ssrlive
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# JavaScript Engine in Rust
2+
3+
[![Crates.io](https://img.shields.io/crates/v/javascript.svg)](https://crates.io/crates/javascript)
4+
[![Documentation](https://docs.rs/javascript/badge.svg)](https://docs.rs/javascript)
5+
[![License](https://img.shields.io/crates/l/javascript.svg)](https://github.com/ssrlive/javascript/blob/master/LICENSE)
6+
[![Rust](https://img.shields.io/badge/rust-2024+-blue.svg)](https://www.rust-lang.org/)
7+
[![Build Status](https://img.shields.io/github/actions/workflow/status/ssrlive/javascript/ci.yml)](https://github.com/ssrlive/javascript/actions)
8+
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](https://github.com/ssrlive/javascript/actions)
9+
[![Downloads](https://img.shields.io/crates/d/javascript.svg)](https://crates.io/crates/javascript)
10+
11+
A JavaScript engine implementation written in Rust, providing a complete JavaScript runtime
12+
with support for modern language features.
13+
14+
## Features
15+
16+
### Core JavaScript Features
17+
- **Variables and Scoping**: `let`, `const`, `var` declarations
18+
- **Data Types**: Numbers, strings, booleans, objects, arrays, functions, classes
19+
- **Control Flow**: `if/else`, loops (`for`, `while`, `do-while`), `switch`, `try/catch/finally`
20+
- **Functions**: Regular functions, arrow functions, async/await
21+
- **Classes**: Class definitions, inheritance, static methods/properties, getters/setters
22+
- **Promises**: Promise creation, resolution, async/await syntax
23+
- **Destructuring**: Array and object destructuring
24+
- **Template Literals**: String interpolation
25+
- **Optional Chaining**: Safe property access (`?.`)
26+
- **Nullish Coalescing**: `??` operator and assignments (`??=`)
27+
- **Logical Assignments**: `&&=`, `||=` operators
28+
29+
### Built-in Objects and APIs
30+
- **Array**: Full array methods and static constructors
31+
- **Object**: Property manipulation, prototype chain
32+
- **String**: String methods and UTF-16 support
33+
- **Number**: Number parsing and formatting
34+
- **Math**: Mathematical functions and constants
35+
- **Date**: Date/time handling with chrono integration
36+
- **RegExp**: Regular expressions with regex crate
37+
- **JSON**: JSON parsing and stringification
38+
- **Console**: Logging and debugging utilities
39+
- **OS**: File system operations, path manipulation
40+
- **File**: File I/O operations
41+
42+
### Advanced Features
43+
- **Modules**: Import/export system with `import * as name from "module"`
44+
- **Event Loop**: Asynchronous task scheduling and execution
45+
- **Memory Management**: Reference counting and garbage collection
46+
- **FFI Integration**: C-compatible API similar to QuickJS
47+
48+
## Installation
49+
50+
Add this to your `Cargo.toml`:
51+
52+
```toml
53+
[dependencies]
54+
javascript = "0.1.0"
55+
```
56+
57+
## Usage
58+
59+
### Basic Evaluation
60+
61+
```rust
62+
use javascript::evaluate_script;
63+
64+
let result = evaluate_script(r#"
65+
let x = 42;
66+
let y = x * 2;
67+
y + 10
68+
"#).unwrap();
69+
70+
match result {
71+
javascript::Value::Number(n) => println!("Result: {}", n), // Output: Result: 94
72+
_ => println!("Unexpected result"),
73+
}
74+
```
75+
76+
### Using Built-in Modules
77+
78+
```rust
79+
use javascript::evaluate_script;
80+
81+
let result = evaluate_script(r#"
82+
import * as console from "console";
83+
import * as os from "os";
84+
85+
console.log("Hello from JavaScript!");
86+
let cwd = os.getcwd();
87+
cwd
88+
"#).unwrap();
89+
```
90+
91+
### Command Line Interface
92+
93+
The crate provides two example binaries:
94+
95+
#### `js` - QuickJS-compatible FFI interface
96+
```bash
97+
cargo run --example js -- -e "console.log('Hello World!')"
98+
cargo run --example js script.js
99+
```
100+
101+
#### `rust_js` - High-level Rust interface
102+
```bash
103+
cargo run --example rust_js -- -e "1 + 2 * 3"
104+
cargo run --example rust_js script.js
105+
```
106+
107+
## API Reference
108+
109+
### Core Functions
110+
111+
- `evaluate_script(code: &str) -> Result<Value, JSError>`: Evaluate JavaScript code
112+
- `evaluate_script_async(code: &str) -> Result<Value, JSError>`: Evaluate with async support
113+
- `tokenize(code: &str) -> Result<Vec<Token>, JSError>`: Lexical analysis
114+
115+
### FFI Interface (QuickJS-compatible)
116+
117+
- `JS_NewRuntime() -> *mut JSRuntime`: Create a new runtime
118+
- `JS_NewContext(rt: *mut JSRuntime) -> *mut JSContext`: Create a context
119+
- `JS_Eval(ctx, code, len, filename, flags) -> JSValue`: Evaluate code
120+
- `JS_NewString(ctx, str) -> JSValue`: Create a string value
121+
- `JS_DefinePropertyValue(ctx, obj, atom, val, flags) -> i32`: Define object property
122+
123+
### Value Types
124+
125+
The engine uses a `Value` enum to represent JavaScript values. See the source code for the complete definition, which includes variants for numbers, strings, objects, functions, promises, and more.
126+
127+
## Architecture
128+
129+
The engine consists of several key components:
130+
131+
- **Parser**: Converts JavaScript source code into an AST
132+
- **Evaluator**: Executes the AST in a managed environment
133+
- **Object System**: Reference-counted objects with prototype chains
134+
- **Memory Management**: Custom allocators and garbage collection
135+
- **FFI Layer**: C-compatible interface for embedding
136+
- **Built-in Modules**: Standard library implementations
137+
138+
## Testing
139+
140+
Run the test suite:
141+
142+
```bash
143+
cargo test
144+
```
145+
146+
Run with logging:
147+
148+
```bash
149+
RUST_LOG=debug cargo test
150+
```
151+
152+
## Performance
153+
154+
The engine is optimized for:
155+
- Fast parsing and evaluation
156+
- Efficient memory usage with Rc<RefCell<>>
157+
- Minimal allocations during execution
158+
- QuickJS-compatible FFI for high-performance embedding
159+
160+
## Limitations
161+
162+
- No JIT compilation (interpreted only)
163+
- Limited browser API compatibility
164+
- Some ES6+ features may be incomplete
165+
- Error handling could be more robust
166+
167+
## Contributing
168+
169+
Contributions are welcome! Areas for improvement:
170+
171+
- JIT compilation support
172+
- More comprehensive test coverage
173+
- Browser API compatibility
174+
- Performance optimizations
175+
- Additional language features
176+
177+
## License
178+
179+
This project is licensed under the MIT License - see the LICENSE file for details.
180+
181+
## Acknowledgments
182+
183+
- Inspired by the QuickJS JavaScript engine
184+
- Built with Rust's powerful type system and memory safety guarantees
185+
- Uses several excellent Rust crates: `regex`, `chrono`, `serde_json`, etc.

‎src/lib.rs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
#![doc = include_str!("../README.md")]
2+
13
// pub mod cutils;
24
// pub mod libregexp;
35
// pub mod libunicode;

0 commit comments

Comments
 (0)