jac-coder 0.1.0__py3-none-any.whl

jac_coder/data/examples/core_patterns.md

@@ -0,0 +1,321 @@
+# Core Jac Patterns — Complete Working Examples
+
+## Basic Module with Entry Block
+
+```jac
+"""A simple greeting module."""
+
+def greet(name: str) -> str {
+    return f"Hello, {name}!";
+}
+
+with entry {
+    message = greet("World");
+    print(message);
+}
+```
+
+## Object with Fields and Methods
+
+```jac
+"""Object archetype with has declarations and methods."""
+
+obj Person {
+    has name: str = "",
+        age: int = 0,
+        email: str = "";
+
+    def greet() -> str {
+        return f"Hi, I'm {self.name}, age {self.age}";
+    }
+
+    def is_adult() -> bool {
+        return self.age >= 18;
+    }
+}
+
+with entry {
+    p = Person(name="Alice", age=30, email="alice@example.com");
+    print(p.greet());
+    print(f"Adult: {p.is_adult()}");
+}
+```
+
+## Interface and Implementation Separation
+
+Declaration (`calculator.jac`):
+
+```jac
+obj Calculator {
+    has result: float = 0.0;
+
+    def add(x: float) -> float;
+    def subtract(x: float) -> float;
+    def reset() -> None;
+    def get_result() -> float;
+}
+```
+
+Implementation (`impl/calculator.impl.jac`):
+
+```jac
+impl Calculator.add(x: float) -> float {
+    self.result += x;
+    return self.result;
+}
+
+impl Calculator.subtract(x: float) -> float {
+    self.result -= x;
+    return self.result;
+}
+
+impl Calculator.reset() -> None {
+    self.result = 0.0;
+}
+
+impl Calculator.get_result() -> float {
+    return self.result;
+}
+```
+
+## Walker Traversal
+
+```jac
+"""Walker that traverses a city graph."""
+
+node City {
+    has name: str = "",
+        population: int = 0;
+}
+
+edge Road {
+    has distance: float = 0.0;
+}
+
+walker Explorer {
+    has visited: list[str] = [];
+
+    can visit_city with City entry {
+        self.visited.append(here.name);
+        print(f"Visiting {here.name} (pop: {here.population})");
+        visit [-->];
+    }
+}
+
+with entry {
+    nyc = City(name="New York", population=8_300_000);
+    la = City(name="Los Angeles", population=3_900_000);
+    chi = City(name="Chicago", population=2_700_000);
+
+    root ++> nyc;
+    nyc +>:Road(distance=790.0):+> chi;
+    chi +>:Road(distance=2015.0):+> la;
+
+    explorer = root spawn Explorer();
+}
+```
+
+## Social Network Graph
+
+```jac
+"""Graph-based social network with typed edges."""
+
+node User {
+    has username: str = "",
+        bio: str = "";
+}
+
+edge Follows {
+    has since: str = "";
+}
+
+with entry {
+    alice = User(username="alice", bio="Developer");
+    bob = User(username="bob", bio="Designer");
+    carol = User(username="carol", bio="Manager");
+
+    alice +>:Follows(since="2024-01"):+> bob;
+    alice +>:Follows(since="2024-03"):+> carol;
+    bob +>:Follows(since="2024-02"):+> carol;
+}
+```
+
+## AI-Powered Function (by llm)
+
+```jac
+"""Using by llm() for AI-powered functions."""
+
+import from byllm.lib { Model }
+
+glob model: Model = Model(model_name="openai/gpt-4o-mini");
+
+def summarize(text: str) -> str by model(
+    reason="Summarize the given text in 2-3 sentences"
+);
+
+enum Sentiment { POSITIVE, NEGATIVE, NEUTRAL }
+
+def classify_sentiment(text: str) -> Sentiment by model(
+    reason="Classify the sentiment of the text"
+);
+
+with entry {
+    result = summarize("Long article text here...");
+    print(result);
+}
+```
+
+## Test Blocks
+
+```jac
+"""Tests for the calculator module."""
+
+import from calculator { Calculator }
+
+test "calculator addition" {
+    calc = Calculator();
+    calc.add(5.0);
+    assert calc.get_result() == 5.0;
+    calc.add(3.0);
+    assert calc.get_result() == 8.0;
+}
+
+test "calculator reset" {
+    calc = Calculator();
+    calc.add(10.0);
+    calc.reset();
+    assert calc.get_result() == 0.0;
+}
+```
+
+## Enum and Match/Case
+
+```jac
+"""Enum types and pattern matching."""
+
+enum Color {
+    RED = "red",
+    GREEN = "green",
+    BLUE = "blue"
+}
+
+def describe_value(x: object) -> str {
+    match x {
+        case int():
+            return f"Integer: {x}";
+        case str():
+            return f"String: {x}";
+        case list():
+            return f"List with {len(x)} items";
+        case _:
+            return "Unknown type";
+    }
+}
+
+with entry {
+    print(describe_value(42));
+    print(describe_value("hello"));
+}
+```
+
+## Async/Await
+
+```jac
+"""Async operations in Jac."""
+
+import asyncio;
+
+async def fetch_data(url: str) -> str {
+    await asyncio.sleep(0.1);
+    return f"Data from {url}";
+}
+
+with entry {
+    result = asyncio.run(fetch_data("https://example.com"));
+    print(result);
+}
+```
+
+## CRUD Backend with Graph
+
+```jac
+"""Complete CRUD backend using nodes and def:pub endpoints."""
+
+import from uuid { uuid4 }
+
+node Product {
+    has id: str = "";
+    has name: str = "";
+    has price: float = 0.0;
+    has category: str = "";
+}
+
+def:pub add_product(name: str, price: float, category: str = "") -> dict {
+    product = (root ++> Product(
+        id=str(uuid4()), name=name, price=price, category=category
+    ))[0];
+    return {"id": product.id, "name": product.name, "price": product.price};
+}
+
+def:pub get_products(category: str = "") -> list {
+    all_products = [root-->][?:Product];
+    if category {
+        all_products = [p for p in all_products if p.category == category];
+    }
+    return [{"id": p.id, "name": p.name, "price": p.price}
+            for p in all_products];
+}
+
+def:pub delete_product(product_id: str) -> dict {
+    for p in [root-->][?:Product] {
+        if p.id == product_id {
+            root del--> p;
+            return {"success": True};
+        }
+    }
+    return {"success": False, "error": "Not found"};
+}
+```
+
+## Multi-Node Walker Endpoint
+
+```jac
+"""Walker that traverses Order → OrderItems in one request."""
+
+node Order {
+    has id: str = "";
+    has status: str = "pending";
+    has total: float = 0.0;
+}
+
+node OrderItem {
+    has name: str = "";
+    has qty: int = 0;
+    has price: float = 0.0;
+}
+
+walker :pub get_order_details {
+    has order_id: str = "";
+
+    can find_order with Root entry {
+        for order in [-->][?:Order] {
+            if order.id == self.order_id {
+                visit order;
+                return;
+            }
+        }
+        report {"error": "Order not found"};
+    }
+
+    can collect_items with Order entry {
+        items = [{"name": i.name, "qty": i.qty, "price": i.price}
+                 for i in [-->][?:OrderItem]];
+        report {
+            "order_id": here.id,
+            "status": here.status,
+            "items": items,
+            "total": here.total
+        };
+    }
+}
+```

