Typos fail the build, not the request
Ticket's zones are Polar plugins, so a mistake in a route or a view is
reported by polar check on the line you wrote, with a
hint for the fix.
routes
root -> PagesController.home
resources posts -> PostController
$ polar check
error[POLAR0901]: no module `PostController` in `uses`
--> src/routes.px:12:23
|
12 | resources posts -> PostController
| ^^^^^^^^^^^^^^
|
= help: a controller is a module in `uses`, named by
its last segment or its `as` alias
The lineup
What already works in Ticket today. Every example comes from the framework's own example apps and tests.
Routes the way Rails taught you
root, verb lines, resources with
only and except, nesting,
member, collection and
namespace. The zone generates the router and a typed
helper for each named route, like article_path(id).
polar start -- routes prints the table, just like
rails routes.
routes
root -> PagesController.home
get /about -> PagesController.about as about
resources articles -> ArticlesController only index show new create
namespace admin
get /stats -> StatsController.show as stats
$ polar start -- routes
root_path GET / PagesController.home
about_path GET /about PagesController.about
articles_path GET /articles ArticlesController.index
new_article_path GET /articles/new ArticlesController.new
POST /articles ArticlesController.create
article_path GET /articles/:id ArticlesController.show
admin_stats_path GET /admin/stats StatsController.show
Controllers are modules of plain functions
Every action takes a Conn and returns a
Response. Its effects are in the signature, so you
can see at a glance which actions touch state and which can halt.
redirect_to answers a form post with a 303, so the
browser follows it with a GET.
functions
show(conn: Conn) -> Response / {Mut, Throws<Halt>} {
let article = find_or_halt(conn)
Response.render(Layout.app(article.title, Articles.show(article)))
}
create(conn: Conn) -> Response / {Mut} {
let article = Article.create(title_of(conn))
Response.redirect_to(conn, Paths.article_path(article.id))
}
Markup that type-checks
A view is a header plus markup, and it compiles to a function that
returns Html. Holes are escaped, a
Bool attribute appears or disappears, and a
None leaves the attribute out.
Shared components go in a view_component zone and are
used as <UI.Card> from any module.
view_component
Card(title: String, children: Html)
<section class="card">
<h2>{title}</h2>
{children}
</section>
views
item(article: Article)
<li><a href={Paths.article_path(article.id)}>{article.title}</a></li>
wrapped()
<Card title="Latest">
<p>Fresh off the press</p>
</Card>
Filters without magic
A filter is a function from Conn to
Result<Response, Conn>. Ok lets
the request through and Err answers it.
Action.before runs them in order, like Rails'
before_action.
Deep inside a helper, throw Halt(response) answers
the request on the spot.
functions
show(conn: Conn) -> Response / {Mut} {
Action.before([require_token], stats)(conn)
}
require_token(conn: Conn) -> Result<Response, Conn> {
if Params.string(conn, "token") == Some("secret") {
Ok(conn)
} else {
Err(Response.text(401, "unauthorized"))
}
}
Migrations, then SQLite or Postgres
A migration is a few lines in the migrations zone.
The same file runs on SQLite, which is built in, and on Postgres
with the pg package, where ids become identity
columns and times become timestamptz.
Switching is one setting in ticket.toml. Models and
queries don't change.
migrations
20261001_100100 create_table posts
title String
body String
published Bool default false
author_id Id<User> references users on_delete cascade
timestamps
# ticket.toml
[database]
adapter = "postgres"
database = "postgres://app:secret@localhost/app"
$ ticket db:migrate
== 20261001_100100 create_table posts: migrating
== 20261001_100100 create_table posts: migrated (12ms)
Validations are one line per field
presence, length, and
uniqueness sit next to the model. Failures come back
as typed errors that the form helpers show beside the field.
Queries are typed as well: a filter on the wrong column type is a compile error.
Database guide →validations
title presence length 3..120 uniqueness
body presence
functions
latest() -> List<Post> / {Db, Throws<DbFailure>} {
Posts.filter(
[Query.eq(Schema.post_published, true)],
[Query.order_desc(Schema.post_id)],
)
}
Tests that drive the router
Test.with_db gives each test a fresh database with
your migrations applied. Test.get and
Test.post go through the real router and return a
reply you can assert on.
polar test runs them. Set
TICKET_TEST_POSTGRES and the same tests run on
Postgres.
test_index_lists_posts_with_authors() {
Test.with_db(
Schema.migrations,
function() {
seed()
let reply = Test.get(Routes.router, Test.client(), "/posts")
Test.assert_status(reply, 200)
Test.assert_body_contains(reply, "Hello, Ticket")
},
)
}
One action, HTML or JSON
respond_to picks the branch from the request's
format, so the same action answers a browser and
/data.json. A record type with
derive(Json) is all the encoding you write.
types
Data = { title: String } derive(Json)
functions
data(conn: Conn) -> Response {
Response.respond_to(
conn,
function() { Response.text(200, "html") },
function() { Response.json(200, { title: "Hello" }) },
)
}
Board in three steps
You'll need Polar 0.4.0 or newer and Node 22.5 or newer.
-
Step 1Check in
Install the CLI
Puts the
ticketcommand on your path.$ curl -fsSL https://ticket-polar.vercel.app/install.sh | sh -
Step 2Pack
Create an app
Writes the skeleton: routes, a controller, views, tests.
$ ticket new my_app $ cd my_app -
Step 3Board
Start the server
Builds every host and serves on
:3000.$ ticket server
Adding Ticket to an existing Polar app
Run polar add github.com/stepanvanzuriak/ticket, or
add the dependency and launcher by hand.
[project]
name = "app"
hosts = ["Node"]
main = "src/routes.px"
[dependencies]
ticket = { git = "github.com/stepanvanzuriak/ticket", version = "v0.2.0" }
[run]
launcher = "ticket"
options = { port = 3000 }
$ polar run
# builds every host and serves on :3000
$ polar start -- routes
# prints the route table