RDF Mapper for Dart

// RDF Turtle input to deserialize
final turtleInput = '''
@base <http://example.org/book/> .
@prefix schema: <https://schema.org/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<hobbit> a schema:Book;
    schema:aggregateRating 5;
    schema:author "J.R.R. Tolkien";
    schema:datePublished "1937-09-20T23:00:00.000Z"^^xsd:dateTime;
    schema:genre "adventure", "children", "fantasy";
    schema:hasPart ([ a schema:Chapter ; schema:name "An Unexpected Party" ; schema:position 1 ] [ a schema:Chapter ; schema:name "Roast Mutton" ; schema:position 2 ] [ a schema:Chapter ; schema:name "A Short Rest" ; schema:position 3 ]);
    schema:isbn <urn:isbn:9780618260300>;
    schema:name "The Hobbit" .
''';

// Deserialize RDF back to our Book object with all its chapters
final book = rdf.decodeObject<Book>(turtleInput);

// Access complex properties
print('Title: ${book.title}');
print('Author: ${book.author}');
print('Published: ${book.published}');
print('Rating: ${book.rating.stars} stars');
print('Chapters: ${book.chapters.length}');

// Lossless mapping preserves unmapped RDF data
// that couldn't be processed by your mappers

// Deserialize with lossless APIs
final (book, unmappedData) = rdf.decodeObjectLossless<Book>(turtleInput);

// Access the original mapped object
print('Book: ${book.title} by ${book.author}');

// Check what RDF data wasn't mapped to Dart properties
if (unmappedData.isNotEmpty) {
  print('Found ${unmappedData.length} unmapped triples');
  
  // You could store this data, log it, or process it later
  for (final triple in unmappedData) {
    print('Unmapped: ${triple.subject} ${triple.predicate} ${triple.object}');
  }
}

// When serializing back, preserve the unmapped data
final modifiedBook = Book(
  id: book.id,
  title: 'The Hobbit (Annotated Edition)', // Modified title
  author: book.author,
  published: book.published,
  isbn: book.isbn,
  rating: book.rating,
  chapters: book.chapters,
);

// Add unmapped data back during serialization
final newTurtle = rdf.encodeObjectLossless(modifiedBook, unmappedData);

// The result contains both your object changes AND the original unmapped RDF

// --- Domain Model ---

// Primary entity with an identifier
class Book {
  final String id;
  final String title;
  final String author;
  final DateTime published;
  final ISBN isbn;
  final Rating rating;
  // ORDERED: Chapters sequence matters (mapped to RDF list)
  final List<Chapter> chapters;
  // UNORDERED: Multiple independent values (mapped to multiple triples)
  final List<String> genres;

  Book({
    required this.id,
    required this.title,
    required this.author,
    required this.published,
    required this.isbn,
    required this.rating,
    required this.chapters,
    required this.genres,
  });
}

// Value object using blank nodes (no identifier)
class Chapter {
  final String title;
  final int number;

  Chapter(this.title, this.number);
}

// Custom identifier type using IRI mapping
class ISBN {
  final String value;
  ISBN(this.value);
}

// Custom value type using literal mapping
class Rating {
  final int stars;
  Rating(this.stars) {
    if (stars < 0 || stars > 5) {
      throw ArgumentError('Rating must be between 0 and 5 stars');
    }
  }
}

// Book mapper - maps Book objects to IRI nodes
class BookMapper implements GlobalResourceMapper<Book> {
  // Property predicates for semantic clarity
  static final titlePredicate = SchemaBook.name;
  static final authorPredicate = SchemaBook.author;
  static final publishedPredicate = SchemaBook.datePublished;
  static final isbnPredicate = SchemaBook.isbn;
  static final ratingPredicate = SchemaBook.aggregateRating;
  static final chapterPredicate = SchemaBook.hasPart;
  static final genrePredicate = SchemaBook.genre;
  
  static const String bookIriPrefix = 'http://example.org/book/';
  
  @override
  final IriTerm typeIri = SchemaBook.classIri;
  
