AshTypst.Resource

Spark DSL extension for rendering Typst templates as Ash generic actions.

This extension adds a typst DSL section to your Ash resource where you can declare reusable templates and render actions. Each render action is transformed into an Ash generic action that compiles and exports a Typst document, returning an AshTypst.Document struct.

Usage

Add the extension to your resource:

defmodule MyApp.Invoice do
  use Ash.Resource,
    domain: MyApp.Domain,
    extensions: [AshTypst.Resource]

  typst do
    root "priv/typst"

    template :invoice do
      source "invoice.typ"
      inputs %{"company" => "Acme Corp"}
    end

    template :receipt do
      # ~TYPST sigil is auto-imported in template blocks
      markup ~TYPST"""
      #import "data.typ": record, args
      = Receipt #args.receipt_number
      *Customer:* #record.name
      """
    end

    render :generate_pdf do
      template :invoice
      format :pdf

      argument :invoice_id, :string, allow_nil?: false

      read :one do
        filter expr(id == ^arg(:invoice_id))
        load [:line_items, :customer]
      end

      pdf_options do
        pdf_standards [:pdf_a_2b]
      end
    end
  end
end

Then call the action like any other Ash generic action:

input = Ash.ActionInput.for_action(MyApp.Invoice, :generate_pdf, %{invoice_id: "123"})
{:ok, %AshTypst.Document{format: :pdf, data: pdf_binary}} = Ash.run_action(input)

How It Works

1. Templates are declared in the typst section. Each template has either an inline markup string (the ~TYPST sigil is auto-imported inside template blocks) or a source file path relative to the root directory.

2. Render actions reference a template and specify an output format (:pdf, :svg, or :html). They can optionally declare arguments, a read to fetch resource data, and format-specific options like pdf_options.

3. At compile time, the BuildActions transformer converts each render entity into a standard Ash.Resource.Actions.Action.

4. At runtime, the action implementation creates a context, sets the template, injects data (arguments and/or read results) into a virtual file, compiles, and exports in the requested format.

Data Injection

The render action injects data into a virtual file (default "data.typ") that your template can #import:

• No read: only args (a dictionary of action arguments) is available.
• Read :one: both record (the single resource) and args are available.
• Read :many: records (an array, streamed in batches) and args are available.

DSL Reference

For the complete DSL reference with all options, see AshTypst.Resource.

typst

Configuration for Typst template rendering.

Nested DSLs

• template
• render
  • argument
  • read
  • pdf_options
  • prepare
  • validate

Options

typst.template

template name

Declares a reusable Typst template.

Arguments

Options

Introspection

Target: AshTypst.Resource.Template

typst.render

render name

Declares a Typst template rendering action.

Nested DSLs

• argument
• read
• pdf_options
• prepare
• validate

Arguments

Options

typst.render.argument

argument name, type

Declares an argument on the action.

Arguments

Options

Introspection

Target: Ash.Resource.Actions.Argument

typst.render.read

read cardinality

Declares how to fetch resource data to pass to the template.

Arguments

Options

Introspection

Target: AshTypst.Resource.Render.Read

typst.render.pdf_options

PDF-specific export options.

Options

Introspection

Target: AshTypst.Resource.Render.PdfOptions

typst.render.prepare

prepare preparation

Declares a preparation that runs before the template is rendered.

Arguments

Options

Introspection

Target: Ash.Resource.Preparation

typst.render.validate

validate validation

Declares a validation for this action.

Arguments

Options

Introspection

Target: Ash.Resource.Validation

Introspection

Target: AshTypst.Resource.Render