MINI-CLOJURE-TS

Um interpretador e transpilador de Clojure robusto e modular escrito em TypeScript.

---

Table of Contents

Table of Contents

• Overview
• Features
• Project Structure
• Project Index
• Getting Started
  • Prerequisites
  • Installation
  • Usage
  • Testing
• Roadmap
• Contributing
• License
• Acknowledgments

---

Overview

Mini-Clojure-TS é um interpretador e transpilador de Lisp moderno inspirado em Clojure, construído inteiramente em TypeScript. Este projeto foi desenvolvido com foco em arquitetura modular, performance e extensibilidade. Ele suporta recursos avançados como otimização de chamada de cauda (TCO), metaprogramação via Macros, interoperabilidade direta com JavaScript e agora também transpilação para código JavaScript executável.

---

Features

	Componente	Detalhes
⚙️	Arquitetura	Design modular que separa Tokenizador, Analisador Sintático, Avaliador, Ambiente e Transpilador Sistema de tratamento de erros tipado com classes de erro personalizadas Separação clara da Biblioteca Padrão (stdlib)
⚡️	Desempenho	Otimização de Chamada de Cauda (TCO): Implementa a técnica de Trampolim para lidar com recursão infinita sem estouro de pilha Processamento e avaliação eficientes da AST
🧠	Metaprogramação	Suporte completo a macros (defmacro, quasiquote, unquote) Expansão de macros em tempo de execução Capacidade de estender a sintaxe da linguagem dinamicamente
🌐	Interoperabilidade com JS	Acesso direto a globalThis via js/Namespace Instanciação de classes JS (new) Encadeamento de métodos e acesso a propriedades (operador .)
📦	Estruturas de Dados	Suporte para listas (), vetores [] e mapas de hash {} Palavras-chave (:key), átomos (estado mutável) e tipos primitivos Operações no estilo imutável via funções da stdlib
🛡️	Tratamento de Erros	Tratamento de exceções Try/Catch Tipos de erro personalizados (ClojureError, InvalidParamError, ClojureReferenceError) Relatórios de erro detalhados com contexto
🔄	Gerenciamento de Estado	Átomos para estado mutável com atom, deref, reset!, swap! Atualizações de estado thread-safe
🎯	Desestruturação	Suporte completo à desestruturação em vinculações let e parâmetros de função Suporte para parâmetros rest & Padrões de desestruturação aninhados
⚙️	Transpilador	Compila código Clojure para JavaScript executável Suporte à transpilação pela linha de comando Gera código JS limpo e executável
💻	REPL	Loop interativo de leitura-avaliação-impressão com realce de sintaxe Estado de ambiente persistente Relatório de erros detalhado

---

Project Structure

└── mini-clojure-ts/
    ├── .github
    │   └── workflows
    ├── src/
    │   ├── core/
    │   │   ├── Environment.ts
    │   │   ├── Evaluator.ts
    │   │   ├── Parser.ts
    │   │   ├── Tokenizer.ts
    │   │   ├── Trampoline.ts
    │   │   └── Transpiler.ts
    │   ├── errors/
    │   │   ├── ClojureError.ts
    │   │   ├── InvalidParamError.ts
    │   │   └── ReferenceError.ts
    │   ├── stdlib/
    │   │   └── index.ts
    │   ├── types/
    │   │   └── index.ts
    │   └── index.ts
    ├── tests/
    │   ├── atomos.clj
    │   ├── compilador.clj
    │   ├── compilador.js
    │   ├── destructuring.clj
    │   ├── erros.clj
    │   ├── estouro.clj
    │   ├── filtro.clj
    │   ├── final.clj
    │   ├── interop.clj
    │   ├── listas.clj
    │   ├── macros.clj
    │   ├── main.clj
    │   ├── map.clj
    │   ├── multiplo.clj
    │   └── soma.clj
    ├── README.md
    ├── LICENSE
    ├── package.json
    ├── tsconfig.json
    ├── .eslintrc.json
    ├── .prettierrc
    └── pnpm-lock.yaml

Project Index

MINI-CLOJURE-TS/

src

⦿ src

File Name	Summary
index.ts	- Ponto de entrada principal da aplicação - Gerencia argumentos CLI para executar arquivos, iniciar REPL ou transpilar código - Implementa REPL interativo com highlighting de sintaxe - Suporte a transpilação para JavaScript

core

⦿ src.core

