Introduction to JSango

npx jsango new my-backend
cd my-backend
npm install

import { defineModel, fields } from 'jsango';

export const Product = defineModel(
  'Product',
  {
    id: fields.id(),
    name: fields.string({ maxLength: 255 }),
    price: fields.decimal({ precision: 10, scale: 2 }),
    inStock: fields.boolean({ defaultValue: true }),
  },
  { table: 'products', timestamps: true }
);

npx jsango makemigrations   # writes migrations/<timestamp>_create_products.ts
npx jsango migrate          # creates the tables

import { createApp } from 'jsango';
import { configureDatabase, db } from './database.js';
import { Product } from './models/product.js';

configureDatabase();                 // all models use the configured database
const app = createApp();

app.get('/api/products', () => Product.where('inStock', true).orderBy('name').get());
app.crud('/api/crud/products', Product);   // full REST CRUD in one line

await db.verify();                   // fail fast if the database is unreachable
await app.listen(3000);

npm run dev

my-backend/
├── src/
│   ├── models/            # Declarative ORM models & relations
│   ├── routes/            # HTTP Route handlers & route groups
│   ├── middleware/        # Authentication, CORS & rate limit guards
│   ├── agents/            # Autonomous AI agents & custom tools
│   ├── workflows/         # Multi-agent orchestration workflows
│   ├── jobs/              # Background queue workers
│   ├── events/            # Strongly typed domain events
│   └── index.ts           # App bootstrap & server initialization
├── migrations/            # Version-controlled database migrations
├── jsango.config.ts       # Framework & multi-database configuration
├── .env                   # Environment variables
├── tsconfig.json          # Strict TypeScript configuration
└── package.json

import { defineConfig } from 'jsango';
import { db } from './src/database.js';

export default defineConfig({
  database: db,               // a DatabaseManager, or { default, connections } config object
  models: './src/models',     // files/folders with defineModel() calls
  migrations: './migrations', // migration files directory
});

DATABASE_URL=postgres://app:secret@localhost:5432/myapp
PORT=3000
JWT_SECRET=change-me

// Automatically validates UUID format before triggering handler
app.get('/api/v1/users/:id:uuid', async (ctx) => {
  const userId = ctx.request.params['id'];
  const user = await User.find(userId);
  return user ? ctx.response.json(user) : ctx.response.notFound();
});

app.group('/api/v1/admin', (router) => {
  router.use(requireAdminAuth);
  router.get('/analytics', analyticsHandler);
  router.post('/settings', settingsHandler);
});

app.post('/api/users/profile', async (ctx) => {
  // Read parsed JSON body & query params
  const body = ctx.request.body;
  const query = ctx.request.query;

  // Read headers and cookies
  const authHeader = ctx.request.headers.get('Authorization');
  const sessionCookie = ctx.request.cookies.get('session_id');

  // Return standard JSON response with status
  return ctx.response.json({ success: true, user: body }, { status: 201 });
});

import { createApp, model, fields } from 'jsango';

export const Article = model('Article', {
  id: fields.id(),
  title: fields.string({ maxLength: 200 }),
  content: fields.text(),
  published: fields.boolean({ defaultValue: false }),
});

const app = createApp();

// Generates GET, POST, PUT, DELETE endpoints automatically
app.crud('/api/articles', Article, {
  pagination: { defaultLimit: 25, maxLimit: 100 },
  allowedFilters: ['published', 'title'],
});

await app.listen(3000);

import { RequestContext, NextFunction } from 'jsango';

export async function authGuard(ctx: RequestContext, next: NextFunction) {
  const token = ctx.request.headers.get('Authorization')?.replace('Bearer ', '');
  if (!token) {
    return ctx.response.unauthorized('Authentication token required');
  }

  // Attach verified user to request state
  ctx.state.user = await verifyJwtToken(token);
  return next();
}

import { object, string, number, validate } from 'jsango';

const CreateProductSchema = object({
  name: string().min(3).max(100),
  price: number().positive(),
  category: string().optional(),
});

app.post('/api/products', async (ctx) => {
  const result = validate(CreateProductSchema, ctx.request.body);
  if (!result.success) {
    return ctx.response.badRequest({ errors: result.errors });
  }

  const newProduct = await Product.create(result.data);
  return ctx.response.json(newProduct, { status: 201 });
});

