titanpl 6.0.0 → 7.0.0-beta

package/packages/native/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@titanpl/native",
-  "version": "6.0.0",
+  "version": "7.0.0-beta",
   "description": "Titan native utilities package",
   "type": "module",
   "keywords": [

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

@@ -297,6 +297,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).
  *
@@ -647,12 +655,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 +1020,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 +1752,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;
 }
 
@@ -91,7 +100,7 @@ export async function release(root = process.cwd()) {
     } catch (e) { }
   }
 
-  const filesToCopy = config.build && config.build.files ? config.build.files : ["public", "static", "db", "config"];
+  const filesToCopy = config.build && config.build.files ? config.build.files : ["public", "static", "db", "config", "tanfig.json", "titan.json"];
 
   // Clear or ensure build dir
   if (fs.existsSync(buildDir)) {
@@ -111,11 +120,19 @@ export async function release(root = process.cwd()) {
     }
   }
 
-  // 3. Copy package.json
+  // 3. Copy package.json & tanfig.json
   const pkgPath = path.join(root, "package.json");
   if (fs.existsSync(pkgPath)) {
     fs.copyFileSync(pkgPath, path.join(buildDir, "package.json"));
   }
+  const tanfigPath = path.join(root, "tanfig.json");
+  if (fs.existsSync(tanfigPath)) {
+    fs.copyFileSync(tanfigPath, path.join(buildDir, "tanfig.json"));
+  }
+  const titanConfigPath = path.join(root, "titan.json");
+  if (fs.existsSync(titanConfigPath)) {
+    fs.copyFileSync(titanConfigPath, path.join(buildDir, "titan.json"));
+  }
 
   // 4. Create .env
   fs.writeFileSync(path.join(buildDir, ".env"), "TITAN_DEV=0\n");

package/packages/packet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@titanpl/packet",
-  "version": "6.0.0",
+  "version": "7.0.0-beta",
   "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-beta",
   "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-beta",
+  "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,18 @@
-{
-    "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": false,
+    "allowNative": []
+  },
+  "build": {
+    "purpose": "test",
+    "files": [
+      "public",
+      "static",
+      "db",
+      "tanfig.json"
+    ]
+  }
 }

package/templates/extension/index.d.ts

@@ -1,27 +1,31 @@
-// Type definitions for {{name}}
-// This file facilitates type inference when this extension is installed in a Titan project.
+/**
+ * @package ext-template
+ * Professional extension template for the TitanPL framework.
+ */
 
