Skip to Content
API ReferenceTypes Reference

This reference documents the core types and classes used in Flutter InstantDB.

Core Classes

InstantDB

Main database class providing all database operations.

class InstantDB {
  String get appId;
  InstantConfig get config;
  AuthManager get auth;
  PresenceManager get presence;
  TransactionBuilder get tx;
  
  // Reactive signals
  Signal<bool> get isReady;
  Signal<bool> get isOnline;
 
  // Initialization
  static Future<InstantDB> init({
    required String appId,
    InstantConfig? config,
    InstantSchema? schema,
  });
  
  // Query methods
  Signal<QueryResult> query(Map<String, dynamic> query, {bool syncedOnly = false});
  Future<QueryResult> queryOnce(Map<String, dynamic> query, {bool syncedOnly = false});
  
  // Transaction methods
  Future<TransactionResult> transact(dynamic transaction);
  
  // Auth methods
  Stream<AuthUser?> subscribeAuth();
  
  // Utilities
  String id();
}

InstantConfig

Configuration options for database initialization.

class InstantConfig {
  const InstantConfig({
    this.persistenceDir,
    this.syncEnabled = true,
    this.baseUrl = 'https://api.instantdb.com',
    this.maxCacheSize = 50 * 1024 * 1024,
    this.reconnectDelay = const Duration(seconds: 1),
    this.verboseLogging = false,
  });
 
  final String? persistenceDir;
  final bool syncEnabled;
  final String baseUrl;
  final int maxCacheSize;
  final Duration reconnectDelay;
  final bool verboseLogging;
}

QueryResult

Result returned by query operations.

class QueryResult {
  final Map<String, dynamic>? data;
  final String? error;
  final bool isLoading;
 
  bool get hasData => data != null;
  bool get hasError => error != null;
}

AuthUser

Represents an authenticated user.

class AuthUser {
  final String id;
  final String email;
  final DateTime createdAt;
  final Map<String, dynamic>? metadata;
}

TransactionResult

Result returned by transaction operations.

class TransactionResult {
  final bool success;
  final String? error;
  final Map<String, dynamic>? data;
}

Presence Types

PresenceData

Represents a user’s presence state in a room.

class PresenceData {
  final String userId;
  final Map<String, dynamic> data;
  final DateTime lastSeen;
}

CursorData

Represents cursor position and metadata.

class CursorData {
  final String userId;
  final String? userName;
  final String? userColor;
  final double x;
  final double y;
  final Map<String, dynamic>? metadata;
  final DateTime lastUpdated;
}

ReactionData

Represents a reaction sent to a room.

class ReactionData {
  final String id;
  final String userId;
  final String roomId;
  final String emoji;
  final Map<String, dynamic>? metadata;
  final DateTime timestamp;
}

Transaction Internals

Operation

Represents a single database mutation.

class Operation {
  final OperationType type;
  final String entityType;
  final String entityId;
  final Map<String, dynamic>? data;
}
 
enum OperationType {
  add,
  update,
  delete,
  merge,
  link,
  unlink,
  retract
}

LookupRef

Reference used to look up entities by an attribute other than id.

class LookupRef {
  final String entityType;
  final String attribute;
  final dynamic value;
}

TransactionChunk

A wrapper for a list of operations, often generated by the fluent tx API.

class TransactionChunk {
  final List<Operation> operations;
}
Widgets