jac-coder 0.1.0__py3-none-any.whl

jac_coder/data/reference/osp.md

@@ -0,0 +1,229 @@
+# Object-Spatial Programming — Nodes, Edges, Walkers
+
+## Node Definition
+
+Nodes are data containers that live in the graph. Connected to `root`, they auto-persist (SQLite).
+
+```jac
+node Session {
+    has id: str = "";
+    has chat_history: list[dict] = [];
+
+    def postinit {
+        if not self.id { self.id = str(uuid4()); }
+    }
+}
+
+node City {
+    has name: str;
+    has population: int = 0;
+}
+```
+
+## Edge Definition
+
+Edges define typed relationships between nodes.
+
+```jac
+edge Road {
+    has distance: float = 0.0;
+}
+
+edge Knows {
+    has since: int;
+    has strength: float = 1.0;
+}
+```
+
+## Graph Construction and Connection
+
+```jac
+# Connect with default edge
+a ++> b;
+
+# Connect with typed edge
+alice +>:Knows(since=2020):+> bob;
+
+# Create + connect in one step (returns list — use [0])
+new_node = (here ++> Session(id="abc"))[0];
+
+# Chain connections
+root ++> Router() ++> BuildHandler();
+
+# Connect to root (auto-persists)
+root ++> City(name="NYC", population=8_300_000);
+```
+
+## Graph Querying
+
+```jac
+# Query all connected nodes of a type
+sessions = [-->][?:Session];
+cities = [root-->][?:City];
+
+# Query with filter condition
+active = [-->][?:Session](?status == "active");
+big_cities = [root-->][?:City](?population > 1_000_000);
+
+# Query by edge type
+friends = [->:Knows:->];
+
+# Chained query
+handlers = [root-->][?:Router]-->[?:BuildHandler];
+
+# Delete edge
+a del--> b;
+
+# Delete node
+del node;
+```
+
+## Walker Definition
+
+Walkers traverse the graph and execute abilities on each visited node.
+
+```jac
+walker Explorer {
+    has visited: list[str] = [];
+
+    can visit_city with City entry {
+        self.visited.append(here.name);
+        print(f"Visiting {here.name}");
+        visit [-->];           # continue to connected nodes
+    }
+}
+
+# Spawn walker from root
+result = root spawn Explorer();
+```
+
+## Walker Traversal Commands
+
+```jac
+visit [-->];                       # Visit all outgoing nodes
+visit [-->][?:City];               # Visit only City nodes
+visit [<--];                       # Back-traverse (incoming)
+visit [-->][?:Router] else {       # Fallback if none found
+    router = (here ++> Router())[0];
+    visit router;
+};
+
+report {"data": value};            # Emit data from walker
+disengage;                         # Stop walker entirely
+```
+
+## Context Keywords
+
+| Keyword | Meaning | Used In |
+|---------|---------|---------|
+| `here` | Current node being visited | Walker abilities |
+| `visitor` | The walker visiting this node | Node abilities |
+| `self` | The archetype instance | Any method |
+| `root` | Graph root node | Anywhere |
+
+```jac
+# Walker ability — here is the node, self is the walker
+walker Collector {
+    has items: list = [];
+    can collect with DataNode entry {
+        self.items.append(here.value);
+        visit [-->];
+    }
+}
+
+# Node ability — here is this node, visitor is the walker
+node DataNode {
+    has value: int;
+    can respond with Collector entry {
+        print(f"Walker has {len(visitor.items)} items");
+    }
+}
+```
+
+## disengage vs return
+
+- `return` — exits current ability only. Walker continues to next queued node.
+- `disengage` — stops walker entirely. No more traversal.
+
+```jac
+walker Search {
+    has target: str;
+    can check with Item entry {
+        if here.name == self.target {
+            report here;
+            disengage;    # found it, stop everything
+        }
+        visit [-->];      # keep searching
+    }
+}
+```
+
+## Walker Spawn and Reports
+
+```jac
+# Spawn walker and get result
+result = root spawn GetData();
+data = result.reports[0];          # Access first reported value
+
+# Walker that reports
+walker GetData {
+    can fetch with Root entry {
+        items = [{"id": str(i.id)} for i in [-->][?:Item]];
+        report {"items": items};
+    }
+}
+```
+
+## Lazy Graph Creation Pattern
+
+```jac
+visit [-->][?:Router] else {
+    router = (here ++> Router())[0];
+    visit router;
+};
+```
+
+## Walker as REST Endpoint
+
+```jac
+walker :pub search_items {
+    has query: str;
+        static has as_query: list = ["query"];  # for GET params
+    can find with Root entry {
+        matches = [i for i in [-->][?:Item] if self.query in i.name];
+        report {"results": matches};
+    }
+}
+```
+
+## Parent-Child Graph Patterns
+
+```jac
+node Category { has name: str; }
+node Item { has title: str; }
+
+# Hierarchy: root → Category → Item
+def:pub add_category(name: str) -> dict {
+    cat = (root ++> Category(name=name))[0];
+    return {"name": cat.name};
+}
+
+def:pub add_item(category_name: str, title: str) -> dict {
+    for cat in [root-->][?:Category] {
+        if cat.name == category_name {
+            item = (cat ++> Item(title=title))[0];
+            return {"title": item.title};
+        }
+    }
+    return {"error": "Category not found"};
+}
+
+def:pub get_items_by_category(category_name: str) -> list {
+    for cat in [root-->][?:Category] {
+        if cat.name == category_name {
+            return [{"title": i.title} for i in [cat-->][?:Item]];
+        }
+    }
+    return [];
+}
+```

