Enterprise-grade TypeScript libraries for web applications, database operations, and code generation
BlendSDK v5 is a modern TypeScript monorepo providing production-ready libraries for building enterprise web applications. With a focus on type safety, developer experience, and fluent APIs, BlendSDK offers everything from web frameworks to database abstraction and code generation tools.
- 🎯 Type Safety First - Strict TypeScript with full type coverage
- 🔄 Fluent APIs - Chainable, intuitive interfaces
- 📦 Modular Design - Use only what you need
- ⚡ Performance - Optimized for production workloads
- 🧪 Fully Tested - Comprehensive test coverage with Vitest
- 🚀 ESM Native - Modern ECMAScript modules
Production-ready Express.js framework with dependency injection, plugin system, and fluent routing.
import { WebApplication, BaseController } from '@blendsdk/webafx';
const app = new WebApplication({ PORT: 3000 });
class UserController extends BaseController {
routes() {
return [
this.route().get('/').handle(this.list),
this.authenticated().post('/').handle(this.create),
];
}
}
app.registerController('/api/users', UserController);
await app.start();Features:
- Dependency injection container
- Plugin-based architecture
- Fluent route builder with authentication/authorization
- Built-in middleware (CORS, compression, request ID)
- Graceful shutdown support
- Health checks
PostgreSQL client with connection pooling and graceful shutdown.
import { PostgreSQLDatabase } from '@blendsdk/postgresql';
const db = new PostgreSQLDatabase({
host: 'localhost',
database: 'myapp',
user: 'postgres',
password: 'secret',
});
await db.connect();
const users = await db.query('SELECT * FROM users WHERE active = $1', [true]);
await db.shutdown();Features:
- Connection pooling with
pgdriver - Graceful connection management
- Transaction support
- Prepared statements
- Health checks
Database abstraction layer with CRUD statement builders.
import { SelectStatement } from '@blendsdk/dbcore';
const query = new SelectStatement()
.from('users')
.select('id', 'email', 'name')
.where('active = $1', true)
.orderBy('created_at DESC')
.limit(10);
const { sql, params } = query.compile();Features:
- Fluent query builders (SELECT, INSERT, UPDATE, DELETE)
- Expression builder integration
- Parameter binding
- Type-safe compilation
Immutable AST-based SQL WHERE clause builder.
import { query } from '@blendsdk/expression';
const result = query()
.where('status')
.equals('active')
.and(q => q.where('age').greaterThan(21).or('verified').equals(true))
.compile();
// Output: { sql: "status = $1 AND (age > $2 OR verified = $3)", params: {...} }Features:
- Immutable query objects
- Nested conditions
- Type-safe operators
- SQL injection protection
TypeScript/Zod/SQL generator with PostgreSQL introspection.
import { SchemaContainer, TypeGenerator } from '@blendsdk/codegen';
const schema = new SchemaContainer();
const s = schema.scope('api');
const User = s
.object({
id: s.number(),
email: s.string(),
role: s.string().enum(['admin', 'user']),
})
.named('User');
const typeGen = new TypeGenerator();
const tsCode = await typeGen.generate(schema);Features:
- Database schema builder (DDL generation)
- TypeScript type generation
- Zod schema generation
- PostgreSQL introspection (reverse engineering)
- Supports enums, arrays, nullable types
Standard library with type guards and utility functions.
import { isString, isNumber, isDefined } from '@blendsdk/stdlib';
if (isString(value)) {
console.log(value.toUpperCase()); // TypeScript knows value is string
}Features:
- Type guards for runtime checking
- Common utility functions
- No external dependencies
Fluent command-line argument parser with validation.
import { CommandLineParser } from '@blendsdk/cmdline';
const parser = new CommandLineParser()
.option('--port', { type: 'number', default: 3000 })
.option('--env', { type: 'string', choices: ['dev', 'prod'] })
.flag('--verbose');
const args = parser.parse(process.argv);
console.log(`Starting on port ${args.port}`);Features:
- Type-safe argument parsing
- Validation and default values
- Help text generation
- Boolean flags
# Web framework
npm install @blendsdk/webafx
# Database
npm install @blendsdk/postgresql @blendsdk/dbcore @blendsdk/expression
# Code generation
npm install @blendsdk/codegen
# Utilities
npm install @blendsdk/stdlib @blendsdk/cmdline- Node.js: >= 22.0.0
- Package Manager: npm, yarn, or pnpm
import { WebApplication, BaseController } from '@blendsdk/webafx';
import { PostgreSQLDatabase } from '@blendsdk/postgresql';
const app = new WebApplication({ PORT: 3000 });
// Register database service
app.registerService({
name: 'db',
type: 'singleton',
factory: async () => {
const db = new PostgreSQLDatabase({
/* config */
});
await db.connect();
return db;
},
});
// Create controller
class UserController extends BaseController {
routes() {
return [this.route().get('/').handle(this.list)];
}
async list(req, res) {
const db = await req.services.get('db');
const users = await db.query('SELECT * FROM users');
res.json(users);
}
}
app.registerController('/api/users', UserController);
const shutdown = await app.start();
console.log('Server running on http://localhost:3000');
process.on('SIGTERM', shutdown);import { PostgreSQLDatabase } from '@blendsdk/postgresql';
import { SelectStatement } from '@blendsdk/dbcore';
import { query } from '@blendsdk/expression';
const db = new PostgreSQLDatabase({
/* config */
});
await db.connect();
// Using raw queries
const result = await db.query('SELECT * FROM users WHERE id = $1', [123]);
// Using statement builders
const stmt = new SelectStatement()
.from('users')
.select('*')
.where(query().where('active').equals(true).and('role').in(['admin', 'user']).compile());
const { sql, params } = stmt.compile();
const users = await db.query(sql, Object.values(params));import { SchemaContainer, TypeGenerator, ZodGenerator } from '@blendsdk/codegen';
const schema = new SchemaContainer();
const s = schema.scope('api');
// Define schema
const User = s
.object({
id: s.number(),
email: s.string(),
name: s.string().optional(),
roles: s.string().arrayed(),
})
.named('User');
// Generate TypeScript types
const typeGen = new TypeGenerator();
const types = await typeGen.generate(schema);
console.log(types);
// export interface User {
// id: number;
// email: string;
// name?: string;
// roles: string[];
// }
// Generate Zod schemas
const zodGen = new ZodGenerator();
const schemas = await zodGen.generate(schema);
console.log(schemas);
// export const UserSchema = z.object({
// id: z.number(),
// email: z.string(),
// name: z.string().optional(),
// roles: z.array(z.string())
// });BlendSDK is a monorepo managed with Turbo and uses lockstep versioning (all packages share the same version).
# Clone repository
git clone https://github.com/TrueSoftwareNL/blendsdk.git
cd blendsdk
# Install dependencies (requires Yarn)
yarn install
# Build all packages
yarn build
# Run tests
yarn test# Build all packages
yarn build
# Test all packages
yarn test
# Test with coverage
yarn test --coverage
# Watch mode
yarn test:watch
# Type check
yarn type-check
# Clean build artifacts
yarn clean# Navigate to package
cd packages/webafx
# Build specific package
yarn build
# Test specific package
yarn test
# Watch mode
yarn devBlendSDK uses lockstep versioning - all packages are versioned together:
# Auto-detect version bump from conventional commits
yarn lockstep:version:auto --ci
# Explicit version bumps
yarn lockstep:version:patch --ci
yarn lockstep:version:minor --ci
yarn lockstep:version:major --ci
# Publish to npm
yarn lockstep:publish:latest
yarn lockstep:publish:nextpackages/
├── stdlib/ # Foundation (no dependencies)
├── expression/ # SQL expression builder (depends on stdlib)
├── dbcore/ # Database abstraction (depends on expression)
├── postgresql/ # PostgreSQL client (depends on dbcore)
├── cmdline/ # CLI parser (depends on stdlib)
├── codegen/ # Code generators (depends on dbcore, postgresql)
└── webafx/ # Web framework (depends on stdlib)
stdlib ──→ cmdline
expression ──→ dbcore ──→ postgresql ──→ codegen
webafx (standalone, depends on express)
- TypeScript 5.9 - Strict mode, ESM modules
- Vitest - Fast, modern test framework
- Turbo - High-performance build system
- Express 5 - Web server (webafx)
- pg - PostgreSQL driver (postgresql)
- Zod - Schema validation (codegen)
# All packages
yarn test
# With coverage
yarn test --coverage
# Watch mode
yarn test:watch
# Specific package
cd packages/webafx && yarn testSome packages (postgresql, codegen) use Docker Compose for integration testing:
# Start test database
cd packages/postgresql
yarn db:up
# Run tests
yarn test
# Stop test database
yarn db:down- Package Documentation - Individual package READMEs
- API Reference - JSDoc comments in source code
- Implementation Plans - Architecture documents
- AI Agent Instructions - Development guidelines
We welcome contributions! Please follow these guidelines:
- Follow existing patterns - Review code in similar packages
- Write tests - All new features must have test coverage
- Use conventional commits - For automatic versioning
- Update documentation - Keep READMEs and JSDoc current
- Run tests before committing - Ensure all tests pass
feat: add new feature (minor version bump)
fix: bug fix (patch version bump)
docs: documentation only
refactor: code change without feature/fix
test: adding/updating tests
chore: maintenance tasks
BREAKING CHANGE: triggers major version bump
MIT © True Software
- Issues: GitHub Issues
- Discussions: GitHub Discussions
BlendSDK follows Semantic Versioning:
- Major (x.0.0): Breaking changes
- Minor (0.x.0): New features (backward compatible)
- Patch (0.0.x): Bug fixes (backward compatible)
Current version: 5.32.0 (lockstep across all packages)
Built with ❤️ by TrueSoftware