Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mainser/cindel/llms.txt

Use this file to discover all available pages before exploring further.

CindelTypedCollection<T> is the generated typed access layer that bridges your Dart model class to a Cindel collection at runtime. Every public method accepts and returns fully typed T objects, so your application code never touches raw documents or byte buffers. In practice you never instantiate this class yourself — the code generator produces an extension getter on CindelDatabase (for example, db.users) that returns a ready-to-use CindelTypedCollection<User>. The class delegates all persistence details to CindelDatabase and selects the fastest safe path available — native binary plans on MDBX, native SQLite document reads on the SQLite backends, or Dart-side deserialization as a fallback.

​
Properties

​
database
CindelDatabase
required
The CindelDatabase instance that owns this collection. All read and write calls are routed through this handle, which means the collection respects any active transaction started on the same database.
​
schema
CindelCollectionSchema<T>
required
Generated schema metadata for this collection, including the collection name, field descriptors, id accessor, serializers, and link binders. This value is produced by the code generator and should be treated as opaque by application code.

​
Write Operations

​
put

Future<void> put(T object)
Persists a single object. The id used for storage is read through the generated id accessor declared by schema. If the object’s id field equals autoIncrement, Cindel allocates the next database id and writes it back through the generated id setter before the object is stored. After put returns, the dbId field on the object reflects the assigned id. 
final user = User()
  ..email = 'ada@example.com'
  ..name = 'Ada Lovelace';

await db.users.put(user);

print(user.dbId); // Assigned auto-increment id, e.g. 1
​
object
T
required
The object to persist. When the id field is autoIncrement, the assigned id is written back to this object before the method returns.

​
putAll

Future<void> putAll(Iterable<T> objects)
Persists every object in objects atomically. Auto-increment ids are allocated individually for objects whose id field equals autoIncrement, and each assigned id is written back before the batch reaches storage. Duplicate ids within the same call throw an ArgumentError before any write reaches storage. An empty iterable is treated as a no-op and returns immediately. 
final users = [
  User()..email = 'ada@example.com'..name = 'Ada',
  User()..email = 'grace@example.com'..name = 'Grace',
];

await db.users.putAll(users);
​
objects
Iterable<T>
required
The objects to persist. Duplicate ids across this iterable cause an ArgumentError. An empty iterable is a no-op.

​
putMany

Future<void> putMany(Iterable<T> objects)
Alias for putAll. Provided for APIs that prefer many naming. Behaviour is identical in every respect.
​
objects
Iterable<T>
required
The objects to persist. Delegates directly to putAll.

​
Read Operations

​
get

Future<T?> get(int id)
Returns the typed object stored under id, or null if no document with that id exists in the collection. 
final user = await db.users.get(1);
if (user != null) {
  print(user.name);
}
​
id
int
required
The document id to look up.

​
getAll

Future<List<T?>> getAll(Iterable<int> ids)
Returns typed objects for each id in ids, preserving input order. Missing ids appear as null at the corresponding position in the returned list. The list length always equals the number of ids supplied. 
final results = await db.users.getAll([1, 2, 404]);
// results[0] → User with id 1
// results[1] → User with id 2
// results[2] → null (not found)
​
ids
Iterable<int>
required
The document ids to fetch. The result preserves this order and returns null for each id that does not exist.

​
Delete Operations

​
delete

Future<void> delete(int id)
Deletes the document stored under id. If no document with that id exists, the call completes without error. 
await db.users.delete(user.dbId);
​
id
int
required
The document id to delete.

​
deleteAll

Future<void> deleteAll(Iterable<int> ids)
Deletes every document whose id appears in ids atomically. Missing ids are ignored. An empty iterable is a no-op. 
await db.users.deleteAll([1, 2, 3]);
​
ids
Iterable<int>
required
The document ids to delete. Missing ids are silently ignored.

​
Query Builders

Query builders return a CindelQuery<T> that can be further refined with filters, sorts, and pagination before execution. All query methods are non-mutating — each call returns a new query object.

​
all

CindelQuery<T> all()
Returns a query over every document in the collection. This is the starting point for any query that does not use an index source. Chain sort, filter, and pagination methods before calling a terminal operation such as findAll() or count(). 
final count = await db.users.all().count();

final page = await db.users
    .all()
    .offset(0)
    .limit(20)
    .findAll();

​
where

A generated method available only when the collection declares at least one @Index field. where() returns a typed where-clause builder whose methods correspond to the indexed fields — for example, emailEqualTo, createdAtBetween, or nameSortBy. Index-backed queries let Cindel use the underlying index to narrow the candidate document set before any Dart-side filtering. 
// Generated where() helper for @Index() email field
final ada = await db.users
    .where()
    .emailEqualTo('ada@example.com')
    .findFirst();

