jetson library

🌐 JetLeaf Jetson Object Mapping & Serialization Library

Jetson provides a comprehensive framework for serializing and deserializing objects across multiple formats, including:

JSON
XML
YAML

It supports advanced features such as:

annotation-driven object mapping
pluggable adapters and serializers
naming strategies
context-aware serialization/deserialization
validation of structured data

This library is intended for robust data binding and format conversions in JetLeaf applications.

🔑 Core Concepts

🧱 Base Infrastructure

Generator, Node, ObjectMapper, ObjectMapperType, Parser — foundational abstractions for all object mapping operations

🔄 Serialization & Deserialization

BaseSerializer, ObjectSerializer, ObjectDeserializer
SerializationContext / DeserializationContext
SerializationFeature / DeserializationFeature
ObjectSerializable — marker interface for serializable objects

⏱ Common Adapters & Helpers

StandardSerializers, StandardDeserializers — default implementations
TimeSerializationAdapters — adapters for handling date/time types

🔧 Jetson Core Mappers

JetsonObjectMapper — main object mapper implementation
AbstractJsonObjectMapper, AbstractXmlObjectMapper, AbstractYamlObjectMapper
AbstractAwareObjectMapper — advanced context-aware mapping

📄 JSON Support

Node types: JsonNode, JsonArrayNode, JsonMapNode, JsonTextNode, JsonBooleanNode, JsonNumberNode, JsonNullNode
Generators: JsonGenerator, StringJsonGenerator
Parsers: JsonParser, StringJsonParser
Adapters: JsonAdapter, DartJsonSerializationAdapter, List/Map/SetJsonSerializationAdapter
JsonObjectMapper, JsonToken, JsonDeserializationContext, JsonSerializationContext
JsonValidator — validates JSON content

📄 XML Support

Node types: XmlNode, XmlElementNode, XmlTextNode
Generators: XmlGenerator, StringXmlGenerator
Parsers: XmlParser, StringXmlParser
Adapters: XmlAdapter, DartXmlSerializationAdapter, List/Map/SetXmlSerializationAdapter
XmlObjectMapper, XmlToken, XmlDeserializationContext, XmlSerializationContext

📄 YAML Support

Node types: YamlNode, YamlMapNode, YamlScalarNode, YamlSequenceNode, YamlNodeType
Generators: YamlGenerator, StringYamlGenerator
Parsers: YamlParser, StringYamlParser
Adapters: YamlAdapter, DartYamlSerializationAdapter, List/Map/SetYamlSerializationAdapter
YamlObjectMapper, YamlToken, YamlDeserializationContext, YamlSerializationContext

🏷 Annotations & Naming Strategies

annotations.dart — declarative mapping and serialization annotations
naming_strategy.dart / naming_strategies.dart — control field name transformations

⚠ Exception Handling

exceptions.dart — framework-level exception types

🛠 Utilities

jetson_utils.dart — helper functions for common mapping operations

🎯 Intended Usage

Import this library for advanced object mapping and format conversions:

import 'package:jetson/jetson.dart';

final mapper = JetsonObjectMapper();
final json = mapper.serializeToJson(myObject);
final obj = mapper.deserializeFromJson<MyClass>(json);

Supports annotation-driven mapping, custom adapters, context-aware serialization, and validation for multiple formats (JSON, XML, YAML).

Classes

