KromScript Dart SDK

pub package Release

A lightweight, embeddable scripting language interpreter for Dart/Flutter applications.

📖 Documentation complète : docs-kodiscript.dickode.net

Installation

Add to your pubspec.yaml:

dependencies:
  krom_script: ^1.0.0

Quick Start

import 'package:krom_script/krom_script.dart';

void main() {
  // Simple evaluation
  final result = KromScript.eval('2 + 3 * 4');
  print(result); // 14.0

  // With variables
  final greeting = KromScript.run(
    'greeting + ", " + name + "!"',
    variables: {'greeting': 'Hello', 'name': 'World'},
  );
  print(greeting.value); // "Hello, World!"

  // Capture output
  final output = KromScript.run('''
    let items = ["apple", "banana", "cherry"]
    for (item in items) {
      print(item)
    }
  ''');
  print(output.output); // ["apple", "banana", "cherry"]
}

Features

  • Variables: let x = 10
  • Functions: fn(a, b) { return a + b }
  • Control Flow: if / else if / else, for-in (arrays & maps), while, ternary cond ? a : b
  • Operators: arithmetic, comparison, logical, and compound assignment (+=, -=, *=, /=)
  • Data Types: numbers (whole numbers print without a trailing .0, and reach the host as an int — fractions as a double), strings, booleans, arrays, objects
  • Comments: line // and block /* ... */
  • Null Safety: ?. (safe access), ?: (elvis operator)
  • Safe by default: built-in execution guard (op-budget + deadline)
  • 48+ Native Functions: string, math, range(), random, type, array, JSON, encoding, crypto

🔌 Extensibilité

KromScript est conçu pour être extensible. Vous pouvez enrichir le langage en ajoutant vos propres fonctions natives.

Fonctions personnalisées

final result = KromScript.builder('greet("Dart")')
    .registerFunction('greet', (args) => 'Hello, ${args[0]}!')
    .execute();

print(result.value); // "Hello, Dart!"

Exemple : intégration Flutter

class ScriptEngine {
  final UserRepository userRepo;
  final NotificationService notifications;
  
  ScriptEngine(this.userRepo, this.notifications);
  
  Future<ScriptResult> execute(String script, Map<String, dynamic> context) {
    return KromScript.builder(script)
      .withVariables(context)
      .registerFunction('fetchUser', (args) async {
        return await userRepo.findById(args[0] as int);
      })
      .registerFunction('sendPush', (args) {
        notifications.send(
          title: args[0] as String,
          body: args[1] as String,
        );
        return true;
      })
      .registerFunction('calculatePrice', (args) {
        final quantity = args[0] as num;
        final unitPrice = args[1] as num;
        final discount = args.length > 2 ? args[2] as num : 0;
        return quantity * unitPrice * (1 - discount / 100);
      })
      .execute();
  }
}

Cela permet à vos utilisateurs d'écrire des scripts puissants tout en gardant le contrôle sur les fonctionnalités exposées.

API Reference

KromScript.eval(source, {limits})

Evaluates a script and returns the result value.

KromScript.run(source, {variables, limits})

Runs a script with optional variables and returns ScriptResult.

KromScript.builder(source)

Creates a builder for advanced configuration.

Execution guard

Every entry point runs under ExecutionLimits() — an operation budget and a wall-clock deadline — so an infinite loop fails with a resource error instead of hanging the host. Tune it, or opt out explicitly for trusted first-party code:

// Tighter budget than the default.
KromScript.builder(source)
    .withLimits(const ExecutionLimits(deadline: Duration(milliseconds: 200)))
    .execute();

// No budget, no deadline — trusted code only.
KromScript.builder(source).withLimits(ExecutionLimits.unlimited).execute();

withMaxOperations(n) and withTimeout(d) override one bound each and leave the other at its default.

Native Functions

Category Functions
String toString, toNumber, length, substring, toUpperCase, toLowerCase, trim, split, join, replace, contains, startsWith, endsWith, indexOf
Math abs, floor, ceil, round, min, max, pow, sqrt, sin, cos, tan, log, log10, exp
Random random, randomInt, randomUUID
Type typeOf, isNull, isNumber, isString, isBool
Array size, first, last, reverse, slice, sort
JSON jsonParse, jsonStringify
Encoding base64Encode, base64Decode, urlEncode, urlDecode
Crypto md5, sha1, sha256
Date/Time now, date, time, datetime, timestamp, formatDate, year, month, day, hour, minute, second, dayOfWeek, addDays, addHours, diffDays

Other Implementations

Language Package
Kotlin Maven Central
Go pkg.go.dev
TypeScript npm

License

MIT

Libraries

krom_script
KromScript - A lightweight, embeddable scripting language for Dart.