npm package: @flex-donec/core
Description: Core FLEX framework functionality - A high-performance Express.js framework with Drizzle ORM
Author: fvargas
Latest version: 0.1.2

# @flex/core

A high-performance Express.js framework with Drizzle ORM integration, designed for exceptional Developer Experience (DX) and rapid API development.

## Features

- 🚀 **Express.js Foundation**: Built on top of Express for maximum compatibility
- 💾 **Drizzle ORM Integration**: First-class support for Drizzle ORM with PostgreSQL
- 🔐 **Built-in Authentication**: JWT-based authentication with flexible strategy support
- 🛡️ **Authorization System**: CASL-based authorization for fine-grained access control
- 🪝 **Powerful Hooks System**: Before/after hooks for all service operations
- ✅ **Validation**: Zod-based validation for all inputs
- 🔄 **Auto CRUD Generation**: Automatic REST endpoints for your database models
- 📦 **Service Discovery**: Automatic service registration and routing
- 🎯 **Type-Safe**: Full TypeScript support with excellent type inference

## Installation

```bash
# Install the core package and its peer dependencies
pnpm add @flex-donec/core express@^4.18.2 drizzle-orm@^0.44.6 zod@^3.22.4

# Optional: Install drizzle-zod for auto-schema generation
pnpm add drizzle-zod@^0.5.1

# Install database driver (choose one)
pnpm add postgres  # PostgreSQL (recommended)
# OR
pnpm add pg        # node-postgres
```

> ⚠️ **Important**: Make sure to install the peer dependencies (`express`, `drizzle-orm`, `zod`) alongside this package to avoid type conflicts.

## Quick Start

```typescript
import { FlexApp, DrizzleService, DrizzleAdapter } from '@flex-donec/core';
import { drizzle } from 'drizzle-orm/postgres-js';
import { pgTable, serial, text } from 'drizzle-orm/pg-core';
import postgres from 'postgres';

// Define your database schema
const users = pgTable('users', {
  id: serial('id').primaryKey(),
  email: text('email').notNull().unique(),
  name: text('name').notNull(),
});

// Create database connection
const client = postgres(process.env.DATABASE_URL!);
const db = drizzle(client);
const storage = new DrizzleAdapter(db);

// Create Flex app
const app = new FlexApp();

// Create a service - schema is auto-generated from table!
const usersService = new DrizzleService(storage, users);

// Register service
app.service('users', usersService);

// Start server
app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});
```

### Key Features

- **🎯 No Redundant Schemas**: The Zod validation schema is automatically generated from your Drizzle table definition using `drizzle-zod`
- **⚙️ Flexible Validation**: Optionally provide custom schemas for advanced validation logic
- **🔄 Smart Defaults**: Separate schemas for create (insert) and patch (partial update) operations are auto-generated

### Advanced Usage with Custom Schemas

When you need custom validation logic, you can still provide your own schemas:

```typescript
import { z } from 'zod';

// Custom create schema with additional validation
const createUserSchema = z.object({
  email: z.string().email().toLowerCase(),
  name: z.string().min(2).max(100),
  age: z.number().min(18).max(120).optional(),
});

// Custom patch schema for updates
const patchUserSchema = z.object({
  email: z.string().email().toLowerCase().optional(),
  name: z.string().min(2).max(100).optional(),
  age: z.number().min(18).max(120).optional(),
});

// Create service with custom schemas
const usersService = new DrizzleService(
  storage,
  users,
  undefined, // Use auto-generated select schema
  createUserSchema, // Custom create validation
  patchUserSchema  // Custom patch validation
);
```

## Environment Variables

Flex Core uses environment variables for configuration. All values are optional and have sensible defaults.

### JWT Configuration

```bash
# Required: Secret keys for token signing and verification
JWT_SECRET=your-secret-key-here
JWT_REFRESH_SECRET=your-refresh-secret-key-here

# Optional: Token expiration times (default: 1h for access, 7d for refresh)
# Examples: '15m', '1h', '2h', '7d', '30d'
JWT_ACCESS_TOKEN_EXPIRES_IN=1h
JWT_REFRESH_TOKEN_EXPIRES_IN=7d

# Optional: JWT Issuer and Audience for additional validation
# Leave empty to disable issuer/audience validation (recommended for most cases)
# JWT_ISSUER=your-app-name
# JWT_AUDIENCE=your-app-users
```

### Database Configuration

```bash
DATABASE_URL=postgresql://user:password@localhost:5432/database_name
```

### Server Configuration

```bash
PORT=3000
```

## Documentation

For full documentation, please visit [GitHub Repository](https://github.com/Donec-AI/flex-donec).

## License

MIT © fvargas