Zorphy

Zorphy is a powerful code generation package for Dart/Flutter that provides clean, immutable class definitions with advanced features including copyWith methods, JSON serialization, equality, toString, inheritance support, and sophisticated patch mechanisms.

✨ Features

📋 Immutable Data Classes - Clean, immutable class definitions with minimal boilerplate
🔄 CopyWith Methods - Generate copyWith methods for creating modified copies
🎯 Function-based CopyWith - Optional function-based copyWith for computed updates
🔧 Patch System - Advanced patching mechanism for partial updates with nested support

📚 Documentation & Resources

Official Documentation - Comprehensive guides and examples
pub.dev - Package on the Dart package repository
GitHub - Source code and issue tracker
Examples - Complete working examples in the repository
Zuraffa - Clean Architecture framework for Flutter
📦 JSON Serialization - Full toJson/fromJson support with polymorphic type handling
⚖️ Equality - Auto-generated == operator and hashCode
📝 toString - Meaningful string representations for debugging
🔐 Sealed Classes - Support for sealed classes with exhaustiveness checking
🌳 Self-Referencing Types - Handle tree structures and hierarchical data
🏭 Factory Methods - Support for custom factory constructors
🧬 Inheritance & Polymorphism - Multiple inheritance, generics, and interfaces
🔢 Enum Support - Full enum integration with JSON serialization
📊 CompareTo - Generate comparison methods showing differences between instances
🔄 ChangeTo - Convert between related types in inheritance hierarchies
🤖 AI-Friendly CLI - Command-line tool optimized for AI agents and developers
🔌 MCP Server - Model Context Protocol server for agentic integration
🔮 Plugin API - Extensible compiler pipeline with third-party plugin support

📦 Installation

Add the dependencies to your pubspec.yaml:

dependencies:
  zorphy_annotation: ^2.0.0

dev_dependencies:
  zorphy: ^2.0.0
  build_runner: ^2.4.0

Install the CLI globally:

dart pub global activate zorphy

🚀 Quick Start

Using the CLI (Recommended for AI Agents)

The Zorphy CLI is designed for optimal AI agent usage:

# Interactive entity creation
zorphy create -n User

# Create with fields
zorphy create -n Product \
  --field name:String \
  --field price:double \
  --field inStock:bool

# Quick create (simple entity with defaults)
zorphy new -n Category

# Build all entities
zorphy build

# List entities
zorphy list

Manual Class Definition

Or create classes manually:

import 'package:zorphy_annotation/zorphy_annotation.dart';

part 'user.zorphy.dart';

@Zorphy()
abstract class $User {
  String get name;
  int get age;
  String? get email;
}

Run the generator:

dart run build_runner build

Use the generated class:

void main() {
  final user = User(name: 'Alice', age: 30);

  // Copy with changes
  final olderUser = user.copyWith(age: 31);

  // Convert to JSON (if generateJson: true)
  final json = user.toJson();

  // Create from JSON
  final fromJson = User.fromJson(json);
}

🤖 Zorphy CLI

The Zorphy CLI provides an intuitive interface for creating and managing entities, optimized for both human developers and AI agents.

Installation

# Install globally
dart pub global activate zorphy

# Or run directly
dart run zorphy:zorphy_cli

CLI Commands

`create` - Create New Entity

Create a new Zorphy entity with full control over options:

zorphy create [options]

Options:

-n, --name - Entity name (required)
-o, --output - Output directory (default: lib/entities)
-p, --package - Package name for imports
--json - Enable JSON serialization (default: true)
--copywith-fn - Enable function-based copyWith (default: false)
--compare - Enable compareTo (default: true)
--sealed - Create sealed class (default: false)
--non-sealed - Create non-sealed class (default: false)
-f, --fields - Interactive field prompts (default: true)
--field - Add fields directly (name:type or name:type?)
--extends - Interface to extend (e.g., $BaseEntity)
--subtypes - Explicit subtypes for polymorphism

Examples:

# Interactive creation
zorphy create -n User

# With fields
zorphy create -n User \
  --field name:String \
  --field age:int \
  --field email:String?

# With all options
zorphy create -n Product \
  --output lib/models \
  --json \
  --compare \
  --field name:String \
  --field price:double \
  --field category:String?

# Sealed class
zorphy create -n Result --sealed