import { DatabaseManager, databaseConfigFromEnv, setDatabaseManager } from 'jsango';

export const db = new DatabaseManager(databaseConfigFromEnv());

export function configureDatabase() {
  setDatabaseManager(db); // every model now uses this database
  return db;
}

# Option A — one URL (wins if set)
DATABASE_URL=postgres://app:secret@localhost:5432/myapp

# Option B — individual settings
DATABASE_DRIVER=mysql
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_NAME=myapp
DATABASE_USER=app
DATABASE_PASSWORD=secret
DATABASE_SSL=true          # true/require, no-verify, false
DATABASE_POOL_MAX=10
DATABASE_FILE=./db.sqlite3 # SQLite only

export const db = new DatabaseManager({
  default: 'primary',
  connections: {
    primary: {
      driver: 'postgres',
      host: process.env.DB_HOST,
      database: 'myapp',
      username: 'app',
      password: process.env.DB_PASSWORD,
      ssl: true,
      pool: { max: 20, connectionTimeoutMs: 10_000 },
    },
    analytics: { url: process.env.ANALYTICS_URL }, // driver inferred from the URL
    local: { driver: 'sqlite', filename: './data/local.sqlite3' },
  },
});

// models: defineModel('Event', {...}, { connection: 'analytics' })

await db.verify();                 // throws a descriptive error if it can't connect
await app.listen(3000);
process.once('SIGTERM', async () => { await db.close(); process.exit(0); });

// raw SQL: always write ? placeholders (converted to $1, $2 for PostgreSQL)
const { rows } = await db.query('SELECT id, email FROM users WHERE created_at > ?', [since]);
await db.transaction(async (tx) => {
  await tx.query('UPDATE accounts SET balance = balance - ? WHERE id = ?', [100, from]);
  await tx.query('UPDATE accounts SET balance = balance + ? WHERE id = ?', [100, to]);
});

npx jsango db:status
# Connection  Driver    Target                     Status      Latency
# default     postgres  app@localhost:5432/myapp   ✓ HEALTHY   4ms

import { defineModel, fields } from 'jsango';

export const User = defineModel(
  'User',
  {
    id: fields.id(),                                        // auto-increment primary key
    email: fields.string({ maxLength: 255, unique: true }),
    name: fields.string({ maxLength: 120, nullable: true }),
    role: fields.string({ maxLength: 20, defaultValue: 'member', indexed: true }),
    isActive: fields.boolean({ defaultValue: true }),
    settings: fields.json({ nullable: true }),
  },
  {
    table: 'users',     // default: lower-cased name + "s"
    timestamps: true,   // createdAt / updatedAt, maintained automatically
    softDelete: false,  // true: delete() sets deletedAt instead of removing the row
    relations: {
      posts: { type: 'hasMany', target: 'Post', foreignKey: 'userId' },
    },
  }
);

export const Post = defineModel(
  'Post',
  {
    id: fields.id(),
    title: fields.string(),
    userId: fields.integer(),   // foreign key column
  },
  {
    table: 'posts',
    relations: {
      // posts.userId -> users.id; the migration creates a FOREIGN KEY (ON DELETE CASCADE)
      author: { type: 'belongsTo', target: 'User', foreignKey: 'userId' },
    },
  }
);

const posts = await Post.query().with('author').orderBy('id', 'DESC').limit(10).get();
posts[0].author.email; // all authors loaded with ONE extra query

// Create
const user = await User.create({ email: 'a@example.com', name: 'Ada' });
user.id;        // assigned by the database
await Post.bulkCreate([{ title: 'One', userId: user.id }, { title: 'Two', userId: user.id }]);

// Read
await User.find(1);                                  // or null
await User.findOrFail(1);                            // throws ModelNotFoundError
await User.where('email', 'a@example.com').first();
await User.where({ role: 'admin', isActive: true }).get();

// Update
user.name = 'Ada Lovelace';
await user.save();                                   // only changed columns are written
await User.where('isActive', false).update({ role: 'inactive' });

// Delete
await user.delete();
await User.where('role', 'spam').delete();

