@venizia/ignis-docs 0.0.4-0 → 0.0.4-2

package/wiki/best-practices/common-pitfalls.md

@@ -54,8 +54,8 @@ export class Application extends BaseApplication {
   }),
 })
 
-// ❌ BAD - typo in string
-@inject({ key: 'repositories.ConfigurationRepositry' })
+// ❌ BAD - typo in string (note: "Repository" is misspelled)
+@inject({ key: 'repositories.ConfigurationRepository' })
 ```
 
 ## 3. Business Logic in Controllers
@@ -240,4 +240,165 @@ try {
     });
   }
 }
-```
+```
+
+## 9. Circular Dependency Issues
+
+**Problem:** Application fails to start with `Cannot access 'X' before initialization` or similar errors.
+
+**Cause:** Two or more modules import each other directly, creating a circular reference that JavaScript cannot resolve.
+
+**Solution:** Use lazy imports or restructure your modules:
+
+```typescript
+// ❌ BAD - Direct import causes circular dependency
+import { UserService } from './user.service';
+
+@model({ type: 'entity' })
+export class Order extends BaseEntity<typeof Order.schema> {
+  static override relations = (): TRelationConfig[] => [
+    { schema: User.schema, ... }, // User imports Order, Order imports User
+  ];
+}
+
+// ✅ GOOD - Lazy import breaks the cycle
+@model({ type: 'entity' })
+export class Order extends BaseEntity<typeof Order.schema> {
+  static override relations = (): TRelationConfig[] => {
+    const { User } = require('./user.model'); // Lazy require
+    return [{ schema: User.schema, ... }];
+  };
+}
+```
+
+**Alternative:** Restructure to have a shared module that both import from.
+
+## 10. Transaction Not Rolling Back
+
+**Problem:** Errors occur but database changes are still persisted.
+
+**Cause:** Transaction not properly wrapped in try-catch, or rollback not called on error.
+
+**Solution:** Always wrap transactions in try-catch with explicit rollback:
+
+```typescript
+// ❌ BAD - No error handling
+const tx = await repo.beginTransaction();
+await repo.create({ data, options: { transaction: tx } });
+await tx.commit(); // If create fails, commit is never called but neither is rollback
+
+// ✅ GOOD - Proper transaction handling
+const tx = await repo.beginTransaction();
+try {
+  await repo.create({ data, options: { transaction: tx } });
+  await otherRepo.update({ data: other, options: { transaction: tx } });
+  await tx.commit();
+} catch (error) {
+  await tx.rollback();
+  throw error; // Re-throw to let caller handle
+}
+```
+
+## 11. Fire-and-Forget Promises Losing Context
+
+**Problem:** `getCurrentUserId()` or other context-dependent functions return `null` in background tasks.
+
+**Cause:** When you fire-and-forget a promise, it runs outside the original async context where the user was authenticated.
+
+**Solution:** Pass required context data explicitly to background tasks:
+
+```typescript
+// ❌ BAD - Context lost in fire-and-forget
+@post({ configs: RouteConfigs.CREATE_ORDER })
+async createOrder(c: Context) {
+  const data = c.req.valid('json');
+  const order = await this.orderService.create(data);
+
+  // Fire-and-forget: sendNotification runs outside request context
+  this.notificationService.sendOrderConfirmation(order.id);
+  // Inside sendOrderConfirmation, getCurrentUserId() returns null!
+
+  return c.json(order);
+}
+
+// ✅ GOOD - Pass user ID explicitly
+@post({ configs: RouteConfigs.CREATE_ORDER })
+async createOrder(c: Context) {
+  const data = c.req.valid('json');
+  const userId = c.get(Authentication.AUDIT_USER_ID);
+  const order = await this.orderService.create(data);
+
+  // Pass userId explicitly to background task
+  this.notificationService.sendOrderConfirmation(order.id, userId);
+
+  return c.json(order);
+}
+```
+
+> [!WARNING]
+> This is especially important when using `allowAnonymous: false` in user audit columns. The enricher will throw an error if it cannot find the user context.
+
+## 12. Incorrect Relation Configuration
+
+**Problem:** Relations return empty arrays or `null` unexpectedly.
+
+**Cause:** Mismatch between `fields` and `references` in relation metadata.
+
+**Solution:** Double-check that foreign keys point to the correct columns:
+
+```typescript
+// ❌ BAD - fields and references swapped
+static override relations = (): TRelationConfig[] => [
+  {
+    name: 'posts',
+    type: RelationTypes.MANY,
+    schema: Post.schema,
+    metadata: {
+      fields: [Post.schema.authorId],     // Wrong! This should be User.schema.id
+      references: [User.schema.id],        // Wrong! This should be Post.schema.authorId
+    },
+  },
+];
+
+// ✅ GOOD - Correct configuration
+// "User has many Posts where User.id = Post.authorId"
+static override relations = (): TRelationConfig[] => [
+  {
+    name: 'posts',
+    type: RelationTypes.MANY,
+    schema: Post.schema,
+    metadata: {
+      fields: [User.schema.id],            // Parent's key
+      references: [Post.schema.authorId],  // Child's foreign key
+    },
+  },
+];
+```
+
+**Rule of thumb:** `fields` is the key on the current entity, `references` is the key on the related entity.
+
+## 13. Overwriting Data with Partial Updates
+
+**Problem:** PATCH endpoint replaces entire record instead of merging fields.
+
+**Cause:** Using `create()` or full `update()` instead of partial update methods.
+
+**Solution:** Use `updateById()` which only updates provided fields:
+
+```typescript
+// ❌ BAD - Overwrites all fields (if using raw insert/update)
+await db.update(users).set(data).where(eq(users.id, id));
+// If data = { name: 'New' }, email and other fields might be set to undefined
+
+// ✅ GOOD - Repository updateById only updates provided fields
+await userRepository.updateById({
+  id: userId,
+  data: { name: 'New Name' }, // Only updates 'name', leaves other fields intact
+});
+```
+
+## See Also
+
+- [Troubleshooting Tips](./troubleshooting-tips) - Debug common issues
+- [Error Handling](./error-handling) - Proper error handling patterns
+- [Architecture Decisions](./architecture-decisions) - Avoid design mistakes

package/wiki/best-practices/contribution-workflow.md

@@ -125,7 +125,7 @@ git checkout -b feature/your-feature-name
 ### Step 2: Make Changes
 
 **Checklist:**
-- ✅ Follow [Code Style Standards](./code-style-standards.md)
+- ✅ Follow [Code Style Standards](./code-style-standards/)
 - ✅ Follow [Architectural Patterns](./architectural-patterns.md)
 - ✅ Add tests for new features/fixes
 - ✅ Update docs in `packages/docs/wiki` if needed

package/wiki/best-practices/data-modeling.md

@@ -38,7 +38,7 @@ Instead of manually defining common columns like primary keys, timestamps, or au
 | `generateIdColumnDefs` | Adds a Primary Key | `id` (text, number, or big-number) |
 | `generatePrincipalColumnDefs` | Adds polymorphic relation fields | `{discriminator}Id`, `{discriminator}Type` |
 | `generateTzColumnDefs` | Adds timestamps | `createdAt`, `modifiedAt` (auto-updating) |
-| `generateUserAuditColumnDefs` | Adds audit fields | `createdBy`, `modifiedBy` |
+| `generateUserAuditColumnDefs` | Adds audit fields | `createdBy`, `modifiedBy` (supports `allowAnonymous` option) |
 | `generateDataTypeColumnDefs` | Adds generic value fields | `nValue` (number), `tValue` (text), `jValue` (json), etc. |
 | `extraUserColumns` | Comprehensive user fields | Combines audit, timestamps, status, and type fields |
 
@@ -373,4 +373,104 @@ export class User extends BaseEntity<typeof User.schema> {
 - Hidden properties are **recursively excluded** from included relations
 - Use the connector directly when you need to access hidden data (e.g., password verification)
 
-> **Reference:** See [Hidden Properties](../references/base/models.md#hidden-properties) for complete documentation.
+> **Reference:** See [Hidden Properties](../references/base/models.md#hidden-properties) for complete documentation.
+
+## 6. Database Migrations
+
+Drizzle Kit handles schema migrations. Follow these best practices for safe migrations.
+
+### Generate Migrations
+
+```bash
+# Generate migration from schema changes
+bun run db:generate
+
+# Apply migrations to database
+bun run db:migrate
+
+# Push schema directly (development only)
+bun run db:push
+```
+
+### Migration Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| **One change per migration** | Keep migrations focused and reversible |
+| **Never edit applied migrations** | Create new migration instead |
+| **Test on staging first** | Always test migrations before production |
+| **Backup before migrate** | `pg_dump` before running in production |
+| **Use transactions** | Drizzle wraps migrations in transactions by default |
+
+### Safe Schema Changes
+
+**Adding columns (safe):**
+```typescript
+// Add with default value to avoid nulls in existing rows
+newField: text('new_field').default(''),
+
+// Or allow null initially, then backfill and set notNull
+newField: text('new_field'),  // Initially nullable
+```
+
+**Renaming columns (requires care):**
+```sql
+-- In custom migration SQL
+ALTER TABLE "User" RENAME COLUMN "old_name" TO "new_name";
+```
+
+**Dropping columns (dangerous):**
+```typescript
+// 1. First, remove all code references
+// 2. Deploy code changes
+// 3. Then drop in separate migration
+```
+
+### Custom Migration SQL
+
+For complex migrations, use custom SQL:
+
+```typescript
+// drizzle/migrations/0005_custom_migration.ts
+import { sql } from 'drizzle-orm';
+
+export async function up(db: DrizzleDB) {
+  // Add index for performance
+  await db.execute(sql`
+    CREATE INDEX CONCURRENTLY idx_user_email
+    ON "User" (email)
+    WHERE status = 'ACTIVE'
+  `);
+
+  // Backfill data
+  await db.execute(sql`
+    UPDATE "User"
+    SET normalized_email = LOWER(email)
+    WHERE normalized_email IS NULL
+  `);
+}
+
+export async function down(db: DrizzleDB) {
+  await db.execute(sql`DROP INDEX IF EXISTS idx_user_email`);
+}
+```
+
+### Migration Checklist
+
+| Step | Action |
+|------|--------|
+| 1 | Review generated SQL before applying |
+| 2 | Test migration on staging database |
+| 3 | Backup production database |
+| 4 | Run during low-traffic period |
+| 5 | Monitor for errors after migration |
+| 6 | Have rollback plan ready |
+
+> [!WARNING]
+> Never run migrations directly on production without testing. Use staging environments that mirror production data structure.
+
+## See Also
+
+- [API Usage Examples](./api-usage-examples) - Query patterns
+- [Performance Optimization](./performance-optimization) - Index design
+- [Common Pitfalls](./common-pitfalls) - Migration mistakes to avoid