@fjell/express-router 4.4.56 → 4.4.58

package/docs/package.json

@@ -1,34 +0,0 @@
-{
-  "name": "fjell-express-router-docs",
-  "private": true,
-  "version": "0.0.0",
-  "type": "module",
-  "scripts": {
-    "copy-docs": "node node_modules/@fjell/docs-template/dist/scripts/copy-docs.js",
-    "dev": "npm run copy-docs && vite",
-    "build": "npm run copy-docs && vite build",
-    "preview": "vite preview",
-    "test": "vitest run --coverage",
-    "test:watch": "vitest --watch"
-  },
-  "dependencies": {
-    "@fjell/docs-template": "^1.0.38",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0"
-  },
-  "devDependencies": {
-    "@testing-library/jest-dom": "^6.6.3",
-    "@testing-library/react": "^16.3.0",
-    "@testing-library/user-event": "^14.6.1",
-    "@types/react": "^19.1.8",
-    "@types/react-dom": "^19.1.6",
-    "@types/react-syntax-highlighter": "^15.5.13",
-    "@vitejs/plugin-react": "^4.6.0",
-    "@vitest/coverage-v8": "^3.2.4",
-    "@vitest/ui": "^3.2.4",
-    "jsdom": "^26.1.0",
-    "typescript": "^5.8.3",
-    "vite": "^7.0.0",
-    "vitest": "^3.2.4"
-  }
-}

package/docs/public/README.md