# With inheritance
zorphy create -n Admin \
  --extends User \
  --field permissions:List<String>

`new` - Quick Create

Create a simple entity with default settings:

zorphy new -n EntityName

Options:

-n, --name - Entity name (required)
-o, --output - Output directory (default: lib/entities)
--json - Enable JSON (default: true)

Example:

zorphy new -n Product

`build` - Run Code Generation

Generate code for all Zorphy entities:

zorphy build [options]

Options:

-w, --watch - Watch for changes (default: false)
-c, --clean - Clean before build (default: false)
-o, --output - Build output directory

Examples:

# Build once
zorphy build

# Clean and build
zorphy build --clean

# Watch mode
zorphy build --watch

`list` - List Entities

List all Zorphy entities in a directory:

zorphy list [options]

Options:

-o, --output - Directory to search (default: lib/entities)

Example:

zorphy list
# Output:
# 📂 Zorphy Entities in lib/entities:
#
# 📄 User
#    File: lib/entities/user.dart
#    ✓ JSON support
#    ✓ Function-based copyWith
#
# Total: 1 entity/entities

Field Types

The CLI supports various field types:

Basic types: String, int, double, bool, num, DateTime
Nullable types: Add ? after type (e.g., String?, int?)
Generic types: List<Type>, Set<Type>, Map<KeyType, ValueType>
Custom types: Any other class name

Examples:

--field name:String
--field age:int
--field email:String?
--field tags:List<String>
--field metadata:Map<String, dynamic>
--field createdAt:DateTime

Interactive Mode

When using create with --fields (default), the CLI prompts for fields:

$ zorphy create -n User

📝 Creating Zorphy Entity: User
Enter fields one by one. Press Enter without input to finish.

Field name (or press Enter to finish): name
Field type (e.g., String, int, List<String>): String
✓ Added field: name (String)

Field name (or press Enter to finish): age
Field type (e.g., String, int, List<String>): int
✓ Added field: age (int)

Field name (or press Enter to finish): address
Field type (e.g., String, int, Address): Address
✓ Added field: address (Address)

Field name (or press Enter to finish):

✓ Created entity file: lib/entities/user.dart

📋 Next steps:
  1. Run: zorphy build
  2. Or run: dart run build_runner build
  3. Import and use your User class

✨ Generated 2 fields:
  - name: String
  - age: int

🔮 Plugin API

Zorphy 2.0 supports third-party plugins that can inspect and mutate generated code before it is emitted. Plugins are Dart classes that extend ZorphyPlugin and implement transform hooks for classes, methods, and fields.

Quick example — a plugin that adds a timestamp field:

import 'package:code_builder/code_builder.dart';
import 'package:zorphy/zorphy_plugin.dart';

class TimestampPlugin extends ZorphyPlugin {
  @override
  String get name => 'timestamp';

  @override
  Spec transformClass(Spec spec, PluginContext context) {
    if (spec is! Class) return spec;
    return spec.rebuild((c) => c
      ..methods.add(Method((m) {
        m.name = 'generatedAt';
        m.type = MethodType.getter;
        m.returns = refer('DateTime');
        m.lambda = true;
        m.body = refer('DateTime').property('now').call([]).code;
      })));
  }
}

Register via build.yaml:

targets:
  $default:
    builders:
      zorphy:zorphy:
        options:
          plugins:
            - package:my_package/timestamp_plugin.dart

Programmatic registration:

import 'package:zorphy/zorphy_plugin.dart';

final registry = PluginRegistry();
registry.register(TimestampPlugin());
final generator = ZorphyGenerator(pluginRegistry: registry);

Plugins execute in topological order via runBefore/runAfter constraints. When no plugins are registered, output is byte-identical to the pre-plugin pipeline.

📚 Full Plugin API docs · Example

🔌 Zorphy MCP Server

The Model Context Protocol (MCP) server enables AI agents like Claude to programmatically create and manage Zorphy entities.

Setting up the MCP Server

Add to your Claude/MCP client configuration:

{
  "mcpServers": {
    "zorphy": {
      "command": "dart",
      "args": ["run", "zorphy:zorphy_mcp_server"]
    }
  }
}

Available MCP Tools

`create_entity`

Create a new Zorphy entity programmatically.