const users = await User.query()
  .where('createdAt', '>=', since)
  .whereIn('role', ['admin', 'editor'])
  .whereNotNull('name')
  .orWhere('email', 'ILIKE', '%@example.com')
  .orderBy('createdAt', 'DESC')
  .limit(20)
  .offset(40)
  .get();

await User.count();
await User.where('isActive', true).exists();

const page = await User.query().orderBy('id').paginate({ page: 2, pageSize: 25 });
// page.items, page.total, page.page, page.pageSize, page.totalPages

for await (const u of User.query().cursor(500)) {
  // stream a large table in batches of 500
}

// genre = 'fiction' AND (price < 10 OR pages > 500)
await Book.where('genre', 'fiction')
  .where((q) => q.where('price', '<', 10).orWhere('pages', '>', 500))
  .get();

await Book.whereNot('status', 'draft').get();
await Book.whereBetween('price', [10, 25]).get();
await Book.whereLike('title', '%guide%').get();     // case-insensitive
await Book.select('genre').distinct().get();
await Book.orderBy('price').pluck('title');
await Book.latest().first();

// aggregates
await Book.sum('price');
await Book.where('genre', 'science').avg('price');
await Book.min('price');
await Book.max('pages');

// GROUP BY / HAVING -> plain rows
await Book.query().groupBy(
  ['genre'],
  { total: ['sum', 'price'], books: ['count'] },
  { having: [['books', '>=', 2]], orderBy: [['total', 'DESC']] }
); // [{ genre: 'science', total: 42.5, books: 2 }, ...]

// atomic counters, find-or-create, batches, row locks
await Author.where('active', true).increment('logins');
await post.increment('views');
await Tag.firstOrCreate({ slug: 'news' }, { label: 'News' });
await Setting.updateOrCreate({ key: 'theme' }, { value: 'dark' });
await User.query().chunk(500, async (users) => { /* ... */ });
await transaction(async () => {
  const acc = await Account.where('id', id).lockForUpdate().first();
});

// escape hatch
await User.whereRaw('LOWER(email) = ?', [email]).get();      // SQL
await User.whereRaw({ tags: { $all: ['a', 'b'] } }).get();   // MongoDB

// model option: softDelete: true
await post.delete();                  // sets deletedAt
await Post.query().get();             // excludes soft-deleted rows
await Post.withTrashed().get();       // includes them
await Post.onlyTrashed().get();       // only them
await post.delete({ force: true });   // real DELETE

import { transaction } from 'jsango';

await transaction(async () => {
  const user = await User.create({ email });
  await Profile.create({ userId: user.id });   // automatically in the same transaction
  if (!ok) throw new Error('abort');            // any error rolls everything back
});

await transaction(async () => { /* ... */ }, { isolationLevel: 'SERIALIZABLE' });

// explicit alternative
await db.transaction(async (tx) => {
  await User.create({ email }, { connection: tx });
  await User.query().using(tx).where('id', 1).update({ name: 'x' });
});

npm install mongodb
# .env
DATABASE_URL=mongodb://app:secret@localhost:27017/myapp

export const Post = defineModel('Post', {
  id: fields.objectId({ primaryKey: true }),  // maps to _id, new ObjectId on create
  title: fields.string(),
  authorId: fields.objectId(),                // ObjectId reference
  tags: fields.json({ nullable: true }),      // stored natively
}, {
  table: 'posts',                             // collection
  timestamps: true,
  relations: { author: { type: 'belongsTo', target: 'Author', foreignKey: 'authorId' } },
});

const post = await Post.create({ title: 'Hello', authorId: author.id });
post.id;                   // '65f1c2…' (ObjectId as string)
await Post.find(post.id);  // converted back to ObjectId in queries

export default defineMigration({
  id: '20260930130000_backfill_roles',
  async up(ctx) {
    await ctx.execute({ op: 'updateMany', collection: 'users', filter: { role: null }, update: { $set: { role: 'member' } } });
  },
});

// anything else: the native driver
import type { Db } from 'mongodb';
const mongo = await db.mongo<Db>();
await mongo.collection('events').aggregate([...]).toArray();

# 1. change a model, e.g. add  age: fields.integer({ nullable: true })  to User

npx jsango makemigrations          # or: npx jsango migrate:generate add_age_to_users
#  ✔ Created migration migrations/20260930101500_add_age_to_users.ts
#    [+] Add column users.age (integer)

