heliumts 0.2.4 → 0.2.6

package/README.md

@@ -1,6 +1,6 @@
 [![Status](https://img.shields.io/badge/status-active-success.svg)]()
-[![GitHub Issues](https://img.shields.io/github/issues/heliobentes/heliumjs)](https://github.com/heliobentes/heliumjs/issues)
-[![GitHub Pull Requests](https://img.shields.io/github/issues-pr/heliobentes/heliumjs)](https://github.com/heliobentes/heliumjs/pulls)
+[![GitHub Issues](https://img.shields.io/github/issues/heliobentes/heliumts)](https://github.com/heliobentes/heliumts/issues)
+[![GitHub Pull Requests](https://img.shields.io/github/issues-pr/heliobentes/heliumts)](https://github.com/heliobentes/heliumts/pulls)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](/LICENSE)
 
 # HeliumTS
@@ -31,49 +31,21 @@ HeliumTS is a blazing fast 🚀 and opinionated full-stack React + Vite framewor
 
 ### 1.1. Installation
 
-An installation script is coming soon! Meanwhile, follow these steps to set up a new HeliumTS project.
-
-#### 1.1.1. Install React + Vite
-
-```bash
-npm create vite@latest my-helium-app -- --template react-ts
-```
-#### 1.1.2. Install HeliumJS
+The easiest way to get started with HeliumTS is by using the scaffolding tool:
 
 ```bash
-npm install heliumts
+npm create heliumts-app@latest my-helium-app
 ```
 
-#### 1.1.3. Setup Vite Config
-Create or update `vite.config.ts` in the project root to include Helium's Vite plugin:
-
-```typescript
-import react from '@vitejs/plugin-react';
-import helium from 'heliumts/vite';
-import { defineConfig } from 'vite';
+Or (to create in the current directory):
 
-export default defineConfig({
-    plugins: [react(), helium()]
-});
 ```
-
-#### 1.1.4. Delete **main.tsx**
-Delete the `src/main.tsx` file created by Vite, as HeliumTS handles the client entry point automatically.
-Also, remove its reference from `index.html` if present.
-```html
-<!-- Remove this from index.html -->
-<script type="module" src="/src/main.tsx"></script>
+npm create heliumts-app@latest . 
 ```
 
-#### 1.1.5. Update `src/App.tsx`
-Replace the contents of `src/App.tsx` with the following content:
-```tsx
-import { type AppShellProps } from "heliumts/client";
+This command will guide you through setting up a new project with everything configured for you.
 
-export default function App({ Component, pageProps }: AppShellProps) {
-    return <Component {...pageProps} />;
-}
-```
+If you prefer to set up the project manually, please refer to the [Manual Installation Guide](./docs/manual-installation.md).
 
 ### 1.2. Running the Development Server
 
@@ -91,7 +63,7 @@ npx helium build
 npx helium start
 ```
 
-Check the working Example APP at: [https://github.com/heliobentes/heliumjs-example-app](https://github.com/heliobentes/heliumjs-example-app)
+Check the working Example APP at: [https://github.com/heliobentes/heliumts-example-app](https://github.com/heliobentes/heliumts-example-app)
 
 ## 2. Project Structure
 
@@ -336,6 +308,9 @@ See [SSG Documentation](./docs/ssg.md) for detailed information including limita
 
 ## 5. More Documentation
 
+### Getting Started
+-   [Manual Installation](./docs/manual-installation.md) - Step-by-step guide to setting up a HeliumTS project manually
+
 ### Core Features
 -   [Routing & useRouter](./docs/routing.md) - File-based routing, dynamic routes, navigation, and the useRouter hook
 -   [Configuration](./docs/helium-config.md) - Configure RPC encoding, compression, security, and proxy settings

package/dist/server/ipExtractor.d.ts

@@ -0,0 +1,48 @@
+import type http from "http";
+/**
+ * Extracts the client IP address from an HTTP request, taking into account proxy configurations.
+ *
+ * When behind proxies (like Vercel, Cloudflare, AWS ALB, etc.), the X-Forwarded-For header
+ * contains a chain of IP addresses. The format is: "client, proxy1, proxy2, ..."
+ *
+ * @param req - The HTTP request object
+ * @param trustProxyDepth - Number of proxy levels to trust
+ *   - 0: Only use req.socket.remoteAddress (no proxy trust)
+ *   - 1: Trust 1 proxy level (get the last IP before your server)
+ *   - 2+: Trust multiple proxy levels (for complex setups)
+ *
+ * Examples:
+ * - trustProxyDepth=0: Direct connection, no proxies
+ *   X-Forwarded-For: ignored
+ *   Result: req.socket.remoteAddress
+ *
+ * - trustProxyDepth=1: Behind one proxy (e.g., Vercel, Netlify)
+ *   X-Forwarded-For: "203.0.113.1, 198.51.100.1"
+ *   Result: "203.0.113.1" (client IP)
+ *
+ * - trustProxyDepth=2: Behind two proxies (e.g., Cloudflare -> Load Balancer)
+ *   X-Forwarded-For: "203.0.113.1, 198.51.100.1, 192.0.2.1"
+ *   Result: "203.0.113.1" (client IP)
+ *
+ * Common configurations:
+ * - Vercel/Netlify/Railway: trustProxyDepth=1
+ * - Cloudflare -> Origin: trustProxyDepth=1 or 2 (depending on your setup)
+ * - AWS ALB -> EC2: trustProxyDepth=1
+ * - Nginx -> Node: trustProxyDepth=1
+ * - Cloudflare -> Nginx -> Node: trustProxyDepth=2
+ */
+export declare function extractClientIP(req: http.IncomingMessage, trustProxyDepth?: number): string;
+/**
+ * Alternative extraction method that works from the right (trusts the rightmost IPs).
+ * This is useful when you want to trust the last N proxies in the chain.
+ *
+ * @param req - The HTTP request object
+ * @param trustProxyDepth - Number of proxy levels to trust from the right
+ *
+ * Example:
+ * X-Forwarded-For: "203.0.113.1, 198.51.100.1, 192.0.2.1"
+ * trustProxyDepth=1: Result is "198.51.100.1" (skip the last trusted proxy)
+ * trustProxyDepth=2: Result is "203.0.113.1" (skip the last 2 trusted proxies)
+ */
+export declare function extractClientIPFromRight(req: http.IncomingMessage, trustProxyDepth?: number): string;
+//# sourceMappingURL=ipExtractor.d.ts.map

package/dist/server/ipExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipExtractor.d.ts","sourceRoot":"","sources":["../../src/server/ipExtractor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,eAAe,GAAE,MAAU,GAAG,MAAM,CAqC9F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,eAAe,GAAE,MAAU,GAAG,MAAM,CAsBvG"}

package/dist/server/ipExtractor.js

@@ -0,0 +1,96 @@
+/**
+ * Extracts the client IP address from an HTTP request, taking into account proxy configurations.
+ *
+ * When behind proxies (like Vercel, Cloudflare, AWS ALB, etc.), the X-Forwarded-For header
+ * contains a chain of IP addresses. The format is: "client, proxy1, proxy2, ..."
+ *
+ * @param req - The HTTP request object
+ * @param trustProxyDepth - Number of proxy levels to trust
+ *   - 0: Only use req.socket.remoteAddress (no proxy trust)
+ *   - 1: Trust 1 proxy level (get the last IP before your server)
+ *   - 2+: Trust multiple proxy levels (for complex setups)
+ *
+ * Examples:
+ * - trustProxyDepth=0: Direct connection, no proxies
+ *   X-Forwarded-For: ignored
+ *   Result: req.socket.remoteAddress
+ *
+ * - trustProxyDepth=1: Behind one proxy (e.g., Vercel, Netlify)
+ *   X-Forwarded-For: "203.0.113.1, 198.51.100.1"
+ *   Result: "203.0.113.1" (client IP)
+ *
+ * - trustProxyDepth=2: Behind two proxies (e.g., Cloudflare -> Load Balancer)
+ *   X-Forwarded-For: "203.0.113.1, 198.51.100.1, 192.0.2.1"
+ *   Result: "203.0.113.1" (client IP)
+ *
+ * Common configurations:
+ * - Vercel/Netlify/Railway: trustProxyDepth=1
+ * - Cloudflare -> Origin: trustProxyDepth=1 or 2 (depending on your setup)
+ * - AWS ALB -> EC2: trustProxyDepth=1
+ * - Nginx -> Node: trustProxyDepth=1
+ * - Cloudflare -> Nginx -> Node: trustProxyDepth=2
+ */
+export function extractClientIP(req, trustProxyDepth = 0) {
+    // If not trusting any proxies, return the direct connection IP
+    if (trustProxyDepth === 0) {
+        return req.socket.remoteAddress || "unknown";
+    }
+    // Get X-Forwarded-For header
+    const forwardedFor = req.headers["x-forwarded-for"];
+    if (!forwardedFor) {
+        // No X-Forwarded-For header, fall back to direct connection
+        return req.socket.remoteAddress || "unknown";
+    }
+    // Parse X-Forwarded-For header (can be a string or array of strings)
+    const forwardedIPs = (Array.isArray(forwardedFor) ? forwardedFor.join(",") : forwardedFor)
+        .split(",")
+        .map((ip) => ip.trim())
+        .filter((ip) => ip.length > 0);
+    if (forwardedIPs.length === 0) {
+        // Empty X-Forwarded-For, fall back to direct connection
+        return req.socket.remoteAddress || "unknown";
+    }
+    // The client IP is at the beginning of the chain
+    // We trust the chain up to trustProxyDepth levels
+    // Format: [clientIP, proxy1, proxy2, ..., lastProxy]
+    // We want the clientIP, but we need to verify we have enough trusted proxies
+    if (forwardedIPs.length < trustProxyDepth) {
+        // Not enough IPs in the chain, the chain might be incomplete or spoofed
+        // Fall back to direct connection for safety
+        return req.socket.remoteAddress || "unknown";
+    }
+    // Return the client IP (first in the chain)
+    return forwardedIPs[0];
+}
+/**
+ * Alternative extraction method that works from the right (trusts the rightmost IPs).
+ * This is useful when you want to trust the last N proxies in the chain.
+ *
+ * @param req - The HTTP request object
+ * @param trustProxyDepth - Number of proxy levels to trust from the right
+ *
+ * Example:
+ * X-Forwarded-For: "203.0.113.1, 198.51.100.1, 192.0.2.1"
+ * trustProxyDepth=1: Result is "198.51.100.1" (skip the last trusted proxy)
+ * trustProxyDepth=2: Result is "203.0.113.1" (skip the last 2 trusted proxies)
+ */
+export function extractClientIPFromRight(req, trustProxyDepth = 0) {
+    if (trustProxyDepth === 0) {
+        return req.socket.remoteAddress || "unknown";
+    }
+    const forwardedFor = req.headers["x-forwarded-for"];
+    if (!forwardedFor) {
+        return req.socket.remoteAddress || "unknown";
+    }
+    const forwardedIPs = (Array.isArray(forwardedFor) ? forwardedFor.join(",") : forwardedFor)
+        .split(",")
+        .map((ip) => ip.trim())
+        .filter((ip) => ip.length > 0);
+    if (forwardedIPs.length === 0) {
+        return req.socket.remoteAddress || "unknown";
+    }
+    // Calculate which IP to trust by skipping the rightmost N trusted proxies
+    const clientIPIndex = Math.max(0, forwardedIPs.length - trustProxyDepth - 1);
+    return forwardedIPs[clientIPIndex];
+}
+//# sourceMappingURL=ipExtractor.js.map

package/dist/server/ipExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipExtractor.js","sourceRoot":"","sources":["../../src/server/ipExtractor.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,eAAe,CAAC,GAAyB,EAAE,kBAA0B,CAAC;IAClF,+DAA+D;IAC/D,IAAI,eAAe,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,GAAG,CAAC,MAAM,CAAC,aAAa,IAAI,SAAS,CAAC;IACjD,CAAC;IAED,6BAA6B;IAC7B,MAAM,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACpD,IAAI,CAAC,YAAY,EAAE,CAAC;QAChB,4DAA4D;QAC5D,OAAO,GAAG,CAAC,MAAM,CAAC,aAAa,IAAI,SAAS,CAAC;IACjD,CAAC;IAED,qEAAqE;IACrE,MAAM,YAAY,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;SACrF,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;SACtB,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAEnC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,wDAAwD;QACxD,OAAO,GAAG,CAAC,MAAM,CAAC,aAAa,IAAI,SAAS,CAAC;IACjD,CAAC;IAED,iDAAiD;IACjD,kDAAkD;IAClD,qDAAqD;IACrD,6EAA6E;IAE7E,IAAI,YAAY,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QACxC,wEAAwE;QACxE,4CAA4C;QAC5C,OAAO,GAAG,CAAC,MAAM,CAAC,aAAa,IAAI,SAAS,CAAC;IACjD,CAAC;IAED,4CAA4C;IAC5C,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAyB,EAAE,kBAA0B,CAAC;IAC3F,IAAI,eAAe,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,GAAG,CAAC,MAAM,CAAC,aAAa,IAAI,SAAS,CAAC;IACjD,CAAC;IAED,MAAM,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACpD,IAAI,CAAC,YAAY,EAAE,CAAC;QAChB,OAAO,GAAG,CAAC,MAAM,CAAC,aAAa,IAAI,SAAS,CAAC;IACjD,CAAC;IAED,MAAM,YAAY,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;SACrF,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;SACtB,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAEnC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,GAAG,CAAC,MAAM,CAAC,aAAa,IAAI,SAAS,CAAC;IACjD,CAAC;IAED,0EAA0E;IAC1E,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,MAAM,GAAG,eAAe,GAAG,CAAC,CAAC,CAAC;IAC7E,OAAO,YAAY,CAAC,aAAa,CAAC,CAAC;AACvC,CAAC"}

package/dist/utils/deepEqual.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=deepEqual.d.ts.map

package/dist/utils/deepEqual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepEqual.d.ts","sourceRoot":"","sources":["../../src/utils/deepEqual.ts"],"names":[],"mappings":""}

package/dist/utils/deepEqual.js

@@ -0,0 +1,2 @@
+"use strict";
+//# sourceMappingURL=deepEqual.js.map

package/dist/utils/deepEqual.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepEqual.js","sourceRoot":"","sources":["../../src/utils/deepEqual.ts"],"names":[],"mappings":""}

package/dist/utils/formatError.d.ts

@@ -0,0 +1,2 @@
+export declare function formatError(err: unknown): string;
+//# sourceMappingURL=formatError.d.ts.map

package/dist/utils/formatError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatError.d.ts","sourceRoot":"","sources":["../../src/utils/formatError.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAgBhD"}

package/dist/utils/formatError.js

@@ -0,0 +1,18 @@
+export function formatError(err) {
+    console.log("🚀 ~ formatError ~ err:", err);
+    if (err instanceof Error) {
+        return err.message;
+    }
+    if (typeof err === "object" && err !== null) {
+        if ("message" in err) {
+            return String(err.message);
+        }
+        // Format Record<string, string> errors
+        return JSON.stringify(err, null, 2);
+    }
+    if (typeof err === "string") {
+        return err;
+    }
+    return String(err);
+}
+//# sourceMappingURL=formatError.js.map

package/dist/utils/formatError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatError.js","sourceRoot":"","sources":["../../src/utils/formatError.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,WAAW,CAAC,GAAY;IACpC,OAAO,CAAC,GAAG,CAAC,yBAAyB,EAAE,GAAG,CAAC,CAAC;IAC5C,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC,OAAO,CAAC;IACvB,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC1C,IAAI,SAAS,IAAI,GAAG,EAAE,CAAC;YACnB,OAAO,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC;QACD,uCAAuC;QACvC,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO,GAAG,CAAC;IACf,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACvB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "heliumts",
-    "version": "0.2.4",
+    "version": "0.2.6",
     "description": "A lightweight full-stack React framework with file-based routing, RPC, and SSG support",
     "keywords": [
         "react",
@@ -15,11 +15,11 @@
     "license": "MIT",
     "repository": {
         "type": "git",
-        "url": "https://github.com/heliobentes/heliumjs.git"
+        "url": "https://github.com/heliobentes/heliumts.git"
     },
-    "homepage": "https://heliumjs.com",
+    "homepage": "https://heliumts.com",
     "bugs": {
-        "url": "https://github.com/heliobentes/heliumjs/issues"
+        "url": "https://github.com/heliobentes/heliumts/issues"
     },
     "bin": {
         "helium": "dist/bin/helium.js"