@ezetgalaxy/titan 26.8.3 → 26.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/README.md +63 -14
  2. package/index.js +62 -15
  3. package/package.json +1 -1
  4. package/templates/extension/README.md +104 -104
  5. package/templates/extension/index.js +27 -27
  6. package/templates/extension/jsconfig.json +12 -12
  7. package/templates/extension/native/Cargo.toml +9 -9
  8. package/templates/extension/native/src/lib.rs +5 -5
  9. package/templates/extension/package.json +20 -20
  10. package/templates/extension/titan.json +17 -17
  11. package/templates/js/Dockerfile +66 -66
  12. package/templates/js/_dockerignore +3 -3
  13. package/templates/js/_gitignore +1 -0
  14. package/templates/js/app/actions/hello.js +5 -5
  15. package/templates/js/app/titan.d.ts +87 -87
  16. package/templates/js/jsconfig.json +18 -18
  17. package/templates/js/server/src/action_management.rs +131 -131
  18. package/templates/js/server/src/errors.rs +10 -10
  19. package/templates/js/server/src/extensions.rs +989 -989
  20. package/templates/js/server/src/utils.rs +33 -33
  21. package/templates/js/titan/bundle.js +78 -78
  22. package/templates/js/titan/dev.js +9 -1
  23. package/templates/js/titan/titan.js +122 -122
  24. package/templates/rust/Dockerfile +66 -66
  25. package/templates/rust/_dockerignore +3 -3
  26. package/templates/rust/_gitignore +1 -0
  27. package/templates/rust/app/actions/hello.js +5 -5
  28. package/templates/rust/app/actions/rust_hello.rs +14 -14
  29. package/templates/rust/app/titan.d.ts +101 -101
  30. package/templates/rust/jsconfig.json +18 -18
  31. package/templates/rust/server/src/action_management.rs +131 -131
  32. package/templates/rust/server/src/errors.rs +10 -10
  33. package/templates/rust/server/src/extensions.rs +989 -989
  34. package/templates/rust/server/src/utils.rs +33 -33
  35. package/templates/rust/titan/dev.js +9 -1
  36. package/templates/rust-ts/Dockerfile +66 -0
  37. package/templates/rust-ts/_dockerignore +3 -0
  38. package/templates/rust-ts/_gitignore +38 -0
  39. package/templates/rust-ts/app/actions/hello.ts +5 -0
  40. package/templates/rust-ts/app/actions/rust_hello.rs +14 -0
  41. package/templates/rust-ts/app/app.ts +11 -0
  42. package/templates/rust-ts/app/titan.d.ts +101 -0
  43. package/templates/rust-ts/package.json +14 -0
  44. package/templates/rust-ts/server/Cargo.lock +2869 -0
  45. package/templates/rust-ts/server/Cargo.toml +39 -0
  46. package/templates/rust-ts/server/src/action_management.rs +131 -0
  47. package/templates/rust-ts/server/src/errors.rs +51 -0
  48. package/templates/rust-ts/server/src/extensions.rs +989 -0
  49. package/templates/rust-ts/server/src/main.rs +468 -0
  50. package/templates/rust-ts/server/src/utils.rs +33 -0
  51. package/templates/rust-ts/titan/bundle.js +157 -0
  52. package/templates/rust-ts/titan/dev.js +402 -0
  53. package/templates/rust-ts/titan/titan.js +122 -0
  54. package/templates/rust-ts/tsconfig.json +21 -0
  55. package/templates/ts/Dockerfile +66 -0
  56. package/templates/ts/_dockerignore +3 -0
  57. package/templates/ts/_gitignore +38 -0
  58. package/templates/ts/app/actions/hello.ts +9 -0
  59. package/templates/ts/app/app.ts +10 -0
  60. package/templates/ts/app/titan.d.ts +102 -0
  61. package/templates/ts/package.json +26 -0
  62. package/templates/ts/server/Cargo.lock +2869 -0
  63. package/templates/ts/server/Cargo.toml +27 -0
  64. package/templates/ts/server/src/action_management.rs +131 -0
  65. package/templates/ts/server/src/errors.rs +51 -0
  66. package/templates/ts/server/src/extensions.rs +989 -0
  67. package/templates/ts/server/src/main.rs +437 -0
  68. package/templates/ts/server/src/utils.rs +33 -0
  69. package/templates/ts/titan/bundle.js +78 -0
  70. package/templates/ts/titan/dev.js +402 -0
  71. package/templates/ts/titan/titan.js +122 -0
  72. package/templates/ts/tsconfig.json +16 -0
  73. package/titanpl-sdk/README.md +109 -109
  74. package/titanpl-sdk/bin/run.js +254 -254
  75. package/titanpl-sdk/index.d.ts +46 -46
  76. package/titanpl-sdk/index.js +5 -5
  77. package/titanpl-sdk/package.json +32 -32
  78. package/titanpl-sdk/templates/.dockerignore +3 -3
  79. package/titanpl-sdk/templates/Dockerfile +53 -53
  80. package/titanpl-sdk/templates/app/actions/hello.js +5 -5
  81. package/titanpl-sdk/templates/app/titan.d.ts +87 -87
  82. package/titanpl-sdk/templates/jsconfig.json +18 -18
  83. package/titanpl-sdk/templates/server/src/action_management.rs +131 -131
  84. package/titanpl-sdk/templates/server/src/errors.rs +10 -10
  85. package/titanpl-sdk/templates/server/src/extensions.rs +640 -640
  86. package/titanpl-sdk/templates/server/src/utils.rs +33 -33
  87. package/titanpl-sdk/templates/titan/bundle.js +65 -65
  88. package/titanpl-sdk/templates/titan/dev.js +113 -113
  89. package/titanpl-sdk/templates/titan/titan.js +98 -98
  90. package/templates/js/server/action_map.json +0 -3
  91. package/templates/js/server/actions/hello.jsbundle +0 -48
  92. package/templates/js/server/routes.json +0 -16
  93. package/templates/rust/server/action_map.json +0 -3
  94. package/templates/rust/server/actions/hello.jsbundle +0 -47
  95. package/templates/rust/server/routes.json +0 -22
  96. package/templates/rust/server/src/actions_rust/mod.rs +0 -19
  97. package/templates/rust/server/src/actions_rust/rust_hello.rs +0 -14
