@fjell/core 4.4.12 → 4.4.16

package/docs/public/api.md

@@ -1,230 +0,0 @@
-# Fjell Core API Reference
-
-Complete API documentation for all Fjell Core modules and exports.
-
-## Overview
-
-Fjell Core provides a comprehensive set of tools for item management, key utilities, and service coordination. All APIs are built with TypeScript-first design for maximum type safety.
-
-## Core Exports
-
-### Factory Classes
-
-#### `IFactory<V, S, L1, L2, L3, L4, L5>`
-Generic item factory for creating strongly-typed items with hierarchical key support.
-
-**Type Parameters:**
-- `V extends Item<S, L1, L2, L3, L4, L5>`: The item type being created
-- `S extends string`: Primary key type
-- `L1-L5 extends string`: Location key types (optional)
-
-**Constructor:**
-```typescript
-new IFactory<V, S, L1, L2, L3, L4, L5>(props?: Record<string, any>)
-```
-
-**Methods:**
-
-##### `addRef(item: Item, name?: string): IFactory`
-Adds a reference to another item.
-
-**Parameters:**
-- `item`: The item to reference
-- `name`: Optional reference name (defaults to primary type)
-
-**Returns:** Factory instance for chaining
-
-##### `static addRef<V, S, L1, L2, L3, L4, L5>(item: V, name?: string): IFactory`
-Static method to create a factory with a reference.
-
-##### `addDefaultEvents(): IFactory`
-Adds default event timestamps (created, updated).
-
-**Returns:** Factory instance for chaining
-
-#### `IQFactory`
-Factory for building item queries with filtering, sorting, and pagination.
-
-### Utility Classes
-
-#### `KUtils`
-Comprehensive key management utilities for hierarchical key operations.
-
-**Methods:**
-
-##### `createNormalizedHashFunction<T>(): (key: T) => string`
-Creates a normalized hash function for consistent key comparison.
-
-**Returns:** Hash function that normalizes pk/lk values to strings
-
-##### `normalizeKeyValue(value: string | number): string`
-Normalizes key values for consistent comparison.
-
-**Parameters:**
-- `value`: The value to normalize
-
-**Returns:** String representation of the value
-
-##### `primaryType(key: ComKey | PriKey): string`
-Extracts the primary type from a composite or primary key.
-
-### Service Classes
-
-#### `AItemService<S, L1, L2, L3, L4, L5>`
-Abstract base class for building domain-specific item services.
-
-**Type Parameters:**
-- `S extends string`: Primary key type
-- `L1-L5 extends string`: Location key types (hierarchical)
-
-**Constructor:**
-```typescript
-new AItemService<S, L1, L2, L3, L4, L5>(
-  pkType: S,
-  parentService?: AItemService<L1, L2, L3, L4, L5, never>
-)
-```
-
-**Parameters:**
-- `pkType`: The primary key type for this service
-- `parentService`: Optional parent service for hierarchical structures
-
-**Methods:**
-
-##### `getPkType(): S`
-Gets the primary key type for this service.
-
-**Returns:** The primary key type string
-
-##### `getKeyTypes(): AllItemTypeArrays<S, L1, L2, L3, L4, L5>`
-Gets all key types managed by this service, including parent service types.
-
-**Returns:** Array of all key type strings in the hierarchy
-
-## Type Definitions
-
-### Key Types
-
-#### `PriKey<S>`
-Primary key structure for items.
-
-#### `ComKey<S, L1, L2, L3, L4, L5>`
-Composite key structure supporting hierarchical locations.
-
-#### `LocKey`
-Location key for hierarchical positioning.
-
-#### `LocKeyArray`
-Array of location keys for complex hierarchies.
-
-### Item Types
-
-#### `Item<S, L1, L2, L3, L4, L5>`
-Base item interface with hierarchical key support.
-
-**Properties:**
-- `key`: The item's key (PriKey or ComKey)
-- `refs?`: Optional references to other items
-- `events?`: Optional event timestamps
-
-### Query Types
-
-#### `ItemQuery<S, L1, L2, L3, L4, L5>`
-Query structure for filtering and retrieving items.
-
-## Utility Functions
-
-### Dictionary Operations
-Exported from `dictionary` module for key-value operations with normalized hashing.
-
-### Key Operations
-Exported from `keys` module for advanced key manipulation and validation.
-
-### Item Operations
-Exported from `items` module for item creation, validation, and transformation.
-
-## Query Building
-
-### IQFactory
-Factory for building complex queries:
-
-```typescript
-const query = IQFactory.create('user')
-  .where('status', 'active')
-  .where('role', 'admin')
-  .limit(10)
-  .orderBy('createdAt', 'desc')
-```
-
-### IQUtils
-Utilities for executing and optimizing queries.
-
-### IUtils
-General item utilities for validation, transformation, and manipulation.
-
-## Best Practices
-
-### Type Safety
-Always use generic type parameters to ensure compile-time type checking:
-
-```typescript
-interface User {
-  id: string
-  name: string
-  email: string
-}
-
-const userFactory = new IFactory<User, 'user'>()
-const user = userFactory.create({ id: '123', name: 'John', email: 'john@example.com' })
-```
-
-### Hierarchical Keys
-Use the hierarchical key system for complex data relationships:
-
-```typescript
-class UserService extends AItemService<'user', 'organization'> {
-  constructor(orgService: OrganizationService) {
-    super('user', orgService)
-  }
-}
-```
-
-### Key Normalization
-Use normalized hash functions for consistent key comparison:
-
-```typescript
-const hashFn = KUtils.createNormalizedHashFunction<ComKey<'user', 'org'>>()
-const hash = hashFn(userKey)
-```
-
-## Error Handling
-
-All methods may throw validation errors or type mismatches. Always wrap operations in try-catch blocks for production code:
-
-```typescript
-try {
-  const item = factory.create(data)
-  const key = KUtils.generateKey(components)
-} catch (error) {
-  console.error('Operation failed:', error.message)
-}
-```
-
-## Performance Considerations
-
-- Use normalized hash functions for efficient key comparisons
-- Leverage hierarchical services for organized data access
-- Implement proper query optimization using IQUtils
-- Consider memory usage with large item collections
-
-## Integration
-
-Fjell Core is designed to integrate seamlessly with the entire Fjell ecosystem:
-
-- **@fjell/registry**: Service location and dependency injection
-- **@fjell/cache**: High-performance caching with key-based operations
-- **@fjell/lib**: Database abstraction layers
-- **@fjell/providers**: React state management
-- **@fjell/client-api**: HTTP client utilities
-
-Each integration maintains the same type safety and hierarchical key principles established in Fjell Core.

