@leejungkiin/awkit 1.7.4 → 1.7.5

package/docs/history/PRD.v2.md

@@ -0,0 +1,57 @@
+# Product Requirement Document (PRD) - GreetingApp
+
+## Revision History
+| Version | Date | Description | Author |
+|---|---|---|---|
+| v1.0 | 2026-06-22 | Initial PRD for GreetingApp | Antigravity Orchestrator |
+
+---
+
+## 1. Executive Summary
+GreetingApp is a micro-application designed to deliver personalized, localized, and dynamic greetings to users. It adapts to the user's name, current time of day, and language preferences.
+
+## 2. Objectives & Goals
+- Provide dynamic greetings based on user local time (Morning, Afternoon, Evening, Night).
+- Support multi-language greetings (English, Vietnamese, Japanese).
+- Track user greeting history and statistics.
+- Expose both CLI and REST API interfaces.
+
+## 3. User Personas & Use Cases
+- **End User:** Wants to see a welcoming, contextual message when logging in or using the CLI.
+- **Developer:** Wants an easy-to-integrate greeting microservice API for downstream services.
+
+## 4. Functional Requirements
+1. **Dynamic Greeting Generation:**
+   - Detects local time of user.
+   - Personalizes with name (fallback to "Guest").
+2. **Localization (i18n):**
+   - Supports: English (`en`), Vietnamese (`vi`), Japanese (`ja`).
+3. **Greeting Analytics / History:**
+   - Stores logs of generated greetings (User, Timestamp, Language).
+   - Exposes statistics (e.g., total greetings generated, most active user).
+4. **Interfaces:**
+   - Command Line Interface (CLI): `awkit greet --name=Alice`
+   - REST API endpoint: `GET /api/greet?name=Alice&lang=vi`
+
+## 5. Non-Functional Requirements
+- **Performance:** Response time for greeting generation under 50ms.
+- **Reliability:** Storage fallback to memory if database/file storage is offline.
+- **Extensibility:** Easy configuration to add new languages.
+
+## 6. System Flow & Sequence Diagram
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant Client as CLI / API Client
+    participant Engine as Greeting Engine
+    participant DB as Storage / History DB
+
+    User->>Client: Triggers greeting command/request (name, lang)
+    Client->>Engine: Resolve greeting configuration
+    Engine->>Engine: Validate input & detect Time of Day
+    Engine->>DB: Log transaction (user, time, format)
+    DB-->>Engine: Log confirmation
+    Engine->>Client: Return formatted greeting string
+    Client->>User: Display greeting output
+```

package/docs/history/memoizedfibonacci_spec.v1.md

@@ -0,0 +1,127 @@
+# Technical Specification — MemoizedFibonacci
+
+## Revision History
+
+| Version | Date | Author | Description |
+| :--- | :--- | :--- | :--- |
+| 1.0 | 2026-06-22 | Antigravity Orchestrator | Initial technical design with Mermaid diagram, class architecture, and caching strategy. |
+
+---
+
+## 1. System Architecture
+
+The `MemoizedFibonacci` feature consists of three primary layers:
+1. **API & Interface Layer:** Exposes synchronous and asynchronous methods to users.
+2. **LRU Cache Layer:** Manages in-memory storage of computed sequences with automatic eviction based on Least Recently Used patterns.
+3. **Computation Engine:** Performs iterative sequence calculations to prevent call stack overflow, handles dynamic upgrading to `BigInt` for large numbers, and schedules asynchronous chunks for heavy inputs.
+
+---
+
+## 2. API Design & Core Interface
+
+```typescript
+interface FibonacciConfig {
+  maxCacheSize?: number;      // Maximum number of entries in the cache (default: 1000)
+  useBigInt?: boolean;        // Force BigInt computation even for small inputs (default: false)
+  asyncThreshold?: number;    // Input size to trigger asynchronous execution (default: 50000)
+}
+
+interface CacheStats {
+  hits: number;
+  misses: number;
+  size: number;
+  evictions: number;
+}
+
+class MemoizedFibonacci {
+  private cache: Map<number, number | bigint>;
+  private lruList: number[]; // Tracks usage order (least recently used at the front)
+  private config: Required<FibonacciConfig>;
+  private stats: CacheStats;
+
+  constructor(config?: FibonacciConfig);
+
+  /**
+   * Calculates Fibonacci of n. Automatically picks sync/async mode based on threshold.
+   */
+  public async calculate(n: number): Promise<number | bigint>;
+
+  /**
+   * Synchronously calculates Fibonacci of n.
+   * Throws warning/error if n is larger than asyncThreshold.
+   */
+  public calculateSync(n: number): number | bigint;
+
+  /**
+   * Retreives cache usage statistics.
+   */
+  public getStats(): CacheStats;
+
+  /**
+   * Clears all cache entries and metrics.
+   */
+  public clearCache(): void;
+
+  /**
+   * Private helper implementing iterative Fibonacci sequence.
+   */
+  private computeIterative(n: number, isBigInt: boolean): number | bigint;
+}
+```
+
+---
+
+## 3. Detailed Logic Flow (Mermaid Diagram)
+
+The following diagram illustrates the routing, validation, precision selection, and caching logic:
+
+```mermaid
+graph TD
+    A[Start: Calculate F(n)] --> B{Validate input n >= 0}
+    B -- No --> C[Throw Error: Invalid Input]
+    B -- Yes --> D{Check Cache for n}
+    D -- Hit (Yes) --> E[Update LRU Order]
+    E --> F[Return Cached Value]
+    D -- Miss (No) --> G{Check Precision Mode: n > 78 or useBigInt}
+    G -- Standard Number (n <= 78) --> H[Compute using standard arithmetic]
+    G -- BigInt (n > 78) --> I{Is n >= asyncThreshold?}
+    I -- No (Sync BigInt) --> J[Compute iteratively using BigInt]
+    I -- Yes (Async BigInt) --> K[Offload computation to worker thread / chunked loop]
+    K --> L[Iterate asynchronously without blocking event loop]
+    H --> M[Store Result in Cache]
+    J --> M
+    L --> M
+    M --> N{Cache Size > maxCacheSize?}
+    N -- Yes --> O[Evict Least Recently Used entry]
+    O --> P[Return Computed Result]
+    N -- No --> P
+```
+
+---
+
+## 4. Key Implementation Mechanics
+
+### 4.1 LRU Eviction Implementation
+To avoid linear scanning for evictions, the cache is backed by:
+- A `Map` mapping `n` to the value (either `Number` or `BigInt`).
+- A doubly-linked list or ordered array (`lruList`) tracking usage keys. On a cache hit, the key is moved to the end. On a cache insertion, if the map exceeds `maxCacheSize`, the key at the front of `lruList` is deleted from both the list and the map.
+
+### 4.2 Precision Safeguards
+- **Standard Float Limits:** Standard numbers in JavaScript lose precision above $F(78)$ ($F(78) = 8944394323791464$, whereas $F(79) = 14472334024559020$ which exceeds `Number.MAX_SAFE_INTEGER`).
+- **Automatic BigInt Upgrade:** If the class configuration is not explicitly set, inputs $n \ge 79$ automatically upgrade execution to `BigInt` mode.
+
+### 4.3 Async Slicing / Non-blocking Loop
+For large values of $n$ (e.g. $n \ge 500,000$), calculating Fibonacci in a single synchronous loop blocks the JS single-threaded event loop for several milliseconds. The `MemoizedFibonacci` class handles this via:
+- **Chunked execution:** Splitting the loop into chunks of 10,000 iterations and yielding back control using `setImmediate` or `setTimeout(..., 0)` to allow standard event-loop ticks to execute.
+- Alternatively, utilizing **Worker Threads** via `node:worker_threads` for CPU offloading in Node.js environments.
+
+---
+
+## 5. Error Handling & Edge Cases
+
+| Condition | System Response |
+| :--- | :--- |
+| Negative Input ($n < 0$) | Throws `RangeError: Input must be a non-negative integer.` |
+| Floating point Input (e.g., $n = 3.5$) | Automatically truncated using `Math.floor(n)` with a console warning, or throws a `TypeError`. |
+| Out of Memory Risk ($n > 1,000,000$) | Rejects promise with a warning about resource exhaustion unless a `force` flag is set. |
+| Cache Collision (Standard vs BigInt) | Values in cache are stored with consistent type based on configuration to avoid mixed-type arithmetic downstream. |

package/docs/specs/greetingapp_spec.md

@@ -0,0 +1,97 @@
+# Technical Specification - GreetingApp
+
+## Revision History
+| Version | Date | Description | Author |
+|---|---|---|---|
+| v1.0 | 2026-06-22 | Technical specification for GreetingApp | Antigravity Orchestrator |
+
+---
+
+## 1. System Architecture
+The GreetingApp consists of three major components:
+1. **Greeting Engine (Core):** Performs validation, detects time-of-day categories, maps to localization files, and builds the string.
+2. **Storage Layer:** A lightweight JSON/SQLite file logger to record history.
+3. **Interfaces:**
+   - CLI Controller: Handles flags and standard output formatting.
+   - REST Controller: Express.js routes and JSON responses.
+
+## 2. Detailed Component Specs
+
+### 2.1 Greeting Engine (`core/GreetingEngine`)
+- **Input:**
+  - `name`: string (optional, default: "Guest")
+  - `lang`: string (optional, default: "en")
+  - `timezone`: string (optional, default: system timezone)
+- **Time Periods:**
+  - `Morning`: 05:00 - 11:59
+  - `Afternoon`: 12:00 - 17:59
+  - `Evening`: 18:00 - 21:59
+  - `Night`: 22:00 - 04:59
+- **Localization Files (`locales/*.json`):**
+  - Example `en.json`:
+    ```json
+    {
+      "morning": "Good morning, {name}!",
+      "afternoon": "Good afternoon, {name}!",
+      "evening": "Good evening, {name}!",
+      "night": "Good night, {name}!"
+    }
+    ```
+
+### 2.2 Storage Schema
+A SQLite or JSON lines file containing:
+- `id`: UUID / Auto-increment integer
+- `name`: String
+- `language`: String
+- `timestamp`: ISO-8601 string
+- `greeting_message`: String
+
+## 3. Interface Design
+
+### 3.1 CLI Interface
+`awkit greet [options]`
+- `--name, -n`: Name of the user to greet.
+- `--lang, -l`: Language code (en, vi, ja).
+- `--help, -h`: Show usage description.
+
+### 3.2 REST API Specification
+`GET /api/greet`
+- **Query Parameters:**
+  - `name` (string)
+  - `lang` (string)
+- **Response (200 OK):**
+  - Content-Type: `application/json`
+  - Body:
+    ```json
+    {
+      "status": "success",
+      "data": {
+        "message": "Good morning, Alice!",
+        "name": "Alice",
+        "lang": "en",
+        "timestamp": "2026-06-22T05:35:15Z"
+      }
+    }
+    ```
+
+## 4. Error Handling
+- **Invalid Language:** Fallback to `en` and log warning.
+- **Invalid Input characters:** Sanitize inputs to prevent command line injection or XSS (on API side).
+
+## 5. Flow Diagram
+```mermaid
+graph TD
+    A[Start Request] --> B{Validate Inputs}
+    B -- Invalid --> C[Use Defaults: Guest/en]
+    B -- Valid --> D[Resolve User Local Time]
+    C --> D
+    D --> E{Determine Time of Day}
+    E -->|05:00-11:59| F[Morning Template]
+    E -->|12:00-17:59| G[Afternoon Template]
+    E -->|18:00-21:59| H[Evening Template]
+    E -->|22:00-04:59| I[Night Template]
+    F & G & H & I --> J[Replace {name} in Template]
+    J --> K[Log Transaction to History DB]
+    K --> L[Format Output CLI/REST]
+    L --> M[End Request]
+```

package/docs/specs/memoizedfibonacci_spec.md

@@ -0,0 +1,211 @@
+# Technical Specification — MemoizedFibonacci
+
+## Revision History
+
+| Version | Date | Author | Description |
+| :--- | :--- | :--- | :--- |
+| 1.0 | 2026-06-22 | Antigravity Orchestrator | Initial technical design with Mermaid diagram, class architecture, and caching strategy. |
+| 1.1 | 2026-06-22 | Antigravity Orchestrator | Refined LRU caching mechanism using ES6 Map insertion ordering. Added explicit detail on Async Slicing and Testing Strategy. |
+
+---
+
+## 1. System Architecture
+
+The `MemoizedFibonacci` feature consists of three primary layers:
+1. **API & Interface Layer:** Exposes synchronous and asynchronous methods to users.
+2. **LRU Cache Layer:** Manages in-memory storage of computed sequences with automatic eviction based on Least Recently Used patterns.
+3. **Computation Engine:** Performs iterative sequence calculations to prevent call stack overflow, handles dynamic upgrading to `BigInt` for large numbers, and schedules asynchronous chunks for heavy inputs.
+
+---
+
+## 2. API Design & Core Interface
+
+```typescript
+interface FibonacciConfig {
+  maxCacheSize?: number;      // Maximum number of entries in the cache (default: 1000)
+  useBigInt?: boolean;        // Force BigInt computation even for small inputs (default: false)
+  asyncThreshold?: number;    // Input size to trigger asynchronous execution (default: 50000)
+}
+
+interface CacheStats {
+  hits: number;
+  misses: number;
+  size: number;
+  evictions: number;
+}
+
+class MemoizedFibonacci {
+  // Built-in ES6 Map maintains insertion order.
+  // By deleting and re-inserting a key on access, the most recently used keys move to the end.
+  // The first key in map.keys() represents the Least Recently Used (LRU) element.
+  private cache: Map<number, number | bigint>;
+  private config: Required<FibonacciConfig>;
+  private stats: CacheStats;
+
+  constructor(config?: FibonacciConfig);
+
+  /**
+   * Calculates Fibonacci of n. Automatically picks sync/async mode based on threshold.
+   * Returns a Promise resolving to number or bigint.
+   */
+  public calculate(n: number): Promise<number | bigint>;
+
+  /**
+   * Synchronously calculates Fibonacci of n.
+   * Throws RangeError if n exceeds asyncThreshold to protect the thread.
+   */
+  public calculateSync(n: number): number | bigint;
+
+  /**
+   * Checks if the value for n is currently cached.
+   */
+  public isCached(n: number): boolean;
+
+  /**
+   * Dynamically updates the cache capacity limit. Evicts items if size exceeds new limit.
+   */
+  public setMaxCacheSize(size: number): void;
+
+  /**
+   * Retrieves cache usage statistics.
+   */
+  public getStats(): CacheStats;
+
+  /**
+   * Clears all cache entries and resets statistics.
+   */
+  public clearCache(): void;
+
+  /**
+   * Internal helper implementing iterative computation.
+   */
+  private computeIterative(n: number, isBigInt: boolean): number | bigint;
+
+  /**
+   * Internal helper performing non-blocking chunked computation.
+   */
+  private computeAsyncChunked(n: number, chunkSize: number): Promise<bigint>;
+}
+```
+
+---
+
+## 3. Detailed Logic Flow (Mermaid Diagram)
+
+The following diagram illustrates the routing, validation, precision selection, and caching logic:
+
+```mermaid
+graph TD
+    A[Start: Calculate F(n)] --> B{Validate input n >= 0}
+    B -- No --> C[Throw RangeError: Invalid Input]
+    B -- Yes --> D{Check Cache for n}
+    
+    D -- Hit (Yes) --> E[Update Map Insertion Order: Delete & Re-insert]
+    E --> F[Increment Hit Metric]
+    F --> G[Return Cached Value]
+    
+    D -- Miss (No) --> H[Increment Miss Metric]
+    H --> I{Check Precision Mode: n > 78 or useBigInt}
+    
+    I -- Standard Number (n <= 78) --> J[Compute iteratively using standard Number]
+    I -- BigInt (n > 78) --> K{Is n >= asyncThreshold?}
+    
+    K -- No (Sync BigInt) --> L[Compute iteratively using BigInt]
+    K -- Yes (Async BigInt) --> M[Invoke computeAsyncChunked]
+    
+    M --> N[Loop in chunks of size 10,000 using setImmediate]
+    N --> O[Yield control back to Event Loop after each chunk]
+    
+    J --> P[Store Result in Cache]
+    L --> P
+    O --> P
+    
+    P --> Q{Cache Size > maxCacheSize?}
+    Q -- Yes --> R[Evict map.keys.next.value oldest entry]
+    R --> S[Increment Eviction Metric]
+    S --> T[Return Computed Result]
+    Q -- No --> T
+```
+
+---
+
+## 4. Key Implementation Mechanics
+
+### 4.1 LRU Eviction Implementation (ES6 Map)
+Instead of managing a separate `lruList` array (which incurs $O(N)$ lookup/splice operations), the implementation relies entirely on the ordered property of JavaScript's `Map`.
+* **Read (Cache Hit):**
+  ```javascript
+  const value = this.cache.get(key);
+  this.cache.delete(key);
+  this.cache.set(key, value); // Re-inserts at the end of the Map
+  ```
+* **Write (Cache Miss & Capacity Exceeded):**
+  ```javascript
+  this.cache.set(key, value);
+  if (this.cache.size > this.config.maxCacheSize) {
+    const oldestKey = this.cache.keys().next().value;
+    this.cache.delete(oldestKey); // Deletes the oldest insertion
+    this.stats.evictions++;
+  }
+  ```
+This architecture yields highly efficient $O(1)$ operations for both cache lookup and replacement.
+
+### 4.2 Precision Safeguards & Double Limits
+- **Standard Float Limits:** Standard numbers in JavaScript lose precision above $F(78)$ ($F(78) = 8944394323791464$, whereas $F(79) = 14472334024559020$ which exceeds `Number.MAX_SAFE_INTEGER`).
+- **Automatic BigInt Upgrade:** If the class configuration is not explicitly set, inputs $n \ge 79$ automatically upgrade execution to `BigInt` mode.
+
+### 4.3 Async Slicing / Non-blocking Loop
+For large values of $n$ (e.g. $n \ge 100,000$), calculating Fibonacci in a single synchronous loop blocks the JS single-threaded event loop.
+We employ a chunked calculation pattern:
+```javascript
+private async computeAsyncChunked(n: number, chunkSize: number = 10000): Promise<bigint> {
+  let prev = 0n;
+  let curr = 1n;
+  let i = 2;
+
+  const runChunk = (): Promise<bigint> => {
+    return new Promise((resolve) => {
+      setImmediate(() => {
+        const target = Math.min(i + chunkSize, n + 1);
+        for (; i < target; i++) {
+          const next = prev + curr;
+          prev = curr;
+          curr = next;
+        }
+        if (i <= n) {
+          resolve(runChunk()); // Recursively queue the next chunk
+        } else {
+          resolve(curr);
+        }
+      });
+    });
+  };
+
+  return runChunk();
+}
+```
+
+---
+
+## 5. Error Handling & Edge Cases
+
+| Condition | System Response |
+| :--- | :--- |
+| Negative Input ($n < 0$) | Throws `RangeError: Input must be a non-negative integer.` |
+| Floating point Input (e.g., $n = 3.5$) | Throws `TypeError: Input must be an integer.` |
+| Maximum Guardrail Breach ($n > 1,000,000$) | Throws `RangeError: Calculation size exceeds maximum guardrail of 1,000,000.` |
+| Sync Call beyond Threshold ($n > asyncThreshold$) | Throws `RangeError: Input exceeds asyncThreshold. Use calculate() instead.` |
+
+---
+
+## 6. Testing Strategy
+
+### 6.1 Unit Tests
+* **Core Calculations:** Verify $F(0) = 0$, $F(1) = 1$, $F(10) = 55$, and $F(78) = 8944394323791464$.
+* **BigInt Accuracy:** Verify $F(79)$ is correctly calculated as `14472334024559020n` (with tailing `n` specifying bigint).
+* **Caching Performance:** Retrieve $F(50)$ twice. The second call must trigger a cache hit and have a latency under 1 microsecond.
+* **LRU Eviction:** Set cache limit to 3. Populate cache with keys 1, 2, 3. Read key 1 (making it most recently used). Insert key 4. Verify key 2 is evicted.
+
+### 6.2 Performance & Memory Benchmarks
+* **Sync vs Async Threshold:** Test the threshold boundary. Verify that calling `calculate(49999)` completes synchronously within milliseconds, and `calculate(50001)` returns a Promise and yields event loop control.
+* **Leak Testing:** Execute calculation loop of random values up to $n = 10,000$ for 100,000 iterations. Verify heap memory remains flat (no leakage outside the bounds of `maxCacheSize`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leejungkiin/awkit",
-  "version": "1.7.4",
+  "version": "1.7.5",
   "description": "Antigravity Workflow Kit v1.6 Unified AI agent orchestration system with Mindful Checkpoints.",
   "main": "bin/awk.js",
   "private": false,