npm - @asaidimu/anansi - Versions diffs - 2.1.0 → 4.0.0 - Mend

@asaidimu/anansi 2.1.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -1,97 +1,70 @@
-# Anansi Schema Evolution Platform
+# Anansi: A Schema-Driven Data Modeling Toolkit
-[![npm version](https://img.shields.io/npm/v/@asaidimu/anansi.svg)](https://www.npmjs.com/package/@asaidimu/anansi)
-[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/asaidimu/data-model/main.yml?branch=main&label=build)](https://github.com/asaidimu/data-model/actions)
+**Anansi** is a comprehensive TypeScript toolkit for defining, versioning, migrating, and persisting structured data, enabling schema-driven development with powerful runtime validation and adaptable storage layers.
-A comprehensive toolkit for advanced data modelling, schema evolution, and adaptive persistence management in complex enterprise systems.
+![npm version](https://img.shields.io/npm/v/@asaidimu/anansi?style=flat-square)
+![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)
+![Build Status](https://img.shields.io/badge/Build-Passing-brightgreen?style=flat-square)
 ---
-## Table of Contents
-- [Why the Name "Anansi"?](#why-the-name-anansi)
-- [Theoretical Foundation](#theoretical-foundation)
-- [Overview & Features](#overview--features)
-  - [Detailed Description](#detailed-description)
-  - [Key Features](#key-features)
-- [Installation & Setup](#installation--setup)
-  - [Prerequisites](#prerequisites)
-  - [Installation Steps](#installation-steps)
-  - [Configuration](#configuration)
-- [Usage Documentation](#usage-documentation)
-  - [Defining a Schema](#defining-a-schema)
-  - [Ephemeral Persistence](#ephemeral-persistence)
-  - [Schema Registry (Git-backed)](#schema-registry-git-backed)
-  - [Schema Migration](#schema-migration)
-  - [Type Generation](#type-generation)
-  - [Documentation Generation](#documentation-generation)
-- [Project Architecture](#project-architecture)
-  - [Directory Structure](#directory-structure)
-  - [Core Components](#core-components)
-  - [Data Flow](#data-flow)
-  - [Extension Points](#extension-points)
-- [Development & Contributing](#development--contributing)
-  - [Development Setup](#development-setup)
-  - [Available Scripts](#available-scripts)
-  - [Testing](#testing)
-  - [Contributing Guidelines](#contributing-guidelines)
-  - [Issue Reporting](#issue-reporting)
-- [Additional Information](#additional-information)
-  - [Troubleshooting](#troubleshooting)
-  - [FAQ](#faq)
-  - [Changelog](#changelog)
-  - [License](#license)
-  - [Acknowledgments](#acknowledgments)
+### Table of Contents
+1.  [Overview & Features](#overview--features)
+2.  [Installation & Setup](#installation--setup)
+3.  [Usage Documentation](#usage-documentation)
+    *   [Core Concepts](#core-concepts)
+    *   [Defining Schemas](#defining-schemas)
+    *   [Schema Registry](#schema-registry)
+    *   [Schema Evolution (Migrations)](#schema-evolution-migrations)
+    *   [Runtime Validation](#runtime-validation)
+    *   [Developer Tools](#developer-tools)
+4.  [Project Architecture](#project-architecture)
+    *   [Core Components](#core-components)
+    *   [Extension Points](#extension-points)
+5.  [Development & Contributing](#development--contributing)
+    *   [Local Development Setup](#local-development-setup)
+    *   [Available Scripts](#available-scripts)
+    *   [Testing](#testing)
+    *   [Contributing Guidelines](#contributing-guidelines)
+    *   [Issue Reporting](#issue-reporting)
+6.  [Additional Information](#additional-information)
+    *   [Troubleshooting](#troubleshooting)
+    *   [Changelog & Roadmap](#changelog--roadmap)
+    *   [License](#license)
+    *   [Acknowledgments](#acknowledgments)
 ---
-## Why the Name "Anansi"?
-Named after the legendary Akan trickster god of West Africa, our platform embodies Anansi's core attributes:
-- **Wisdom in Complexity**: Like Anansi weaving intricate webs, this platform navigates the complex landscapes of enterprise data systems.
-- **Adaptive Intelligence**: Anansi's legendary ability to transform and adapt mirrors our platform's approach to schema evolution.
-- **Storytelling of Systems**: In Akan folklore, Anansi is a master storyteller who can unravel and reweave narratives—just as our platform manages the intricate narratives of data models.
-The name reflects our philosophical approach: transformative, intelligent, and deeply respectful of the complex systems we seek to understand and evolve.
-## Theoretical Foundation
-A mathematically rigorous framework for managing data model complexity, grounded in advanced theoretical principles of system evolution and distributed computing.
 ## Overview & Features
-### Detailed Description
+Anansi is designed to streamline data management in TypeScript applications by providing a robust and flexible framework for defining data models, ensuring data integrity, and managing schema evolution over time. It abstracts away the complexities of various persistence layers, allowing developers to focus on the business logic while maintaining strong type safety and consistency.
-Anansi is a comprehensive platform built to tackle the challenges of modern enterprise data management. It provides a principled approach to schema design, evolution, and system integration, moving beyond simple CRUD operations to offer a robust, version-controlled environment for your data models. By treating schemas as living, evolving constructs, Anansi enables systematic transformations while preserving system-wide data integrity. Its in-memory capabilities, backed by a persistent Git-enabled registry, ensure both high performance and reliable versioning for collaborative development and deployment. Anansi is ideal for organizations navigating complex, rapidly evolving, and distributed system architectures.
-### Key Conceptual Components
-- 👷 **Schema Registry**: Inspired by the intricate webs of knowledge, this component offers comprehensive metadata tracking and explicit dependency management for all your data schemas.
-- 🧠 **Theoretical Migration Framework**: Provides formal methods for schema evolution, guaranteeing atomic transformations and supporting bidirectional migrations to ensure data consistency across versions.
-- 🌐 **Architectural Abstractions**: Enables decoupled schema representation, cross-system consistency models, and adaptive persistence strategies to integrate seamlessly into diverse architectural landscapes.
+Whether you're building a new application from scratch or need to bring order to an existing, evolving data landscape, Anansi offers the tools to define clear, verifiable data structures, automate schema updates, and integrate seamlessly with diverse storage solutions. Its modular design promotes extensibility, allowing for easy integration of new features and custom adapters.
 ### Key Features
-- **Schema Definition & Validation**: Define complex data structures using a rich `SchemaDefinition` interface, complete with fields, nested schemas, constraints, and indexes. Leverage a powerful, auto-generated validation SDK to ensure data integrity against your defined schemas.
-- **Schema Evolution & Migration**: Manage schema changes over time with a robust `MigrationEngine`. Define schema changes and data transformations to seamlessly evolve your data models forward and backward, preserving data consistency.
-- **Flexible Persistence Adapters**: Interact with various data stores through a unified `Persistence` interface. Includes an in-memory ephemeral persistence layer for rapid prototyping and a production-ready PocketBase adapter with built-in retry mechanisms and error categorization.
-- **Schema Registry with Version Control**: Store, manage, and version your schemas using a `SchemaRegistry` that can operate purely in-memory (backed by `LightningFS`) or integrate with Git for distributed version control, branching, and tagging.
-- **Code Generation & Utilities**: Automatically generate TypeScript types (`schemaToTypes`) and human-readable documentation (`docgen`) directly from your `SchemaDefinition` files. Includes essential utilities for cryptographic hashing, deep merging, and JSON Patch operations.
-- **Event-driven Data Operations**: Subscribe to granular persistence events (e.g., `create:success`, `update:failed`) and define triggers or scheduled tasks to automate workflows around data changes.
+*   **Declarative Schema Definition**: Define complex data models using a rich `SchemaDefinition` interface, supporting primitive types, arrays, sets, enums, objects, discriminated unions, and relationships. Includes support for custom constraints, indexes, and descriptive metadata.
+*   **Comprehensive Versioning & Migration**: Manage schema evolution gracefully with a built-in migration engine. Define schema changes and data transformation functions to automatically upgrade or rollback data between versions, ensuring data consistency across deployments.
+*   **Pluggable Persistence Layer**: Interact with various data storage backends through a unified `Persistence` API. Comes with an in-memory ephemeral store for rapid prototyping and easily extendable to support other databases.
+*   **Runtime Data Validation**: Automatically generate TypeScript validators from your `SchemaDefinition` to enforce data integrity at runtime. Integrates with standard validation specifications (`@standard-schema/spec`) and can be adapted for popular form libraries like React Hook Form.
+*   **Git-Powered Schema Registry**: Store and manage your `SchemaDefinition` files in a version-controlled, collaborative registry. The Git integration (`isomorphic-git` and `LightningFS`) allows for distributed schema management, branching, tagging, and synchronization with remote repositories like GitHub or Gitea.
+*   **Eventing & Observability**: Hook into persistence operations with a powerful event bus. Register triggers and schedule tasks to automate workflows, react to data changes, or perform maintenance operations. Access comprehensive metadata for monitoring your collections.
+*   **Developer Tooling**: Boost productivity with utility functions for generating TypeScript types directly from your schemas, creating human-readable Markdown documentation, and applying JSON Patch operations for granular data updates.
 ## Installation & Setup
 ### Prerequisites
--   **Node.js**: Version 18.x or higher.
--   **Bun**: Recommended for faster installation and script execution. (Alternatively, npm/yarn can be used).
--   **TypeScript**: For developing with Anansi and its generated types.
--   **PocketBase** (Optional): If using the PocketBase persistence adapter, a running PocketBase instance is required.
+To use Anansi, ensure you have the following installed:
+*   **Node.js**: v18.x or higher
+*   **Bun**: (Recommended for running scripts and faster dependency installation) or `npm`/`yarn`
+*   **TypeScript**: v5.x or higher
 ### Installation Steps
-Install Anansi into your project using Bun (recommended) or npm:
+Install Anansi in your project using Bun (recommended) or your preferred package manager:
 ```bash
 # Using Bun
@@ -99,691 +72,668 @@ bun add @asaidimu/anansi
 # Using npm
 npm install @asaidimu/anansi
+# Using yarn
+yarn add @asaidimu/anansi
 ```
 ### Configuration
-#### Ephemeral Persistence (In-memory)
+Anansi is designed to be highly configurable through its API. For internal development, modules are often aliased with `@core` to `src/`. If you are importing from the distributed package, you'll use `@asaidimu/anansi`.
-For local development and testing, you can use the ephemeral persistence layer which requires no external configuration:
+No global configuration files are strictly required, but specific persistence adapters will require their own configuration (e.g., API URLs, authentication tokens).
+### Verification
+You can quickly verify the installation by trying a simple import in a TypeScript file:
 ```typescript
 import { createEphemeralPersistence } from '@asaidimu/anansi';
+import type { SchemaDefinition } from '@asaidimu/anansi';
-// Define your predicate map (if using custom constraints)
-const myPredicates = {
-  isPositive: ({ data, field, arguments: min }) => data[field] > min,
+// Define a simple schema
+const userSchema: SchemaDefinition = {
+  name: 'User',
+  version: '1.0.0',
+  fields: {
+    id: { name: 'id', type: 'string', required: true },
+    name: { name: 'name', type: 'string' }
+  },
+  nestedSchemas: {} // Always required, even if empty
 };
-// Create a new in-memory persistence instance
-const persistence = createEphemeralPersistence({}, myPredicates); // No functionMap needed for basic use
+// Create an in-memory persistence instance
+const persistence = createEphemeralPersistence({}, {}); // Requires functionMap and predicateMap (can be empty for basic usage)
+async function verify() {
+  try {
+    const userCollection = await persistence.create<typeof userSchema>({ schema: userSchema });
+    console.log(`Collection '${userCollection.schema().name}' created successfully.`);
+    const collections = await persistence.collections();
+    console.log('Available collections:', collections);
+  } catch (error) {
+    console.error('Verification failed:', error);
+  }
+}
-// Now you can create and manage collections in memory
+verify();
 ```
-#### Git-backed Schema Registry
+## Usage Documentation
-To enable persistent, version-controlled schema management, you'll configure `createGitSchemaRegistry` with a remote Git repository (e.g., GitHub, Gitea). This will require authentication credentials.
+### Core Concepts
-```typescript
-import { createGitSchemaRegistry, createGithubRepository } from '@asaidimu/anansi';
-// Example for GitHub
-const remoteRepo = await createGithubRepository({
-  username: process.env.GITHUB_USERNAME!,
-  password: process.env.GITHUB_PAT!, // Personal Access Token
-  repository: 'my-anansi-schemas',
-  create: true, // Auto-create if not exists
-});
-const gitRegistry = await createGitSchemaRegistry('/my-schema-registry', {
-  remote: remoteRepo,
-  author: { name: 'Anansi Bot', email: 'anansi-bot@example.com' },
-  // proxy: 'https://cors.isomorphic-git.org', // Uncomment if encountering CORS issues
-});
+Anansi revolves around several core concepts:
-await gitRegistry.init(); // Initialize the local Git repository and sync with remote
-```
+*   **`SchemaDefinition`**: The blueprint for your data. It describes fields, their types, constraints, indexes, and nested structures.
+*   **`Persistence`**: The high-level interface for interacting with data stores (e.g., creating collections, managing schemas globally).
+*   **`PersistenceCollection`**: An instance tied to a specific schema/collection, providing CRUD, validation, and migration operations for that data.
+*   **`Migration`**: A record of how a schema has evolved, including both structural `changes` and `DataTransform` functions to convert data between versions.
+*   **`SchemaRegistry`**: A system for storing, managing, and retrieving `SchemaDefinition` files and their `Migration` history. This can be in-memory or backed by Git.
-#### PocketBase Persistence
+### Defining Schemas
-To use PocketBase, you need to provide the PocketBase URL and optionally an auth token:
+Schemas are defined using the `SchemaDefinition` interface. Here's an example:
 ```typescript
-import { createPocketBasePersistence } from '@asaidimu/anansi/sdk/pocketbase'; // Note: path to specific SDK
-import { createSchemaMigrationHelper } from '@asaidimu/anansi/lib/schema/helpers'; // Note: direct import for helper
-const pocketBasePersistence = createPocketBasePersistence({
-  url: 'http://127.0.0.1:8090', // Your PocketBase instance URL
-  // authToken: 'YOUR_POCKETBASE_AUTH_TOKEN', // Optional: if auth is required
-  env: 'development', // 'development' for migrations/rollbacks, 'production' for read-only
-});
-// Use pocketBasePersistence like any other Anansi persistence instance
-```
+import type { SchemaDefinition, FieldType } from '@asaidimu/anansi';
-## Usage Documentation
-### Defining a Schema
-Schemas are defined using the `SchemaDefinition` interface. Here's a basic example:
-```typescript
-import { SchemaDefinition } from '@asaidimu/anansi';
+const addressSchema: SchemaDefinition['nestedSchemas']['address'] = {
+  name: 'Address', // Name used for referencing this nested schema
+  description: 'Represents a physical address',
+  fields: {
+    street: { name: 'street', type: 'string', required: true, description: 'Street address line' },
+    city: { name: 'city', type: 'string', required: true },
+    zipCode: { name: 'zipCode', type: 'string', required: true, hint: { input: { type: 'text', placeholder: 'e.g., 90210' } } }
+  }
+};
-const UserSchema: SchemaDefinition = {
-  name: "User",
-  version: "1.0.0",
-  description: "Represents a user in the system",
+const userSchema: SchemaDefinition = {
+  name: 'User',
+  version: '1.0.0',
+  description: 'Defines a user profile',
   fields: {
-    id: { name: "id", type: "string", required: true, description: "Unique user ID" },
+    id: { name: 'id', type: 'string', required: true, unique: true, description: 'Unique user identifier' },
+    firstName: { name: 'firstName', type: 'string', required: true },
+    lastName: { name: 'lastName', type: 'string', required: true },
     email: {
-      name: "email",
-      type: "string",
+      name: 'email',
+      type: 'string',
       required: true,
-      constraints: [{
-        name: "isEmail",
-        predicate: "isEmailFormat", // Assumes 'isEmailFormat' is in your predicateMap
-        parameters: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
-        errorMessage: "Must be a valid email address."
-      }],
-      description: "User's email address"
+      unique: true,
+      constraints: [{ name: 'isEmailFormat', predicate: 'regex', parameters: /^[^\s@]+@[^\s@]+\.[^\s@]+$/, errorMessage: 'Must be a valid email format' }],
+      hint: { input: { type: 'email' } }
     },
     status: {
-      name: "status",
-      type: "enum",
-      values: ["active", "inactive", "pending"],
-      default: "pending",
-      description: "User's current status"
+      name: 'status',
+      type: 'enum',
+      values: ['active', 'inactive', 'suspended'],
+      default: 'active',
+      description: 'Current status of the user',
+      hint: { input: { type: 'select', options: [{value: 'active', label: 'Active'}, {value: 'inactive', label: 'Inactive'}, {value: 'suspended', label: 'Suspended'}] } }
     },
-    profile: {
-      name: "profile",
-      type: "object",
-      schema: { id: "UserProfile" }, // References a nested schema
+    address: {
+      name: 'address',
+      type: 'object',
+      schema: { id: 'address' }, // Reference to the nested schema
       required: false,
-      description: "User's profile details"
+      description: 'User\'s residential address'
     },
-    roles: {
-      name: "roles",
-      type: "set",
-      itemsType: "string",
-      description: "Set of unique roles assigned to the user"
+    tags: {
+      name: 'tags',
+      type: 'set', // Ensures unique items
+      itemsType: 'string',
+      default: [],
+      description: 'A set of keywords associated with the user'
     }
   },
   nestedSchemas: {
-    UserProfile: {
-      name: "UserProfile",
-      fields: {
-        firstName: { name: "firstName", type: "string", required: true },
-        lastName: { name: "lastName", type: "string", required: true },
-        age: { name: "age", type: "number", required: false, default: 18 }
-      }
-    }
+    address: addressSchema // Define the nested schema here
   },
   indexes: [
-    { name: "emailIndex", fields: ["email"], type: "unique", description: "Ensures unique email addresses" }
+    { name: 'emailIndex', fields: ['email'], type: 'unique', description: 'Ensure email uniqueness' },
+    { name: 'nameCompositeIndex', fields: ['lastName', 'firstName'], type: 'composite' }
   ],
   constraints: [
     {
-      name: "ageConstraint",
-      operator: "and",
+      name: 'fullNameLength',
+      operator: 'and',
       rules: [
-        { name: "minAge", predicate: "min", field: "profile.age", parameters: 18 },
-        { name: "maxAge", predicate: "max", field: "profile.age", parameters: 120 }
+        { name: 'firstNameMinLength', predicate: 'minLength', field: 'firstName', parameters: 2, errorMessage: 'First name too short' },
+        { name: 'lastNameMinLength', predicate: 'minLength', field: 'lastName', parameters: 2, errorMessage: 'Last name too short' }
       ]
     }
   ],
+  // Example of a mock data generator (uses @faker-js/faker)
   mock: (faker) => ({
     id: faker.string.uuid(),
+    firstName: faker.person.firstName(),
+    lastName: faker.person.lastName(),
     email: faker.internet.email(),
-    status: faker.helpers.arrayElement(["active", "inactive", "pending"]),
-    profile: {
-      firstName: faker.person.firstName(),
-      lastName: faker.person.lastName(),
-      age: faker.number.int({ min: 18, max: 99 })
+    status: faker.helpers.arrayElement(['active', 'inactive', 'suspended']),
+    address: {
+      street: faker.location.streetAddress(),
+      city: faker.location.city(),
+      zipCode: faker.location.zipCode()
     },
-    roles: faker.helpers.arrayElements(["admin", "user", "guest"], { min: 1, max: 3 })
+    tags: Array.from({length: faker.number.int({min: 1, max: 3})}, () => faker.lorem.word())
   })
 };
 ```
-### Ephemeral Persistence
+### Schema Registry
-Interact with data using the in-memory persistence layer:
+The `SchemaRegistry` is responsible for storing and managing your `SchemaDefinition` files and their versions.
+#### Core `SchemaRegistry` (In-Memory)
 ```typescript
-import { createEphemeralPersistence, SchemaDefinition } from '@asaidimu/anansi';
+import { SchemaRegistry, type SchemaDefinition } from '@asaidimu/anansi';
-const myPredicates = {
-  isEmailFormat: ({ data, field, arguments: regex }) => regex.test(data[field]),
-  min: ({ data, field, arguments: minValue }) => data[field] >= minValue,
-  max: ({ data, field, arguments: maxValue }) => data[field] <= maxValue,
-};
+const registry = new SchemaRegistry('/my-app-schemas'); // Uses LightningFS in browser, local files in Node.js
-const persistence = createEphemeralPersistence({}, myPredicates);
+async function demoRegistry() {
+  await registry.init(); // Initialize the registry structure
-// Assume UserSchema is defined as above
-const usersCollection = await persistence.createCollection<typeof UserSchema>({
-  name: UserSchema.name,
-  version: UserSchema.version,
-  fields: UserSchema.fields,
-  nestedSchemas: UserSchema.nestedSchemas,
-  constraints: UserSchema.constraints,
-  indexes: UserSchema.indexes,
-});
+  const productSchema: SchemaDefinition = {
+    name: 'Product',
+    version: '1.0.0',
+    fields: {
+      id: { name: 'id', type: 'string', required: true },
+      name: { name: 'name', type: 'string' },
+      price: { name: 'price', type: 'number' }
+    },
+    nestedSchemas: {}
+  };
-// 🚀 Create
-const newUser = await usersCollection.create({
-  data: {
-    id: 'user123',
-    email: 'test@example.com',
-    status: 'active',
-    profile: { firstName: 'John', lastName: 'Doe', age: 30 },
-    roles: ['admin', 'user'],
-  },
-});
-console.log('Created user:', newUser);
+  await registry.create({ schema: productSchema });
+  console.log('Product schema created.');
-// ⚡ Read
-const activeUsers = await usersCollection.read({
-  query: { filters: { status: { $eq: 'active' } } },
-});
-console.log('Active users:', activeUsers);
+  const schemas = await registry.list();
+  console.log('Available schemas:', schemas);
-// 🔄 Update
-const updatedUsers = await usersCollection.update({
-  query: { email: { $eq: 'test@example.com' } },
-  data: { status: 'inactive' },
-});
-console.log('Updated users:', updatedUsers);
+  const fetchedSchema = await registry.schema({ name: 'Product' });
+  console.log('Fetched Product schema:', fetchedSchema?.version);
-// 🗑️ Delete
-const deletedCount = await usersCollection.delete({
-  query: { id: { $eq: 'user123' } },
-});
-console.log('Deleted users count:', deletedCount);
+  // Update schema
+  const updatedProductSchema = { ...productSchema, version: '1.1.0', description: 'Updated product schema' };
+  await registry.update({ schema: updatedProductSchema });
+  console.log('Product schema updated to version:', (await registry.schema({ name: 'Product' }))?.version);
+  const history = await registry.history({ name: 'Product' });
+  console.log('Product schema history:', history.map(s => s.version));
-// ✨ Validate
-const invalidUser = { id: 'invalid', email: 'bad-email' };
-const validationResult = usersCollection.validate(invalidUser);
-console.log('Validation issues:', validationResult.issues);
+  // Sync the registry (updates internal lockfile hashes)
+  await registry.sync();
+  console.log('Registry synced.');
+}
+demoRegistry();
 ```
-### Schema Registry (Git-backed)
+#### Git-Enabled `SchemaRegistry`
-Manage your schemas persistently with Git integration.
+For persistent storage, collaboration, and advanced versioning, `createGitSchemaRegistry` wraps the core `SchemaRegistry` with `isomorphic-git`. This allows pushing/pulling schemas to a remote Git repository (e.g., GitHub, Gitea).
 ```typescript
-import {
-  createGitSchemaRegistry,
-  createGithubRepository,
-  SchemaDefinition,
-} from '@asaidimu/anansi';
-import { UserSchema } from './my-schemas'; // Assuming UserSchema is defined
-// Configure remote repository (e.g., GitHub)
-const githubRepo = await createGithubRepository({
+import { createGitSchemaRegistry, SchemaDefinition } from '@asaidimu/anansi';
+import { createGithubRepository } from '@asaidimu/anansi/lib/registry/github';
+// IMPORTANT: Replace with your actual GitHub credentials and desired repository details
+const githubRemote = await createGithubRepository({
   username: 'your-github-username',
-  password: 'your-github-pat', // Use a Personal Access Token
-  repository: 'anansi-schemas',
-  create: true, // Create the repo if it doesn't exist
+  password: 'your-github-personal-access-token', // PAT with repo scope
+  repository: 'anansi-schemas-repo', // The repo name to use on GitHub
+  create: true // Will create the repo if it doesn't exist
 });
-// Create Git-backed schema registry
-const registry = await createGitSchemaRegistry('/anansi-schemas', {
-  remote: githubRepo,
-  author: { name: 'Anansi Bot', email: 'bot@anansi.com' },
-});
+async function demoGitRegistry() {
+  const gitRegistry = await createGitSchemaRegistry(
+    '/git-registry', // Local directory for the Git clone
+    {
+      remote: githubRemote,
+      mainBranch: 'main',
+      createRemote: true, // Auto-create remote repo if not exists
+      author: { name: 'Anansi Bot', email: 'anansi@example.com' },
+      proxy: 'https://cors.isomorphic-git.org' // Optional CORS proxy for browser environments
+    }
+  );
+  await gitRegistry.init(); // Initialize local Git repository
+  const orderSchema: SchemaDefinition = {
+    name: 'Order',
+    version: '1.0.0',
+    fields: {
+      orderId: { name: 'orderId', type: 'string', required: true },
+      amount: { name: 'amount', type: 'number' }
+    },
+    nestedSchemas: {}
+  };
+  // Create schema and push to remote
+  await gitRegistry.create({ schema: orderSchema });
+  console.log('Order schema created and pushed to Git registry.');
+  // Update schema and push to remote
+  const updatedOrderSchema = { ...orderSchema, version: '1.1.0', fields: { ...orderSchema.fields, status: { name: 'status', type: 'string' } } };
+  await gitRegistry.update({ schema: updatedOrderSchema });
+  console.log('Order schema updated and pushed to Git registry.');
+  // Pull latest changes from remote (e.g., if another user pushed)
+  await gitRegistry.sync();
+  console.log('Git registry synced with remote.');
-// Initialize the registry (clones/creates local repo, syncs)
-await registry.init();
+  // Delete schema and clean up remote tags/branches
+  await gitRegistry.delete({ name: 'Order' });
+  console.log('Order schema deleted from Git registry and remote.');
+}
+// In a real application, ensure you handle authentication tokens securely
+// and avoid hardcoding them.
+// demoGitRegistry();
+```
-// 👷 Create a schema
-await registry.create({ schema: UserSchema });
-console.log(`Schema '${UserSchema.name}' created/updated in registry.`);
+### Schema Evolution (Migrations)
-// 📋 List all schemas
-const allSchemas = await registry.list();
-console.log('All schemas:', allSchemas);
+Anansi provides a robust `MigrationEngine` to manage schema changes and transform data.
-// 🔍 Retrieve a schema definition
-const retrievedSchema = await registry.schema({ name: 'User' });
-console.log('Retrieved User schema:', retrievedSchema?.version);
+```typescript
+import { MigrationEngine, DataTransform, SchemaDefinition } from '@asaidimu/anansi';
+import { createSchemaMigrationHelper } from '@asaidimu/anansi';
-// 🔄 Update a schema
-const updatedUserSchema: SchemaDefinition = {
-  ...UserSchema,
-  version: "1.1.0",
+// Assume initial schema (e.g., loaded from SchemaRegistry)
+let currentSchema: SchemaDefinition = {
+  name: 'LegacyUser',
+  version: '1.0.0',
   fields: {
-    ...UserSchema.fields,
-    phone: { name: "phone", type: "string", required: false, description: "User's phone number" }
-  }
+    legacyId: { name: 'legacyId', type: 'string', required: true },
+    oldName: { name: 'oldName', type: 'string' }
+  },
+  nestedSchemas: {}
 };
-await registry.update({ schema: updatedUserSchema });
-console.log(`Schema '${updatedUserSchema.name}' updated to v${updatedUserSchema.version}.`);
-// ⚡ Sync local changes with remote Git repository
-await registry.sync();
-console.log('Registry synced with remote Git repository.');
+const migrationEngine = new MigrationEngine(currentSchema);
+async function performMigration() {
+  // Define a migration helper for version 1.1.0
+  const helper = createSchemaMigrationHelper(currentSchema);
+  // Schema changes: Rename field, add new field
+  helper.modifyField('oldName', { name: 'fullName' }); // Renaming field name, not property key
+  helper.addField('email', { name: 'email', type: 'string', required: true });
+  // Data transform: Map oldName to fullName, add a default email
+  const transform: DataTransform<any, any> = {
+    forward: (data) => ({
+      id: data.legacyId, // Assuming 'id' is a new concept mapped from legacyId
+      fullName: data.oldName,
+      email: data.oldName.toLowerCase().replace(/\s/g, '.') + '@example.com'
+    }),
+    backward: (data) => ({
+      legacyId: data.id,
+      oldName: data.fullName,
+      // Cannot reliably reverse email generation, so might need placeholder
+    })
+  };
+  const { migrate, rollback } = helper.changes(); // Get both forward and backward changes
+  // Add the migration to the engine
+  await migrationEngine.add({
+    description: 'Rename oldName to fullName and add email',
+    changes: migrate,
+    rollback: rollback,
+    transform: transform
+  });
-// 🗑️ Delete a schema
-// await registry.delete({ name: 'User' });
-// console.log(`Schema 'User' deleted.`);
+  // Example initial data
+  let data = [{ legacyId: 'A1', oldName: 'John Doe' }, { legacyId: 'B2', oldName: 'Jane Smith' }];
+  let dataStream = new ReadableStream({
+    start(controller) {
+      data.forEach(item => controller.enqueue(item));
+      controller.close();
+    }
+  });
+  console.log('--- Dry Run Migration ---');
+  const { newSchema: dryRunSchema, dataPreview: dryRunPreview } = await migrationEngine.dryRun(dataStream, 'forward');
+  const previewData = await new Response(dryRunPreview).json(); // Consume stream
+  console.log('Simulated New Schema:', dryRunSchema);
+  console.log('Simulated Data Preview:', previewData);
+  // Now, apply the actual migration
+  console.log('\n--- Applying Migration ---');
+  const transformedStream = await migrationEngine.migrate(dataStream);
+  const transformedData = await new Response(transformedStream).json(); // Consume stream
+  console.log('Transformed Data:', transformedData);
+  currentSchema = migrationEngine.data().schema; // Update current schema in place
+  console.log('Actual New Schema Version:', currentSchema.version);
+  // Now, rollback the migration (using the updated currentSchema)
+  console.log('\n--- Rolling Back Migration ---');
+  const rollbackEngine = new MigrationEngine(currentSchema, migrationEngine.data().migrations, migrationEngine.data().history);
+  dataStream = new ReadableStream({
+    start(controller) {
+      transformedData.forEach(item => controller.enqueue(item));
+      controller.close();
+    }
+  });
+  const rolledBackStream = await rollbackEngine.rollback(dataStream);
+  const rolledBackData = await new Response(rolledBackStream).json();
+  console.log('Rolled Back Data:', rolledBackData);
+  currentSchema = rollbackEngine.data().schema;
+  console.log('Rolled Back Schema Version:', currentSchema.version);
+}
+performMigration();
 ```
-### Schema Migration
+### Runtime Validation
-Apply and roll back schema changes, including data transformations.
+Anansi generates runtime validators based on your schema definitions.
 ```typescript
-import { createEphemeralPersistence, createSchemaMigrationHelper, SchemaDefinition, DataTransform } from '@asaidimu/anansi';
+import { createStandardSchemaValidator, type SchemaDefinition } from '@asaidimu/anansi';
-// Assume UserSchema is defined as above
-const oldUserSchema: SchemaDefinition = {
-  ...UserSchema,
-  version: "1.0.0", // Original version
+const productSchema: SchemaDefinition = {
+  name: 'Product',
+  version: '1.0.0',
   fields: {
-    id: { name: "id", type: "string", required: true },
-    oldEmail: { name: "oldEmail", type: "string", required: false } // Field to be migrated
+    id: { name: 'id', type: 'string', required: true },
+    name: { name: 'name', type: 'string', required: true },
+    price: { name: 'price', type: 'number', required: true, constraints: [{ name: 'positivePrice', predicate: 'min', parameters: 0 }] },
+    category: { name: 'category', type: 'string', required: false, default: 'General' },
+    inStock: { name: 'inStock', type: 'boolean', required: true }
   },
   nestedSchemas: {}
 };
-const persistence = createEphemeralPersistence({}, {});
-const usersCollection = await persistence.createCollection<any>({
-  name: oldUserSchema.name,
-  version: oldUserSchema.version,
-  fields: oldUserSchema.fields,
-  nestedSchemas: oldUserSchema.nestedSchemas
-});
+// Define custom predicates (validation functions)
+const customPredicates = {
+  min: ({ data, field, arguments: minValue }: { data: any, field: string, arguments: number }) => {
+    return data[field] >= minValue;
+  },
+  // Add other predicates as needed for your constraints
+};
-// Add some dummy data with oldEmail
-await usersCollection.create({
-  data: [
-    { id: 'u1', oldEmail: 'user1@old.com', status: 'active' },
-    { id: 'u2', oldEmail: 'user2@old.com', status: 'inactive' }
-  ]
-});
+const productValidator = createStandardSchemaValidator(productSchema, customPredicates)['~standard'];
-// Define the migration
-const addEmailMigration = (h: ReturnType<typeof createSchemaMigrationHelper>) => {
-  // Define forward transformation: oldEmail -> email
-  const forwardTransform: DataTransform<any, any>['forward'] = (data) => ({
-    ...data,
-    email: data.oldEmail,
-    oldEmail: undefined // Remove old field
-  });
+// Valid data
+const validProduct = {
+  id: 'prod123',
+  name: 'Laptop Pro',
+  price: 1200.50,
+  inStock: true
+};
-  // Define backward transformation: email -> oldEmail
-  const backwardTransform: DataTransform<any, any>['backward'] = (data) => ({
-    ...data,
-    oldEmail: data.email,
-    email: undefined // Remove new field
-  });
+const validationResult1 = productValidator.validate(validProduct);
+console.log('Valid product validation:', validationResult1); // { value: {...} }
+// Invalid data (missing required field)
+const invalidProduct1 = {
+  id: 'prod124',
+  price: 500,
+  inStock: false
+};
-  h.addField('email', { name: 'email', type: 'string', required: true, description: 'New email field' });
-  h.removeField('oldEmail'); // Deprecate/remove old field
+const validationResult2 = productValidator.validate(invalidProduct1);
+console.log('Invalid product (missing name) validation:', validationResult2);
+// { issues: [{ message: "Field 'name' is required", path: ["name"] }] }
-  return { forward: forwardTransform, backward: backwardTransform };
+// Invalid data (price constraint violation)
+const invalidProduct2 = {
+  id: 'prod125',
+  name: 'Headphones',
+  price: -10, // Invalid price
+  inStock: true
 };
-// ➡️ Perform a dry run migration
-console.log('\n--- Dry Run Migration (Forward) ---');
-const { newSchema: dryRunSchema, dataPreview } = await usersCollection.migrate(
-  'Migrate oldEmail to email',
-  addEmailMigration,
-  true // dryRun = true
-);
-console.log('Dry run new schema version:', dryRunSchema.version);
-const previewRecords = await new Response(dataPreview).json(); // Read from stream
-console.log('Dry run data preview:', previewRecords);
-// 🚀 Apply the actual migration
-console.log('\n--- Applying Migration (Forward) ---');
-await usersCollection.migrate(
-  'Migrate oldEmail to email',
-  addEmailMigration,
-  false // dryRun = false
-);
-console.log('Migration applied. Current schema version:', usersCollection.schema().version);
-const migratedData = await usersCollection.read({});
-console.log('Migrated data:', migratedData);
-// ⏪ Rollback the migration (if supported by persistence)
-console.log('\n--- Rolling Back Migration ---');
-await usersCollection.rollback(undefined, false); // Rollback to previous version
-console.log('Rolled back. Current schema version:', usersCollection.schema().version);
-const rolledBackData = await usersCollection.read({});
-console.log('Rolled back data:', rolledBackData);
+const validationResult3 = productValidator.validate(invalidProduct2);
+console.log('Invalid product (price constraint) validation:', validationResult3);
+// { issues: [{ message: "Constraint 'positivePrice' failed for field 'price' with params 0", path: ["price", "constraints[0]"] }] }
 ```
-### Type Generation
+### Developer Tools
-Generate TypeScript types from your schema definitions.
+Anansi includes utilities to assist developers in building and documenting their applications.
+#### Generating TypeScript Types
+`schemaToTypes` generates TypeScript type definitions from your schema, providing strong typing for your application's data models.
 ```typescript
-import { schemaToTypes, SchemaDefinition } from '@asaidimu/anansi';
+import { schemaToTypes, type SchemaDefinition } from '@asaidimu/anansi';
-const ProductSchema: SchemaDefinition = {
-  name: "Product",
-  version: "1.0.0",
+const mySchema: SchemaDefinition = {
+  name: 'BlogPost',
+  version: '1.0.0',
+  description: 'A blog post entry',
   fields: {
-    id: { name: "id", type: "string", required: true },
-    name: { name: "name", type: "string", required: true },
-    price: { name: "price", type: "number", required: true },
-    currency: { name: "currency", type: "enum", values: ["USD", "EUR", "GBP"] },
-    details: {
-      name: "details",
-      type: "object",
-      schema: { id: "ProductDetails" }
-    }
+    id: { name: 'id', type: 'string', required: true },
+    title: { name: 'title', type: 'string', required: true, description: 'The title of the blog post' },
+    author: { name: 'author', type: 'string', required: false, deprecated: true },
+    content: { name: 'content', type: 'string' },
+    status: { name: 'status', type: 'enum', values: ['draft', 'published', 'archived'] },
+    metadata: { name: 'metadata', type: 'record', required: false, description: 'Arbitrary key-value metadata' },
+    tags: { name: 'tags', type: 'array', itemsType: 'string', default: [] },
+    comments: { name: 'comments', type: 'object', schema: { id: 'Comment' }, required: false }
   },
   nestedSchemas: {
-    ProductDetails: {
-      name: "ProductDetails",
-      fields: {
-        weight: { name: "weight", type: "number" },
-        dimensions: {
-          name: "dimensions",
-          type: "object",
-          schema: { id: "ProductDimensions" }
-        }
-      }
-    },
-    ProductDimensions: {
-      name: "ProductDimensions",
+    Comment: {
+      name: 'Comment',
       fields: {
-        length: { name: "length", type: "number" },
-        width: { name: "width", type: "number" },
-        height: { name: "height", type: "number" }
+        commentId: { name: 'commentId', type: 'string', required: true },
+        text: { name: 'text', type: 'string', required: true },
+        authorEmail: { name: 'authorEmail', type: 'string', required: true }
       }
     }
-  }
+  },
+  indexes: [
+    { name: 'titleIndex', fields: ['title'], type: 'normal' }
+  ]
 };
-const generatedTypes = schemaToTypes(ProductSchema);
+const generatedTypes = schemaToTypes(mySchema, true, true);
 console.log(generatedTypes);
-/*
-// Output will be similar to:
-export type ProductDimensions = {
-  length?: number;
-  width?: number;
-  height?: number;
-};
-export type ProductDetails = {
-  weight?: number;
-  dimensions?: ProductDimensions;
+/* Expected Output (simplified):
+export type Comment = {
+  commentId: string;
+  text: string;
+  authorEmail: string;
 };
-export type ProductCurrency = "USD" | "EUR" | "GBP";
+export type BlogPostStatus = "draft" | "published" | "archived";
-export type Product = {
+export type BlogPost<Metadata extends Record<string, any> = Record<string, any>> = {
   id: string;
-  name: string;
-  price: number;
-  currency: ProductCurrency;
-  details?: string | ProductDetails; // "string" for concrete schemas reference
+  title: string;
+   ... rest of fields and types ...
+  author?: string;
+  metadata?: Metadata;
+  tags?: string[];
+  comments?: string | Comment;
 };
-export enum ProductIndexNames {
-  ...
+export enum BlogPostIndexNames {
+  titleIndex = "titleIndex",
 }
-*/
+ */
 ```
-### Documentation Generation
+#### Generating Markdown Documentation
-Generate markdown documentation for your schemas.
+`docgen` creates a human-readable Markdown document describing your schema.
 ```typescript
-import { docgen, SchemaDefinition } from '@asaidimu/anansi';
+import { docgen, type SchemaDefinition } from '@asaidimu/anansi';
 import { faker } from '@faker-js/faker';
-// Assume ProductSchema is defined as above
+const docSchema: SchemaDefinition = {
+  name: 'Customer',
+  version: '1.0.0',
+  description: 'Detailed profile for a customer.',
+  fields: {
+    customerId: { name: 'customerId', type: 'string', required: true, unique: true, description: 'Unique identifier for the customer.' },
+    fullName: { name: 'fullName', type: 'string', required: true, description: 'Full name of the customer.' },
+    tier: { name: 'tier', type: 'enum', values: ['Bronze', 'Silver', 'Gold'], default: 'Bronze', description: 'Customer loyalty tier.' },
+    lastPurchaseDate: { name: 'lastPurchaseDate', type: 'string', required: false, description: 'Date of the last purchase (ISO string).' }
+  },
+  nestedSchemas: {},
+  mock: (fakerInstance) => ({
+    customerId: fakerInstance.string.uuid(),
+    fullName: fakerInstance.person.fullName(),
+    tier: fakerInstance.helpers.arrayElement(['Bronze', 'Silver', 'Gold']),
+    lastPurchaseDate: fakerInstance.date.past().toISOString()
+  })
+};
+const markdownDoc = docgen(docSchema, { faker });
+console.log(markdownDoc);
-const productDoc = docgen(ProductSchema, { faker });
-console.log(productDoc);
+/* Expected Output (partial):
+# Customer Schema (Version 1.0.0)
-/*
-// Output will be similar to:
-# Product Schema (Version 1.0.0)
+Detailed profile for a customer.
 ## Metadata
 - **Dependencies:** None
-- **Created:** 2024-01-01T00:00:00.000Z
+- **Created:** 2024-XX-XXTXX:XX:XXZ
 ## Fields
-| Name     | Type   | Required | Default | Description        | Deprecated | Unique | Constraints |
-|----------|--------|----------|---------|--------------------|------------|--------|-------------|
-| id       | string | Yes      | `None`  |                    | No         | No     | 0           |
-| name     | string | Yes      | `None`  |                    | No         | No     | 0           |
-| price    | number | Yes      | `None`  |                    | No         | No     | 0           |
-| currency | enum   | Yes      | `"USD"` |                    | No         | No     | 0           |
-| details  | object | No       | `None`  |                    | No         | No     | 0           |
-### Nested Schema: ProductDetails
-#### weight (number)
-**Required:** No
-#### dimensions (object)
-##### length (number)
-**Required:** No
-##### width (number)
-**Required:** No
-##### height (number)
-**Required:** No
+| Name | Type | Required | Default | Description | Deprecated | Unique | Constraints |
+|------|------|----------|---------|-------------|------------|--------|-------------|
+| customerId | string | Yes | `None` | Unique identifier for the customer. | No | Yes | 0 |
+| fullName | string | Yes | `None` | Full name of the customer. | No | No | 0 |
+| tier | enum | No | `"Bronze"` | Customer loyalty tier. | No | No | 0 |
+| lastPurchaseDate | string | No | `None` | Date of the last purchase (ISO string). | No | No | 0 |
 ## Indexes
-| Name | Type   | Fields  | Unique | Order | Partial Condition | Description |
-|------|--------|---------|--------|-------|-------------------|-------------|
-| ...  | ...    | ...     | ...    | ...   | ...               | ...         |
-## Constraints
-### Schema-level Constraints
 ...
-## Migrations
-| ID | Description | Status | Changes |
-|----|-------------|--------|---------|
-| ...| ...         | ...    | ...     |
-## Example Data
-```json
-{
-  "id": "e221b3a4-c5d6-7890-a1b2-c3d4e5f67890",
-  "name": "Ergonomic Widget",
-  "price": 99.99,
-  "currency": "USD",
-  "details": {
-    "weight": 0.5,
-    "dimensions": {
-      "length": 10,
-      "width": 5,
-      "height": 2
-    }
-  }
-}
 */
 ```
 ## Project Architecture
-Anansi is structured to provide a modular and extensible platform for data model management.
-### Directory Structure
-```
-.
-├── src/
-│   ├── lib/                  # Core libraries for persistence, registry, migration, schema
-│   │   ├── persistence/      # In-memory and adapter-based data persistence (EmphemeralCollection)
-│   │   ├── registry/         # Schema Registry (LightningFS + Git integration)
-│   │   ├── migration/        # Schema migration engine (MigrationEngine)
-│   │   └── schema/           # Schema validation, helpers, and utilities
-│   ├── sdk/                  # Specific SDK implementations (e.g., PocketBase adapter, static validators)
-│   ├── types/                # Core TypeScript interfaces (SchemaDefinition, Persistence, Migration, etc.)
-│   └── tools/                # General utilities (crypto, merge, patch, typegen, docgen, validator, version)
-├── docs/                     # VitePress documentation site
-├── tests/                    # Unit and integration tests
-├── public/                   # Public assets for UI (e.g., Vite SVG)
-├── index.ts                  # Main entry point for the Anansi library
-├── package.json              # Project metadata and dependencies
-├── dist.package.json         # Package.json for distributed npm package
-├── vitest.config.ts          # Vitest configuration for testing
-├── vite.config.ts            # Vite configuration for UI development
-└── tsconfig.json             # TypeScript configuration
-```
+Anansi's architecture is modular, promoting separation of concerns and extensibility.
 ### Core Components
--   **`SchemaDefinition` (`src/types/schema-definition.ts`)**: The central contract defining the structure of data models, including fields, nested schemas, constraints, and migrations.
--   **`Persistence` (`src/types/persistence.ts`)**: An abstract interface for all data storage operations (create, read, update, delete, subscribe), designed for pluggable backends.
-    -   **`EmphemeralCollection` (`src/lib/persistence/collection.ts`)**: An in-memory implementation of `PersistenceCollection` for rapid development.
-    -   **PocketBase Adapter (`src/sdk/pocketbase/index.tsx`)**: A concrete `Persistence` implementation for PocketBase, handling schema-driven collection management, migrations, and eventing.
--   **`MigrationEngine` (`src/lib/migration/index.ts`)**: Manages the evolution of schemas over time, applying schema changes and data transformations in a controlled, versioned manner.
--   **`SchemaRegistry` (`src/lib/registry/registry.ts`)**: The core component for storing and versioning schema definitions. It uses `LightningFS` for in-memory storage.
-    -   **`createGitSchemaRegistry` (`src/lib/registry/git-registry.ts`)**: A factory function that wraps `SchemaRegistry` with `isomorphic-git` to provide persistent, distributed version control for schemas.
--   **`Validators` (`src/tools/validator.ts`, `src/lib/schema/validators.ts`)**: Provides utilities for validating data against `SchemaDefinition` rules and for validating the schema definitions themselves.
--   **`Type Generators` (`src/tools/typegen.ts`)**: Automatically generates TypeScript type definitions from `SchemaDefinition` files, ensuring strict type safety across your codebase.
--   **`Documentation Generator` (`src/tools/docgen.ts`)**: Generates human-readable Markdown documentation for schemas, including fields, indexes, constraints, and example mock data.
-### Data Flow
-1.  **Schema Definition**: Developers define data models using the `SchemaDefinition` interface.
-2.  **Schema Registration**: Schemas are added to the `SchemaRegistry` (either in-memory or Git-backed) for version control and discovery.
-3.  **Persistence Layer**: A `Persistence` instance (e.g., `EphemeralPersistence`, `PocketBasePersistence`) is initialized with optional predicates and functions for query and validation.
-4.  **Collection Interaction**: Developers interact with collections (e.g., `usersCollection.create()`, `usersCollection.read()`) through the `PersistenceCollection` interface.
-5.  **Validation**: All data operations trigger internal validation against the collection's `SchemaDefinition` using the `createStandardSchemaValidator`.
-6.  **Schema Evolution**: When data models change, `SchemaChanges` are defined, and the `MigrationEngine` applies these changes to both the schema definition and existing data.
-7.  **Synchronization (Git)**: For Git-backed registries, changes are committed and pushed, enabling collaborative schema evolution and traceability.
+*   **`src/types`**: Defines the foundational data structures and interfaces for Anansi. This is the "language" of your data models and how various parts of the system interact.
+*   **`src/lib`**: Contains the core implementations of Anansi's main functionalities:
+    *   **Persistence**: Manages data operations (CRUD, events, tasks) against a specific backend. `EphemeralCollection` provides an in-memory implementation for quick starts.
+    *   **Registry**: Provides a mechanism for storing and retrieving schema definitions and their histories. `SchemaRegistry` handles local filesystem storage, while `createGitSchemaRegistry` integrates with Git for distributed version control.
+    *   **Migration**: Orchestrates schema evolution, applying changes and transforming data between versions.
+*   **`src/sdk`**: Houses pluggable Software Development Kit components, such as specific persistence adapters (e.g., PocketBase) and code generators (e.g., static TypeScript validators).
+*   **`src/tools`**: A collection of cross-cutting utility functions that support various aspects of Anansi, including cryptographic hashing, JSON Patching, type generation, and advanced runtime validation.
 ### Extension Points
--   **Custom Persistence Adapters**: Implement the `Persistence` and `PersistenceCollection` interfaces to integrate Anansi with any new data storage backend.
--   **Custom Predicates**: Define custom validation logic (e.g., `isEmailFormat`, `isStrongPassword`) and provide them to `createEphemeralPersistence` or any other persistence implementation.
--   **Data Transforms**: Write custom `forward` and `backward` transformation functions for migrations, enabling complex data shape changes between schema versions.
--   **Schema Hints**: Extend `InputHint` and `SchemaHint` to guide UI generation or other tooling based on schema metadata.
+Anansi is designed for extensibility:
+*   **Persistence Adapters**: Implement the `Persistence` and `PersistenceCollection` interfaces to connect Anansi to any database or storage solution (e.g., SQL, NoSQL, GraphQL endpoints).
+*   **Custom Predicates**: Extend the validation system by defining your own `Predicate` functions and including them in the `PredicateMap` when initializing validators.
+*   **Schema Changes & Transforms**: The `SchemaMigrationHelper` and `DataTransform` types provide a powerful DSL to define custom schema evolutions and data transformations for complex migrations.
+*   **Remote Repository Adapters**: Implement the `RemoteRepository` interface to integrate the `SchemaRegistry` with other Git hosting services beyond GitHub and Gitea.
 ## Development & Contributing
-### Development Setup
+We welcome contributions to Anansi! Here's how you can get started:
-To set up the project for local development:
+### Local Development Setup
 1.  **Clone the repository:**
     ```bash
     git clone https://github.com/asaidimu/data-model.git anansi
     cd anansi
     ```
-2.  **Install dependencies using Bun (recommended):**
+2.  **Install dependencies:**
     ```bash
     bun install
     ```
-    If you don't have Bun, you can use npm:
+    (or `npm install` / `yarn install`)
+3.  **Build the project:**
     ```bash
-    npm install
+    bun run build
     ```
 ### Available Scripts
-The `package.json` includes several scripts for development workflows:
--   `bun ci`: Installs dependencies.
--   `bun clean`: Removes the `dist` directory.
--   `bun prebuild`: Cleans and runs `./.sync-package.ts`.
--   `bun build`: Compiles TypeScript files to `dist/` for CJS and ESM formats, generates declaration files, and minifies.
--   `bun build:watch`: Runs `build` in watch mode for continuous compilation.
--   `bun postbuild`: Copies `README.md`, `LICENSE.md`, and `dist.package.json` into the `dist` directory.
--   `bun test`: Runs unit and integration tests using Vitest.
--   `bun test:ci`: Runs Vitest tests in CI mode (runs once, exits).
--   `bun test:debug`: Runs Vitest with debugger attached.
--   `bun docs:dev`: Starts the VitePress development server for documentation.
--   `bun docs:build`: Builds the static VitePress documentation site.
--   `bun ui:dev`: Starts the Vite development server for the example UI.
--   `bun docs:preview`: Previews the built documentation site.
+*   `bun run ci`: Installs dependencies (for CI environments).
+*   `bun run clean`: Removes the `dist/` directory.
+*   `bun run prebuild`: Cleans the `dist/` directory and runs `.sync-package.ts` (internal synchronization).
+*   `bun run build`: Compiles TypeScript source files into `dist/` for CommonJS and ES Modules, generates declaration files (`.d.ts`), and minifies output.
+*   `bun run build:watch`: Runs the build process in watch mode for continuous compilation during development.
+*   `bun run postbuild`: Copies `README.md`, `LICENSE.md`, and `dist.package.json` into the `dist/` directory.
+*   `bun run test`: Runs all unit tests using Vitest.
+*   `bun run test:ci`: Runs Vitest tests once for CI environments.
+*   `bun run test:debug`: Runs Vitest in debug mode, useful for debugging tests in an IDE.
+*   `bun run docs:dev`: Starts the VitePress development server for the documentation.
+*   `bun run docs:build`: Builds the static VitePress documentation site.
+*   `bun run ui:dev`: Starts a local Vite development server for the UI (likely a demo or internal tooling).
+*   `bun run docs:preview`: Previews the built VitePress documentation.
 ### Testing
 Anansi uses [Vitest](https://vitest.dev/) for its test suite.
-To run all tests:
-```bash
-bun test
-```
-To run tests in CI mode (non-interactive):
-```bash
-bun test:ci
-```
-Tests include coverage checks and are configured to run in a `happy-dom` environment with `fake-indexeddb` for browser-like filesystem operations (`LightningFS`).
+*   To run all tests:
+    ```bash
+    bun run test
+    ```
+*   The tests are configured to run in different environments (Node.js and browser via `happy-dom`/`playwright`) to ensure compatibility.
+*   Test coverage can be generated by running `bun test --coverage`.
 ### Contributing Guidelines
 We welcome contributions! Please follow these guidelines:
 1.  **Fork** the repository and **clone** your fork.
-2.  Create a **new branch** for your feature or bug fix: `git checkout -b feature/my-new-feature` or `bugfix/fix-some-bug`.
-3.  Make your changes, ensuring code adheres to existing style and conventions.
-4.  Write or update **tests** for your changes to ensure proper functionality and maintain test coverage.
-5.  Ensure all tests pass (`bun test`).
-6.  Use **semantic commit messages** (e.g., `feat: add new feature`, `fix: resolve bug`). This project uses `semantic-release`.
-7.  **Open a Pull Request** to the `main` branch of the upstream repository.
+2.  Create a new **branch** for your feature or bug fix: `git checkout -b feature/my-new-feature` or `bugfix/fix-that-bug`.
+3.  Ensure your code adheres to existing coding styles (ESLint, Prettier are used internally).
+4.  Write **tests** for your changes.
+5.  Ensure all tests pass (`bun run test`).
+6.  **Commit** your changes with clear, concise messages following [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) (e.g., `feat: add new feature`, `fix: resolve bug`).
+7.  **Push** your branch and create a **Pull Request** to the `main` branch.
 ### Issue Reporting
-For bugs, feature requests, or questions, please open an issue on our [GitHub Issues page](https://github.com/asaidimu/data-model/issues).
+*   **Bug Reports**: If you find a bug, please open an issue on the [GitHub Issues page](https://github.com/asaidimu/data-model/issues). Provide a clear description, steps to reproduce, expected behavior, and your environment details.
+*   **Feature Requests**: For new features or enhancements, open an issue with a detailed explanation of the proposed functionality and its use case.
 ## Additional Information
 ### Troubleshooting
--   **`Buffer is not defined` error**: If running in a browser environment, ensure that `window.Buffer = Buffer;` is included as done in `src/lib/registry/registry.ts`.
--   **CORS issues with `isomorphic-git` or PocketBase**: If interacting with remote Git repositories or PocketBase from a browser, you might need a CORS proxy. Configure `createGitSchemaRegistry` or `createPocketBasePersistence` with a `proxy` URL.
--   **Migration `TRANSFORM_ERROR`**: Ensure your `DataTransform` functions are correctly defined and handle all expected input shapes. For remote transforms, verify the URL and module export.
--   **Git `fastForwardOnly` errors**: When performing `git pull` or `git push`, if `fastForwardOnly` is enabled and conflicts exist, the operation might fail. Consider resolving conflicts manually or disable `fastForwardOnly` if acceptable for your workflow.
+*   **"Buffer is not defined"**: If you encounter this error in a browser environment, ensure that `window.Buffer = Buffer;` is included in your entry point, as `LightningFS` and `isomorphic-git` might rely on it. Anansi's `registry.ts` already includes this for convenience.
+*   **CORS Issues with Git Remote**: When using `createGitSchemaRegistry` in a browser, you might hit CORS restrictions. Utilize the `proxy` option with a CORS proxy URL (e.g., `https://cors.isomorphic-git.org`) in the factory function.
+*   **Migration Checksum Mismatch**: If you modify a migration file after it has been added to the registry, its checksum will no longer match, leading to an error. Always generate new migrations for changes or ensure your migration logic is stable.
-### FAQ
+### Changelog & Roadmap
--   **What is Anansi primarily designed for?**
-    Anansi is designed for managing complex enterprise data models, focusing on schema evolution, data integrity, and flexible persistence across distributed systems. It's a comprehensive toolkit, not just a simple ORM or validation library.
--   **How does Anansi handle data transformations during migrations?**
-    Anansi uses `DataTransform` objects within migrations, which contain explicit `forward` and `backward` functions. These functions are executed on data streams to transform data shapes as the schema evolves.
--   **Is Anansi production-ready?**
-    Yes, Anansi is built with production use cases in mind, emphasizing theoretical rigor, data integrity, and extensible architecture. The PocketBase adapter and Git-backed schema registry provide production-grade capabilities for persistence and version control.
--   **Can I use Anansi with other databases?**
-    Yes, Anansi is designed with a pluggable `Persistence` interface. You can create custom adapters for any database or data source by implementing this interface.
+Stay up-to-date with the latest changes and future plans:
-### Changelog
-For a detailed history of changes, features, and bug fixes, please refer to the [CHANGELOG.md](CHANGELOG.md) file.
+*   **Changelog**: Refer to the [CHANGELOG.md](CHANGELOG.md) for a detailed history of releases and breaking changes.
+*   **Roadmap**: Future development plans are typically tracked via GitHub issues and project boards.
 ### License
-This project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details.
+Anansi is open-source software licensed under the **MIT License**. You can find the full text in the [LICENSE.md](LICENSE.md) file.
 ### Acknowledgments
-Anansi draws inspiration from and builds upon several foundational technologies and concepts:
+Anansi builds upon the shoulders of giants. We'd like to acknowledge the following projects and libraries that make Anansi possible:
--   **SQL Pragmatism**: For the approach to schema definition, constraints, and indexing.
--   **`isomorphic-git`**: For enabling Git operations in diverse JavaScript environments.
--   **`LightningFS`**: For providing a performant in-memory filesystem abstraction.
--   **PocketBase**: For its powerful real-time backend capabilities, integrated via a dedicated persistence adapter.
--   **`@faker-js/faker`**: For robust mock data generation capabilities.
--   **`@standard-schema/spec`**: For providing a standardized schema validation specification.
+*   [isomorphic-git](https://isomorphic-git.org/): For bringing Git to JavaScript environments.
+*   [@isomorphic-git/lightning-fs](https://www.npmjs.com/package/@isomorphic-git/lightning-fs): A super-fast in-memory filesystem.
+*   [PocketBase](https://pocketbase.io/): For a delightful backend experience.
+*   [@faker-js/faker](https://fakerjs.dev/): For robust mock data generation.
+*   [@standard-schema/spec](https://github.com/standard-schema/spec): For a standardized schema validation interface.
+*   [Bun](https://bun.sh/): For an incredibly fast JavaScript runtime and toolkit.
+*   [Vitest](https://vitest.dev/): For a blazing-fast unit test framework.
+*   [VitePress](https://vitepress.dev/): For beautiful and fast documentation.
-We are grateful to the creators and maintainers of these projects for their invaluable contributions to the open-source ecosystem.
+---