@@ -1,332 +0,0 @@
-# Fjell Express Router
-
-**Express Router for Fjell** - Automatic REST API generation with hierarchical data management for Express.js applications.
-
-Fjell Express Router provides a powerful abstraction layer for creating Express.js REST APIs that automatically handle CRUD operations for complex, hierarchical data models. Built on the Fjell framework, it enables rapid development of enterprise-grade APIs with built-in support for nested resources, business logic integration, and type-safe operations.
-
-## Features
-
-- **Automatic CRUD Routes**: Generate complete REST endpoints with minimal configuration
-- **Hierarchical Data Support**: Handle complex nested relationships with parent-child routing
-- **Type-Safe Operations**: Full TypeScript support with generic type constraints
-- **Flexible Business Logic**: Easy integration of custom business rules and validations
-- **Express.js Integration**: Seamless mounting as Express middleware with full compatibility
-- **Built-in Error Handling**: Comprehensive error responses with proper HTTP status codes
-- **Extensible Architecture**: Support for custom actions, facets, and middleware
-
-## Installation
-
-```bash
-npm install @fjell/express-router
-```
-
-Or with npm:
-
-```bash
-npm install @fjell/express-router
-```
-
-## Quick Start
-
-```typescript
-import { PItemRouter, createRegistry } from '@fjell/express-router';
-import { Item } from '@fjell/core';
-import express from 'express';
-
-// Define your data model
-interface User extends Item<'user'> {
-  id: string;
-  name: string;
-  email: string;
-  role: 'admin' | 'user' | 'guest';
-}
-
-// Create Express app and registry
-const app = express();
-const registry = createRegistry();
-
-// Create instance and router
-const userInstance = registry.getInstance(
-  'user',
-  userOperations, // Your business logic implementation
-  userOptions     // Configuration options
-);
-
-const userRouter = new PItemRouter(userInstance, 'user');
-
-// Mount router - automatically creates CRUD endpoints
-app.use('/api/users', userRouter.getRouter());
-
-// Start server
-app.listen(3000, () => {
-  console.log('Server running on http://localhost:3000');
-});
-```
-
-This automatically creates the following endpoints:
-
-- `GET /api/users` - List all users
-- `GET /api/users/:userPk` - Get specific user
-- `POST /api/users` - Create new user
-- `PUT /api/users/:userPk` - Update user
-- `DELETE /api/users/:userPk` - Delete user
-
-## Core Concepts
-
-### Router Types
-
-**PItemRouter** - For primary entities that exist independently:
-```typescript
-const userRouter = new PItemRouter(userInstance, 'user');
-const productRouter = new PItemRouter(productInstance, 'product');
-```
-
-**CItemRouter** - For child entities that belong to parent entities:
-```typescript
-const orderRouter = new PItemRouter(orderInstance, 'order');
-const orderItemRouter = new CItemRouter(orderItemInstance, 'orderItem', orderRouter);
-```
-
-### Hierarchical Routing
-
-Create nested routes for complex relationships:
-
-```typescript
-// Organization -> Department -> Employee hierarchy
-const orgRouter = new PItemRouter(orgInstance, 'organization');
-const deptRouter = new CItemRouter(deptInstance, 'department', orgRouter);
-const empRouter = new CItemRouter(empInstance, 'employee', deptRouter);
-
-// Mount hierarchical routes
-app.use('/api/organizations', orgRouter.getRouter());
-app.use('/api/organizations/:organizationPk/departments', deptRouter.getRouter());
-app.use('/api/organizations/:organizationPk/departments/:departmentPk/employees', empRouter.getRouter());
-```
-
-This creates endpoints like:
-- `GET /api/organizations/org-1/departments/dept-1/employees`
-- `POST /api/organizations/org-1/departments/dept-1/employees`
-- `GET /api/organizations/org-1/departments/dept-1/employees/emp-1`
-
-## Advanced Usage
-
-### Custom Business Logic
-
-Add custom routes alongside automatic CRUD operations:
-
-```typescript
-const router = userRouter.getRouter();
-
-// Add custom business logic routes
-router.get('/analytics', async (req, res) => {
-  const analytics = await userInstance.operations.getAnalytics();
-  res.json(analytics);
-});
-
-router.post('/:userPk/activate', async (req, res) => {
-  const userPk = req.params.userPk;
-  const user = await userInstance.operations.activate(userPk);
-  res.json(user);
-});
-
-app.use('/api/users', router);
-```
-
-### Middleware Integration
-
-Add Express middleware for authentication, validation, and more:
-
-```typescript
-import { authenticate, authorize, validateRequest } from './middleware';
-
-// Global middleware
-app.use(express.json());
-app.use(authenticate);
-
-// Router-specific middleware
-const protectedRouter = userRouter.getRouter();
-protectedRouter.use(authorize(['admin', 'user']));
-protectedRouter.use('/sensitive-endpoint', validateRequest);
-
-app.use('/api/users', protectedRouter);
-```
-
-### Error Handling
-
-Built-in error handling with proper HTTP status codes:
-
-```typescript
-// Automatic error responses for common scenarios:
-// 404 - Entity not found
-// 400 - Invalid request data
-// 500 - Internal server errors
-
-// Custom error handling
-app.use((err, req, res, next) => {
-  console.error('API Error:', err);
-  res.status(err.status || 500).json({
-    error: err.message || 'Internal Server Error',
-    ...(process.env.NODE_ENV === 'development' && { stack: err.stack })
-  });
-});
-```
-
-## Data Model Requirements
-
-Your data models must extend the Fjell `Item` interface:
-
-```typescript
-import { Item, UUID } from '@fjell/core';
-
-interface User extends Item<'user'> {
-  id: string;
-  name: string;
-  email: string;
-  // ... other properties
-}
-
-interface Order extends Item<'order'> {
-  id: string;
-  customerId: string;
-  total: number;
-  // ... other properties
-}
-
-interface OrderItem extends Item<'orderItem', 'order'> {
-  id: string;
-  productId: string;
-  quantity: number;
-  price: number;
-  // ... other properties
-}
-```
-
-## Configuration
-
-Configure your instances with business operations and options:
-
-```typescript
-const userInstance = registry.getInstance(
-  'user',
-  {
-    // Business operations implementation
-    create: async (item) => { /* create logic */ },
-    get: async (pk) => { /* get logic */ },
-    update: async (pk, updates) => { /* update logic */ },
-    delete: async (pk) => { /* delete logic */ },
-    list: async (query) => { /* list logic */ },
-    // ... other operations
-  },
-  {
-    // Configuration options
-    allowedMethods: ['GET', 'POST', 'PUT', 'DELETE'],
-    validation: { /* validation rules */ },
-    facets: { /* custom facets */ },
-    actions: { /* custom actions */ },
-    // ... other options
-  }
-);
-```
-
-## Examples
-
-This package includes comprehensive examples in the `examples/` directory:
-
-- **`basic-router-example.ts`** - Start here for fundamental usage patterns
-- **`nested-router-example.ts`** - Hierarchical data management with organizations/departments/employees
-- **`full-application-example.ts`** - Production-ready e-commerce application
-
-Run examples:
-
-```bash
-# Basic example
-npx tsx examples/basic-router-example.ts
-
-# Nested routing example
-npx tsx examples/nested-router-example.ts
-
-# Full application example
-npx tsx examples/full-application-example.ts
-```
-
-## API Reference
-
-### PItemRouter<T, S>
-
-Primary item router for top-level entities.
-
-**Constructor**
-```typescript
-new PItemRouter<T, S>(instance: Instance<T, S>, keyType: S, options?: ItemRouterOptions)
-```
-
-**Methods**
-- `getRouter(): Router` - Get Express router instance
-- `getPkType(): S` - Get primary key type
-- `createItem(req, res)` - Handle POST requests
-- `getItem(req, res)` - Handle GET requests for single items
-- `updateItem(req, res)` - Handle PUT requests
-- `deleteItem(req, res)` - Handle DELETE requests
-
-### CItemRouter<T, S, L1, ...>
-
-Child item router for nested entities.
-
-**Constructor**
-```typescript
-new CItemRouter<T, S, L1>(
-  instance: Instance<T, S, L1>,
-  keyType: S,
-  parentRouter: ItemRouter<L1>,
-  options?: ItemRouterOptions
-)
-```
-
-Inherits all methods from `ItemRouter` with additional parent-child relationship handling.
-
-### createRegistry()
-
-Factory function to create a new registry instance for managing multiple routers.
-
-```typescript
-const registry = createRegistry();
-const instance = registry.getInstance(keyType, operations, options);
-```
-
-## Requirements
-
-- Node.js >= 21
-- TypeScript >= 5.0
-- Express.js >= 5.0
-
-## Dependencies
-
-- `@fjell/core` - Core Fjell framework types and utilities
-- `@fjell/lib` - Fjell library components
-- `@fjell/logging` - Structured logging for Fjell applications
-- `@fjell/registry` - Registry management for Fjell instances
-- `express` - Express.js web framework
-- `deepmerge` - Deep object merging utility
-
-## Contributing
-
-Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes with tests
-4. Ensure all tests pass
-5. Submit a pull request
-
-## License
-
-Licensed under the Apache License 2.0. See the LICENSE file for details.
-
-## Support
-
-- **Documentation**: [Full documentation and guides](./docs/)
-- **Examples**: [Comprehensive examples](./examples/)
-- **Issues**: [GitHub Issues](https://github.com/getfjell/express-router/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/getfjell/express-router/discussions)
-
-Built with care by the Fjell team.

package/docs/public/examples-README.md

@@ -1,339 +0,0 @@
-# Fjell-Express-Router Examples
-
-This directory contains examples demonstrating how to use fjell-express-router for building Express.js applications with automatic CRUD routing, hierarchical data management, and business logic integration with different patterns and complexity levels.
-
-## Examples
-
-### 1. `basic-router-example.ts` ⭐ **Start Here!**
-**Perfect for beginners!** Demonstrates the fundamental way to use fjell-express-router for REST API development:
-- **Basic PItemRouter usage** - Create routers for primary entities (Users, Tasks)
-- **Automatic CRUD endpoints** - GET, POST, PUT, DELETE routes generated automatically
-- **Mock data operations** - Simple in-memory storage with business logic
-- **Express app integration** - Mount routers and add custom middleware
-- **Custom business routes** - Dashboard and health check endpoints
-
-Great for understanding the fundamentals of fjell-express-router for REST API development.
-
-### 2. `nested-router-example.ts` 🏗️ **Hierarchical Data Management**
-**Advanced hierarchical routing!** Demonstrates complex data structures with nested relationships:
-- **Multiple router types**: PItemRouter for Organizations, CItemRouter for Departments and Employees
-- **Nested route mounting**: `/organizations/:orgId/departments/:deptId/employees/:empId`
-- **Hierarchical data models**: Organization → Department → Employee relationships
-- **Location-based operations**: Complex queries spanning multiple organizational levels
-- **Business analytics**: Organizational hierarchy summaries and statistics
-
-Shows how fjell-express-router handles enterprise organizational data patterns with deep hierarchies.
-
-### 3. `full-application-example.ts` 🚀 **Production-Ready Application**
-**Complete enterprise application!** Demonstrates a realistic e-commerce system with advanced patterns:
-- **Multiple interconnected entities**: Customer, Product, Order, OrderItem, Review
-- **Advanced middleware**: Error handling, request logging, business validation
-- **Complex business logic**: Product catalog, customer analytics, order management
-- **Production patterns**: CORS headers, security middleware, proper error handling
-- **Real-world scenarios**: Complete e-commerce platform with customer lifecycle management
-
-Perfect for understanding how to build production-ready applications with fjell-express-router.
-
-## Key Concepts Demonstrated
-
-### Basic Router Setup (basic-router-example.ts)
-```typescript
-// Import fjell-express-router functionality
-import { PItemRouter, createRegistry } from '@fjell/express-router';
-import express from 'express';
-
-// Create Express app and registry
-const app = express();
-const registry = createRegistry();
-
-// Create router instance
-const userRouter = new PItemRouter(userInstance, 'user');
-
-// Mount router to create automatic REST endpoints
-app.use('/api/users', userRouter.getRouter());
-// This creates:
-// GET    /api/users           - List all users
-// GET    /api/users/:userPk   - Get specific user
-// POST   /api/users           - Create new user
-// PUT    /api/users/:userPk   - Update user
-// DELETE /api/users/:userPk   - Delete user
-```
-
-### Nested Routing (nested-router-example.ts)
-```typescript
-// Create hierarchical routers
-const orgRouter = new PItemRouter(orgInstance, 'organization');
-const deptRouter = new CItemRouter(deptInstance, 'department', orgRouter);
-const empRouter = new CItemRouter(empInstance, 'employee', deptRouter);
-
-// Mount nested routes
-app.use('/api/organizations', orgRouter.getRouter());
-app.use('/api/organizations/:organizationPk/departments', deptRouter.getRouter());
-app.use('/api/organizations/:organizationPk/departments/:departmentPk/employees', empRouter.getRouter());
-
-// This creates nested endpoints like:
-// GET /api/organizations/org-1/departments/dept-1/employees
-// POST /api/organizations/org-1/departments/dept-1/employees
-```
-
-### Production Application (full-application-example.ts)
-```typescript
-// Advanced middleware setup
-app.use(express.json({ limit: '10mb' }));
-app.use(requestLogger);
-app.use(validateCustomerTier);
-app.use(errorHandler);
-
-// Business logic routes
-app.get('/api/dashboard', async (req, res) => {
-  // Complex dashboard with analytics
-});
-
-app.get('/api/catalog', async (req, res) => {
-  // Product catalog with filtering and search
-});
-```
-
-## Data Model Patterns
-
-### Primary Items (PItemRouter)
-Primary items are top-level entities that exist independently:
-```typescript
-interface User extends Item<'user'> {
-  id: string;
-  name: string;
-  email: string;
-  // ... other properties
-}
-
-// Creates routes: /api/users, /api/users/:userPk
-const userRouter = new PItemRouter(userInstance, 'user');
-```
-
-### Contained Items (CItemRouter)
-Contained items exist within a parent context and inherit location:
-```typescript
-interface Department extends Item<'department', 'organization'> {
-  id: string;
-  name: string;
-  organizationId: string; // Reference to parent
-  // ... other properties
-}
-
-// Creates nested routes: /api/organizations/:orgPk/departments
-const deptRouter = new CItemRouter(deptInstance, 'department', orgRouter);
-```
-
-### Multi-Level Hierarchies
-Deep nesting is supported for complex organizational structures:
-```typescript
-interface Employee extends Item<'employee', 'organization', 'department'> {
-  id: string;
-  name: string;
-  organizationId: string;
-  departmentId: string;
-  // ... other properties
-}
-
-// Creates deeply nested routes: /api/organizations/:orgPk/departments/:deptPk/employees
-const empRouter = new CItemRouter(empInstance, 'employee', deptRouter);
-```
-
-## Running the Examples
-
-### Prerequisites
-```bash
-# Install dependencies
-npm install express @fjell/core @fjell/lib @fjell/express-router
-
-# For running TypeScript examples
-npm install -g tsx
-```
-
-### Running Individual Examples
-
-**Basic Router Example:**
-```bash
-npx tsx examples/basic-router-example.ts
-# Server runs on http://localhost:3001
-```
-
-**Nested Router Example:**
-```bash
-npx tsx examples/nested-router-example.ts
-# Server runs on http://localhost:3002
-```
-
-**Full Application Example:**
-```bash
-npx tsx examples/full-application-example.ts
-# Server runs on http://localhost:3003
-```
-
-## Testing the Examples
-
-### Basic Router Example (Port 3001)
-```bash
-# Health check
-curl http://localhost:3001/api/health
-
-# Dashboard summary
-curl http://localhost:3001/api/dashboard
-
-# List all users
-curl http://localhost:3001/api/users
-
-# Get specific user
-curl http://localhost:3001/api/users/user-1
-
-# Create new user
-curl -X POST http://localhost:3001/api/users \
-  -H "Content-Type: application/json" \
-  -d '{"name":"New User","email":"new@example.com","role":"user"}'
-
-# List all tasks
-curl http://localhost:3001/api/tasks
-```
-
-### Nested Router Example (Port 3002)
-```bash
-# Organizational hierarchy
-curl http://localhost:3002/api/hierarchy
-
-# Statistics summary
-curl http://localhost:3002/api/stats
-
-# List organizations
-curl http://localhost:3002/api/organizations
-
-# List departments for organization
-curl http://localhost:3002/api/organizations/org-1/departments
-
-# List employees for department
-curl http://localhost:3002/api/organizations/org-1/departments/dept-1/employees
-
-# Create new department
-curl -X POST http://localhost:3002/api/organizations/org-1/departments \
-  -H "Content-Type: application/json" \
-  -d '{"name":"IT Department","budget":1000000,"headCount":15}'
-```
-
-### Full Application Example (Port 3003)
-```bash
-# System health
-curl http://localhost:3003/health
-
-# Business dashboard
-curl http://localhost:3003/api/dashboard
-
-# Product catalog
-curl http://localhost:3003/api/catalog
-
-# Filtered catalog
-curl "http://localhost:3003/api/catalog?category=Electronics&featured=true"
-
-# Customer analytics
-curl http://localhost:3003/api/customers/cust-1/analytics
-
-# List customers
-curl http://localhost:3003/api/customers
-
-# Customer orders
-curl http://localhost:3003/api/customers/cust-1/orders
-
-# Create new customer
-curl -X POST http://localhost:3003/api/customers \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "New Customer",
-    "email": "customer@example.com",
-    "phone": "+1-555-0789",
-    "address": {
-      "street": "789 Pine St",
-      "city": "Seattle",
-      "state": "WA",
-      "zipCode": "98101"
-    },
-    "tier": "bronze"
-  }'
-```
-
-## Integration Patterns
-
-### Mock Operations
-All examples use mock operations that simulate real database interactions:
-```typescript
-const createUserOperations = () => ({
-  async all() { /* return all users */ },
-  async get(key) { /* return specific user */ },
-  async create(item) { /* create new user */ },
-  async update(key, updates) { /* update user */ },
-  async remove(key) { /* delete user */ },
-  async find(finder, params) { /* find users with criteria */ }
-});
-```
-
-### Instance Creation
-Fjell instances wrap operations and provide router integration:
-```typescript
-const mockUserInstance = {
-  operations: createUserOperations(),
-  options: {}
-};
-
-const userRouter = new PItemRouter(mockUserInstance, 'user');
-```
-
-### Error Handling
-Production applications should include comprehensive error handling:
-```typescript
-const errorHandler = (err, req, res, next) => {
-  console.error('Application Error:', err.message);
-  res.status(500).json({
-    error: 'Internal Server Error',
-    message: process.env.NODE_ENV === 'development' ? err.message : 'Something went wrong'
-  });
-};
-
-app.use(errorHandler);
-```
-
-## Best Practices
-
-### 1. **Start Simple**
-Begin with the basic router example to understand core concepts before moving to complex hierarchies.
-
-### 2. **Design Your Data Model**
-Plan your Item interfaces and relationships carefully:
-- Use PItemRouter for independent entities
-- Use CItemRouter for entities that belong to parents
-- Define clear location hierarchies for nested data
-
-### 3. **Implement Operations**
-Create comprehensive operations that handle:
-- CRUD operations (all, get, create, update, remove)
-- Business logic finders (find method with custom logic)
-- Error handling and validation
-
-### 4. **Add Business Logic**
-Extend beyond basic CRUD with:
-- Custom middleware for validation
-- Business logic routes (dashboards, analytics)
-- Proper error handling and logging
-
-### 5. **Production Considerations**
-For production applications:
-- Implement proper authentication/authorization
-- Add rate limiting and security headers
-- Use environment-specific configurations
-- Implement comprehensive logging and monitoring
-
-## Next Steps
-
-1. **Study the examples** in order of complexity
-2. **Run each example** and test the endpoints
-3. **Modify the data models** to match your use case
-4. **Implement real operations** with your database/API
-5. **Add authentication and security** for production use
-
-For more advanced usage, see the fjell-express-router documentation and explore other fjell ecosystem packages like fjell-cache, fjell-lib, and fjell-client-api.

package/docs/public/fjell-icon.svg

@@ -1 +0,0 @@
-