bunsane 0.1.0 → 0.1.1

package/docs/getting-started.md

@@ -0,0 +1,337 @@
+# Getting Started with BunSane
+
+This guide will walk you through installing and setting up BunSane for your first project.
+
+## 📋 Prerequisites
+
+Before you begin, ensure you have the following installed:
+
+- **Bun Runtime**: Version 1.0 or later ([Download Bun](https://bun.sh/))
+- **PostgreSQL**: Version 12 or later ([Download PostgreSQL](https://www.postgresql.org/download/))
+- **Node.js**: Version 18+ (for some development tools, though Bun is the primary runtime)
+
+## 🚀 Installation
+
+### 1. Install BunSane
+
+```bash
+bun install bunsane
+```
+
+### 2. Verify Installation
+
+```bash
+bun run --version
+# Should show Bun version 1.x.x
+```
+
+## ⚙️ Configuration
+
+### TypeScript Configuration
+
+BunSane requires experimental decorators to be enabled. Update your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*", "index.ts"],
+  "exclude": ["node_modules"]
+}
+```
+
+### Database Setup
+
+Create a PostgreSQL database for your application:
+
+```sql
+-- Create database
+CREATE DATABASE bunsane_app;
+
+-- Create user (optional)
+CREATE USER bunsane_user WITH PASSWORD 'your_password';
+
+-- Grant permissions
+GRANT ALL PRIVILEGES ON DATABASE bunsane_app TO bunsane_user;
+```
+
+### Environment Configuration
+
+Create a `.env` file in your project root:
+
+```env
+# Database Configuration
+DATABASE_URL=postgresql://username:password@localhost:5432/bunsane_app
+
+# Application Configuration
+NODE_ENV=development
+PORT=3000
+
+# Optional: Logging
+LOG_LEVEL=info
+```
+
+## 🏗️ Your First BunSane Application
+
+### Project Structure
+
+Create the following directory structure:
+
+```
+my-bunsane-app/
+├── src/
+│   ├── services/
+│   └── helpers/
+├── index.ts
+├── package.json
+├── tsconfig.json
+└── .env
+```
+
+### 1. Create Your First Component
+
+```typescript
+// src/services/UserService.ts
+import { Component, CompData, BaseComponent, ArcheType, Entity, GraphQLObjectType, GraphQLOperation, GraphQLFieldTypes, GraphQLField } from 'bunsane';
+
+@Component
+export class UserProfile extends BaseComponent {
+  @CompData()
+  name: string = '';
+
+  @CompData()
+  email: string = '';
+
+  @CompData({ indexed: true })
+  username: string = '';
+}
+
+@Component
+export class UserPreferences extends BaseComponent {
+  @CompData()
+  theme: 'light' | 'dark' = 'light';
+
+  @CompData()
+  notifications: boolean = true;
+}
+```
+
+### 2. Create an ArcheType
+
+```typescript
+// src/services/UserService.ts (continued)
+import { ArcheType } from 'bunsane';
+
+export const UserArcheType = new ArcheType([
+  UserProfile,
+  UserPreferences
+]);
+```
+
+### 3. Create a Service
+
+```typescript
+// src/services/UserService.ts (continued)
+import { BaseService, GraphQLObjectType, GraphQLOperation, GraphQLFieldTypes, GraphQLField } from 'bunsane';
+
+const userFields = {
+  id: GraphQLFieldTypes.ID_REQUIRED,
+  name: GraphQLFieldTypes.STRING_OPTIONAL,
+  email: GraphQLFieldTypes.STRING_REQUIRED,
+  username: GraphQLFieldTypes.STRING_OPTIONAL
+};
+
+const userInputs = {
+  createUser: {
+    name: GraphQLFieldTypes.STRING_REQUIRED,
+    email: GraphQLFieldTypes.STRING_REQUIRED,
+    username: GraphQLFieldTypes.STRING_REQUIRED
+  },
+  getUser: {
+    id: GraphQLFieldTypes.ID_REQUIRED
+  }
+};
+
+@GraphQLObjectType({
+  name: "User",
+  fields: userFields
+})
+export default class UserService extends BaseService {
+  @GraphQLOperation({
+    type: "Mutation",
+    input: userInputs.createUser,
+    output: "User"
+  })
+  async createUser(args: { name: string; email: string; username: string }) {
+    const userEntity = UserArcheType.fill(args).createEntity();
+    await userEntity.save();
+    return await UserArcheType.Unwrap(userEntity);
+  }
+
+  @GraphQLOperation({
+    type: "Query",
+    input: userInputs.getUser,
+    output: "User"
+  })
+  async getUser(args: { id: string }) {
+    const entity = await Entity.FindById(args.id);
+    if (!entity) return null;
+    return await UserArcheType.Unwrap(entity);
+  }
+
+  @GraphQLField({ type: "User", field: "id" })
+  idResolver(parent: Entity) {
+    return parent.id;
+  }
+
+  @GraphQLField({ type: "User", field: "name" })
+  async nameResolver(parent: Entity) {
+    const profile = await parent.get(UserProfile);
+    return profile?.name ?? "";
+  }
+
+  @GraphQLField({ type: "User", field: "email" })
+  async emailResolver(parent: Entity) {
+    const profile = await parent.get(UserProfile);
+    return profile?.email ?? "";
+  }
+
+  @GraphQLField({ type: "User", field: "username" })
+  async usernameResolver(parent: Entity) {
+    const profile = await parent.get(UserProfile);
+    return profile?.username ?? "";
+  }
+}
+```
+
+### 4. Set Up the Application
+
+```typescript
+// index.ts
+import { App } from 'bunsane';
+import UserService from './src/services/UserService';
+
+async function main() {
+  // Services are automatically registered when imported
+  // No manual registration needed
+
+  // Create and start the application
+  const app = new App({
+    port: 3000,
+    databaseUrl: process.env.DATABASE_URL
+  });
+
+  await app.start();
+
+  console.log('🚀 BunSane server running on http://localhost:3000');
+}
+
+main().catch(console.error);
+```
+
+### 5. Run Your Application
+
+```bash
+bun run index.ts
+```
+
+## 🧪 Testing Your Setup
+
+### GraphQL API Testing
+
+Your service now exposes GraphQL endpoints. Visit `http://localhost:3000/graphql` to access the GraphQL playground.
+
+**Create User Mutation:**
+```graphql
+mutation CreateUser($input: CreateUserInput!) {
+  createUser(input: $input) {
+    id
+    name
+    email
+    username
+  }
+}
+```
+
+With variables:
+```json
+{
+  "input": {
+    "name": "John Doe",
+    "email": "john.doe@example.com",
+    "username": "johndoe"
+  }
+}
+```
+
+**Get User Query:**
+```graphql
+query GetUser($id: ID!) {
+  getUser(input: { id: $id }) {
+    id
+    name
+    email
+    username
+  }
+}
+```
+
+### REST API Testing
+
+You can also test REST endpoints using tools like curl or Postman:
+
+```bash
+# Example curl request
+curl -X GET http://localhost:3000/api/users
+```
+
+## 🔍 What's Next?
+
+Congratulations! You now have a working BunSane application. Here's what you can explore next:
+
+- **[Entity System](core-concepts/entity.md)** - Deep dive into entity management
+- **[Component Architecture](core-concepts/components.md)** - Advanced component patterns
+- **[Query System](core-concepts/query.md)** - Efficient data retrieval
+- **[Lifecycle Hooks](core-concepts/hooks.md)** - Business logic integration
+- **[Real Examples](examples/)** - Complete application tutorials
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**"Component not registered" error**
+- Ensure all components are properly decorated with `@Component`
+- Check that components are imported before use
+
+**Database connection failed**
+- Verify PostgreSQL is running
+- Check DATABASE_URL format and credentials
+- Ensure database exists and user has permissions
+
+**Service not found error**
+- Verify services extend `BaseService`
+- Check that services are registered with `ServiceRegistry`
+
+### Getting Help
+
+- [GitHub Issues](https://github.com/yaaruu/bunsane/issues) - Report bugs
+- [GitHub Discussions](https://github.com/yaaruu/bunsane/discussions) - Ask questions
+- [Documentation](https://yaaruu.github.io/bunsane/) - Complete reference
+
+---
+
+*Ready to build something amazing? Let's continue with the [Entity System](core-concepts/entity.md)!* 🚀

package/docs/index.html

@@ -0,0 +1,97 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>BunSane Framework Documentation</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Professional documentation for BunSane - A batteries-included TypeScript API framework for Bun">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+  <link rel="icon" href="https://raw.githubusercontent.com/yaaruu/bunsane/main/BunSane.jpg" type="image/x-icon">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/dark.css" title="dark" disabled>
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/buble.css" title="buble" disabled>
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/pure.css" title="pure" disabled>
+  <style>
+    .sidebar-nav ul li a {
+      font-size: 14px;
+      padding: 8px 15px;
+    }
+    .sidebar-nav ul li.active > a {
+      background-color: #f0f8ff;
+      border-left: 4px solid #007acc;
+    }
+    .content {
+      max-width: 900px;
+    }
+    .markdown-section h1 {
+      border-bottom: 2px solid #007acc;
+      padding-bottom: 10px;
+    }
+    .markdown-section h2 {
+      border-bottom: 1px solid #ddd;
+      padding-bottom: 5px;
+    }
+    .markdown-section code {
+      background-color: #f6f8fa;
+      padding: 2px 6px;
+      border-radius: 3px;
+      font-size: 0.9em;
+    }
+    .markdown-section pre code {
+      background-color: transparent;
+      padding: 0;
+    }
+    .markdown-section blockquote {
+      border-left: 4px solid #007acc;
+      background-color: #f0f8ff;
+      margin: 20px 0;
+      padding: 15px 20px;
+    }
+  </style>
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'BunSane Framework',
+      repo: 'https://github.com/yaaruu/bunsane',
+      loadSidebar: true,
+      loadNavbar: true,
+      coverpage: true,
+      themeColor: '#007acc',
+      auto2top: true,
+      search: {
+        paths: 'auto',
+        placeholder: 'Search documentation...',
+        noData: 'No results found',
+        depth: 3
+      },
+      pagination: {
+        previousText: 'Previous',
+        nextText: 'Next',
+        crossChapter: true,
+        crossChapterText: true
+      },
+      plugins: [
+        function(hook, vm) {
+          hook.beforeEach(function(html) {
+            return html + '\n\n---\n\n*Last updated: ' + new Date().toLocaleDateString() + '*';
+          });
+        }
+      ]
+    }
+  </script>
+  <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/emoji.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/zoom-image.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/external-script.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-typescript.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-sql.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-graphql.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/plugins/line-numbers/prism-line-numbers.min.js"></script>
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/prismjs@1/plugins/line-numbers/prism-line-numbers.css">
+</body>
+</html>

package/examples/hooks/README.md

@@ -0,0 +1,228 @@
+# Entity Lifecycle Hooks Examples
+
+This directory contains example implementations of common use cases for the Entity Lifecycle Hooks system. Each example demonstrates best practices for hook implementation, error handling, and performance optimization.
+
+## Examples Overview
+
+### 1. Audit Logging (`audit-logger.ts`)
+Demonstrates comprehensive audit logging for entity lifecycle events with different storage backends.
+
+### 2. Cache Management (`cache-manager.ts`)
+Shows how to implement intelligent cache invalidation and population using entity hooks.
+
+### 3. Search Indexing (`search-indexer.ts`)
+Illustrates real-time search index updates for entities and components.
+
+### 4. Business Rules (`business-rules.ts`)
+Examples of business rule validation and enforcement using component hooks.
+
+### 5. Notifications (`notification-service.ts`)
+Demonstrates event-driven notification systems for user actions.
+
+### 6. Data Synchronization (`data-sync.ts`)
+Shows cross-system data synchronization patterns.
+
+### 7. Metrics Collection (`metrics-collector.ts`)
+Performance monitoring and metrics collection for entity operations.
+
+### 8. Security (`security-hooks.ts`)
+Security-related hooks for access control and data protection.
+
+## Usage
+
+Each example can be used as a starting point for your own implementations. Import the example classes and register them with the hook system:
+
+```typescript
+import { AuditLogger } from "./examples/hooks/audit-logger";
+import { registerDecoratedHooks } from "bunsane";
+
+// Register example hooks
+const auditLogger = new AuditLogger();
+registerDecoratedHooks(auditLogger);
+```
+
+## Best Practices Demonstrated
+
+- **Error Isolation**: Each hook handles its own errors without affecting others
+- **Performance Optimization**: Use of filters, batching, and async operations
+- **Resource Management**: Proper cleanup and resource handling
+- **Type Safety**: Full TypeScript support with proper typing
+- **Monitoring**: Built-in metrics and logging
+- **Configuration**: Environment-based configuration
+- **Testing**: Testable hook implementations
+
+## Common Patterns
+
+### Conditional Execution
+```typescript
+@EntityHook("entity.created")
+async handleEntityCreated(event: EntityCreatedEvent) {
+    // Only process specific entity types
+    if (!event.getEntity().has(TargetComponent)) return;
+
+    // Process the entity
+    await this.processEntity(event.getEntity());
+}
+```
+
+### Batch Processing
+```typescript
+private pendingEvents: EntityCreatedEvent[] = [];
+
+@EntityHook("entity.created")
+handleEntityCreated(event: EntityCreatedEvent) {
+    this.pendingEvents.push(event);
+
+    // Process in batches to improve performance
+    if (this.pendingEvents.length >= 10) {
+        this.processBatch();
+    }
+}
+```
+
+### Error Handling
+```typescript
+@EntityHook("entity.created")
+async handleEntityCreated(event: EntityCreatedEvent) {
+    try {
+        await this.unreliableOperation();
+    } catch (error) {
+        // Log error but don't throw - preserve other hooks
+        this.logger.error("Hook execution failed:", error);
+    }
+}
+```
+
+### Resource Cleanup
+```typescript
+@EntityHook("entity.deleted")
+handleEntityDeleted(event: EntityDeletedEvent) {
+    // Clean up resources associated with the entity
+    this.cache.delete(event.getEntity().id);
+    this.pendingOperations.delete(event.getEntity().id);
+}
+```
+
+## Configuration
+
+Most examples support configuration through environment variables or constructor parameters:
+
+```typescript
+// Environment-based configuration
+const auditLogger = new AuditLogger({
+    enabled: process.env.AUDIT_ENABLED === 'true',
+    level: process.env.AUDIT_LEVEL || 'info',
+    storage: process.env.AUDIT_STORAGE || 'database'
+});
+```
+
+## Testing
+
+Each example includes testing patterns:
+
+```typescript
+describe("AuditLogger", () => {
+    let auditLogger: AuditLogger;
+
+    beforeEach(() => {
+        auditLogger = new AuditLogger();
+        registerDecoratedHooks(auditLogger);
+    });
+
+    afterEach(() => {
+        EntityHookManager.clearAllHooks();
+    });
+
+    test("should log entity creation", async () => {
+        const entity = Entity.Create();
+        await entity.save();
+
+        // Verify audit log was created
+        expect(auditLogger.getLogs()).toContain(/* expected log entry */);
+    });
+});
+```
+
+## Performance Considerations
+
+Examples demonstrate performance optimization techniques:
+
+- **Filtering**: Reduce unnecessary hook execution
+- **Batching**: Group operations for efficiency
+- **Async Processing**: Use async hooks for I/O operations
+- **Caching**: Cache frequently accessed data
+- **Timeouts**: Prevent hanging operations
+
+## Integration
+
+Examples show how to integrate with existing systems:
+
+- **Database**: Entity persistence and queries
+- **Cache**: Redis, Memcached, or in-memory caching
+- **Search**: Elasticsearch, Algolia, or custom search
+- **Queues**: Background job processing
+- **Monitoring**: Metrics collection and alerting
+- **Logging**: Structured logging with context
+
+## Customization
+
+Examples are designed to be easily customizable:
+
+```typescript
+// Extend base examples
+class CustomAuditLogger extends AuditLogger {
+    @EntityHook("entity.updated")
+    async handleCustomUpdate(event: EntityUpdatedEvent) {
+        // Custom logic
+        await super.handleEntityUpdated(event);
+
+        // Additional processing
+        await this.customProcessing(event);
+    }
+}
+```
+
+## Monitoring
+
+Examples include monitoring and health checks:
+
+```typescript
+// Health check endpoint
+app.get('/health/hooks', async (req, res) => {
+    const metrics = EntityHookManager.getMetrics();
+    const health = {
+        status: metrics.errorCount > 10 ? 'unhealthy' : 'healthy',
+        metrics,
+        timestamp: new Date().toISOString()
+    };
+
+    res.json(health);
+});
+```
+
+## Troubleshooting
+
+Common issues and solutions:
+
+1. **Hooks not executing**: Check `EntityHookManager.waitForReady()`
+2. **Performance issues**: Use `EntityHookManager.getMetrics()` to identify bottlenecks
+3. **Memory leaks**: Ensure proper cleanup in deletion hooks
+4. **Error propagation**: Handle errors gracefully to prevent hook isolation issues
+
+## Contributing
+
+When adding new examples:
+
+1. Follow the established patterns and best practices
+2. Include comprehensive error handling
+3. Add performance optimizations
+4. Provide configuration options
+5. Include tests and documentation
+6. Demonstrate integration patterns
+
+## Related Documentation
+
+- [Hooks Documentation](../HOOKS_DOCUMENTATION.md)
+- [Migration Guide](../HOOKS_MIGRATION_GUIDE.md)
+- [Performance Guide](../HOOKS_PERFORMANCE_GUIDE.md)
+- [API Reference](../HOOKS_DOCUMENTATION.md#api-reference)