jac_coder/data/reference/pitfalls.md

@@ -0,0 +1,141 @@
+# Runtime Gotchas — Passes Compilation, Crashes at Runtime
+
+## JS Constructors Need Reflect.construct
+
+In .cl.jac, `ClassName()` without `new` returns wrong type or throws. Jac has no `new` keyword.
+
+```jac
+# WRONG — Date() returns string, not Date object
+year = Date().getFullYear();          # CRASH
+
+# RIGHT
+year = Reflect.construct(Date, []).getFullYear();
+ws = Reflect.construct(WebSocket, ["ws://localhost"]);
+```
+
+**Safe statics (no Reflect needed):** `Date.now()`, `JSON.parse()`, `JSON.stringify()`, `Math.random()`, `Math.floor()`
+
+**Always need Reflect.construct:** Date, WebSocket, TextDecoder, TextEncoder, URL, URLSearchParams, FormData, AbortController, RegExp, Error, Worker, Headers, Request, Response, Uint8Array, ArrayBuffer, Blob, File, FileReader, MutationObserver, ResizeObserver, IntersectionObserver
+
+## Browser Global Name Conflicts
+
+Do NOT define functions with names that shadow browser globals:
+
+```jac
+# WRONG — shadows window.open
+def open(url: str) -> None { ... }
+
+# RIGHT
+def handleOpen(url: str) -> None { ... }
+```
+
+**Avoid as function names:** open, close, print, focus, blur, scroll, fetch, stop, find, alert, confirm, prompt
+
+## Callback-in-Lambda Bug
+
+Jac compiles `callback(arg)` inside a lambda as `new callback(arg)`. Crashes silently.
+
+```jac
+# WRONG — lambda compiles to new onMessage(msg), crashes
+ws.onmessage = lambda(e: any) -> None { onMessage(e.data); };
+
+# RIGHT — named handler with .call()
+msgHandler = onMessage;
+def handle_ws_message(e: any) -> None {
+    msgHandler.call(None, e.data);
+}
+ws.onmessage = handle_ws_message;
+```
+
+## Undefined Property Access Crashes
+
+The #1 runtime crash in .cl.jac. Happens when accessing property on `undefined`.
+
+```jac
+# WRONG — crashes if parent doesn't pass "items" prop
+items = props.items;              # undefined!
+return <div>{[... for item in items]}</div>;  # CRASH
+
+# RIGHT — always default props
+items = props.items or [];
+title = props.title or "";
+
+# WRONG — chaining on undefined
+data = result.reports[0].items;   # CRASH if reports empty
+
+# RIGHT — guard each level
+if result and result.reports and len(result.reports) > 0 {
+    data = result.reports[0].items or [];
+}
+```
+
+## Number and Boolean Display in JSX
+
+Jac doesn't auto-convert to strings in JSX.
+
+```jac
+# WRONG — may render nothing
+<span>{count}</span>
+
+# RIGHT
+<span>{str(count)}</span>
+<p>{str(item["price"])}</p>
+```
+
+## sv import kwargs Are Broken
+
+In .cl.jac, kwargs compile to a single dict argument. Server gets wrong data.
+
+```jac
+# WRONG — server receives {"a": {"a":2, "b":4, "op":"add"}}
+resp = await calc(a=2, b=4, op="add");
+
+# RIGHT — positional, order matches def:pub signature
+resp = await calc(2, 4, "add");
+```
+
+## State List Mutation Doesn't Re-render
+
+`.append()` mutates in place — React won't detect the change.
+
+```jac
+# WRONG — no re-render
+items.append(newItem);
+
+# RIGHT — new reference triggers re-render
+items = items + [newItem];
+```
+
+## Comments Inside JSX Break Rendering
+
+```jac
+# WRONG — all of these crash
+return <div>
+    {# comment}
+    <!-- comment -->
+    {/* comment */}
+</div>;
+
+# RIGHT — comments above JSX only
+# Render the list
+return <div>...</div>;
+```
+
+## .impl.jac Parse Error Breaks Entire File
+
+A single syntax error in an `.impl.jac` file causes ALL implementations in that file to have 0 body items. The compiler won't report which implementation failed — they all silently become empty. Always double-check syntax in impl files.
+
+## Missing :pub on Exports
+
+- Components in `.cl.jac` need `def:pub` to be importable
+- Walkers need `walker :pub` for REST API
+- `app()` in main.jac MUST be `def:pub`
+- Hooks need `def:pub` to be importable
+
+```jac
+# WRONG — not importable
+def Header() -> JsxElement { ... }
+
+# RIGHT
+def:pub Header() -> JsxElement { ... }
+```

