{"id":26954598,"url":"https://github.com/evandersondev/snail","last_synced_at":"2026-02-11T14:32:27.441Z","repository":{"id":268274457,"uuid":"902997342","full_name":"evandersondev/snail","owner":"evandersondev","description":"🐌 Snail is a library inspired by Spring Data JPA, designed to simplify SQLite database management in Flutter/Dart applications. Easy to use like a snail (but as functional as a rocket 🚀)!","archived":false,"fork":false,"pushed_at":"2025-04-12T19:56:17.000Z","size":479,"stargazers_count":8,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-12T14:49:53.772Z","etag":null,"topics":["dart","flutter","jpa","orm","snail","sqflite","sql"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/snail","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evandersondev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-13T17:52:05.000Z","updated_at":"2025-04-12T19:56:21.000Z","dependencies_parsed_at":"2025-04-12T20:37:15.432Z","dependency_job_id":null,"html_url":"https://github.com/evandersondev/snail","commit_stats":null,"previous_names":["evandersondev/snail"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/evandersondev/snail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evandersondev%2Fsnail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evandersondev%2Fsnail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evandersondev%2Fsnail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evandersondev%2Fsnail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evandersondev","download_url":"https://codeload.github.com/evandersondev/snail/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evandersondev%2Fsnail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29335227,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T14:07:45.431Z","status":"ssl_error","status_checked_at":"2026-02-11T14:07:45.080Z","response_time":97,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dart","flutter","jpa","orm","snail","sqflite","sql"],"created_at":"2025-04-03T02:18:30.379Z","updated_at":"2026-02-11T14:32:27.426Z","avatar_url":"https://github.com/evandersondev.png","language":"Dart","readme":"# 🐌 Snail: A Simple ORM-like Library for Flutter/Dart 🐦\n\n**Snail** is a library inspired by Spring Boot's JPA, designed to simplify SQLite database management in Flutter/Dart applications. Easy to use like a snail 🐌 (but as functional as a rocket 🚀)!\n\n## ✨ Features\n\n- ✅ Create, Read, Update, Delete (CRUD) operations.\n- 🔍 Dynamic query methods based on method naming conventions.\n- 🛠️ Table creation based on field definitions.\n- 🔄 Automatic mapping of entities to database rows and vice versa.\n- 🔗 Support for snake_case and camelCase conversions.\n- 📜 Pagination, sorting, and filtering support.\n\n## 📥 Installation\n\nAdd the following dependency to your `pubspec.yaml`:\n\n```yaml\ndependencies:\n  snail: ^1.1.4\n```\n\n## Getting Started 🏁\n\n### Creating a Repository 📦\n\nTo create a repository for your model, extend the `SnailRepository` class:\n\n```dart\nimport 'package:snail/snail.dart';\n\nclass UserRepository extends SnailRepository\u003cUser, int\u003e {\n  UserRepository() : super(\n    tableName: 'users',\n    primaryKeyColumn: 'id',\n    defineFields: {\n      'id': int,\n      'name': String,\n      'email': String,\n      'isActive': bool,\n    },\n  );\n\n  @override\n  Map\u003cString, dynamic\u003e toMap(User entity) =\u003e entity.toMap();\n\n  @override\n  User fromMap(Map\u003cString, dynamic\u003e map) =\u003e User.fromMap(map);\n}\n\nclass User {\n  final int id;\n  final String name;\n  final String email;\n  final bool isActive;\n\n  User({\n    required this.id,\n    required this.name,\n    required this.email,\n    required this.isActive,\n  });\n\n   Map\u003cString, dynamic\u003e toMap() {\n    final result = \u003cString, dynamic\u003e{};\n\n    result.addAll({'id': id});\n    result.addAll({'name': name});\n    result.addAll({'email': email});\n    result.addAll({'isActive': isActive});\n\n    return result;\n  }\n\n  factory UserModel.fromMap(Map\u003cString, dynamic\u003e map) {\n    return UserModel(\n      id: map['id']?.toInt() ?? 0,\n      name: map['name'] ?? '',\n      email: map['email'] ?? '',\n      email: map['isActive'] ?? '',\n    );\n  }\n}\n\nvoid main() async {\n  WidgetsFlutterBinding.ensureInitialized();\n\n  await Snail.initialize(\n    repositories: [\n      UserRepository(),\n    ],\n  );\n\n  runApp(AppWidget());\n}\n```\n\n### Using the Repository 🔧\n\n```dart\nvoid main() async {\n  final userRepository = UserRepository();\n\n  // Save a user\n  await userRepository.save(User(id: 1, name: 'John Doe', email: 'john@example.com', isActive: true));\n\n  // Find a user by ID\n  final user = await userRepository.findById(1);\n\n  // Find all users\n  final users = await userRepository.findAll();\n\n  // Delete a user\n  await userRepository.deleteById(1);\n}\n```\n\n## Dynamic Methods 🔍\n\nThe `dynamicMethod` allows constructing SQL queries based on the method naming. The naming structure should follow standard conventions:\n\n### Naming Structure 🛠️\n\n- **Prefixes**: `find` or `findAll`\n- **Connectors**: `And`, `Or`\n- **Operators**: `Between`, `LessThan`, `GreaterThan`, `Like`, `StartingWith`, `EndingWith`, `Containing`, `In`, `NotIn`, `OrderBy`, `True`, `False`, `IsNull`, `NotNull`\n\n### Example Naming Conventions 📖\n\n```dart\nfindByTitle(String title);\nfindById(int id);\nfindByTitleAndDescription(String title, String description);\nfindByTitleOrDescription(String title, String description);\nfindByTitleStartingWith(String title);\nfindByTitleEndingWith(String title);\nfindByTitleContaining(String title);\nfindByIdLessThan(int id);\nfindByIdGreaterThan(int id);\nfindByDateBetween(DateTime startDate, DateTime endDate);\nfindByTitleStartingWithAndIdLessThan(String title, int id);\nfindByTitleContainingOrDescriptionLike(String title, String description);\nfindByIdIn(List\u003cint\u003e ids);\nfindByIdNotIn(List\u003cint\u003e ids);\nfindByTitleOrderByDate(String title);\nfindByTitleOrderByDateDesc(String title);\nfindByTitleAndDescriptionOrderByDate(String title, String description);\nfindByIsActiveTrue();\nfindByIsActiveFalse();\nfindByTitleIsNull();\nfindByTitleNotNull();\n```\n\n### Usage Example 📝\n\n```dart\nFuture\u003cList\u003cUser\u003e\u003e findByTitleStartingWith(String title) {\n  return dynamicMethod('findByTitleStartingWith', [title]);\n}\n```\n\n## Filters: Pagination, Sorting, and Size 📊\n\nSnail supports additional filtering through the `size`, `page`, and `sort` parameters:\n\n- **`size`**: Specifies the number of records to fetch per page. Example: `size: 20`.\n- **`page`**: Specifies the page number to fetch. Example: `page: 1` (fetches the first 20 records if `size` is set to 20).\n- **`sort`**: Specifies the sorting order. Use the format `\u003cfield\u003e,\u003corder\u003e`, where `\u003corder\u003e` can be `asc` or `desc`. Example: `sort: 'createdAt,asc'`.\n\nBy default, Snail applies a descending sort (`createdAt,desc`) if no sorting is specified.\n\n### Example Usage 📝\n\n```dart\nFuture\u003cList\u003cUser\u003e\u003e findAllUsersWithPagination() async {\n  return await userRepository.findAll(\n    size: 20,\n    page: 1,\n    sort: 'createdAt,asc',\n  );\n}\n```\n\n## CRUD Operations ⚙️\n\n### Save or Update an Entity 💾\n\n```dart\nFuture\u003cint\u003e save(T entity);\n```\n\n### Save or Update Multiple Entities 💾💾\n\n```dart\nFuture\u003cList\u003cint\u003e\u003e saveAll(List\u003cT\u003e entities);\n```\n\n### Find an Entity by ID 🔍\n\n```dart\nFuture\u003cT?\u003e findById(ID id);\n```\n\n### Find All Entities 🔎\n\n```dart\nFuture\u003cList\u003cT\u003e\u003e findAll({int? size, int? page, String? sort});\n```\n\n### Delete an Entity by ID 🗑️\n\n```dart\nFuture\u003cint\u003e deleteById(ID id);\n```\n\n### Delete All Entities 🗑️🗑️\n\n```dart\nFuture\u003cint\u003e deleteAll(List\u003cT\u003e? entities);\n```\n\n### Count Entities 🔢\n\n```dart\nFuture\u003cint\u003e count();\n```\n\n## Automatic Fields: `createdAt` and `updatedAt` 🕒\n\nSnail automatically adds `createdAt` and `updatedAt` fields to all models. These fields track when a record was created and last updated.\n\n### Optional Usage in Models 📌\n\nIf you wish to explicitly include these fields in your model, you can define them as optional:\n\n```dart\nclass TodoModel {\n  final String id;\n  final String title;\n  final bool isCompleted;\n  final DateTime? createdAt;\n  final DateTime? updatedAt;\n\n  TodoModel({\n    required this.id,\n    required this.title,\n    this.isCompleted = false,\n    this.createdAt,\n    this.updatedAt,\n  });\n\n  Map\u003cString, dynamic\u003e toMap() {\n    return \u003cString, dynamic\u003e{\n      'id': id,\n      'title': title,\n      'isCompleted': isCompleted,\n      'createdAt': createdAt,\n      'updatedAt': updatedAt,\n    };\n  }\n\n  factory TodoModel.fromMap(Map\u003cString, dynamic\u003e map) {\n    return TodoModel(\n      id: map['id'] as String,\n      title: map['title'] as String,\n      isCompleted: map['isCompleted'] as bool,\n      createdAt: map['createdAt'] as DateTime?,\n      updatedAt: map['updatedAt'] as DateTime?,\n    );\n  }\n}\n```\n\n## Full API 📚\n\nBelow is the complete list of methods provided by Snail Repository:\n\n| Method                                             | Description                                                      |\n| -------------------------------------------------- | ---------------------------------------------------------------- |\n| `save(T entity)`                                   | Saves or updates an entity in the database.                      |\n| `saveAll(List\u003cT\u003e entities)`                        | Saves or updates multiple entities in the database.              |\n| `findById(ID id)`                                  | Finds an entity by its primary key.                              |\n| `findAll({int? size, int? page, String? sort})`    | Retrieves all entities with optional pagination and sorting.     |\n| `deleteAll(List\u003cT\u003e? entities)`                     | Deletes all entities or a list of specified entities.            |\n| `count()`                                          | Counts the total number of entities in the database.             |\n| `dynamicMethod(String name, List\u003cObject?\u003e params)` | Executes a query based on the dynamic method naming conventions. |\n\n## Contributing 🤝\n\nFeel free to fork this repository and contribute by submitting a pull request. Your contributions are welcome! 💡\n\n## License 📜\n\nThis project is licensed under the MIT License.\n\n---\n\nMade with ❤️ for Flutter developers! 🎯\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevandersondev%2Fsnail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevandersondev%2Fsnail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevandersondev%2Fsnail/lists"}