v0.2.0-beta.1

Release v0.2.0-beta.1

This release introduces significant improvements to the SchemaModel API, enhanced string validation, and better OpenAPI integration.

Key Features

• Code Generation: Generate schema classes from your models
• Type-safe Schema Access: Direct property getters with proper types
• Automatic Validation: Validation happens during construction
• Multiple Validation Approaches: Choose what fits your workflow
• Improved String Validation: New pattern matching options
• JSON Schema Integration: Generate API specifications automatically

Code Generation

Define Your Models

Annotate your models with validation rules:

@Schema()
class Product {
  @IsNotEmpty()
  final String id;

  @MinLength(3)
  final String name;

  final double price;

  final Category category;

  Product({
    required this.id,
    required this.name,
    required this.price,
    required this.category,
  });
}

Run the Generator

Use the build_runner to generate schema classes:

dart run build_runner build --delete-conflicting-outputs

This creates a .schema.dart file with your generated schemas.

SchemaModel API

Creating Schemas

The constructor now validates data automatically:

// Create schema with automatic validation
final schema = ProductSchema({
  'id': '123',
  'name': 'Test Product',
  'price': 19.99
});

// Check if valid
bool valid = schema.isValid;

Accessing Schema Values

Access validated data with type-safe getters:

// Type-safe access to properties
String id = schema.id;
String name = schema.name;
double price = schema.price;

// Access nested schema objects
CategorySchema category = schema.category;
String categoryName = category.name;

Handling Validation Errors

Get detailed error information when validation fails:

if (!schema.isValid) {
  SchemaError? error = schema.getErrors();
  
  // Error details
  String errorType = error?.name;       // e.g., "required_field"
  String message = error?.message;      // e.g., "Required field is missing"
  String? path = error?.path;           // e.g., "category.id"
}

Converting to Models

Transform schema data to strongly-typed models:

// Convert schema to model instance
Product product = schema.toModel();

// Access model properties
String id = product.id;
Category category = product.category;

Alternative Validation Approaches

Choose your preferred validation style:

// Approach 1: Constructor + isValid check
final schema = ProductSchema(data);
if (schema.isValid) {
  final product = schema.toModel();
}

// Approach 2: Direct parse (throws on failure)
try {
  Product product = ProductSchema.parse(data);
} catch (e) {
  // Handle validation error
}

// Approach 3: Try-parse (returns null on failure)
Product? product = ProductSchema.tryParse(data);
if (product != null) {
  // Use valid product
}

Creating Schema from Model

Convert model instances to schemas for serialization:

// Create schema from model instance
final schema = ProductSchema.fromModel(product);

// Serialize to various formats
Map<String, Object?> map = schema.toMap();
String json = schema.toJson();

Enhanced String Validation

Full Pattern Matching

The matches() method now validates entire strings:

// Full string pattern matching (with anchors)
final schema = Ack.string.matches('^[a-z0-9_]{3,16}$');
schema.validate('user_123').isOk;  // true
schema.validate('user@123').isOk;  // false - contains @

Partial String Matching

New contains() method for substring matching:

// Partial string matching
final schema = Ack.string.contains('important');
schema.validate('This is important text').isOk;  // true
schema.validate('Nothing here').isOk;  // false

JSON Schema Integration

Generate API specifications from your schemas:

// Get JSON Schema
Map<String, Object?> jsonSchema = ProductSchema.toJsonSchema();

// Convert to JSON string
String jsonString = jsonEncode(jsonSchema);

Migration Guide

If you're upgrading from 0.1.x, note these changes:

1. Update string pattern validation:

   // Old (0.1.x): Matches substrings
   Ack.string.matches('abc');  // Would match 'abcdef'
   
   // New (0.2.0): Matches whole string
   Ack.string.matches('^abc$'); // Only matches 'abc' exactly
   Ack.string.contains('abc');  // Matches substrings, like old matches()

2. Use the new validation workflow:

   // Create and validate in one step
   final schema = ProductSchema(data);
   
   // Check isValid before using
   if (schema.isValid) {
     schema.id;              // Access schema properties
     schema.category.name;   // Access nested properties
     
     // Or convert to model
     final product = schema.toModel();
   }

Documentation

Full documentation is available at https://docs.page/btwld/ack