@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

# 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

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:

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

# 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

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

Server Configuration

PORT=3000

Documentation

For full documentation, please visit GitHub Repository.

License

MIT © fvargas