🥕 Carotene

Appearance

Standard Library ​

In a traditional backend language like Node.js or Go, the standard library is massive. It includes file system access (fs), low-level networking (net), and buffer management.

Carotene operates at a higher architectural level. Because functions execute inside a Zero-Trust Sandbox, you do not have raw access to the file system or the network. Instead, Carotene provides a focused, highly optimized Standard Library designed specifically for writing fast, deterministic business rules before handing off complex logic to the @(...)Generative Operator.

Here are the built-in modules available globally inside any function block.

1. session (Execution Context) ​

The session object is a globally available primitive that contains the context of the user triggering the function. It is primarily used alongside the requires keyword for RBAC (Role-Based Access Control).

  • session.isAuthenticated (Boolean): True if the request provided a valid auth token.
  • session.userId (UUID?): The ID of the authenticated user. Null if anonymous.
  • session.role (String?): The permission tier of the user (e.g., "Admin", "User").
  • session.ip (String): The IP address of the incoming request.
dart
requires session.isAuthenticated
if (session.role != "Admin") {
  rejects with "Insufficient privileges"
}

2. Time (Deterministic Dates) ​

Handling dates and times in traditional languages often leads to flaky tests. The Carotene Time module is entirely deterministic. When running in a test block, it automatically respects the Sandbox's frozen clock.

  • Time.now() -> Date: Returns the current UTC timestamp (or the frozen Sandbox time).
  • Time.addDays(date: Date, days: Int) -> Date: Adds or subtracts days.
  • Time.isAfter(date1: Date, date2: Date) -> Boolean: Compares two timestamps.
  • Time.format(date: Date, format: String) -> String: Outputs a formatted string (e.g., "YYYY-MM-DD").
dart
order = store.Order(orderId)
returnWindow = Time.addDays(order.createdAt, 30)

if (Time.isAfter(Time.now(), returnWindow)) {
  rejects with "Return window has closed"
}

3. Crypto (Security & Hashing) ​

Carotene abstracts away the complexity of choosing the right hashing algorithms (like bcrypt or Argon2) by providing natively secure primitives.

  • Crypto.hashPassword(plain: String) -> String: Generates a salt and hashes the password using industry-standard algorithms.
  • Crypto.verifyPassword(plain: String, hash: String) -> Boolean: Safely compares a password attempt against a hash.
  • Crypto.generateUUID() -> UUID: Generates a secure, v4 UUID.
  • Crypto.sha256(data: String) -> String: Generates a standard SHA-256 hash for data integrity.
dart
// Usually utilized in Identity domains
updates store.User
targetUser.passwordHash = Crypto.hashPassword(newPassword)

4. Math (Sandboxed Calculations) ​

Like the Time module, the Math module is built for testing safety. Any randomness generated here is automatically seeded during carrot dev and carrot build to ensure your AI generation loops remain deterministic.

  • Math.round(val: Float, decimals: Int) -> Float: Rounds a float to a specific decimal place.
  • Math.floor(val: Float) -> Int: Rounds down to the nearest whole number.
  • Math.ceil(val: Float) -> Int: Rounds up to the nearest whole number.
  • Math.random() -> Float: Returns a pseudo-random float between 0 and 1. (Seeded in sandbox).
dart
// Ensuring exact currency formatting before Stripe charges
finalAmount = Math.round(cart.total, 2)

5. Future (Asynchronous Handlers) ​

While Carotene hides most async/await boilerplate behind standard assignment (customer = store.Customer(id) is implicitly awaited), the Future object is required when mocking network integrations or handling explicitly deferred tasks.

  • Future.resolve(value: Any): Instantly resolves with a specific value. Used extensively in mock statements.
  • Future.reject(error: String): Instantly fails with an error string.
dart
// Intercepting an integration to test a successful future
mock integration.Stripe.Charge -> Future.resolve("txn_999")

// Testing a network failure
mock integration.Stripe.Charge -> Future.reject("Card Declined")