jpsx 0.1.16

package/README.md

@@ -0,0 +1,242 @@
+# JPS (Just Python Script)
+
+A Python-like language that compiles to JavaScript, designed to integrate seamlessly with **any frontend framework**.
+
+[![npm version](https://img.shields.io/npm/v/jps.svg)](https://www.npmjs.com/package/jps)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
+
+## ✨ Features
+
+- 🐍 **Python-like syntax** that compiles to clean JavaScript
+- ⚡ **Standalone file integration** - Import `.jps` files like `.jsx/.tsx` files!
+- 🔥 **Hot Module Replacement (HMR)** - Instant feedback during development
+- ⚡ **Zero-config integration** with React, Vue, Svelte, Angular, and more
+- 📦 **Multiple output formats**: ESM, CommonJS, IIFE, UMD
+- 🔌 **Flexible runtime modes**: Inline, external, CDN, or custom
+- 🛠️ **Build tool plugins** for Vite, Webpack, Rollup, esbuild
+- 🌐 **Browser-ready**: Works without any build step
+- 📝 **TypeScript support** with auto-generated declarations
+
+## 🚀 Quick Start
+
+### Standalone File Integration (⚡ Recommended)
+
+Import `.jps` files directly in your code - just like `.tsx` files!
+
+```python
+# math.jps - a real file!
+def add(a, b):
+    return a + b
+
+class Calculator:
+    def __init__(self):
+        self.value = 0
+```
+
+```typescript
+// App.tsx - just import and use!
+import { add, Calculator } from './math.jps';
+
+const sum = add(10, 20);
+const calc = new Calculator();
+```
+
+**[See full example →](examples/react-vite-standalone/)**
+
+---
+
+### As a CLI Tool
+
+```bash
+# Install globally
+npm install -g jps
+
+# Create a new project
+jps init my-project
+cd my-project
+jps run main.jps
+```
+
+### As a Library (Runtime Compilation)
+
+```bash
+# Install in your project
+npm install jps
+```
+
+#### React
+
+```javascript
+import { compile } from 'jps';
+
+function App() {
+  const jpsCode = `
+def greet(name):
+    return "Hello, " + name
+
+print(greet("React"))
+  `;
+
+  const result = compile(jpsCode, {
+    format: 'iife',
+    runtimeMode: 'inline'
+  });
+
+  eval(result.code); // Outputs: Hello, React
+}
+```
+
+#### Vue
+
+```vue
+<script setup>
+import { compile } from 'jps';
+const result = compile('print("Hello Vue!")', {
+  format: 'iife',
+  runtimeMode: 'inline'
+});
+eval(result.code);
+</script>
+```
+
+#### Browser (No Build Step)
+
+```html
+<script type="module">
+  import { compile } from 'https://cdn.jsdelivr.net/npm/jps@latest/dist/api/index.js';
+  const result = compile('print("Hello Browser!")', {
+    format: 'iife',
+    runtimeMode: 'inline'
+  });
+  eval(result.code);
+</script>
+```
+
+## 📖 Documentation
+
+- **[Standalone File Integration](docs/STANDALONE_INTEGRATION.md)** - ⚡ Import .jps like .tsx (recommended!)
+- **[Integration Guide](docs/INTEGRATION.md)** - Complete guide for all frameworks
+- **[Quick Start](docs/QUICKSTART.md)** - 30-second integration examples
+- **[Syntax Guide](docs/syntax.md)** - JPS language syntax
+- **[Standard Library](docs/stdlib.md)** - Built-in functions
+- **[API Reference](docs/API.md)** - Programmatic API
+
+## 🎯 Use Cases
+
+- **Code Playgrounds**: Build interactive Python-like editors
+- **Educational Tools**: Teach Python concepts in the browser
+- **Scripting**: Add Python-like scripting to your JavaScript app
+- **DSL**: Create domain-specific languages with Python syntax
+- **Prototyping**: Rapid development with Python-like syntax
+
+## 📦 CLI Commands
+
+- `jps build <file>` - Compile JPS to JavaScript
+- `jps run <file>` - Compile and execute
+- `jps watch <file>` - Watch for changes and recompile
+- `jps init [name]` - Initialize a new JPS project
+- `jps doctor` - Verify environment setup
+
+## 🔧 Programmatic API
+
+```javascript
+import { compile, compileToJS, getRuntime } from 'jps';
+
+// Full API with metadata
+const result = compile(source, {
+  format: 'esm',           // Output format: 'esm' | 'cjs' | 'iife' | 'umd'
+  runtimeMode: 'inline',   // Runtime: 'inline' | 'external' | 'cdn' | 'none'
+  moduleName: 'MyApp',     // For IIFE/UMD
+  sourceMap: true,         // Include source maps
+  standalone: false        // Bundle everything
+});
+
+// Simple API (just returns code)
+const jsCode = compileToJS(source);
+
+// Get runtime library code
+const runtime = getRuntime();
+```
+
+## 🎨 Framework Examples
+
+Check out the [examples/](examples/) directory for complete working examples:
+
+- **React** - Vite plugin, Webpack loader, runtime compilation
+- **Vue 3** - Composition API integration
+- **Svelte** - Component integration
+- **Angular** - Service integration
+- **Next.js** - App Router and Pages Router
+- **Vanilla Browser** - No build step required
+
+## 🛠️ Build Tool Plugins
+
+### Vite
+
+```javascript
+// vite.config.js
+import { jpsPlugin } from './vite-plugin-jps';
+
+export default {
+  plugins: [jpsPlugin()]
+};
+```
+
+### Webpack
+
+```javascript
+// webpack.config.js
+module.exports = {
+  module: {
+    rules: [
+      { test: /\.jps$/, use: 'jps-loader' }
+    ]
+  }
+};
+```
+
+See [INTEGRATION.md](docs/INTEGRATION.md) for Rollup, esbuild, and more.
+
+## 🌟 Why JPS?
+
+1. **Framework Agnostic**: Works with React, Vue, Svelte, Angular, and vanilla JS
+2. **Flexible Output**: Choose the format that fits your needs
+3. **Modern & Production-Ready**: Built with TypeScript, full test coverage
+4. **Developer Friendly**: Simple API, great error messages, comprehensive docs
+5. **Lightweight**: Minimal dependencies, tree-shakeable
+
+## 🏗️ Development
+
+Prerequisites: Node.js 18+
+
+```bash
+# Clone the repository
+git clone https://github.com/your-repo/jps.git
+cd jps
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+```
+
+## 📄 License
+
+ISC - See [LICENSE](LICENSE) file for details
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our contributing guidelines first.
+
+## 📮 Support
+
+- **Issues**: [GitHub Issues](https://github.com/your-repo/jps/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/your-repo/jps/discussions)
+
+---
+
+**Made with ❤️ by Loaii abdalslam**

package/dist/api/__tests__/compile.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=compile.test.d.ts.map

package/dist/api/__tests__/compile.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.test.d.ts","sourceRoot":"","sources":["../../../src/api/__tests__/compile.test.ts"],"names":[],"mappings":""}

package/dist/api/__tests__/compile.test.js

@@ -0,0 +1,336 @@
+import { compile, compileToJS, getRuntime } from "../index.js";
+describe("compile() - Basic Functionality", () => {
+    test("should compile simple JPS code", () => {
+        const source = 'print("Hello World")';
+        const result = compile(source);
+        expect(result.code).toBeDefined();
+        expect(result.code).toContain("print");
+        expect(result.code).toContain("Hello World");
+    });
+    test("should return CompileResult with code property", () => {
+        const source = 'x = 5';
+        const result = compile(source);
+        expect(result).toHaveProperty("code");
+        expect(typeof result.code).toBe("string");
+    });
+    test("should compile function definitions", () => {
+        const source = `
+def greet(name):
+    return "Hello, " + name
+
+print(greet("World"))
+    `;
+        const result = compile(source);
+        expect(result.code).toContain("function greet");
+        expect(result.code).toContain("return");
+    });
+    test("should compile list comprehensions", () => {
+        const source = '[x * 2 for x in range(5)]';
+        const result = compile(source);
+        expect(result.code).toContain("for");
+        expect(result.code).toContain("push");
+    });
+    test("should handle multiple statements", () => {
+        const source = `
+x = 10
+y = 20
+z = x + y
+print(z)
+    `;
+        const result = compile(source);
+        expect(result.code).toContain("var x");
+        expect(result.code).toContain("var y");
+        expect(result.code).toContain("var z");
+    });
+});
+describe("compile() - Output Formats", () => {
+    const source = 'print("test")';
+    test("should generate ESM format by default", () => {
+        const result = compile(source);
+        expect(result.code).toContain("import");
+    });
+    test("should generate ESM format when specified", () => {
+        const result = compile(source, { format: "esm" });
+        expect(result.code).toContain("import {");
+        expect(result.code).toMatch(/from\s+['"]/);
+    });
+    test("should generate CommonJS format", () => {
+        const result = compile(source, { format: "cjs" });
+        expect(result.code).toContain("require");
+        expect(result.code).toMatch(/const\s+{.*}\s*=\s*require/);
+    });
+    test("should generate IIFE format", () => {
+        const result = compile(source, { format: "iife", moduleName: "TestModule" });
+        expect(result.code).toContain("(function");
+        expect(result.code).toContain("TestModule");
+    });
+    test("should generate UMD format", () => {
+        const result = compile(source, { format: "umd", moduleName: "TestLib" });
+        expect(result.code).toContain("define.amd");
+        expect(result.code).toContain("module.exports");
+        expect(result.code).toContain("TestLib");
+    });
+});
+describe("compile() - Runtime Modes", () => {
+    const source = 'print("test")';
+    test("should use external runtime by default", () => {
+        const result = compile(source);
+        expect(result.code).toContain("./jps_runtime.js");
+    });
+    test("should use external runtime mode", () => {
+        const result = compile(source, { runtimeMode: "external" });
+        expect(result.code).toContain("jps_runtime");
+    });
+    test("should inline runtime code", () => {
+        const result = compile(source, { runtimeMode: "inline" });
+        expect(result.code).toContain("function print");
+        expect(result.code).toContain("function range");
+        expect(result.code).not.toContain("import");
+    });
+    test("should use CDN runtime with custom URL", () => {
+        const cdnUrl = "https://example.com/runtime.js";
+        const result = compile(source, { runtimeMode: "cdn", cdnUrl });
+        expect(result.code).toContain(cdnUrl);
+    });
+    test("should use default CDN URL", () => {
+        const result = compile(source, { runtimeMode: "cdn" });
+        expect(result.code).toContain("cdn.jsdelivr.net");
+    });
+    test("should exclude runtime when mode is none", () => {
+        const result = compile(source, { runtimeMode: "none" });
+        expect(result.code).not.toContain("import");
+        expect(result.code).not.toContain("require");
+        expect(result.code).not.toContain("function print");
+    });
+});
+describe("compile() - Source Maps", () => {
+    const source = 'x = 10';
+    test("should not include source map by default", () => {
+        const result = compile(source);
+        expect(result.map).toBeUndefined();
+        expect(result.ast).toBeUndefined();
+    });
+    test("should include AST when sourceMap is enabled", () => {
+        const result = compile(source, { sourceMap: true });
+        expect(result.ast).toBeDefined();
+        expect(result.ast).toHaveProperty("body");
+    });
+});
+describe("compile() - Module Names", () => {
+    const source = 'print("test")';
+    test("should use custom module name in IIFE", () => {
+        const result = compile(source, {
+            format: "iife",
+            moduleName: "MyCustomApp",
+            runtimeMode: "inline"
+        });
+        expect(result.code).toContain("MyCustomApp");
+    });
+    test("should use custom module name in UMD", () => {
+        const result = compile(source, {
+            format: "umd",
+            moduleName: "MyLibrary"
+        });
+        expect(result.code).toContain("MyLibrary");
+    });
+    test("should use default module name when not specified", () => {
+        const result = compile(source, {
+            format: "iife",
+            runtimeMode: "inline"
+        });
+        expect(result.code).toContain("JPSModule");
+    });
+});
+describe("compile() - Error Handling", () => {
+    test("should throw error for invalid syntax", () => {
+        const source = "def invalid syntax here";
+        expect(() => compile(source)).toThrow();
+    });
+    test("should provide error details", () => {
+        const source = "this is not valid jps";
+        try {
+            compile(source);
+            fail("Should have thrown an error");
+        }
+        catch (error) {
+            expect(error).toBeDefined();
+        }
+    });
+});
+describe("compile() - Complex Programs", () => {
+    test("should compile classes", () => {
+        const source = `
+class Person:
+    def __init__(self, name):
+        self.name = name
+
+    def greet(self):
+        return "Hello, " + self.name
+    `;
+        const result = compile(source);
+        expect(result.code).toContain("class Person");
+    });
+    test("should compile control flow", () => {
+        const source = `
+if x > 5:
+    print("big")
+else:
+    print("small")
+    `;
+        const result = compile(source);
+        expect(result.code).toContain("if");
+        expect(result.code).toContain("else");
+    });
+    test("should compile loops", () => {
+        const source = `
+for i in range(10):
+    print(i)
+    `;
+        const result = compile(source);
+        expect(result.code).toContain("for");
+    });
+    test("should compile while loops", () => {
+        const source = `
+while x < 10:
+    x = x + 1
+    `;
+        const result = compile(source);
+        expect(result.code).toContain("while");
+    });
+    test("should compile try-catch", () => {
+        const source = `
+try:
+    risky_operation()
+except:
+    print("error")
+    `;
+        const result = compile(source);
+        expect(result.code).toContain("try");
+        expect(result.code).toContain("catch");
+    });
+});
+describe("compileToJS() - Simplified API", () => {
+    test("should return only JavaScript code as string", () => {
+        const source = 'print("test")';
+        const result = compileToJS(source);
+        expect(typeof result).toBe("string");
+        expect(result).toContain("print");
+    });
+    test("should accept options", () => {
+        const source = 'print("test")';
+        const result = compileToJS(source, {
+            format: "iife",
+            runtimeMode: "inline"
+        });
+        expect(result).toContain("function");
+        expect(result).toContain("print");
+    });
+});
+describe("getRuntime()", () => {
+    test("should return runtime code as string", () => {
+        const runtime = getRuntime();
+        expect(typeof runtime).toBe("string");
+        expect(runtime).toContain("function print");
+    });
+    test("should include all runtime functions", () => {
+        const runtime = getRuntime();
+        expect(runtime).toContain("function print");
+        expect(runtime).toContain("function range");
+        expect(runtime).toContain("function sum");
+        expect(runtime).toContain("function len");
+        expect(runtime).toContain("function min");
+        expect(runtime).toContain("function max");
+        expect(runtime).toContain("function sorted");
+        expect(runtime).toContain("function str");
+        expect(runtime).toContain("function int");
+        expect(runtime).toContain("function float");
+        expect(runtime).toContain("function map");
+        expect(runtime).toContain("function filter");
+        expect(runtime).toContain("function list");
+    });
+});
+describe("Integration Tests - Runtime Execution", () => {
+    test("should execute compiled code with inline runtime", () => {
+        const source = `
+def add(a, b):
+    return a + b
+
+result = add(2, 3)
+    `;
+        const compiled = compile(source, {
+            format: "iife",
+            runtimeMode: "inline",
+            moduleName: "TestApp"
+        });
+        // This would need actual execution in a real test
+        expect(compiled.code).toContain("function add");
+    });
+    test("should handle runtime functions in compiled code", () => {
+        const source = `
+numbers = range(5)
+total = sum(numbers)
+print(total)
+    `;
+        const compiled = compile(source, {
+            format: "iife",
+            runtimeMode: "inline"
+        });
+        expect(compiled.code).toContain("range");
+        expect(compiled.code).toContain("sum");
+        expect(compiled.code).toContain("print");
+    });
+});
+describe("Edge Cases", () => {
+    test("should handle empty source", () => {
+        const result = compile("");
+        expect(result.code).toBeDefined();
+    });
+    test("should handle source with only comments", () => {
+        const source = "# This is a comment";
+        const result = compile(source);
+        expect(result.code).toBeDefined();
+    });
+    test("should handle source with special characters", () => {
+        const source = 'print("Hello! @#$%^&*()")';
+        const result = compile(source);
+        expect(result.code).toContain("Hello");
+    });
+    test("should handle unicode characters", () => {
+        const source = 'print("こんにちは 世界")';
+        const result = compile(source);
+        expect(result.code).toContain("こんにちは");
+    });
+});
+describe("Format Combinations", () => {
+    const source = 'print("test")';
+    test("ESM + inline runtime", () => {
+        const result = compile(source, {
+            format: "esm",
+            runtimeMode: "inline"
+        });
+        expect(result.code).toContain("function print");
+        expect(result.code).not.toContain("import");
+    });
+    test("CommonJS + inline runtime", () => {
+        const result = compile(source, {
+            format: "cjs",
+            runtimeMode: "inline"
+        });
+        expect(result.code).toContain("function print");
+        expect(result.code).not.toContain("require");
+    });
+    test("IIFE + CDN runtime", () => {
+        const result = compile(source, {
+            format: "iife",
+            runtimeMode: "cdn"
+        });
+        expect(result.code).toContain("function");
+    });
+    test("UMD + external runtime", () => {
+        const result = compile(source, {
+            format: "umd",
+            runtimeMode: "external"
+        });
+        expect(result.code).toContain("define.amd");
+    });
+});

package/dist/api/__tests__/runtime.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runtime.test.d.ts.map

package/dist/api/__tests__/runtime.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.test.d.ts","sourceRoot":"","sources":["../../../src/api/__tests__/runtime.test.ts"],"names":[],"mappings":""}