tjs-lang 0.6.44 → 0.7.3

package/README.md

@@ -2,7 +2,9 @@
 
 # TJS Platform
 
-![tjs-lang logo](/tjs-lang.svg)
+<center>
+    <tosi-lottie style="width: 40vmin; height: 40vmin;" src="./tosi-platform.json"><img alt="tjs-lang logo" style="width: 40vmin; height: 40vmin" src="tjs-lang.svg"></tosi-lottie>
+</center>
 
 [playground](https://tjs-platform.web.app) | [github](https://github.com/tonioloewald/tjs-lang#readme) | [npm](https://www.npmjs.com/package/tjs-lang) | [discord](https://discord.gg/ramJ9rgky5)
 
@@ -16,21 +18,7 @@
 
 **TJS is also a toolchain.** It transpiles itself into JavaScript. It transpiles TypeScript into itself and then into JS. It turns function definitions into runtime contracts, documentation, and simple tests. It uses types both as contracts and examples. It allows inline tests of private module internals that disappear at runtime. It compresses transpilation, linting, testing, and documentation generation into a single fast pass. As for bundling? It allows it but it targets an unbundled web.
 
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                            TJS Platform                                 │
-├─────────────────────┬─────────────────────┬─────────────────────────────┤
-│      Language       │      Runtime        │      Safe Execution         │
-├─────────────────────┼─────────────────────┼─────────────────────────────┤
-│  TypeScript         │  __tjs metadata     │  AJS Agent                  │
-│       ↓             │       ↓             │       ↓                     │
-│  TJS                │  Runtime Validation │  JSON AST                   │
-│       ↓             │       ↓             │       ↓                     │
-│  JavaScript         │  Auto Documentation │  Gas-Limited VM             │
-│                     │                     │       ↓                     │
-│                     │                     │  Injected Capabilities      │
-└─────────────────────┴─────────────────────┴─────────────────────────────┘
-```
+![TJS Platform Overview](docs/diagrams/platform-overview.svg)
 
 ## The Problem
 
@@ -59,16 +47,16 @@ Write typed JavaScript where the type _is_ an example. No split-brain validation
 
 ```typescript
 // TJS: The type is an example AND a test
-function greet(name: 'World') -> 'Hello, World!' {
+function greet(name: 'World'): 'Hello, World!' {
   return `Hello, ${name}!`
 }
 // At transpile time: greet('World') is called and checked against 'Hello, World!'
 
 // Runtime: The type becomes a contract
-console.log(greet.__tjs.params)  // { name: { type: 'string', example: 'World', required: true } }
+console.log(greet.__tjs.params) // { name: { type: 'string', example: 'World', required: true } }
 
 // Safety: Errors are values, not crashes
-const result = greet(123)        // MonadicError: Expected string for 'greet.name', got number
+const result = greet(123) // MonadicError: Expected string for 'greet.name', got number
 ```
 
 **Why it matters:**
@@ -80,24 +68,7 @@ const result = greet(123)        // MonadicError: Expected string for 'greet.nam
 - **Zero build step** — transpiles in the browser, no webpack/Vite/Babel
 - **The compiler _is_ the client** — TJS transpiles itself _and_ TypeScript entirely client-side
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ COMPILE TIME                                                    │
-│                                                                 │
-│   function greet(name: 'World')  ──→  Parse  ──→  Extract type  │
-│                                                   name = string │
-└─────────────────────────────────────────────────────────────────┘
-                              ↓
-┌─────────────────────────────────────────────────────────────────┐
-│ RUNTIME                                                         │
-│                                                                 │
-│   greet.__tjs = { params: { name: { type: 'string' } } }        │
-│                                                                 │
-│   greet(123)  ──→  Type Check  ──┬──→  Pass  ──→  Execute       │
-│                                  └──→  Fail  ──→  MonadicError  │
-│                                                   (no throw)    │
-└─────────────────────────────────────────────────────────────────┘
-```
+![Compile Time and Runtime Flow](docs/diagrams/compile-runtime.svg)
 
 ## AJS — Code That Travels
 
@@ -133,27 +104,7 @@ const result = await vm.run(
 
 ## The Architecture Shift
 
-```
-❌ OLD WAY: Data-to-Code
-┌────────┐    request    ┌────────┐  fetch 100 rows  ┌──────────┐
-│ Client │ ────────────→ │ Server │ ───────────────→ │ Database │
-│        │ ←──────────── │        │ ←─────────────── │          │
-└────────┘   5 rows      └────────┘    100 rows      └──────────┘
-             (after filtering 95 away)
-```
-
-_High latency. High bandwidth. Validate at every layer._
-
-```
-✅ TJS WAY: Code-to-Data
-┌────────┐  send agent   ┌────────┐  run at data    ┌──────────┐
-│ Client │ ────────────→ │  Edge  │ ───────────────→ │ Database │
-│        │ ←──────────── │        │ ←─────────────── │          │
-└────────┘    5 rows     └────────┘     5 rows       └──────────┘
-             (agent filtered at source)
-```
-
-_Low latency. Zero waste. Validate once._
+![Architecture Shift: Data-to-Code vs Code-to-Data](docs/diagrams/architecture-shift.svg)
 
 The agent carries its own validation. The server grants capabilities. Caching happens automatically because the query _is_ the code.
 
@@ -187,26 +138,7 @@ const { result, fuelUsed } = await Eval({
 
 The untrusted code thinks it has `fetch`, but it only has _your_ `fetch`. No CSP violations. No infinite loops. No access to anything you didn't explicitly grant.
 
-```
-                    ┌─────────────────┐
-                    │ Untrusted Code  │
-                    └────────┬────────┘
-                             │
-         ┌───────────┬───────┴───────┬───────────┐
-         ↓           ↓               ↓           ↓
-     fetch()    fs.read()         loop       console
-         │           │               │           │
-         ↓           ↓               ↓           ↓
-    ┌─────────┐ ┌─────────┐    ┌─────────┐ ┌─────────┐
-    │Granted? │ │Granted? │    │Fuel left│ │Granted? │
-    └────┬────┘ └────┬────┘    └────┬────┘ └────┬────┘
-      Y  │  N     N  │          Y   │  N     N  │
-         ↓     ↓     ↓             ↓     ↓      ↓
-    ┌────────┐ ┌───────┐      Continue  Halt  Block
-    │  Your  │ │ Block │          │
-    │safeFetch│ └───────┘          ↓
-    └────────┘
-```
+![Safe Eval: Capability-Based Security](docs/diagrams/safe-eval.svg)
 
 ## Quick Start
 
@@ -236,7 +168,7 @@ console.log(result) // { result: 42 }
 import { tjs } from 'tjs-lang'
 
 const { code, metadata } = tjs`
-  function add(a: 0, b: 0) -> 0 {
+  function add(a: 0, b: 0): 0 {
     return a + b
   }
 `
@@ -281,9 +213,10 @@ The cost of "safe eval"—compare to a 200MB Docker image:
 
 ## Documentation
 
-- **[TJS Language Guide](DOCS-TJS.md)** — Types, syntax, runtime
-- **[AJS Runtime Guide](DOCS-AJS.md)** — VM, atoms, capabilities
-- **[Architecture Deep Dive](CONTEXT.md)** — How it all fits together
+- **[TJS Language Guide](https://github.com/tonioloewald/tjs-lang/blob/main/DOCS-TJS.md)** — Types, syntax, runtime
+- **[AJS Runtime Guide](https://github.com/tonioloewald/tjs-lang/blob/main/DOCS-AJS.md)** — VM, atoms, capabilities
+- **[WASM Quick Start](https://github.com/tonioloewald/tjs-lang/blob/main/docs/WASM-QUICKSTART.md)** — Build WASM-accelerated libraries with zero toolchain setup
+- **[Architecture Deep Dive](https://github.com/tonioloewald/tjs-lang/blob/main/CONTEXT.md)** — How it all fits together
 - **[Playground](https://tjs-platform.web.app)** — Try it now
 
 ## Installation

package/bin/benchmarks.ts

@@ -47,7 +47,7 @@ console.log('Running TJS benchmarks...\n')
 // CLI Cold Start
 console.log('CLI Cold Start:')
 const testFile = '/tmp/bench-test.tjs'
-writeFileSync(testFile, `function add(a: 1, b: 2) -> 0 { return a + b }`)
+writeFileSync(testFile, `function add(a: 1, b: 2) -> 3 { return a + b }`)
 
 function measureCLI(cmd: string): number {
   const times: number[] = []
@@ -197,9 +197,9 @@ results.push({
 console.log('\n3-Function Chain:')
 
 // Create safe chain
-const safeStep1Result = tjs(`function safeStep1(x: 0) -> 0 { return x * 2 }`)
-const safeStep2Result = tjs(`function safeStep2(x: 0) -> 0 { return x + 10 }`)
-const safeStep3Result = tjs(`function safeStep3(x: 0) -> 0 { return x / 2 }`)
+const safeStep1Result = tjs(`function safeStep1(x: 5) -> 10 { return x * 2 }`)
+const safeStep2Result = tjs(`function safeStep2(x: 10) -> 20 { return x + 10 }`)
+const safeStep3Result = tjs(`function safeStep3(x: 20) -> 10 { return x / 2 }`)
 
 const safeStep1 = new Function(`${safeStep1Result.code}; return safeStep1;`)()
 const safeStep2 = new Function(`${safeStep2Result.code}; return safeStep2;`)()
@@ -207,13 +207,13 @@ const safeStep3 = new Function(`${safeStep3Result.code}; return safeStep3;`)()
 
 // Create unsafe chain with (!)
 const unsafeStep1Result = tjs(
-  `function unsafeStep1(! x: 0) -> 0 { return x * 2 }`
+  `function unsafeStep1(! x: 5) -> 10 { return x * 2 }`
 )
 const unsafeStep2Result = tjs(
-  `function unsafeStep2(! x: 0) -> 0 { return x + 10 }`
+  `function unsafeStep2(! x: 10) -> 20 { return x + 10 }`
 )
 const unsafeStep3Result = tjs(
-  `function unsafeStep3(! x: 0) -> 0 { return x / 2 }`
+  `function unsafeStep3(! x: 20) -> 10 { return x / 2 }`
 )
 
 const unsafeStep1 = new Function(

package/bin/dev.ts

@@ -78,8 +78,9 @@ async function buildDemo() {
     })
 
     // Copy static files (including TFS service worker — must not be bundled)
-    await $`cp demo/index.html demo/static/favicon.svg demo/static/photo-*.jpg tjs-lang.svg demo/src/tfs-worker.js .demo/`
+    await $`cp demo/index.html demo/static/favicon.svg demo/static/photo-*.jpg demo/static/tosi-platform.json tjs-lang.svg demo/src/tfs-worker.js .demo/`
     await $`cp -r demo/static/texts .demo/`
+    await $`mkdir -p .demo/docs && cp -r docs/diagrams .demo/docs/ 2>/dev/null || true`
 
     console.log('Build complete!')
   } catch (error) {

package/demo/autocomplete.test.ts

@@ -54,7 +54,7 @@ describe('getCompletions', () => {
 
     it('should suggest types after return arrow', () => {
       const completions = getCompletions({
-        source: 'function foo() -> ',
+        source: 'function foo(): ',
         position: 18,
       })