AbstractAwareObjectMapper: An enhanced, application-aware Jetson object mapper that integrates seamlessly with the JetLeaf dependency injection, environment system, and conversion infrastructure.
AbstractJsonObjectMapper: A high-level, multi-format Jetson object mapper with integrated support for JSON, XML, and YAML serialization and deserialization.
AbstractXmlObjectMapper: Abstract base implementation of XmlObjectMapper providing core XML serialization and deserialization functionality.
AbstractYamlObjectMapper: Abstract base implementation of YamlObjectMapper extending AbstractXmlObjectMapper to provide YAML-specific serialization/deserialization.
BaseSerializer: Base interface for all serializers within the JetLeaf mapping framework.
BoolDeserializer>: Deserializes JSON boolean-like values into Dart bool instances.
BoolSerializer<G extends Generator, C extends SerializationContext<Generator>>: Serializes Dart bool values into JSON boolean values.
CamelCaseNamingStrategy: Leaves field names unchanged (camelCase).
DartJsonSerializationAdapter: Provides a generic serialization and deserialization adapter for Dart classes using reflection within the JetLeaf JSON subsystem.
DartXmlSerializationAdapter
DartYamlSerializationAdapter
DateTimeSerializationAdapter<G extends Generator, P extends Parser, DC extends DeserializationContext<Parser>, SC extends SerializationContext<Generator>>: Serializes and deserializes Dart ZonedDateTime values to and from strings.
DeserializationContext: A stateful, format-agnostic deserialization context that coordinates all operations required to convert parser tokens into Dart object graphs.
DoubleDeserializer>: Deserializes JSON numeric values into Dart double instances.
DoubleSerializer<G extends Generator, C extends SerializationContext<Generator>>: Serializes Dart double values into JSON numeric values.
DurationSerializationAdapter<G extends Generator, P extends Parser, DC extends DeserializationContext<Parser>, SC extends SerializationContext<Generator>>: Serializes and deserializes Dart Duration values to and from JSON-compatible representations.
FromJson<T>: A constraint annotation for generating instances of a class from a JSON map representation.
Generator: A low-level, format-agnostic output writer used by Jetson's serialization pipeline.
IntDeserializer>: Deserializes JSON numeric values into Dart int instances.
IntSerializer<G extends Generator, C extends SerializationContext<Generator>>: Serializes Dart int values into JSON numeric values.
JetsonObjectMapper: A high-level, multi-format Jetson object mapper with integrated support for JSON, XML, and YAML serialization and deserialization.
JetsonUtils: Utility class providing object construction helpers for Dart types.
JsonArrayNode: Represents a JSON array node ([...]) in the Dart JSON model.
JsonBooleanNode: Represents a JSON boolean node (true or false) in the Dart JSON model.
JsonConverter<T extends ObjectSerializable>: Annotation used to associate a custom JSON converter with a class field or property.
JsonCreator: Annotation to designate a constructor as the primary entry point for JSON deserialization.
JsonDeserializationContext: Default implementation of DeserializationContext in JetLeaf’s JSON subsystem.
JsonDeserializer<T>: A specialization of ObjectDeserializer for JSON deserialization using a JsonParser.
JsonField: Annotation to customize how a class field is serialized to and deserialized from JSON.
JsonGenerator: A streaming JSON writer that outputs JSON tokens sequentially.
JsonIgnore: Marks a Dart field, getter, or setter to be ignored during JSON serialization and deserialization.
JsonMapNode: Represents a JSON object node ({...}) in the Dart JSON model.
JsonNode<ObjectType>: Base class for all JSON nodes in the Dart model.
JsonNullNode: Represents a JSON null node (null) in the Dart JSON model.
JsonNumberNode: Represents a JSON numeric node in the Dart JSON model.
JsonObjectMapper: Provides a unified abstraction for object serialization and deserialization within the JetLeaf framework.
JsonOutput: Annotation to designate a method as the primary JSON output provider for an object.
JsonParser: A parser for JSON configuration files.
JsonSerializationAdapter<T>: A bidirectional JSON converter that implements both ObjectSerializer and ObjectDeserializer for type T.
JsonSerializationContext: Default implementation of SerializationContext for JetLeaf’s JSON subsystem.
JsonSerializer<T>: A specialization of ObjectSerializer for JSON serialization using a JsonGenerator.
JsonTextNode: Represents a JSON string node in the Dart JSON model.
JsonValidator: Utility class for validating JSON structures and content.
KebabCaseNamingStrategy: Converts field names from camelCase to kebab-case and vice versa.
ListJsonSerializationAdapter: Handles serialization and deserialization of List objects in JetLeaf’s JSON subsystem.
ListXmlSerializationAdapter
ListYamlSerializationAdapter
LocalDateSerializationAdapter<G extends Generator, P extends Parser, DC extends DeserializationContext<Parser>, SC extends SerializationContext<Generator>>: Serializes and deserializes Dart LocalDate values to and from ISO-8601 strings.
LocalDateTimeSerializationAdapter<G extends Generator, P extends Parser, DC extends DeserializationContext<Parser>, SC extends SerializationContext<Generator>>: Serializes and deserializes Dart LocalDateTime values to and from ISO-8601 strings.
MapJsonSerializationAdapter: Handles serialization and deserialization of Map objects in JetLeaf’s JSON subsystem.
MapXmlSerializationAdapter
MapYamlSerializationAdapter
NamingStrategy: Provides a unified interface for field name transformation between Dart-style and JSON-style representations.
Node<ObjectType>: Generic interface representing a parsed node in JetLeaf's structured data model (JSON/YAML/other).
NumDeserializer>: Deserializes JSON numeric values into Dart num instances.
NumSerializer<G extends Generator, C extends SerializationContext<Generator>>: Serializes Dart num values into JSON numeric values.
ObjectDeserializer<T, P extends Parser, Context extends DeserializationContext<Parser>>: A generic, pluggable object deserializer responsible for converting structured data (parsed through a Parser) into fully-typed Dart objects.
ObjectMapper: Provides a unified abstraction for object serialization and deserialization within the JetLeaf framework.
ObjectSerializable: Marker interface for all Jetson object (de)serialization components.
ObjectSerializer<T, G extends Generator, Context extends SerializationContext<Generator>>: A generic, extensible object serializer responsible for converting Dart objects into structured, generator-friendly representations (such as JSON objects, YAML maps, or custom AST nodes).
Parser<Token>: Base interface for all token-based streaming parsers.
SerializationContext<G extends Generator>: A stateful, format-agnostic serialization context responsible for orchestrating Jetson’s object-to-structure serialization pipeline.
SetJsonSerializationAdapter: Provides serialization and deserialization support for Dart Set types within JetLeaf’s JSON subsystem.
SetXmlSerializationAdapter
SetYamlSerializationAdapter
SnakeCaseNamingStrategy: Converts field names from camelCase to snake_case and vice versa.
StringDeserializer>: Deserializes JSON values into Dart String instances.
StringJsonGenerator: Internal JsonGenerator implementation that writes JSON into a StringBuffer.
StringJsonParser: A string-based streaming JSON parser that reads and tokenizes JSON input.
StringSerializer<G extends Generator, C extends SerializationContext<Generator>>: Serializes Dart String values into JSON string values.
StringXmlGenerator: Internal XmlGenerator implementation that writes XML into a StringBuffer.
StringXmlParser: Simple XML parser implementation for parsing XML strings.
StringYamlGenerator: Internal YamlGenerator implementation that writes YAML into a StringBuffer.
StringYamlParser: A production-ready, streaming YAML 1.2 parser that converts a YAML string into a normalized stream of YamlTokens.
ToJson: A constraint annotation for converting an instance of a class to a JSON map representation.
UriSerializationAdapter<G extends Generator, P extends Parser, DC extends DeserializationContext<Parser>, SC extends SerializationContext<Generator>>: Serializes and deserializes Dart Uri values to and from strings.
UrlSerializationAdapter<G extends Generator, P extends Parser, DC extends DeserializationContext<Parser>, SC extends SerializationContext<Generator>>: Serializes and deserializes Dart Url values to and from strings.
XmlDeserializationContext: Manages ObjectDeserializer instances during XML deserialization.
XmlDeserializer<T>: Specialization of ObjectDeserializer for XML deserialization using XmlParser.
XmlElementNode: Implementation of XmlNode representing an XML element.
XmlGenerator: Provides structured, incremental XML output for JetLeaf's serialization engine.
XmlNode<ObjectType>: Represents a node in an XML document tree (DOM-like structure).
XmlObjectMapper: Extends the ObjectMapper interface to provide specialized support for XML serialization and deserialization.
XmlParser: A parser for XML configuration files.
XmlSerializationAdapter<T>: Bidirectional XML converter implementing both serialization and deserialization.
XmlSerializationContext: Manages ObjectSerializer instances during XML serialization.
XmlSerializer<T>: Specialization of ObjectSerializer for XML serialization using XmlGenerator.
XmlTextNode: Implementation of XmlNode representing text content.
YamlDeserializationContext: Manages ObjectDeserializer instances during YAML deserialization.
YamlDeserializer<T>: Specialization of ObjectDeserializer for YAML deserialization using YamlParser.
YamlGenerator: A format-specific Generator for producing YAML output.
YamlMappingNode: Implementation of YamlNode representing a YAML mapping (object).
YamlNode<ObjectType>: Represents a node in a YAML document tree (DOM-like structure).
YamlObjectMapper: Extends the ObjectMapper interface to provide specialized support for YAML serialization and deserialization.
YamlParser: A parser for YAML configuration files.
YamlScalarNode: Implementation of YamlNode representing a scalar value.
YamlSequenceNode: Implementation of YamlNode representing a YAML sequence (array).
YamlSerializationAdapter<T>: Bidirectional YAML converter implementing both serialization and deserialization.
YamlSerializationContext: Manages ObjectSerializer instances during YAML serialization.
YamlSerializer<T>: Specialization of ObjectSerializer for YAML serialization using YamlGenerator.
ZonedDateTimeSerializationAdapter<G extends Generator, P extends Parser, DC extends DeserializationContext<Parser>, SC extends SerializationContext<Generator>>: Serializes and deserializes Dart ZonedDateTime values to and from strings.

