bunsane 0.1.0 → 0.1.2

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/gql/Generator.ts

@@ -1,72 +1,94 @@
 import { GraphQLSchema, GraphQLError } from "graphql";
-import {makeExecutableSchema} from "@graphql-tools/schema";
+import { createSchema } from "graphql-yoga";
 import { logger as MainLogger } from "core/Logger";
+import type { GraphQLType } from "./helpers";
 const logger = MainLogger.child({ scope: "GraphQLGenerator" });
-export interface GraphQLTypeMeta {
+export interface GraphQLObjectTypeMeta {
     name: string;
-    fields: Record<string, string>;
+    fields: Record<string, GraphQLType>;
 }
 
 export interface GraphQLOperationMeta {
     type: "Query" | "Mutation";
     name?: string;
-    input?: Record<string, string>;
-    output: Record<string, string> | string;
+    input?: Record<string, GraphQLType>;
+    output: GraphQLType | Record<string, GraphQLType>;
 }
 
 export interface GraphQLFieldMeta {
-    type: string;
+    type: GraphQLType;
     field: string;
 }
 
-export function GraphQLType(meta: GraphQLTypeMeta) {
+export function GraphQLObjectType(meta: GraphQLObjectTypeMeta) {
     return (target: any) => {
-        target.__graphqlType = meta;
+        if (!target.__graphqlObjectType) target.__graphqlObjectType = [];
+        target.__graphqlObjectType.push(meta);
+    }
+}
+
+export function GraphQLScalarType(name: string) {
+    return (target: any) => {
+        if (!target.__graphqlScalarTypes) target.__graphqlScalarTypes = [];
+        target.__graphqlScalarTypes.push(name);
     }
 }
 
 export function GraphQLOperation(meta: GraphQLOperationMeta) {
-    return function (target: any, context: ClassMethodDecoratorContext) {
+    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
         if (!target.__graphqlOperations) target.__graphqlOperations = [];
-        const operationName = meta.name ?? context;
+        const operationName = meta.name ?? propertyKey;
         if (!operationName) {
-            throw new Error("GraphQLOperation: Operation name is required (either meta.name or context.name must be defined)");
+            throw new Error("GraphQLOperation: Operation name is required (either meta.name or propertyKey must be defined)");
         }
-        const operationMeta = { ...meta, name: operationName, propertyKey: context};
+        const operationMeta = { ...meta, name: operationName, propertyKey };
         target.__graphqlOperations.push(operationMeta);
     };
 }
 
 export function GraphQLField(meta: GraphQLFieldMeta) {
-    return function (target: any, context: ClassMethodDecoratorContext) {
+    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
         if (!target.__graphqlFields) target.__graphqlFields = [];
-        target.__graphqlFields.push({ ...meta, propertyKey: context });
+        target.__graphqlFields.push({ ...meta, propertyKey });
     };
 }
 
-export function generateGraphQLSchema(systems: any[]): { schema: GraphQLSchema | null; resolvers: any } {
-    let typeDefs = "";
-    const resolvers: any = { Query: {}, Mutation: {} };
+export function generateGraphQLSchema(services: any[]): { schema: GraphQLSchema | null; resolvers: any } {
+    let typeDefs = `
+    `;
+    const scalarTypes: Set<string> = new Set();
+    const resolvers: any = {};
     const queryFields: string[] = [];
     const mutationFields: string[] = [];
 
-    systems.forEach(system => {
-        logger.trace(`Processing system: ${system.constructor.name}`);
-        if (system.constructor.__graphqlType) {
-            const { name, fields } = system.constructor.__graphqlType;
-            typeDefs += `type ${name} {\n${Object.entries(fields).map(([k, v]) => `  ${k}: ${v}`).join('\n')}\n}\n`;
+    services.forEach(service => {
+        logger.trace(`Processing service: ${service.constructor.name}`);
+        if(service.constructor.__graphqlScalarTypes) {
+            for (const scalarName of service.constructor.__graphqlScalarTypes) {
+                if (!scalarTypes.has(scalarName)) {
+                    scalarTypes.add(scalarName);
+                    typeDefs += `scalar ${scalarName}\n`;
+                }
+            }
+        }
+        if (service.constructor.__graphqlObjectType) {
+            for (const meta of service.constructor.__graphqlObjectType) {
+                const { name, fields } = meta;
+                typeDefs += `type ${name} {\n${Object.entries(fields).map(([k, v]) => `  ${k}: ${v}`).join('\n')}\n}\n`;
+            }
         }
-        if (system.__graphqlOperations) {
-            system.__graphqlOperations.forEach((op: any) => {
+        if (service.__graphqlOperations) {
+            service.__graphqlOperations.forEach((op: any) => {
                 const { type, name, input, output, propertyKey } = op;
+                if (!resolvers[type]) resolvers[type] = {};
                 let fieldDef = `${name}`;
                 if (input) {
                     const inputName = `${name}Input`;
                     typeDefs += `input ${inputName} {\n${Object.entries(input).map(([k, v]) => `  ${k}: ${v}`).join('\n')}\n}\n`;
                     fieldDef += `(input: ${inputName}!)`;
-                    resolvers[type][name] = async (_: any, args: any, context: any) => {
+                    resolvers[type][name] = async (_: any, args: any, context: any, info: any) => {
                         try {
-                            return await system[propertyKey](args.input || args, context);
+                            return await service[propertyKey](args.input || args, context, info);
                         } catch (error) {
                             logger.error(`Error in ${type}.${name}:`);
                             logger.error(error);
@@ -82,9 +104,9 @@ export function generateGraphQLSchema(systems: any[]): { schema: GraphQLSchema |
                         }
                     };
                 } else {
-                    resolvers[type][name] = async (_: any, args: any, context: any) => {
+                    resolvers[type][name] = async (_: any, args: any, context: any, info: any) => {
                         try {
-                            return await system[propertyKey]({}, context);
+                            return await service[propertyKey]({}, context, info);
                         } catch (error) {
                             logger.error(`Error in ${type}.${name}:`);
                             logger.error(error);
@@ -117,14 +139,14 @@ export function generateGraphQLSchema(systems: any[]): { schema: GraphQLSchema |
     });
 
     // Process field resolvers
-    systems.forEach(system => {
-        if (system.__graphqlFields) {
-            system.__graphqlFields.forEach((fieldMeta: any) => {
+    services.forEach(service => {
+        if (service.__graphqlFields) {
+            service.__graphqlFields.forEach((fieldMeta: any) => {
                 const { type, field, propertyKey } = fieldMeta;
                 if (!resolvers[type]) resolvers[type] = {};
-                resolvers[type][field] = async (parent: any, args: any, context: any) => {
+                resolvers[type][field] = async (parent: any, args: any, context: any, info: any) => {
                     try {
-                        return await system[propertyKey](parent, args, context);
+                        return await service[propertyKey](parent, args, context, info);
                     } catch (error) {
                         logger.error(`Error in ${type}.${field}:`);
                         logger.error(error);
@@ -152,8 +174,9 @@ export function generateGraphQLSchema(systems: any[]): { schema: GraphQLSchema |
 
     logger.trace(`System Type Defs: ${typeDefs}`);
     let schema : GraphQLSchema | null = null;
-    if(typeDefs !== "")  {
-        schema = makeExecutableSchema({ typeDefs, resolvers });
+    // Check if typeDefs contains actual schema definitions, not just whitespace
+    if(typeDefs.trim() !== "" && (queryFields.length > 0 || mutationFields.length > 0 || scalarTypes.size > 0))  {
+        schema = createSchema({ typeDefs, resolvers });
     }
     return { schema, resolvers };
 }