File Name	Summary
Environment.ts	- Gerencia escopo de variáveis e closures - Implementa cadeia de escopos (scope chain) - Suporte a destructuring em bindings
Evaluator.ts	- Cérebro do interpretador - Processa AST, lida com forms especiais (`def`, `if`, `fn`, `let`, `try/catch`) - Expansão de macros e execução de código - Suporte a destructuring e TCO
Parser.ts	- Converte tokens em Abstract Syntax Tree (AST) - Lida com estruturas recursivas (Lists, Vectors, Maps) - Suporte a reader macros (`'`, `` ` ``, `~`, `@`)
Tokenizer.ts	- Análise léxica usando Regex - Lida com comentários, strings, símbolos e caracteres especiais - Suporte a keywords e números
Trampoline.ts	- Implementa padrão Trampoline para Tail Call Optimization (TCO) - Permite recursão infinita sem stack overflow
Transpiler.ts	- NOVO: Compila AST Clojure para código JavaScript executável - Suporte a forms básicos, funções, condicionais e interop JS - Gera código limpo e otimizado

errors

⦿ src.errors

File Name	Summary
ClojureError.ts	- Classe base para todos os erros do interpretador
InvalidParamError.ts	- Erro para parâmetros inválidos em funções e forms especiais
ReferenceError.ts	- Erro para símbolos não encontrados no ambiente

stdlib

⦿ src.stdlib

File Name	Summary
index.ts	- Biblioteca padrão com funções essenciais (`map`, `filter`, `+`, `str`, etc.) - Funções de interoperação JavaScript - Operações com átomos (`atom`, `deref`, `reset!`, `swap!`) - Funções para manipulação de coleções

types

⦿ src.types

File Name	Summary
index.ts	- Tipos de dados fundamentais do Clojure - `ClojureVector`, `ClojureKeyword`, `ClojureMap`, `ClojureAtom`, `ClojureMacro` - Interfaces e tipos para AST e funções de usuário

tests

⦿ tests

File Name	Summary
atomos.clj	- Testes de átomos e estado mutável
compilador.clj	- Programa de exemplo para transpilação
compilador.js	- NOVO: Saída transpilada do compilador.clj
destructuring.clj	- Testes de destructuring em let e funções
erros.clj	- Testes de try/catch e tratamento de erros
estouro.clj	- Testes de Tail Call Optimization (TCO)
filtro.clj	- Implementação da função filter
final.clj	- Teste final integrado
interop.clj	- Testes de interoperabilidade JavaScript
listas.clj	- Manipulação básica de listas
macros.clj	- Testes de metaprogramação com macros
main.clj	- Programa principal de exemplo
map.clj	- Testes da função map
multiplo.clj	- Testes de blocos do e strings
soma.clj	- Testes de recursão básica

---

Getting Started

Prerequisites

This project requires the following dependencies:

• Runtime: Node.js (v18+)
• Package Manager: pnpm (recommended) or npm

Installation

1. Clone the repository:

❯ git clone https://github.com/BrunoL28/mini-clojure-ts.git

2. Navigate to the project directory:

❯ cd mini-clojure-ts

3. Install the dependencies: Using pnpm:

❯ pnpm install

Using npm:

❯ npm install

Usage

Start the REPL (Interactive Mode):

❯ pnpm start

Execute a Clojure file:

❯ pnpm start -- tests/final.clj

Transpile a Clojure file to JavaScript:

❯ pnpm start -- -t tests/compilador.clj

or

❯ pnpm start -- --transpile tests/compilador.clj

Testing

The project includes a comprehensive suite of .clj files to test various features:

# Test Tail Call Optimization
❯ pnpm start -- tests/estouro.clj

# Test Macros
❯ pnpm start -- tests/macros.clj

# Test Atoms and State Management
❯ pnpm start -- tests/atomos.clj

# Test Destructuring
❯ pnpm start -- tests/destructuring.clj

# Test Error Handling
❯ pnpm start -- tests/erros.clj

# Test JavaScript Interop
❯ pnpm start -- tests/interop.clj

# Test Transpilation
❯ pnpm start -- -t tests/compilador.clj

---

API Pública (Embed)

O Mini-Clojure-TS pode ser usado como uma biblioteca em outros projetos TypeScript/JavaScript.

import { runSource, createGlobalEnv, parse } from "./src/index.js";

// 1. Execução Simples
const code = "(+ 10 20)";
const result = runSource(code);
console.log(result); // 30

// 2. Ambiente Personalizado
const env = createGlobalEnv();
runSource("(def x 42)", { env });
const x = runSource("x", { env });
console.log(x); // 42

// 3. Acesso à AST
const ast = parse('(print "Ola")');
console.log(ast);
// [ ['print', "Ola"] ]

---

Roadmap

• v3.0: Rastreabilidade de Erros, CI e testes automatizados, Separação Engine/CLI, Multiline + Histórico no REPL
• v4.0: Escapes e erros melhores, identical (para ponteiros), Printing legível, Ferramentas de Macro, Destructuring de Mapas
• v5.0: Sec/Core Functions, Predicados e Tipos, Macros Utilitárias, Utilitários e IO básicos para uso no Node
• v6.0: Loader e Cache, Namespaces, Empacotamento
• v7.0: Transpiler como Compilador Útil, Runtime de Suporte, Macroexpand em Compile-Time, Output e Targets
• v8.0: Source Maps, Watch Mode, Sandbox/Whitelist, Definição de Política de Interop

---

Contributing

• 💬 Join the Discussions: Share your insights, provide feedback, or ask questions.
• 🐛 Report Issues: Submit bugs found or log feature requests.
• 💡 Submit Pull Requests: Review open PRs, and submit your own PRs.

Contributing Guidelines

1. Fork the Repository: Start by forking the project repository to your github account.
2. Clone Locally: Clone the forked repository to your local machine.
3. Create a New Branch: Always work on a new branch.

git checkout -b feature/my-new-feature

4. Make Your Changes: Develop and test your changes locally.
5. Commit Your Changes: Commit with a clear message.
6. Push to github: Push the changes to your forked repository.
7. Submit a Pull Request: Create a PR against the original project repository.

---

License

Distributed under the MIT License. See LICENSE for more information.

---

Acknowledgments

• Inspired by Rich Hickey's Clojure.
• Built with TypeScript for type safety and developer experience.
• Thanks to all contributors and testers who helped shape this project.

⬆ Back to Top