final recent = await db.users
    .where()
    .createdAtBetween(start, end)
    .sortByCreatedAt()
    .findAll();
where() helpers cover equality, range, prefix, and word-token queries depending on the index type declared on the field. Composite indexes generate a multi-field equality helper that uses the composite index as its source.

​
filter

A generated method that returns a typed filter builder covering all persisted fields in the collection, regardless of whether they are indexed. Filter builders generate per-field predicate methods — for example, activeEqualTo, nameContains, tagsElementEqualTo — and can be chained with sorting and pagination helpers. 
// Generated filter() helper
final activeUsers = await db.users
    .filter()
    .activeEqualTo(true)
    .sortByName()
    .findAll();

final matching = await db.users
    .filter()
    .nameContains('Ada')
    .findAll();
Unlike where(), filter() does not restrict predicates to indexed fields, but it also does not guarantee an index-backed execution path. For high-cardinality lookups on large collections, prefer where() when an appropriate index is available.

​
Watchers

Watcher methods return Stream values that emit when the underlying collection data changes. Streams use polling internally and deduplicate consecutive identical snapshots, so listeners only fire when the observed data actually changes.

​
watchObject

Stream<T?> watchObject(
  int id, {
  Duration pollInterval = defaultCindelWatchPollInterval,
  bool fireImmediately = true,
})
Returns a stream that emits the typed object stored under id each time that document changes. When the document does not exist — including after it is deleted — the stream emits null. By default the stream emits the current value immediately on subscription. Set fireImmediately: false to suppress the initial event and only receive subsequent changes. 
final subscription = db.users
    .watchObject(user.dbId)
    .listen((user) {
      if (user == null) {
        print('User was deleted');
      } else {
        print('User updated: ${user.name}');
      }
    });
​
id
int
required
The document id to watch.
​
pollInterval
Duration
default:"defaultCindelWatchPollInterval"
How often the underlying change watcher polls for updates. Defaults to the global defaultCindelWatchPollInterval constant.
​
fireImmediately
bool
default:"true"
When true (the default), the stream emits the current object value immediately on subscription before waiting for the next change. Set to false to receive only subsequent change events.

​
watchCollection

Stream<List<T>> watchCollection({
  Duration pollInterval = defaultCindelWatchPollInterval,
  bool fireImmediately = true,
})
Returns a stream that emits a full typed snapshot of the collection on each change. Each event contains the complete list of current objects as returned by all().findAll(). 
final subscription = db.users
    .watchCollection()
    .listen((users) {
      setState(() => _users = users);
    });
​
pollInterval
Duration
default:"defaultCindelWatchPollInterval"
How often the underlying change watcher polls for updates. Defaults to the global defaultCindelWatchPollInterval constant.
​
fireImmediately
bool
default:"true"
When true (the default), the stream emits the current collection snapshot immediately on subscription before waiting for the next change. Set to false to receive only subsequent change events.

​
watchObjectLazy

Stream<void> watchObjectLazy(
  int id, {
  Duration pollInterval = defaultCindelWatchPollInterval,
  bool fireImmediately = false,
})
Returns an invalidation-only stream that emits a void event each time the object stored under id changes, without fetching or returning the object itself. Use this when you want to re-fetch on change without paying for automatic deserialization on every event. 
db.users.watchObjectLazy(user.dbId).listen((_) async {
  final fresh = await db.users.get(user.dbId);
  // Handle refresh manually.
});
​
id
int
required
The document id to watch.
​
pollInterval
Duration
default:"defaultCindelWatchPollInterval"
How often the underlying change watcher polls for updates.
​
fireImmediately
bool
default:"false"
When true, the stream emits one event immediately on subscription before waiting for the next change.

​
watchCollectionLazy

Stream<void> watchCollectionLazy({
  Duration pollInterval = defaultCindelWatchPollInterval,
  bool fireImmediately = false,
})
Returns an invalidation-only stream that emits a void event each time any document in the collection changes, without returning the updated objects. Useful for cache-invalidation patterns where you manage the read yourself. 
db.users.watchCollectionLazy().listen((_) {
  // Trigger a manual refresh of cached state.
});
​
pollInterval
Duration
default:"defaultCindelWatchPollInterval"
How often the underlying change watcher polls for updates.
​
fireImmediately
bool
default:"false"
When true, the stream emits one event immediately on subscription before waiting for the next change.

Build docs developers (and LLMs) love

Get started for freeTalk to us