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.

Cindel’s code generator emits one CindelCollectionSchema<T> instance per annotated collection class, together with the field, link, and composite-index metadata nested inside it. The runtime reads these schema objects at open time to register collections, validate migrations, and route serialization. Application code encounters them in two places: the schemas list passed to Cindel.open (e.g. [UserSchema, OrderSchema]) and the CindelBackupCollection(UserSchema) constructor used for backup and restore. You never construct these types manually — every instance is produced by the generator.
All four types described on this page are declared in package:cindel/src/schema.dart and re-exported from package:cindel.

​
CindelCollectionSchema<T>

Generated metadata for a single Cindel collection. The type parameter T is the Dart class the schema represents (e.g. CindelCollectionSchema<User>). Declaration: final class CindelCollectionSchema<T>

​
Constructor parameters

​
name
String
required
The stored collection name — the string used in the native database, schemas, and migration contexts. Matches the name argument of @Collection, or the lower-camel-case class name when no name was given.
​
dartName
String
required
The Dart class name as written in source (e.g. "User"). Used for diagnostic messages and migration introspection.
​
idField
String
required
The Dart field name that holds the document id (e.g. "dbId"). The runtime uses this to read and write the id without going through the full document map.
​
fields
Iterable<CindelFieldSchema>
required
Metadata for every persisted field. The list is stored as an unmodifiable copy. See CindelFieldSchema below.
​
links
Iterable<CindelLinkSchema>
default:"[]"
Metadata for every generated link and backlink field. The list is stored as an unmodifiable copy. See CindelLinkSchema below.
​
compositeIndexes
Iterable<CindelCompositeIndexSchema>
default:"[]"
Metadata for every collection-level composite index. The list is stored as an unmodifiable copy. See CindelCompositeIndexSchema below.
​
toDocument
CindelToDocument<T>
required
Generated serializer — converts a T instance into a Map<String, Object?> document. Used by the map-based backends and during backup export.
​
fromDocument
CindelFromDocument<T>
required
Generated deserializer — converts a Map<String, Object?> document back into a T instance. Used by the map-based backends and during backup import.
​
toBinaryDocument
CindelToBinaryDocument<T>?
Optional generated serializer — converts a T instance into CindelBinaryDocumentBytes (a Uint8List). Provided when the generator emits a native binary fast path for this collection.
​
fromBinaryDocument
CindelFromBinaryDocument<T>?
Optional generated deserializer — converts CindelBinaryDocumentBytes back into a T instance. Provided when the generator emits a native binary fast path for this collection.
​
getId
CindelGetId<T>?
Optional generated accessor — reads the id field from a T instance without constructing a full document map. Provided when the generator can emit it.
​
writeNativeDocument
CindelWriteNativeDocument<T>?
Optional generated serializer — writes a T instance into a CindelNativeDocumentWriter directly, bypassing an intermediate Map. Provided when the generator emits a native-writer fast path.
​
readNativeDocument
CindelReadNativeDocument<T>?
Optional generated deserializer — reads a T instance from a CindelNativeDocumentReader directly. Provided when the generator emits a native-reader fast path.
​
setId
CindelSetId<T>?
Optional generated mutator — assigns a native auto-increment id back to a T instance after a write. Provided when the generator can emit it.
​
bindLinks
CindelBindLinks<T>?
Optional generated callback — binds generated link fields to the database handle after an object is hydrated. Provided when the collection has links or backlinks.

​
Example

The generator produces a top-level constant for each collection. The snippet below shows the shape of a generated schema (simplified): 
// Generated — do not edit.
final UserSchema = CindelCollectionSchema<User>(
  name: 'users',
  dartName: 'User',
  idField: 'dbId',
  fields: [
    CindelFieldSchema(
      name: 'dbId',
      dartType: 'Id',
      isId: true,
      isIndexed: false,
    ),
    CindelFieldSchema(
      name: 'email',
      dartType: 'String',
      isId: false,
      isIndexed: true,
      isIndexUnique: true,
    ),
  ],
  toDocument: (user) => {
    'dbId': user.dbId,
    'email': user.email,
  },
  fromDocument: (doc) => User()
    ..dbId = doc['dbId'] as int
    ..email = doc['email'] as String,
  getId: (user) => user.dbId,
  setId: (user, id) => user.dbId = id,
);

