# JustScale

> A TypeScript backend framework where plain, straight-line code just scales - durable processes and an ID-free domain built in.

JustScale is a general-purpose TypeScript backend framework where you write
plain, straight-line code and it just scales - the Go model (write
blocking-style code, it scales) brought to TypeScript. Long-running workflows
are plain async code the compiler makes durable, the domain layer never
handles string IDs, and the type system catches mistakes at compile time. The
pages below are the canonical documentation.

Full text of every page in one file: https://justscale.sh/llms-full.txt

## Core philosophy

Most backend code is infrastructure - wiring storage, transport, transactions,
and restart-survival - not business logic. JustScale's goal is to make the
"t-shirt code" real: code that reads like a plain description of what happens,
while the framework and compiler handle how. Ten principles define it:

1. Domain code describes WHAT, never HOW. A months-long subscription or a poker
   hand reads like a simple loop; durability and distribution are mechanical.
2. IDs do not exist in domain code. A stored entity IS its own reference; there
   is no .id or .createdAt in the domain. Raw keys are an adapter concern, and
   turning a string into a reference happens only at boundaries.
3. You declare the data form you need; the caller provides it. Type-states
   (Transient = unsaved/writable, Persistent = stored/readonly, Lock<Persistent>
   = stored+locked/writable) make the method signature the contract.
4. Models are services. A model instance's prototype is a resolved service, so
   injected dependencies are reachable on this without passing them around.
5. References replace relationships. Fields hold typed references (field.ref /
   field.refs), not foreign keys; references are type-safe and awaitable.
6. Adapters own their concerns. The domain defines models; adapters (Postgres,
   in-memory, Redis) implement storage. Domain code is unchanged when you swap them.
7. Async context is the framework. AsyncLocalStorage tracks the active instance,
   so there is no global mutable state and multiple instances stay isolated.
8. Durable processes are plain code. Long-running workflows are ordinary async
   functions the compiler turns into resumable, persisted state machines.
9. The framework composes and reflects itself. Features, sub-apps, and wrappers
   are first-class, and every scope exposes a queryable AbstractContainer.
10. If it compiles, it works. Missing dependencies, wrong data form, and
    impossible cross-adapter queries are caught statically, not at runtime.

What JustScale is not: a micro-framework, backwards-compatible with TypeORM or
Prisma models, or trying to be everything to everyone. It is opinionated and
comprehensive, for people who want to think in domain terms.

## Overview

