@ezetgalaxy/titan 26.12.8 → 26.13.0

package/README.md

@@ -223,192 +223,5 @@ Titan compiles your entire app—JS/TS code, Rust code, and server logic—into
 
 ---
 
-# 🧱 Architecture: Multi-Threaded, Strictly Synchronous V8 Runtime
 
-TitanPl is **not** a Node.js framework, TitanPl have Gravity Runtime. It is a **Rust server with embedded V8 engines** that executes JavaScript/TypeScript **synchronously**.
-
-### Key Architectural Principles:
-
-* **No Event Loop in Workers**: Unlike Node.js, Titan workers do **not** run an event loop. Code executes synchronously from request entry to response exit.
-* **Request-Driven Execution**: Each worker processes one request at a time, blocks until completion, then awaits the next request.
-* **Blocking I/O**: All I/O operations (HTTP, DB, file system) block the worker thread. Scaling is achieved by increasing worker threads, not through async I/O.
-* **Deterministic Execution**: All code runs linearly, making debugging predictable and straightforward.
-* **True Isolation**: Each worker owns an independent V8 isolate with zero shared state or cross-worker communication.
-* **No `require` or `import.meta`**: Use ES6 imports only. Dependencies are bundled with esbuild.
-* **No Async/Await**: JavaScript actions cannot use Promises, `async/await`, `setTimeout`, or any other asynchronous primitives.
-
-### Synchronous Execution Model:
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    Incoming HTTP Request                        │
-└─────────────────────┬───────────────────────────────────────────┘
-                      │
-                      ▼
-         ┌────────────────────────┐
-         │   Axum HTTP Server     │
-         │    (Rust, async)       │
-         └────────┬───────────────┘
-                  │
-                  │ Dispatch to Worker
-                  ▼
-    ┌──────────────────────────────────┐
-    │      Worker Thread (Rust)        │
-    │  ┌────────────────────────────┐  │
-    │  │   V8 Isolate               │  │
-    │  │  ┌──────────────────────┐  │  │
-    │  │  │  Execute Action      │  │  │ ◄── Synchronous, blocking execution
-    │  │  │  (JavaScript/TS)     │  │  │
-    │  │  │                      │  │  │
-    │  │  │  t.fetch() ──────────┼──┼──┼──► Blocks until HTTP response
-    │  │  │         │            │  │  │
-    │  │  │         ▼            │  │  │
-    │  │  │  return { ... }      │  │  │
-    │  │  └──────────────────────┘  │  │
-    │  └────────────────────────────┘  │
-    └──────────┬───────────────────────┘
-               │
-               │ Return response
-               ▼
-    ┌─────────────────────────┐
-    │   HTTP Response Sent    │
-    └─────────────────────────┘
-```
-
-### Performance Characteristics:
-
-* **Cold Start**: ~3-5ms (embedded runtime eliminates disk I/O)
-* **Action Execute**: ~100-500µs
-* **Memory/Worker**: ~40-80MB (configurable via V8 flags)
-* **Throughput**: ~10k - 19k req/sec @ 200 concurrent connections
-* **Latency**: ~14-17ms (p50), ~30ms (p97.5)
-
-### When to Use TitanPL:
-
-✅ **Perfect for:**
-* CPU-bound or compute-heavy services
-* Deterministic execution requirements
-* Linear debugging workflows
-* Predictable memory usage per worker
-* Crash isolation (one worker crash doesn't affect others)
-
-❌ **Not ideal for:**
-* I/O-heavy services with high concurrency (use Node.js, Deno, or Bun)
-* Applications requiring `setTimeout`, Promises, or async/await
-* Real-time event-driven architectures
-
-### Migration from Async Patterns:
-
-If you're coming from Node.js, **do not** try to use async patterns:
-
-```javascript
-// ❌ This will NOT work
-export const fetchUser = defineAction(async (req) => {
-  const response = await t.fetch("https://api.example.com/user");
-  return response;
-});
-
-// ✅ Use synchronous blocking calls instead
-export const fetchUser = defineAction((req) => {
-  const response = t.fetch("https://api.example.com/user"); // Blocks until complete
-  return response;
-});
-```
-
----
-
-# 🚀 TitanPL Gravity Multi-Threaded Architecture
-
-### What this means:
-
-* **Each CPU core runs JavaScript independently**
-* **Every request is handled in parallel**
-* **Zero lock contention**
-* **Linear scaling with core count**
-* **Massive throughput increase under real traffic**
-
-No tricks. No fake concurrency.
-Just **native multi-threaded JavaScript execution**, powered by Rust.
-
----
-
-# 🧠 How It Works
-
-TitanPL spins up a **worker pool**, where each worker owns:
-
-* Its own V8 isolate
-* Its own context
-* Its own compiled actions
-* **No event loop** (synchronous execution only)
-
-Workers never share a lock, never block each other, and never wait for global state.
-
-This gives TitanPL a performance profile similar to:
-
-* Deno’s multi-isolate approach
-* Chrome’s process-per-tab architecture
-* High-performance Rust servers like Actix or Hyper
-
-But executed **directly for JavaScript with synchronous semantics**.
-
----
-
-# ⚡ Real Performance Gains
-
-TitanPL demonstrates:
-
-* **10× lower contention** compared with previous versions
-* **2× higher throughput** on multi-core systems
-* **Stable latency at 500–800 concurrent clients**
-* **True hardware utilization**, not single-threaded bottlenecks
-
-Example on an 8-core machine:
-
-```
-Before: 5k–6k req/sec
-Now:   10k–12k+ req/sec
-```
-
----
-
-# 🛠 Why Multi-Threading Matters
-
-Traditional JavaScript runtimes:
-
-* Run user code on **one thread**
-* Rely heavily on **async I/O** to “fake” concurrency
-* Collapse under CPU-heavy workloads
-
-TitanPL eliminates this limitation:
-
-### Every worker can execute CPU-bound JavaScript simultaneously — **zero blocking**.
-
-This is ideal for:
-
-* AI systems
-* Gaming backends
-* Real-time analytics
-* Compute-heavy actions
-* Multi-user concurrency
-
----
-
-# 🌌 TitanPL: The Future of JavaScript Backend Engines
-
-With native Rust + V8 multi-threading, TitanPL becomes:
-
-* Faster than single-threaded Node
-* More scalable under load
-* Safer and more predictable
-* Architecturally modern
-* Ready for enterprise-grade traffic
-
----
-
-
-
-**Titan v26 — Stable**
-* Production-ready Hybrid Runtime
-* Strict TypeScript Support
-* Native Rust Performance
-* Zero-Config Cloud Deployment
+**To know more read docs 💟 **Titan Planet docs:** https://titan-docs-ez.vercel.app/docs**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ezetgalaxy/titan",
-  "version": "26.12.8",
+  "version": "26.13.0",
   "description": "Titan Planet is a JavaScript-first backend framework that embeds JS actions into a Rust + Axum server and ships as a single native binary. Routes are compiled to static metadata; only actions run in the embedded JS runtime. No Node.js. No event loop in production.",
   "license": "ISC",
   "author": "ezetgalaxy",

package/templates/common/Dockerfile

@@ -61,6 +61,6 @@ COPY --from=builder /app/server/actions /app/actions
 # Copy only Titan extensions
 COPY --from=builder /app/.ext ./.ext
 
-EXPOSE 3000
+EXPOSE 5100
 
 CMD ["./titan-server"]

package/templates/common/app/titan.d.ts

@@ -13,23 +13,40 @@ export interface TitanBuilder {
     start(port?: number, msg?: string): Promise<void>;
 }
 
-// The default export from titan.js is the Builder
 declare const builder: TitanBuilder;
 export const Titan: TitanBuilder;
 export default builder;
 
-/**
- * Define a Titan Action with type inference.
- */
 export declare function defineAction<T>(actionFn: (req: TitanRequest) => T): (req: TitanRequest) => T;
 
-
 // -- Global Definitions (Runtime Environment) --
 
+/**
+ * # Drift - Orchestration Engine
+ * 
+ * Revolutionary system for high-performance asynchronous operations using a **Deterministic Replay-based Suspension** model.
+ * 
+ * ## Mechanism
+ * Drift utilizes a suspension model similar to **Algebraic Effects**. When a `drift()` operation is encountered, 
+ * the runtime suspends the isolate, offloads the task to the background Tokio executor, and frees the isolate 
+ * to handle other requests. Upon completion, the code is efficiently **re-played** with the result injected.
+ * 
+ * @param promise - The promise or expression to drift.
+ * @returns The resolved value of the input promise.
+ * 
+ * @example
+ * ```javascript
+ * const resp = drift t.fetch("http://api.titan.com");
+ * ```
+ */
+declare var drift: <T>(promise: Promise<T> | T) => T;
+
 declare global {
     /**
-     * The Titan Request Object passed to actions.
+     * Titan Global Drift
      */
+    var drift: <T>(promise: Promise<T> | T) => T;
+
     interface TitanRequest {
         body: any;
         method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
@@ -46,41 +63,16 @@ declare global {
     }
 
     interface DbConnection {
-        /**
-         * Execute a SQL query.
-         * @param sql The SQL query string.
-         * @param params (Optional) Parameters for the query ($1, $2, etc).
-         */
         query(sql: string, params?: any[]): any[];
     }
 
-    /**
-     * Global defineAction (available without import in runtime)
-     */
     function defineAction<T>(actionFn: (req: TitanRequest) => T): (req: TitanRequest) => T;
 
-    /**
-     * Global Request Object
-     * Available automatically in actions.
-     */
     var req: TitanRequest;
 
-    /**
-     * Titan Runtime Utilities
-     * (Available globally in the runtime, e.g. inside actions)
-     */
     interface TitanRuntimeUtils {
-        /**
-         * Log messages to the server console with Titan formatting.
-         */
         log(...args: any[]): void;
-
-        /**
-         * Read a file contents as string.
-         * @param path Relative path to the file from project root.
-         */
         read(path: string): string;
-
         fetch(url: string, options?: {
             method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
             headers?: Record<string, string>;
@@ -93,11 +85,7 @@ declare global {
         };
 
         jwt: {
-            sign(
-                payload: object,
-                secret: string,
-                options?: { expiresIn?: string | number }
-            ): string;
+            sign(payload: object, secret: string, options?: { expiresIn?: string | number }): string;
             verify(token: string, secret: string): any;
         };
 
@@ -106,27 +94,156 @@ declare global {
             verify(password: string, hash: string): boolean;
         };
 
+        /** ### `db` (Database Connection) */
         db: {
             connect(url: string): DbConnection;
         };
 
-        /**
-         * Titan Validator (Zod-compatible)
-         */
-        valid: any;
+        /** ### `fs` (File System) */
+        fs: TitanCore.FileSystem;
+
+        /** ### `path` (Path Manipulation) */
+        path: TitanCore.Path;
+
+        /** ### `crypto` (Cryptography) */
+        crypto: TitanCore.Crypto;
 
-        // Allow extensions
+        /** ### `buffer` (Buffer Utilities) */
+        buffer: TitanCore.BufferModule;
+
+        /** ### `ls` / `localStorage` (Persistent Storage) */
+        ls: TitanCore.LocalStorage;
+        localStorage: TitanCore.LocalStorage;
+
+        /** ### `session` (Server-side Sessions) */
+        session: TitanCore.Session;
+
+        /** ### `cookies` (HTTP Cookies) */
+        cookies: TitanCore.Cookies;
+
+        /** ### `os` (Operating System) */
+        os: TitanCore.OS;
+
+        /** ### `net` (Network) */
+        net: TitanCore.Net;
+
+        /** ### `proc` (Process) */
+        proc: TitanCore.Process;
+
+        /** ### `time` (Time) */
+        time: TitanCore.Time;
+
+        /** ### `url` (URL) */
+        url: TitanCore.URLModule;
+
+        /** ### `response` (HTTP Response Builder) */
+        response: TitanCore.ResponseModule;
+
+        valid: any;
         [key: string]: any;
     }
 
-    /**
-     * Titan Runtime Utilities
-     * (Available globally in the runtime, e.g. inside actions)
-     */
     const t: TitanRuntimeUtils;
-
-    /**
-     * Titan Runtime Utilities (Alias for t)
-     */
     const Titan: TitanRuntimeUtils;
+
+    namespace TitanCore {
+        interface FileSystem {
+            readFile(path: string): string;
+            writeFile(path: string, content: string): void;
+            readdir(path: string): string[];
+            mkdir(path: string): void;
+            exists(path: string): boolean;
+            stat(path: string): { size: number, isFile: boolean, isDir: boolean, modified: number };
+            remove(path: string): void;
+        }
+
+        interface Path {
+            join(...args: string[]): string;
+            resolve(...args: string[]): string;
+            extname(path: string): string;
+            dirname(path: string): string;
+            basename(path: string): string;
+        }
+
+        interface Crypto {
+            hash(algorithm: 'sha256' | 'sha512' | 'md5', data: string): string;
+            randomBytes(size: number): string;
+            uuid(): string;
+            compare(hash: string, target: string): boolean;
+            encrypt(algorithm: string, key: string, plaintext: string): string;
+            decrypt(algorithm: string, key: string, ciphertext: string): string;
+            hashKeyed(algorithm: 'hmac-sha256' | 'hmac-sha512', key: string, message: string): string;
+        }
+
+        interface BufferModule {
+            fromBase64(str: string): Uint8Array;
+            toBase64(bytes: Uint8Array | string): string;
+            fromHex(str: string): Uint8Array;
+            toHex(bytes: Uint8Array | string): string;
+            fromUtf8(str: string): Uint8Array;
+            toUtf8(bytes: Uint8Array): string;
+        }
+
+        interface LocalStorage {
+            get(key: string): string | null;
+            set(key: string, value: string): void;
+            remove(key: string): void;
+            clear(): void;
+            keys(): string[];
+        }
+
+        interface Session {
+            get(sessionId: string, key: string): string | null;
+            set(sessionId: string, key: string, value: string): void;
+            delete(sessionId: string, key: string): void;
+            clear(sessionId: string): void;
+        }
+
+        interface Cookies {
+            get(req: any, name: string): string | null;
+            set(res: any, name: string, value: string, options?: any): void;
+            delete(res: any, name: string): void;
+        }
+
+        interface OS {
+            platform(): string;
+            cpus(): number;
+            totalMemory(): number;
+            freeMemory(): number;
+            tmpdir(): string;
+        }
+
+        interface Net {
+            resolveDNS(hostname: string): string[];
+            ip(): string;
+            ping(host: string): boolean;
+        }
+
+        interface Process {
+            pid(): number;
+            uptime(): number;
+            memory(): Record<string, any>;
+        }
+
+        interface Time {
+            sleep(ms: number): void;
+            now(): number;
+            timestamp(): string;
+        }
+
+        interface URLModule {
+            parse(url: string): any;
+            format(urlObj: any): string;
+            SearchParams: any;
+        }
+
+        interface ResponseModule {
+            (options: any): any;
+            text(content: string, status?: number): any;
+            html(content: string, status?: number): any;
+            json(content: any, status?: number): any;
+            redirect(url: string, status?: number): any;
+            empty(status?: number): any;
+        }
+    }
 }

package/templates/js/app/app.js

@@ -7,4 +7,4 @@ t.post("/hello").action("hello") // pass a json payload { "name": "titan" }
 
 t.get("/").reply("Ready to land on Titan Planet 🚀");
 
-t.start(3000, "Titan Running!");
+t.start(5100, "Titan Running!");

package/templates/js/server/src/action_management.rs

@@ -8,6 +8,7 @@ use serde_json::Value;
 #[derive(Debug, Deserialize, Clone)]
 pub struct RouteVal {
     pub r#type: String,
+    #[serde(alias = "target")]
     pub value: Value,
 }