{"id":25688681,"url":"https://github.com/breadbored/composty","last_synced_at":"2026-05-08T04:07:55.385Z","repository":{"id":277787340,"uuid":"933493974","full_name":"breadbored/ComposTy","owner":"breadbored","description":"Type-safe SQL query builder designed for complex database operations... in just 2kb","archived":false,"fork":false,"pushed_at":"2025-03-24T13:49:49.000Z","size":72,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-09T22:35:31.473Z","etag":null,"topics":["mysql","mysql5","mysql8","postgres","postgresql","sql"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/breadbored.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2025-02-16T04:54:38.000Z","updated_at":"2025-03-24T13:49:53.000Z","dependencies_parsed_at":"2025-02-16T05:26:14.598Z","dependency_job_id":"6588edb3-96aa-4978-a901-f54b7e10fc3a","html_url":"https://github.com/breadbored/ComposTy","commit_stats":null,"previous_names":["breadbored/composty"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/breadbored/ComposTy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breadbored%2FComposTy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breadbored%2FComposTy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breadbored%2FComposTy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breadbored%2FComposTy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/breadbored","download_url":"https://codeload.github.com/breadbored/ComposTy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breadbored%2FComposTy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270065427,"owners_count":24520946,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["mysql","mysql5","mysql8","postgres","postgresql","sql"],"created_at":"2025-02-24T21:05:18.675Z","updated_at":"2026-05-08T04:07:55.347Z","avatar_url":"https://github.com/breadbored.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ComposTy\n\n## Overview\n\nShort for SQL Composable TypeScript, ComposTy is a type-safe SQL query builder designed for complex database operations, for people who love SQL and feel limited by ORMs. Composty focuses on aggregating and joining related data into a single query to reduce the number of DB calls, making it ideal for applications that require comprehensive result sets from multiple datasets.\n\nComposTy can reduce the connection time of multiple queries across multiple instances by aggregating related data into a single, fast query.\n\nComposTy is agnostic to the database engine. Though, to get the most power out of your experience, you should use a database that supports:\n\n- Indexes\n- JSON / array aggregation functions\n- Common Table Expressions (CTEs; AKA `WITH` clauses)\n  - See [Subquery Config](#subquery-config) if your database does not support CTEs (e.g., MySQL 5, SQLite2, etc.)\n- Recursive CTEs (optional, but useful for hierarchical data)\n- Window functions (optional)\n\n### Recommended Databases\n\nComposTy loves:\n\n- BigQuery\n- PostgreSQL\n- MySQL 8\n\n## Key Features\n\n- **Type-safe query building**: Fully typed TypeScript implementation ensures query correctness at compile time\n- **Composable WITH clauses**: Support for complex subqueries using Common Table Expressions (CTEs)\n- **JSON aggregation**: Built-in support for aggregating related data into JSON structures\n- **Pagination and ordering**: Integrated support for pagination and custom ordering\n- **Parameter handling**: Secure parameter substitution with named parameters\n- **Dynamic WHERE clauses**: Flexible condition building\n\n## Core Concepts\n\n### Single-ID Aggregation Pattern\n\nThe project implements a specific pattern for handling aggregated data:\n\n1. All subqueries are grouped by a single identifier (e.g., `user_id`, `post_id`)\n2. Subqueries only include the grouping ID and aggregated fields\n3. Results are combined using appropriate JOIN types\n\nThis pattern ensures:  \n- One result per primary key in aggregated data\n- No unexpected row multiplication\n- Predictable and maintainable query results\n\n### Query Structure\n\nQueries are built using two main types:\n\n1. `SQLQuery`: Defines the main query structure\n```typescript\ntype SQLQuery = {\n  sourceTable: string\n  alias: string\n  fields: { [key: string]: string }\n  where?: string\n  withSubqueries?: WithSubquerySQL[]\n}\n```\n\n2. `WithSubquerySQL`: Defines subquery components\n```typescript\ntype WithSubquerySQL = {\n  name: string\n  alias: string\n  query: string\n  joinType: \"JOIN\" | \"LEFT JOIN\"\n  joinOn: string\n  fields: { [key: string]: string }\n  params?: SQParams\n}\n```\n\n## Usage Example\n\nHere's a basic example of how to use the query builder:\n\n```typescript\nconst courseDetails: SQLQuery = {\n  sourceTable: \"post\",\n  alias: \"p\",\n  fields: {\n    id: `p.id`,\n    title: `p.title`,\n    // ... other fields\n  },\n  withSubqueries: [\n    postComments,\n    // ... other subqueries\n  ],\n  where: `p.published = 1`\n}\n\nconst { query, params } = buildComplexSQL(courseDetails, {\n  where: \"p.id = ?post_id\",\n  params: {\n    post_id: 123,\n  },\n  order_by: [\"p.created DESC\"],\n  page_size: 10\n})\n```\n\n## Best Practices\n\n1. **Query Organization**:\n   - Define reusable subqueries as separate constants\n   - Use consistent and meaningful table aliases\n   - Group related fields in field definitions\n\n2. **JSON Aggregation**:\n   - Use `JSON_ARRAYAGG` for nested data structures\n   - Always provide `COALESCE` defaults for JSON fields\n   - Include computed fields at the subquery level\n\n3. **Performance**:\n   - Pre-filter data in subqueries before aggregation\n   - Use appropriate JOIN types\n   - Include pagination for large result sets\n   - Ensure proper indexing on JOIN and WHERE fields\n\n4. **Maintainability**:\n   - Document complex WHERE clauses and JOIN conditions\n   - Keep field mappings explicit\n   - Use consistent naming patterns\n   - Group related queries in feature-specific files\n\n## Error Handling\n\nThe project includes robust error handling through the `SQLBuildError` class, which provides detailed error messages for common issues such as:\n- Missing required fields\n- Invalid pagination parameters\n- Incorrect subquery configurations\n- Missing parameters\n- General SQL building errors\n\n## Configuration\n\n### Subquery Config\n\n```cpp\n// TODO\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbreadbored%2Fcomposty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbreadbored%2Fcomposty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbreadbored%2Fcomposty/lists"}