@kithinji/orca 1.0.18 → 1.0.19

package/README.md

@@ -26,24 +26,41 @@
 
 ## The Problem
 
-Building modern web apps means maintaining two separate projects: a frontend repo and a backend repo. Two package.jsons. Two deployment pipelines. Two sets of bugs for what should be _one feature_.
+Modern web apps require two separate projects: one for the frontend, one for the backend. This means:
 
-The cognitive overhead is exhausting. You're not just switching files, you're switching mental models. Frontend brain, backend brain. Component lifecycle, request lifecycle. By the time you've wired everything together, you've spent more time _connecting_ things than building them.
+- Two repositories to maintain
+- Two deployment pipelines
+- Two sets of dependencies
+- Manual API contracts that constantly drift
+- Endless context switching between different codebases
 
-**Orca solves this.**
+Building a single feature requires touching multiple repos, keeping types in sync manually, and spending more time wiring things together than actually building.
+
+**Orca solves this by unifying your entire stack in one codebase.**
+
+---
 
 ## What is Orca?
 
-Orca is a full-stack TypeScript framework that lets you build your entire application - API, business logic, and UI - in a single codebase with shared types, unified architecture, and zero artificial boundaries.
+Orca is a full-stack TypeScript framework that lets you build your entire application (API, business logic, and UI) in a single codebase.
+
+Write your backend services, frontend components, and API endpoints together with shared types and zero boilerplate.
+
+### Inspired By
+
+- **NestJS** for backend architecture (dependency injection, decorators, modules)
+- **Angular** for frontend structure (class-based components, clear organization)
+- **Islands Architecture** for optimal performance (server-render by default, hydrate selectively)
 
-Inspired by NestJS and Angular, Orca brings structure and convention to full-stack development using dependency injection, event systems, and a novel approach to client-server separation.
+### How It Works
 
-### The Core Innovation
+Orca uses three simple directives to control where code runs:
 
-Instead of forcing you to choose between server rendering or client interactivity, Orca gives you **both** with two simple directives:
+**1. Default: Server Components**
+
+Components render on the server by default. Fast initial loads, works without JavaScript.
 
 ```tsx
-// Server-rendered by default - fast, works without JavaScript
 @Component()
 export class ProductList {
   constructor(private products: ProductService) {}
@@ -52,7 +69,7 @@ export class ProductList {
     const items = await this.products.getAll();
     return (
       <div>
-        {items.map((item) => (
+        {items.map(item => (
           <ProductCard key={item.id} product={item} />
         ))}
       </div>
@@ -61,15 +78,18 @@ export class ProductList {
 }
 ```
 
+**2. `"use interactive"` for Client Components**
+
+Add this directive when you need client-side interactivity like click handlers, forms, or animations.
+
 ```tsx
-// "use interactive" creates islands of interactivity
 "use interactive";
 import { Component, signal } from "@kithinji/orca";
 
 @Component()
 export class AddToCartButton {
   constructor(private cart: CartService) {}
-
+  
   props!: { productId: number };
   private adding = signal(false);
 
@@ -90,20 +110,23 @@ export class AddToCartButton {
 }
 ```
 
