tina4-nodejs 3.10.41 → 3.10.42

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.10.41)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.10.42)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.10.41 — a convention-over-configuration structural paradigm. **Not a framework.** The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.10.42 — a convention-over-configuration structural paradigm. **Not a framework.** The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 

package/README.md

@@ -6,7 +6,7 @@
 <p align="center">54 built-in features. Zero dependencies. One import, everything works.</p>
 <p align="center">
   <a href="https://www.npmjs.com/package/tina4-nodejs"><img src="https://img.shields.io/npm/v/tina4-nodejs?color=7b1fa2&label=npm" alt="npm"></a>
-  <img src="https://img.shields.io/badge/tests-1%2C950%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/tests-1%2C812%20passing-brightgreen" alt="Tests">
   <img src="https://img.shields.io/badge/features-54-blue" alt="Features">
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="Zero Deps">
   <a href="https://tina4.com"><img src="https://img.shields.io/badge/docs-tina4.com-7b1fa2" alt="Docs"></a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.10.41",
+  "version": "3.10.42",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript — 54 built-in features, zero dependencies",
   "keywords": ["tina4", "framework", "web", "api", "orm", "graphql", "websocket", "typescript"],

package/packages/core/src/devAdmin.ts

@@ -2185,6 +2185,15 @@ function drillDownFile(path){
             });
             html+='</div>';
         }
