Merge branch '5-flex-map'

Author: greenrobot

.github/workflows/code-analysis.yml

@@ -15,8 +15,8 @@ permissions:
 env:
   # Do code analysis with latest SDK.
   # Pick a concrete version instead of "latest" to avoid builds breaking due to changes in new SDKs.
-  FLUTTER_VERSION: 3.35.2 # Available versions: https://docs.flutter.dev/release/archive
-  DART_VERSION: 3.9.2 # Available versions: https://dart.dev/get-dart/archive
+  FLUTTER_VERSION: 3.38.5 # Available versions: https://docs.flutter.dev/release/archive
+  DART_VERSION: 3.10.4 # Available versions: https://dart.dev/get-dart/archive
 
 jobs:
   format-and-analyze:

.github/workflows/test.yml

@@ -20,8 +20,8 @@ env:
   # Run generator integration tests and init script with latest SDK.
   # Pick a concrete version instead of "latest" to avoid builds breaking due to changes in new SDKs.
   # NOTE: also update matrix configurations below!
-  FLUTTER_VERSION: 3.35.2 # Available versions: https://docs.flutter.dev/release/archive
-  DART_VERSION: 3.9.2 # Available versions: https://dart.dev/get-dart/archive
+  FLUTTER_VERSION: 3.38.5 # Available versions: https://docs.flutter.dev/release/archive
+  DART_VERSION: 3.10.4 # Available versions: https://dart.dev/get-dart/archive
 
 jobs:
 
@@ -67,7 +67,7 @@ jobs:
           # Pick a concrete version instead of "latest" to avoid builds breaking due to changes in new SDKs.
           # Can not use env variables here, only within 'steps'.
           # For available versions see https://dart.dev/get-dart/archive
-          - 3.9.2
+          - 3.10.4
           - 3.7.2 # Use latest bugfix release to get tooling fixes
     runs-on: ${{ matrix.os }}
     steps:
@@ -112,14 +112,14 @@ jobs:
           # Can not use env variables here, only within 'steps'.
           # For available versions see https://docs.flutter.dev/release/archive
           # NOTE Also update versions for Ubuntu below!
-          - 3.35.2
+          - 3.38.5
           - 3.29.3 # Use latest bugfix release to get tooling fixes
         include:
           # Test building for Android with highest supported JDK on latest Flutter SDK,
           # lowest supported JDK on lowest supported Flutter SDK. (Android is only built if a Linux
           # OS is detected, see integration-test.sh)
           - os: ubuntu-24.04
-            flutter-version: 3.35.2
+            flutter-version: 3.38.5
             jdk: 21
           - os: ubuntu-24.04
             flutter-version: 3.29.3 # Use latest bugfix release to get tooling fixes

.gitignore

@@ -23,3 +23,7 @@ objectbox.lib
 
 # backup created by publish.sh - ignore to avoid publishing
 **/pubspec.yaml.original
+
+# ObjectBox database files
+data.mdb
+lock.mdb

.gitlab-ci.yml

@@ -8,8 +8,8 @@ variables:
   # # Pick a concrete version instead of "latest" to avoid builds breaking due to changes in new
   # SDKs.
   # For available versions see https://hub.docker.com/_/dart/tags and https://dart.dev/get-dart/archive
-  DART_VERSION_LATEST: '3.9.2'
-  DART_VERSION_LOWEST: '3.7.2' # Use latest bugfix release to get tooling fixes
+  DART_VERSION_LATEST: '3.10.4'
+  DART_VERSION_LOWEST: '3.7.3' # Use latest bugfix release to get tooling fixes
   DART_VERSION: $DART_VERSION_LATEST # Also used for caching, see .cache template
 
 .common:

CONTRIBUTING.md

