@fjell/core 4.4.7 → 4.4.12

package/docs/src/index.css

@@ -0,0 +1,38 @@
+:root {
+  font-family: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif;
+  line-height: 1.5;
+  font-weight: 400;
+
+  color-scheme: light dark;
+  color: rgba(255, 255, 255, 0.87);
+  background-color: #242424;
+
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-text-size-adjust: 100%;
+}
+
+a {
+  font-weight: 500;
+  color: #646cff;
+  text-decoration: inherit;
+}
+
+a:hover {
+  color: #535bf2;
+}
+
+body {
+  margin: 0;
+  display: flex;
+  place-items: center;
+  min-width: 320px;
+  min-height: 100vh;
+}
+
+h1 {
+  font-size: 3.2em;
+  line-height: 1.1;
+}

package/docs/src/main.tsx

@@ -0,0 +1,10 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App.tsx'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)

package/docs/tsconfig.node.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true,
+    "strict": true
+  },
+  "include": [
+    "vite.config.ts",
+    "vitest.config.ts"
+  ]
+}

package/docs/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./src/test/setup.ts'],
+    coverage: {
+      reporter: ['text', 'json', 'html']
+    }
+  }
+})

package/examples/README.md

@@ -0,0 +1,147 @@
+# 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/examples/basic-usage.ts

@@ -0,0 +1,293 @@
+/**
+ * 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fjell/core",
   "description": "Core Item and Key Framework for Fjell",
-  "version": "4.4.7",
+  "version": "4.4.12",
   "keywords": [
     "core",
     "fjell"
@@ -18,24 +18,25 @@
   },
   "type": "module",
   "dependencies": {
-    "@fjell/logging": "^4.4.7",
+    "@fjell/logging": "^4.4.13",
     "deepmerge": "^4.3.1",
     "luxon": "^3.7.1"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.31.0",
-    "@swc/core": "^1.12.14",
+    "@fjell/eslint-config": "^1.0.5",
+    "@swc/core": "^1.13.1",
     "@tsconfig/recommended": "^1.0.10",
     "@types/luxon": "^3.6.2",
-    "@typescript-eslint/eslint-plugin": "^8.37.0",
-    "@typescript-eslint/parser": "^8.37.0",
+    "@typescript-eslint/eslint-plugin": "^8.38.0",
+    "@typescript-eslint/parser": "^8.38.0",
     "@vitest/coverage-v8": "3.2.4",
     "concurrently": "^9.2.0",
     "eslint": "^9.31.0",
     "rimraf": "^6.0.1",
     "typescript": "^5.8.3",
-    "vite": "^7.0.4",
+    "vite": "^7.0.5",
     "vite-plugin-dts": "^4.5.4",
     "vite-plugin-node": "^7.0.0",
     "vitest": "3.2.4"

package/src/item/IUtils.ts

@@ -1,5 +1,5 @@
 /* eslint-disable indent */
-/* eslint-disable max-len */
+ 
 import { Item } from "@/items";
 import { isComKey, isPriKey, toKeyTypeArray } from "@/key/KUtils";
 import { AllItemTypeArrays, ComKey, PriKey } from "@/keys";