+**3. `"use public"` for Auto-Generated APIs**
+
+Mark services with this directive to automatically create type-safe API endpoints.
+
 ```tsx
-// "use public" creates type-safe API endpoints automatically
 "use public";
 import { Injectable } from "@kithinji/orca";
 
 @Injectable()
 export class CartService {
+  // This becomes: POST /cart/addItem
   public async addItem(productId: number) {
-    // This code runs on the server
-    // But can be called from the client like a local function
     const item = await this.db.products.findUnique({ where: { productId } });
     return this.db.cart.create({ data: { productId, quantity: 1 } });
   }
 
+  // This becomes: GET /cart/getTotal
   public async getTotal() {
     return this.db.cart.aggregate({ _sum: { price: true } });
   }
@@ -112,48 +135,48 @@ export class CartService {
 
 When you call `this.cart.addItem()` from a client component, Orca automatically:
 
-1. Generates a `/CartService/addItem` API endpoint
-2. Validates the input on the server
-3. Executes your server-side logic
-4. Returns the typed response
-
-**You never write `fetch()` calls. The types never drift.**
+1. Generates the `/cart/addItem` endpoint
+2. Serializes your function call into a fetch request
+3. Validates input on the server
+4. Executes your server-side logic
+5. Returns the typed response
 
-## Key Features
+**No manual API calls. No type drift. Just call methods like they're local.**
 
-- **Islands Architecture**: Server-render by default, add interactivity only where needed with `"use interactive"`
-- **Type-Safe APIs**: Mark services with `"use public"` to auto-generate typed API endpoints. No manual fetch calls
-- **Dependency Injection**: Services, controllers, and components work together with clean separation of concerns
-- **Stack-Based Navigation**: Push components onto a navigation stack instead of wrestling with file-based routing
-- **Shared TypeScript Types**: Your types never drift because they're literally the same types across client and server
-- **Decorator-Based APIs**: Express your intent clearly with TypeScript decorators
-- **Built-in Validation**: Request validation using schemas like Zod
-- **Modular Architecture**: Organize code by feature, not by technical layer
+---
 
-## Why Not...?
+## Why Use Orca?
 
-### "Why not separate frontend/backend repos?"
+### Type Safety Across Your Entire Stack
 
-Because maintaining two repos for one app doubles your work. Two sets of types that drift. Two deployment pipelines. Constant context switching between mental models. If you're a solo dev or small team, you're spending more time wiring things together than building features.
+Your types never drift because they're literally the same types. Change a service method's signature and TypeScript catches every call site instantly, whether it's in a server component, client component, or controller.
 
-### "Why not Next.js?"
+### Less Boilerplate, More Features
 
-Next.js is excellent at rendering UI fast. But the moment you try to build a real backend with Server Actions, the lines blur in uncomfortable ways. Validation logic bleeds into components. Database queries live next to UI code. It's optimized for frontend-first development, not full-stack architecture.
+```tsx
+// Traditional approach: Define API route, write fetch call, handle errors
+const response = await fetch('/api/cart/add', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ productId })
+});
+const data = await response.json();
 
-Orca gives you a proper backend with controllers, services, and dependency injection, plus UI rendering that doesn't feel like an afterthought.
+// Orca: Just call the method
+await this.cart.addItem(productId);
+```
 
-### "Why not HTMX?"
+### Islands Architecture for Performance
 
-HTMX is elegant for server-rendered apps. But endpoints that return HTML lock you in. What happens when you need a mobile app? A CLI? A webhook consumer? You either build a second JSON API or parse HTML on the client.
+Server-render everything by default for fast initial loads. Add `"use interactive"` only to components that need client-side JavaScript. Your page stays lightweight while still providing rich interactivity where needed.
 
-Orca's API returns JSON by default. The UI rendering is a layer on top, not a replacement. You're never painted into a corner.
+### Clear Architecture That Scales
 
-## Getting Started
+Dependency injection, decorators, and modules keep your code organized as your application grows. No more tangled mess of utility functions and scattered business logic.
 
-### Prerequisites
+---
 
-- Node.js v20.9 or above
-- A text editor (VS Code recommended)
+## Quick Start
 
 ### Installation
 
@@ -163,7 +186,7 @@ Install the Orca CLI globally:
 npm install -g @kithinji/pod
 ```
 
-### Create Your First Project
+### Create a New Project
 
 ```bash
 pod new my-app
@@ -171,7 +194,14 @@ cd my-app
 npm run dev
 ```
 
-Visit `http://localhost:8080` to see your application running. 🎉
+Open your browser to `http://localhost:8080` to see your app.
+
+### Requirements
+
+- Node.js v20.9 or higher
+- A text editor (VS Code recommended)
+
+---
 
 ## Project Structure
 
@@ -179,31 +209,34 @@ Visit `http://localhost:8080` to see your application running. 🎉
 src/
 ├── features/
 │   ├── user/
-│   │   ├── user.controller.ts          # HTTP endpoints (optional)
-│   │   ├── user.service.ts             # Business logic
-│   │   ├── pages/                      # UI page components
+│   │   ├── user.service.ts          # Business logic
+│   │   ├── user.controller.ts       # HTTP endpoints (optional)
+│   │   ├── pages/
 │   │   │   ├── user-profile.page.tsx
 │   │   │   └── user-login.page.tsx
-│   │   ├── components/                 # UI components
+│   │   ├── components/
 │   │   │   └── avatar.component.tsx
-│   │   └── user.module.ts              # Module definition
+│   │   └── user.module.ts           # Feature module
 │   └── product/
 │       ├── product.service.ts
 │       ├── components/
 │       └── product.module.ts
-└── app.module.ts                 # Root module
+└── app.module.ts                     # Root module
 ```
 
+Organize by feature, not by technical layer. Everything related to "products" lives in the products folder.
+
+---
+
 ## Core Concepts
 
-### 1. Services (Business Logic)
+### Services (Business Logic Layer)
 
-Services contain your application's business logic. They're injectable classes that can be used anywhere in your app.
+Services contain your application logic. They're injectable classes that can be used anywhere.
 
 ```typescript