- [Introduction](https://justscale.sh/docs/overview/introduction): What is JustScale and why should you use it?
- [Installation](https://justscale.sh/docs/overview/installation): Get JustScale installed in your project
- [Quick Start](https://justscale.sh/docs/overview/quick-start): Build your first JustScale application
- [Philosophy](https://justscale.sh/docs/overview/philosophy): Design principles behind JustScale

## Fundamentals

- [Services](https://justscale.sh/docs/fundamentals/services): Type-safe dependency injection with services
- [Controllers](https://justscale.sh/docs/fundamentals/controllers): Group related routes with controllers
- [Routes](https://justscale.sh/docs/fundamentals/routes): Define HTTP endpoints with route builders
- [Middleware](https://justscale.sh/docs/fundamentals/middleware): Process requests with middleware
- [Guards](https://justscale.sh/docs/fundamentals/guards): Protect routes with guard functions
- [Models](https://justscale.sh/docs/models/overview): Define your domain models with type-safe field builders
- [Field Builders](https://justscale.sh/docs/models/field-builders): Comprehensive reference for all field types and modifiers
- [Queries](https://justscale.sh/docs/queries/overview): Type-safe query system for building database queries
- [Conditions](https://justscale.sh/docs/queries/conditions): Complete reference of all query operators and conditions
- [Repositories](https://justscale.sh/docs/repositories/overview): Connect to different storage backends
- [References](https://justscale.sh/docs/repositories/references): Working with entity relationships in a DDD-friendly way
- [Features](https://justscale.sh/docs/fundamentals/features): Compose reusable feature modules
- [Sub-apps](https://justscale.sh/docs/fundamentals/sub-apps): Isolated JustScale() scopes composed via scope-switched bridges
- [Channels](https://justscale.sh/docs/fundamentals/channels): Typed pub/sub messaging for real-time features
- [Locks](https://justscale.sh/docs/fundamentals/locks): Distributed locking for safe concurrent access

## Core Concepts

- [Type States](https://justscale.sh/docs/concepts/type-states): How data shape controls what your code can do
- [Models as Services](https://justscale.sh/docs/concepts/models-as-services): Model instances with injected dependencies via prototype chain
- [References](https://justscale.sh/docs/concepts/references): ID-free domain modeling with type-safe references

## HTTP

- [Request Handling](https://justscale.sh/docs/http/request-handling): Handle HTTP requests and responses
- [Path Parameters](https://justscale.sh/docs/http/path-parameters): Extract parameters from URLs
- [Typed Parameters](https://justscale.sh/docs/http/typed-params): Transform path parameters into model references with .types()
- [Query & Body](https://justscale.sh/docs/http/query-body): Parse query strings and request bodies
- [Response Types](https://justscale.sh/docs/http/response-types): Send JSON, HTML, and streaming responses
- [Server-Sent Events](https://justscale.sh/docs/http/sse): Real-time streaming with SSE routes

## PostgreSQL

- [Overview](https://justscale.sh/docs/postgres/overview): PostgreSQL adapter for persistent storage
- [Repositories](https://justscale.sh/docs/postgres/repositories): Query methods, transactions, and advanced features
- [Migrations](https://justscale.sh/docs/postgres/migrations): Schema migrations for PostgreSQL

## Configuration

- [Overview](https://justscale.sh/docs/configuration/overview): Type-safe configuration management with Zod validation

## Techniques

- [Validation](https://justscale.sh/docs/techniques/validation): Validate input with Zod schemas
- [OpenAPI](https://justscale.sh/docs/techniques/openapi): Generate OpenAPI documentation
- [Error Handling](https://justscale.sh/docs/techniques/error-handling): Handle errors gracefully
- [Testing](https://justscale.sh/docs/techniques/testing): Test your JustScale applications
- [In-Memory Repository](https://justscale.sh/docs/repositories/in-memory): Fast in-memory storage for testing

## CLI

- [Usage](https://justscale.sh/docs/cli/usage): Build command-line interfaces

## Features

- [Overview](https://justscale.sh/docs/features/overview): Pre-built feature modules
- [Authentication](https://justscale.sh/docs/features/auth): User authentication with database sessions
- [Permissions](https://justscale.sh/docs/features/permissions): Declarative, queryable model-level access control
- [Shell](https://justscale.sh/docs/features/shell): Interactive shell feature
- [OpenTelemetry](https://justscale.sh/docs/features/otel): Distributed tracing with OpenTelemetry
- [Event](https://justscale.sh/docs/features/event): Event-driven architecture
- [Datastar](https://justscale.sh/docs/features/datastar): Datastar integration

## Processes

- [Overview](https://justscale.sh/docs/processes/overview): Long-running workflows that survive restarts
- [Signals](https://justscale.sh/docs/processes/signals): Event-driven suspension and resumption of durable processes
- [Runtime & Testing](https://justscale.sh/docs/processes/runtime): Setting up the process executor and testing durable processes
- [Compiler](https://justscale.sh/docs/processes/compiler): How durable processes are transformed at build time

## Cluster

- [Overview](https://justscale.sh/docs/cluster/overview): Create clustered applications

## WebSocket

- [Overview](https://justscale.sh/docs/websocket/overview): Real-time WebSocket support
- [Message Handling](https://justscale.sh/docs/websocket/messages): Validate, process, and respond to WebSocket messages
- [Rooms & Broadcasting](https://justscale.sh/docs/websocket/rooms): Implement real-time rooms with pub/sub channels
- [Contextual Controllers](https://justscale.sh/docs/websocket/contextual): Build RPC-style WebSocket APIs with procedures

## gRPC / RPC

- [Overview](https://justscale.sh/docs/rpc/overview): Type-safe gRPC services with proto imports
- [Controllers](https://justscale.sh/docs/rpc/controllers): Implement gRPC service contracts with controllers
- [Client](https://justscale.sh/docs/rpc/client): Type-safe gRPC client with DI integration
- [Status & Errors](https://justscale.sh/docs/rpc/status-errors): gRPC status codes and error handling

## Advanced

- [Why It Scales](https://justscale.sh/docs/advanced/why-it-scales): The mechanical chain that turns a one-instance program into a distributed one
- [Plugins](https://justscale.sh/docs/advanced/plugins): Extend JustScale with plugins
- [Type Utilities](https://justscale.sh/docs/advanced/types): Advanced TypeScript utilities
- [Debugging](https://justscale.sh/docs/advanced/debugging): Debug JustScale applications
- [HMR](https://justscale.sh/docs/advanced/hmr): Edit services, controllers, and models without restarting the process

## Comparisons

- [JustScale vs NestJS](https://justscale.sh/compare/justscale-vs-nestjs): How JustScale compares to NestJS: a general-purpose framework where plain code just scales - durable processes, an ID-free domain, type-states - vs decorators and modules.
- [JustScale vs Temporal](https://justscale.sh/compare/justscale-vs-temporal): JustScale vs Temporal for durable execution: in-process durable processes on your own database vs a dedicated workflow server and worker fleet.
- [JustScale vs Encore](https://justscale.sh/compare/justscale-vs-encore): JustScale vs Encore: a framework with durable processes and a pure domain model vs an infrastructure-from-code platform that provisions your cloud.
- [JustScale vs Inngest & Restate](https://justscale.sh/compare/justscale-vs-inngest): JustScale vs Inngest and Restate: in-framework durable processes on your own database vs hosted/serverless durable-function platforms and runtimes.

## Migration guides

- [Migrating from NestJS to JustScale](https://justscale.sh/migrate/from-nestjs): A step-by-step guide to migrating a NestJS app to JustScale: providers to services, controllers, modules, DTOs, and BullMQ jobs to durable processes.
- [Migrating from Temporal to JustScale](https://justscale.sh/migrate/from-temporal): How to migrate Temporal workflows to JustScale durable processes: workflows to processes, activities to service calls, signals, and timers — no worker fleet.