Parameters:

{
  "name": "string (required)",
  "output_dir": "string (default: lib/entities)",
  "fields": [
    {
      "name": "string",
      "type": "string",
      "nullable": "boolean (default: false)"
    }
  ],
  "options": {
    "generateJson": "boolean (default: true)",
    "generateCopyWithFn": "boolean (default: false)",
    "generateCompareTo": "boolean (default: true)",
    "sealed": "boolean (default: false)",
    "nonSealed": "boolean (default: false)"
  },
  "extends": "string (optional)",
  "explicit_subtypes": ["string"]
}

Example:

{
  "name": "User",
  "fields": [
    { "name": "id", "type": "String" },
    { "name": "name", "type": "String" },
    { "name": "email", "type": "String?", "nullable": true },
    { "name": "age", "type": "int" }
  ],
  "options": {
    "generateJson": true,
    "generateCompareTo": true
  }
}

`list_entities`

List all Zorphy entities in a directory.

Parameters:

{
  "directory": "string (default: lib/entities)"
}

`generate_entity_code`

Generate entity code without writing to file (preview mode).

Parameters: Same as create_entity

Use case: Preview generated code before creating the file.

`build_entities`

Run build_runner to generate Zorphy code.

Parameters:

{
  "clean": "boolean (default: false)",
  "watch": "boolean (default: false)"
}

`analyze_entity`

Analyze an existing entity file and return its structure.

Parameters:

{
  "file_path": "string (required)"
}

Returns:

{
  "name": "User",
  "path": "lib/entities/user.dart",
  "hasJson": true,
  "hasCopyWithFn": false,
  "isSealed": false,
  "fields": ["id: String", "name: String", "email: String?", "age: int"],
  "extends": null
}

`create_sealed_hierarchy`

Create a sealed class hierarchy with multiple variants.

Parameters:

{
  "base_name": "string (required)",
  "variants": [
    {
      "name": "string",
      "fields": [{ "name": "string", "type": "string", "nullable": "boolean" }]
    }
  ],
  "output_dir": "string (default: lib/entities)",
  "generate_json": "boolean (default: true)"
}

Example - Creating a Result type:

{
  "base_name": "Result",
  "variants": [
    {
      "name": "Success",
      "fields": [{ "name": "data", "type": "dynamic" }]
    },
    {
      "name": "Error",
      "fields": [
        { "name": "message", "type": "String" },
        { "name": "code", "type": "int" }
      ]
    }
  ]
}

This creates:

$$Result - Sealed base class
$Success - Success variant
$Error - Error variant

Agentic Usage Examples

Example 1: Agent Creating a User Entity

# Agent using MCP server
mcp.call_tool("create_entity", {
    "name": "User",
    "fields": [
        {"name": "id", "type": "String"},
        {"name": "username", "type": "String"},
        {"name": "email", "type": "String?", "nullable": true},
        {"name": "createdAt", "type": "DateTime"}
    ],
    "options": {
        "generateJson": True,
        "generateCompareTo": True
    }
})

Example 2: Agent Creating a Payment Hierarchy

mcp.call_tool("create_sealed_hierarchy", {
    "base_name": "PaymentMethod",
    "variants": [
        {
            "name": "CreditCard",
            "fields": [
                {"name": "cardNumber", "type": "String"},
                {"name": "expiryDate", "type": "String"}
            ]
        },
        {
            "name": "PayPal",
            "fields": [
                {"name": "email", "type": "String"}
            ]
        }
    ]
})

Example 3: Agent Analyzing and Extending

# Analyze existing entity
analysis = mcp.call_tool("analyze_entity", {
    "file_path": "lib/entities/user.dart"
})

# Extend with new field
mcp.call_tool("create_entity", {
    "name": "Admin",
    "extends": "$User",
    "fields": [
        {"name": "permissions", "type": "List<String>"}
    ]
})

📖 Complete Feature Guide

1. Class Definition Patterns

Concrete Classes (Single $)

Use a single $ prefix for concrete classes:

@Zorphy()
abstract class $Person {
  String get firstName;
  String get lastName;
  int? get age;
}

// Usage: Omit the $ when using
final person = Person(firstName: 'John', lastName: 'Doe');

Sealed Abstract Classes (Double $$)