-// product.service.ts
-"use public"; // Makes this service callable from the client
-import { Injectable, Signature } from "@kithinji/orca";
+"use public";
+import { Injectable, Signature, Observable } from "@kithinji/orca";
 import { z } from "zod";
 
 const GetProductSchema = z.object({ id: z.number() });
@@ -217,7 +250,7 @@ const ProductSchema = z.object({
 export class ProductService {
   constructor(private db: DatabaseService) {}
 
-  @Signature(GetProductSchema, ProductSchema) // used in generating validation logic automatically
+  @Signature(GetProductSchema, ProductSchema)
   public async getProduct(id: number) {
     return this.db.products.findUnique({ where: { id } });
   }
@@ -225,19 +258,23 @@ export class ProductService {
   public async listProducts() {
     return this.db.products.findMany();
   }
+
+  // Type annotate with Observable for Server-Sent Events
+  public stream(): Observable<number> {
+    // Implementation
+  }
 }
 ```
 
-### 2. Components (UI Layer)
+The `@Signature` decorator defines validation schemas. Orca uses these to automatically validate requests.
 
-Components are class-based and return JSX from a `build()` method. They're server-rendered by default.
+### Components (UI Layer)
 
-**Server Component (async data fetching):**
+Components are classes that return JSX from a `build()` method.
 
-```tsx
-// product-list.component.tsx
-import { Component } from "@kithinji/orca";
+**Server Component:**
 
+```tsx
 @Component()
 export class ProductList {
   constructor(private products: ProductService) {}
@@ -248,7 +285,7 @@ export class ProductList {
     return (
       <div>
         <h1>Products</h1>
-        {items.map((item) => (
+        {items.map(item => (
           <div key={item.id}>
             <h3>{item.name}</h3>
             <p>${item.price}</p>
@@ -261,21 +298,27 @@ export class ProductList {
 }
 ```
 
-**Interactive Component (client-side reactivity):**
+**Interactive Component:**
 
 ```tsx
-// add-to-cart-button.component.tsx
 "use interactive";
-import { Component, signal } from "@kithinji/orca";
+import { Component, signal, toSignal } from "@kithinji/orca";
 
 @Component()
 export class AddToCartButton {
-  constructor(private cart: CartService) {}
+  constructor(
+    private cart: CartService,
+    private products: ProductService
+  ) {}
 
   props!: { productId: number };
   private adding = signal(false);
 
   build() {
+    // Streams become EventSource for Server-Sent Events
+    const stream = this.products.stream();
+    const value = toSignal(stream, this);
+
     return (
       <button
         onClick={async () => {
@@ -291,9 +334,9 @@ export class AddToCartButton {
 }
 ```
 
-### 3. Controllers (HTTP Layer)
+### Controllers (HTTP Endpoints)
 
-Controllers handle HTTP requests and define REST endpoints. You can write them manually or let Orca generate them automatically for `"use public"` services.
+Controllers define REST endpoints. You can write them manually or let Orca auto-generate them from `"use public"` services.
 
 **Manual Controller:**
 
@@ -321,45 +364,52 @@ export class ProductController {
 }
 ```
 
-**Auto-Generated Controller:**
+**Auto-Generated:**
 
-When you mark a service with `"use public"`, Orca automatically creates endpoints:
+When you mark a service with `"use public"`, Orca creates endpoints automatically:
 
-- `POST /ProductService/getProduct`
-- `GET /ProductService/listProducts`
+- `POST /product/getProduct`
+- `GET /product/listProducts`
 
-No controller code needed - just mark the service and call methods from your client components.
+No controller code required.
 
-### 4. Modules (Organization)
+### Modules (Organizing Features)
 
-Modules group related functionality together and manage dependencies.
+Modules group related functionality and manage dependencies.
 
 ```typescript
-// product.module.ts
 import { Module } from "@kithinji/orca";
 import { ProductController } from "./product.controller";
 import { ProductService } from "./product.service";
 import { ProductList, AddToCartButton } from "./components";
 
 @Module({
-  imports: [DatabaseModule], // Modules we depend on
-  controllers: [ProductController], // HTTP endpoints
-  providers: [ProductService], // Services
+  imports: [DatabaseModule],              // Dependencies
+  controllers: [ProductController],       // HTTP endpoints
+  providers: [ProductService],            // Services
   declarations: [ProductList, AddToCartButton], // UI components
-  exports: [ProductService, ProductList], // What others can use
+  exports: [ProductService, ProductList]  // What other modules can use
 })
 export class ProductModule {}
 ```
 
-### 5. Navigation (Stack-Based Routing)
+### Navigation (Stack-Based Routing)
 
-Instead of file-based routing, Orca uses a navigation stack. Push components onto the stack to navigate.
+Instead of file-based routing, push components onto a navigation stack.
 
 ```tsx
-import { Navigate } from "@kithinji/orca";
+import { Navigate, Component } from "@kithinji/orca";
 
-@Component()
+@Component({
+  route: "/home/:id?location&browser*",
+})
 export class HomePage {
+  props!: {
+    id: string;
+    location: string;
+    browser?: string;
+  };
+
   constructor(private navigate: Navigate) {}
 
   build() {
@@ -375,21 +425,33 @@ export class HomePage {
 }
 ```
 
-Navigation methods:
+**Navigation Methods:**
 
-- `push()` - Add a new page on top
+- `push()` - Navigate to a new page
 - `pop()` - Go back to previous page
 - `replace()` - Replace current page
 - `popToRoot()` - Clear stack and return to root
 - `canPop()` - Check if back navigation is possible
 
-## The Magic: How It All Works Together
+**Using `<a>` tags:**
+
+You can still use anchor tags, but they're not type-safe:
 
-Here's a complete feature showing the full stack:
+```tsx
+<a href="/home/123?location=nairobi&browser=FireFox">To Home</a>
+```
+
+---
+
+## Complete Example
+
+Here's how everything works together:
 
 ```typescript
 // cart.service.ts
 "use public";
+import { Injectable } from "@kithinji/orca";
+
 @Injectable()
 export class CartService {
   constructor(private db: DatabaseService) {}
@@ -397,7 +459,7 @@ export class CartService {
   public async addItem(productId: number, quantity: number = 1) {
     const product = await this.db.products.findUnique({ where: { productId } });
     return this.db.cart.create({
-      data: { productId, quantity, price: product.price },
+      data: { productId, quantity, price: product.price }
     });
   }
 
@@ -405,8 +467,12 @@ export class CartService {
     return this.db.cart.findMany();
   }
 }
+```
 
+```tsx
 // cart-page.component.tsx
+import { Component } from "@kithinji/orca";
+
 @Component()
 export class CartPage {
   constructor(private cart: CartService) {}
@@ -416,20 +482,26 @@ export class CartPage {
     return (
       <div>
         <h1>Your Cart</h1>
-        {items.map((item) => (
+        {items.map(item => (
           <CartItem key={item.id} item={item} />
         ))}
       </div>
     );
   }
 }
+```
 
+```tsx
 // add-to-cart-button.component.tsx
-("use interactive");
+"use interactive";
+import { Component, Navigate } from "@kithinji/orca";
 
 @Component()
 export class AddToCartButton {
-  constructor(private cart: CartService, private navigate: Navigate) {}
+  constructor(
+    private cart: CartService,
+    private navigate: Navigate
+  ) {}
 
   props!: { productId: number };
 
@@ -448,56 +520,83 @@ export class AddToCartButton {
 }
 ```
 
-**What happens here:**
+**What happens:**
 
-1. `CartService` is marked `"use public"`, so Orca generates API endpoints
-2. `CartPage` (server component) calls `cart.getCart()` on the server during initial render
+1. `CartService` has `"use public"`, so Orca generates API endpoints
+2. `CartPage` (server component) calls `cart.getCart()` on the server during render
 3. `AddToCartButton` (interactive component) calls `cart.addItem()` from the browser
-4. Orca automatically converts that call into `fetch('/CartService/addItem', ...)`
-5. Types are preserved end-to-end; TypeScript catches errors everywhere
-6. Navigation happens by pushing a component, not a URL string
+4. Orca converts that call into `fetch('/cart/addItem', ...)`
+5. Types are preserved everywhere. TypeScript catches errors before runtime
+6. Navigation happens by pushing components, not URL strings
+
+---
+
+## When to Use Orca
+
+**Orca is great for:**
+
+- Solo developers or small teams
+- Building features quickly without managing two repos
+- Internal tools, dashboards, or admin panels
+- Highly interactive web applications
+- Projects where you need a real API (for mobile apps, CLIs, webhooks)
+- Teams tired of keeping types in sync between frontend and backend
+
+**Orca might not fit if:**
+
+- You have separate frontend and backend teams
+- You prefer the traditional split and it works for you
+- You need a purely client-side SPA
+- You're building a static marketing site or blog (use Astro or Next.js)
+- Your team is heavily invested in another stack
+
+---
+
+## Orca vs. Alternatives
+
+### Why not separate repos?
 
-## Is Orca for You?
+Separate repos mean double the maintenance. Two sets of types that drift. Two deployment pipelines. Constant context switching. For solo devs or small teams, you spend more time connecting things than building.
 
-**Orca is great if you:**
+### Why not Next.js?
 
-- Are a solo developer or small team
-- Want to ship features without maintaining two separate projects
-- Value clear architecture and separation of concerns
-- Need a real API that can grow (mobile apps, CLIs, integrations)
-- Are tired of context switching between frontend and backend mental models
-- Build internal tools, dashboards, or admin panels
-- You're building highly interactive web apps
+Next.js excels at rendering UI fast, but it's optimized for frontend-first development. The moment you need a proper backend with controllers, services, and dependency injection, things get messy. Server Actions blur the lines between UI and backend in ways that make larger apps hard to maintain.
 
-**Orca might not be for you if:**
+Orca gives you a real backend architecture with clean separation of concerns, plus UI rendering that integrates naturally.
 
-- You have a large team with dedicated frontend/backend developers
-- You prefer the frontend/backend split and it works for your workflow
-- You need a purely client-side SPA framework
-- You're building a marketing site or content-heavy blog (use Astro or Next.js)
-- Your team is already deeply invested in another stack
+### Why not HTMX?
 
-This isn't a crusade. If the traditional split works for you, keep doing what works. But if you've ever thought "there has to be a simpler way", Orca is that way.
+HTMX is elegant for server-rendered apps. But endpoints that return HTML lock you in. When you need a mobile app, CLI, or webhook consumer, you either build a second JSON API or parse HTML on the client.
+
+Orca's API returns JSON by default. UI rendering is a layer on top, not a replacement. You're never painted into a corner.
+
+---
 
 ## Philosophy
 
-With the rise of React, Vue, and Angular, web development split into two worlds: frontend and backend. For large teams, that makes sense. But for solo devs and small teams, it doubles the work.
+Orca rejects the artificial divide between frontend and backend. For large teams with dedicated specialists, that split makes sense. But for solo developers and small teams, it doubles the work.
 
-Orca rejects the artificial divide. Instead:
+### Core Principles
 
-- **One codebase**: Write features end-to-end in one place
-- **Islands of interactivity**: Server-render by default, add JavaScript only where needed
-- **Type-safe APIs**: No manual fetch calls, no drifting types
-- **Clear architecture**: DI, decorators, and modules keep large apps maintainable
-- **Stack-based navigation**: Route by pushing components, not by folder structure
+**One Codebase** - Write features end to end in one place
 
-This is opinionated software. It has rules, structure, and conventions. That's the point. The rules exist to free you from decision fatigue so you can focus on building.
+**Islands of Interactivity** - Server-render by default, add JavaScript only where needed
+
+**Type-Safe APIs** - No manual fetch calls, no drifting types
+
+**Clear Architecture** - Dependency injection, decorators, and modules keep large apps maintainable
+
+**Stack-Based Navigation** - Route by pushing components, not folder structures
+
+This is opinionated software. It has rules, structure, and conventions. The rules exist to free you from decision fatigue so you can focus on building.
+
+---
 
 ## Documentation
 
-Full guides, API references, and examples at **[orca.dafifi.net](https://orca.dafifi.net/)**
+Full guides, API references, and examples at [**orca.dafifi.net**](https://orca.dafifi.net/)
 
-Topics covered:
+**Topics covered:**
 
 - Components and JSX
 - Dependency Injection
@@ -506,30 +605,38 @@ Topics covered:
 - The `"use interactive"` directive
 - The `"use public"` directive
 - Signals and Reactivity
-- Observables
+- Observables and Server-Sent Events
 - Navigation Stack
 - Validation with Zod
 
+---
+
 ## Roadmap
 
 - [ ] Database integrations (TypeORM, Prisma)
-- [ ] Authentication & authorization modules
+- [ ] Authentication and authorization modules
 - [ ] WebSocket support
 - [ ] GraphQL adapter
 - [ ] CLI scaffolding improvements
 - [ ] File upload handling
-- [ ] Background jobs / task queues
+- [ ] Background jobs and task queues
+
+---
 
 ## Contributing
 
 Contributions are welcome! Please read our contributing guidelines before submitting PRs.
 
-## Stay in Touch
+---
+
+## Stay Connected
 
 - **Author**: [Kithinji Brian](https://www.linkedin.com/in/kithinjibrian/)
 - **Website**: [orca.dafifi.net](https://orca.dafifi.net/)
 - **NPM**: [@kithinji/orca](https://www.npmjs.com/package/@kithinji/orca)
 
+---
+
 ## License
 
 MIT
@@ -538,4 +645,4 @@ MIT
 
 <p align="center">
 Made in Nairobi with ❤️ for developers who just want to ship
-</p>
+</p>