Enums

DeserializationFeature: Feature flags that influence deserialization behavior in JetLeaf.
JsonToken: Enumerates all token types that a JsonParser can encounter during JSON parsing.
ObjectMapperType: Specifies the data format handled by a particular ObjectMapper instance.
SerializationFeature: Feature flags that influence serialization behavior in JetLeaf.
XmlToken: Enumerates all token types that an XmlParser can encounter during XML parsing.
YamlNodeType
YamlToken: Represents the lexical tokens produced by a YAML tokenizer/parser.

Typedefs

JsonParserFactory = JsonParser Function(String content): A factory function type for creating JsonParser instances from a raw JSON string.

Exceptions / Errors

FailedDeserializationException: Thrown when an object cannot be deserialized into the target Dart type.
IllegalObjectTokenException: Thrown when a parser encounters an illegal or unexpected token while reading an object structure (JSON, YAML, XML, etc.).
JsonParsingException: Thrown when a JSON input cannot be parsed or is syntactically invalid.
MalformedJsonException: Thrown when JSON data is structurally invalid or fails validation.
NoDeserializerFoundException: Thrown when Jetson cannot locate a deserializer capable of converting input data (JSON, YAML, XML, etc.) into an object of the requested type.
NoSerializerFoundException: Thrown when Jetson cannot locate a serializer capable of converting a Dart object into an output format (JSON, YAML, XML, etc.).
ObjectGeneratorException: Thrown when a generator fails to serialize an object structure into an output format (JSON, YAML, XML, etc.).
UnsupportedYamlFeatureException: Thrown when a YAML document uses a feature that is not supported.
YamlException: Thrown when an error occurs while parsing or processing a YAML document.
YamlSyntaxException: Thrown when a YAML document contains invalid or malformed syntax.

jetson library

🔑 Core Concepts

🧱 Base Infrastructure

🔄 Serialization & Deserialization

⏱ Common Adapters & Helpers

🔧 Jetson Core Mappers

📄 JSON Support

📄 XML Support

📄 YAML Support

🏷 Annotations & Naming Strategies

⚠ Exception Handling

🛠 Utilities

🎯 Intended Usage

Classes

Enums

Typedefs

Exceptions / Errors

jetleaf_web package

jetson library