  @override
  (IriTerm, List<Triple>) toRdfResource(
    Book book,
    SerializationContext context, {
    RdfSubject? parentSubject,
  }) {
    return context
        .resourceBuilder(IriTerm('$bookIriPrefix${book.id}'))
        .addValue(titlePredicate, book.title)
        .addValue(authorPredicate, book.author)
        .addValue<DateTime>(publishedPredicate, book.published)
        .addValue<ISBN>(isbnPredicate, book.isbn)
        .addValue<Rating>(ratingPredicate, book.rating)
        // ORDERED: Use addRdfList for chapters (preserves sequence)
        .addRdfList<Chapter>(chapterPredicate, book.chapters)
        // UNORDERED: Use addValues for genres (multiple independent values)
        .addValues<String>(genrePredicate, book.genres)
        .build();
  }
  
  @override
  Book fromRdfResource(IriTerm term, DeserializationContext context) {
    final reader = context.reader(term);
    
    return Book(
      id: _extractIdFromIri(term.iri),
      title: reader.require<String>(titlePredicate),
      author: reader.require<String>(authorPredicate),
      published: reader.require<DateTime>(publishedPredicate),
      isbn: reader.require<ISBN>(isbnPredicate),
      rating: reader.require<Rating>(ratingPredicate),
      // ORDERED: Use optionalRdfList for chapters (preserves sequence)
      chapters: reader.optionalRdfList<Chapter>(chapterPredicate) ?? const [],
      // UNORDERED: Use getValues for genres (multiple independent values)
      genres: reader.getValues<String>(genrePredicate).toList(),
    );
  }
  
  // Helper method to extract ID from IRI
  String _extractIdFromIri(String iri) {
    if (!iri.startsWith(bookIriPrefix)) {
      throw ArgumentError('Invalid Book IRI format: $iri');
    }
    return iri.substring(bookIriPrefix.length);
  }
}

// Chapter mapper - maps Chapters to blank nodes
class ChapterMapper implements LocalResourceMapper<Chapter> {
  static final titlePredicate = SchemaChapter.name;
  static final numberPredicate = SchemaChapter.position;

  @override
  final IriTerm typeIri = SchemaChapter.classIri;
  
  @override
  (BlankNodeTerm, List<Triple>) toRdfResource(
    Chapter chapter,
    SerializationContext context, {
    RdfSubject? parentSubject,
  }) {
    return context.resourceBuilder(BlankNodeTerm())
      .addValue(titlePredicate, chapter.title)
      .addValue(numberPredicate, chapter.number)
      .build();
  }
  
  @override
  Chapter fromRdfResource(BlankNodeTerm term, DeserializationContext context) {
    final reader = context.reader(term);
    
    return Chapter(
      reader.require<String>(titlePredicate),
      reader.require<int>(numberPredicate),
    );
  }
}

// ISBN mapper - maps ISBN to IRI term
class ISBNMapper implements IriTermMapper<ISBN> {
  static const String ISBN_URI_PREFIX = 'urn:isbn:';

  @override
  IriTerm toRdfTerm(ISBN value, SerializationContext context) {
    return IriTerm('$ISBN_URI_PREFIX${value.value}');
  }
  
  @override
  ISBN fromRdfTerm(IriTerm term, DeserializationContext context) {
    final uri = term.iri;
    if (!uri.startsWith(ISBN_URI_PREFIX)) {
      throw ArgumentError('Invalid ISBN URI format: $uri');
    }
    return ISBN(uri.substring(ISBN_URI_PREFIX.length));
  }
}

// Rating mapper - maps Rating to literal term
class RatingMapper implements LiteralTermMapper<Rating> {
  @override
  LiteralTerm toRdfTerm(Rating value, SerializationContext context) {
    return LiteralTerm.typed(value.stars.toString(), 'integer');
  }
  
  @override
  Rating fromRdfTerm(LiteralTerm term, DeserializationContext context) {
    return Rating(int.parse(term.value));
  }
}