neotype

The comptime(...) block allows for compile-time evaluation of Scala-like expressions. Supported constructs include:

• Literals: Int, Long, Float, Double, Boolean, Char, Byte, Short, String, Unit, tuples, and collections.
• Union Types: Supports A | B syntax (e.g., String | Boolean).
• Control Flow: if/else expressions, try/catch/finally expressions (including exception type matching and variable binding), and throw expressions (only for existing Throwable instances, not constructor calls).
• Variables: Blocks with local vals and vars (mutable local variables with assignment).
• Lambdas: Supported when used within standard library operations like map, filter, or foldLeft.
• Member Access: Basic field access is supported when the receiver is a constant (e.g., case class fields).

Pattern matching is fully supported within comptime blocks. You can use:

• Patterns: Literal, wildcard, variable, and typed patterns (case _: T, case x: T).
• Guards: if conditions within cases.
• Alternatives: case a | b syntax.
• Tuple Patterns: Support for Tuple2 through Tuple5.
• Standard Extractors:
  • Option, Either, Try (Some, None, Left, Right, Success, Failure).
  • Collections: List, Vector, Seq, Array, Nil, :: (cons), and _ * (varargs).
  • Regex extractors via "..." .r.
• Custom Extractors: unapply and unapplySeq are supported.
• Binders: @ binders for alternatives and nested patterns.

To measure the performance impact of changes to the rule engine or macro-heavy compile steps, use shell timing with sbt. It is recommended to run each command multiple times and compare the median of 3 runs to account for JVM warm-up.

Baseline Measurement

Run the following commands on your baseline branch:

(time sbt "clean; comptimeJVM/compile")
(time sbt "clean; neotypeJVM/test")

Comparison

Run the same commands on the branch containing the performance improvements and compare the results.

Add the following dependencies to your Scala project. Use the latest version available on Maven Central.

To use the core newtype functionality:

"io.github.kitlangton" %% "neotype" % "x.y.z"

To use the optional comptime engine for compile-time evaluation:

"io.github.kitlangton" %% "comptime" % "x.y.z"

Use Newtype[A] to create a distinct type from an existing type A. By overriding the validate method, you can enforce constraints at compile-time. If the input is a literal or constant expression, apply will perform validation during compilation and raise an error if it fails. For runtime values, use make or makeOrThrow.

// DEFINITION
type Digits = Digits.Type
object Digits extends Newtype[String]:
  override inline def validate(value: String) = 
    value.forall(_.isDigit)

// COMPILE-TIME VALIDATION
Digits("123") // Compiles successfully.
Digits("abc") // Fails to compile due to validation.

// RUN-TIME VALIDATION
val input = "123"
Digits.make(input) // Right(Digits("123"))

val bad = "abc"
Digits.make(bad) // Left("String must be numeric")

The following features are not guaranteed to work in comptime blocks unless explicitly covered by the test suite:

• Loops: while loops are not supported.
• Lazy Values: lazy val is not supported.
• Exception Constructors: new RuntimeException("msg") is not supported; use existing Throwable instances instead.
• Arbitrary Methods: Any method call outside the whitelisted standard library rules.
• Reflection/IO: General reflection or IO (except for comptime.readFile and comptime.readFileBytes).
• Variable Limitations:
  • Functions in vars: You cannot store a lambda in a var and then call it (e.g., var f = (x: Int) => x + 1; f(1) will fail).
  • Unused val exceptions: If a var is in scope, an unused val whose initializer would throw an exception might not actually throw.

You can read files at compile time using the comptime helper module. Paths resolve relative to the call site.

Note: File changes do not automatically trigger recompilation; these APIs should be treated like embedded constants.

// Reads file as String
val content = comptime.readFile("config.txt", "UTF-8")

// Reads file as bytes
val bytes = comptime.readFileBytes("data.bin")