package/README.md CHANGED
@@ -13,6 +13,7 @@
13
13
  💙 **Enjoy development mode `titan dev`**
14
14
  💟 **Titan Planet docs:** https://titan-docs-ez.vercel.app/docs
15
15
  🚀 **CLI: `titan` is now the canonical command. `tit` remains supported as an alias.**
16
+ 🛡️ **Strict Mode:** Titan now enforces zero type errors before running.
16
17
 
17
18
  ---
18
19
 
@@ -21,15 +22,15 @@
21
22
  [![npm version](https://img.shields.io/npm/v/@ezetgalaxy/titan.svg?style=flat-square)](https://www.npmjs.com/package/@ezetgalaxy/titan)
22
23
 
23
24
 
24
- **JavaScript Simplicity. Native Rust Power. Zero Configuration.**
25
+ **TypeScript Precision. JavaScript Simplicity. Native Rust Power. Zero Configuration.**
25
26
 
26
- Titan Planet is a **JavaScript-first Backend Framework** that compiles your application into a single, high-performance native binary. It embeds a V8 JavaScript runtime directly into a specialized Rust + Axum server.
27
+ Titan Planet is a **JavaScript/TypeScript-first Backend Framework** that compiles your application into a single, high-performance native binary. It embeds a V8 JavaScript runtime directly into a specialized Rust + Axum server.
27
28
 
28
- **Start with pure JavaScript.**
29
+ **Start with pure TypeScript/JavaScript.**
29
30
  **Need raw power? Add Rust actions seamlessly.**
30
31
  Titan handles the compilation, bundling, and routing automatically for both.
31
32
 
32
- Titan = **JavaScript productivity × Rust performance × Zero DevOps**
33
+ Titan = **TS/JS productivity × Rust performance × Zero DevOps**
33
34
 
34
35
  ---
35
36
 
@@ -38,8 +39,8 @@ Titan = **JavaScript productivity × Rust performance × Zero DevOps**
38
39
  | Feature | Titan | Express/Nest | FastAPI | Bun |
39
40
  | ------------------------------------ | ----- | ------------ | ------- | --------- |
40
41
  | Native binary output | ✅ Yes | ❌ No | ❌ No | ❌ No |
41
- | Hybrid Rust + JS Actions | ✅ Yes | ❌ No | ❌ No | ❌ No |
42
- | Pure JavaScript developer experience | ✅ Yes | ✅ Yes | ❌ No | ❌ Partial |
42
+ | Hybrid Rust + JS/TS Actions | ✅ Yes | ❌ No | ❌ No | ❌ No |
43
+ | Strict TypeScript Enforcement | ✅ Yes | ❌ Setup Req. | ❌ No | ❌ Partial |
43
44
  | Zero-config Docker deploy | ✅ Yes | ❌ No | ❌ No | ❌ No |
44
45
  | Action-based architecture | ✅ Yes | ❌ No | ❌ No | ❌ No |
45
46
  | Hot reload dev server | ✅ Yes | ❌ No | ❌ No | ❌ No |
@@ -62,7 +63,9 @@ npm install -g @ezetgalaxy/titan
62
63
  titan init my-app
63
64
  # Follow the interactive prompt to choose:
64
65
  # - JavaScript (Standard)
66
+ # - TypeScript (Strict)
65
67
  # - Rust + JavaScript (Beta)
68
+ # - Rust + TypeScript (Beta)
66
69
  ```
67
70
 
68
71
  Inside your project:
@@ -73,10 +76,11 @@ titan dev
73
76
 
74
77
  You'll see the Titan Dev Server spin up:
75
78
  ```
76
- Titan Planet v26.8.0 [ Dev Mode ]
79
+ Titan Planet v26.9.0 [ Dev Mode ]
77
80
 
78
- Type: Rust + JS Actions
81
+ Type: Rust + TS Actions
79
82
  Hot Reload: Enabled
83
+ Strict Mode: Active 🛡️
80
84
 
81
85
  • Preparing runtime... Done
82
86
  • A new orbit is ready for your app in 0.9s
@@ -87,7 +91,25 @@ You'll see the Titan Dev Server spin up:
87
91
 
88
92
  # ⚡ Hybrid Action System
89
93
 
90
- Titan is unique because it allows you to write endpoints in **both** JavaScript and Rust within the same project.
94
+ Titan is unique because it allows you to write endpoints in **JavaScript, TypeScript, and Rust** within the same project.
95
+
96
+ ### 🔵 TypeScript Actions (`app/actions/hello.ts`)
97
+ Fully typed, strict, and auto-compiled.
98
+ ```typescript
99
+ import { Context } from '@ezetgalaxy/titan';
100
+
101
+ export function run(req: Context) {
102
+ t.log("Handling request with strict types...");
103
+
104
+ // Type checking allows safe property access
105
+ const user = req.body as { name: string };
106
+
107
+ return {
108
+ message: "Hello from TypeScript!",
109
+ user_name: user.name
110
+ };
111
+ }
112
+ ```
91
113
 
92
114
  ### 🟡 JavaScript Actions (`app/actions/hello.js`)
93
115
  Perfect for business logic, rapid prototyping, and IO-bound tasks.
@@ -115,17 +137,43 @@ pub async fn run(req: Request<Body>) -> impl IntoResponse {
115
137
  }
116
138
  ```
117
139
 
118
- **Titan automatically detects, compiles, and routes both types.**
140
+ **Titan automatically detects, compiles, and routes all types.**
141
+ * `.ts` files are type-checked and compiled with esbuild.
119
142
  * `.js` files are bundled with esbuild.
120
143
  * `.rs` files are compiled into the native binary.
121
- * Both share the same `routes.json` configuration.
144
+ * All share the same `routes.json` configuration.
145
+
146
+ ---
147
+
148
+ # 🛡️ Strict Type Safety & Error Logs
149
+
150
+ Titan prioritizes code quality by enforcing **Strict TypeScript** logic during development.
151
+
152
+ If `titan dev` detects a type error, the server **will not run**. This ensures you never ship or test broken code.
153
+
154
+ ### Sample Error Output
155
+ When a type error occurs, Titan pauses execution and provides a clear, actionable log:
156
+
157
+ ```text
158
+ [Titan] ❌ TypeScript Error:
159
+ app/actions/payment.ts(12,5): error TS2322: Type 'string' is not assignable to type 'number'.
160
+
161
+ 10 | const amount: number = req.body.amount;
162
+ 11 |
163
+ > 12 | processPayment( "100" ); // Error here
164
+ | ^^^^^^^^^^^^^^^^^^^^^^^
165
+
166
+ [Titan] 🛑 Server paused due to type errors. Fix them to resume.
167
+ ```
168
+
169
+ Once fixed, the server automatically resumes.
122
170
 
123
171
  ---
124
172
 
125
173
  # ✨ Core Capabilities
126
174
 
127
175
  ### 🔌 Unified Runtime API (`t`)
128
- Both JS and Rust actions have access to the powerful `t` namespace:
176
+ All actions (JS/TS/Rust) have access to the powerful `t` namespace:
129
177
 
130
178
  * `t.fetch(url, options)` — High-performance HTTP client
131
179
  * `t.log(msg)` — Sandboxed, structured logging
@@ -143,7 +191,7 @@ Extend the runtime with custom Rust engines using **Titan Extensions**.
143
191
 
144
192
  # 📦 Deployment
145
193
 
146
- Titan compiles your entire app—JS code, Rust code, and server logic—into a **single executable**.
194
+ Titan compiles your entire app—JS/TS code, Rust code, and server logic—into a **single executable**.
147
195
 
148
196
  * **Tiny Docker Images**: Alpine-based, ~20MB compressed.
149
197
  * **Instant Startup**: No node_modules overhead.
@@ -152,7 +200,7 @@ Titan compiles your entire app—JS code, Rust code, and server logic—into a *
152
200
  ---
153
201
 
154
202
  # 🧱 Architecture Note
155
- Titan is **not** a Node.js framework. It is a Rust server that speaks JavaScript.
203
+ Titan is **not** a Node.js framework. It is a Rust server that speaks JavaScript/TypeScript.
156
204
  * **No Event Loop** for JS (Request/Response model).
157
205
  * **No `require`** (Use raw imports or bundled dependencies).
158
206
  * **True Isolation** per request.
@@ -161,6 +209,7 @@ Titan is **not** a Node.js framework. It is a Rust server that speaks JavaScript
161
209
 
162
210
  **Titan v26 — Stable**
163
211
  * Production-ready Hybrid Runtime
212
+ * Strict TypeScript Support
164
213
  * Native Rust Performance
165
214
  * Zero-Config Cloud Deployment
166
215
 
package/index.js CHANGED
@@ -123,37 +123,82 @@ ${yellow("Note: `tit` is supported as a legacy alias.")}
123
123
  * INIT
124
124
  * ----------------------------------------------------- */
125
125
  async function initProject(name, templateName) {
126
- if (!name) {
127
- console.log(red("Usage: titan init <project> [--template <js|rust>]"));
128
- return;
126
+ let projName = name;
127
+
128
+ if (!projName) {
129
+ const response = await prompts({
130
+ type: 'text',
131
+ name: 'value',
132
+ message: 'Project name:',
133
+ initial: 'my-titan-app'
134
+ });
135
+
136
+ if (!response.value) {
137
+ console.log(red("✖ Operation cancelled"));
138
+ return;
139
+ }
140
+ projName = response.value;
129
141
  }
130
142
 
131
143
  let selectedTemplate = templateName;
132
144
 
133
145
  if (!selectedTemplate) {
134
- const response = await prompts({
146
+ // 1. Language Selection
147
+ const langRes = await prompts({
135
148
  type: 'select',
136
149
  name: 'value',
137
- message: 'Select a template:',
150
+ message: 'Select language:',
138
151
  choices: [
139
- { title: 'JavaScript', description: 'Standard Titan app with JS actions', value: 'js' },
140
- { title: `Rust + JavaScript ${yellow('(Beta)')}`, description: 'High-performance Rust actions + JS flexibility', value: 'rust' }
152
+ { title: 'JavaScript', value: 'js' },
153
+ { title: 'TypeScript', value: 'ts' }
141
154
  ],
142
155
  initial: 0
143
156
  });
144
157
 
145
- if (!response.value) {
158
+ if (!langRes.value) {
159
+ console.log(red("✖ Operation cancelled"));
160
+ return;
161
+ }
162
+ const lang = langRes.value;
163
+
164
+ // 2. Template Selection
165
+ const archRes = await prompts({
166
+ type: 'select',
167
+ name: 'value',
168
+ message: 'Select template:',
169
+ choices: [
170
+ {
171
+ title: `Standard (${lang.toUpperCase()})`,
172
+ description: `Standard Titan app with ${lang.toUpperCase()} actions`,
173
+ value: 'standard'
174
+ },
175
+ {
176
+ title: `Rust + ${lang.toUpperCase()} (Hybrid)`,
177
+ description: `High-performance Rust actions + ${lang.toUpperCase()} flexibility`,
178
+ value: 'hybrid'
179
+ }
180
+ ],
181
+ initial: 0
182
+ });
183
+
184
+ if (!archRes.value) {
146
185
  console.log(red("✖ Operation cancelled"));
147
186
  return;
148
187
  }
149
- selectedTemplate = response.value;
188
+ const arch = archRes.value;
189
+
190
+ if (lang === 'js') {
191
+ selectedTemplate = arch === 'standard' ? 'js' : 'rust';
192
+ } else {
193
+ selectedTemplate = arch === 'standard' ? 'ts' : 'rust-ts';
194
+ }
150
195
  }
151
196
 
152
- const target = path.join(process.cwd(), name);
197
+ const target = path.join(process.cwd(), projName);
153
198
  const templateDir = path.join(__dirname, "templates", selectedTemplate);
154
199
 
155
200
  if (!fs.existsSync(templateDir)) {
156
- console.log(red(`Template '${selectedTemplate}' not found. Available: js, rust`));
201
+ console.log(red(`Template '${selectedTemplate}' not found.`));
157
202
  return;
158
203
  }
159
204
 
@@ -164,7 +209,7 @@ async function initProject(name, templateName) {
164
209
 
165
210
  console.log("\n" + bold(cyan("🚀 Initializing Titan Project...")));
166
211
  console.log(gray(` Target: ${target}`));
167
- console.log(gray(` Template: ${selectedTemplate === 'rust' ? 'Rust + JS (Native Perf)' : 'JavaScript (Standard)'}`));
212
+ console.log(gray(` Template: ${selectedTemplate}`));
168
213
 
169
214
  // ----------------------------------------------------------
170
215
  // 1. Copy full template directory
@@ -198,7 +243,7 @@ async function initProject(name, templateName) {
198
243
  console.log(cyan("📦 Installing dependencies..."));
199
244
 
200
245
  try {
201
- execSync(`npm install esbuild chokidar --silent`, {
246
+ execSync(`npm install --silent`, {
202
247
  cwd: target,
203
248
  stdio: "inherit",
204
249
  });
@@ -210,7 +255,7 @@ async function initProject(name, templateName) {
210
255
  console.log("\n" + bold(green("🎉 You're all set!")));
211
256
  console.log(`
212
257
  ${gray("Next steps:")}
213
- ${cyan(`cd ${name}`)}
258
+ ${cyan(`cd ${projName}`)}
214
259
  ${cyan("titan dev")}
215
260
  `);
216
261
  }
@@ -335,7 +380,9 @@ function updateTitan() {
335
380
  }
336
381
 
337
382
  if (!fs.existsSync(templateServer)) {
338
- console.log(red("CLI is corrupted — server template missing."));
383
+ console.log(red(`CLI seems corrupted or incomplete.`));
384
+ console.log(red(`Expected server template at: ${templateServer}`));
385
+ console.log(yellow(`If you are running from npx, try clearing cache or installing a specific version.`));
339
386
  return;
340
387
  }
341
388
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ezetgalaxy/titan",
3
- "version": "26.8.3",
3
+ "version": "26.9.0",
4
4
  "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.",
5
5
  "license": "ISC",
6
6
  "author": "ezetgalaxy",
package/templates/extension/README.md CHANGED
@@ -1,104 +1,104 @@
1
- # 🪐 Titan Extension: {{name}}
2
-
3
- > Elevate Titan Planet with custom JavaScript and high-performance Native Rust logic.
4
-
5
- Welcome to your new Titan extension! This template provides everything you need to build, test, and deploy powerful additions to the Titan project.
6
-
7
- ---
8
-
9
- ## 🛠 Project Structure
10
-
11
- - `index.js`: The JavaScript entry point where you define your extension's API on the global `t` object.
12
- - `titan.json`: Manifest file defining extension metadata and Native module mappings.
13
- - `native/`: Directory for Rust source code.
14
- - `src/lib.rs`: Your Native function implementations.
15
- - `Cargo.toml`: Rust package and dependency configuration.
16
- - `jsconfig.json`: Enables full IntelliSense for the Titan Runtime API.
17
-
18
- ---
19
-
20
- ## 🚀 Quick Start
21
-
22
- ### 1. Install Dependencies
23
- Get full type support in your IDE:
24
- ```bash
25
- npm install
26
- ```
27
-
28
- ### 2. Build Native Module (Optional)
29
- If your extension uses Rust, compile it to a dynamic library:
30
- ```bash
31
- cd native
32
- cargo build --release
33
- cd ..
34
- ```
35
-
36
- ### 3. Test the Extension
37
- Use the Titan SDK to run a local test harness:
38
- ```bash
39
- titan run ext
40
- ```
41
- *Tip: Visit `http://localhost:3000/test` after starting the runner to see your extension in action!*
42
-
43
- ---
44
-
45
- ## 💻 Development Guide
46
-
47
- ### Writing JavaScript
48
- Extensions interact with the global `t` object. It's best practice to namespace your extension:
49
-
50
- ```javascript
51
- t.{{name}} = {
52
- myMethod: (val) => {
53
- t.log("{{name}}", "Doing something...");
54
- return val * 2;
55
- }
56
- };
57
- ```
58
-
59
- ### Writing Native Rust Functions
60
- Native functions should be marked with `#[unsafe(no_mangle)]` and use `extern "C"`:
61
-
62
- ```rust
63
- #[unsafe(no_mangle)]
64
- pub extern "C" fn multiply(a: f64, b: f64) -> f64 {
65
- a * b
66
- }
67
- ```
68
-
69
- ### Mapping Native Functions in `titan.json`
70
- Expose your Rust functions to JavaScript by adding them to the `native.functions` section:
71
-
72
- ```json
73
- "functions": {
74
- "add": {
75
- "symbol": "add",
76
- "parameters": ["f64", "f64"],
77
- "result": "f64"
78
- }
79
- }
80
- ```
81
-
82
- ---
83
-
84
- ## 🧪 Testing with Titan SDK
85
-
86
- The `titan run ext` command automates the testing workflow:
87
- 1. It builds your native code.
88
- 2. It sets up a temporary Titan project environment.
89
- 3. It links your extension into `node_modules`.
90
- 4. It starts the Titan Runtime at `http://localhost:3000`.
91
-
92
- You can modify the test harness or add custom test cases by exploring the generated `.titan_test_run` directory (it is git-ignored).
93
-
94
- ---
95
-
96
- ## 📦 Deployment
97
- To use your extension in a Titan project:
98
- 1. Publish your extension to npm or link it locally.
99
- 2. In your Titan project: `npm install my-extension`.
100
- 3. The Titan Runtime will automatically detect and load your extension if it contains a `titan.json`.
101
-
102
- ---
103
-
104
- Happy coding on Titan Planet! 🚀
1
+ # 🪐 Titan Extension: {{name}}
2
+
3
+ > Elevate Titan Planet with custom JavaScript and high-performance Native Rust logic.
4
+
5
+ Welcome to your new Titan extension! This template provides everything you need to build, test, and deploy powerful additions to the Titan project.
6
+
7
+ ---
8
+
9
+ ## 🛠 Project Structure
10
+
11
+ - `index.js`: The JavaScript entry point where you define your extension's API on the global `t` object.
12
+ - `titan.json`: Manifest file defining extension metadata and Native module mappings.
13
+ - `native/`: Directory for Rust source code.
14
+ - `src/lib.rs`: Your Native function implementations.
15
+ - `Cargo.toml`: Rust package and dependency configuration.
16
+ - `jsconfig.json`: Enables full IntelliSense for the Titan Runtime API.
17
+
18
+ ---
19
+
20
+ ## 🚀 Quick Start
21
+
22
+ ### 1. Install Dependencies
23
+ Get full type support in your IDE:
24
+ ```bash
25
+ npm install
26
+ ```
27
+
28
+ ### 2. Build Native Module (Optional)
29
+ If your extension uses Rust, compile it to a dynamic library:
30
+ ```bash
31
+ cd native
32
+ cargo build --release
33
+ cd ..
34
+ ```
35
+
36
+ ### 3. Test the Extension
37
+ Use the Titan SDK to run a local test harness:
38
+ ```bash
39
+ titan run ext
40
+ ```
41
+ *Tip: Visit `http://localhost:3000/test` after starting the runner to see your extension in action!*
42
+
43
+ ---
44
+
45
+ ## 💻 Development Guide
46
+
47
+ ### Writing JavaScript
48
+ Extensions interact with the global `t` object. It's best practice to namespace your extension:
49
+
50
+ ```javascript
51
+ t.{{name}} = {
52
+ myMethod: (val) => {
53
+ t.log("{{name}}", "Doing something...");
54
+ return val * 2;
55
+ }
56
+ };
57
+ ```
58
+
59
+ ### Writing Native Rust Functions
60
+ Native functions should be marked with `#[unsafe(no_mangle)]` and use `extern "C"`:
61
+
62
+ ```rust
63
+ #[unsafe(no_mangle)]
64
+ pub extern "C" fn multiply(a: f64, b: f64) -> f64 {
65
+ a * b
66
+ }
67
+ ```
68
+
69
+ ### Mapping Native Functions in `titan.json`
70
+ Expose your Rust functions to JavaScript by adding them to the `native.functions` section:
71
+
72
+ ```json
73
+ "functions": {
74
+ "add": {
75
+ "symbol": "add",
76
+ "parameters": ["f64", "f64"],
77
+ "result": "f64"
78
+ }
79
+ }
80
+ ```
81
+
82
+ ---
83
+
84
+ ## 🧪 Testing with Titan SDK
85
+
86
+ The `titan run ext` command automates the testing workflow:
87
+ 1. It builds your native code.
88
+ 2. It sets up a temporary Titan project environment.
89
+ 3. It links your extension into `node_modules`.
90
+ 4. It starts the Titan Runtime at `http://localhost:3000`.
91
+
92
+ You can modify the test harness or add custom test cases by exploring the generated `.titan_test_run` directory (it is git-ignored).
93
+
94
+ ---
95
+
96
+ ## 📦 Deployment
97
+ To use your extension in a Titan project:
98
+ 1. Publish your extension to npm or link it locally.
99
+ 2. In your Titan project: `npm install my-extension`.
100
+ 3. The Titan Runtime will automatically detect and load your extension if it contains a `titan.json`.
101
+
102
+ ---
103
+
104
+ Happy coding on Titan Planet! 🚀
package/templates/extension/index.js CHANGED
@@ -1,27 +1,27 @@
1
- /**
2
- * Titan Extension Entry Point
3
- * You can attach methods to the global `t` object here.
4
- */
5
-
6
- // Define your extension Key
7
- const EXT_KEY = "{{name}}";
8
-
9
- t.log(EXT_KEY, "Extension loading...");
10
-
11
- // Preserve any native functions already attached to this key
12
- t[EXT_KEY] = Object.assign(t[EXT_KEY] || {}, {
13
- // Example pure JavaScript function
14
- hello: function (name) {
15
- t.log(EXT_KEY, `Hello ${name} from ${EXT_KEY}!`);
16
- return `Hello ${name}!`;
17
- },
18
-
19
- // Example Wrapper for Native function
20
- calc: function (a, b) {
21
- t.log(EXT_KEY, `Calculating ${a} + ${b} natively...`);
22
- // Assumes the native function 'add' is mapped in titan.json
23
- return t[EXT_KEY].add(a, b);
24
- }
25
- });
26
-
27
- t.log(EXT_KEY, "Extension loaded!");
1
+ /**
2
+ * Titan Extension Entry Point
3
+ * You can attach methods to the global `t` object here.
4
+ */
5
+
6
+ // Define your extension Key
7
+ const EXT_KEY = "{{name}}";
8
+
9
+ t.log(EXT_KEY, "Extension loading...");
10
+
11
+ // Preserve any native functions already attached to this key
12
+ t[EXT_KEY] = Object.assign(t[EXT_KEY] || {}, {
13
+ // Example pure JavaScript function
14
+ hello: function (name) {
15
+ t.log(EXT_KEY, `Hello ${name} from ${EXT_KEY}!`);
16
+ return `Hello ${name}!`;
17
+ },
18
+
19
+ // Example Wrapper for Native function
20
+ calc: function (a, b) {
21
+ t.log(EXT_KEY, `Calculating ${a} + ${b} natively...`);
22
+ // Assumes the native function 'add' is mapped in titan.json
23
+ return t[EXT_KEY].add(a, b);
24
+ }
25
+ });
26
+
27
+ t.log(EXT_KEY, "Extension loaded!");
package/templates/extension/jsconfig.json CHANGED
@@ -1,13 +1,13 @@
1
- {
2
- "compilerOptions": {
3
- "module": "commonjs",
4
- "target": "es2021",
5
- "checkJs": false,
6
- "allowJs": true,
7
- "moduleResolution": "node"
8
- },
9
- "include": [
10
- "index.js",
11
- "node_modules/titan-sdk/index.d.ts"
12
- ]
1
+ {
2
+ "compilerOptions": {
3
+ "module": "commonjs",
4
+ "target": "es2021",
5
+ "checkJs": false,
6
+ "allowJs": true,
7
+ "moduleResolution": "node"
8
+ },
9
+ "include": [
10
+ "index.js",
11
+ "node_modules/titan-sdk/index.d.ts"
12
+ ]
13
13
  }
package/templates/extension/native/Cargo.toml CHANGED
@@ -1,9 +1,9 @@
1
- [package]
2
- name = "{{native_name}}_native"
3
- version = "0.1.0"
4
- edition = "2024"
5
-
6
- [lib]
7
- crate-type = ["cdylib"]
8
-
9
- [dependencies]
1
+ [package]
2
+ name = "{{native_name}}_native"
3
+ version = "0.1.0"
4
+ edition = "2024"
5
+
6
+ [lib]
7
+ crate-type = ["cdylib"]
8
+
9
+ [dependencies]
package/templates/extension/native/src/lib.rs CHANGED
@@ -1,5 +1,5 @@
1
-
2
- #[unsafe(no_mangle)]
3
- pub extern "C" fn add(a: f64, b: f64) -> f64 {
4
- a + b
5
- }
1
+
2
+ #[unsafe(no_mangle)]
3
+ pub extern "C" fn add(a: f64, b: f64) -> f64 {
4
+ a + b
5
+ }
package/templates/extension/package.json CHANGED
@@ -1,21 +1,21 @@
1
- {
2
- "name": "{{name}}",
3
- "version": "1.0.0",
4
- "description": "A Titan Planet extension",
5
- "main": "index.js",
6
- "type": "commonjs",
7
- "scripts": {
8
- "test": "echo \"Error: no test specified\" && exit 1"
9
- },
10
- "keywords": [
11
- "titan planet",
12
- "extension"
13
- ],
14
- "author": "",
15
- "license": "ISC",
16
- "dependencies": {
17
- "titanpl-sdk": "latest",
18
- "chokidar": "^5.0.0",
19
- "esbuild": "^0.27.2"
20
- }
1
+ {
2
+ "name": "{{name}}",
3
+ "version": "1.0.0",
4
+ "description": "A Titan Planet extension",
5
+ "main": "index.js",
6
+ "type": "commonjs",
7
+ "scripts": {
8
+ "test": "echo \"Error: no test specified\" && exit 1"
9
+ },
10
+ "keywords": [
11
+ "titan planet",
12
+ "extension"
13
+ ],
14
+ "author": "",
15
+ "license": "ISC",
16
+ "dependencies": {
17
+ "titanpl-sdk": "latest",
18
+ "chokidar": "^5.0.0",
19
+ "esbuild": "^0.27.2"
20
+ }
21
21
  }