npx jsango migrate --dry-run       # optional: print the exact SQL
npx jsango migrate                 # apply
npx jsango migrate:status          # applied / pending
npx jsango migrate:rollback        # undo the last batch (--steps 1 for one migration)

import { AddColumnOperation, Migration } from 'jsango';

export const id = '20260930101500_add_age_to_users';
export const name = 'add_age_to_users';

export default new Migration({
  id,
  name,
  operations: [
    new AddColumnOperation('users', { "name": "age", "type": "integer", "nullable": true }),
  ],
});

npx jsango makemigrations rename_user_name --empty

import { defineMigration } from 'jsango';

export default defineMigration({
  id: '20260930120000_rename_user_name',
  async up(ctx) {
    await ctx.renameColumn('users', 'name', 'fullName');

    await ctx.createTable('audit_logs', (t) => {
      t.id();
      t.integer('userId').references('users');   // FK -> users.id ON DELETE CASCADE
      t.string('action', 50).index();
      t.json('payload').nullable();
      t.timestamps();
    });

    await ctx.sql("UPDATE users SET role = 'member' WHERE role IS NULL"); // data migration
  },
  async down(ctx) {
    await ctx.dropTable('audit_logs');
    await ctx.renameColumn('users', 'fullName', 'name');
  },
});

npm ci
npx jsango migrate:check --skip-db   # CI: fail if a model change has no migration
npx jsango migrate                   # apply pending migrations (locked)
npm start

import { createApp, model, fields } from 'jsango';

export const Product = model('Product', {
  id: fields.id(),
  name: fields.string({ maxLength: 255 }),
  price: fields.number(),
  inStock: fields.boolean({ defaultValue: true }),
});

const app = createApp();

// Mount Admin SPA with custom prefix, models & super admin credentials
app.admin({
  prefix: '/admin',
  title: 'My Store Admin',
  resources: [Product],
  auth: {
    email: 'admin@jsango.dev',
    password: process.env.JSANGO_ADMIN_PASSWORD || 'admin123',
    name: 'Super Administrator',
  }
});

await app.listen(3000);

import { createAdminResource } from '@jsango/admin-core';
import { User } from '../models/user.js';

export const UserAdminResource = createAdminResource(User, {
  label: 'User Accounts',
  icon: 'users',
  listFields: ['id', 'email', 'fullName', 'role', 'isActive'],
  searchFields: ['email', 'fullName'],
  filters: [
    { field: 'role', type: 'select', options: ['admin', 'editor', 'viewer'] },
    { field: 'isActive', type: 'boolean' }
  ],
  export: { csv: true, json: true },
});

import { agent, tool, object, string, number, createApp } from 'jsango';

// 1. Define tools with automatic schema validation
const getOrder = tool({
  name: 'getOrder',
  description: 'Fetch order details',
  schema: object({ orderId: string() }),
  execute: async ({ orderId }) => await Order.find(orderId),
});

const refundOrder = tool({
  name: 'refundOrder',
  description: 'Process a customer refund',
  schema: object({ orderId: string(), amount: number() }),
  requiresApproval: true, // Human approval gate
  execute: async ({ orderId, amount }) => await Stripe.refund(orderId, amount),
});

// 2. Create the Agent
export const supportAgent = agent({
  name: 'SupportAgent',
  model: 'openai:gpt-4o',
  instructions: 'Help customers with orders and refunds.',
  tools: { getOrder, refundOrder },
});

// 3. Expose over HTTP / SSE and WebSockets in 1 line
const app = createApp();
app.agent('/api/support', supportAgent);
app.wsAgent('/ws/support', supportAgent);

import { OpenAiProvider, AnthropicProvider, GeminiProvider, OllamaProvider, agent } from 'jsango';

// 1. Google Gemini
const geminiAgent = agent({
  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY }),
  model: 'gemini-1.5-pro',
  instructions: 'Expert data analyst',
});

// 2. Local Ollama (100% offline, zero cloud cost)
const localAgent = agent({
  provider: new OllamaProvider({ baseUrl: 'http://localhost:11434' }),
  model: 'llama3.2',
  instructions: 'Privacy-focused assistant',
});

import { workflow, agent } from 'jsango';