jac_coder/data/examples/todo_app.md

@@ -0,0 +1,321 @@
+# Example: Fullstack Todo App
+
+Complete fullstack app: backend nodes, def:priv endpoints, hook, components, auth, file-based routing.
+
+## Project Structure
+
+```
+todo-app/
+├── jac.toml
+├── main.jac                      # ALL backend + cl { app() }
+├── components/
+│   ├── Layout.cl.jac             # Root layout
+│   ├── Header.cl.jac             # Nav bar
+│   ├── TodoList.cl.jac           # List + add form (calls hook)
+│   ├── TodoItem.cl.jac           # Single item display
+│   └── AddTodoForm.cl.jac        # Input form
+├── hooks/
+│   └── useTodos.cl.jac           # Data hook (sv import + state)
+├── pages/
+│   ├── layout.jac                # Root layout with nav
+│   ├── (public)/login.jac        # Login page
+│   └── (auth)/
+│       ├── layout.jac            # Auth guard
+│       └── dashboard.jac         # Dashboard
+└── styles/global.css
+```
+
+## main.jac — Backend + Entry
+
+```jac
+import from uuid { uuid4 }
+import from datetime { datetime }
+
+node Todo {
+    has id: str = "";
+    has title: str = "";
+    has completed: bool = False;
+    has created_at: str = "";
+
+    def postinit {
+        if not self.id { self.id = str(uuid4()); }
+        if not self.created_at { self.created_at = datetime.now().isoformat(); }
+    }
+}
+
+def:priv get_todos() -> list {
+    return [{"id": t.id, "title": t.title, "completed": t.completed}
+            for t in [root-->][?:Todo]];
+}
+
+def:priv add_todo(title: str) -> dict {
+    todo = (root ++> Todo(title=title))[0];
+    return {"id": todo.id, "title": todo.title, "completed": False};
+}
+
+def:priv toggle_todo(id: str) -> dict {
+    for todo in [root-->][?:Todo] {
+        if todo.id == id {
+            todo.completed = not todo.completed;
+            return {"id": todo.id, "completed": todo.completed};
+        }
+    }
+    return {"error": "not found"};
+}
+
+def:priv delete_todo(id: str) -> dict {
+    for todo in [root-->][?:Todo] {
+        if todo.id == id {
+            root del--> todo;
+            return {"deleted": id};
+        }
+    }
+    return {"error": "not found"};
+}
+
+cl import from .components.Layout { Layout }
+cl {
+    def:pub app() -> JsxElement { return <Layout />; }
+}
+```
+
+## hooks/useTodos.cl.jac — Data Hook
+
+```jac
+sv import from ..main { get_todos, add_todo, toggle_todo, delete_todo }
+
+def:pub useTodos() -> dict {
+    has todos: list = [];
+    has loading: bool = True;
+    has error: str = "";
+
+    async can with entry {
+        try {
+            result = await get_todos();
+            todos = result or [];
+        } except Exception as e {
+            error = str(e);
+        }
+        loading = False;
+    }
+
+    async def handleAdd(title: str) -> None {
+        if not title { return; }
+        result = await add_todo(title);
+        if result and not result.error {
+            todos = todos + [result];
+        }
+    }
+
+    async def handleToggle(id: str) -> None {
+        result = await toggle_todo(id);
+        if result and not result.error {
+            todos = [
+                ({"id": t["id"], "title": t["title"],
+                  "completed": result["completed"]}
+                 if t["id"] == id else t)
+                for t in todos
+            ];
+        }
+    }
+
+    async def handleDelete(id: str) -> None {
+        result = await delete_todo(id);
+        if result and not result.error {
+            todos = [t for t in todos if t["id"] != id];
+        }
+    }
+
+    return {
+        "todos": todos, "loading": loading, "error": error,
+        "handleAdd": handleAdd, "handleToggle": handleToggle,
+        "handleDelete": handleDelete
+    };
+}
+```
+
+## components/Layout.cl.jac — Root Layout
+
+```jac
+import "..styles.global.css";
+import from ".Header" { Header }
+import from ".TodoList" { TodoList }
+
+def:pub Layout() -> JsxElement {
+    return (
+        <div className="min-h-screen bg-gray-50">
+            <Header title="Todo App" />
+            <main className="max-w-2xl mx-auto px-4 py-8">
+                <TodoList />
+            </main>
+        </div>
+    );
+}
+```
+
+## components/Header.cl.jac
+
+```jac
+def:pub Header(props: dict) -> JsxElement {
+    title = props.title or "";
+    return (
+        <header className="border-b px-6 py-4">
+            <h1 className="text-xl font-bold">{title}</h1>
+        </header>
+    );
+}
+```
+
+## components/TodoItem.cl.jac
+
+```jac
+def:pub TodoItem(props: dict) -> JsxElement {
+    todo = props.todo or {};
+    onToggle = props.onToggle or None;
+    onDelete = props.onDelete or None;
+    todoId = todo["id"] or "";
+    title = todo["title"] or "";
+    completed = todo["completed"] or False;
+
+    def handle_toggle() -> None {
+        if onToggle { onToggle(todoId); }
+    }
+
+    def handle_delete() -> None {
+        if onDelete { onDelete(todoId); }
+    }
+
+    return (
+        <div className="flex items-center gap-3 p-3 border rounded-lg">
+            <button onClick={handle_toggle} className="w-5 h-5 rounded border-2">
+                {completed and "✓"}
+            </button>
+            <span class={completed and "flex-1 line-through text-gray-400" or "flex-1"}>
+                {title}
+            </span>
+            <button onClick={handle_delete} className="text-red-500">×</button>
+        </div>
+    );
+}
+```
+
+## components/AddTodoForm.cl.jac
+
+```jac
+def:pub AddTodoForm(props: dict) -> JsxElement {
+    onAdd = props.onAdd or None;
+    has inputValue: str = "";
+
+    def handleSubmit(e: any) -> None {
+        e.preventDefault();
+        if inputValue and onAdd {
+            onAdd(inputValue);
+            inputValue = "";
+        }
+    }
+
+    def handle_input(e: any) -> None {
+        inputValue = e.target.value;
+    }
+
+    return (
+        <form onSubmit={handleSubmit} className="flex gap-2">
+            <input value={inputValue} onChange={handle_input}
+                placeholder="What needs to be done?"
+                className="flex-1 px-4 py-2 border rounded-lg" />
+            <button type="submit" className="px-4 py-2 bg-blue-500 text-white rounded-lg">+</button>
+        </form>
+    );
+}
+```
+
+## components/TodoList.cl.jac
+
+```jac
+import from ".TodoItem" { TodoItem }
+import from ".AddTodoForm" { AddTodoForm }
+import from "..hooks.useTodos" { useTodos }
+
+def:pub TodoList() -> JsxElement {
+    todoData = useTodos();
+    todos = todoData["todos"] or [];
+
+    if todoData["loading"] {
+        return <p className="text-gray-400 text-center py-8">Loading...</p>;
+    }
+
+    return (
+        <div>
+            {todoData["error"] and (<p className="text-red-500 mb-4">{todoData["error"]}</p>)}
+            <div className="mb-6"><AddTodoForm onAdd={todoData["handleAdd"]} /></div>
+            {len(todos) == 0 and (<p className="text-gray-400 text-center py-8">No todos yet.</p>)}
+            <div className="space-y-2">
+                {[
+                    <TodoItem key={todo["id"]} todo={todo}
+                        onToggle={todoData["handleToggle"]}
+                        onDelete={todoData["handleDelete"]} />
+                    for todo in todos
+                ]}
+            </div>
+        </div>
+    );
+}
+```
+
+## pages/(public)/login.jac — Login Page
+
+```jac
+cl import from "@jac/runtime" { jacLogin, useNavigate }
+
+cl {
+    def:pub page() -> JsxElement {
+        has username: str = "";
+        has password: str = "";
+        has error: str = "";
+        has loading: bool = False;
+        navigate = useNavigate();
+
+        async def handleLogin(e: any) -> None {
+            e.preventDefault();
+            loading = True;
+            error = "";
+            success = await jacLogin(username, password);
+            if success { navigate("/dashboard"); }
+            else { error = "Invalid credentials"; }
+            loading = False;
+        }
+
+        def handle_user(e: any) -> None { username = e.target.value; }
+        def handle_pass(e: any) -> None { password = e.target.value; }
+
+        return (
+            <div className="max-w-sm mx-auto">
+                <h1 className="text-2xl font-bold mb-6">Login</h1>
+                {error and <div className="p-3 mb-4 text-red-500">{error}</div>}
+                <form onSubmit={handleLogin} className="space-y-4">
+                    <input value={username} onChange={handle_user} placeholder="Username"
+                        className="w-full px-4 py-2 border rounded-lg" />
+                    <input type="password" value={password} onChange={handle_pass}
+                        placeholder="Password" className="w-full px-4 py-2 border rounded-lg" />
+                    <button type="submit" disabled={loading}
+                        className="w-full px-4 py-2 bg-blue-500 text-white rounded-lg">
+                        {loading and "Logging in..." or "Login"}
+                    </button>
+                </form>
+            </div>
+        );
+    }
+}
+```
+
+## pages/(auth)/layout.jac — Auth Guard
+
+```jac
+cl import from "@jac/runtime" { AuthGuard, Outlet }
+
+cl {
+    def:pub layout() -> JsxElement {
+        return <AuthGuard redirect="/login"><Outlet /></AuthGuard>;
+    }
+}
+```