package/docs/public/basic-usage.ts

@@ -1,293 +0,0 @@
-/**
- * Basic Usage Example - Fjell Core
- *
- * This example demonstrates the fundamental operations available in Fjell Core:
- * - Item creation with IFactory
- * - Key generation and manipulation with KUtils
- * - Basic service implementation with AItemService
- */
-
-import { AItemService, IFactory, KUtils } from '@fjell/core'
-
-// Define our data types
-interface User {
-  id: string
-  name: string
-  email: string
-  createdAt: string
-  status: 'active' | 'inactive'
-}
-
-interface Product {
-  id: string
-  name: string
-  price: number
-  category: string
-  inStock: boolean
-}
-
-/**
- * 1. ITEM CREATION WITH IFACTORY
- *
- * IFactory provides type-safe item creation with validation and defaults.
- */
-console.log('=== Item Creation Examples ===')
-
-// Create a user item
-const user = IFactory.create<User>('user', {
-  id: 'user-123',
-  name: 'John Doe',
-  email: 'john.doe@example.com',
-  createdAt: new Date().toISOString(),
-  status: 'active'
-})
-
-console.log('Created user:', user)
-
-// Create a product item
-const product = IFactory.create<Product>('product', {
-  id: 'prod-456',
-  name: 'Wireless Headphones',
-  price: 199.99,
-  category: 'Electronics',
-  inStock: true
-})
-
-console.log('Created product:', product)
-
-/**
- * 2. KEY MANAGEMENT WITH KUTILS
- *
- * KUtils provides hierarchical key generation and manipulation utilities.
- */
-console.log('\n=== Key Management Examples ===')
-
-// Generate hierarchical keys
-const userKey = KUtils.generateKey(['users', user.id])
-const userProfileKey = KUtils.generateKey(['users', user.id, 'profile'])
-const userOrdersKey = KUtils.generateKey(['users', user.id, 'orders'])
-
-console.log('User key:', userKey)
-console.log('User profile key:', userProfileKey)
-console.log('User orders key:', userOrdersKey)
-
-// Parse keys back to components
-const userKeyComponents = KUtils.parseKey(userKey)
-const profileKeyComponents = KUtils.parseKey(userProfileKey)
-
-console.log('User key components:', userKeyComponents)
-console.log('Profile key components:', profileKeyComponents)
-
-// Validate keys
-const isValidUserKey = KUtils.isValidKey(userKey)
-const isValidInvalidKey = KUtils.isValidKey('invalid::key::format')
-
-console.log('User key is valid:', isValidUserKey)
-console.log('Invalid key is valid:', isValidInvalidKey)
-
-// Get parent keys
-const parentOfProfile = KUtils.getParentKey(userProfileKey)
-console.log('Parent of profile key:', parentOfProfile)
-
-/**
- * 3. SERVICE LAYER WITH AITEMSERVICE
- *
- * AItemService provides an abstract base for building domain services.
- */
-console.log('\n=== Service Layer Examples ===')
-
-class UserService extends AItemService {
-  private users = new Map<string, User>()
-
-  async create(userData: Partial<User>): Promise<User> {
-    console.log('Creating user with data:', userData)
-
-    // Create user with IFactory
-    const user = IFactory.create<User>('user', {
-      id: this.generateId(),
-      createdAt: new Date().toISOString(),
-      status: 'active',
-      ...userData
-    })
-
-    // Validate the user
-    await this.validate(user)
-
-    // Save the user
-    await this.save(user)
-
-    console.log('User created successfully:', user.id)
-    return user
-  }
-
-  async findById(id: string): Promise<User | null> {
-    const key = KUtils.generateKey(['users', id])
-    const user = this.users.get(key)
-    console.log(`Finding user by ID ${id}:`, user ? 'found' : 'not found')
-    return user || null
-  }
-
-  async updateStatus(id: string, status: User['status']): Promise<User | null> {
-    const user = await this.findById(id)
-    if (!user) {
-      console.log(`User ${id} not found for status update`)
-      return null
-    }
-
-    const updatedUser = { ...user, status }
-    await this.save(updatedUser)
-
-    console.log(`User ${id} status updated to ${status}`)
-    return updatedUser
-  }
-
-  async listActiveUsers(): Promise<User[]> {
-    const activeUsers = Array.from(this.users.values())
-      .filter(user => user.status === 'active')
-
-    console.log(`Found ${activeUsers.length} active users`)
-    return activeUsers
-  }
-
-  protected async validate(user: User): Promise<void> {
-    if (!user.email || !user.email.includes('@')) {
-      throw new Error('Valid email is required')
-    }
-
-    if (!user.name || user.name.length < 2) {
-      throw new Error('Name must be at least 2 characters')
-    }
-
-    console.log('User validation passed for:', user.email)
-  }
-
-  protected async save(user: User): Promise<User> {
-    const key = KUtils.generateKey(['users', user.id])
-    this.users.set(key, user)
-    console.log('User saved with key:', key)
-    return user
-  }
-
-  private generateId(): string {
-    return `user-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`
-  }
-}
-
-// Demonstrate service usage
-async function demonstrateService() {
-  const userService = new UserService()
-
-  try {
-    // Create users
-    const user1 = await userService.create({
-      name: 'Alice Smith',
-      email: 'alice.smith@example.com'
-    })
-
-    const user2 = await userService.create({
-      name: 'Bob Johnson',
-      email: 'bob.johnson@example.com'
-    })
-
-    // Find users
-    const foundUser = await userService.findById(user1.id)
-    console.log('Found user:', foundUser?.name)
-
-    // Update user status
-    await userService.updateStatus(user2.id, 'inactive')
-
-    // List active users
-    const activeUsers = await userService.listActiveUsers()
-    console.log('Active users:', activeUsers.map(u => u.name))
-
-  } catch (error) {
-    console.error('Service error:', error.message)
-  }
-}
-
-/**
- * 4. PRACTICAL INTEGRATION EXAMPLE
- *
- * Combining all concepts in a realistic scenario.
- */
-console.log('\n=== Integration Example ===')
-
-class OrderService extends AItemService {
-  private orders = new Map<string, any>()
-
-  constructor(private userService: UserService) {
-    super()
-  }
-
-  async createOrder(userId: string, items: any[]): Promise<any> {
-    // Verify user exists
-    const user = await this.userService.findById(userId)
-    if (!user) {
-      throw new Error(`User ${userId} not found`)
-    }
-
-    // Create order
-    const order = IFactory.create('order', {
-      id: this.generateOrderId(),
-      userId,
-      items,
-      total: this.calculateTotal(items),
-      status: 'pending',
-      createdAt: new Date().toISOString()
-    })
-
-    // Save order
-    const orderKey = KUtils.generateKey(['orders', order.id])
-    this.orders.set(orderKey, order)
-
-    console.log(`Order ${order.id} created for user ${user.name}`)
-    return order
-  }
-
-  private generateOrderId(): string {
-    return `order-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`
-  }
-
-  private calculateTotal(items: any[]): number {
-    return items.reduce((total, item) => total + (item.price * item.quantity), 0)
-  }
-}
-
-async function demonstrateIntegration() {
-  const userService = new UserService()
-  const orderService = new OrderService(userService)
-
-  try {
-    // Create a user
-    const user = await userService.create({
-      name: 'Customer One',
-      email: 'customer@example.com'
-    })
-
-    // Create an order for the user
-    const order = await orderService.createOrder(user.id, [
-      { name: 'Product A', price: 29.99, quantity: 2 },
-      { name: 'Product B', price: 15.50, quantity: 1 }
-    ])
-
-    console.log('Integration completed successfully')
-    console.log('Order total:', order.total)
-
-  } catch (error) {
-    console.error('Integration error:', error.message)
-  }
-}
-
-// Run all demonstrations
-async function runExamples() {
-  await demonstrateService()
-  await demonstrateIntegration()
-  console.log('\n=== All examples completed ===')
-}
-
-// Execute if running directly
-if (require.main === module) {
-  runExamples().catch(console.error)
-}
-
-export { UserService, OrderService }