​
Passing schemas to Cindel.open

final db = await Cindel.open(
  directory: directory.path,
  schemas: [UserSchema, OrderSchema],
);

​
Passing schemas to CindelBackupCollection

await CindelBackup.exportDatabase(
  database: db,
  collections: [
    CindelBackupCollection(UserSchema),
    CindelBackupCollection(OrderSchema),
  ],
  output: output,
);

​
CindelFieldSchema

Generated metadata for a single persisted field within a collection. Declaration: final class CindelFieldSchema
​
name
String
required
The stored field name as it appears in documents and native indexes. Matches the Dart field name unless overridden with @Name.
​
dartType
String
required
The Dart type string as written by the analyzer (e.g. "String", "int?", "List<String>"). Used for migration introspection and diagnostics.
​
binaryType
String?
The schema-backed binary storage type used by generated native serializers. null when no native binary path is available for this field.
​
isId
bool
required
true when this field is the collection’s id field (i.e. it holds the Id / int document identifier).
​
isIndexed
bool
required
true when the field is annotated with @Index or @index.
​
isIndexUnique
bool
default:"false"
true when the index was declared with unique: true.
​
isIndexReplace
bool
default:"false"
true when the unique index was declared with replace: true. When set, conflicting writes replace the existing document instead of throwing.
​
indexCaseSensitive
bool
default:"true"
true when string index lookups are case-sensitive. Only meaningful for String fields.
​
indexType
CindelIndexType
default:"CindelIndexType.value"
The storage strategy for this field’s index. See CindelIndexType in the Annotations reference.

​
Example

// Produced by the generator for: @Index(unique: true) late String email;
const CindelFieldSchema(
  name: 'email',
  dartType: 'String',
  isId: false,
  isIndexed: true,
  isIndexUnique: true,
  isIndexReplace: false,
  indexCaseSensitive: true,
  indexType: CindelIndexType.value,
)

​
CindelLinkSchema

Generated metadata for a link (CindelLink<T> or CindelLinks<T>) or backlink (@Backlink) field. Declaration: final class CindelLinkSchema
​
name
String
required
The persisted relation name used in the native link table. Derived from the Dart field name unless overridden with @Name.
​
dartName
String
required
The Dart field name as written in source (e.g. "featuredArtists").
​
targetCollection
String
required
The stored collection name of the collection this link points to.
​
isToMany
bool
required
true for CindelLinks<T> (to-many) fields; false for CindelLink<T> (to-one) fields.
​
isBacklink
bool
required
true when this schema entry describes a backlink (i.e. the field is annotated with @Backlink).
​
backlinkTo
String?
For backlinks, the Dart field name of the forward link on the target collection that this backlink mirrors. null for forward links.

​
Example

// For: @Backlink(to: 'featuredArtists') final songs = CindelLinks<Song>();
const CindelLinkSchema(
  name: 'songs',
  dartName: 'songs',
  targetCollection: 'songs',
  isToMany: true,
  isBacklink: true,
  backlinkTo: 'featuredArtists',
)

​
CindelCompositeIndexSchema

Generated metadata for a collection-level composite index declared via CompositeIndex in the @Collection annotation. Declaration: final class CindelCompositeIndexSchema
​
name
String
required
The stable native index name generated by the code generator. This name is written to the native backend and must remain stable across re-generations for migrations to work correctly. The generator derives it deterministically from the collection name and field list.
​
fields
Iterable<String>
required
The indexed field names in index order. The list is stored as an unmodifiable copy.
​
isUnique
bool
default:"false"
true when the composite index requires unique values across the combined key.
​
isReplace
bool
default:"false"
true when a write conflicting with this unique composite index should replace the existing document.
​
caseSensitive
bool
default:"true"
true when string field comparisons within the composite key are case-sensitive.

​
Example

// For: CompositeIndex(['accountId', 'createdAt'])
CindelCompositeIndexSchema(
  name: 'events_accountId_createdAt',
  fields: ['accountId', 'createdAt'],
  isUnique: false,
  isReplace: false,
  caseSensitive: true,
)

Build docs developers (and LLMs) love

Get started for freeTalk to us