local_first_sqlite_storage 0.2.0

SQLite adapter for local_first: structured tables, indexes, and filtered queries.

local_first_sqlite_storage

Child package of the local_first ecosystem. This SQLite adapter provides structured tables with typed schemas, indexes, and server-like filtering/sorting for offline-first apps.

Supported config type	Example
bool	true
int	42
double	3.14
String	'hello'
List<String>	['a', 'b']

Why use this adapter?

• Structured schema with per-column indexes.
• Rich query filters (whereIn, comparisons, null checks), sorting, limit/offset.
• JSON fallback for non-schema fields.
• Namespaces and metadata storage.
• Reactive watchQuery updates on data changes.

Installation

Add the core and the SQLite adapter to your pubspec.yaml:

dependencies:
  local_first: ^0.5.0
  local_first_sqlite_storage: ^0.1.0

Quick start

import 'package:local_first/local_first.dart';
import 'package:local_first_sqlite_storage/local_first_sqlite_storage.dart';

// Keep your model immutable; LocalFirstEvent wraps it with sync metadata.
class Todo {
  const Todo({
    required this.id,
    required this.title,
    required this.updatedAt,
  });

  final String id;
  final String title;
  final DateTime updatedAt;

  JsonMaptoJson() => {
        'id': id,
        'title': title,
        'updated_at': updatedAt.toUtc().toIso8601String(),
      };

  factory Todo.fromJson(JsonMapjson) => Todo(
        id: json['id'] as String,
        title: json['title'] as String,
        updatedAt: DateTime.parse(json['updated_at']).toUtc(),
      );

  static Todo resolveConflict(Todo local, Todo remote) =>
      local.updatedAt.isAfter(remote.updatedAt) ? local : remote;
}

final todoRepository = LocalFirstRepository<Todo>.create(
  name: 'todo',
  getId: (todo) => todo.id,
  toJson: (todo) => todo.toJson(),
  fromJson: Todo.fromJson,
  onConflict: Todo.resolveConflict,
  schema: const {
    'title': LocalFieldType.text,
    'updated_at': LocalFieldType.datetime,
  },
);

Future<void> main() async {
  final client = LocalFirstClient(
    repositories: [todoRepository],
    localStorage: SqliteLocalFirstStorage(),
    syncStrategies: [
      // Provide your own strategy implementing DataSyncStrategy.
    ],
  );

  await client.initialize();
  await todoRepository.upsert(
    Todo(
      id: '1',
      title: 'Buy milk',
      updatedAt: DateTime.now().toUtc(),
    ),
    needSync: true,
  );
}

Features

• Creates tables and indexes based on provided schema.
• Query builder with comparisons, IN/NOT IN, null checks, sorting, limit/offset.
• Stores full JSON in a data column and leverages schema columns for performance.
• Namespaces and metadata (setConfigValue / getConfigValue).
• Reactive watchQuery.

Testing

Run tests from this package root:

flutter test

Example app

This package ships the shared demo app. To run it:

cd local_first_sqlite_storage/example
flutter run

Contributing

Please read the contribution guidelines in the root project before opening issues or PRs: see ../CONTRIBUTING.md.

License

MIT (see LICENSE).