+        if(d.warnings&&d.warnings.length){
+            html+='<h3 style="margin:0.75rem 0 0.25rem;color:#eab308;font-size:0.85rem">&#9888; Warnings</h3>';
+            html+='<div style="display:flex;flex-direction:column;gap:4px">';
+            d.warnings.forEach(function(w){
+                html+='<div style="padding:4px 8px;background:rgba(234,179,8,0.08);border-left:3px solid #eab308;border-radius:0 4px 4px 0;font-size:0.75rem;font-family:var(--mono);color:var(--text)">';
+                html+='<span style="color:#eab308;margin-right:6px">L'+w.line+'</span>'+w.message+'</div>';
+            });
+            html+='</div>';
+        }
         dd.querySelector('.p-md').innerHTML=html;
     }).catch(function(e){
         dd.querySelector('.p-md').innerHTML='<p style="color:var(--danger)">Error: '+e.message+'</p>';

package/packages/core/src/index.ts

@@ -12,7 +12,7 @@ export type {
   WebSocketRouteDefinition,
 } from "./types.js";
 
-export { startServer, resolvePortAndHost } from "./server.js";
+export { startServer, resolvePortAndHost, handle } from "./server.js";
 export { Router, RouteGroup, RouteRef, defaultRouter, runRouteMiddlewares } from "./router.js";
 export { get, post, put, patch, del, any, websocket, del as delete } from "./router.js";
 export type { RouteInfo } from "./router.js";
@@ -94,6 +94,7 @@ export type { ValkeySessionConfig } from "./sessionHandlers/valkeyHandler.js";
 export { RedisNpmSessionHandler } from "./sessionHandlers/redisHandler.js";
 export type { RedisNpmSessionConfig } from "./sessionHandlers/redisHandler.js";
 export { tests, assertEqual, assertThrows, assertTrue, assertFalse, runAllTests, resetTests } from "./testing.js";
+export { TestClient, TestResponse } from "./testClient.js";
 export { Container, container } from "./container.js";
 export { Validator } from "./validator.js";
 export type { ValidationError } from "./validator.js";

package/packages/core/src/metrics.ts

@@ -789,6 +789,18 @@ export function fileDetail(filePath: string): Record<string, any> {
   // Remove file field from function info for single-file detail
   const cleanFunctions = functions.map(({ file, ...rest }) => rest);
 
+  // Detect empty methods/functions (loc <= 1 means only a brace or pass-through)
+  const warnings: { type: string; message: string; line: number }[] = [];
+  for (const fn of cleanFunctions) {
+    if (fn.loc <= 1) {
+      warnings.push({
+        type: "empty_method",
+        message: `Method '${fn.name}' appears to be empty`,
+        line: fn.line,
+      });
+    }
+  }
+
   return {
     path: filePath,
     loc,
@@ -796,5 +808,6 @@ export function fileDetail(filePath: string): Record<string, any> {
     classes,
     functions: cleanFunctions,
     imports,
+    warnings,
   };
 }

package/packages/core/src/server.ts

@@ -1,4 +1,4 @@
-import { createServer } from "node:http";
+import { createServer, IncomingMessage, ServerResponse } from "node:http";
 import { resolve, dirname, join, relative } from "node:path";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { isatty } from "node:tty";
@@ -369,6 +369,20 @@ function deployGallery(name) {
 </html>`;
 }
 
+// Module-level dispatch function — assigned when startServer() is called.
+// Allows handle() to route requests without requiring a reference to the server.
+let _dispatchFn: ((rawReq: IncomingMessage, rawRes: ServerResponse) => Promise<void>) | null = null;
+
+/**
+ * Dispatch a raw Node.js request through the Tina4 router and write the response.
+ * Requires startServer() to have been called first.
+ * Useful for testing and embedding.
+ */
+export async function handle(rawReq: IncomingMessage, rawRes: ServerResponse): Promise<void> {
+  if (!_dispatchFn) throw new Error("Tina4 server not started — call startServer() first");
+  return _dispatchFn(rawReq, rawRes);
+}
+
 export async function startServer(config?: Tina4Config): Promise<{
   close: () => void;
   router: Router;
@@ -578,7 +592,7 @@ ${reset}
     console.log(`  Dev dashboard at  \x1b[36mhttp://localhost:${port}/__dev\x1b[0m`);
   }
 
-  const server = createServer(async (rawReq, rawRes) => {
+  async function dispatch(rawReq: IncomingMessage, rawRes: ServerResponse): Promise<void> {
     const req = createRequest(rawReq);
     const res = createResponse(rawRes);
 
@@ -808,7 +822,12 @@ ${reset}
         }
       }
     }
-  });
+  }
+
+  // Assign to module-level so handle() can dispatch without a server reference
+  _dispatchFn = dispatch;
+
+  const server = createServer(dispatch);
 
   return new Promise((resolvePromise) => {
     server.listen(port, host, () => {

package/packages/core/src/testClient.ts

@@ -0,0 +1,187 @@
+/**
+ * Tina4 Test Client — Test routes without starting a server.
+ *
+ * Usage:
+ *
+ *   import { TestClient } from "@tina4/core";
+ *
+ *   const client = new TestClient(router);
+ *
+ *   const response = await client.get("/api/users");
+ *   assert(response.status === 200);
+ *   assert(response.json().users);
+ *
+ *   const response = await client.post("/api/users", { json: { name: "Alice" } });
+ *   assert(response.status === 201);
+ */
+import { IncomingMessage, ServerResponse } from "node:http";
+import { Socket } from "node:net";
+import { createRequest, parseBody } from "./request.js";
+import { createResponse } from "./response.js";
+import { defaultRouter, type Router } from "./router.js";
+
+export class TestResponse {
+  public readonly status: number;
+  public readonly body: string;
+  public readonly headers: Record<string, string>;
+  public readonly contentType: string;
+
+  constructor(statusCode: number, headers: Record<string, string>, body: string) {
+    this.status = statusCode;
+    this.body = body;
+    this.headers = headers;
+    this.contentType = headers["content-type"] ?? "";
+  }
+
+  /** Parse body as JSON. */
+  json(): unknown {
+    if (!this.body) return null;
+    try {
+      return JSON.parse(this.body);
+    } catch {
+      return null;
+    }
+  }
+
+  /** Return body as a string. */
+  text(): string {
+    return this.body;
+  }
+
+  toString(): string {
+    return `<TestResponse status=${this.status} contentType="${this.contentType}">`;
+  }
+}
+
+interface RequestOptions {
+  json?: Record<string, unknown> | unknown[];
+  body?: string;
+  headers?: Record<string, string>;
+}
+
+export class TestClient {
+  private router: Router;
+
+  constructor(router?: Router) {
+    this.router = router ?? defaultRouter;
+  }
+
+  /** Send a GET request. */
+  async get(path: string, options?: RequestOptions): Promise<TestResponse> {
+    return this._request("GET", path, options);
+  }
+
+  /** Send a POST request. */
+  async post(path: string, options?: RequestOptions): Promise<TestResponse> {
+    return this._request("POST", path, options);
+  }
+
+  /** Send a PUT request. */
+  async put(path: string, options?: RequestOptions): Promise<TestResponse> {
+    return this._request("PUT", path, options);
+  }
+
+  /** Send a PATCH request. */
+  async patch(path: string, options?: RequestOptions): Promise<TestResponse> {
+    return this._request("PATCH", path, options);
+  }
+
+  /** Send a DELETE request. */
+  async delete(path: string, options?: RequestOptions): Promise<TestResponse> {
+    return this._request("DELETE", path, options);
+  }
+
+  /** Build a mock request, match the route, execute the handler. */
+  private async _request(method: string, path: string, options?: RequestOptions): Promise<TestResponse> {
+    const { json, body, headers } = options ?? {};
+
+    // Build raw body
+    let rawBody = "";
+    let contentType = "";
+    if (json !== undefined) {
+      rawBody = JSON.stringify(json);
+      contentType = "application/json";
+    } else if (body !== undefined) {
+      rawBody = body;
+    }
+
+    // Build headers
+    const reqHeaders: Record<string, string> = {};
+    if (headers) {
+      for (const [k, v] of Object.entries(headers)) {
+        reqHeaders[k.toLowerCase()] = v;
+      }
+    }
+    if (contentType && !reqHeaders["content-type"]) {
+      reqHeaders["content-type"] = contentType;
+    }
+    if (rawBody && !reqHeaders["content-length"]) {
+      reqHeaders["content-length"] = String(Buffer.byteLength(rawBody));
+    }
+
+    // Create a mock IncomingMessage
+    const socket = new Socket();
+    const rawReq = new IncomingMessage(socket);
+    rawReq.method = method.toUpperCase();
+    rawReq.url = path;
+    rawReq.headers = { ...reqHeaders, host: "localhost:7145" };
+
+    // Push body data into the readable stream
+    if (rawBody) {
+      rawReq.push(Buffer.from(rawBody));
+    }
+    rawReq.push(null); // signal end of stream
+
+    // Create a mock ServerResponse that captures output
+    const rawRes = new ServerResponse(rawReq);
+    const chunks: Buffer[] = [];
+    const originalWrite = rawRes.write.bind(rawRes);
+    const originalEnd = rawRes.end.bind(rawRes);
+
+    rawRes.write = function (chunk: any, ...args: any[]): boolean {
+      if (chunk) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+      return true;
+    } as typeof rawRes.write;
+
+    rawRes.end = function (chunk?: any, ...args: any[]): ServerResponse {
+      if (chunk) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+      return rawRes;
+    } as typeof rawRes.end;
+
+    // Create Tina4 request/response wrappers
+    const req = createRequest(rawReq);
+    const res = createResponse(rawRes);
+
+    // Parse body (populates req.body)
+    await parseBody(req);
+
+    // Split path for route matching
+    const cleanPath = path.includes("?") ? path.split("?")[0] : path;
+
+    // Match route
+    const match = this.router.match(method.toUpperCase(), cleanPath);
+    if (!match) {
+      return new TestResponse(404, { "content-type": "application/json" }, '{"error":"Not found"}');
+    }
+
+    // Inject route params
+    req.params = match.params;
+
+    // Execute handler
+    await match.handler(req, res);
+
+    // Collect response
+    const responseBody = Buffer.concat(chunks).toString();
+    const responseHeaders: Record<string, string> = {};
+    for (const [name, value] of Object.entries(rawRes.getHeaders())) {
+      if (value !== undefined) {
+        responseHeaders[name] = Array.isArray(value) ? value.join(", ") : String(value);
+      }
+    }
+
+    // Clean up the socket
+    socket.destroy();
+
+    return new TestResponse(rawRes.statusCode, responseHeaders, responseBody);
+  }
+}