🔌 Extensibility

KodiScript is designed to be extensible. You can enrich the language by adding your own native functions, allowing scripts to interact with your system while maintaining full control over what’s exposed.

Why Extensibility?

The built-in native functions cover common use cases, but your application likely has unique requirements:

Database access: Let scripts fetch users, orders, or any data
Notifications: Send emails, push notifications, SMS from scripts
Business logic: Calculate discounts, validate rules, process workflows
External APIs: Call third-party services securely
File operations: Read/write files with proper permissions

Function Registration

Each SDK provides a registerFunction method that lets you add custom functions callable from KodiScript:

val result = KodiScript.builder("""
    let user = fetchUser(123)
    let discount = calculateDiscount(user.tier, 100)
    print("Discount: " + discount + "%")
""")
    .registerFunction("fetchUser") { args ->
        // Call your database
        mapOf("id" to args[0], "name" to "Alice", "tier" to "gold")
    }
    .registerFunction("calculateDiscount") { args ->
        val tier = args[0] as String
        when (tier) {
            "gold" -> 20
            "silver" -> 10
            else -> 5
        }
    }
    .execute()

script := kodi.New(`
    let user = fetchUser(123)
    let discount = calculateDiscount(user.tier, 100)
    print("Discount: " + discount + "%")
`)
 
script.RegisterFunction("fetchUser", func(args ...interface{}) (interface{}, error) {
    id := args[0].(float64)
    return map[string]interface{}{
        "id": id, "name": "Alice", "tier": "gold",
    }, nil
})
 
script.RegisterFunction("calculateDiscount", func(args ...interface{}) (interface{}, error) {
    tier := args[0].(string)
    switch tier {
    case "gold": return 20, nil
    case "silver": return 10, nil
    default: return 5, nil
    }
})
 
result := script.Execute()

final result = KodiScript.builder('''
    let user = fetchUser(123)
    let discount = calculateDiscount(user.tier, 100)
    print("Discount: " + discount + "%")
''')
    .registerFunction('fetchUser', (args) {
        // Call your database
        return {'id': args[0], 'name': 'Alice', 'tier': 'gold'};
    })
    .registerFunction('calculateDiscount', (args) {
        final tier = args[0] as String;
        switch (tier) {
            case 'gold': return 20;
            case 'silver': return 10;
            default: return 5;
        }
    })
    .execute();

const result = KodiScript.builder(`
    let user = fetchUser(123)
    let discount = calculateDiscount(user.tier, 100)
    print("Discount: " + discount + "%")
`)
    .registerFunction('fetchUser', (id) => {
        // Call your database
        return { id, name: 'Alice', tier: 'gold' };
    })
    .registerFunction('calculateDiscount', (tier, amount) => {
        const discounts = { gold: 20, silver: 10, bronze: 5 };
        return discounts[tier] || 0;
    })
    .execute();

