titanpl 6.0.0 → 7.0.0

package/packages/native/t.native.d.ts

@@ -233,6 +233,34 @@ export const password: typeof t.password;
  */
 export const db: typeof t.db;
 
+/**
+ * WebSocket communication utilities.
+ *
+ * Re-exported from the `t` global for module-style imports.
+ * @see {@link TitanRuntimeUtils.ws} for full documentation.
+ */
+export const ws: typeof t.ws;
+
+/**
+ * Binary serialization using V8's fast format.
+ *
+ * Re-exported from the `t` global for module-style imports.
+ * @see {@link TitanRuntimeUtils.serialize}
+ */
+export const serialize: typeof t.serialize;
+/** Alias for serialize. @see {@link TitanRuntimeUtils.serialise} */
+export const serialise: typeof t.serialise;
+
+/**
+ * Binary deserialization for V8 buffers.
+ *
+ * Re-exported from the `t` global for module-style imports.
+ * @see {@link TitanRuntimeUtils.deserialize}
+ */
+export const deserialize: typeof t.deserialize;
+/** Alias for deserialize. @see {@link TitanRuntimeUtils.deserialise} */
+export const deserialise: typeof t.deserialise;
+
 /**
  * Async file system operations (read, write, mkdir, stat, etc.).
  *
@@ -297,6 +325,14 @@ export const session: typeof t.session;
  */
 export const cookies: typeof t.cookies;
 