-declare global {
-    namespace Titan {
-        interface Runtime {
-            /**
-             * {{name}} Extension
-             */
-            "{{name}}": {
-                /**
-                 * Example hello function
-                 */
-                hello(name: string): string;
+/** Main configuration interface */
+export interface Config {
+  /** Secure key or secret */
+  secret?: string;
+  /** Custom logging function */
+  log?: (msg: string) => void;
+}
+
+/** Standard Success Response */
+export interface Result {
+  result: string;
+  status: "ok" | "error";
+}
+
+/** Main Extension class */
+declare class Extension {
+  constructor(config?: Config);
 
-                /**
-                 * Example calc function (native wrapper)
-                 */
-                calc(a: number, b: number): number;
+  /** Hash a string synchronously using bcryptjs */
+  hash(data: string): string;
 
-                // Add your extension methods here
-            }
-        }
-    }
+  /** Standard execution for processing input */
+  execute(input: string): Result;
 }
 
-export { };
+export default Extension;

package/templates/extension/index.js

@@ -1,17 +1,17 @@
-// Define your extension Key
-if (typeof Titan === "undefined") globalThis.Titan = t;
-const EXT_KEY = "{{name}}";
+import { registerExtension } from './utils/registerExtension.js';
 
-// Preserve any native functions already attached to this key
-t[EXT_KEY] = Object.assign(t[EXT_KEY] || {}, {
-    // Example pure JavaScript function
-    hello: function (name) {
-        return `Hello ${name} from ${EXT_KEY}!`;
-    },
-
-    // Example Wrapper for Native function
-    calc: function (a, b) {
-        // Assumes the native function 'add' is mapped in titan.json
-        return t[EXT_KEY].add(a, b);
+const myExt = {
+    /**
+     * A sample function that can be called from any Titan Action.
+     */
+    hello: () => {
+        t.log("{{name}}", "Hello from extension!");
+        return "hello";
     }
-});
+};
+
+// If this is a Wasm or Native extension, bindings will be injected here during build.
+// Use 'titan build ext' to generate them.
+
+registerExtension("{{name}}", myExt);
+export default myExt;

package/templates/extension/native/Cargo.toml

@@ -1,9 +1,11 @@
 [package]
-name = "{{native_name}}_native"
-version = "0.1.0"
-edition = "2024"
+name = "my-extension-native"
+version = "1.0.0"
+edition = "2021"
 
 [lib]
 crate-type = ["cdylib"]
 
 [dependencies]
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"

package/templates/extension/native/src/lib.rs

@@ -1,5 +1,4 @@
-
-#[unsafe(no_mangle)]
-pub extern "C" fn add(a: f64, b: f64) -> f64 {
+#[titanpl::export]
+pub fn add(a: f64, b: f64) -> f64 {
     a + b
 }

package/templates/extension/package.json

@@ -1,26 +1,16 @@
 {
-  "name": "{{name}}",
-  "version": "6.0.0",
-  "description": "A Titan Planet extension",
+  "name": "my-extension",
+  "version": "7.0.0-beta",
+  "description": "A high-performance TitanPL extension.",
+  "type": "module",
   "main": "index.js",
-  "types": "index.d.ts",
-  "type": "commonjs",
-  "scripts": {
-    "test": "microgravity test"
-  },
-  "keywords": [
-    "titan planet",
-    "extension"
+  "files": [
+    "index.js",
+    "titan.json",
+    "jsconfig.json",
+    "README.md"
   ],
-  "author": "",
-  "license": "ISC",
   "dependencies": {
-    "@titanpl/core": "latest",
-    "chokidar": "^5.0.0",
-    "esbuild": "^0.27.2",
-    "titanpl-sdk": "6.0.0"
-  },
-  "devDependencies": {
-    "@tgrv/microgravity": "latest"
+    "@titanpl/sdk": "7.0.0-beta"
   }
 }

package/templates/extension/titan.json

@@ -1,18 +1,7 @@
 {
-    "name": "{{name}}",
-    "main": "index.js",
-    "description": "A Titan extension",
-    "native": {
-        "path": "native/target/release/{{native_name}}_native.dll",
-        "functions": {
-            "add": {
-                "symbol": "add",
-                "parameters": [
-                    "f64",
-                    "f64"
-                ],
-                "result": "f64"
-            }
-        }
-    }
+  "name": "my-extension",
+  "version": "1.0.0",
+  "type": "wasm",
+  "entry": "index.js",
+  "description": "A high-performance TitanPL extension."
 }

package/templates/extension/utils/registerExtension.js

@@ -0,0 +1,44 @@
+// utils/registerExtension.js
+
+/**
+ * Safely registers an extension in the global t object
+ * @param {string} extensionName - Unique name for the extension
+ * @param {any} extensionModule - The extension module/object to register
+ * @returns {boolean} True if registration was successful
+ */
+export function registerExtension(extensionName, extensionModule) {
+    // Check for global t object
+    if (typeof t === 'undefined') {
+        console.warn(`[registerExtension] Global 't' object not available. Cannot register: ${extensionName}`);
+        return false;
+    }
+
+    // Input validation
+    if (!extensionName || typeof extensionName !== 'string') {
+        console.error('[registerExtension] Invalid extension name provided');
+        return false;
+    }
+
+    // Check for naming conflicts
+    if (t[extensionName]) {
+        console.warn(`[registerExtension] '${extensionName}' already exists in global t object, overwriting`);
+    }
+
+    try {
+        // Register the extension
+        t[extensionName] = extensionModule;
+        
+        console.log(`[registerExtension] Successfully registered '${extensionName}'`);
+
+        return true;
+    } catch (error) {
+        // Structured error reporting
+        console.error(`[registerExtension] Failed to register '${extensionName}':`, {
+            error: error.message,
+            extensionName,
+            moduleType: typeof extensionModule
+        });
+
+        return false;
+    }
+}

package/templates/js/package.json

@@ -6,16 +6,16 @@
     "template": "js"
   },
   "dependencies": {
-    "@titanpl/cli": "6.0.0",
-    "@titanpl/route": "6.0.0",
-    "@titanpl/native": "6.0.0",
+    "@titanpl/cli": "7.0.0-beta",
+    "@titanpl/route": "7.0.0-beta",
+    "@titanpl/native": "7.0.0-beta",
     "@titanpl/core": "latest",
     "@titanpl/node": "latest",
-    "@titanpl/packet": "6.0.0"
+    "@titanpl/packet": "7.0.0-beta"
   },
   "optionalDependencies": {
-    "@titanpl/engine-linux-x64": "6.0.0",
-    "@titanpl/engine-win32-x64": "6.0.0"
+    "@titanpl/engine-linux-x64": "7.0.0-beta",
+    "@titanpl/engine-win32-x64": "7.0.0-beta"
   },
   "scripts": {
     "build": "titan build",
@@ -28,5 +28,5 @@
     "eslint": "^9.39.2",
     "eslint-plugin-titanpl": "latest"
   },
-  "version": "6.0.0"
+  "version": "7.0.0-beta"
 }

package/templates/rust-js/package.json

@@ -1,15 +1,15 @@
 {
   "name": "titanpl",
-  "version": "6.0.0",
+  "version": "7.0.0-beta",
   "description": "A Titan Planet server",
   "type": "module",
   "titan": {
     "template": "rust-js"
   },
   "dependencies": {
-    "@titanpl/cli": "6.0.0",
-    "@titanpl/route": "6.0.0",
-    "@titanpl/native": "6.0.0",
+    "@titanpl/cli": "7.0.0-beta",
+    "@titanpl/route": "7.0.0-beta",
+    "@titanpl/native": "7.0.0-beta",
     "@titanpl/core": "latest",
     "@titanpl/node": "latest"
   },

package/templates/rust-ts/package.json

@@ -1,15 +1,15 @@
 {
   "name": "titanpl",
-  "version": "6.0.0",
+  "version": "7.0.0-beta",
   "description": "A Titan Planet server (Rust + TypeScript)",
   "type": "module",
   "titan": {
     "template": "rust-ts"
   },
   "dependencies": {
-    "@titanpl/cli": "6.0.0",
-    "@titanpl/route": "6.0.0",
-    "@titanpl/native": "6.0.0",
+    "@titanpl/cli": "7.0.0-beta",
+    "@titanpl/route": "7.0.0-beta",
+    "@titanpl/native": "7.0.0-beta",
     "@titanpl/core": "latest",
     "@titanpl/node": "latest",
     "typescript": "^5.0.0"