Pondoknusa

v6.0.0 — TypeScript-native full-stack web framework (service container, routing, middleware, Eloquent ORM, queues, auth, post-quantum crypto, AI inference & RAG, native WebSockets, TSX views, and a first-class CLI) on standard Web APIs.

Source · npm · Docs · Guide · Package Reference

Requires Node.js ≥ 26 (native SQLite node:sqlite, WebSocket server/client framing, and OpenSSL post-quantum crypto with no JavaScript fallbacks). Bun is also supported as a runtime.

---

Highlights

• Lean by default — Zero third-party dependencies required out of the box. Default scaffold uses SQLite (node:sqlite), database queues, log mail, and native WebSockets with zero external daemons.
• AI-Native & MCP — Built-in LLM inference (@pondoknusa/inference) supporting 26+ providers over standard fetch with zero SDK dependencies, vector embeddings & search (@pondoknusa/vector), RAG pipelines (@pondoknusa/rag), and Model Context Protocol agent server (@pondoknusa/mcp).
• Post-Quantum Cryptography — Native ML-KEM, ML-DSA, SLH-DSA, and hybrid X25519 + ML-KEM-768 encryption via Node 26+ OpenSSL (@pondoknusa/crypto), with encrypted sessions and quantum-safe OAuth tokens.
• Cold-Start Optimized (v4.0) — Bundled module config caching (storage/framework/config.mjs), pondoknusa build --full single-file serverless bundles, lazy middleware compilation, and instant pool warming.
• Full-Stack Ergonomics — IoC container, Eloquent ORM with relationships and migrations, TSX views with islands and streaming SSR, typed jobs, domain events, and fluent collections — all in TypeScript.
• Enterprise Auth — Session guard, hashed API tokens, multi-provider social OAuth (PKCE), OAuth2 authorization server (@pondoknusa/auth-oauth), WebAuthn / Passkeys (@pondoknusa/auth-passkey), and role/policy gates.

---

Lean by default