package/docs/public/examples-README.md

@@ -1,147 +0,0 @@
-# Fjell Core Examples
-
-This directory contains comprehensive examples demonstrating real-world usage patterns for Fjell Core.
-
-## Available Examples
-
-### Basic Examples
-
-#### [basic-usage.ts](./basic-usage.ts)
-Demonstrates fundamental Fjell Core operations:
-- Item creation with IFactory
-- Key generation and manipulation with KUtils
-- Basic service implementation with AItemService
-
-#### [service-patterns.ts](./service-patterns.ts)
-Shows common service implementation patterns:
-- Repository pattern implementation
-- Service composition
-- Error handling strategies
-
-#### [query-examples.ts](./query-examples.ts)
-Query building and execution examples:
-- Basic query construction
-- Complex filtering and sorting
-- Query optimization techniques
-
-### Advanced Examples
-
-#### [enterprise-example.ts](./enterprise-example.ts)
-Production-ready enterprise patterns:
-- Multi-layered service architecture
-- Transaction management
-- Comprehensive error handling
-- Performance optimization
-
-#### [testing-example.ts](./testing-example.ts)
-Testing strategies and utilities:
-- Unit testing with Fjell Core
-- Mock creation and management
-- Integration testing patterns
-
-## Running the Examples
-
-All examples are TypeScript files that can be run directly:
-
-```bash
-# Using ts-node
-npx ts-node examples/basic-usage.ts
-
-# Using tsx
-npx tsx examples/basic-usage.ts
-
-# Compile and run
-tsc examples/basic-usage.ts && node examples/basic-usage.js
-```
-
-## Prerequisites
-
-Make sure you have Fjell Core installed:
-
-```bash
-npm install @fjell/core
-```
-
-For the examples that integrate with databases or external services, you may need additional dependencies as noted in each example.
-
-## Example Structure
-
-Each example follows a consistent structure:
-
-1. **Imports**: Required Fjell Core modules
-2. **Type Definitions**: TypeScript interfaces and types
-3. **Implementation**: Core logic demonstration
-4. **Usage**: Practical usage examples
-5. **Output**: Expected results and explanations
-
-## Integration Examples
-
-Several examples show integration with popular libraries and frameworks:
-
-- Express.js web applications
-- Database ORMs (Sequelize, TypeORM)
-- Testing frameworks (Jest, Vitest)
-- React applications
-- GraphQL APIs
-
-## Best Practices
-
-The examples demonstrate Fjell Core best practices:
-
-- **Type Safety**: Comprehensive TypeScript usage
-- **Error Handling**: Robust error management
-- **Performance**: Optimized patterns for production
-- **Testing**: Comprehensive test coverage
-- **Documentation**: Clear code documentation
-
-## Contributing Examples
-
-We welcome new examples! Please follow these guidelines:
-
-1. Create a new TypeScript file with a descriptive name
-2. Include comprehensive comments explaining the concepts
-3. Add proper type definitions
-4. Include usage examples and expected output
-5. Update this README with a description of your example
-
-## Getting Help
-
-If you have questions about any example:
-
-1. Check the inline comments for explanations
-2. Review the main Fjell Core documentation
-3. Open an issue on GitHub for specific questions
-4. Join our community discussions
-
-## Common Patterns Demonstrated
-
-### Factory Pattern
-```typescript
-const user = IFactory.create<User>('user', userData)
-```
-
-### Repository Pattern
-```typescript
-class UserRepository extends AItemService {
-  async save(user: User): Promise<User> { ... }
-  async findById(id: string): Promise<User | null> { ... }
-}
-```
-
-### Service Layer
-```typescript
-class UserService extends AItemService {
-  constructor(private userRepo: UserRepository) { super() }
-  async registerUser(data: UserData): Promise<User> { ... }
-}
-```
-
-### Query Building
-```typescript
-const query = IQFactory.create('user')
-  .where('status', 'active')
-  .orderBy('createdAt', 'desc')
-  .limit(10)
-```
-
-These examples provide a solid foundation for building production applications with Fjell Core.

package/docs/public/fjell-icon.svg

@@ -1 +0,0 @@
-