fpad 1.0.0

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

Here is a beautiful, complete, production-quality README.md for your fpad package. It explains everything clearly, includes examples, diagrams (ASCII), badges, installation guide, API usage, best practices, and more.

You can copy-paste this directly into your repository.

📦 FPAD - Fast Portable App Data Format

A simple, lightweight, offline-friendly structured file format for Dart & Flutter.

🧩 What is FPAD?

FPAD is a small and efficient file format designed for offline apps that need to save structured data locally using custom file extensions – such as:

.fpad – FocusPad list files

.todo.fpad – To-do export file

.backup.fpad – Full app backup

The library provides encoding, decoding, validation, and file I/O helpers, making it easy to integrate custom file types into any app.

FPAD uses regular UTF-8 JSON internally, wrapped in a lightweight, versioned envelope:

FPAD File Structure

---

| Magic header: FPAD | | Version: 1 | | Payload: JSON data |

This ensures your files stay portable, readable, and safe.

✨ Features

🔐 Schema-validated format (ensures correct structure)

⚡ Fast encoder/decoder

📁 Utilities for reading/writing .fpad files

🧪 Fully testable (with included test suite)

🛠 Framework-agnostic (pure Dart)

📦 Safe for long-term data storage

🎯 Great for offline apps that avoid cloud dependency

📥 Installation

Add this to your pubspec.yaml:

dependencies: fpad: ^1.0.0

Then run:

dart pub get

🚀 Quick Start

1. Import import 'package:fpad/fpad.dart';

🔄 Encoding Data to FPAD import 'package:fpad/fpad.dart';

void main() { final data = { 'title': 'Shopping List', 'items': ['Milk', 'Bread', 'Eggs'] };

final encoded = FpadEncoder.encode(data); print(encoded); }

Output example:

FPAD:1:{"title":"Shopping List","items":["Milk","Bread","Eggs"]}

🔁 Decoding FPAD Back to Data final decoded = FpadDecoder.decode(encoded);

print(decoded['title']); // Shopping List print(decoded['items']); // [Milk, Bread, Eggs]

💾 Reading & Writing .fpad Files import 'package:fpad/src/file_io.dart';

void main() async { final data = {'name': 'FocusPad Backup', 'version': 1};

// Write to file await FpadFileIO.writeToFile('backup.fpad', data);

// Read file final loaded = await FpadFileIO.readFromFile('backup.fpad');

print(loaded); }

🧱 FPAD Schema

All FPAD files follow this structure:

class FpadSchema { final String magic; // Always "FPAD" final int version; // Format version final Map<String, dynamic> payload; }

This guarantees:

Header validation

Version validation

Consistent payload integrity

📂 File Format Design

FPAD keeps files human-readable while still being structured.

Example .fpad file content:

FPAD:1:{ "id": "b23ff2", "name": "Focus Pad Export", "lists": [ { "id": "1", "title": "Groceries", "items": ["Apple", "Orange", "Rice"] } ] }

🧪 Running Tests dart test

All tests included under /test.

📝 Example Project

A complete example is available under:

example/main.dart

Run it using:

dart run example/main.dart

🔒 Safety Notes

FPAD uses pure JSON internally – no binary corruption risk

Broken headers or invalid JSON raise meaningful errors

Safe for user backups and app exports

📦 Apps That Should Use FPAD

To-do apps

Notes and checklist apps

Habit trackers

Offline planners

Lightweight CRMs

Backup utilities

If your app doesn't rely on the cloud, FPAD is perfect for exchanging user data.

🤝 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.