ZigScript (Work in Progress)

Overview

ZigScript is a powerful tool designed to seamlessly transpile TypeScript--and, by extension, JavaScript--code to Zig, allowing developers to take advantage of Zig's cross-compilation and low-level optimization capabilities while preserving access to high-level language constructs afforded by JavaScript and TypeScript. This README file provides essential information on using ZigScript, its features, and design principles.

Table of Contents

• Getting Started
• Features
• Usage
• Design Principles
• Contributing
• License

Getting Started

To experiment with ZigScript and contribute to its development, follow these steps:

1. Install Zig on your machine (https://ziglang.org/download/).
2. Clone this repository: git clone https://github.com/clay-curry/ZigScript.git
3. Build the script: zig build
4. Start exploring and enhancing the codebase!

Features

• JavaScript and TypeScript Support: ZigScript currently supports a variety of JavaScript and TypeScript features, but the project is a work in progress, and not all features may be fully supported.

• Performance: The script leverages Zig's performance-oriented design, with ongoing efforts to optimize and enhance code generation.

• Error Reporting: Clear and concise error messages are provided, but improvements are continually being made to enhance error transparency.

• Maintainability: The generated Zig code aims to be readable and maintainable, but ongoing efforts are in place to improve code quality.

Usage

Whatever your use case, ZigScript requires having Zig installed on your machine. To install Zig, follow the instructions here.

Transpile JavaScript | TypeScript

To transpile a JavaScript or TypeScript file, use the following command:

zig build run -- input.js

Replace input.js with the path to your JavaScript or TypeScript file. The transpiled Zig code will be generated in the same directory with the .zig extension.

Build

Currently this only works on Linux. To build a distributable npm package, we will use the Bun Runtime. First, install Bun:

curl -fsSL https://bun.sh/install | bash

For additional options and advanced Bun usage, refer to Bun documentation. Using the runtime defined by Bun, we will execute the build script defined in our local package.json file as follows,

bun run build

Note that the above command builds the debuggable ZigScript executable within the zig-out directory, which, in addition to Zig output files, produces compiler log messages and additional compilation information such as intermediate AST representations, relocatable object files, resolved paths, and potentially other useful information in the future.

To build an equivalent

Design Principles

1. Preservation of High-Level Semantics: ZigScript prioritizes maintaining the high-level semantics of JavaScript and TypeScript code, with ongoing enhancements to cover a broader range of language features.

2. Readability and Understandability: The generated Zig code is designed to be readable and understandable, with continuous efforts to improve code clarity and structure.

3. Progressive Enhancement: ZigScript supports a progressive enhancement approach, allowing you to incrementally transpile and optimize parts of your codebase as ongoing development progresses.

4. Error Transparency: Clear error messages are provided during the transpilation process, and ongoing work is being done to improve error reporting for a smoother development experience.

5. Performance-Oriented: The script aims to generate Zig code that is performant, with ongoing optimizations to harness Zig's low-level capabilities more effectively.

Contributing

Contributions are highly encouraged! See the Contribution Guidelines for details on how to get involved.

License

ZigScript is licensed under the MIT License - see the LICENSE file for details.