eskema 2.0.0

Eskema is a small, composable runtime validation library for Dart. It helps you validate dynamic values (JSON, Maps, Lists, primitives) with readable validators and clear error messages.

Eskema

Composable runtime validation for Dart. Build readable schemas from tiny validator functions & operators and get precise, structured errors (message, code, path, data) for untyped JSON, configs, and user input. Fast sync path, seamless async, no boilerplate.

Why

• Validate untyped JSON & config fast
• Concise composition (&, |, not(), nullable(), optional())
• Sync fast path, auto async when needed
• Rich Expectation objects: message, code, path, data
• Extensively tested

Install

dart pub add eskema

Core example (from example/readme_example.dart)

import 'package:eskema/eskema.dart';

void main() {
  final userValidator = eskema({
    'username': isString(),                  // basic type check
    'lastname': $isString,                   // cached zero‑arg variant
    'age': all([isInt(), isGte(0)]),         // multi validator (AND)
    'theme': isString() & (isEq('light') | isEq('dark')), // operators
    'premium': nullable($isBool),            // key must exist; value may be null
    'birthday': optional(isDate()),          // key may be absent
  });

  final ok = userValidator.validate({
    'username': 'bob', 'lastname': 'builder', 'theme': 'light', 'age': 42,
  });
  print(ok); // missing premium (nullable != optional)

  final res = userValidator.validate({'username': 'alice', 'age': -1});
  print(res.isValid);        // false
  print(res.expectations);   // structured reasons (age invalid, missing keys, etc.)
}

How it works

1. Build a schema with eskema({...}) (map of field -> validator)
2. Compose validators with functions (isString(), isGte(0), all([...])) or operators (&, |)
3. Add modifiers: nullable() (value may be null) vs optional() (key may be absent)
4. Call validate(value) (sync chain) or validateAsync(value) if any link is async
5. Inspect Result.isValid & Result.expectations or throw via validateOrThrow()

Reading failures

Each failure is an Expectation having:

• message – human text
• code – stable identifier (see expectation codes doc)
• path – location (e.g. .user.address[0].city)
• data – structured metadata

More examples

See the example/ directory for:

• transformers (toInt, defaultTo, trim)
• conditional validation (when + getField)
• custom validators & builders
• list & strict schema validation

Docs & help

• Docs & guides
• API reference
• Wiki
• Issues / questions: https://github.com/nombrekeff/eskema/issues

Contributing

Open an issue for discussion, then PR with tests. Keep additions composable. (Detailed guidelines live in the wiki / future CONTRIBUTING doc.)

License

MIT – see LICENSE.

---

Star the repo if it helps you. ⭐