@venizia/ignis-docs 0.0.2 → 0.0.4-0

package/wiki/references/helpers/uid.md

@@ -0,0 +1,167 @@
+# UID Helper
+
+Snowflake ID generator with Base62 encoding for generating unique, time-sortable IDs suitable for distributed systems.
+
+## Quick Reference
+
+| Class | Purpose | Key Features |
+|-------|---------|--------------|
+| **SnowflakeConfig** | Configuration constants | Bit structure, limits, defaults |
+| **SnowflakeUidHelper** | ID generation | Snowflake IDs, Base62 encoding/decoding |
+
+### Snowflake ID Structure (70 bits)
+
+| Component | Bits | Range | Purpose |
+|-----------|------|-------|---------|
+| Timestamp | 48 | ~8,919 years | Time since epoch |
+| Worker ID | 10 | 0-1023 | Unique worker identifier |
+| Sequence | 12 | 0-4095 | IDs per millisecond |
+
+### Key Specifications
+
+| Spec | Value |
+|------|-------|
+| Base62 Output | 10-12 characters |
+| Throughput | 4,096,000 IDs/second/worker |
+| Max Workers | 1024 |
+| Lifespan | Until ~10,944 AD |
+| Default Epoch | 2025-01-01 00:00:00 UTC |
+
+## Basic Usage
+
+### Creating an Instance
+
+```typescript
+import { SnowflakeUidHelper, SnowflakeConfig } from '@venizia/ignis-helpers';
+
+// Use defaults (workerId: 199, epoch: 2025-01-01 00:00:00 UTC)
+const generator = new SnowflakeUidHelper();
+
+// Or with custom values
+const customGenerator = new SnowflakeUidHelper({
+  workerId: 123,
+  epoch: BigInt(1735689600000),
+});
+```
+
+### Generating IDs
+
+```typescript
+// Generate Base62 encoded ID (recommended for most use cases)
+const id = generator.nextId();
+// => e.g., "9du1sJXO88"
+
+// Generate raw Snowflake ID as bigint
+const snowflakeId = generator.nextSnowflake();
+// => e.g., 130546360012247045n
+```
+
+## Base62 Encoding/Decoding
+
+### Encode a BigInt to Base62
+
+```typescript
+const encoded = generator.encodeBase62(130546360012247045n);
+// => "9du1sJXO88"
+```
+
+### Decode Base62 to BigInt
+
+```typescript
+const decoded = generator.decodeBase62("9du1sJXO88");
+// => 130546360012247045n
+```
+
+## Parsing and Extracting Components
+
+### Parse a Base62 ID
+
+```typescript
+const parsed = generator.parseId("9du1sJXO88");
+// => {
+//   raw: 130546360012247045n,
+//   timestamp: Date,
+//   workerId: 199,
+//   sequence: 0
+// }
+```
+
+### Extract Individual Components
+
+```typescript
+const snowflakeId = generator.nextSnowflake();
+
+// Extract timestamp
+const timestamp = generator.extractTimestamp(snowflakeId);
+// => Date object
+
+// Extract worker ID
+const workerId = generator.extractWorkerId(snowflakeId);
+// => 199
+
+// Extract sequence
+const sequence = generator.extractSequence(snowflakeId);
+// => 0-4095
+```
+
+## Configuration
+
+### SnowflakeConfig Constants
+
+```typescript
+import { SnowflakeConfig } from '@venizia/ignis-helpers';
+
+SnowflakeConfig.DEFAULT_EPOCH      // BigInt(1735689600000) - 2025-01-01 00:00:00 UTC
+SnowflakeConfig.MAX_WORKER_ID      // 1023n
+SnowflakeConfig.MAX_SEQUENCE       // 4095n
+SnowflakeConfig.TIMESTAMP_SHIFT    // 22n
+SnowflakeConfig.WORKER_ID_SHIFT    // 12n
+```
+
+### Constructor Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `workerId` | `number` | `199` | Worker ID (0-1023) |
+| `epoch` | `bigint` | `SnowflakeConfig.DEFAULT_EPOCH` | Custom epoch timestamp in milliseconds |
+
+## Error Handling
+
+The helper throws errors in these cases:
+
+- **Invalid Worker ID**: Worker ID outside 0-1023 range
+- **Invalid Epoch**: Epoch is zero, negative, or in the future
+- **Clock Backward**: System clock moved backward by more than 100ms
+- **Invalid Base62**: Decoding a string with invalid characters
+
+```typescript
+try {
+  const generator = new SnowflakeUidHelper({ workerId: 2000 }); // Invalid
+} catch (error) {
+  // Worker ID must be between 0 and 1023
+}
+```
+
+## Best Practices
+
+1. **Use unique worker IDs** in distributed systems to prevent ID collisions
+2. **Keep epoch consistent** across all instances to ensure proper ID ordering
+3. **Use `nextId()`** for most cases (returns compact Base62 string)
+4. **Use `nextSnowflake()`** when you need the raw bigint for arithmetic operations
+
+## See Also
+
+- **Related Concepts:**
+  - [Models](/guides/core-concepts/persistent/models) - Using UIDs as primary keys
+  - [Services](/guides/core-concepts/services) - Generating unique IDs
+
+- **Other Helpers:**
+  - [Helpers Index](./index) - All available helpers
+  - [Crypto Helper](./crypto) - For cryptographic random values
+
+- **External Resources:**
+  - [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) - Snowflake algorithm explained
+  - [Base62 Encoding](https://en.wikipedia.org/wiki/Base62) - Base62 encoding overview
+
+- **Best Practices:**
+  - [Data Modeling](/best-practices/data-modeling) - ID generation strategies

package/wiki/references/helpers/worker-thread.md

@@ -160,3 +160,19 @@ const workerBus = new BaseWorkerBusHelper({
   }),
 });
 ```
+
+## See Also
+
+- **Related Concepts:**
+  - [Services](/guides/core-concepts/services) - CPU-intensive tasks in services
+
+- **Other Helpers:**
+  - [Helpers Index](./index) - All available helpers
+  - [Queue Helper](./queue) - For I/O-bound background tasks
+
+- **External Resources:**
+  - [Node.js Worker Threads](https://nodejs.org/api/worker_threads.html) - Official worker_threads API
+  - [MessageChannel](https://nodejs.org/api/worker_threads.html#class-messagechannel) - Two-way communication
+
+- **Best Practices:**
+  - [Performance Optimization](/best-practices/performance-optimization) - Worker thread strategies

package/wiki/references/index.md

@@ -0,0 +1,177 @@
+# API Reference
+
+Complete reference documentation for the Ignis framework. Find detailed API docs, type definitions, and usage examples for every class, component, and utility in the framework.
+
+<div class="guide-cards">
+
+<a href="./base/" class="guide-card highlight">
+<span class="guide-icon">🏗️</span>
+<h3>Base Abstractions</h3>
+<p>Application, Controller, Service, Repository, Model</p>
+</a>
+
+<a href="./components/" class="guide-card">
+<span class="guide-icon">🧩</span>
+<h3>Components</h3>
+<p>Auth, Mail, Socket.IO, Swagger, Health Check</p>
+</a>
+
+<a href="./helpers/" class="guide-card">
+<span class="guide-icon">🛠️</span>
+<h3>Helpers</h3>
+<p>Logger, Redis, Queue, Storage, Cron, Crypto</p>
+</a>
+
+<a href="./utilities/" class="guide-card">
+<span class="guide-icon">⚙️</span>
+<h3>Utilities</h3>
+<p>Date, Parse, Promise, Schema, Performance</p>
+</a>
+
+<a href="./configuration/" class="guide-card">
+<span class="guide-icon">📝</span>
+<h3>Configuration</h3>
+<p>Environment variables and settings</p>
+</a>
+
+<a href="./src-details/" class="guide-card">
+<span class="guide-icon">📦</span>
+<h3>Framework Internals</h3>
+<p>Package structure and architecture</p>
+</a>
+
+</div>
+
+## Find What You Need
+
+<div class="roadmap">
+
+<div class="roadmap-stage">
+<div class="stage-header">
+<span class="stage-num">1</span>
+<h4>Building an API</h4>
+</div>
+<p><a href="./base/application">Application</a> → <a href="./base/controllers">Controllers</a> → <a href="./base/services">Services</a> → <a href="./base/repositories/">Repositories</a></p>
+<span class="stage-desc">Request handling, business logic, and data access</span>
+</div>
+
+<div class="roadmap-stage">
+<div class="stage-header">
+<span class="stage-num">2</span>
+<h4>Data Layer</h4>
+</div>
+<p><a href="./base/models">Models</a> → <a href="./base/datasources">DataSources</a> → <a href="./base/filter-system/">Filtering</a> → <a href="./base/repositories/relations">Relations</a></p>
+<span class="stage-desc">Entities, database connections, and query building</span>
+</div>
+
+<div class="roadmap-stage">
+<div class="stage-header">
+<span class="stage-num">3</span>
+<h4>Adding Features</h4>
+</div>
+<p><a href="./components/authentication">Auth</a> → <a href="./components/socket-io">Real-time</a> → <a href="./components/mail">Email</a> → <a href="./components/swagger">API Docs</a></p>
+<span class="stage-desc">Pre-built components for common features</span>
+</div>
+
+<div class="roadmap-stage">
+<div class="stage-header">
+<span class="stage-num">4</span>
+<h4>Infrastructure</h4>
+</div>
+<p><a href="./helpers/logger">Logging</a> → <a href="./helpers/redis">Caching</a> → <a href="./helpers/queue">Queues</a> → <a href="./helpers/cron">Scheduling</a></p>
+<span class="stage-desc">Background jobs, caching, and observability</span>
+</div>
+
+<div class="roadmap-stage">
+<div class="stage-header">
+<span class="stage-num">5</span>
+<h4>Advanced Patterns</h4>
+</div>
+<p><a href="./base/dependency-injection">Dependency Injection</a> → <a href="./base/providers">Custom Providers</a> → <a href="./base/middlewares">Middlewares</a> → <a href="./base/components">Components</a></p>
+<span class="stage-desc">Advanced architecture patterns and customization</span>
+</div>
+
+<div class="roadmap-stage">
+<div class="stage-header">
+<span class="stage-num">6</span>
+<h4>Production Ready</h4>
+</div>
+<p><a href="./base/middlewares">Error Handling</a> → <a href="./components/health-check">Health Checks</a> → <a href="./configuration/environment-variables">Configuration</a> → <a href="./base/bootstrapping">Auto-Discovery</a></p>
+<span class="stage-desc">Production deployment, monitoring, and reliability</span>
+</div>
+
+<div class="roadmap-stage">
+<div class="stage-header">
+<span class="stage-num">7</span>
+<h4>Testing & Quality</h4>
+</div>
+<p><a href="./helpers/testing">Unit Testing</a> → <a href="./base/repositories/advanced">Mocking & Stubs</a> → <a href="./quick-reference">Best Practices</a></p>
+<span class="stage-desc">Testing strategies, quality assurance, and code review</span>
+</div>
+
+</div>
+
+::: tip Looking for tutorials?
+Check out the [Getting Started Guide](/guides/) for step-by-step tutorials and the [Core Concepts](/guides/core-concepts/application/) for architectural explanations.
+:::
+
+## Quick Examples
+
+**Define a Controller:**
+```typescript
+@controller({ path: '/users' })
+class UserController extends BaseController {
+  @get({ configs: { path: '/:id' } })
+  getUser(c: Context) {
+    return c.json({ id: c.req.param('id') });
+  }
+}
+```
+
+**Query with Repository:**
+```typescript
+const users = await userRepo.find({
+  where: { isActive: true },
+  orderBy: { createdAt: 'desc' },
+  limit: 10,
+});
+```
+
+**Schedule a Job:**
+```typescript
+CronHelper.schedule('0 * * * *', async () => {
+  await cleanupExpiredSessions();
+});
+```
+
+## Common Imports
+
+```typescript
+// Core framework
+import {
+  BaseApplication,
+  BaseController,
+  BaseService,
+  BaseRepository,
+  controller,
+  get, post, put, del,
+  inject,
+} from '@venizia/ignis';
+
+// Helpers
+import {
+  LoggerFactory,
+  RedisHelper,
+  QueueHelper,
+} from '@venizia/ignis-helpers';
+
+// DI Container
+import { Container } from '@venizia/ignis-inversion';
+```
+
+## See Also
+
+- [Getting Started](/guides/) - New to Ignis? Start here
+- [Core Concepts](/guides/core-concepts/application/) - Deep dive into architecture
+- [Best Practices](/best-practices/) - Production patterns
+- [Changelogs](/changelogs/) - Version history