fix(docs): Update README with routing examples and utility server config; bump @cloudflare/workers-types and @push.rocks/smartserve versions

2025-12-05 21:30:36 +00:00
parent 980ccfe949
commit f8b4c355d5
5 changed files with 188 additions and 40 deletions
--- a/readme.md
+++ b/readme.md
@@ -1,6 +1,6 @@
 # @api.global/typedserver

-A TypeScript-first web server framework for building modern full-stack applications. Features static file serving, live reload, type-safe API integration, service worker support, and edge computing capabilities. Part of the `@api.global` ecosystem.
+A powerful TypeScript-first web server framework for building modern full-stack applications. Features static file serving, live reload, type-safe API integration, decorator-based routing, service worker support, and edge computing capabilities. Part of the `@api.global` ecosystem.

 ## Issue Reporting and Security

@@ -9,13 +9,14 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 ## ✨ Features

 - 🔒 **Type-Safe API** - Full TypeScript support with `@api.global/typedrequest` and `@api.global/typedsocket`
- 🛡️ **Security Headers** - Built-in CSP, HSTS, X-Frame-Options, and more
+- 🎯 **Decorator Routing** - Clean, expressive routing with `@Route`, `@Get`, `@Post` decorators via smartserve
+- 🛡️ **Security Headers** - Built-in CSP, HSTS, X-Frame-Options, and comprehensive security configuration
 - ⚡ **Live Reload** - Automatic browser refresh on file changes during development
 - 🛠️ **Service Worker** - Advanced caching, offline support, and background sync
 - ☁️ **Edge Workers** - Cloudflare Workers compatible edge computing with domain routing
 - 📡 **WebSocket** - Real-time bidirectional communication via TypedSocket
 - 🗺️ **SEO Tools** - Built-in sitemap, RSS feed, and robots.txt generation
- 🎯 **SPA Support** - Single-page application fallback routing (default in UtilityWebsiteServer)
+- 🎯 **SPA Support** - Single-page application fallback routing
 - 📱 **PWA Ready** - Web App Manifest generation for progressive web apps

 ## 📦 Installation
@@ -43,7 +44,7 @@ const server = new TypedServer({
 });

 await server.start();
-console.log('Server running!');
+console.log('Server running on port 3000!');
 ```

 ### Full Configuration
@@ -86,6 +87,85 @@ const server = new TypedServer({
 await server.start();
 ```

+## 🛣️ Routing
+
+TypedServer uses a unified routing system powered by `@push.rocks/smartserve`. You can add routes using decorators or the programmatic API.
+
+### Decorator-Based Routing
+
+Create clean, expressive controllers using decorators:
+
+```typescript
+import * as smartserve from '@push.rocks/smartserve';
+
+@smartserve.Route('/api/users')
+class UserController {
+  @smartserve.Get('/')
+  async listUsers(ctx: smartserve.IRequestContext): Promise<Response> {
+    const users = await getUsersFromDb();
+    return new Response(JSON.stringify(users), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  @smartserve.Get('/:id')
+  async getUser(ctx: smartserve.IRequestContext): Promise<Response> {
+    const userId = ctx.params.id;
+    const user = await getUserById(userId);
+    return new Response(JSON.stringify(user), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  @smartserve.Post('/')
+  async createUser(ctx: smartserve.IRequestContext): Promise<Response> {
+    const userData = ctx.body;
+    const newUser = await createUserInDb(userData);
+    return new Response(JSON.stringify(newUser), {
+      status: 201,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+}
+
+// Register the controller
+smartserve.ControllerRegistry.registerInstance(new UserController());
+```
+
+### Programmatic Routes with `addRoute()`
+
+Add routes dynamically using the `addRoute()` API:
+
+```typescript
+import { TypedServer } from '@api.global/typedserver';
+
+const server = new TypedServer({ serveDir: './public', cors: true });
+
+// Simple route
+server.addRoute('/api/health', 'GET', async (request) => {
+  return new Response(JSON.stringify({ status: 'ok' }), {
+    headers: { 'Content-Type': 'application/json' },
+  });
+});
+
+// Route with parameters (Express-style :param syntax)
+server.addRoute('/api/items/:id', 'GET', async (request) => {
+  const itemId = (request as any).params.id;
+  return new Response(JSON.stringify({ id: itemId }), {
+    headers: { 'Content-Type': 'application/json' },
+  });
+});
+
+// Wildcard routes
+server.addRoute('/files/*path', 'GET', async (request) => {
+  const filePath = (request as any).params.path;
+  // Handle file serving logic
+  return new Response(`Requested: ${filePath}`);
+});
+
+await server.start();
+```
+
 ## 🔌 Type-Safe API Integration

 ### Adding TypedRequest Handlers