Use $$ prefix for sealed abstract classes. Sealed classes enable exhaustiveness checking:

@Zorphy()
abstract class $$Shape {
  double get area;
}

@Zorphy()
abstract class $Circle implements $$Shape {
  double get radius;

  @override
  double get area => 3.14159 * radius * radius;
}

@Zorphy()
abstract class $Rectangle implements $$Shape {
  double get width;
  double get height;

  @override
  double get area => width * height;
}

// Exhaustiveness checking
String describeShape(Shape shape) => switch (shape) {
  Circle() => 'A circle',
  Rectangle() => 'A rectangle',
};

Non-Sealed Abstract Classes

Use nonSealed: true to create non-sealed abstract classes:

@Zorphy(nonSealed: true)
abstract class $$BaseEntity {
  String get id;
  DateTime get createdAt;
}

2. JSON Serialization

Enable JSON generation with generateJson: true:

@Zorphy(generateJson: true)
abstract class $User {
  String get id;
  String get name;
  String? get email;
}

Features:

Automatic toJson() and fromJson()
toJsonLean() removes metadata for cleaner output
Handles nested objects and collections
Supports polymorphic serialization with type discriminators

Polymorphic JSON

@Zorphy()
abstract class $$Animal {}

@Zorphy(generateJson: true)
abstract class $Dog implements $$Animal {
  String get breed;
}

@Zorphy(generateJson: true)
abstract class $Cat implements $$Animal {
  double get whiskerLength;
}

// Serialization includes type discriminator
final dog = Dog(breed: 'Labrador');
final json = dog.toJson();
// {"__typename": "Dog", "breed": "Labrador"}

// Deserialization automatically handles type
final animal = Animal.fromJson(json);
print(animal); // Instance of Dog

3. CopyWith Methods

Basic CopyWith

@Zorphy()
abstract class $User {
  String get name;
  int get age;
}

final user = User(name: 'Alice', age: 30);
final updated = user.copyWith(name: 'Bob');
// User(name: 'Bob', age: 30)

Function-based CopyWith

Enable with generateCopyWithFn: true:

@Zorphy(generateCopyWithFn: true)
abstract class $Counter {
  int get value;
}

final counter = Counter(value: 0);
final incremented = counter.copyWithCounterFn(
  value: () => counter.value + 1,
);
// Counter(value: 1)

Type-specific CopyWith

@Zorphy()
abstract class $Pet {
  String get name;
  int get age;
}

@Zorphy()
abstract class $Dog implements $Pet {
  String get breed;
}

final dog = Dog(name: 'Buddy', age: 5, breed: 'Labrador');
final updated = dog.copyWithDog(breed: 'Golden Retriever');
// Updates only Dog-specific fields

4. Patch System

The patch system provides powerful partial updates with nested support:

@Zorphy()
abstract class $User {
  String get name;
  int get age;
}

// Create a patch
final patch = UserPatch.create()
  ..withName('New Name')
  ..withAge(25);

// Apply patch
final updated = user.patchWithUser(patchInput: patch);

Nested Patches

@Zorphy()
abstract class $Address {
  String get street;
  String get city;
}

@Zorphy()
abstract class $User {
  String get name;
  Address get address;
}

// Nested patching
final patch = UserPatch.create()
  ..withName('Updated Name')
  ..withAddressPatch((addrPatch) => addrPatch
    ..withStreet('123 New St')
    ..withCity('New York'));

final updated = user.patchWithUser(patchInput: patch);

Collection Patching

@Zorphy()
abstract class $TodoList {
  String get title;
  List<Todo> get todos;
}

// Update specific item in list
final patch = TodoListPatch.create()
  ..updateTodosAt(0, (todoPatch) => todoPatch
    ..withCompleted(true)
    ..withTitle('Updated Title'));

Functional Patches

// Using functions for computed updates
final patch = CounterPatch.create()
  ..withValue((current) => current + 1);

final updated = counter.patchWithCounter(patchInput: patch);

Map and List Patching

// Patch specific Map entries
final settingsPatch = SettingsPatch.create()
  ..updateConfigValue('theme', 'dark')
  ..updateConfigValue('fontSize', '16');

// Patch specific List indices
final todoListPatch = TodoListPatch.create()
  ..updateTodosAt(2, (todoPatch) => todoPatch..withCompleted(true));

