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';constapp=newWebApplication({PORT: 3000});classUserControllerextendsBaseController{routes(){return[this.route().get('/').handle(this.list),this.authenticated().post('/').handle(this.create),];}}app.registerController('/api/users',UserController);awaitapp.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';constdb=newPostgreSQLDatabase({host: 'localhost',database: 'myapp',user: 'postgres',password: 'secret',});awaitdb.connect();constusers=awaitdb.query('SELECT * FROM users WHERE active = $1',[true]);awaitdb.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';constquery=newSelectStatement().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';constresult=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';constschema=newSchemaContainer();consts=schema.scope('api');constUser=s.object({id: s.number(),email: s.string(),role: s.string().enum(['admin','user']),}).named('User');consttypeGen=newTypeGenerator();consttsCode=awaittypeGen.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';constparser=newCommandLineParser().option('--port',{type: 'number',default: 3000}).option('--env',{type: 'string',choices: ['dev','prod']}).flag('--verbose');constargs=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
React component and hook library for BlendSDK applications. Provides reusable UI components with full TypeScript support.
import{GlobalLoaderProvider,useGlobalLoader}from'@blendsdk/react';// Wrap your app with the provider<GlobalLoaderProviderconfig={{spinnerColor: '#25b09b'}}><App/></GlobalLoaderProvider>// Use the hook anywhere inside the providerconst{ showLoader, setText }=useGlobalLoader();setText('Loading data…');showLoader(true);Features:
- Full-screen GlobalLoader with CSS-only spinner animation
- Context + Provider + Hook pattern for app-wide loader control
- Configurable appearance (colors, size, z-index, custom text component)
- Body scroll lock, nesting detection, auto-text-clearing
- Zero dependencies beyond React 19+
# 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';constapp=newWebApplication({PORT: 3000});// Register database serviceapp.registerService({name: 'db',type: 'singleton',factory: async()=>{constdb=newPostgreSQLDatabase({/* config */});awaitdb.connect();returndb;},});// Create controllerclassUserControllerextendsBaseController{routes(){return[this.route().get('/').handle(this.list)];}asynclist(req,res){constdb=awaitreq.services.get('db');constusers=awaitdb.query('SELECT * FROM users');res.json(users);}}app.registerController('/api/users',UserController);constshutdown=awaitapp.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';constdb=newPostgreSQLDatabase({/* config */});awaitdb.connect();// Using raw queriesconstresult=awaitdb.query('SELECT * FROM users WHERE id = $1',[123]);// Using statement buildersconststmt=newSelectStatement().from('users').select('*').where(query().where('active').equals(true).and('role').in(['admin','user']).compile());const{ sql, params }=stmt.compile();constusers=awaitdb.query(sql,Object.values(params));import{SchemaContainer,TypeGenerator,ZodGenerator}from'@blendsdk/codegen';constschema=newSchemaContainer();consts=schema.scope('api');// Define schemaconstUser=s.object({id: s.number(),email: s.string(),name: s.string().optional(),roles: s.string().arrayed(),}).named('User');// Generate TypeScript typesconsttypeGen=newTypeGenerator();consttypes=awaittypeGen.generate(schema);console.log(types);// export interface User {// id: number;// email: string;// name?: string;// roles: string[];// }// Generate Zod schemasconstzodGen=newZodGenerator();constschemas=awaitzodGen.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 packagecd 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 packagecd packages/webafx && yarn testSome packages (postgresql, codegen) use Docker Compose for integration testing:
# Start test databasecd 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