@kithinji/orca 1.0.14 → 1.0.16

package/README.md

@@ -0,0 +1,541 @@
+<h1 align="center">Orca</h1>
+<p align="center">
+<img src="https://i.postimg.cc/Wpq8CWvV/orca.png" alt="orca-logo" width="150px"/>
+<br>
+<em>One codebase. One deployment.
+<br> Build full-stack applications without the frontend/backend divide.</em>
+<br>
+</p>
+<p align="center">
+<a href="https://orca.dafifi.net/"><strong>orca.dafifi.net</strong></a>
+<br>
+</p>
+<p align="center">
+<a href="https://www.npmjs.com/package/@kithinji/orca">
+<img src="https://img.shields.io/badge/NPM_package-v1.0.16-blue" alt="Orca on npm" />
+</a>
+</p>
+
+<p align="center">
+<a href="https://github.com/kithinjibrian/pod">
+<img src="https://img.shields.io/badge/POD CLI Tool-blue" alt="Pod on github" />
+</a>
+</p>
+
+<hr>
+
+## 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_.
+
+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.
+
+**Orca solves this.**
+
+## 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.
+
+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.
+
+### The Core Innovation
+
+Instead of forcing you to choose between server rendering or client interactivity, Orca gives you **both** with two simple directives:
+
+```tsx
+// Server-rendered by default - fast, works without JavaScript
+@Component()
+export class ProductList {
+  constructor(private products: ProductService) {}
+
+  async build() {
+    const items = await this.products.getAll();
+    return (
+      <div>
+        {items.map((item) => (
+          <ProductCard key={item.id} product={item} />
+        ))}
+      </div>
+    );
+  }
+}
+```
+
+```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);
+
+  build() {
+    return (
+      <button
+        disabled={this.adding.value}
+        onClick={async () => {
+          this.adding.value = true;
+          await this.cart.addItem(this.props.productId);
+          this.adding.value = false;
+        }}
+      >
+        {this.adding.value ? "Adding..." : "Add to Cart"}
+      </button>
+    );
+  }
+}
+```
+
+```tsx
+// "use public" creates type-safe API endpoints automatically
+"use public";
+import { Injectable } from "@kithinji/orca";
+
+@Injectable()
+export class CartService {
+  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 } });
+  }
+
+  public async getTotal() {
+    return this.db.cart.aggregate({ _sum: { price: true } });
+  }
+}
+```
+
+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.**
+
+## Key Features
+
+- **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 not separate frontend/backend repos?"
+
+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.
+
+### "Why not Next.js?"
+
+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.
+
+Orca gives you a proper backend with controllers, services, and dependency injection, plus UI rendering that doesn't feel like an afterthought.
+
+### "Why not HTMX?"
+
+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.
+
+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.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js v20.9 or above
+- A text editor (VS Code recommended)
+
+### Installation
+
+Install the Orca CLI globally:
+
+```bash
+npm install -g @kithinji/pod
+```
+
+### Create Your First Project
+
+```bash
+pod new my-app
+cd my-app
+npm run dev
+```
+
+Visit `http://localhost:8080` to see your application running. 🎉
+
+## Project Structure
+
+```
+src/
+├── features/
+│   ├── user/
+│   │   ├── user.controller.ts          # HTTP endpoints (optional)
+│   │   ├── user.service.ts             # Business logic
+│   │   ├── pages/                      # UI page components
+│   │   │   ├── user-profile.page.tsx
+│   │   │   └── user-login.page.tsx
+│   │   ├── components/                 # UI components
+│   │   │   └── avatar.component.tsx
+│   │   └── user.module.ts              # Module definition
+│   └── product/
+│       ├── product.service.ts
+│       ├── components/
+│       └── product.module.ts
+└── app.module.ts                 # Root module
+```
+
+## Core Concepts
+
+### 1. Services (Business Logic)
+
+Services contain your application's business logic. They're injectable classes that can be used anywhere in your app.
+
+```typescript
+// product.service.ts
+"use public"; // Makes this service callable from the client
+import { Injectable, Signature } from "@kithinji/orca";
+import { z } from "zod";
+
+const GetProductSchema = z.object({ id: z.number() });
+const ProductSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  price: z.number(),
+});
+
+@Injectable()
+export class ProductService {
+  constructor(private db: DatabaseService) {}
+
+  @Signature(GetProductSchema, ProductSchema) // used in generating validation logic automatically
+  public async getProduct(id: number) {
+    return this.db.products.findUnique({ where: { id } });
+  }
+
+  public async listProducts() {
+    return this.db.products.findMany();
+  }
+}
+```
+
+### 2. Components (UI Layer)
+
+Components are class-based and return JSX from a `build()` method. They're server-rendered by default.
+
+**Server Component (async data fetching):**
+
+```tsx
+// product-list.component.tsx
+import { Component } from "@kithinji/orca";
+
+@Component()
+export class ProductList {
+  constructor(private products: ProductService) {}
+
+  async build() {
+    const items = await this.products.listProducts();
+
+    return (
+      <div>
+        <h1>Products</h1>
+        {items.map((item) => (
+          <div key={item.id}>
+            <h3>{item.name}</h3>
+            <p>${item.price}</p>
+            <AddToCartButton productId={item.id} />
+          </div>
+        ))}
+      </div>
+    );
+  }
+}
+```
+
+**Interactive Component (client-side reactivity):**
+
+```tsx
+// add-to-cart-button.component.tsx
+"use interactive";
+import { Component, signal } from "@kithinji/orca";
+
+@Component()
+export class AddToCartButton {
+  constructor(private cart: CartService) {}
+
+  props!: { productId: number };
+  private adding = signal(false);
+
+  build() {
+    return (
+      <button
+        onClick={async () => {
+          this.adding.value = true;
+          await this.cart.addItem(this.props.productId);
+          this.adding.value = false;
+        }}
+      >
+        {this.adding.value ? "Adding..." : "Add to Cart"}
+      </button>
+    );
+  }
+}
+```
+
+### 3. Controllers (HTTP Layer)
+
+Controllers handle HTTP requests and define REST endpoints. You can write them manually or let Orca generate them automatically for `"use public"` services.
+
+**Manual Controller:**
+
+```typescript
+import { Controller, Get, Post, Body, Param } from "@kithinji/orca";
+
+@Controller("/products")
+export class ProductController {
+  constructor(private products: ProductService) {}
+
+  @Get()
+  async findAll() {
+    return this.products.listProducts();
+  }
+
+  @Get("/:id")
+  async findOne(@Param("id") id: number) {
+    return this.products.getProduct(id);
+  }
+
+  @Post()
+  async create(@Body() data: CreateProductDto) {
+    return this.products.create(data);
+  }
+}
+```
+
+**Auto-Generated Controller:**
+
+When you mark a service with `"use public"`, Orca automatically creates endpoints:
+
+- `POST /ProductService/getProduct`
+- `GET /ProductService/listProducts`
+
+No controller code needed - just mark the service and call methods from your client components.
+
+### 4. Modules (Organization)
+
+Modules group related functionality together 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
+  declarations: [ProductList, AddToCartButton], // UI components
+  exports: [ProductService, ProductList], // What others can use
+})
+export class ProductModule {}
+```
+
+### 5. Navigation (Stack-Based Routing)
+
+Instead of file-based routing, Orca uses a navigation stack. Push components onto the stack to navigate.
+
+```tsx
+import { Navigate } from "@kithinji/orca";
+
+@Component()
+export class HomePage {
+  constructor(private navigate: Navigate) {}
+
+  build() {
+    return (
+      <div>
+        <h1>Welcome</h1>
+        <button onClick={() => this.navigate.push(<UserProfile userId={1} />)}>
+          View Profile
+        </button>
+      </div>
+    );
+  }
+}
+```
+
+Navigation methods:
+
+- `push()` - Add a new page on top
+- `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
+
+Here's a complete feature showing the full stack:
+
+```typescript
+// cart.service.ts
+"use public";
+@Injectable()
+export class CartService {
+  constructor(private db: DatabaseService) {}
+
+  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 },
+    });
+  }
+
+  public async getCart() {
+    return this.db.cart.findMany();
+  }
+}
+
+// cart-page.component.tsx
+@Component()
+export class CartPage {
+  constructor(private cart: CartService) {}
+
+  async build() {
+    const items = await this.cart.getCart();
+    return (
+      <div>
+        <h1>Your Cart</h1>
+        {items.map((item) => (
+          <CartItem key={item.id} item={item} />
+        ))}
+      </div>
+    );
+  }
+}
+
+// add-to-cart-button.component.tsx
+("use interactive");
+
+@Component()
+export class AddToCartButton {
+  constructor(private cart: CartService, private navigate: Navigate) {}
+
+  props!: { productId: number };
+
+  build() {
+    return (
+      <button
+        onClick={async () => {
+          await this.cart.addItem(this.props.productId);
+          this.navigate.push(<CartPage />);
+        }}
+      >
+        Add to Cart
+      </button>
+    );
+  }
+}
+```
+
+**What happens here:**
+
+1. `CartService` is marked `"use public"`, so Orca generates API endpoints
+2. `CartPage` (server component) calls `cart.getCart()` on the server during initial 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
+
+## Is Orca for You?
+
+**Orca is great if you:**
+
+- 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
+
+**Orca might not be for you if:**
+
+- 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
+
+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.
+
+## 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. Instead:
+
+- **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
+
+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.
+
+## Documentation
+
+Full guides, API references, and examples at **[orca.dafifi.net](https://orca.dafifi.net/)**
+
+Topics covered:
+
+- Components and JSX
+- Dependency Injection
+- Modules and Providers
+- Controllers and Routing
+- The `"use interactive"` directive
+- The `"use public"` directive
+- Signals and Reactivity
+- Observables
+- Navigation Stack
+- Validation with Zod
+
+## Roadmap
+
+- [ ] Database integrations (TypeORM, Prisma)
+- [ ] Authentication & authorization modules
+- [ ] WebSocket support
+- [ ] GraphQL adapter
+- [ ] CLI scaffolding improvements
+- [ ] File upload handling
+- [ ] Background jobs / task queues
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.
+
+## Stay in Touch
+
+- **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
+
+---
+
+<p align="center">
+Made in Nairobi with ❤️ for developers who just want to ship
+</p>

package/dist/browser/index.iife.js

@@ -81,10 +81,12 @@ var kithinjiorca = (() => {
     SIGNATURE_METADATA_KEY: () => SIGNATURE_METADATA_KEY,
     Signature: () => Signature,
     assert$: () => assert$,
+    batch: () => batch,
     browser: () => browser_exports,
     collectAllProvidersFromNode: () => collectAllProvidersFromNode,
     computed: () => computed,
     createComponent: () => createComponent,
+    createRoot: () => createRoot,
     effect: () => effect,
     from: () => from,
     getCurrentInjector: () => getCurrentInjector,
@@ -109,7 +111,8 @@ var kithinjiorca = (() => {
     style: () => style,
     symbolValueReplacer: () => symbolValueReplacer,
     symbolValueReviver: () => symbolValueReviver,
-    toSignal: () => toSignal
+    toSignal: () => toSignal,
+    untracked: () => untracked
   });
   var import_reflect_metadata = __require("reflect-metadata");
 
@@ -171,8 +174,10 @@ var kithinjiorca = (() => {
     StringRenderer: () => StringRenderer,
     VNode: () => VNode,
     assert$: () => assert$,
+    batch: () => batch,
     collectAllProvidersFromNode: () => collectAllProvidersFromNode,
     computed: () => computed,
+    createRoot: () => createRoot,
     effect: () => effect,
     from: () => from,
     getCurrentInjector: () => getCurrentInjector,
@@ -194,7 +199,8 @@ var kithinjiorca = (() => {
     store: () => store,
     symbolValueReplacer: () => symbolValueReplacer,
     symbolValueReviver: () => symbolValueReviver,
-    toSignal: () => toSignal
+    toSignal: () => toSignal,
+    untracked: () => untracked
   });
 
   // src/shared/store.ts
@@ -1220,11 +1226,17 @@ var kithinjiorca = (() => {
 
   // src/shared/signal/signal.ts
   var currentEffect = null;
+  var batchDepth = 0;
+  var pendingEffects = /* @__PURE__ */ new Set();
   function signal(initialValue) {
     let value = initialValue;
     const subscribers = /* @__PURE__ */ new Set();
     const notify = () => {
-      subscribers.forEach((sub) => sub());
+      if (batchDepth > 0) {
+        subscribers.forEach((sub) => pendingEffects.add(sub));
+      } else {
+        subscribers.forEach((sub) => sub.execute());
+      }
     };
     return {
       _isSignal: true,
@@ -1232,6 +1244,7 @@ var kithinjiorca = (() => {
       get value() {
         if (currentEffect) {
           subscribers.add(currentEffect);
+          currentEffect.deps.add(subscribers);
         }
         return value;
       },
@@ -1244,29 +1257,98 @@ var kithinjiorca = (() => {
     };
   }
   function effect(fn) {
-    const execute = () => {
-      currentEffect = execute;
+    const deps = /* @__PURE__ */ new Set();
+    let cleanupFn;
+    const runner = () => {
+      runner.execute();
+    };
+    runner.deps = deps;
+    runner.execute = () => {
+      if (cleanupFn) {
+        cleanupFn();
+        cleanupFn = void 0;
+      }
+      deps.forEach((subs) => subs.delete(runner));
+      deps.clear();
+      const prevEffect = currentEffect;
+      currentEffect = runner;
       try {
-        fn();
+        const result = fn();
+        if (typeof result === "function") {
+          cleanupFn = result;
+        }
       } finally {
-        currentEffect = null;
+        currentEffect = prevEffect;
       }
     };
-    execute();
-    return () => {
-      currentEffect = null;
+    runner.cleanup = () => {
+      if (cleanupFn) {
+        cleanupFn();
+        cleanupFn = void 0;
+      }
+      deps.forEach((subs) => subs.delete(runner));
+      deps.clear();
     };
+    runner.cleanupFn = cleanupFn;
+    runner.execute();
+    return () => runner.cleanup();
   }
   function computed(fn) {
     const sig = signal(fn());
-    effect(() => {
+    let cleanup;
+    cleanup = effect(() => {
       sig.value = fn();
     });
+    const originalSignal = sig;
+    const dispose = cleanup;
+    originalSignal.dispose = dispose;
     return sig;
   }
+  function batch(fn) {
+    batchDepth++;
+    try {
+      fn();
+    } finally {
+      batchDepth--;
+      if (batchDepth === 0) {
+        const effects = Array.from(pendingEffects);
+        pendingEffects.clear();
+        effects.forEach((effect2) => effect2.execute());
+      }
+    }
+  }
   function isSignal(value) {
     return value && value._isSignal === true;
   }
+  function createRoot(fn) {
+    const cleanups = [];
+    const dispose = () => {
+      cleanups.forEach((cleanup) => cleanup());
+      cleanups.length = 0;
+    };
+    const prevEffect = currentEffect;
+    const originalEffect = effect;
+    globalThis.effect = (fn2) => {
+      const cleanup = originalEffect(fn2);
+      cleanups.push(cleanup);
+      return cleanup;
+    };
+    try {
+      return fn(dispose);
+    } finally {
+      globalThis.effect = originalEffect;
+      currentEffect = prevEffect;
+    }
+  }
+  function untracked(fn) {
+    const prevEffect = currentEffect;
+    currentEffect = null;
+    try {
+      return fn();
+    } finally {
+      currentEffect = prevEffect;
+    }
+  }
 
   // src/shared/observable/observable.ts
   var Observable = class {