@ Constants Reference

Adama has a collection of special constants prefixed with @ that give you access to contextual information during execution. Some of these (@who, @no_one) you'll use constantly; others (@headers, @parameters) only show up in web handlers. This page documents all of them.

Identity Constants

@who

The current authenticated principal (user identity) in the execution context. This is probably the @ constant you'll use most.

Type: principal

Availability:

Channels (complete and incomplete)
@connected and @disconnected handlers
@construct handler
Privacy policies
Bubbles
Web handlers (when authenticated)

Example:

message Message {
  string text;
}

record Item {
  public principal owner;
  public string text;
}

table<Item> items;

record Msg {
  public principal sender;
  public string text;
}

table<Msg> _messages;

private principal owner;

@construct {
  owner = @who;  // Store the creator as owner
}

channel sendMessage(Message msg) {
  // @who is the sender
  _messages <- {sender: @who, text: msg.text};
}

policy is_owner {
  return @who == owner;
}

bubble my_items = iterate items where owner == @who;

Notes:

In @cron jobs, @who is @no_one (no user context)
In @static blocks, @who represents the user attempting the operation
Comparisons with @who are the bread and butter of privacy policies

@no_one

A special principal constant representing "nobody." The absence of a user identity -- anonymous, null user, however you want to think about it.

Type: principal

Availability: Everywhere

Example:

message Empty {}

private principal assigned_to;

@construct {
  assigned_to = @no_one;  // Not assigned to anyone initially
}

policy has_assignment {
  return assigned_to != @no_one;
}

channel claim(Empty msg) {
  if (assigned_to == @no_one) {
    assigned_to = @who;
  }
}

Common Patterns:

private principal owner;
private principal winner = @no_one;

@connected {
  // Check if user is authenticated
  if (@who != @no_one) {
    // User is authenticated
  }

  // Check if a principal field is set
  if (owner == @no_one) {
    // No owner assigned
  }
  return true;
}

Web Handler Constants

@web

Marker constant indicating the web handler context. Used in return statements to construct web responses.

Type: Context marker (not directly usable as a value)

Availability: Web handlers only (@web get, @web put, etc.)

Example:

@web get /status {
  return {
    json: { status: "ok", time: Time.datetime() }
  };
}

@web get /page {
  return {
    html: "<html><body><h1>Hello</h1></body></html>"
  };
}

Response Fields:

Field	Type	Description
`json`	message/object	JSON response body
`html`	string	HTML response body
`xml`	string	XML response body
`css`	string	CSS response body
`js`	string	JavaScript response body
`asset`	asset	File download
`error`	string	Error response
`forward`	string	HTTP 302 redirect
`redirect`	string	HTTP 301 redirect
`sign`	principal	Create signed JWT
`identity`	string	Pre-signed identity
`cors`	bool	Enable CORS headers
`cache_ttl_seconds`	int	Cache duration

@headers

HTTP request headers available in web handlers. Gives you access to all headers sent with the HTTP request.

Type: map<string, string>

Availability: Web handlers only

Example:

private string expected_api_key;

message DataMessage {
  string value;
}

@web get /info {
  let userAgent = @headers["User-Agent"];
  let authHeader = @headers["Authorization"];
  let contentType = @headers["Content-Type"];

  return {
    json: {
      user_agent: userAgent,
      has_auth: authHeader != ""
    }
  };
}

@web put /api/data (DataMessage data) {
  // Check API key in header
  if (@headers["X-API-Key"] != expected_api_key) {
    return {
      json: { error: "Invalid API key" }
    };
  }
  return {
    json: { success: true }
  };
}

Common Headers:

Authorization - Authentication credentials
Content-Type - Request body type
User-Agent - Client identifier
Accept - Acceptable response types
X-Forwarded-For - Original client IP (behind proxy)
Custom headers (X-*)

@parameters

URL query string parameters available in web handlers. A dynamic value containing whatever was in the query string.