+/**
+ * Titan Shared Context (Shared In-Memory State) shorthand.
+ *
+ * Re-exported from the `t` global for module-style imports.
+ * @see {@link TitanCore.ShareContext} for full documentation.
+ */
+export const shareContext: typeof t.shareContext;
+
 /**
  * Operating system information (platform, CPU count, memory).
  *
@@ -639,6 +675,55 @@ declare global {
             body?: string;
             error?: string;
         }>;
+        
+        /**
+         * Fast binary serialization using V8's internal value format.
+         *
+         * Highly efficient for complex JavaScript objects including `Date`, `Map`, 
+         * `Set`, and `TypedArrays`. The resulting `Uint8Array` is stable and
+         * can be safely stored in databases (e.g. `t.ls`) or transmitted.
+         *
+         * @param value - The JavaScript value/object to serialize.
+         * @returns A `Uint8Array` containing the binary-serialized representation.
+         *
+         * @example
+         * ```js
+         * const complex = { date: new Date(), map: new Map([["a", 1]]) };
+         * const bytes = t.serialize(complex);
+         * // Store bytes in database or pass to another action
+         * ```
+         */
+        serialize(value: any): Uint8Array;
+
+        /** 
+         * Binary serialization. Alias for `t.serialize`. 
+         * @see {@link TitanRuntimeUtils.serialize}
+         */
+        serialise(value: any): Uint8Array;
+
+        /**
+         * Deserializes a binary buffer back into its original JavaScript value.
+         *
+         * Restores full object fidelity including native types like `Date` and `Buffer`.
+         * Performance is significantly faster than `JSON.parse` for large objects.
+         *
+         * @param buffer - A `Uint8Array` created by `t.serialize()`.
+         * @returns The restored JavaScript value or object.
+         * @throws If the buffer is invalid or contains corrupted V8 header data.
+         *
+         * @example
+         * ```js
+         * const restored = t.deserialize(bytes);
+         * console.log(restored.date instanceof Date); // true
+         * ```
+         */
+        deserialize(buffer: Uint8Array): any;
+
+        /** 
+         * Binary deserialization. Alias for `t.deserialize`. 
+         * @see {@link TitanRuntimeUtils.deserialize}
+         */
+        deserialise(buffer: Uint8Array): any;
 
         /**
          * WebSocket communication utilities.
@@ -647,12 +732,12 @@ declare global {
          *
          * @example
          * ```js
-         * export default defineAction((req) => {
+         * export default function chat(req) {
          *   if (req.event === "open") {
          *     t.ws.send(req.socketId, "Welcome!");
          *     t.ws.broadcast("Someone joined.");
          *   }
-         * });
+         * }
          * ```
          */
         ws: {
@@ -1012,6 +1097,19 @@ declare global {
          */
         session: TitanCore.Session;
 
+        /**
+         * Titan Shared Context — Cross-isolate Shared In-Memory State.
+         *
+         * Provides a mechanism for sharing data across different isolates (requests)
+         * and broadcasting events within the same server process.
+         * 
+         * Data in `shareContext` is volatile and lost when the server exits.
+         * 
+         * @see {@link TitanCore.ShareContext} for method signatures.
+         * @see https://titanpl.vercel.app/docs/knowledge/05-titan-core — TitanCore Runtime APIs (t.shareContext)
+         */
+        shareContext: TitanCore.ShareContext;
+
         /**
          * HTTP cookie utilities for reading, setting, and deleting cookies.
          *
@@ -1731,6 +1829,73 @@ declare global {
             clear(sessionId: string): void;
         }
 
+        /**
+         * Titan Shared Context — Cross-isolate Shared In-Memory State.
+         *
+         * Provides a mechanism for sharing data across different isolates (requests)
+         * and broadcasting events within the same server process.
+         * 
+         * Data in `shareContext` is in-memory only and is lost when the server process exits.
+         * 
+         * @example
+         * ```js
+         * export function getStats(req) {
+         *   // Store a value common to all requests
+         *   t.shareContext.set("last_login", t.time.now());
+         *   
+         *   // Retrieve a value
+         *   const users = t.shareContext.get("active_users");
+         *   
+         *   // Broadcast a message to other workers
+         *   t.shareContext.broadcast("user_login", { user: "Titan" });
+         * }
+         * ```
+         * 
+         * @see https://titanpl.vercel.app/docs/knowledge/05-titan-core — TitanCore Runtime APIs (t.shareContext)
+         */
+        interface ShareContext {
+            /**
+             * Retrieve a value from the shared context.
+             * 
+             * @param key - The key of the value to retrieve.
+             * @returns The parsed value, or `null` if the key does not exist.
+             */
+            get(key: string): any;
+
+            /**
+             * Store a value in the shared context.
+             * 
+             * Values are serialized as JSON and must be serializable.
+             * 
+             * @param key - The key to store under.
+             * @param value - The JSON-serializable value to store.
+             */
+            set(key: string, value: any): void;
+
+            /**
+             * Remove a key and its value from the shared context.
+             * 
+             * @param key - The key to remove.
+             */
+            delete(key: string): void;
+
+            /**
+             * Get a list of all keys currently in the shared context.
+             * 
+             * @returns An array of string keys.
+             */
+            keys(): string[];
+
+            /**
+             * Broadcast an event and payload to other active isolates (requests) 
+             * and workers in this server process.
+             * 
+             * @param event - The name of the event to broadcast.
+             * @param payload - The payload of the event.
+             */
+            broadcast(event: string, payload: any): void;
+        }
+
         /**
          * HTTP cookie management utilities.
          *

package/packages/packet/index.js

@@ -67,6 +67,15 @@ export async function build(root = process.cwd()) {
     outDir: dist,
   });
 
+  const tanfigPath = path.join(root, "tanfig.json");
+  if (fs.existsSync(tanfigPath)) {
+    fs.copyFileSync(tanfigPath, path.join(dist, "tanfig.json"));
+  }
+  const titanExtPath = path.join(root, "titan.json");
+  if (fs.existsSync(titanExtPath)) {
+    fs.copyFileSync(titanExtPath, path.join(dist, "titan.json"));
+  }
+
   return dist;
 }
 
@@ -74,10 +83,19 @@ export async function build(root = process.cwd()) {
  * Release build (Production ready folder)
  */
 export async function release(root = process.cwd()) {
-  const dist = await build(root);
   const buildDir = path.join(root, "build");
 
-  // Read config
+  // Step 1: Pre-build (Production mode)
+  // Run production build to generate 'dist' folder
+  const dist = await build(root);
+
+  // Step 2: Clear or ensure build dir
+  if (fs.existsSync(buildDir)) {
+    fs.rmSync(buildDir, { recursive: true, force: true });
+  }
+  fs.mkdirSync(buildDir, { recursive: true });
+
+  // Step 3: Read config and files list
   let config = {};
   const configPath = fs.existsSync(path.join(root, "tanfig.json"))
     ? path.join(root, "tanfig.json")
@@ -91,41 +109,63 @@ export async function release(root = process.cwd()) {
     } catch (e) { }
   }
 
-  const filesToCopy = config.build && config.build.files ? config.build.files : ["public", "static", "db", "config"];
-
-  // Clear or ensure build dir
-  if (fs.existsSync(buildDir)) {
-    fs.rmSync(buildDir, { recursive: true, force: true });
-  }
-  fs.mkdirSync(buildDir, { recursive: true });
-
-  // 1. Copy dist
-  copyDir(dist, path.join(buildDir, "dist"));
+  // Default files to copy from root
+  const defaultFiles = ["public", "static", "db", "config", "views", "auth"];
+  const userFiles = config.build && Array.isArray(config.build.files) ? config.build.files : [];
+  const filesToCopy = Array.from(new Set([...defaultFiles, ...userFiles]));
 
-  // 2. Extra files/folders from root based on config
+  // Step 4: Copy Files & Folders from root and app folders to build
   for (const item of filesToCopy) {
+    // Check root first, then app/ folder
     const src = path.join(root, item);
+    const appSrc = path.join(root, "app", item);
+    const dest = path.join(buildDir, item);
+
     if (fs.existsSync(src)) {
-      const dest = path.join(buildDir, item);
       copyDir(src, dest);
+    } else if (fs.existsSync(appSrc)) {
+      const appDest = path.join(buildDir, "app", item);
+      copyDir(appSrc, appDest);
     }
   }
 
-  // 3. Copy package.json
-  const pkgPath = path.join(root, "package.json");
-  if (fs.existsSync(pkgPath)) {
-    fs.copyFileSync(pkgPath, path.join(buildDir, "package.json"));
+  // Step 5: Copy generated 'dist' (static routes/actions metadata)
+  copyDir(dist, path.join(buildDir, "dist"));
+
+  // Step 6: Copy essential config files (mandatory for runtime)
+  const essentials = ["package.json", "tanfig.json", "titan.json"];
+  for (const f of essentials) {
+    const src = path.join(root, f);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(buildDir, f));
+    }
   }
 
-  // 4. Create .env
+  // Step 7: Create .env for production
   fs.writeFileSync(path.join(buildDir, ".env"), "TITAN_DEV=0\n");
 
-  // 5. Extract extensions
+  // Step 8: Extract Extensions
   const extDir = path.join(buildDir, ".ext");
   fs.mkdirSync(extDir, { recursive: true });
 
   const nodeModules = path.join(root, "node_modules");
   if (fs.existsSync(nodeModules)) {
+    const localPkgs = path.resolve(root, "../../packages"); 
+    if (fs.existsSync(localPkgs)) {
+       const pkgs = fs.readdirSync(localPkgs);
+       for (const pkg of pkgs) {
+           const pkgPath = path.join(localPkgs, pkg);
+           const titanJsonPath = path.join(pkgPath, "titan.json");
+           if (fs.existsSync(titanJsonPath)) {
+               try {
+                   const config = JSON.parse(fs.readFileSync(titanJsonPath, "utf8"));
+                   const extName = config.name;
+                   const dest = path.join(extDir, extName.includes("/") ? extName : extName);
+                   copyDir(pkgPath, dest);
+               } catch(e) {}
+           }
+       }
+    }
     const findExtensions = (dir, depth = 0) => {
       if (depth > 2) return;
       if (!fs.existsSync(dir)) return;
@@ -147,6 +187,8 @@ export async function release(root = process.cwd()) {
               }
 
               const destPath = path.join(extDir, targetPkgName);
+              if (fs.existsSync(destPath)) continue; // Don't overwrite monorepo packages
+              
               fs.mkdirSync(path.dirname(destPath), { recursive: true });
 
               copyDir(fullPath, destPath, (src) => {
@@ -161,98 +203,65 @@ export async function release(root = process.cwd()) {
       }
     };
     findExtensions(nodeModules);
-  }
 
-  // 6. Copy Engine binaries
-  if (fs.existsSync(path.join(nodeModules, "@titanpl"))) {
-    const scopeDir = path.join(nodeModules, "@titanpl");
-    const folders = fs.readdirSync(scopeDir);
-    for (const folder of folders) {
-      if (folder.startsWith("engine-")) {
-        const engineDest = path.join(extDir, "@titanpl", folder);
-        copyDir(path.join(scopeDir, folder), engineDest);
-      }
-    }
-  }
-
-  // 7. Create node_modules junction to .ext for engine resolution
-  // If env is 'deploy' or 'production', we might want to skip this for a cleaner build
-  const buildEnv = config.build && (config.build.env || config.build.purpose) ? (config.build.env || config.build.purpose) : "test";
-
-  if (buildEnv !== "deploy" && buildEnv !== "production") {
-    const nmSymlink = path.join(buildDir, "node_modules");
-    if (!fs.existsSync(nmSymlink)) {
-      try {
-        // Junctions don't require admin on Windows
-        fs.symlinkSync(".ext", nmSymlink, "junction");
-      } catch (e) {
-        try {
-          fs.symlinkSync(".ext", nmSymlink, "dir");
-        } catch (e2) {
-          // Fallback or ignore if symlink creation is totally restricted
+    // Also copy engine binaries if they exist in node_modules
+    if (fs.existsSync(path.join(nodeModules, "@titanpl"))) {
+      const scopeDir = path.join(nodeModules, "@titanpl");
+      const folders = fs.readdirSync(scopeDir);
+      for (const folder of folders) {
+        if (folder.startsWith("engine-") || folder.startsWith("runtime-")) {
+          const engineDest = path.join(extDir, "@titanpl", folder);
+          copyDir(path.join(scopeDir, folder), engineDest);
         }
       }
     }
   }
 
-  // 8. Create 'titan' executable link in the build root for easy starting
+  // Step 9: Copy/Extract titan-server binary to build root
   const binName = process.platform === "win32" ? "titan-server.exe" : "titan-server";
   let engineBin = null;
 
-  // Strategy A: Search in the .ext we just populated
-  const findInExt = (dir) => {
-    if (!fs.existsSync(dir)) return null;
-    const entries = fs.readdirSync(dir);
-    for (const entry of entries) {
-      const full = path.join(dir, entry);
-      if (fs.statSync(full).isDirectory()) {
-        // Check both pkgRoot/bin/titan-server and pkgRoot/titan-server (some layouts differ)
-        const p1 = path.join(full, "bin", binName);
-        if (fs.existsSync(p1)) return p1;
-        const p2 = path.join(full, binName);
-        if (fs.existsSync(p2)) return p2;
-
-        const found = findInExt(full);
-        if (found) return found;
-      }
-    }
-    return null;
+  // Search in .ext
+  const searchBin = (dir) => {
+     if (!fs.existsSync(dir)) return null;
+     const entries = fs.readdirSync(dir);
+     for (const e of entries) {
+         const full = path.join(dir, e);
+         if (fs.statSync(full).isDirectory()) {
+             const p1 = path.join(full, "bin", binName);
+             if (fs.existsSync(p1)) return p1;
+             const p2 = path.join(full, binName);
+             if (fs.existsSync(p2)) return p2;
+             const found = searchBin(full);
+             if (found) return found;
+         }
+     }
+     return null;
   };
+  engineBin = searchBin(extDir);
 
-  engineBin = findInExt(extDir);
-
-  // Strategy B: Monorepo fallback (if building inside the titanpl repo)
+  // Fallback to monorepo binary (if building in repo)
   if (!engineBin) {
-    let current = root;
-    for (let i = 0; i < 5; i++) {
-      const potential = path.join(current, "engine", "target", "release", binName);
-      if (fs.existsSync(potential)) {
-        engineBin = potential;
-        break;
-      }
-      const parent = path.dirname(current);
-      if (parent === current) break;
-      current = parent;
+    let curr = root;
+    for(let i=0; i<3; i++) {
+        const potential = path.join(curr, "engine", "target", "release", binName);
+        if (fs.existsSync(potential)) {
+            engineBin = potential;
+            break;
+        }
+        curr = path.dirname(curr);
     }
   }
 
   if (engineBin) {
-    const linkName = binName; // Keep the original name 'titan-server'
-    const linkPath = path.join(buildDir, linkName);
-
-    if (!fs.existsSync(linkPath)) {
-      try {
-        // Always copy the binary to the root for maximum portability in the 'build' folder
-        fs.copyFileSync(engineBin, linkPath);
-        if (process.platform !== "win32") {
-          fs.chmodSync(linkPath, 0o755);
-        }
-      } catch (e) {
-        console.error(`[Titan] Failed to create titan binary: ${e.message}`);
-      }
-    }
+    const destBin = path.join(buildDir, binName);
+    fs.copyFileSync(engineBin, destBin);
+    if (process.platform !== "win32") fs.chmodSync(destBin, 0o755);
   }
 
+  // Step 10: In production builds, we DON'T use symlinks for node_modules.
+  // Instead, the engine knows to look in .ext.
+
   return buildDir;
 }
 

package/packages/packet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@titanpl/packet",
-  "version": "6.0.0",
+  "version": "7.0.0",
   "description": "The bundler for TitanPl servers.",
   "keywords": [
     "bundler",

package/packages/route/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@titanpl/route",
-  "version": "6.0.0",
+  "version": "7.0.0",
   "description": "Titan routing DSL",
   "type": "module",
   "main": "index.js",

package/packages/sdk/index.js

@@ -0,0 +1,2 @@
+// Titan SDK - Entry point
+export * from './test/index.js';

package/packages/sdk/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@titanpl/sdk",
+  "version": "7.0.0",
+  "description": "The official SDK for Titan Planet extensions and testing.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./test": "./test/index.js"
+  },
+  "keywords": [
+    "titanpl",
+    "titan",
+    "sdk"
+  ],
+  "author": "ezetgalaxy",
+  "license": "ISC"
+}

package/packages/sdk/test/index.js

@@ -0,0 +1,120 @@
+import fs from 'fs';
+import path from 'path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'url';
+
+/**
+ * Creates a lightweight production-grade test environment for Titan extensions.
+ * Provides isolation via node:vm and a full t-object emulation.
+ */
+export async function createTestEnv(options) {
+    const { extPath, allowWasm = false, allowNative = false } = options;
+    const absolutePath = path.resolve(extPath);
+    const titanJsonPath = path.join(absolutePath, 'titan.json');
+
+    if (!fs.existsSync(titanJsonPath)) {
+        throw new Error(`[@titanpl/sdk/test] titan.json not found at ${absolutePath}`);
+    }
+
+    const titanJson = JSON.parse(fs.readFileSync(titanJsonPath, 'utf8'));
+    
+    // Create the global 't' mock
+    const tMock = {
+        _logs: [],
+        _calls: [],
+        log: (name, ...args) => {
+            const entry = `[${name}] ${args.join(' ')}`;
+            tMock._logs.push(entry);
+            console.log('\x1b[36m%s\x1b[0m', entry);
+        },
+        __native: {
+            call: async (ext, fn, args) => {
+                if (!allowNative) throw new Error(`[@titanpl/sdk/test] Native call blocked (allowNative: false)`);
+                tMock._calls.push({ type: 'native', ext, fn, args });
+                return `[MOCK_NATIVE_RESULT]`;
+            }
+        }
+    };
+
+    // Create a VM context
+    const context = {
+        t: tMock,
+        global: {},
+        globalThis: {},
+        console: console,
+        setTimeout,
+        clearTimeout,
+        process: { env: { ...process.env } }
+    };
+    context.global = context;
+    context.globalThis = context;
+
+    vm.createContext(context);
+
+    // Load extension entry
+    const entryPath = path.join(absolutePath, titanJson.entry);
+    const code = fs.readFileSync(entryPath, 'utf8');
+
+    // Resolve relative imports within the extension
+    // Simple loader: replace relative imports with absolute ones or mock them
+    // For a real production-ready test env, we'd use a custom loader or compile with ESBuild.
+    // For now, we'll use a functional script wrapper.
+    
+    const script = new vm.Script(`
+        (async () => {
+            ${code.replace(/import\s+{([^}]+)}\s+from\s+'\.\/utils\/registerExtension\.js'/g, 'const {$1} = t._registerHelper;')}
+        })()
+    `);
+
+    // Add registration helper to 't'
+    tMock._registerHelper = {
+        registerExtension: (name, module) => {
+            tMock[name] = module;
+            console.log(`[@titanpl/sdk/test] Registered extension: ${name}`);
+        }
+    };
+
+    try {
+        await script.runInContext(context);
+    } catch (err) {
+        console.error(`[@titanpl/sdk/test] Runtime error in extension '${titanJson.name}':`, err);
+        throw err;
+    }
+
+    return {
+        /**
+         * Call an extension method
+         */
+        call: async (path, args = []) => {
+            const [extName, methodName] = path.split('.');
+            if (!tMock[extName]) throw new Error(`Extension '${extName}' not registered`);
+            if (!tMock[extName][methodName]) throw new Error(`Method '${methodName}' not found on extension '${extName}'`);
+            
+            return await tMock[extName][methodName](...args);
+        },
+
+        /**
+         * Assert a method result
+         */
+        assert: async (path, args, expected) => {
+            const result = await tMock.call(path, args);
+            if (JSON.stringify(result) !== JSON.stringify(expected)) {
+                throw new Error(`Assertion Failed for ${path}\nExpected: ${JSON.stringify(expected)}\nActual: ${JSON.stringify(result)}`);
+            }
+            console.log(`\x1b[32m✔ Assertion Passed: ${path}\x1b[0m`);
+        },
+
+        /**
+         * Get all logs captured during execution
+         */
+        getLogs: () => tMock._logs,
+
+        /**
+         * Teardown the environment
+         */
+        teardown: async () => {
+            // Cleanup context and references
+            for (const key in tMock) delete tMock[key];
+        }
+    };
+}

package/templates/common/_tanfig.json

@@ -1,14 +1,20 @@
-{
-    "name": "{{name}}",
-    "description": "A powerful Titan Planet project",
-    "version": "1.0.0",
-    "build": {
-        "purpose": "test",
-        "files": [
-            "public",
-            "static",
-            "db",
-            "config"
-        ]
-    }
+{
+  "name": "{{name}}",
+  "description": "A powerful TitanPL project",
+  "version": "1.0.0",
+  "extensions": {
+    "allowWasm": true,
+    "allowNative": [
+      "@titanpl/core"
+    ]
+  },
+  "build": {
+    "purpose": "test",
+    "files": [
+      "public",
+      "static",
+      "db",
+      "tanfig.json"
+    ]
+  }
 }