@@ -139,20 +219,22 @@ server.typedrouter.addTypedHandler<IChatMessage>(
 await server.start();

 // Push messages to connected clients
-const connections = await server.typedsocket.findAllTargetConnectionsByTag('typedserver_frontend');
+const connections = await server.typedsocket.findAllTargetConnectionsByTag('allClients');
 for (const conn of connections) {
-  // Push to specific clients
+  // Push to specific clients via TypedSocket
 }
 ```

 ## ☁️ Edge Worker (Cloudflare Workers)

+Deploy your application to the edge with Cloudflare Workers:
+
 ```typescript
 import { EdgeWorker, DomainRouter } from '@api.global/typedserver/edgeworker';

 const worker = new EdgeWorker();

-// Configure domain routing
+// Configure domain routing with caching
 worker.domainRouter.addDomainInstruction({
  domainPattern: '*.example.com',
  originUrl: 'https://origin.example.com',
@@ -160,10 +242,11 @@ worker.domainRouter.addDomainInstruction({
  cacheConfig: { maxAge: 3600 },
 });

+// Pass-through to origin for API routes
 worker.domainRouter.addDomainInstruction({
  domainPattern: 'api.example.com',
  originUrl: 'https://api-origin.example.com',
-  type: 'origin',  // Pass through to origin
+  type: 'origin',
 });

 // Cloudflare Worker entry point
@@ -188,6 +271,7 @@ const swClient = await getServiceworkerClient({
 // - Cache invalidation from server
 // - Offline support
 // - Background sync
+// - Version updates
 ```

 ## 🛡️ Security Headers
@@ -250,7 +334,7 @@ await server.start();
 | `Strict-Transport-Security` | `hstsMaxAge`, `hstsIncludeSubDomains`, `hstsPreload` | Forces HTTPS connections |
 | `X-Frame-Options` | `xFrameOptions` | Prevents clickjacking attacks |
 | `X-Content-Type-Options` | `xContentTypeOptions` | Prevents MIME-sniffing |
-| `X-XSS-Protection` | `xXssProtection` | Legacy XSS filter (still useful) |
+| `X-XSS-Protection` | `xXssProtection` | Legacy XSS filter |
 | `Referrer-Policy` | `referrerPolicy` | Controls referrer information |
 | `Permissions-Policy` | `permissionsPolicy` | Controls browser features |
 | `Cross-Origin-Opener-Policy` | `crossOriginOpenerPolicy` | Isolates browsing context |
@@ -281,7 +365,7 @@ await server.start();
 | `defaultAnswer` | `function` | - | Custom default response handler |
 | `feedMetadata` | `object` | - | RSS feed metadata options |
 | `blockWaybackMachine` | `boolean` | `false` | Block Wayback Machine archiving |
-| `securityHeaders` | `ISecurityHeaders` | - | Security headers configuration (CSP, HSTS, etc.) |
+| `securityHeaders` | `ISecurityHeaders` | - | Security headers configuration |

 ## 🏗️ Package Exports

@@ -297,7 +381,7 @@ await server.start();

 ## 🔄 Utility Servers

-Pre-configured server templates with best practices built-in:
+Pre-configured server templates with best practices built-in.

 ### UtilityWebsiteServer

@@ -310,10 +394,10 @@ const websiteServer = new utilityservers.UtilityWebsiteServer({
  serveDir: './dist',
  domain: 'example.com',

-  // SPA fallback enabled by default (serves index.html for client routes)
+  // SPA fallback enabled by default
  spaFallback: true,   // default: true

-  // Optional security headers
+  // Security headers
  securityHeaders: {
    csp: {
      defaultSrc: ["'self'"],
@@ -328,14 +412,34 @@ const websiteServer = new utilityservers.UtilityWebsiteServer({
  cors: true,          // default: true
  forceSsl: false,     // default: false
  appSemVer: '1.0.0',
+  port: 3000,          // default: 3000
+
+  // Optional ads.txt entries (only served if configured)
+  adsTxt: [
+    'google.com, pub-1234567890, DIRECT, f08c47fec0942fa0',
+  ],
+
+  // RSS feed metadata
+  feedMetadata: {
+    title: 'My Blog',
+    description: 'A cool blog',
+    link: 'https://example.com',
+  },
+
+  // Add custom routes
+  addCustomRoutes: async (typedserver) => {
+    typedserver.addRoute('/api/custom', 'GET', async () => {
+      return new Response('Custom route!');
+    });
+  },
 });

-await websiteServer.start();  // Default port 3000
+await websiteServer.start();
 ```

 ### UtilityServiceServer

-Optimized for API services:
+Optimized for API services with auto-generated info page:

 ```typescript
 import { utilityservers } from '@api.global/typedserver';
@@ -345,11 +449,42 @@ const serviceServer = new utilityservers.UtilityServiceServer({
  serviceVersion: '1.0.0',
  serviceDomain: 'api.example.com',
  port: 8080,
+
+  // Add custom routes
+  addCustomRoutes: async (typedserver) => {
+    typedserver.addRoute('/api/status', 'GET', async () => {
+      return new Response(JSON.stringify({ status: 'healthy' }), {
+        headers: { 'Content-Type': 'application/json' },
+      });
+    });
+  },
 });

 await serviceServer.start();
 ```

+## 🧩 Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      TypedServer                            │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
+│  │ SmartServe  │  │ TypedRouter │  │    TypedSocket      │ │
+│  │ (Routing)   │  │ (RPC)       │  │    (WebSocket)      │ │
+│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
+│         │                │                    │             │
+│         ▼                ▼                    ▼             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │              Request Handler Pipeline               │   │
+│  │  1. Controller Registry (Decorated Routes)          │   │
+│  │  2. TypedRequest/TypedSocket handlers               │   │
+│  │  3. Static File Serving                             │   │
+│  │  4. SPA Fallback                                    │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
 ## License and Legal Information

 This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.