5. Inheritance & Polymorphism

Multiple Inheritance

@Zorphy()
abstract class $Pet {
  String get name;
  int get age;
}

@Zorphy()
abstract class $Dog {
  String get barkSound;
}

@Zorphy()
abstract class $Cat {
  double get whiskerLength;
}

// Implement multiple interfaces
@Zorphy()
abstract class $FrankensteinsDogCat implements $Dog, $Pet, $Cat {
  // Inherits all fields from all interfaces
}

Generic Inheritance and JSON

Zorphy now provides full support for generic types in JSON serialization:

@Zorphy(generateJson: true)
abstract class $PaginatedResponse<T> {
  List<T> get items;
  int get total;
}

// Generated code includes genericArgumentFactories: true
// final response = PaginatedResponse<User>.fromJson(json, (j) => User.fromJson(j as Map<String, dynamic>));

Custom JSON Converters

You can now use @JsonConverter with Zorphy entities:

class DateTimeConverter extends JsonConverter<DateTime, String> {
  const DateTimeConverter();
  @override
  DateTime fromJson(String json) => DateTime.parse(json);
  @override
  String toJson(DateTime object) => object.toIso8601String();
}

@Zorphy(generateJson: true)
abstract class $Event {
  @DateTimeConverter()
  DateTime get timestamp;
}

T? find(String id); List

@Zorphy() abstract class $UserRepository implements $$Repository

@override List


#### Generic Classes with Type Constraints