jac_coder/data/reference/syntax.md

@@ -0,0 +1,159 @@
+# Jac Language Syntax Reference
+
+## Variables and Types
+
+**Builtin types:** int, float, str, bool, bytes, list, tuple, set, dict, any, type, None
+
+**Generic types:** `list[str]`, `dict[str, int]`, `set[int]`, `tuple[str, int]`, `Type | None`
+
+```jac
+# Field declarations in archetypes
+obj Example {
+    has name: str;                    # Required field
+    has count: int = 0;              # With default
+    has items: list[str] = [];       # Generic type
+    has data: dict | None = None;    # Optional
+}
+
+# Module-level global
+glob config: dict = {};
+
+# Local variables
+x: int = 42;      # Annotated
+name = "hello";    # Type inferred
+```
+
+Type annotations are **required** on `has` fields and function signatures.
+
+## Functions and Methods
+
+```jac
+# Standalone function
+def greet(name: str, greeting: str = "Hello") -> str {
+    return f"{greeting}, {name}!";
+}
+
+# Object with methods
+obj Person {
+    has name: str;
+    has age: int = 0;
+
+    def postinit { print(f"Created {self.name}"); }
+    def greet() -> str { return f"Hi, I'm {self.name}"; }
+    def is_adult() -> bool { return self.age >= 18; }
+}
+
+# Inheritance
+obj Student(Person) { has grade: str = "A"; }
+
+# Static method
+obj Utils {
+    static def helper() -> int { return 42; }
+}
+```
+
+## Enums
+
+```jac
+enum Color { RED = "red", GREEN = "green", BLUE = "blue" }
+enum Direction { NORTH, SOUTH, EAST, WEST }
+
+# Usage
+c = Color.RED;
+print(c.value);  # "red"
+```
+
+## Control Flow
+
+```jac
+# if/elif/else
+if x > 0 { print("positive"); }
+elif x == 0 { print("zero"); }
+else { print("negative"); }
+
+# Inline conditional
+result = "yes" if condition else "no";
+
+# Loops
+for item in items { print(item); }
+for (i, x) in enumerate(items) { print(i, x); }
+for (k, v) in my_dict.items() { print(k, v); }
+while count < 10 { count += 1; }
+
+# Match/case (uses colons, not braces)
+match value {
+    case "add":
+        result = a + b;
+    case "sub":
+        result = a - b;
+    case _:
+        result = 0;
+}
+
+# Exception handling
+try { result = risky(); }
+except ValueError as e { print(f"Error: {e}"); }
+finally { cleanup(); }
+```
+
+## Comprehensions
+
+```jac
+squares = [x ** 2 for x in range(10)];
+filtered = [x for x in items if x > 0];
+mapping = {k: v for (k, v) in items.items() if v > 0};
+```
+
+## String Methods
+
+All Python string methods work in Jac:
+
+```jac
+name.lower();  name.upper();  name.strip();
+name.split(",");  name.replace("old", "new");
+name.startswith("prefix");  name.endswith("suffix");
+",".join(items);  name.find("sub");
+f"Hello, {name}!";  # f-strings supported
+```
+
+## Access Modifiers
+
+| Modifier | Meaning | Use Case |
+|----------|---------|----------|
+| `:pub` | Public | REST endpoint, importable component/hook |
+| `:priv` | Private (auth) | Per-user endpoint, requires login |
+| `:protect` | Protected | Module-internal helper |
+| *(none)* | Default | Module-scoped, not exposed |
+
+```jac
+walker :pub get_tasks { ... }        # Public API
+walker :priv add_task { ... }        # Authenticated
+def :protect validate(x: str) -> bool { ... }
+def:pub get_items() -> list { ... }  # Public function endpoint
+```
+
+## Module Entry Point
+
+```jac
+with entry {
+    print("Module loaded");
+    root spawn MyWalker();
+}
+```
+
+## Imports
+
+```jac
+# Python standard library
+import from os { path }
+import from datetime { datetime }
+import from pathlib { Path }
+import os;
+import json;
+
+# Jac modules (relative)
+import from .submodule { Helper }
+import from jac_coder.nodes { Session }
+
+# NEVER use import:py — it's deprecated
+```