# 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', { 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): Promise { const user = IFactory.create('user', userData) await this.validate(user) return this.save(user) } protected async validate(user: User): Promise { 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) ``` ### Operations Interface @fjell/core provides the standard Operations interface used across all fjell libraries. This interface defines the contract for working with Items: ```typescript import { Operations, PrimaryOperations, ContainedOperations } from '@fjell/core'; // For primary items const userOps: PrimaryOperations = ...; // For contained items const commentOps: ContainedOperations = ...; ``` See [Operations README](src/operations/README.md) for detailed documentation. ### Validation Module @fjell/core provides centralized validation functions for ensuring data integrity across the Fjell ecosystem: ```typescript import { validateLocations, validateKey, validatePK, validateKeys, validateSchema, SchemaValidator } from '@fjell/validation'; ``` #### Schema Validation (Zod, Yup, etc.) Universal schema validation that works with any validator matching the `SchemaValidator` interface. Zod is supported out of the box via duck typing: ```typescript import { validateSchema } from '@fjell/validation'; import { z } from 'zod'; // Define a Zod schema const userSchema = z.object({ name: z.string().min(3), age: z.number().min(18), email: z.string().email().optional() }); // Validate data before caching, sending to API, or persisting const validatedUser = await validateSchema(userData, userSchema); // Validation throws ValidationError with FieldError[] on failure try { await validateSchema({ name: 'Al', age: 10 }, userSchema); } catch (error) { if (error instanceof ValidationError) { console.log(error.fieldErrors); // [ // { path: ['name'], message: 'String must contain at least 3 character(s)', code: 'too_small' }, // { path: ['age'], message: 'Number must be greater than or equal to 18', code: 'too_small' } // ] } } ``` **Schema Validation Features:** - **Universal**: Works with Zod, Yup, Joi, or any validator matching the interface - **Type-Safe**: Full TypeScript support with type inference - **Error Transformation**: Automatically converts validator errors to Fjell `ValidationError` - **Async Support**: Handles both sync and async validation - **Available Everywhere**: Use in cache layers, APIs, persistence, or any system boundary #### Location Validation Validates that location key arrays match the expected coordinate hierarchy: ```typescript import { validateLocations } from '@fjell/validation'; // Validate location array order validateLocations( [{ kt: 'store', lk: 'store-1' }], coordinate, 'create' // operation name for error context ); // Non-throwing validation import { isValidLocations } from '@fjell/validation'; const result = isValidLocations( [{ kt: 'store', lk: 'store-1' }], coordinate, 'create' ); if (!result.valid) { console.log(result.error); // Validation error message } ``` #### Key Validation Validates PriKey and ComKey structures match library type: ```typescript import { validateKey, validatePriKey, validateComKey } from '@fjell/validation'; // Validate any key type validateKey(key, coordinate, 'get'); // Validate specific key types validatePriKey(priKey, coordinate, 'update'); validateComKey(comKey, coordinate, 'remove'); ``` #### Item Validation Validates Item keys match expected types: ```typescript import { validatePK, validateKeys } from '@fjell/validation'; // Validate item has correct primary key type const validatedItem = validatePK(item, 'product'); // Validate item key types match key type array const validatedItem = validateKeys(item, ['product', 'store']); ``` **Features:** - **Comprehensive Error Messages**: Detailed context including operation name, expected vs actual values - **Type Safety**: Full TypeScript support with proper type inference - **Performance**: Optimized O(n) validation with minimal overhead - **Flexible**: Both throwing and non-throwing variants available See [Validation Examples](examples/validation-example.ts) for detailed usage patterns. ## 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('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 { // 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.