Departing soon · v0.2.0

Rails-shaped. Type-checked.

A web framework written in Polar. Routes, views and filters are checked by the type checker before the first request comes in.

$ curl -fsSL https://ticket-polar.vercel.app/install.sh | sh

Resource routing, Typed views, SQLite, Postgres and migrations, Validations, Authentication, Generators, JSON and uploads, Docker-ready.

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.

src/routes.px
routes
  root             -> PagesController.home
  resources posts  -> PostController
terminal
$ 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.

Routing guide →
routes zoneGate 01
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.

Controllers guide →
controllersGate 02
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.

Views guide →
views zoneGate 03
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.

Filters guide →
filtersGate 04
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.

Database guide →
migrations zoneGate 05
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 zoneGate 06
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.

Testing guide →
testingGate 07
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.

Controllers guide →
jsonGate 08
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.

  1. Step 1Check in

    Install the CLI

    Puts the ticket command on your path.

    $ curl -fsSL https://ticket-polar.vercel.app/install.sh | sh
  2. Step 2Pack

    Create an app

    Writes the skeleton: routes, a controller, views, tests.

    $ ticket new my_app
    $ cd my_app
  3. 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.

polar.tomlConfig
[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 }
terminalRun
$ polar run
# builds every host and serves on :3000

$ polar start -- routes
# prints the route table