A vanilla pondoknusa new app is almost entirely @pondoknusa/* packages. The default scaffold uses SQLite (no extra driver), database queues, and log mail — no Redis, no cloud SDKs, no external socket servers.

When you need external infrastructure, install only the specific driver package:

Purpose	Optional driver package	Peer dependency	Third-party npm dependency
PostgreSQL	@pondoknusa/database-pg	@pondoknusa/database	pg
MySQL	@pondoknusa/database-mysql	@pondoknusa/database	mysql2
Cloudflare D1	@pondoknusa/database-d1	@pondoknusa/database	— (REST API or Workers binding)
SQL Server	@pondoknusa/database-mssql	@pondoknusa/database	mssql
Oracle DB	@pondoknusa/database-oracle	@pondoknusa/database	oracledb
Redis (cache/queue/broadcast)	@pondoknusa/redis-node	@pondoknusa/redis	redis
Memcached	@pondoknusa/cache-memcached	@pondoknusa/cache	memcached
Upstash Redis	@pondoknusa/cache-upstash	@pondoknusa/cache	@upstash/redis
DynamoDB Cache	@pondoknusa/cache-dynamodb	@pondoknusa/cache	@aws-sdk/client-dynamodb
AWS S3 Storage	@pondoknusa/storage-aws-s3	@pondoknusa/storage	@aws-sdk/client-s3, @aws-sdk/s3-request-presigner
Cloudflare R2 Storage	@pondoknusa/storage-r2	@pondoknusa/storage	@aws-sdk/client-s3, @aws-sdk/s3-request-presigner
Supabase Storage	@pondoknusa/storage-supabase	@pondoknusa/storage	@supabase/storage-js
Postmark Mail	@pondoknusa/mail-postmark	@pondoknusa/mail	— (HTTP API over fetch)
Resend Mail	@pondoknusa/mail-resend	@pondoknusa/mail	— (HTTP API over fetch)
Amazon SES Mail	@pondoknusa/mail-ses	@pondoknusa/mail	@aws-sdk/client-sesv2
SendGrid Mail	@pondoknusa/mail-sendgrid	@pondoknusa/mail	— (HTTP API over fetch)
Mailgun Mail	@pondoknusa/mail-mailgun	@pondoknusa/mail	— (HTTP API over fetch)
OpenAI SDK Inference	@pondoknusa/inference-openai	@pondoknusa/inference	openai
Anthropic SDK Inference	@pondoknusa/inference-anthropic	@pondoknusa/inference	@anthropic-ai/sdk
pgvector Vector Store	@pondoknusa/vector-pg	@pondoknusa/database	— (uses the app's PostgreSQL connection)
Pinecone Vector Store	@pondoknusa/vector-pinecone	@pondoknusa/database	— (REST API over fetch)
Qdrant Vector Store	@pondoknusa/vector-qdrant	@pondoknusa/database	— (REST API over fetch)

Broadcasting uses a native WebSocket hub (@pondoknusa/broadcasting-websocket) and browser WebSocket via @pondoknusa/echo — zero third-party client dependencies. AI inference in @pondoknusa/inference supports 26+ vendors natively over standard fetch without vendor SDKs.

---

API stability

Published @pondoknusa/* packages follow the semver and deprecation rules in STABILITY.md. All 63 packages share a synchronized version number and release together.

• 6.0.0 — Oxc TSX dialect (<Raw html> , island pn-* markers, host events are compile errors), RFC 9457 JSON errors, agent-ready HTTP. See Upgrading to 6.0.
• 5.0.0 — .tyr templates removed. Views are TSX (.tsx). See Upgrading to 5.0.
• Upgrading to 4.0 — Cold-start bundled module config cache, pondoknusa build --full, view cache enforcement, lazy middleware compilation.
• Upgrading to 3.0 — Security hardening release (mass assignment protection, session integrity, OAuth/PKCE lockdown).
• Upgrading to 2.0 — Rebrand from Tyravel to Pondoknusa (@tyravel/* → @pondoknusa/*).
• Upgrading to 1.0 — Initial semver-strict release and async API sweep.

---

Packages directory

The Pondoknusa monorepo is structured into focused, modular packages:

Core & Architecture

Package	Description
@pondoknusa/core	Application kernel, HTTP kernel, service providers, exception handlers, and facades (Route, DB, Auth, Cache, Queue, Events, Log, Mail, Notifications, Storage, View, Gate, Password)
@pondoknusa/container	High-performance IoC service container with singletons, aliases, and callable auto-injection
@pondoknusa/config	Typed configuration loading, .env management, dotted-key ConfigRepository, and schema validation
@pondoknusa/support	String helpers (Str.slug, camel, snake, studly, kebab, random), Stringable, Pipeline, global helpers (collect, now, retry), and utilities
@pondoknusa/collection	Fluent, chainable, immutable collection pipeline (collect(), where*, map, groupBy, sortBy, chunk, pipe)
@pondoknusa/events	Typed domain events, listeners, queued listeners (QueuedListener), and event subscribers (EventSubscriber)
@pondoknusa/locale	Localization, translation dictionaries, pluralization, and string interpolation
@pondoknusa/log	Structured logging channels (stdout, file, stack), JSON-line entries with context redaction, and Log facade

HTTP, Routing & API

Package	Description
@pondoknusa/http	Expressive router, group prefixes/middleware, request/response helpers, JSON fast-path, signed URLs, and JsonResource API transformations
@pondoknusa/validation	Request validation engine with pipe rules (`required
@pondoknusa/graphql	Zero-dependency GraphQL server with programmatic schema definitions, query execution, and operation caching
@pondoknusa/lint	Static and request-level linter for Pondoknusa applications (route diagnostics, auth policies, CSRF exemptions)
@pondoknusa/debug	Request timeline profiler, database query inspector, debug bar UI, and CLI timeline watcher
@pondoknusa/admin	Instant auto-generated CRUD admin panel for Eloquent models

Database & ORM

Package	Description
@pondoknusa/database	Eloquent ORM, fluent query builder, schema builder, migrations, model relations, scopes, casts, factories, seeders, soft deletes, prunable models, and pagination
@pondoknusa/database-pg	PostgreSQL driver with connection pooling and prepared statements
@pondoknusa/database-mysql	MySQL / MariaDB driver (mysql2)
@pondoknusa/database-d1	Cloudflare D1 driver with read-after-write consistency handling
@pondoknusa/database-mssql	Microsoft SQL Server driver (mssql)
@pondoknusa/database-oracle	Oracle Database driver (oracledb)

Auth & Security

Package	Description
@pondoknusa/auth	Session guards, hashed API tokens (tyr_*), CSRF protection, Gate / policy authorization, password reset workflows, and social OAuth with PKCE
@pondoknusa/auth-oauth	Complete OAuth2 authorization server (authorization code + PKCE, client credentials, refresh tokens)
@pondoknusa/auth-passkey	WebAuthn / Passkeys authentication (ES256, zero external dependencies, browser mount + server verification)
@pondoknusa/crypto	Post-quantum cryptography (ML-KEM, ML-DSA, SLH-DSA, hybrid X25519+ML-KEM-768), encrypted database sessions, and signed tokens

Queues, Cache, Storage & Comms

Package	Description
@pondoknusa/queue	Asynchronous job dispatching, database & redis queue drivers, retry logic, failed jobs management, and background worker daemon
@pondoknusa/cache	Unified cache repository with taggable stores (Cache.tags()), stampede protection (remember()), file/array/redis drivers
@pondoknusa/cache-dynamodb	AWS DynamoDB cache store driver
@pondoknusa/cache-memcached	Memcached store driver
@pondoknusa/cache-upstash	Upstash serverless Redis REST cache driver
@pondoknusa/redis	Redis connection manager and connection pooling
@pondoknusa/redis-node	node-redis client adapter
@pondoknusa/mail	Mail manager, mailable classes (Mailable), queued emails, log/array transports, and SMTP driver
@pondoknusa/mail-postmark	Postmark HTTP mail driver
@pondoknusa/mail-resend	Resend HTTP mail driver
@pondoknusa/mail-ses	Amazon SES v2 mail driver
@pondoknusa/mail-sendgrid	SendGrid HTTP mail driver
@pondoknusa/mail-mailgun	Mailgun HTTP mail driver
@pondoknusa/notifications	Multi-channel notifications (mail, database, Slack, SMS, webhooks), queued notifications, notification digest/batching
@pondoknusa/storage	Filesystem abstraction with public/private disks, streaming uploads, URL generation, and local disk driver
@pondoknusa/storage-aws-s3	AWS S3 storage driver with presigned URLs
@pondoknusa/storage-r2	Cloudflare R2 storage driver
@pondoknusa/storage-supabase	Supabase Storage adapter

Real-Time & Views

Package	Description
@pondoknusa/views	TSX/JSX view engine: typed props, layouts, components, compile cache, and worker preloading
@pondoknusa/ssr	Client-side hydration runtime for islands with streaming SSR shell flushing
@pondoknusa/reusable-components	Prebuilt, accessible TSX UI components (buttons, modals, forms, dropdowns)
@pondoknusa/broadcasting	Event broadcasting contracts, private/presence channel authorization, and Echo integration
@pondoknusa/broadcasting-websocket	Built-in zero-dependency WebSocket server hub and Redis broadcast fan-out
@pondoknusa/echo	Lightweight browser client for real-time channels using native WebSockets

AI, Vector, RAG & Agents

Package	Description
@pondoknusa/inference	Provider-agnostic LLM interface (chat, streaming, embeddings) with 26+ built-in presets over standard fetch without vendor SDKs
@pondoknusa/inference-openai	OpenAI official SDK inference adapter
@pondoknusa/inference-anthropic	Anthropic official SDK inference adapter
@pondoknusa/vector	Embedding storage, vector collections, and similarity search contracts
@pondoknusa/vector-pg	PostgreSQL pgvector vector store driver
@pondoknusa/vector-pinecone	Pinecone serverless vector database driver
@pondoknusa/vector-qdrant	Qdrant vector database driver
@pondoknusa/rag	RAG document chunking, metadata extraction, vector ingestion pipelines, and retrieval helpers
@pondoknusa/mcp	Model Context Protocol (MCP) server, capability manifest, and pondoknusa.primer for coding agents

CLI, Testing, REPL & Integrations

Package	Description
create-pondoknusa	Interactive project initializer (npm create pondoknusa@latest)
@pondoknusa/cli	First-class CLI (pondoknusa) for development, code scaffolding, database migrations, queue workers, and production bundling
@pondoknusa/repl	Interactive terminal shell (pondoknusa shell) with pre-wired models, facades, and history
@pondoknusa/testing	Feature test suite on Vitest, TestCase, HttpTestClient, container fakes (mailFake, notificationFake, broadcastFake), and time travel
@pondoknusa/telegram	Telegram Bot API integration, webhooks, long-polling, and notification channel
@pondoknusa/telegram-2fa	Two-factor authentication via Telegram bot verification

---

Quick start

1. Create a new project

npm create pondoknusa@latest my-app

The scaffolding experience is create-and-breathe:

• Generates a secure APP_KEY in .env
• Prepares storage/ directory structure
• Installs dependencies
• Wires authentication, sessions, and SQLite database
• Runs initial database migrations
• Installs Cursor / Claude MCP rules and AGENTS.md
• Initializes a git repository

cd my-app
pondoknusa dev

Visit http://127.0.0.1:3000.

Scaffolding flags

npm create pondoknusa@latest my-api -- --headless      # Headless JSON API without view layer
npm create pondoknusa@latest my-ai-app -- --ai         # AI-ready app with inference & vector routes
npm create pondoknusa@latest my-app -- --no-auth       # Skip auth scaffolding
npm create pondoknusa@latest my-app -- --no-git        # Skip git init
npm create pondoknusa@latest my-app -- --no-mcp        # Skip MCP agent configuration

Monorepo example apps

The repository includes runnable examples in examples/:

• examples/hello-world — Complete full-stack web application with auth, TSX views, queues, and deploy configurations.
• examples/headless-api — Pure REST API with token authentication, database queues, and OpenAPI generation.
• examples/rag — Document ingestion, vector embedding, similarity search, and SSE streaming RAG responses.
• examples/saas-starter — Auth, dashboard stub, queues, and deploy manifests (--template=saas).

cd examples/hello-world
npm install
pondoknusa serve

---

CLI reference

# Project & Server
pondoknusa new <name> [--path=<dir>]    # Create-and-breathe scaffold (+ MCP)
pondoknusa key:generate [--force]       # Generate or rotate APP_KEY in .env
pondoknusa dev                          # Start dev server with hot reload
pondoknusa serve [--port=3000] [--host] # Start the development server
pondoknusa start [--cluster] [--workers=n] # Start the production server (cluster mode)
pondoknusa build [--full] [--minify]    # Build production bundle (full inlines app + config)
pondoknusa shell                        # Interactive REPL with auto-imported facades and models
pondoknusa doctor [--perf] [--url=<url>]# Diagnostic health check (env, storage, db, redis, routes)
pondoknusa deploy:check                 # Pre-deployment validation checklist
pondoknusa app:lint                     # Static and runtime application audit
pondoknusa test [--perf]                # Run Vitest test suite with performance budgets
pondoknusa version                      # Output framework and CLI version

# Code Generators (Scaffolding)
pondoknusa make:controller <Name>       # Create src/controllers/<Name>Controller.ts (--api)
pondoknusa make:request <Name>          # Create src/requests/<Name>Request.ts
pondoknusa make:resource <Name>         # Create src/resources/<Name>Resource.ts
pondoknusa make:model <Name>            # Create src/models/<Name>.ts
pondoknusa make:migration <name>        # Create database/migrations/<timestamp>_<name>.ts
pondoknusa make:factory <Model>         # Create database/factories/<model>-factory.ts
pondoknusa make:seeder <Name>           # Create database/seeders/<name>-seeder.ts
pondoknusa make:provider <Name>         # Create src/providers/<Name>ServiceProvider.ts
pondoknusa make:middleware <Name>       # Create src/middleware/<name>.ts
pondoknusa make:command <Name>          # Create src/commands/<name>-command.ts
pondoknusa make:job <Name>              # Create src/jobs/<Name>.ts
pondoknusa make:event <Name>            # Create src/events/<Name>.ts
pondoknusa make:listener <Name>         # Create src/listeners/<Name>.ts
pondoknusa make:subscriber <Name>       # Create src/subscribers/<Name>.ts
pondoknusa make:view <name>             # Create resources/views/<name>.tsx
pondoknusa make:component <name>        # Create resources/views/components/<name>.tsx
pondoknusa make:island <name>           # Scaffold island view + client mount entrypoint
pondoknusa make:social-driver <name>    # Scaffold custom OAuth2 social driver
pondoknusa make:test <Name>             # Create tests/feature/<name>.test.ts
pondoknusa make:openapi                 # Generate storage/api/openapi.json schema
pondoknusa make:tool <Name>             # Create agent MCP tool definition
pondoknusa make:rag-resource <Name>     # Create RAG ingestion and retrieval resource

# Database & Migrations
pondoknusa migrate                      # Run pending database migrations
pondoknusa db:seed [--class=Seeder]     # Execute database seeders
pondoknusa model:prune                  # Prune models marked with Prunable

# Queues & Scheduled Tasks
pondoknusa queue:table                  # Create migration for database jobs table
pondoknusa queue:failed-table           # Create migration for failed_jobs table
pondoknusa queue:work [--queue=default] # Run background queue worker daemon
pondoknusa queue:failed                 # List all failed queue jobs
pondoknusa queue:retry <id>             # Retry a failed queue job by id
pondoknusa schedule:run                 # Execute scheduled console tasks and cron jobs

# Caching & Optimization
pondoknusa config:cache                 # Bundle config/* into storage/framework/config.mjs
pondoknusa config:clear                 # Clear cached configuration bundle
pondoknusa route:list [--json]          # Display registered routes table
pondoknusa route:cache                  # Pre-compile and serialize routing table
pondoknusa route:clear                  # Clear compiled route cache
pondoknusa view:cache                   # Pre-compile all .tsx view templates
pondoknusa view:clear                   # Clear compiled view cache directory
pondoknusa view:lint [--strict]         # Validate TSX views
pondoknusa view:types                   # Generate TypeScript types for view component props
pondoknusa view:catalog [--json]        # Inspect discovered templates and islands
pondoknusa view:watch                   # Watch TSX views and recompile on change

# Auth, Security & Passkeys
pondoknusa auth:install                 # Scaffold session auth (User model, routes, migrations)
pondoknusa oauth:install                # Scaffold OAuth2 authorization server
pondoknusa oauth:client:create <name>   # Register a new OAuth2 client application
pondoknusa session:prune                # Prune expired session rows
pondoknusa crypto:install               # Scaffold config/crypto.ts
pondoknusa crypto:generate-keys         # Generate post-quantum keypairs (ML-KEM / ML-DSA)

# AI, Vector & MCP
pondoknusa vector:install               # Create a migration enabling the pgvector extension
pondoknusa vector:embed --model=<Name>  # Queue embedding jobs for records missing embeddings
pondoknusa mcp:install [--force]        # Configure Cursor MCP, rules, and AGENTS.md
pondoknusa mcp:serve                    # Start stdio MCP server for AI coding agents
pondoknusa mcp:export-rules             # Export agent rule definitions

# Debug & Telemetry
pondoknusa debug:install                # Scaffold debug bar and authenticated /__debug routes
pondoknusa debug:watch [--once]         # Stream live request timeline events to console
pondoknusa debug:clear                  # Purge persisted debug entries

# Localization & Notifications
pondoknusa lang:publish                 # Publish default translation files to lang/
pondoknusa lang:missing                 # Detect untranslated localization keys
pondoknusa notification:failed          # List failed notification deliveries
pondoknusa notification:retry <id>      # Re-dispatch failed notifications
pondoknusa admin:install                # Scaffold auto-generated CRUD admin panel

---

Application structure

my-app/
├── pondoknusa.json           # Application entry and serve configuration
├── package.json
├── .env                      # Environment variables
├── config/                   # Typed application configuration
│   ├── app.ts
│   ├── auth.ts
│   ├── database.ts
│   ├── queue.ts
│   ├── cache.ts
│   ├── inference.ts          # AI providers & presets
│   ├── crypto.ts             # Post-quantum keys & session encryption
│   └── views.ts
├── database/
│   ├── migrations/           # Fluent schema migrations
│   ├── seeders/              # Database seeders
│   └── factories/            # Model factories
├── resources/
│   ├── views/                # TSX views
│   │   ├── layouts/
│   │   ├── components/
│   │   └── islands/
│   └── client/
│       └── islands/          # Island hydration mounts
└── src/
    ├── main.ts               # Application entrypoint and provider registration
    ├── controllers/          # HTTP controllers
    ├── requests/             # Form validation requests
    ├── resources/            # JSON API resource transformers
    ├── models/               # Eloquent ORM models
    ├── jobs/                 # Queueable async jobs
    ├── events/               # Domain events
    ├── listeners/            # Event listeners (sync or queued)
    ├── providers/            # Service providers
    └── routes/
        ├── web.ts            # Web routes with session/CSRF
        └── api.ts            # API routes with bearer token / OAuth

---

Framework features & code tour

Routing & Controllers

Pondoknusa provides an expressive router with group prefixing, middleware aliases, named routes, route model binding, and signed URLs:

import { Route } from '@pondoknusa/core';
import { Response } from '@pondoknusa/http';
import { UserController } from '../controllers/user-controller.js';
import { StoreUserRequest } from '../requests/store-user-request.js';

// Basic route
Route.get('/', (request) => Response.json({ message: 'Welcome to Pondoknusa', path: request.path }));

// Route groups with middleware and prefixes
Route.prefix('api/v1')
  .middleware('auth:api')
  .group(() => {
    Route.get('/users', [UserController, 'index']).name('users.index');
    Route.post('/users', [UserController, 'store', StoreUserRequest]).name('users.store');
    
    // Implicit Route Model Binding
    Route.get('/users/{user}', [UserController, 'show']).name('users.show');
  });

// Signed URL generation
const signedUrl = Route.signed('verify.email', { user: 1 }, { expiresIn: 3600 });

Controllers resolve through the IoC container, automatically injecting typed dependencies into constructors.

---

Form requests & validation

Form requests encapsulate validation rules and authorization gates:

import { FormRequest } from '@pondoknusa/core';
import { User } from '../models/user.js';

export class StoreUserRequest extends FormRequest<{ name: string; email: string; role: string }> {
  async authorize(): Promise<boolean> {
    return this.authorizePolicy('create', User);
  }

  rules() {
    return {
      name: ['required', 'string', 'min_length:2'],
      email: ['required', 'email', 'unique:users,email'],
      role: ['required', 'in:admin,editor,member'],
    };
  }
}

When validation fails, Pondoknusa automatically returns an HTTP 422 JSON response with structured error messages.

---

API resources (JsonResource)

Transform models and paginated collections into consistent API payloads:

import { JsonResource } from '@pondoknusa/http';
import type { PondoknusaRequest } from '@pondoknusa/http';
import { User } from '../models/user.js';

export class UserResource extends JsonResource<User> {
  toArray(_request?: PondoknusaRequest) {
    return {
      id: this.resource.getAttribute('id'),
      name: this.resource.getAttribute('name'),
      email: this.resource.getAttribute('email'),
      created_at: this.resource.getAttribute('created_at'),
    };
  }
}

// In controller:
return UserResource.make(user);                        // Wrapped in { data: ... }
return UserResource.collection(users);                 // Collection
return UserResource.collection(await User.paginate()); // Paginated collection with meta & links

---

Eloquent-style ORM & Database

Typed models, active record pattern, relationships, query scopes, casts, and migrations:

import { Model } from '@pondoknusa/database';
import type { ModelQueryBuilder } from '@pondoknusa/database';
import { Post } from './post.js';

export interface UserAttributes {
  id: number;
  name: string;
  email: string;
  active: boolean;
  settings: Record<string, unknown>;
}

export class User extends Model<UserAttributes> {
  static override table = 'users';
  static override casts = {
    active: 'boolean',
    settings: 'json',
  };

  // Query Scope
  static scopeActive(builder: ModelQueryBuilder): ModelQueryBuilder {
    return builder.where('active', true);
  }

  // Relations
  posts() {
    return this.hasMany(Post, 'user_id');
  }
}

// Queries
const users = await User.scope('active').orderBy('created_at', 'desc').getModels();
const user = await User.find(1);
const posts = await user.posts().get();
const newPost = await user.posts().create({ title: 'Hello World', body: '...' });

// Pagination
const page = await User.query().paginate(15, 1);

Migrations

import { Schema } from '@pondoknusa/database';

export async function up(schema: Schema): Promise<void> {
  await schema.create('users', (table) => {
    table.id();
    table.string('name');
    table.string('email').unique();
    table.boolean('active').default(true);
    table.json('settings').nullable();
    table.timestamps();
  });
}

---

Fluent Collections (@pondoknusa/collection)

Performant, immutable, and type-safe data pipelines:

import { collect } from '@pondoknusa/collection';

const staff = collect([
  { id: 1, name: 'Ada Lovelace', role: 'admin', points: 120 },
  { id: 2, name: 'Grace Hopper', role: 'editor', points: 95 },
  { id: 3, name: 'Alan Turing', role: 'admin', points: 150 },
]);

const adminTotal = staff
  .filter(u => u.role === 'admin')
  .sortByDesc('points')
  .sum('points'); // 270

const grouped = staff.groupBy('role');
// Collection: { admin: [...], editor: [...] }

---

TSX views, components & streaming SSR

Views are TypeScript modules in resources/views/ that return JSX. Layouts and components are other views, used as tags:

interface Props {
  name?: string;
  posts?: Array<{ title: string }>;
}

export default function render({ name, posts = [] }: Props) {
  return (
    <AppLayout title={`Dashboard — ${name}`}>
      <h1>Welcome back, {name}</h1>
      {posts.length ? (
        <div class="grid">
          {posts.map((post) => (
            <PostCard post={post} />
          ))}
        </div>
      ) : (
        <p>No posts available.</p>
      )}
    </AppLayout>
  );
}

Interactive regions are islands: pondoknusa make:island counter writes resources/views/islands/counter.tsx plus a client mount in resources/client/islands/counter.ts (registerIsland from @pondoknusa/ssr).

View.streamSsr() / Response.ssr() flush the document shell, then hydrate islands from the manifest.

---

Queues, Scheduled Tasks & Domain Events

Typed Jobs & Queues

import { Job } from '@pondoknusa/queue';
import { dispatch, Queue } from '@pondoknusa/core';

export class ProcessReportJob extends Job<{ reportId: number }> {
  override async handle(): Promise<void> {
    const { reportId } = this.data;
    // Execute expensive calculation
  }
}

// Dispatch immediately or delayed
await dispatch(new ProcessReportJob({ reportId: 42 }));
await Queue.later(60, new ProcessReportJob({ reportId: 42 }));

Run workers via pondoknusa queue:work.

Domain Events & Queued Listeners

import { Event, Listener, QueuedListener } from '@pondoknusa/events';
import { Events } from '@pondoknusa/core';

export class OrderPlaced extends Event<{ orderId: number; amount: number }> {}

// Background queued listener
export class SendOrderConfirmation extends QueuedListener<OrderPlaced> {
  static override queue = 'emails';

  override async handle(event: OrderPlaced): Promise<void> {
    // Sends confirmation email asynchronously
  }
}

await Events.dispatch(new OrderPlaced({ orderId: 101, amount: 49.99 }));

---

AI Inference, Vector Search & RAG

@pondoknusa/inference (26+ Provider Presets)

Call LLMs with a unified API using standard fetch without heavy SDKs:

import { inferenceChat, streamInferenceChat, registerInferenceProvidersFromEnv } from '@pondoknusa/inference';

// Auto-registers all providers found in .env (OpenAI, Anthropic, Gemini, DeepSeek, Groq, Ollama, etc.)
registerInferenceProvidersFromEnv();

// Simple chat completion
const response = await inferenceChat([
  { role: 'system', content: 'You are a helpful assistant.' },
  { role: 'user', content: 'Explain post-quantum cryptography briefly.' },
], { provider: 'deepseek', model: 'deepseek-chat' });

console.log(response.content);

// Streaming response
for await (const delta of streamInferenceChat(messages, { provider: 'openai' })) {
  process.stdout.write(delta);
}

Vector Search & RAG

import { registerLocalVectorSearchDriver, similarTo } from '@pondoknusa/vector';
import { Rag } from '@pondoknusa/rag';

// Similarity search over an Eloquent model (nearest first)
registerLocalVectorSearchDriver('sqlite');

const matches = await similarTo(Document, queryVector, {
  limit: 5,
  metric: 'cosine', // 'cosine' | 'l2' | 'inner_product'
}).get();

// Grounded RAG prompt construction
// `Document` is a model with a vector column; `embed` is an EmbedFn.
const rag = new Rag({ model: Document, embed });
const chunks = await rag.retrieve(userQuestion, { topK: 5 });
const groundedPrompt = rag.buildPrompt(userQuestion, chunks);

Model Context Protocol (MCP)

Pondoknusa includes native MCP integration for AI coding assistants:

pondoknusa mcp:serve           # Starts stdio MCP server exposing routes, models, and tools
pondoknusa mcp:export-rules    # Exports AGENTS.md / Cursor rules

---

Authentication, OAuth2 & Post-Quantum Cryptography

Authentication & Authorization

import { Auth, Gate, Password } from '@pondoknusa/core';

// Session login
await Auth.attempt({ email: '[email protected]', password: 'secret-password' });

// API tokens (hashed at rest with tyr_ prefix)
const token = await Auth.createToken('cli-token', ['read:reports'], { expiresIn: '30d' });

// Gate authorization
await Gate.authorize(Auth.user(), 'update', document);

OAuth2 Authorization Server (@pondoknusa/auth-oauth)

pondoknusa oauth:install
pondoknusa oauth:client:create "Mobile Client" --redirect=https://app.example.com/callback

Provides full support for Authorization Code (with mandatory PKCE), Client Credentials, and Refresh Token grants.

WebAuthn / Passkeys (@pondoknusa/auth-passkey)

Zero-dependency passkey registration and biometric authentication using standard WebAuthn APIs.

Post-Quantum Cryptography (@pondoknusa/crypto)

Native OpenSSL 3.5+ post-quantum algorithms on Node 26+:

• ML-KEM (Kyber) & Hybrid X25519 + ML-KEM-768 key encapsulation
• ML-DSA (Dilithium) & SLH-DSA (SPHINCS+) quantum-safe digital signatures
• Encrypted database sessions and quantum-safe signed OAuth tokens

pondoknusa crypto:generate-keys --algorithm=hybrid-x25519-ml-kem-768

---

Real-Time Broadcasting & Echo

Zero-dependency native WebSocket broadcasting:

// Server: src/events/message-sent.ts
import { Event } from '@pondoknusa/events';

export class MessageSent extends Event<{ message: string; from: string }> {
  broadcastOn() {
    return ['chat-room'];
  }
}

// Browser: Native WebSocket Echo client (zero third-party deps)
import { Echo } from '@pondoknusa/echo';

const echo = new Echo({
  broadcaster: 'websocket',
  wsHost: window.location.hostname,
  wsPort: 3000,
});

echo.channel('chat-room').listen('MessageSent', (event) => {
  console.log(`${event.from}: ${event.message}`);
});

---

Cache, Mail, Notifications & Storage

import { Cache, Mail, Notifications, Storage } from '@pondoknusa/core';
import { InvoicePaidNotification } from '../notifications/invoice-paid.js';
import { WelcomeMail } from '../mail/welcome-mail.js';

// Cache with stampede protection & tagging
const stats = await Cache.tags(['analytics']).remember('daily_summary', 3600, async () => {
  return computeAnalytics();
});

// Mail (log, array, SMTP)
await Mail.to('[email protected]').send(new WelcomeMail(user));

// Multi-channel Notifications (database, mail, Slack, SMS)
await Notifications.send(user, new InvoicePaidNotification(invoice));

// Cloud & local filesystem storage
await Storage.disk('s3').put('reports/annual.pdf', fileBuffer);
const url = await Storage.disk('s3').temporaryUrl('reports/annual.pdf', 300);

---

Interactive REPL (pondoknusa shell) & Testing

Interactive Shell

pondoknusa shell

Drops into an interactive TypeScript REPL with all models, facades (DB, Route, Auth, Cache), and container bindings automatically imported.

Feature Testing with @pondoknusa/testing

import { TestCase, withPondoknusaTest, mailFake } from '@pondoknusa/testing';

class UserTest extends TestCase {}
const t = withPondoknusaTest(UserTest);

it('creates a user and sends welcome mail', async () => {
  const mail = mailFake();

  const response = await t.http.post('/api/v1/users', {
    json: { name: 'Ada Lovelace', email: '[email protected]' },
  });

  await response.assertStatus(201).assertJsonPath('data.name', 'Ada Lovelace');
  mail.assertSent(WelcomeMail);
});

---

Production deployment & bundling (v4.0)

Pondoknusa 4.0 is engineered for instant cold starts across container and serverless environments:

# Production optimization pipeline
npm install -D esbuild
pondoknusa route:cache
pondoknusa view:cache
pondoknusa build --full

pondoknusa build --full bundles your application code, framework kernel, and configuration into a single standalone module (bootstrap/app.mjs), eliminating disk I/O and cold-start overhead in AWS Lambda, Cloudflare Workers, Fly.io, Railway, and Docker.

NODE_ENV=production node bootstrap/app.mjs

---

Contributing & Publishing

# Run tests across all 63 packages
npm test

# Type-check entire monorepo
npm run typecheck

# Prepare release (bump, tag, push)
npm run release:prepare -- patch

Package releases are published to the @pondoknusa npm organization with npm run release:publish (builds, then interactive npm login and 2FA). Already-published versions are skipped, so a re-run only ships new packages. Preview with npm run release:publish -- --plan.

---

Documentation

Comprehensive documentation is available at pondoknusa.dev:

• Guide — Architectural concepts, routing, ORM, auth, inference, and views.
• Configuration Reference — Complete options for every config/*.ts file.
• Deployment Hub — Docker, Fly.io, Railway, Cloudflare, and CI/CD pipelines.
• Performance & Cold Starts — Benchmarks, bundling, and optimization strategies.
• Security Policy — Vulnerability reporting and disclosure process.
• API Stability Policy — Semver and deprecation policy.

---

Roadmap

See ROADMAP.md for full progress and milestone details.

Shipped Highlights (through v6.0)

• v1.0.0 — Semver strict declaration, hosted documentation at pondoknusa.dev, complete facade reference, deploy walkthroughs.
• v2.0.0 — Rebrand to Pondoknusa (@pondoknusa/*), unified npm scope and CLI branding.
• v3.0.0 — Security hardening: mass assignment protection, session integrity, OAuth/PKCE lockdown, body limits.
• v4.0.0 — Cold-start bundling: bundled module config caching (storage/framework/config.mjs), pondoknusa build --full single-file serverless builds, lazy middleware dispatch, warm connection pools.
• v4.1.0 — LLM inference provider registry (@pondoknusa/inference) with 26+ zero-SDK presets, create-and-breathe scaffolding, Cursor MCP primer and agent rule generation.
• v4.2.0 — TypeScript 7, Vite 8, Rolldown, and Bun as a production runtime.
• v5.0.0 — TSX views replace .tyr. Layouts and components are PascalCase tags. .tyr.ts programmatic views are removed.
• v5.1.0 — TSX view locals (const / let / var before return) are available in component props.
• v6.0.0 — Oxc TSX dialect, island pn-* DOM markers, RFC 9457 errors, agent-ready HTTP (/llms.txt, markdown Accept, /openapi.json).

---

License

MIT © Pondoknusa Contributors