$result = KodiScript::builder('
    let user = fetchUser(123)
    let discount = calculateDiscount(user.tier, 100)
    print("Discount: " + discount + "%")
')
    ->registerFunction('fetchUser', fn($id) => [
        'id' => $id,
        'name' => 'Alice',
        'tier' => 'gold',
    ])
    ->registerFunction('calculateDiscount', function($tier, $amount) {
        return match($tier) {
            'gold' => 20,
            'silver' => 10,
            default => 5,
        };
    })
    ->execute();

Object Binding v0.1.1

Starting from version 0.1.1, you can bind entire objects to the script context. This allows scripts to access properties and call methods on your native objects directly, without wrapping each method in a registerFunction call.

class UserService(private val db: Database) {
    fun findUser(id: Int): User? = db.findUser(id)
    fun createUser(name: String, email: String): User = db.createUser(name, email)
    val userCount: Int get() = db.countUsers()
}
 
val service = UserService(myDatabase)
 
val result = KodiScript.builder("""
    let user = service.findUser(42)
    let total = service.userCount
    print("Found user: " + user.name)
""")
    .bind("service", service)  // Bind the entire object
    .execute()

type UserService struct {
    db *Database
}
 
func (s *UserService) FindUser(id int) *User {
    return s.db.FindUser(id)
}
 
func (s *UserService) UserCount() int {
    return s.db.CountUsers()
}
 
service := &UserService{db: myDatabase}
 
script := kodi.New(`
    let user = service.FindUser(42)
    let total = service.UserCount()
    print("Found user: " + user.Name)
`)
script.Bind("service", service)
result := script.Execute()

class UserService {
  final Database db;
  UserService(this.db);
  
  User? findUser(int id) => db.findUser(id);
  User createUser(String name, String email) => db.createUser(name, email);
  int get userCount => db.countUsers();
}
 
final service = UserService(myDatabase);
 
final result = KodiScript.builder('''
    let user = service.findUser(42)
    let total = service.userCount
    print("Found user: " + user.name)
''')
    .bind('service', service)
    .execute();

class UserService {
  constructor(private db: Database) {}
  
  findUser(id: number): User | null {
    return this.db.findUser(id);
  }
  
  createUser(name: string, email: string): User {
    return this.db.createUser(name, email);
  }
  
  get userCount(): number {
    return this.db.countUsers();
  }
}
 
const service = new UserService(myDatabase);
 
const result = KodiScript.builder(`
    let user = service.findUser(42)
    let total = service.userCount
    print("Found user: " + user.name)
`)
    .bind('service', service)
    .execute();

class UserService {
    public function __construct(private Database $db) {}
    
    public function findUser(int $id): ?User {
        return $this->db->findUser($id);
    }
    
    public function createUser(string $name, string $email): User {
        return $this->db->createUser($name, $email);
    }
    
    public function getUserCount(): int {
        return $this->db->countUsers();
    }
}
 
$service = new UserService($myDatabase);
 
$result = KodiScript::builder('
    let user = service.findUser(42)
    let total = service.getUserCount()
    print("Found user: " + user.name)
')
    ->bind('service', $service)
    ->execute();

When to Use `bind` vs `registerFunction`

Approach	Use Case
`bind()`	Expose an entire service or object with multiple methods/properties
`registerFunction()`	Expose individual functions with custom logic or validation

You can combine both approaches:

KodiScript.builder(script)
    .bind("userService", userService)
    .bind("cartService", cartService)
    .registerFunction("calculateTax") { args -> taxCalculator.compute(args) }
    .execute()

Real-World Example: E-commerce Rules Engine

Imagine letting your business team define discount rules without deploying code:

// Script stored in database, editable by admins
let user = getUser(userId)
let cart = getCart(cartId)
 
let discount = 0
 
// Gold members get 20% off
if (user.tier == "gold") {
    discount = 20
}
 
// Extra 5% for orders over $100
if (cart.total > 100) {
    discount = discount + 5
}
 
// Holiday special
if (isHolidaySeason()) {
    discount = min(discount + 10, 50)  // Cap at 50%
}
 
// Apply and notify
let finalPrice = cart.total * (1 - discount / 100)
sendNotification(user.email, "Your discount: " + discount + "%")
 
return { discount: discount, finalPrice: finalPrice }

Your backend exposes only the functions you choose:

KodiScript.builder(adminScript)
    .withVariable("userId", request.userId)
    .withVariable("cartId", request.cartId)
    .registerFunction("getUser") { userService.findById(it[0] as Long) }
    .registerFunction("getCart") { cartService.findById(it[0] as Long) }
    .registerFunction("isHolidaySeason") { holidayService.isActive() }
    .registerFunction("sendNotification") { notificationService.send(it[0], it[1]) }
    .execute()

Security Best Practices

When exposing functions to scripts:

Validate inputs - Never trust script arguments blindly
Limit scope - Only expose what’s necessary
Rate limit - Prevent abuse of expensive operations
Audit logs - Track what scripts execute
Sandbox - Scripts can’t access anything you don’t explicitly provide

// ✅ Good: Scoped, validated function
.registerFunction("getUser") { args ->
    val id = (args[0] as? Number)?.toLong() 
        ?: throw IllegalArgumentException("Invalid user ID")
    userService.findById(id)?.toSafeMap() // Only expose safe fields
}
 
// ❌ Bad: Too permissive
.registerFunction("query") { args ->
    database.executeRaw(args[0] as String) // SQL injection risk!
}

Use Cases

Use Case	Custom Functions
E-commerce	`getUser`, `getCart`, `applyDiscount`, `sendEmail`
Workflow Engine	`approve`, `reject`, `escalate`, `notify`
Data Processing	`fetchRecord`, `transform`, `validate`, `save`
IoT/Automation	`readSensor`, `setDevice`, `scheduleTask`
Gaming	`getPlayer`, `giveReward`, `checkAchievement`

Next Steps

Explore the SDK Reference for your platform
Check Native Functions for built-in capabilities
See Variables for injecting context

Native Functions Security & Limits