API Reference

Core Functions

typed_function(fn, params, .return)

Wraps a function with runtime type checks for its parameters and, optionally, its return value.

Parameters: - fn: The function to wrap. Its formals are preserved so callers use the same signature. - params: A named list mapping parameter names to their types (e.g. list(x = Numeric, y = String)). Only listed parameters are checked. Defaults to an empty list (no parameter checking). - .return: Optional return type. When NULL (the default), the return value is not checked. Accepts any sicher_type or sicher_union.

Returns: A function with S3 class "sicher_typed_function" that validates types on every call and delegates argument passing to fn unchanged.

Example:

add <- typed_function(
  function(x, y) x + y,
  params  = list(x = Numeric, y = Numeric),
  .return = Numeric
)

greet <- typed_function(
  function(name, title = NULL) {
    if (is.null(title)) paste("Hello,", name)
    else paste("Hello,", title, name)
  },
  params = list(name = String, title = Optional(String))
)

create_type(name, checker)

Creates a new type with a name and validation function.

Parameters: - name: Character string for error messages - checker: Function that returns TRUE/FALSE for validation

Example:

Positive <- create_type("positive", function(x) is.numeric(x) && all(x > 0))

create_list_type(type_spec)

Creates a type for lists with specific field requirements.

Parameters: - type_spec: Named list where names are field names and values are types

Example:

Person <- create_list_type(list(name = String, age = Numeric))

create_dataframe_type(col_spec)

Creates a type for data frames with column specifications.

Parameters: - col_spec: Named list where names are column names and values are types

Example:

Table <- create_dataframe_type(list(id = Integer, name = String))

ListOf(element_type)

Creates a type for homogeneous lists.

Parameters: - element_type: Type that each list element must satisfy

Example:

Numbers <- ListOf(Numeric)

Type Modifiers

Scalar(type)

Requires exactly one element (length 1).

Example:

SingleValue <- Scalar(Numeric)

Readonly(type)

Prevents reassignment after initial value.

Example:

Constant <- Readonly(String)

Optional(type)

Allows NULL in addition to the base type.

Example:

MaybeString <- Optional(String)

Operators

%:%

Type annotation operator.

Usage:

variable %:% Type

%<-%

Typed assignment operator.

Usage:

variable %:% Type %<-% value

|

Union operator for combining types.

Example:

StringOrNumber <- (String | Numeric)

[size]

Size constraint operator.

Example:

ThreeNumbers <- Numeric[3]

Built-in Types

Primitive Types

• Integer: Integer vectors
• Double: Double-precision numeric vectors
• Numeric: Any numeric vectors
• String: Character vectors
• Bool: Logical vectors
• List: List objects
• Any: Accepts any value
• Null: Only NULL values
• Function: Function objects
• DataFrame: Data frame objects

Error Handling

Type errors provide detailed context:

x %:% Numeric %<-% "text"

Error: Type error in 'x': Expected numeric, got string
Received: text

Error messages include: - Expected type - Actual type - Variable name (when available) - Value preview (for debugging)