```dart
@Zorphy()
abstract class $$Base<T> {
  T get value;
}

@Zorphy()
abstract class $Derived<T extends num> implements $$Base<T> {
  @override
  T get value;

  T get doubled => value * 2;
}

6. Explicit Subtypes & ChangeTo

Use explicitSubTypes to enable cross-type operations:

@Zorphy(explicitSubTypes: [$Dog, $Cat])
abstract class $Pet {
  String get name;
  int get age;
}

@Zorphy()
abstract class $Dog implements $Pet {
  String get breed;
}

@Zorphy()
abstract class $Cat implements $Pet {
  double get whiskerLength;
}

This generates changeTo methods:

final dog = Dog(name: 'Buddy', age: 5, breed: 'Labrador');

// Convert Dog to Cat
final cat = dog.changeToCat(whiskerLength: 3.5);
// Cat(name: 'Buddy', age: 5, whiskerLength: 3.5)

7. CompareTo Feature

Generate comparison methods showing differences between instances:

@Zorphy(generateCompareTo: true)
abstract class $User {
  String get name;
  int get age;
}

final user1 = User(name: 'Alice', age: 30);
final user2 = User(name: 'Alice', age: 35);

final diff = user1.compareToUser(user2);
// {'age': () => 35}

8. Enum Support

Full enum integration with JSON serialization:

enum Status {
  active,
  inactive,
  pending,
}

@Zorphy(generateJson: true)
abstract class $User {
  String get name;
  Status get status;
}

final user = User(name: 'Alice', status: Status.active);
final json = user.toJson();
// {"name": "Alice", "status": "active"}

final fromJson = User.fromJson(json);
// User(name: 'Alice', status: Status.active)

9. Self-Referencing Classes

Handle tree structures and hierarchical data:

@Zorphy(generateJson: true)
abstract class $TreeNode {
  String get value;
  List<TreeNode>? get children;
  TreeNode? get parent;
}

final tree = TreeNode(
  value: 'root',
  children: [
    TreeNode(value: 'child1'),
    TreeNode(value: 'child2'),
  ],
);

10. Factory Methods

Support for custom factory constructors:

@Zorphy()
abstract class $Person {
  String get firstName;
  String get lastName;

  // Custom factory method
  factory $Person.fromNames(String first, String last) = _PersonFromNames;

  // Default factory
  factory $Person.empty() => Person(firstName: '', lastName: '');
}

class _PersonFromNames extends Person {
  _PersonFromNames({
    required String first,
    required String last,
  }) : super(
    firstName: first.toUpperCase(),
    lastName: last.toUpperCase(),
  );
}

// Usage
final person = Person.fromNames('john', 'doe');
// Person(firstName: 'JOHN', lastName: 'DOE')

11. Private Constructors

Use underscore suffix to hide public constructor:

@Zorphy(hidePublicConstructor: true)
abstract class $Config_ {
  String get apiKey;
  String get endpoint;
}

// Define custom factory in the same file
Config createProductionConfig() {
  return Config._(
    apiKey: 'prod-key',
    endpoint: 'https://api.prod.com',
  );
}

Config createDevConfig() {
  return Config._(
    apiKey: 'dev-key',
    endpoint: 'https://api.dev.com',
  );
}

// Usage - Config() constructor is not available
final config = createProductionConfig();

12. Constant Constructors

Enable constant constructors for immutable values:

@Zorphy()
abstract class $Color {
  int get red;
  int get green;
  int get blue;

  const $Color();
}

// Usage
const red = Color(red: 255, green: 0, blue: 0);

13. Nullable Fields

Full null safety support:

@Zorphy()
abstract class $User {
  String get name;
  String? get email;
  String? get phone;
}

final user = User(name: 'Alice');
// email and phone are null

final withEmail = user.copyWith(email: 'alice@example.com');

14. Complex Nested Structures

@Zorphy()
abstract class $Company {
  String get name;
  List<Department> get departments;
}

@Zorphy()
abstract class $Department {
  String get name;
  List<Employee> get employees;
}

@Zorphy()
abstract class $Employee {
  String get name;
  String? get title;
}

// Deep nesting with proper JSON support
final company = Company(
  name: 'Tech Corp',
  departments: [
    Department(
      name: 'Engineering',
      employees: [
        Employee(name: 'Alice', title: 'Engineer'),
      ],
    ),
  ],
);

15. Generic Fields and Methods

typedef JsonConverter<T> = T Function(dynamic);

@Zorphy()
abstract class $ApiResponse<T> {
  bool get success;
  T? get data;
  String? get error;
}

@Zorphy()
abstract class $UserListResponse implements $ApiResponse<List<User>> {
  @override
  bool get success;

  @override
  List<User>? get data;

  @override
  String? get error;
}

16. Combining Multiple Features

enum UserRole {
  admin,
  user,
  guest,
}

@Zorphy(
  generateJson: true,
  generateCopyWithFn: true,
  generateCompareTo: true,
)
abstract class $User {
  String get id;
  String get name;
  String? get email;
  int get age;
  UserRole get role;
  DateTime get createdAt;
  List<String>? get tags;
}

// All features available
final user = User(
  id: '1',
  name: 'Alice',
  age: 30,
  role: UserRole.admin,
  createdAt: DateTime.now(),
);

// CopyWith
final updated = user.copyWith(email: 'alice@example.com');

// Function-based CopyWith
final aged = user.copyWithUserFn(age: () => user.age + 1);

// Patch
final patched = user.patchWithUser(
  patchInput: UserPatch.create()..withTags(['developer', 'dart']),
);

// CompareTo
final diff = user.compareToUser(updated);

// JSON
final json = user.toJson();
final fromJson = User.fromJson(json);

🎨 Annotation Options

The @Zorphy annotation supports these options:

Option	Type	Default	Description
`generateJson`	`bool`	`false`	Enable JSON serialization (`toJson`/`fromJson`)
`generateCopyWithFn`	`bool`	`false`	Generate function-based copyWith methods
`generateCompareTo`	`bool`	`true`	Generate comparison methods
`explicitSubTypes`	`List<Type>`	`null`	Specify explicit subtypes for polymorphic operations
`explicitToJson`	`bool`	`true`	Control JSON serialization generation
`hidePublicConstructor`	`bool`	`false`	Hide the public constructor for custom factories
`nonSealed`	`bool`	`false`	Create non-sealed abstract classes instead of sealed

🏗️ Build Configuration

By default, Zorphy runs as part of the build process. The builder is configured in build.yaml:

targets:
  $default:
    builders:
      zorphy:zorphy:
        enabled: true

Run the generator:

# Build once
dart run build_runner build

# Build and watch for changes
dart run build_runner watch

# Clean generated files
dart run build_runner clean

# Or use the CLI
zorphy build
zorphy build --watch
zorphy build --clean

📝 Naming Conventions

Class Prefixes

$ClassName - Concrete class definition (use ClassName in code)
$$ClassName - Sealed abstract class (exhaustiveness checking)
$ClassName_ - Class with hidden private constructor

Generated Files

*.zorphy.dart - Generated code from @Zorphy annotation
*.zorphy2.dart - Generated code from @Zorphy2 annotation (builds before zorphy)

Generated Enums

ClassName$ - Enum of field names for patch system

Generated Patch Classes

ClassNamePatch - Patch class for partial updates

🔄 Migration from Morphy

Zorphy is designed for easy migration from Morphy:

Replace @Morphy with @Zorphy
Replace morphy_annotation dependency with zorphy_annotation
Replace zikzak_morphy dependency with zorphy
Run dart run build_runner clean
Run dart run build_runner build

Key Differences:

Better patch system with nested support
Enhanced generic handling
Improved error messages
More flexible inheritance patterns
Built-in CLI and MCP server for AI agents

🐛 Troubleshooting

Type Not Found Errors

If you get type not found errors, ensure:

You've added part 'filename.zorphy.dart'; to your file
You've run dart run build_runner build or zorphy build
The import includes package:zorphy_annotation/zorphy_annotation.dart

Generic Type Issues

When using generics, ensure type parameter names match between parent and child:

// ✅ Correct - Same generic name
abstract class $A<T> { }
abstract class $B<T> implements $A<T> { }

// ❌ Wrong - Different generic names
abstract class $A<T1> { }
abstract class $B<T2> implements $A<T1> { }

Circular Dependencies

Use @Zorphy2 for classes that need to be built before others:

@Zorphy2()
abstract class $Base {
  String get id;
}

@Zorphy()
abstract class $Derived implements $Base {
  String get extra;
}

License

MIT License - see LICENSE file for details

Acknowledgments

Inspired by and designed to improve upon the Morphy code generation package.

Made with 🔥 by the ZikZak AI team for the community and AI agents

Zuraffa - Clean Architecture framework for Flutter with Zorphy entities as the foundation.

✅ Entity-based Clean Architecture
✅ UseCase pattern (single-shot, streaming, background)
✅ State management with Zorphy entities
✅ ZFA CLI for code generation
✅ Result-based error handling
✅ Comprehensive caching support
✅ MCP server for AI/IDE integration

Visit zuraffa.com for complete documentation and guides.

Zorphy

✨ Features

📚 Documentation & Resources

📦 Installation

🚀 Quick Start

Using the CLI (Recommended for AI Agents)

Manual Class Definition

🤖 Zorphy CLI

Installation

CLI Commands

create - Create New Entity

new - Quick Create

build - Run Code Generation

list - List Entities

Field Types

Interactive Mode

🔮 Plugin API

🔌 Zorphy MCP Server

Setting up the MCP Server

Available MCP Tools

create_entity

list_entities

generate_entity_code

build_entities

analyze_entity

create_sealed_hierarchy

Agentic Usage Examples

📖 Complete Feature Guide

1. Class Definition Patterns

Concrete Classes (Single $)

Sealed Abstract Classes (Double $$)

Non-Sealed Abstract Classes

2. JSON Serialization

Polymorphic JSON

3. CopyWith Methods

Basic CopyWith

Function-based CopyWith

Type-specific CopyWith

4. Patch System

Nested Patches

Collection Patching

Functional Patches

Map and List Patching

5. Inheritance & Polymorphism

Multiple Inheritance

Generic Inheritance and JSON

Custom JSON Converters

6. Explicit Subtypes & ChangeTo

7. CompareTo Feature

8. Enum Support

9. Self-Referencing Classes

10. Factory Methods

11. Private Constructors

12. Constant Constructors

13. Nullable Fields

14. Complex Nested Structures

15. Generic Fields and Methods

16. Combining Multiple Features

🎨 Annotation Options

🏗️ Build Configuration

📝 Naming Conventions

Class Prefixes

Generated Files

Generated Enums

Generated Patch Classes

🔄 Migration from Morphy

🐛 Troubleshooting

Type Not Found Errors

Generic Type Issues

Circular Dependencies

License

Acknowledgments

🦒 Related Projects

Libraries

zorphy package

`create` - Create New Entity

`new` - Quick Create

`build` - Run Code Generation

`list` - List Entities

`create_entity`

`list_entities`

`generate_entity_code`

`build_entities`

`analyze_entity`

`create_sealed_hierarchy`