fpad 1.0.1

A lightweight offline-safe structured file format (.fpad) with encoding, decoding, schema validation, and file IO utilities.

📦 FPAD - A Structured Data Format for Dart

A simple, lightweight, and predictable schema for storing and sharing list-based data in Dart & Flutter applications.

🧩 What is FPAD?

fpad provides a universal, JSON-based schema for representing lists and items. It's designed for applications that need a reliable way to structure, save, and share data for offline use, backups, or exports.

Instead of dealing with raw maps and unstructured data, fpad gives you type-safe Dart classes (FPadSchema, FPadList, FPadItem) that guarantee data integrity. The library includes utilities to encode this schema to a JSON string, decode it back, and handle file I/O, making it trivial to work with .fpad files (or any other extension you choose).

The core of fpad is its well-defined schema, not a complex binary format. The resulting files are human-readable JSON.

// Example 'my_data.fpad' file content
{
  "version": "1.0.0",
  "lists": [
    {
      "id": "list_01",
      "name": "Groceries",
      "items": [
        {
          "id": "item_01",
          "name": "Milk",
          "extra": { "quantity": 2 }
        },
        {
          "id": "item_02",
          "name": "Eggs",
          "extra": null
        }
      ]
    }
  ],
  "extra": { "app": "My Awesome App" }
}

✨ Features

• 📝 Pre-defined Schema: A clear, versioned structure for lists and items.
• 🔒 Type-Safe: Work with Dart classes, not raw Map<String, dynamic>. Avoid runtime errors from typos or incorrect data types.
• 🔄 Simple Serialization: Easily encode to and decode from JSON.
• 📁 File I/O Utilities: Read and write your schema to files with a single function call.
• ✅ Robust Validation: Deserialization automatically validates the data structure, throwing a FormatException on malformed input.
• 💎 Pure Dart: Works in any Dart or Flutter project.
• 🧪 Fully Tested: High test coverage ensures reliability.

Installation

Add this to your pubspec.yaml:

dependencies:
  fpad: ^1.0.0

Then run:

dart pub get

🚀 Quick Start

Import the package:

import 'package:fpad/fpad.dart';

1. Create Your Data Using the Schema

Build your data using the type-safe fpad classes.

void main() {
  // Define items and lists
  final groceries = FPadList(
    id: 'list_01',
    name: 'Groceries',
    items: [
      FPadItem(id: 'item_01', name: 'Milk', extra: {'quantity': 2}),
      FPadItem(id: 'item_02', name: 'Eggs'),
    ],
  );

  // Create the top-level schema object
  final myData = FPadSchema(
    version: '1.0.0',
    lists: [groceries],
    extra: {'author': 'MyApp'},
  );
}

2. Save to a File

Use FPadFileIO to save your schema object directly to a file.

  // Save the schema to a file
  final filePath = 'my_groceries.fpad';
  await FPadFileIO.saveToFile(filePath, myData);
  print('Data saved to $filePath');

3. Load from a File

Read the file and instantly get a validated, type-safe FPadSchema object back.

  // Load the schema from the file
  final loadedData = await FPadFileIO.readFromFile(filePath);

  // Access your data with confidence
  print('Loaded list: ${loadedData.lists.first.name}'); // Prints: Groceries
  print('First item: ${loadedData.lists.first.items.first.name}'); // Prints: Milk

  // The loaded object is equal to the original one
  assert(myData == loadedData);
}

🧪 Running Tests

To run the package tests, clone the repository and run:

dart test

A complete, runnable example is available in the example folder.

🤝 Contributing

Pull requests are welcome! Please follow standard Dart style and run:

dart format .
dart analyze
dart test

before submitting.

📄 License

This package is open-source under the MIT License.