README.Rmd

---
output:
  github_document:
    html_preview: false
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
    warning = FALSE,
    message = FALSE,
    fig.path = "man/figures/README-",
    fig.align = "center",
    out.width = "100%",
    dpi = 75,
    collapse = TRUE,
    comment = "#>"
)
```

# interface

<!-- badges: start -->
[![R-CMD-check](https://github.com/dereckmezquita/interface/workflows/R-CMD-check/badge.svg)](https://github.com/dereckmezquita/interface/actions)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![CRAN status](https://www.r-pkg.org/badges/version/interface)](https://CRAN.R-project.org/package=interface)
[![GitHub version](https://img.shields.io/github/r-package/v/dereckmezquita/interface?label=GitHub)](https://github.com/dereckmezquita/interface)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://cranlogs.r-pkg.org/badges/interface)](https://cran.r-project.org/package=interface)
<!-- badges: end -->

The `interface` package provides a system for defining and implementing interfaces in R, with runtime type checking, bringing some of the benefits of statically-typed languages to R with zero dependencies.

`interface` provides:

1. **Interfaces**: Define and implement interfaces with type checking. Interfaces can be extended and nested.
1. **Typed Functions**: Define functions with strict type constraints.
1. **Typed Frames**: Choose between a `data.frame` or `data.table` with column type constraints and row validation.
1. **Enums**: Define and use enumerated types for stricter type safety.

## Installation

Install the package from CRAN:

```{r eval = FALSE}
install.packages("interface")
```

Or install the latest development version from GitHub:

```{r eval = FALSE}
# Install the package from the source
remotes::install_github("dereckmezquita/interface")
```

## Getting started

Import the package functions.

```{r}
box::use(interface[ interface, type.frame, fun, enum ])
```

Define an interface and implement it:

```{r}
# Define an interface
Person <- interface(
    name = character,
    age = numeric,
    email = character
)

# Implement the interface
john <- Person(
    name = "John Doe",
    age = 30,
    email = "john@example.com"
)

print(john)

# interfaces are lists
print(john$name)

# Modify the object
john$age <- 10
print(john$age)

# Invalid assignment (throws error)
try(john$age <- "thirty")
```

### Extending Interfaces and Nested Interfaces

Create nested and extended interfaces:

```{r}
# Define nested interfaces
Address <- interface(
    street = character,
    city = character,
    postal_code = character
)

Scholarship <- interface(
    amount = numeric,
    status = logical
)

# Extend interfaces
Student <- interface(
    extends = c(Address, Person),
    student_id = character,
    scores = data.table::data.table,
    scholarship = Scholarship
)

# Implement the extended interface
john_student <- Student(
    name = "John Doe",
    age = 30,
    email = "john@example.com",
    street = "123 Main St",
    city = "Small town",
    postal_code = "12345",
    student_id = "123456",
    scores = data.table::data.table(
        subject = c("Math", "Science"),
        score = c(95, 88)
    ),
    scholarship = Scholarship(
        amount = 5000,
        status = TRUE
    )
)

print(john_student)
```

### Custom Validation Functions

Interfaces can have custom validation functions:

```{r}
is_valid_email <- function(x) {
    grepl("[a-z|0-9]+\\@[a-z|0-9]+\\.[a-z|0-9]+", x)
}

UserProfile <- interface(
    username = character,
    email = is_valid_email,
    age = function(x) is.numeric(x) && x >= 18
)

# Implement with valid data
valid_user <- UserProfile(
    username = "john_doe",
    email = "john@example.com",
    age = 25
)

print(valid_user)

# Invalid implementation (throws error)
try(UserProfile(
    username = "jane_doe",
    email = "not_an_email",
    age = "30"
))
```

### Typed Functions

Define functions with strict type constraints:

```{r}
typed_fun <- fun(
    x = numeric,
    y = numeric,
    return = numeric,
    impl = function(x, y) {
        return(x + y)
    }
)

print(typed_fun(1, 2))  # [1] 3
try(typed_fun("a", 2))  # Invalid call
```

Functions with multiple possible return types:

```{r}
typed_fun2 <- fun(
    x = c(numeric, character),
    y = numeric,
    return = c(numeric, character),
    impl = function(x, y) {
        if (is.numeric(x)) {
            return(x + y)
        } else {
            return(paste(x, y))
        }
    }
)

print(typed_fun2(1, 2))  # [1] 3
print(typed_fun2("a", 2))  # [1] "a 2"
```

### Typed `data.frame`s and `data.table`s

Create `data.frame`s with column type constraints and row validation:

```{r}
PersonFrame <- type.frame(
    frame = data.frame, 
    col_types = list(
        id = integer,
        name = character,
        age = numeric,
        is_student = logical
    )
)

# Create a data frame
persons <- PersonFrame(
    id = 1:3,
    name = c("Alice", "Bob", "Charlie"),
    age = c(25, 30, 35),
    is_student = c(TRUE, FALSE, TRUE)
)

print(persons)

# Invalid modification (throws error)
try(persons$id <- letters[1:3])
```

Additional options for `data.frame` validation:

```{r}
PersonFrame <- type.frame(
    frame = data.frame,
    col_types = list(
        id = integer,
        name = character,
        age = numeric,
        is_student = logical,
        gender = enum("M", "F"),
        email = function(x) all(grepl("^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$", x))
    ),
    freeze_n_cols = FALSE,
    row_callback = function(row) {
        if (row$age >= 40) {
            return(sprintf("Age must be less than 40 (got %d)", row$age))
        }
        if (row$name == "Yanice") {
            return("Name cannot be 'Yanice'")
        }
        return(TRUE)
    },
    allow_na = FALSE,
    on_violation = "error"
)

df <- PersonFrame(
    id = 1:3,
    name = c("Alice", "Bob", "Charlie"),
    age = c(25, 35, 35),
    is_student = c(TRUE, FALSE, TRUE),
    gender = c("F", "M", "M"),
    email = c("alice@test.com", "bob_no_valid@test.com", "charlie@example.com")
)

print(df)
summary(df)

# Invalid row addition (throws error)
try(rbind(df, data.frame(
    id = 4,
    name = "David",
    age = 50,
    is_student = TRUE,
    email = "d@test.com"
)))
```

### Enums

Define enums for categorical variables; these are safe to use to protect a value from being modified to invalid options. The `enum` function creates a generator which is then used to create the enum object. This can be used standalone or as part of an interface.

```{r enum}
Colour <- enum("red", "green", "blue")

# Create an enum object
colour <- Colour("red")
print(colour)

colour$value <- "green"
print(colour)

# Invalid modification (throws error)
try(colour$value <- "yellow")

# Use in an interface
Car <- interface(
    make = enum("Toyota", "Ford", "Chevrolet"),
    model = character,
    colour = Colour
)

# Implement the interface
car1 <- Car(
    make = "Toyota",
    model = "Corolla",
    colour = "red"
)

print(car1)

# Invalid implementation (throws error)
try(Car(
    make = "Honda",
    model = "Civic",
    colour = "yellow"
))

# Invalid modification (throws error)
try(car1$colour$value <- "yellow")
try(car1$make$value <- "Honda")
```

## Conclusion

The `interface` package provides powerful tools for ensuring type safety and validation in R. By defining interfaces, typed functions, and typed `data.frame`s, you can create robust and reliable data structures and functions with strict type constraints. For more details, refer to the package documentation.

## License

This package is licensed under the MIT License.

## Citation

If you use this package in your research or work, please cite it as:

Mezquita, D. (2024). interface: A Runtime Type System. R package version 0.1.2. https://github.com/dereckmezquita/interface