Type: dynamic

Availability: Web handlers only

Example:

@web get /search {
  // @parameters is a dynamic value containing all query string params
  // For URL: /search?q=hello&page=2&limit=10
  return {
    json: {
      params: @parameters
    }
  };
}

@web get /filter {
  // For URL: /filter?category=books&sort=price
  return {
    json: {
      params: @parameters
    }
  };
}

Notes:

Parameter values are always strings
Use type conversion for numeric operations
Missing parameters return empty string or null

Viewer Constants

@viewer

Access to viewer-specific state sent by the connected client. Used in bubbles to create personalized views based on what the client told you about itself.

Type: Record containing all view field values

Availability: Bubble expressions only

Example:

// Declare viewer state fields
view int page_number;
view int page_size;
view string category_filter;

record Product {
  public string name;
  public string category;
  public double price;
}

table<Product> products;

// Bubble using viewer state for pagination
bubble paginated_products = iterate products
  where @viewer.category_filter == "" || category == @viewer.category_filter
  offset @viewer.page_number * @viewer.page_size
  limit @viewer.page_size;

View Field Types:

view int scroll_position;
view string search_query;
view bool show_archived;
view string selected_tab;

Notes:

Viewer state is set by the client connection
Each connected viewer has independent state
Changes to viewer state trigger bubble recalculation
Can't be used outside of bubble expressions

Execution Context

@context

Execution context metadata -- origin information, request details, that sort of thing.

Type: Context object with properties

Availability:

@static blocks (create/invent policies)
@connected handler
Web handlers

Properties:

Property	Type	Description
`.origin`	string	Request origin URL
`.ip`	string	Client IP address
`.key`	string	Document key being accessed

Example:

@static {
  create {
    // Only allow creation from specific origin
    return @context.origin == "https://myapp.com" ||
           @context.origin == "https://staging.myapp.com";
  }

  invent {
    // Log the IP attempting to invent
    return true;
  }
}

@connected {
  // Check origin for connection
  if (@context.origin != "https://myapp.com") {
    return false;
  }
  return true;
}

Test Constants

@blocked

Returns true if the document is currently blocked waiting for external input (typically an async channel fetch). Only available in tests -- it's how you verify that your state machine is actually blocking where you expect it to.

Type: bool

Availability: Test blocks only

Example:

message Response {
  int value;
}

channel<Response> respond;
int captured;

@construct {
  transition #waiting;
}

#waiting {
  future<Response> f = respond.fetch(@no_one);
  Response r = f.await();
  captured = r.value;
}

test AsyncBehavior {
  assert !(@blocked);     // Not blocked initially

  @step;                  // Start state machine

  assert @blocked;        // Now blocked waiting for response

  @pump {value: 42} into respond;

  assert @blocked;        // Still blocked (message queued)

  @step;                  // Process message

  assert !(@blocked);     // No longer blocked
  assert captured == 42;
}

Notes:

Only available in test blocks
Used to verify state machine blocking behavior
Combine with @step and @pump for async testing

Value Construction Constants

@nothing

The empty/null asset constant. An asset field with no file attached.

Type: asset

Availability: Everywhere

Example:

message Empty {}

private asset profile_picture = @nothing;

public formula hasProfilePicture = profile_picture != @nothing;

channel clearPicture(Empty msg) {
  profile_picture = @nothing;
}

@maybe(value)

Constructs a maybe<T> containing the given value.

Type: maybe<T> where T is the type of the argument

Availability: Everywhere

Example:

maybe<int> score = @maybe(100);
maybe<string> name = @maybe("Alice");

@construct {
  // Unwrap with pattern matching
  if (score as s) {
    int doubled = s * 2;
  }
}

@date(year, month, day)

Constructs a date value.

Type: date

Availability: Everywhere

Example:

date birthday = @date 1990/6/15;
date today = @date 2025/1/15;

@time(hour, minute)