@@ -22,3 +22,47 @@ ObjectBox offers a [C API](https://github.com/objectbox/objectbox-c) which can b
 The C API is also used by the ObjectBox language bindings for [Go](https://github.com/objectbox/objectbox-go), [Swift](https://github.com/objectbox/objectbox-swift), and [Python](https://github.com/objectbox/objectbox-python).
 These languages may serve as an inspiration for this Dart implementation.
 Internally, ObjectBox uses [FlatBuffers](https://google.github.io/flatbuffers/) to store objects.
+
+## Code organization
+
+This is a multi-package Dart/Flutter repository.
+The core runtime library (`objectbox/`) provides the database API via Dart FFI bindings to the ObjectBox C library.
+Code generation (`generator/`) uses `build_runner` to produce entity bindings at compile time.
+Flutter apps include native libraries via platform-specific plugin packages (`flutter_libs/`, `sync_flutter_libs/`).
+
+- **`objectbox/`** – Core runtime package published as `objectbox` on pub.dev.
+  - `lib/objectbox.dart` – Public API exports (Store, Box, Query, annotations, Sync, etc.).
+  - `lib/src/native/` – FFI bindings and native implementations (Store, Box, Query, Sync).
+  - `lib/src/native/bindings/` – Auto-generated C bindings via `ffigen` and ObjectBox C headers.
+  - `lib/src/modelinfo/` – Model metadata classes used by the generator and runtime.
+  - `lib/src/relations/` – ToOne/ToMany relation implementations.
+  - `lib/src/annotations.dart` – Entity/property annotations (`@Entity`, `@Id`, `@Property`, etc.).
+  - `example/` – Example Dart/Flutter apps demonstrating usage.
+
+- **`generator/`** – Code generator package published as `objectbox_generator`.
+  - `lib/src/entity_resolver.dart` – Parses annotated entity classes using the Dart analyzer.
+  - `lib/src/code_builder.dart` – Orchestrates code generation via `build_runner`.
+  - `lib/src/code_chunks.dart` – Generates `objectbox.g.dart` and `objectbox-model.json`.
+  - `integration-tests/` – End-to-end generator tests with sample entity definitions.
+
+- **`flutter_libs/`** – Flutter plugin package (`objectbox_flutter_libs`) bundling native ObjectBox libraries for Android, iOS, Linux, macOS, and Windows.
+
+- **`sync_flutter_libs/`** – Flutter plugin package (`objectbox_sync_flutter_libs`) bundling native libraries with ObjectBox Sync support.
+
+- **`objectbox_test/`** – Internal test package (not published).
+  Contains comprehensive tests for the runtime: Box, Query, relations, Sync, observers, isolates, etc.
+  Uses `dependency_overrides` to test against local `objectbox/` and `generator/`.
+
+- **`benchmark/`** – Performance benchmarks comparing ObjectBox operations.
+
+- **`tool/`** – Shell scripts for development and release workflows:
+  - Version management (`set-version.sh`, `set-c-version.sh`).
+  - C library updates (`update-c-binding.sh`).
+  - Publishing (`publish.sh`, `pub.sh`).
+
+- **`dev-doc/`** – Internal developer documentation: updating the C library, adding property types, packaging, updating examples.
+
+- **`.github/`** – GitHub Actions workflows and issue templates.
+
+- **`.gitlab-ci.yml`** – GitLab CI pipeline configuration.
+

README.md

@@ -84,7 +84,7 @@ and servers, both online and offline.
 🪂 **ACID compliant** - Atomic, Consistent, Isolated, Durable.\
 💻 **Multiplatform** - Android, iOS, macOS, Linux, Windows, any POSIX-system.\
 🌱 **Scalable** - grows with your app, handling millions of objects with ease.\
-💚 **Sustainable** - frugal on CPU, Memory and battery / power use, reducing CO2 emmissions.
+💚 **Sustainable** - frugal on CPU, Memory and battery / power use, reducing CO2 emissions.
 
 🔗 **[Relations](https://docs.objectbox.io/relations)** - object links / relationships are built-in.\
 💐 **[Queries](https://docs.objectbox.io/queries)** - filter data as needed, even across relations.\
@@ -107,7 +107,9 @@ Continue with our ➡️ **[Getting Started guide](https://docs.objectbox.io/get
 
 ### Flutter Database Performance Benchmarks
 
-We tested across the four main database operations, CRUD (create, read, update, delete). Each test was run multiple times and executed  manually outside of the measured time. Data preparation and evaluation were done outside of the measured time. 
+We tested across the four main database operations, CRUD (create, read, update, delete).
+Each test was run multiple times and executed manually.
+Data preparation and evaluation were done outside the measured time. 
 
 Here are the benchmarks for ObjectBox vs sqflite vs Hive (last updated 2021-09-11) 👇
 
@@ -131,7 +133,7 @@ For general news on ObjectBox, [check our blog](https://objectbox.io/blog)!
 
 ## Contributing
 
-Do you want to check out the ObjectBox code itself? E.g. see in action, run tests, or even contribute code?
+Do you want to check out the ObjectBox code itself? E.g. see it in action, run tests, or even contribute code?
 Great! Clone/check out this repository and run this to generate code and get you started quickly:
 
 ```bash
@@ -154,6 +156,8 @@ This repository holds all ObjectBox Dart/Flutter packages as separate directorie
 There's also a separate repository benchmarking objectbox (and other databases) in Flutter: 
 [objectbox-dart-performance](https://github.com/objectbox/objectbox-dart-performance).
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for a more detailed overview.
+
 ## Other languages/bindings
 
 ObjectBox supports multiple platforms and languages: 
@@ -166,7 +170,7 @@ ObjectBox supports multiple platforms and languages:
 ## License
 
 ```text
-Copyright © 2019 ObjectBox Ltd. <https://objectbox.io/>
+Copyright © 2019-2025 ObjectBox Ltd. <https://objectbox.io/>
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

flutter_libs/pubspec.yaml

@@ -3,7 +3,7 @@ description: Superfast NoSQL Flutter / Dart database. This package contains Flut
 # Link to actual directory in repository so file links on pub.dev work.
 repository: https://github.com/objectbox/objectbox-dart/tree/main/flutter_libs
 homepage: https://objectbox.io
-version: 5.0.4
+version: 5.1.0-dev.0
 
 environment:
   sdk: ^3.7.0
@@ -14,7 +14,7 @@ dependencies:
     sdk: flutter
   # This is here just to ensure compatibility between objectbox-dart code and the libraries used
   # You should still depend on objectbox directly in your Flutter application.
-  objectbox: 5.0.4
+  objectbox: 5.1.0-dev.0
   path_provider: ^2.0.0
 
 dev_dependencies:

generator/lib/src/code_chunks.dart

@@ -324,7 +324,8 @@ class CodeChunks {
           offsets[p.id.id] = offsetVar; // see default case in the switch
 
           var assignment = 'final $offsetVar = ';
-          if (p.fieldIsNullable) {
+          // Note: dynamic is always nullable (currently only used for Flex properties)
+          if (p.fieldIsNullable || p.fieldType == 'dynamic') {
             assignment += '$fieldName == null ? null : ';
             fieldName += '!';
           }
@@ -346,6 +347,9 @@ class CodeChunks {
               return '$assignment fbb.writeListFloat32($fieldName);';
             case OBXPropertyType.DoubleVector:
               return '$assignment fbb.writeListFloat64($fieldName);';
+            case OBXPropertyType.Flex:
+              // Use toFlexBuffer() to serialize Map, List, or value types
+              return '$assignment fbb.writeListInt8($obxInt.toFlexBuffer($fieldName));';
             default:
               offsets.remove(p.id.id);
               return null;
@@ -445,6 +449,26 @@ class CodeChunks {
     );
   }
 
+  /// Extracts the key and value types by removing "Map<" prefix and ">" suffix.
+  static String _getMapKeyValueTypes(String typeString) {
+    // This String operation is very fragile and should be replaced with info
+    // from ModelProperty created by EntityResolver.
+    return typeString.substring(
+      4, // "Map<"
+      typeString.length - 1, // ">"
+    );
+  }
+
+  /// Extracts the element type by removing "List<" prefix and ">" suffix.
+  static String _getListElementType(String typeString) {
+    // This String operation is very fragile and should be replaced with info
+    // from ModelProperty created by EntityResolver.
+    return typeString.substring(
+      5, // "List<"
+      typeString.length - 1, // ">"
+    );
+  }
+
   static String objectFromFB(ModelEntity entity) {
     // collect code for the template at the end of this function
     final constructorLines = <String>[]; // used as constructor arguments
@@ -561,6 +585,78 @@ class CodeChunks {
                 p,
                 'fb.ListReader<String>(fb.StringReader(asciiOptimization: true), lazy: false)',
               );
+            case OBXPropertyType.Flex:
+              // Read as Uint8List and convert to Map, List, or value
+              final offset = propertyFlatBuffersvTableOffset(p);
+              // Use appropriate deserializer based on field type
+              final isMap = p.fieldType.startsWith('Map');
+              // dynamic is always nullable; Object requires nullable annotation
+              final isValue =
+                  p.fieldType == 'dynamic' ||
+                  (p.fieldType == 'Object' && p.fieldIsNullable);
+              // For List<Map<...>> types, use dedicated helper
+              final isListOfMaps = p.fieldType.startsWith('List<Map');
+              // Check if list needs casting (List<Object> or List<Object?>)
+              final isListOfObject = p.fieldType.startsWith('List<Object');
+              final String flexDeserializer;
+              final bool skipNull;
+              final String? defaultValue;
+              final String castSuffix;
+              if (isValue) {
+                // dynamic or Object? - can be any FlexBuffer value
+                flexDeserializer = 'fromFlexBuffer';
+                skipNull = false;
+                defaultValue = null; // nullable only, no default needed
+                castSuffix = '';
+              } else if (isMap) {
+                flexDeserializer = 'flexBufferToMap';
+                final keyValueTypes = _getMapKeyValueTypes(p.fieldType);
+                final hasDynamicValueType = keyValueTypes.endsWith('dynamic');
+                // For maps with non-null values skip nulls (so not
+                // Map<String, dynamic> or Map<String, Object/List/Map?>).
+                skipNull = !hasDynamicValueType && !keyValueTypes.endsWith('?');
+                defaultValue = '<$keyValueTypes>{}';
+                // Cast to the correct Map type if not Map<String, dynamic>
+                if (hasDynamicValueType) {
+                  castSuffix = '';
+                } else {
+                  castSuffix = '?.cast<$keyValueTypes>()';
+                }
+              } else if (isListOfMaps) {
+                flexDeserializer = 'flexBufferToListOfMaps';
+                final elementType = _getListElementType(p.fieldType);
+                // The deserializer already skips nulls
+                skipNull = false;
+                defaultValue = '<$elementType>[]';
+                // Cast needed for Map<String, Object?> and Map<String, Object>
+                if (elementType == 'Map<String, dynamic>') {
+                  castSuffix = '';
+                } else {
+                  castSuffix = '?.cast<$elementType>()';
+                }
+              } else if (isListOfObject) {
+                flexDeserializer = 'flexBufferToList';
+                final elementType = _getListElementType(p.fieldType);
+                // For lists with non-null elements skip nulls
+                skipNull = !elementType.endsWith('?');
+                defaultValue = '<$elementType>[]';
+                castSuffix = '?.cast<$elementType>()';
+              } else {
+                // List<dynamic>
+                flexDeserializer = 'flexBufferToList';
+                skipNull = false;
+                defaultValue = '<dynamic>[]';
+                castSuffix = '';
+              }
+              final skipNullArg = skipNull ? ', skipNull: true' : '';
+              final deserializeExpr =
+                  '$obxInt.$flexDeserializer(buffer, rootOffset, $offset$skipNullArg)$castSuffix';
+              if (p.fieldIsNullable || defaultValue == null) {
+                // Nullable field or value type (dynamic/Object?) - no default
+                return deserializeExpr;
+              } else {
+                return '$deserializeExpr ?? $defaultValue';
+              }
             default:
               return readFieldCodeString(
                 p,
@@ -778,6 +874,9 @@ class CodeChunks {
         case OBXPropertyType.StringVector:
           fieldType = 'StringVector';
           break;
+        case OBXPropertyType.Flex:
+          // Flex properties don't have query support yet, skip generating query property
+          continue;
         default:
           throw InvalidGenerationSourceError(
             'Unsupported property type (${prop.type}): ${entity.name}.$name',