{"id":48128146,"url":"https://github.com/blendsdk/blendsdk","last_synced_at":"2026-04-04T16:28:18.601Z","repository":{"id":345633441,"uuid":"1182440447","full_name":"blendsdk/blendsdk","owner":"blendsdk","description":"Enterprise-grade TypeScript libraries for web applications, database operations, and code generation","archived":false,"fork":false,"pushed_at":"2026-03-23T12:45:27.000Z","size":1068,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T13:54:04.806Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blendsdk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-15T14:26:32.000Z","updated_at":"2026-03-23T12:45:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/blendsdk/blendsdk","commit_stats":null,"previous_names":["blendsdk/blendsdk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/blendsdk/blendsdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blendsdk%2Fblendsdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blendsdk%2Fblendsdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blendsdk%2Fblendsdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blendsdk%2Fblendsdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blendsdk","download_url":"https://codeload.github.com/blendsdk/blendsdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blendsdk%2Fblendsdk/sbom","scorecard":{"id":1245069,"data":{"date":"2026-03-16","repo":{"name":"github.com/blendsdk/blendsdk","commit":"HEAD"},"scorecard":{"version":"v5.4.1-0.20260302234127-4dbf14294ff1","commit":"4dbf14294ff1c660e93a2c6b70159f8f9b7e1051"},"score":-1,"checks":null},"last_synced_at":"2026-03-21T06:05:15.275Z","repository_id":345633441,"created_at":"2026-03-21T06:05:15.275Z","updated_at":"2026-03-21T06:05:15.275Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31405701,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T16:28:18.444Z","updated_at":"2026-04-04T16:28:18.582Z","avatar_url":"https://github.com/blendsdk.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BlendSDK v5\n\n\u003e Enterprise-grade TypeScript libraries for web applications, database operations, and code generation\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.0.0-green.svg)](https://nodejs.org/)\n[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Monorepo](https://img.shields.io/badge/Monorepo-Turbo-blueviolet.svg)](https://turbo.build/)\n\n## Overview\n\nBlendSDK 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.\n\n### Core Principles\n\n- 🎯 **Type Safety First** - Strict TypeScript with full type coverage\n- 🔄 **Fluent APIs** - Chainable, intuitive interfaces\n- 📦 **Modular Design** - Use only what you need\n- ⚡ **Performance** - Optimized for production workloads\n- 🧪 **Fully Tested** - Comprehensive test coverage with Vitest\n- 🚀 **ESM Native** - Modern ECMAScript modules\n\n## Packages\n\n### Web Application Framework\n\n#### [@blendsdk/webafx](packages/webafx)\n\nProduction-ready Express.js framework with dependency injection, plugin system, and fluent routing.\n\n```typescript\nimport { WebApplication, BaseController } from '@blendsdk/webafx';\n\nconst app = new WebApplication({ PORT: 3000 });\n\nclass UserController extends BaseController {\n  routes() {\n    return [\n      this.route().get('/').handle(this.list),\n      this.authenticated().post('/').handle(this.create),\n    ];\n  }\n}\n\napp.registerController('/api/users', UserController);\nawait app.start();\n```\n\n**Features:**\n\n- Dependency injection container\n- Plugin-based architecture\n- Fluent route builder with authentication/authorization\n- Built-in middleware (CORS, compression, request ID)\n- Graceful shutdown support\n- Health checks\n\n---\n\n### Database \u0026 Persistence\n\n#### [@blendsdk/postgresql](packages/postgresql)\n\nPostgreSQL client with connection pooling and graceful shutdown.\n\n```typescript\nimport { PostgreSQLDatabase } from '@blendsdk/postgresql';\n\nconst db = new PostgreSQLDatabase({\n  host: 'localhost',\n  database: 'myapp',\n  user: 'postgres',\n  password: 'secret',\n});\n\nawait db.connect();\nconst users = await db.query('SELECT * FROM users WHERE active = $1', [true]);\nawait db.shutdown();\n```\n\n**Features:**\n\n- Connection pooling with `pg` driver\n- Graceful connection management\n- Transaction support\n- Prepared statements\n- Health checks\n\n#### [@blendsdk/dbcore](packages/dbcore)\n\nDatabase abstraction layer with CRUD statement builders.\n\n```typescript\nimport { SelectStatement } from '@blendsdk/dbcore';\n\nconst query = new SelectStatement()\n  .from('users')\n  .select('id', 'email', 'name')\n  .where('active = $1', true)\n  .orderBy('created_at DESC')\n  .limit(10);\n\nconst { sql, params } = query.compile();\n```\n\n**Features:**\n\n- Fluent query builders (SELECT, INSERT, UPDATE, DELETE)\n- Expression builder integration\n- Parameter binding\n- Type-safe compilation\n\n#### [@blendsdk/expression](packages/expression)\n\nImmutable AST-based SQL WHERE clause builder.\n\n```typescript\nimport { query } from '@blendsdk/expression';\n\nconst result = query()\n  .where('status')\n  .equals('active')\n  .and(q =\u003e q.where('age').greaterThan(21).or('verified').equals(true))\n  .compile();\n\n// Output: { sql: \"status = $1 AND (age \u003e $2 OR verified = $3)\", params: {...} }\n```\n\n**Features:**\n\n- Immutable query objects\n- Nested conditions\n- Type-safe operators\n- SQL injection protection\n\n---\n\n### Code Generation\n\n#### [@blendsdk/codegen](packages/codegen)\n\nTypeScript/Zod/SQL generator with PostgreSQL introspection.\n\n```typescript\nimport { SchemaContainer, TypeGenerator } from '@blendsdk/codegen';\n\nconst schema = new SchemaContainer();\nconst s = schema.scope('api');\n\nconst User = s\n  .object({\n    id: s.number(),\n    email: s.string(),\n    role: s.string().enum(['admin', 'user']),\n  })\n  .named('User');\n\nconst typeGen = new TypeGenerator();\nconst tsCode = await typeGen.generate(schema);\n```\n\n**Features:**\n\n- Database schema builder (DDL generation)\n- TypeScript type generation\n- Zod schema generation\n- PostgreSQL introspection (reverse engineering)\n- Supports enums, arrays, nullable types\n\n---\n\n### Utilities\n\n#### [@blendsdk/stdlib](packages/stdlib)\n\nStandard library with type guards and utility functions.\n\n```typescript\nimport { isString, isNumber, isDefined } from '@blendsdk/stdlib';\n\nif (isString(value)) {\n  console.log(value.toUpperCase()); // TypeScript knows value is string\n}\n```\n\n**Features:**\n\n- Type guards for runtime checking\n- Common utility functions\n- No external dependencies\n\n#### [@blendsdk/cmdline](packages/cmdline)\n\nFluent command-line argument parser with validation.\n\n```typescript\nimport { CommandLineParser } from '@blendsdk/cmdline';\n\nconst parser = new CommandLineParser()\n  .option('--port', { type: 'number', default: 3000 })\n  .option('--env', { type: 'string', choices: ['dev', 'prod'] })\n  .flag('--verbose');\n\nconst args = parser.parse(process.argv);\nconsole.log(`Starting on port ${args.port}`);\n```\n\n**Features:**\n\n- Type-safe argument parsing\n- Validation and default values\n- Help text generation\n- Boolean flags\n\n---\n\n## Installation\n\n### Install Individual Packages\n\n```bash\n# Web framework\nnpm install @blendsdk/webafx\n\n# Database\nnpm install @blendsdk/postgresql @blendsdk/dbcore @blendsdk/expression\n\n# Code generation\nnpm install @blendsdk/codegen\n\n# Utilities\nnpm install @blendsdk/stdlib @blendsdk/cmdline\n```\n\n### Prerequisites\n\n- **Node.js**: \u003e= 22.0.0\n- **Package Manager**: npm, yarn, or pnpm\n\n---\n\n## Quick Start\n\n### 1. Web Application\n\n```typescript\nimport { WebApplication, BaseController } from '@blendsdk/webafx';\nimport { PostgreSQLDatabase } from '@blendsdk/postgresql';\n\nconst app = new WebApplication({ PORT: 3000 });\n\n// Register database service\napp.registerService({\n  name: 'db',\n  type: 'singleton',\n  factory: async () =\u003e {\n    const db = new PostgreSQLDatabase({\n      /* config */\n    });\n    await db.connect();\n    return db;\n  },\n});\n\n// Create controller\nclass UserController extends BaseController {\n  routes() {\n    return [this.route().get('/').handle(this.list)];\n  }\n\n  async list(req, res) {\n    const db = await req.services.get('db');\n    const users = await db.query('SELECT * FROM users');\n    res.json(users);\n  }\n}\n\napp.registerController('/api/users', UserController);\n\nconst shutdown = await app.start();\nconsole.log('Server running on http://localhost:3000');\n\nprocess.on('SIGTERM', shutdown);\n```\n\n### 2. Database Queries\n\n```typescript\nimport { PostgreSQLDatabase } from '@blendsdk/postgresql';\nimport { SelectStatement } from '@blendsdk/dbcore';\nimport { query } from '@blendsdk/expression';\n\nconst db = new PostgreSQLDatabase({\n  /* config */\n});\nawait db.connect();\n\n// Using raw queries\nconst result = await db.query('SELECT * FROM users WHERE id = $1', [123]);\n\n// Using statement builders\nconst stmt = new SelectStatement()\n  .from('users')\n  .select('*')\n  .where(query().where('active').equals(true).and('role').in(['admin', 'user']).compile());\n\nconst { sql, params } = stmt.compile();\nconst users = await db.query(sql, Object.values(params));\n```\n\n### 3. Code Generation\n\n```typescript\nimport { SchemaContainer, TypeGenerator, ZodGenerator } from '@blendsdk/codegen';\n\nconst schema = new SchemaContainer();\nconst s = schema.scope('api');\n\n// Define schema\nconst User = s\n  .object({\n    id: s.number(),\n    email: s.string(),\n    name: s.string().optional(),\n    roles: s.string().arrayed(),\n  })\n  .named('User');\n\n// Generate TypeScript types\nconst typeGen = new TypeGenerator();\nconst types = await typeGen.generate(schema);\nconsole.log(types);\n// export interface User {\n//   id: number;\n//   email: string;\n//   name?: string;\n//   roles: string[];\n// }\n\n// Generate Zod schemas\nconst zodGen = new ZodGenerator();\nconst schemas = await zodGen.generate(schema);\nconsole.log(schemas);\n// export const UserSchema = z.object({\n//   id: z.number(),\n//   email: z.string(),\n//   name: z.string().optional(),\n//   roles: z.array(z.string())\n// });\n```\n\n---\n\n## Development\n\nBlendSDK is a monorepo managed with [Turbo](https://turbo.build/) and uses **lockstep versioning** (all packages share the same version).\n\n### Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/TrueSoftwareNL/blendsdk.git\ncd blendsdk\n\n# Install dependencies (requires Yarn)\nyarn install\n\n# Build all packages\nyarn build\n\n# Run tests\nyarn test\n```\n\n### Package Scripts\n\n```bash\n# Build all packages\nyarn build\n\n# Test all packages\nyarn test\n\n# Test with coverage\nyarn test --coverage\n\n# Watch mode\nyarn test:watch\n\n# Type check\nyarn type-check\n\n# Clean build artifacts\nyarn clean\n```\n\n### Working with Individual Packages\n\n```bash\n# Navigate to package\ncd packages/webafx\n\n# Build specific package\nyarn build\n\n# Test specific package\nyarn test\n\n# Watch mode\nyarn dev\n```\n\n### Version Management\n\nBlendSDK uses lockstep versioning - all packages are versioned together:\n\n```bash\n# Auto-detect version bump from conventional commits\nyarn lockstep:version:auto --ci\n\n# Explicit version bumps\nyarn lockstep:version:patch --ci\nyarn lockstep:version:minor --ci\nyarn lockstep:version:major --ci\n\n# Publish to npm\nyarn lockstep:publish:latest\nyarn lockstep:publish:next\n```\n\n---\n\n## Architecture\n\n### Monorepo Structure\n\n```\npackages/\n├── stdlib/         # Foundation (no dependencies)\n├── expression/     # SQL expression builder (depends on stdlib)\n├── dbcore/         # Database abstraction (depends on expression)\n├── postgresql/     # PostgreSQL client (depends on dbcore)\n├── cmdline/        # CLI parser (depends on stdlib)\n├── codegen/        # Code generators (depends on dbcore, postgresql)\n└── webafx/         # Web framework (depends on stdlib)\n```\n\n### Dependency Graph\n\n```\nstdlib ──→ cmdline\nexpression ──→ dbcore ──→ postgresql ──→ codegen\nwebafx (standalone, depends on express)\n```\n\n### Key Technologies\n\n- **TypeScript 5.9** - Strict mode, ESM modules\n- **Vitest** - Fast, modern test framework\n- **Turbo** - High-performance build system\n- **Express 5** - Web server (webafx)\n- **pg** - PostgreSQL driver (postgresql)\n- **Zod** - Schema validation (codegen)\n\n---\n\n## Testing\n\n### Running Tests\n\n```bash\n# All packages\nyarn test\n\n# With coverage\nyarn test --coverage\n\n# Watch mode\nyarn test:watch\n\n# Specific package\ncd packages/webafx \u0026\u0026 yarn test\n```\n\n### Integration Tests\n\nSome packages (postgresql, codegen) use Docker Compose for integration testing:\n\n```bash\n# Start test database\ncd packages/postgresql\nyarn db:up\n\n# Run tests\nyarn test\n\n# Stop test database\nyarn db:down\n```\n\n---\n\n## Documentation\n\n- **[Package Documentation](packages/)** - Individual package READMEs\n- **[API Reference](packages/*/src/)** - JSDoc comments in source code\n- **[Implementation Plans](implementation/)** - Architecture documents\n- **[AI Agent Instructions](.github/copilot-instructions.md)** - Development guidelines\n\n---\n\n## Contributing\n\nWe welcome contributions! Please follow these guidelines:\n\n1. **Follow existing patterns** - Review code in similar packages\n2. **Write tests** - All new features must have test coverage\n3. **Use conventional commits** - For automatic versioning\n4. **Update documentation** - Keep READMEs and JSDoc current\n5. **Run tests before committing** - Ensure all tests pass\n\n### Conventional Commits\n\n```\nfeat: add new feature (minor version bump)\nfix: bug fix (patch version bump)\ndocs: documentation only\nrefactor: code change without feature/fix\ntest: adding/updating tests\nchore: maintenance tasks\n\nBREAKING CHANGE: triggers major version bump\n```\n\n---\n\n## License\n\nMIT © [True Software](https://github.com/TrueSoftwareNL)\n\n---\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/TrueSoftwareNL/blendsdk/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/TrueSoftwareNL/blendsdk/discussions)\n\n---\n\n## Versioning\n\nBlendSDK follows [Semantic Versioning](https://semver.org/):\n\n- **Major** (x.0.0): Breaking changes\n- **Minor** (0.x.0): New features (backward compatible)\n- **Patch** (0.0.x): Bug fixes (backward compatible)\n\nCurrent version: **5.32.0** (lockstep across all packages)\n\n---\n\n**Built with ❤️ by [TrueSoftware](https://github.com/TrueSoftwareNL)**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblendsdk%2Fblendsdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblendsdk%2Fblendsdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblendsdk%2Fblendsdk/lists"}