const pipeline = workflow('document-review')
  .step('research', researcherAgent)
  .step('draft', writerAgent)
  .branch(
    (state) => state.requiresApproval,
    legalReviewerAgent,
    fastTrackAgent
  );

const result = await pipeline.run({ input: 'Analyze quarterly earnings' });

import { knowledge, InMemoryVectorStore } from 'jsango';

export const docs = knowledge({
  name: 'handbook',
  vectorStore: new InMemoryVectorStore(),
  chunkSize: 500,
});

await docs.ingest({
  id: 'doc_1',
  text: 'JSango is a high-performance TypeScript backend framework with built-in AI agents.',
});

const matches = await docs.query({ query: 'What is JSango?', limit: 3 });

import { McpServer, tool, object, string } from 'jsango';

const server = new McpServer({ name: 'JSango Tools', version: '1.0.9' });

server.registerTool(tool({
  name: 'fetchInventory',
  description: 'Check stock inventory for SKU',
  schema: object({ sku: string() }),
  execute: async ({ sku }) => ({ inStock: true, count: 42 }),
}));

// Ready to handle standard MCP JSON-RPC protocol messages

const app = createApp();

// Server-Sent Events (SSE) streaming
app.agent('/api/agent/stream', supportAgent);

// Bi-directional WebSocket Agent
app.wsAgent('/ws/agent', supportAgent);

import { TotpService } from '@jsango/auth';

const totp = new TotpService();

// 1. Generate Base32 secret and otpauth:// URI
const secret = totp.generateSecret();
const qrUri = totp.generateKeyUri({
  secret,
  accountName: 'developer@example.com',
  issuer: 'JSango App'
});

// 2. Verify 6-digit token with sliding window
const isValid = totp.verifyToken({
  secret,
  token: '123456',
  window: 1
});

app.post('/api/auth/logout-all', async (ctx) => {
  const userId = ctx.state.user.id;
  await sessionManager.revokeAllForUser(userId);
  return ctx.response.json({ message: 'All sessions successfully revoked' });
});

import { authorize } from 'jsango';

app.delete('/api/posts/:id', authorize(['admin', 'editor']), async (ctx) => {
  await Post.delete(ctx.request.params.id);
  return ctx.response.noContent();
});

import { jobs } from 'jsango';

// 1. Define job handler
jobs.define('send-welcome-email', async (payload) => {
  await mailer.send({ to: payload.email, subject: 'Welcome!' });
});

// 2. Dispatch job asynchronously with retry policy
await jobs.dispatch('send-welcome-email', { email: 'user@example.com' }, {
  retries: 3,
  delay: 5000,
});

import { cache } from 'jsango';

// Cache expensive computation or query with remember()
const topProducts = await cache.remember('top-products', 300, async () => {
  return await Product.where('sales', '>', 1000).get();
});

// Invalidate on update
await cache.delete('top-products');

import { events } from 'jsango';

events.on('user:registered', async ({ user }) => {
  console.log('New user registered:', user.email);
});

await events.emit('user:registered', { user: newUser });

app.ws('/ws/chat', (ws) => {
  ws.on('message', (msg) => {
    // Broadcast to room
    ws.broadcast('chat-room', { user: 'Alice', text: msg });
  });

  ws.on('disconnect', () => {
    console.log('Client disconnected');
  });
});

import { MetricRegistry, HealthRegistry } from 'jsango';

// Metrics endpoint exposed for Prometheus scraping
app.get('/metrics', async (ctx) => {
  return ctx.response.text(await MetricRegistry.exportPrometheus());
});

// Liveness & readiness probes for Kubernetes
app.get('/health', async (ctx) => {
  const status = await HealthRegistry.check();
  return ctx.response.json(status);
});

import { createApp } from 'jsango';
import { Product } from './models/product.js';

const app = createApp();

// Mount CRUD routes
app.crud('/api/products', Product);

// Enable automated OpenAPI 3.1 spec and interactive Swagger UI docs
app.openapi({
  path: '/openapi.json',
  title: 'E-Commerce Store API',
  version: '1.0.9',
  description: 'Production REST API with real-time inventory and search',
});

await app.listen(3000);
// Interactive Swagger UI is live at: http://localhost:3000/docs
// OpenAPI JSON schema at: http://localhost:3000/openapi.json