@fjell/core 4.4.7 → 4.4.12

package/docs/public/README.md

@@ -0,0 +1,227 @@
+# Fjell Core
+
+Core Item and Key Framework for Fjell - The foundational library that provides essential item management, key utilities, and service coordination for the entire Fjell ecosystem.
+
+## Features
+
+- **Type-safe item creation** with IFactory
+- **Hierarchical key management** with KUtils
+- **Abstract service layer** with AItemService
+- **Query building and execution** with IQFactory and IQUtils
+- **Comprehensive error handling** with custom error types
+- **Testing utilities** for robust test suites
+- **TypeScript-first design** for excellent developer experience
+
+## Installation
+
+```bash
+npm install @fjell/core
+```
+
+## Quick Start
+
+```typescript
+import { IFactory, KUtils, AItemService } from '@fjell/core'
+
+// Create items with the factory
+const user = IFactory.create('user', {
+  id: 'user-123',
+  name: 'John Doe',
+  email: 'john@example.com'
+})
+
+// Generate hierarchical keys
+const userKey = KUtils.generateKey(['users', user.id])
+
+// Build services
+class UserService extends AItemService {
+  async createUser(userData: any) {
+    const user = IFactory.create('user', userData)
+    await this.validate(user)
+    return this.save(user)
+  }
+}
+```
+
+## Core Modules
+
+### IFactory
+Factory for creating strongly-typed items with validation and defaults.
+
+```typescript
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+const user = IFactory.create<User>('user', {
+  id: 'user-123',
+  name: 'John Doe',
+  email: 'john@example.com'
+})
+```
+
+### KUtils
+Utilities for hierarchical key generation and manipulation.
+
+```typescript
+// Generate keys
+const userKey = KUtils.generateKey(['users', 'user-123'])
+const profileKey = KUtils.generateKey(['users', 'user-123', 'profile'])
+
+// Parse keys
+const components = KUtils.parseKey(userKey) // ['users', 'user-123']
+
+// Validate keys
+const isValid = KUtils.isValidKey(userKey) // true
+```
+
+### AItemService
+Abstract base class for building domain services with lifecycle management.
+
+```typescript
+class UserService extends AItemService {
+  async create(userData: Partial<User>): Promise<User> {
+    const user = IFactory.create<User>('user', userData)
+    await this.validate(user)
+    return this.save(user)
+  }
+
+  protected async validate(user: User): Promise<void> {
+    if (!user.email.includes('@')) {
+      throw new Error('Invalid email')
+    }
+  }
+}
+```
+
+### Query System
+Build and execute queries with IQFactory and IQUtils.
+
+```typescript
+const query = IQFactory.create('user')
+  .where('status', 'active')
+  .where('role', 'admin')
+  .orderBy('createdAt', 'desc')
+  .limit(10)
+
+const results = await IQUtils.execute(query)
+```
+
+## Architecture Philosophy
+
+Fjell Core is designed around **progressive enhancement**:
+
+1. **Start Simple**: Basic operations require minimal setup
+2. **Scale Gradually**: Add complexity only when needed
+3. **Maintain Consistency**: Common patterns across all Fjell libraries
+4. **Enable Integration**: Designed to work with the entire ecosystem
+
+## Integration with Fjell Ecosystem
+
+Fjell Core serves as the foundation for:
+
+- **@fjell/registry**: Service location and dependency injection
+- **@fjell/cache**: High-performance caching solutions
+- **@fjell/lib**: Database abstraction layers
+- **@fjell/providers**: React component state management
+- **@fjell/client-api**: HTTP client utilities
+- **@fjell/express-router**: Express.js routing utilities
+
+## Type Safety
+
+Built with TypeScript-first design for excellent developer experience:
+
+```typescript
+// Strongly typed factories
+const user = IFactory.create<UserType>('user', userData)
+
+// Type-safe key operations
+const key = KUtils.generateKey(['users', user.id])
+const [collection, id] = KUtils.parseKey(key)
+
+// Compile-time validation
+class UserService extends AItemService<User> {
+  // Methods are typed to work with User objects
+}
+```
+
+## Error Handling
+
+Comprehensive error handling with descriptive messages:
+
+```typescript
+try {
+  const user = await userService.create(invalidData)
+} catch (error) {
+  if (error instanceof CoreValidationError) {
+    console.log('Validation failed:', error.details)
+  } else if (error instanceof CoreNotFoundError) {
+    console.log('User not found:', error.id)
+  }
+}
+```
+
+## Testing Support
+
+Built-in testing utilities for robust test suites:
+
+```typescript
+import { TestUtils } from '@fjell/core/testing'
+
+// Mock factories
+const mockFactory = TestUtils.createMockFactory()
+const testUser = mockFactory.create('user', { id: 'test-123' })
+
+// Assertion helpers
+expect(TestUtils.isValidKey(key)).toBe(true)
+expect(TestUtils.getKeyComponents(key)).toEqual(['users', '123'])
+```
+
+## Performance
+
+Optimized for production use:
+
+- **Minimal Runtime Overhead**: Core operations are highly optimized
+- **Memory Efficient**: Smart object pooling and reuse strategies
+- **Lazy Loading**: Components load only when needed
+- **Tree Shaking**: Only bundle what you use
+
+## Examples
+
+Check out the `/examples` directory for comprehensive usage examples:
+
+- Basic item and key operations
+- Service implementation patterns
+- Query building and execution
+- Integration with databases and APIs
+- Testing strategies
+
+## Documentation
+
+- **Getting Started**: Step-by-step setup guide
+- **API Reference**: Complete API documentation
+- **Examples**: Real-world usage patterns
+- **Migration Guide**: Upgrading from previous versions
+
+## Contributing
+
+We welcome contributions! Please see our contributing guidelines for details on:
+
+- Code style and standards
+- Testing requirements
+- Documentation standards
+- Pull request process
+
+## License
+
+Licensed under the Apache License 2.0. See LICENSE file for details.
+
+## Support
+
+- **GitHub Issues**: Report bugs and request features
+- **Discussions**: Community support and questions
+- **Documentation**: Comprehensive guides and API reference
+
+Built with love by the Fjell team.

package/docs/public/api.md

@@ -0,0 +1,230 @@
+# 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.