Constructs a time value.

Type: time

Availability: Everywhere

Example:

time morning = @time 9:30;     // 9:30 AM
time evening = @time 18:00;    // 6:00 PM

@datetime(iso_string)

Constructs a datetime value from an ISO 8601 string.

Type: datetime

Availability: Everywhere

Example:

datetime event = @datetime "2025-06-15T14:30:00-05:00";

@timespan(seconds)

Constructs a timespan (duration) value.

Type: timespan

Availability: Everywhere

Example:

timespan a_minute = @timespan 60.0 sec;
timespan also_minute = @timespan 1.0 min;
timespan an_hour = @timespan 1.0 hr;

@c(real, imaginary)

Constructs a complex number.

Type: complex

Availability: Everywhere

Example:

complex z = 3.0 + 4.0 * @i;  // 3 + 4i

@vec(components...)

Constructs a vector (vec2, vec3, or vec4 based on argument count).

Type: vec2, vec3, or vec4

Availability: Everywhere

Example:

vec2 position = @vec[10.0, 20.0];
vec3 point = @vec[1.0, 2.0, 3.0];
vec4 color = @vec[1.0, 0.5, 0.0, 1.0];

@dynamic(json_string)

Constructs a dynamic value from a JSON string.

Type: dynamic

Availability: Everywhere

Example:

dynamic data;

@convert (value)

Converts a value to the specified type.

Type: Target type T

Availability: Everywhere

Example:

int i = 42;
double d = @convert<double>(i);   // 42.0
string s = @convert<string>(i);   // "42"
long l = @convert<long>(i);       // 42L

Summary Table

Constant	Type	Context	Description
`@who`	`principal`	Channels, handlers, policies, bubbles	Current authenticated user
`@no_one`	`principal`	Everywhere	Empty/anonymous principal
`@web`	context	Web handlers	Web response context
`@headers`	`map<string,string>`	Web handlers	HTTP request headers
`@parameters`	`dynamic`	Web handlers	URL query parameters
`@viewer`	record	Bubbles	Client viewer state
`@context`	object	Static blocks, handlers	Execution context metadata
`@blocked`	`bool`	Tests	Document blocking state
`@nothing`	`asset`	Everywhere	Empty asset value
`@maybe(v)`	`maybe<T>`	Everywhere	Construct maybe value
`@date(y,m,d)`	`date`	Everywhere	Construct date
`@time(h,m)`	`time`	Everywhere	Construct time
`@datetime(s)`	`datetime`	Everywhere	Construct datetime
`@timespan(s)`	`timespan`	Everywhere	Construct timespan
`@c(r,i)`	`complex`	Everywhere	Construct complex number
`@vec(...)`	`vec2/3/4`	Everywhere	Construct vector
`@dynamic(s)`	`dynamic`	Everywhere	Construct dynamic value
`@convert<T>(v)`	`T`	Everywhere	Type conversion

@ Constants Reference#

Identity Constants#

@who#

@no_one#

Web Handler Constants#

@web#

@headers#

@parameters#

Viewer Constants#

@viewer#

Execution Context#

@context#

Test Constants#

@blocked#

Value Construction Constants#

@nothing#

@maybe(value)#

@date(year, month, day)#

@time(hour, minute)#

@datetime(iso_string)#

@timespan(seconds)#

@c(real, imaginary)#

@vec(components...)#

@dynamic(json_string)#

@convert (value) #

Summary Table#

@ Constants Reference

Identity Constants

@who

@no_one

Web Handler Constants

@web

@headers

@parameters

Viewer Constants

@viewer

Execution Context

@context

Test Constants

@blocked

Value Construction Constants

@nothing

@maybe(value)

@date(year, month, day)

@time(hour, minute)

@datetime(iso_string)

@timespan(seconds)

@c(real, imaginary)

@vec(components...)

@dynamic(json_string)

@convert (value)

Summary Table