axiodb 7.33.230 → 7.33.233

package/.antigravity/rules.md

@@ -0,0 +1,228 @@
+# Antigravity IDE Rules for AxioDB
+
+## Project Identity
+
+**AxioDB** - Embedded NoSQL database for Node.js
+- TypeScript strict mode → CommonJS
+- Node.js ≥20.0.0
+- Zero native dependencies
+- Singleton pattern, file-per-document storage
+
+## Agent Instructions
+
+### Planning Mode
+
+When in Planning Mode, create detailed task lists:
+1. Identify affected components
+2. Plan implementation approach
+3. List test requirements
+4. Document update requirements
+5. Build verification steps
+
+### Fast Mode
+
+For quick tasks, ensure:
+- Build after changes
+- No breaking existing tests
+- Follow existing patterns
+
+## Core Principles
+
+### 1. ALWAYS Build
+```bash
+npm run build  # After every code change
+```
+TypeScript errors in production are unacceptable.
+
+### 2. ALWAYS Test
+Update `Test/modules/` for ANY feature change:
+- `crud.test.js` - CRUD operations
+- `transaction.test.js` - Transactions, WAL
+- `read.test.js` - Read optimizations
+
+### 3. NEVER Incomplete
+Definition of "Done":
+- ✅ Code written
+- ✅ `npm run build` passes
+- ✅ Tests added/updated
+- ✅ `npm test` passes
+- ✅ Docs updated
+- ✅ No regressions
+
+### 4. SOLID + DRY
+- Single responsibility per class
+- Extract duplicated logic to helpers
+- No hacky solutions
+- Production-grade code only
+
+### 5. TypeScript Strict
+- No `any` types (use proper interfaces)
+- Null checks: `if (obj !== null)`
+- Type guards for unknown types
+- Enums or const objects (no magic strings)
+
+## Architecture Patterns
+
+### Singleton Pattern
+```typescript
+private static _instance: AxioDB;
+constructor() {
+  if (AxioDB._instance) throw new Error("Only one instance allowed");
+  AxioDB._instance = this;
+}
+```
+**Implication**: Tests must run in separate processes
+
+### Dual-Write (Indexes)
+```typescript
+// Memory (speed) + Disk (durability)
+await this.indexCache.set(key, data, TTL);
+await this.fileManager.writeFile(path, JSON.stringify(data));
+```
+
+### Random Cache TTL
+```typescript
+// 5-15 minutes (prevent cache stampede)
+const TTL = Math.floor(Math.random() * (15 - 5 + 1) + 5) * 60 * 1000;
+```
+
+### File Structure
+- Database: `{RootPath}/{DatabaseName}/`
+- Collection: `{DatabasePath}/{CollectionName}/`
+- Document: `{CollectionPath}/{documentId}.axiodb`
+
+## Module Organization
+
+```
+source/
+├── Services/          # Database, Collection, CRUD, Index, Transaction
+├── engine/           # FileManager, FolderManager
+├── server/           # HTTP GUI (Fastify, port 27018)
+├── tcp/              # TCP server (AxioDBCloud, port 27019)
+├── client/           # TCP client + Proxies
+├── Helper/           # Converter, Crypto, Response
+└── Memory/           # InMemoryCache
+
+Test/modules/         # Tests (separate processes)
+Document/             # React docs site
+```
+
+## Naming Conventions
+
+- **Files**: `{Feature}.operation.ts`, `{Feature}.service.ts`, `{Feature}.helper.ts`
+- **Classes**: PascalCase: `FileManager`, `QueryMatcher`
+- **Methods**: camelCase: `createDatabase()`, `isValidDocument()`
+- **Variables**: camelCase: `documentId`, `collectionPath`
+
+## Error Handling
+
+```typescript
+async function operation(): Promise<SuccessInterface | ErrorInterface> {
+  try {
+    const result = await this.execute();
+    return this.ResponseHelper.success(result);
+  } catch (error) {
+    this.logger.error('Operation failed', error);
+    return this.ResponseHelper.error('Failed', StatusCodes.ERROR);
+  }
+}
+```
+
+## Performance
+
+1. **Use InMemoryCache**: Check cache before disk reads
+2. **Batch operations**: `Promise.all` instead of sequential
+3. **Avoid unnecessary I/O**: Read once, process in memory
+4. **Use Map**: O(1) lookups vs Array O(n)
+
+## Security
+
+1. **Validate input**: Check types, reject arrays as documents
+2. **Sanitize paths**: `documentId.replace(/[^a-zA-Z0-9-_]/g, '_')`
+3. **Encrypt sensitive**: Use AES-256 for collections with sensitive data
+4. **No stack traces**: Return generic error messages to users
+
+## Documentation Requirements
+
+When adding/changing features, update:
+1. **README.md** - Public API, examples, features list
+2. **Document/** - React docs site (run `cd Document && npm run dev`)
+3. **Dockerfile** - If ports/env/commands change
+4. **JSDoc** - All public methods
+
+## Common Workflows
+
+### Add Collection Operation
+1. Edit `source/Services/Collection/collection.operation.ts`
+2. Add method with proper types, error handling
+3. Add to HTTP API: `source/server/router/` + `controller/`
+4. Add to TCP API: `source/tcp/handler/`
+5. Create tests in `Test/modules/crud.test.js`
+6. Update docs (README, Document/)
+7. Build: `npm run build && npm test`
+
+### Add TCP Command
+1. Create handler: `source/tcp/handler/{command}.ts`
+2. Add client proxy: `source/client/{Feature}Proxy.ts`
+3. Register in command map
+4. Add tests
+5. Update docs
+
+### Add Helper Utility
+1. Create: `source/Helper/{Feature}.helper.ts`
+2. Use static methods (stateless)
+3. Import in services that need it
+4. DRY principle - extract duplicated logic
+
+## Anti-Patterns to Avoid
+
+❌ Using `any` types
+❌ Duplicated code (copy-paste)
+❌ Sequential operations that could be parallel
+❌ Ignoring build errors
+❌ Skipping tests
+❌ Missing documentation
+❌ Hardcoded values (use constants/config)
+❌ Unclear variable names
+❌ Deep nesting (>3 levels)
+
+## Agent-Specific Tips
+
+### When Creating Features
+1. Read related files first
+2. Understand existing patterns
+3. Follow established architecture
+4. Test edge cases
+5. Document thoroughly
+
+### When Refactoring
+1. Ensure tests exist first
+2. Make changes incrementally
+3. Run tests after each change
+4. Verify no performance regression
+
+### When Fixing Bugs
+1. Write failing test first
+2. Fix the bug
+3. Verify test passes
+4. Check for similar issues elsewhere
+5. Document the fix
+
+## Multi-Agent Coordination
+
+If using parallel agents:
+- Assign different files/modules to each agent
+- Avoid concurrent edits to same file
+- Coordinate through planning artifacts
+- Merge changes carefully
+
+## Success Criteria
+
+Every task must meet ALL criteria:
+- Builds successfully
+- Tests pass
+- Docs updated
+- No regressions
+- Follows patterns
+- Security validated
+- Performance acceptable

package/.claude/SETTINGS.md

@@ -0,0 +1,161 @@
+# Claude Code Settings
+
+## Permissions Configuration
+
+### Allowed Commands
+
+**Build & Test:**
+- `npm run build`, `npm test`, `npm run lint`
+- `npm install`, `npm ci`
+- `npx tsc`, `npx eslint`
+- `node Test/*` - Run specific tests
+- `node -e` - Execute Node.js code
+
+**Git Operations:**
+- `git status`, `git diff`, `git log` - Read operations
+- `git add`, `git commit` - Stage and commit
+- `git push`, `git pull`, `git fetch` - Sync with remote
+- `git branch`, `git checkout`, `git merge` - Branch operations
+- `git stash` - Temporary storage
+- `gh pr`, `gh repo` - GitHub CLI (PRs, repo info)
+
+**Docker Commands:**
+- `docker build`, `docker run` - Build and run containers
+- `docker logs`, `docker exec` - Debugging
+- `docker ps`, `docker images` - List resources
+- `docker stop` - Stop containers (safe)
+
+**File Operations:**
+- `ls`, `cat`, `wc`, `grep` - Read operations
+- `find`, `tree`, `du` - Search and stats
+- `mkdir` - Create directories (safe)
+- `echo`, `pwd`, `which` - Info commands
+
+### Denied Commands (Security)
+
+**Destructive File Operations:**
+- `rm -rf`, `rm -fr`, `rm -r`, `rm -f` - Prevent accidental deletion
+- `chmod 777` - Prevent security issues
+- `chown` - Prevent ownership changes
+
+**Destructive Git Operations:**
+- `git push --force`, `git push -f` - Prevent force pushes
+- `git reset --hard` - Prevent hard resets
+- `git clean -fd` - Prevent untracked file deletion
+- `git branch -D` - Prevent force branch deletion
+
+**Destructive Docker Operations:**
+- `docker rm -f`, `docker rmi -f` - Prevent force removal
+- `docker system prune -af` - Prevent pruning all resources
+
+**Package Management:**
+- `npm uninstall`, `npm remove` - Prevent dependency removal
+- `npm publish` - Prevent accidental publishing
+
+**Security Risks:**
+- `sudo` - Prevent privilege escalation
+- `curl *| bash`, `wget *| sh` - Prevent script injection
+- `eval` - Prevent code injection
+- Disk operations (`> /dev/sda`, `dd if=`) - Prevent disk damage
+
+## Approval Requirements
+
+### Require User Approval For:
+- Editing config files: `package.json`, `tsconfig.json`, `.gitignore`, `Dockerfile`
+- Publishing: `git push`, `npm publish`, `docker push`
+
+### Auto-Approved (No Confirmation):
+- Reading files: `Read`, `Glob`, `Grep`
+- Building: `npm run build`
+- Testing: `npm test`
+- Linting: `npm run lint`
+- Git info: `git status`, `git diff`, `git log`
+
+## Development Rules
+
+**Enabled:**
+- `require_tests_for_features: true` - Tests mandatory for new features
+- `require_docs_for_features: true` - Docs mandatory for new features
+
+**Disabled (Manual Control):**
+- `auto_build_after_edit: false` - Don't auto-build (you control when)
+- `auto_test_after_build: false` - Don't auto-test (you control when)
+
+## AxioDB-Specific Rules
+
+**Enforced Patterns:**
+- `singleton_check: true` - Verify singleton pattern compliance
+- `test_isolation_required: true` - Tests must run in separate processes
+- `dual_write_pattern_enforced: true` - Indexes must write to memory + disk
+- `cache_ttl_random: true` - Cache TTL must be randomized (5-15min)
+
+## Why These Settings?
+
+### Safety First
+Prevents accidental destructive operations:
+- No `rm -rf` to delete entire directories
+- No `git push --force` to overwrite remote history
+- No `docker system prune -af` to remove all resources
+
+### Development Workflow
+Allows normal development tasks:
+- Build, test, lint freely
+- Commit and push safely
+- Run Docker containers for testing
+- Execute Node.js scripts
+
+### Quality Control
+Requires approval for critical changes:
+- Package.json modifications need review
+- Publishing requires confirmation
+- Config changes need approval
+
+### AxioDB Compliance
+Enforces project-specific patterns:
+- Singleton pattern verification
+- Test isolation (separate processes)
+- Dual-write pattern for indexes
+- Random cache TTL
+
+## Modifying Settings
+
+To add new allowed commands:
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(your-command:*)"
+    ]
+  }
+}
+```
+
+To deny additional commands:
+```json
+{
+  "permissions": {
+    "deny": [
+      "Bash(dangerous-command:*)"
+    ]
+  }
+}
+```
+
+## Emergency Override
+
+If you need to run a blocked command:
+1. Temporarily edit `.claude/settings.json`
+2. Add command to `allow` list
+3. Run the command
+4. Remove from `allow` list (restore safety)
+
+**Better approach**: Ask Claude to use alternative safe commands.
+
+## Summary
+
+This configuration provides:
+- ✅ Full development workflow access
+- ✅ Protection against destructive operations
+- ✅ Approval gates for critical changes
+- ✅ AxioDB pattern enforcement
+- ✅ Safe by default, flexible when needed

package/.claude/commands/build-check.md

@@ -0,0 +1,18 @@
+Build and verify the project for: $ARGUMENTS
+
+Execute in order:
+1. **TypeScript compilation**: `npm run build`
+2. **Lint check**: `npm run lint`
+3. **Type check**: `npx tsc --noEmit`
+
+If any step fails:
+- Show exact error messages with file paths and line numbers
+- Suggest specific fixes
+- Do NOT continue to next step until current step passes
+
+If all pass:
+- Report success
+- Show compiled output location (lib/)
+- Suggest running tests: `npm test`
+
+This is MANDATORY before declaring any task complete.

package/.claude/commands/collection-op.md

@@ -0,0 +1,53 @@
+Create new collection operation: $ARGUMENTS
+
+Location: `source/Services/Collection/collection.operation.ts`
+
+**Step 1: Add Method to Collection Class**
+```typescript
+/**
+ * Description of operation
+ * @param {Type} param - Parameter description
+ * @returns {Promise<SuccessInterface | ErrorInterface>} Result
+ */
+async operationName(param: Type): Promise<SuccessInterface | ErrorInterface> {
+  try {
+    // Validation
+    if (!param) {
+      return this.ResponseHelper.error('Invalid input', StatusCodes.BAD_REQUEST);
+    }
+
+    // Operation logic
+    const result = await this.performOperation(param);
+
+    // Cache update if needed
+    this.cache.invalidate(cacheKey);
+
+    return this.ResponseHelper.success(result);
+  } catch (error) {
+    this.logger.error('Operation failed', error);
+    return this.ResponseHelper.error('Operation failed', StatusCodes.INTERNAL_SERVER_ERROR);
+  }
+}
+```
+
+**Step 2: Add to HTTP API** (if needed)
+- Router: `source/server/router/Routers/Collection.routes.ts`
+- Controller: `source/server/controller/Collection/collection.controller.ts`
+
+**Step 3: Add to TCP API** (if needed)
+- Handler: `source/tcp/handler/`
+- Add command to protocol types
+
+**Step 4: Add Tests**
+- File: `Test/modules/crud.test.js` or relevant module
+- Test success, errors, edge cases
+
+**Step 5: Documentation**
+- Update README.md API Reference
+- Update Document/ with examples
+- Add JSDoc comments
+
+**Step 6: Build & Verify**
+```bash
+npm run build && npm test
+```

package/.claude/commands/docs.md

@@ -0,0 +1,49 @@
+Update documentation for: $ARGUMENTS
+
+**Step 1: README.md**
+- Location: Root `/README.md`
+- Update sections: Features, API Reference, Quick Start, Examples
+- Add version tag if new feature (e.g., "v5.33+")
+- Ensure examples are tested and working
+
+**Step 2: Document/ (React Docs Site)**
+```bash
+cd Document
+npm run dev  # Start at localhost:5173
+```
+- Create or update page in `src/pages/`
+- Add navigation links
+- Include:
+  - Overview (what, why)
+  - Quick start example
+  - Detailed usage
+  - API reference
+  - Best practices
+  - Common pitfalls
+- Test examples work
+- Build: `npm run build`
+
+**Step 3: Dockerfile** (if needed)
+- Update port numbers (EXPOSE)
+- Update environment variables (ENV)
+- Update comments explaining changes
+- Update volume mounts (VOLUME)
+
+**Step 4: JSDoc Comments**
+Add to all public methods:
+```typescript
+/**
+ * Method description
+ * @param {Type} paramName - Description
+ * @returns {Promise<Type>} Description
+ * @example
+ * const result = await method();
+ */
+```
+
+Verify:
+- [ ] README.md updated
+- [ ] Document/ updated and builds
+- [ ] Dockerfile updated (if relevant)
+- [ ] JSDoc added
+- [ ] Examples tested

package/.claude/commands/feature.md

@@ -0,0 +1,38 @@
+Implement new feature: $ARGUMENTS
+
+Follow AxioDB patterns:
+
+**Step 1: Plan**
+- Identify affected components (Collection, CRUD, Index, Transaction)
+- Choose appropriate location:
+  - Services/{category}/ for core operations
+  - Helper/ for utilities
+  - engine/ for file operations
+  - server/router/ + controller/ for HTTP API
+  - tcp/handler/ for TCP commands
+
+**Step 2: Implement**
+- Follow SOLID principles (single responsibility, dependency injection)
+- Use TypeScript strict mode (no `any` types)
+- Add proper error handling with ResponseHelper
+- Use InMemoryCache where appropriate
+- Follow dual-write pattern for indexes (memory + disk)
+
+**Step 3: Test**
+- Add tests to Test/modules/ (MANDATORY)
+- Test happy path, edge cases, errors
+- Run `npm run build && npm test`
+
+**Step 4: Document**
+- Update README.md (if public API)
+- Update Document/ folder (create/update page)
+- Update Dockerfile (if deployment-related)
+- Add JSDoc comments to public methods
+
+**Step 5: Verify**
+- Build passes: `npm run build`
+- Tests pass: `npm test`
+- Lint passes: `npm run lint`
+- Documentation builds: `cd Document && npm run build`
+
+Only mark complete when ALL steps are done.

package/.claude/commands/fix-build.md

@@ -0,0 +1,46 @@
+Fix build errors for: $ARGUMENTS
+
+**Step 1: Run Build**
+```bash
+npm run build
+```
+
+**Step 2: Analyze Errors**
+Common TypeScript errors in AxioDB:
+
+**Type Errors:**
+- `Type 'any' is not assignable` → Add proper interface
+- `Property does not exist` → Add to interface or check spelling
+- `Cannot find module` → Check import path (relative: ../, absolute: source/)
+- `Type 'X' is not assignable to type 'Y'` → Fix type mismatch
+
+**Import Errors:**
+- Missing imports → Add import statement
+- Circular dependencies → Refactor to break cycle
+- Wrong path → Verify file location in source/
+
+**Strict Mode Errors:**
+- `Object is possibly 'null'` → Add null check: `if (obj !== null)`
+- `Object is possibly 'undefined'` → Add undefined check or use `??`
+- `Parameter 'x' implicitly has 'any' type` → Add explicit type
+
+**Step 3: Fix Each Error**
+For each error:
+1. Note file path and line number
+2. Read surrounding code for context
+3. Apply fix following AxioDB patterns
+4. Verify fix doesn't break other code
+
+**Step 4: Verify**
+```bash
+npm run build    # Must pass
+npx tsc --noEmit # Type check
+npm run lint     # Lint check
+```
+
+**Step 5: Test**
+```bash
+npm test  # Ensure no regressions
+```
+
+Only mark complete when build succeeds with zero errors.

package/.claude/commands/helper.md

@@ -0,0 +1,67 @@
+Create new helper utility: $ARGUMENTS
+
+Location: `source/Helper/{FeatureName}.helper.ts`
+
+**Helper Pattern:**
+```typescript
+/**
+ * Helper class for {feature description}
+ */
+export class {FeatureName}Helper {
+  /**
+   * Method description
+   * @param {Type} param - Parameter description
+   * @returns {ReturnType} Return description
+   */
+  static methodName(param: Type): ReturnType {
+    // Pure function - no side effects
+    // Stateless - no instance variables
+    return result;
+  }
+}
+```
+
+**Guidelines:**
+- Use static methods (helpers are stateless)
+- Pure functions (same input = same output)
+- No dependencies on AxioDB instance
+- Single responsibility (one concern per helper)
+- Reusable across multiple services
+
+**Common Helper Types:**
+- **Data transformation**: `Converter.helper.ts`
+- **Validation**: `Validator.helper.ts`
+- **Encryption**: `Crypto.helper.ts`
+- **Formatting**: `Formatter.helper.ts`
+- **Query matching**: `QueryMatcher.helper.ts`
+
+**DRY Principle:**
+If the same logic appears in 2+ files, extract to a helper.
+
+**Example:**
+```typescript
+// Helper/QueryMatcher.helper.ts
+export class QueryMatcher {
+  static matchDocument(doc: any, query: any): boolean {
+    // Logic here
+    return matches;
+  }
+
+  static filterDocuments(docs: any[], query: any): any[] {
+    return docs.filter(d => this.matchDocument(d, query));
+  }
+}
+
+// Usage in Reader.operation.ts
+import { QueryMatcher } from '../Helper/QueryMatcher.helper';
+const filtered = QueryMatcher.filterDocuments(documents, query);
+```
+
+**Steps:**
+1. Create helper file in `source/Helper/`
+2. Implement static methods
+3. Add TypeScript interfaces for parameters
+4. Add JSDoc comments
+5. Import and use in relevant services
+6. Add tests (if complex logic)
+7. Build: `npm run build`